Trust
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)
See also
Types
An SSLSocketFactory together with the exact X509TrustManager that backs it — the two arguments OkHttp's sslSocketFactory(factory, trustManager) expects, guaranteed to belong to the same validation pipeline. Obtain via makeTlsPair.
Properties
true when a validated pinning payload is cached and usable by verify without a new fetch.
Functions
Waits until the pinning configuration has been fetched, signature-verified, and accepted by the SDK's integrity check — the explicit fail-closed gate.
Blocking version of awaitConfiguration. Must not be called from the Android main thread.
Blocking version of fetchCertificate. Must not be called from the Android main thread.
Creates an SSLSocketFactory bound to this TrustPin instance.
Creates a literally matched TLS pair: an SSLSocketFactory and the exact X509TrustManager instance its SSLContext was initialized with.
Creates an X509TrustManager bound to this TrustPin instance.
Sets the log level for this TrustPin instance.
Initializes this TrustPin instance with the given configuration.
Blocking version of setup. Must not be called from the Android main thread.
Verifies an X.509 certificate against the configured pins for domain.
Verifies a PEM-encoded certificate against the configured pins for domain.
Verifies the leaf of a server-presented certificate chain against the configured pins for domain.
Blocking version of verify with X.509 certificate. Must not be called from the Android main thread.
Blocking version of verify with PEM string. Must not be called from the Android main thread.
Blocking version of verify with a certificate chain. Must not be called from the Android main thread.