Glossary

A comprehensive reference of technical terms and concepts used in TrustPin and certificate pinning.

General Security Terms

Certificate Pinning

A security technique that ensures your application only trusts specific SSL/TLS certificates or public keys when establishing HTTPS connections. Instead of trusting any certificate signed by a Certificate Authority (CA), your app validates that the server’s certificate matches a pre-configured “pin” (cryptographic hash).

Use Case: Protects against compromised CAs and man-in-the-middle attacks.

Man-in-the-Middle Attack (MITM)

A cyber attack where an attacker secretly intercepts and potentially alters communications between two parties who believe they are directly communicating with each other.

Example: An attacker on a public WiFi network intercepts your app’s HTTPS traffic by presenting a fraudulent certificate. Without certificate pinning, the OS may trust this certificate if it’s signed by a recognized CA.

Prevention: Certificate pinning prevents MITM attacks by rejecting any certificate that doesn’t match your pre-configured pins, even if signed by a trusted CA.

Public Key

The publicly shareable part of an asymmetric cryptographic key pair. In SSL/TLS certificates, the public key is embedded in the certificate and used to establish encrypted connections.

In TrustPin: We extract and hash the public key from your server’s certificate to create a pin. This allows certificate renewal without changing pins, as long as the same key pair is used.

Format: Typically encoded in formats like PEM, DER, or SPKI.

Private Key

The secret part of an asymmetric cryptographic key pair that must be kept secure. The private key corresponds to the public key embedded in your SSL/TLS certificate.

Security: Your private key should never be shared or uploaded to TrustPin. Only the public key (extracted from your certificate) is used for pinning.

Storage: Store private keys in secure hardware (HSM) or encrypted key stores. Compromise of a private key requires immediate certificate revocation and rotation.

SSL/TLS

SSL (Secure Sockets Layer) and TLS (Transport Layer Security) are cryptographic protocols that provide secure communication over networks.

Current Status:

• SSL 2.0/3.0: Deprecated, insecure
• TLS 1.0/1.1: Deprecated as of 2021
• TLS 1.2: Minimum recommended version
• TLS 1.3: Latest version, recommended

TrustPin Requirement: Your domains must use TLS 1.2 or higher.

Certificate Authority (CA)

A trusted organization that issues digital certificates. Operating systems and browsers maintain lists of trusted CAs.

Problem with CAs: If any CA is compromised, attackers can issue fraudulent certificates for any domain. There have been real-world incidents of CA compromises.

TrustPin’s Role: Certificate pinning reduces reliance on the CA trust model by only accepting certificates you explicitly configure.

Examples: Let’s Encrypt, DigiCert, GlobalSign, AWS Certificate Manager (ACM).

Cryptography & Hashing

SHA-256 (Secure Hash Algorithm)

A cryptographic hash function that produces a 256-bit (32-byte) hash value, typically rendered as 64 hexadecimal characters.

Properties:

• Deterministic: Same input always produces same output
• One-way: Cannot reverse the hash to get original input
• Collision-resistant: Extremely difficult to find two inputs with same hash

In TrustPin: SHA-256 is the default algorithm for creating certificate pins.

Example:

Input: Certificate public key
SHA-256: e8a01f3d9b2c456789abcdef1234567890abcdef1234567890abcdef12345678

Performance: Fast, minimal overhead (~1-5ms per certificate validation).

SHA-512 (Secure Hash Algorithm)

A cryptographic hash function that produces a 512-bit (64-byte) hash value, rendered as 128 hexadecimal characters.

Comparison to SHA-256:

• Stronger security margin
• Slower computation
• Larger hash size

When to Use: High-security applications (banking, healthcare, government) where the extra security margin justifies slightly slower performance.

TrustPin Support: Configurable in dashboard, but SHA-256 is recommended for most applications.

ECDSA

Elliptic Curve Digital Signature Algorithm - A cryptographic algorithm used to create digital signatures using elliptic curve cryptography.

In TrustPin: Configuration responses from the CDN are signed using ECDSA with the P-256 curve. Your app verifies these signatures using the public key you provide during setup.

Advantages:

• Smaller key sizes than RSA for equivalent security
• Faster signature generation and verification
• Lower bandwidth requirements

TrustPin Implementation:

• Algorithm: ECDSA with P-256 (also known as secp256r1 or prime256v1)
• Signature format: JWS (JSON Web Signature)

SPKI

Subject Public Key Info - A data structure defined in X.509 that contains the public key and the algorithm identifier. SPKI is the foundation of public key pinning in TrustPin.

Structure:

SPKI = Algorithm Identifier + Public Key Bits

Example:

Algorithm Identifier: rsaEncryption
Public Key: 2048-bit RSA public key
  ↓ DER-encode SPKI
  ↓ Hash with SHA-256
  ↓ Result: SPKI Pin
E8A01F3D9B2C456789ABCDEF1234567890ABCDEF1234567890ABCDEF12345678

In Certificate Pinning: When using SPKI pinning (vs. leaf certificate pinning), TrustPin extracts the SPKI from the X.509 certificate, DER-encodes it, and creates a hash. This hash becomes the “pin.”

Why SPKI Pinning is Recommended:

• Survives renewal: Pin remains valid when certificate is renewed with the same key pair
• Perfect for auto-managed certs: AWS ACM and Let’s Encrypt reuse key pairs during renewal
• OWASP recommended: Industry best practice per OWASP Mobile Security Testing Guide
• Less operational risk: Reduces chance of app outage due to forgotten pin updates

SPKI vs Leaf Certificate Pinning:

• SPKI pinning: Hashes only the public key → survives certificate renewal
• Leaf pinning: Hashes entire certificate → breaks on renewal

TrustPin Default: SPKI SHA-256 is the recommended configuration for most applications.

Format: SPKI is DER-encoded (binary format) before being hashed with SHA-256 or SHA-512.

Leaf Certificate Pinning

A certificate pinning method that hashes the entire X.509 certificate (including metadata) rather than just the public key.

What Gets Hashed:

Full Certificate Contents:
  - Subject (domain name)
  - Issuer (Certificate Authority)
  - Validity period (not before / not after dates)
  - Serial number
  - Public key
  - Extensions
  - Signature
    ↓ Hash entire certificate
    ↓ Result: Leaf Certificate Pin
3F5A8B1C9D2E7F4A6B8C1D9E3F5A7B2C4D6E8F1A3B5C7D9E2F4A6B8C1D3E5F7A

Characteristics:

• Breaks on renewal: Any certificate field change invalidates the pin
• Higher maintenance: Must update pins before each certificate renewal
• Strictest validation: Validates exact certificate, not just public key
• Full metadata check: Ensures serial number, validity dates match

When to Use Leaf Certificate Pinning:

• Manually managed certificates with one-year or longer validity
• Compliance requires validating full certificate (rare)
• Maximum security scenario where you control certificate lifecycle

When NOT to Use:

• AWS Certificate Manager (ACM) - renews every 60 days
• Let’s Encrypt - renews every 90 days
• Any auto-renewal system
• High-availability production apps (risk of forgotten pin updates)

Comparison to SPKI Pinning:

TrustPin Support: TrustPin supports leaf certificate pinning with SHA-256 or SHA-512, but SPKI pinning is strongly recommended for most use cases.

Hash / Fingerprint

A cryptographic hash is a fixed-size output produced by a hash function. In certificate pinning, the hash of a certificate or public key is called a “fingerprint” or “pin.”

Common Hash Algorithms:

• MD5: 128-bit (deprecated, insecure)
• SHA-1: 160-bit (deprecated for security)
• SHA-256: 256-bit (recommended)
• SHA-512: 512-bit (high security)

Pin Example:

Certificate: -----BEGIN CERTIFICATE-----...
                ↓ SHA-256 Hash
Pin: e8a01f3d9b2c456789abcdef1234567890abcdef1234567890abcdef12345678

Web Standards & Formats

JWS

JSON Web Signature - A standard (RFC 7515) for signing JSON data to ensure its integrity and authenticity.

Structure:

JWS = Header.Payload.Signature

Example:

eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcmdJZCI6IjEyMyIsInByb2plY3RJZCI6IjQ1NiJ9.MEUCIQDx...
│────────── Header ──────────│──────── Payload ────────│─── Signature ───│

In TrustPin: Pin configurations fetched from the CDN are delivered as JWS tokens. Your SDK verifies the signature using your project’s public key to ensure:

• Configuration came from TrustPin (authenticity)
• Configuration wasn’t tampered with (integrity)

Verification Process:

• SDK fetches JWS from CDN
• Extracts header, payload, and signature
• Verifies signature using your ECDSA public key
• If valid, applies the pin configuration

JWT

JSON Web Token - A compact, URL-safe standard (RFC 7519) for securely transmitting information between parties as a JSON object.

Structure:

JWT = Header.Payload.Signature

Difference from JWS:

• JWT is a specific use case of JWS
• JWT contains “claims” (statements about an entity)
• JWS is the signing mechanism; JWT is the token format

In TrustPin: While TrustPin uses JWS for signing configurations, JWT terminology is sometimes used interchangeably. The key point is that configurations are cryptographically signed and verified.

Claims in TrustPin Configurations:

• orgId: Organization identifier
• projectId: Project identifier
• domains: Array of domain configurations with pins
• exp: Expiration timestamp
• iat: Issued at timestamp

PEM

Privacy-Enhanced Mail - A base64-encoded format for storing and transmitting cryptographic keys and certificates.

Structure:

-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQGEwJJ
RTESMBAGA1UEChMJQmFsdGltb3JlMRMwEQYDVQQLEwpDeWJlclRydXN0MSIwIAYD
...
-----END CERTIFICATE-----

Characteristics:

• Text-based (safe for copy-paste)
• Base64-encoded binary data
• Begin/end markers identify content type

In TrustPin: When manually uploading certificates to the dashboard, PEM is the most common format accepted.

Common Types:

• BEGIN CERTIFICATE: X.509 certificate
• BEGIN RSA PRIVATE KEY: RSA private key
• BEGIN PUBLIC KEY: Public key

DER

Distinguished Encoding Rules - A binary format for encoding ASN.1 data structures, including certificates and keys.

Characteristics:

• Binary format (not human-readable)
• More compact than PEM
• Common in Java/Android ecosystems

Conversion:

# PEM to DER
openssl x509 -in cert.pem -outform DER -out cert.der
 
# DER to PEM
openssl x509 -in cert.der -inform DER -out cert.pem

In TrustPin: Both PEM and DER formats are supported for certificate uploads.

X.509 Certificate Standard

X.509 is an international standard (ITU-T X.509) that defines the format of public key certificates used in SSL/TLS and other protocols.

Contains:

• Subject (who the certificate is issued to)
• Issuer (which CA issued it)
• Validity period (not before / not after dates)
• Public key
• Signature
• Extensions (SANs, key usage, etc.)

In Certificate Pinning: X.509 certificates are parsed to extract the public key (SPKI), which is then hashed to create a pin.

Cloud & Infrastructure

CDN

Content Delivery Network - A geographically distributed network of servers that delivers content to users from the nearest location.

TrustPin CDN: cdn.trustpin.cloud

• Hosts signed pin configurations
• Global edge locations for low latency
• Four nines uptime SLA (99.99%)
• Automatic caching and distribution

Why CDN for TrustPin:

• Fast pin updates worldwide (typically less than 1 second propagation)
• High availability (no single point of failure)
• DDoS protection
• Reduced load time for configuration fetches

Caching: TrustPin SDK caches configurations locally for 10 minutes, reducing CDN requests while maintaining freshness.

ACM

AWS Certificate Manager - Amazon Web Services’ managed service for provisioning, managing, and deploying SSL/TLS certificates.

Features:

• Free certificates for AWS resources
• Automatic renewal
• Integration with ELB, CloudFront, API Gateway

TrustPin Integration:

• Generate certificate in ACM
• Deploy to your AWS infrastructure
• Download public certificate from ACM
• Upload to TrustPin dashboard for pinning

Note: ACM private keys never leave AWS. Only the public certificate is needed for TrustPin.

TrustPin-Specific Terms

Pin Configuration

A JSON structure containing all certificate pins for your project’s domains, delivered as a signed JWS token.

Example Structure:

{
  "organizationId": "org-123",
  "projectId": "proj-456",
  "domains": [
    {
      "domain": "api.example.com",
      "pins": [
        {
          "algorithm": "SHA-256",
          "value": "e8a01f3d9b...",
          "expires": "2027-01-01T00:00:00Z"
        }
      ]
    }
  ],
  "exp": 1735689600,
  "iat": 1704153600
}

Delivery: Signed with ECDSA and delivered via CDN at:

https://cdn.trustpin.cloud/v1/configurations/{orgId}/{projectId}

Strict Mode

A pinning mode where the SDK rejects connections to any domain not explicitly configured in your TrustPin project.

Behavior:

• Configured domain with matching pin: ✅ Allow
• Configured domain with mismatched pin: ❌ Reject (PINS_MISMATCH)
• Unconfigured domain: ❌ Reject (DOMAIN_NOT_REGISTERED)

When to Use: Production environments where all API domains are known in advance.

Code Example:

// iOS
try await TrustPin.setup(
    organizationId: "org-123",
    projectId: "proj-456",
    publicKey: "LS0tLS1CRUdJTi...",
    mode: .strict  // Reject unknown domains
)

Permissive Mode

A pinning mode where the SDK allows connections to unconfigured domains while still enforcing pinning on configured domains.

Behavior:

• Configured domain with matching pin: ✅ Allow
• Configured domain with mismatched pin: ❌ Reject (PINS_MISMATCH)
• Unconfigured domain: ✅ Allow (standard OS validation only)

When to Use:

• Development/testing environments
• Apps that connect to user-provided URLs
• Gradual rollout of pinning

Warning: Not recommended for production unless you specifically need to allow arbitrary domains.

Pin Expiration

A timestamp indicating when a certificate pin should no longer be trusted.

Configuration:

Pin expires: 2027-01-01
Certificate expires: 2027-01-15

Recommendation: Set pin expiration 14-30 days before certificate expiration to allow time for rotation.

Behavior When Expired:

• If any valid pin exists: Connection succeeds
• If all pins expired: Connection fails with ALL_PINS_EXPIRED error

Automatic Handling: TrustPin dashboard warns you 60 days before expiration.

Configuration Cache

Local storage of pin configurations on the device to reduce CDN requests and improve performance.

TrustPin Caching Strategy:

• TTL (Time to Live): 10 minutes
• Stale-while-revalidate: If CDN is unreachable, use stale cache
• Storage: In-memory (iOS/Android) or secure SharedPreferences/Keychain

Cache Behavior:

App Launch → Check cache age
  ├─ Cache less than 10 min old → Use cached config
  └─ Cache ≥ 10 min old → Fetch new config from CDN
       ├─ Success → Update cache
       └─ Failure → Use stale cache (log warning)

Manual Cache Clear: Restart app or wait for TTL expiration.

Backup Pin

A secondary pin configured for a domain to enable zero-downtime certificate rotation.

Strategy:

Domain: api.example.com
Pins:
  - Primary: abc123... (current cert, expires 2026-12-01)
  - Backup:  def456... (next cert, expires 2027-12-01)

Rotation Process:

• Add new certificate as backup pin (both active)
• Deploy new certificate to server
• Wait for apps to fetch updated configuration
• Remove old pin after majority of users updated

OWASP Recommendation: Always maintain at least 2 pins per domain.

Common Acronyms

Additional Resources

• OWASP Certificate Pinning 
• RFC 7515 (JWS) 
• RFC 7519 (JWT) 
• RFC 5280 (X.509) 
• TrustPin Dashboard 

Need More Help?

If you encounter a term not listed here:

• 📧 Email: support@trustpin.cloud
• 💬 Documentation: docs.trustpin.cloud