TrustPin Kotlin SDK/cloud.trustpin.kotlin.sdk/TrustPin

TrustPin

TrustPin SSL certificate pinning SDK 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.

Single-Instance Usage (simplest)

For most applications a single, shared pinning context is sufficient. Use the static convenience methods on the companion object — they all delegate to default:

// Setup
TrustPin.setup(
    TrustPinConfiguration(
        organizationId = "my-org",
        projectId      = "my-project",
        publicKey      = "MFkwEwYH...",
        mode           = TrustPinMode.STRICT
    )
)

// Verify
TrustPin.verify("api.example.com", certificate)

// OkHttp integration
val client = OkHttpClient.Builder()
    .sslSocketFactory(TrustPin.makeSSLSocketFactory(), TrustPin.makeTrustManager())
    .build()

Multi-Instance Usage

Libraries or multi-tenant apps that need isolated pinning contexts can create named instances via instance. Each instance has its own configuration, state, and log output tagged with the instance id:

val payments = TrustPin.instance("payments")
payments.setup(
    TrustPinConfiguration(
        organizationId = "payments-org",
        projectId      = "payments-api",
        publicKey      = "MFkwEwYH..."
    )
)
payments.verify("pay.example.com", certificate)

val analytics = TrustPin.instance("analytics")
analytics.setup(/* ... */)

Java Usage

From Java, access the default instance via TrustPin.getDefault():

TrustPin.getDefault().setupBlocking(
    new TrustPinConfiguration("my-org", "my-project", "MFkwEwYH...", TrustPinMode.STRICT, null)
);
SSLSocketFactory factory = TrustPin.getDefault().makeSSLSocketFactory();
X509TrustManager trustManager = TrustPin.getDefault().makeTrustManager();

Pinning Modes

TrustPinMode.STRICT: Throws errors for unregistered domains (recommended for production)
TrustPinMode.PERMISSIVE: Allows unregistered domains to bypass pinning (development/testing)

Types

Companion

object Companion

Functions

fetchCertificate

suspend fun fetchCertificate(host: String, port: Int = 443): String

Opens an ephemeral TLS connection to host:port, performs OS-level certificate chain validation, and returns the server's leaf certificate as a PEM string.

fetchCertificateBlocking

@JvmOverloads

fun fetchCertificateBlocking(host: String, port: Int = 443): String

Blocking version of fetchCertificate. Must not be called from the Android main thread.

makeSSLSocketFactory

fun makeSSLSocketFactory(): SSLSocketFactory

Creates an SSLSocketFactory bound to this TrustPin instance.

makeTrustManager

fun makeTrustManager(): X509TrustManager

Creates an X509TrustManager bound to this TrustPin instance.

setLogLevel

fun setLogLevel(level: TrustPinLogLevel)