TrustPin

TrustPin SSL certificate pinning SDK in Kotlin for JVM and Android.

TrustPin provides SSL certificate pinning functionality to prevent man-in-the-middle (MITM) attacks by validating server certificates against pre-configured public key pins. The library supports both Android and JVM platforms with a unified API and advanced security features.

Overview

TrustPin uses cryptographically signed configuration to securely deliver pinning configurations to your application. All operations are designed to work with Kotlin Coroutines for seamless integration with modern Android and JVM applications.

Key Features

• Kotlin Multiplatform: Shared codebase for Android and JVM platforms

• Flexible Pinning Modes: Strict validation or permissive mode for development

• Multiple Hash Algorithms: SHA-256 and SHA-512 certificate validation

• Signed Configuration: Cryptographically signed pinning configurations

• Android Integrations: OkHttp, TrustManager, and SSLSocketFactory support

• Intelligent Caching: 10-minute configuration cache with stale fallback

• Comprehensive Logging: Configurable log levels for debugging and monitoring

• Thread-Safe: Built with coroutines and concurrent-safe operations

• Singleton Pattern: One instance per application for consistency

• Enhanced Security - Advanced signature verification with multiple authentication methods

Basic Usage

import cloud.trustpin.kotlin.sdk.TrustPin
import cloud.trustpin.kotlin.sdk.TrustPinMode

// Configure with your project credentials (suspend function)
suspend fun initialize() {
    TrustPin.setup(
        organizationId = "your-org-id",
        projectId = "your-project-id",
        publicKey = "your-base64-public-key",
        mode = TrustPinMode.STRICT  // Recommended for production
    )
}

// Verify a certificate (suspend function)
suspend fun verifyCert() {
    val certificate: X509Certificate = // ... obtained from connection
    TrustPin.verify(domain = "api.example.com", certificate = certificate)
}

Android Integration

OkHttp Integration

import cloud.trustpin.kotlin.sdk.TrustPinSSLSocketFactory
import okhttp3.OkHttpClient

val sslSocketFactory = TrustPinSSLSocketFactory.create()
val client = OkHttpClient.Builder()
    .connectTimeout(30, java.util.concurrent.TimeUnit.SECONDS)
    .readTimeout(30, java.util.concurrent.TimeUnit.SECONDS)
    .writeTimeout(30, java.util.concurrent.TimeUnit.SECONDS)
    .sslSocketFactory(sslSocketFactory, sslSocketFactory.trustManager())
    .build()

Manual Certificate Verification

import java.security.cert.X509Certificate

suspend fun verifyManually() {
    val certificate: X509Certificate = // ... obtained from connection
    try {
        TrustPin.verify(domain = "api.example.com", certificate = certificate)
        println("Certificate is valid and matches configured pins")
    } catch (e: TrustPinError.DomainNotRegistered) {
        println("Domain not configured for pinning")
    } catch (e: TrustPinError.PinsMismatch) {
        println("Certificate doesn't match any configured pins")
    }
}

Pinning Modes

• TrustPinMode.STRICT: Throws errors for unregistered domains (recommended for production)

• TrustPinMode.PERMISSIVE: Allows unregistered domains to bypass pinning (development/testing)

Error Handling

All operations can throw specific TrustPinError types for proper error handling:

• TrustPinError.InvalidProjectConfig - Invalid setup parameters

• TrustPinError.ErrorFetchingPinningInfo - CDN fetch failure

• TrustPinError.InvalidServerCert - Invalid certificate format

• TrustPinError.PinsMismatch - Certificate doesn't match pins

• TrustPinError.AllPinsExpired - All pins have expired

• TrustPinError.ConfigurationValidationFailed - Configuration signature validation failed

• TrustPinError.DomainNotRegistered - Domain not configured (strict mode only)

Thread Safety

All TrustPin operations are thread-safe and can be called from any coroutine context. Internal operations are performed on appropriate background dispatchers.

See also