Upgrade — Server Key Pinning#

ClientAuthenticationMethodConfiguration.MtlsKeyHash pins the public keys of the Curity Identity Server‘s certificates. Its trust decision changed: a server whose certificate authority the device does not trust is now refused. An app trusts only the system certificate authorities unless its Network Security Config says otherwise, so add the authority to the app’s Network Security Config <trust-anchors>, or, in debug builds that trust the user store, install it on the device; or use ClientAuthenticationMethodConfiguration.Mtls with a trust store instead.

The platform now validates the server’s certificate chain first, exactly as it does for any HTTPS connection: the chain must lead to a certificate authority the device trusts, every certificate below the trust anchor must be within its validity period, and the app’s Network Security Config applies. The connection is then trusted only if a pinned key matches one of the certificates in that validated chain — the leaf, an intermediate, or the trust root the platform used, even when the server did not send that root. Pinning tightens platform trust; it never replaces it.

Previously, a pinned key’s hash was compared against every certificate in the presented chain, and any match was accepted, with no validation of the chain at all. A server that presented a forged leaf certificate alongside a copy of the pinned certificate authority was accepted, and so was a self-signed or private-authority server the device had no reason to trust. Both are now refused by the platform validation, regardless of the pin.

hostname on each KeyPinning is the bare host the SDK connects to — idsvr.example.com, not idsvr.example.com:8443 or https://idsvr.example.com — compared without regard to case. Setting isValidatingHostname to false on MtlsKeyHash only turns off per-host pin scoping: hostname is then ignored for pin selection, and any pinned key is accepted on a connection to any host. It does not skip the platform’s chain validation, and it does not disable the platform’s own hostname verification, which runs separately either way.

Two related corrections shipped alongside the fix: an expired certificate below the trust anchor is now refused by the platform validation instead of accepted, and MtlsKeyHash and Mtls both fail with a typed error, before anything is sent, instead of proceeding without client authentication when the endpoint is not HTTPS.

If you read the Applicability section below and conclude this upgrade does not affect you, read the Rotation Playbook anyway. It applies to every MtlsKeyHash configuration regardless of this upgrade, and it is what your next certificate or key rotation will actually exercise.

• Check the identity server’s certificate chain. It must chain to a root the device trusts: a public CA, or a private root installed on the device through device management. A self-signed certificate or an uninstalled private CA is refused even when pinned.

• Check what you pinned. A pin on the leaf, an intermediate or the root keeps working as long as that certificate is in the validated chain. If you only pinned the leaf, consider pinning the intermediate as well, or configure two pins per host — the current key and the next — so a rotation does not break the app.

• Check every endpoint is https. HaapiConfiguration’s base URL, the token endpoint and the registration endpoint. An http:// URL is now refused with mutual TLS configured.

• Check the certificate names the host. With isValidatingHostname: true (and always with key pinning) the certificate must carry the host in its Subject Alternative Name; a common name alone is not enough on iOS. Keep false only for a certificate that cannot name the host, and expect the warning.

• Local development. The identity server’s default self-signed certificate is refused. Issue it a certificate with a Subject Alternative Name from a development CA, and install that CA on the simulator:

  xcrun simctl keychain <device> add-root-cert dev-ca.pem

App Transport Security is unchanged. ATS already required an app-level exception to accept a server the system does not trust; the SDK now never accepts such a server on its own, with or without that exception.

• Check the identity server’s certificate chain. It must chain to a certificate authority the app trusts: a system CA, or a private root added to the app’s Network Security Config <trust-anchors> (or, in debug builds that trust the user store, installed on the device). A self-signed certificate or an untrusted private CA is refused even when pinned; alternatively, use Mtls with a trust store that holds the root.
• Check what you pinned. A pin on the leaf, an intermediate or the root keeps working as long as that certificate is in the validated chain, including a root the server does not send. Configure two pins per host — the current key and the next — so a rotation does not break the app.
• Check every endpoint is https. With Mtls or MtlsKeyHash, an http:// endpoint now fails with insecure_transport before anything is sent, instead of sending the request without client authentication. Creating an accessor or a HaapiManager refuses an http address even earlier, with insecure_haapi_configuration, unless allowInsecureHttpEndpoints permits it — see HAAPI Request Target Hardening.
• Check hostname names the connection host. Each KeyPinning.hostname is the bare host the SDK connects to; a certificate’s common name still works, with a warning, until the next major version.
• Local development. The identity server’s default self-signed certificate is refused. Add the development CA, or the self-signed certificate itself, to the debug build’s Network Security Config <trust-anchors>.

Applicability#

Run the command above on the leaf certificate’s PEM unless you are deliberately pinning an issuing certificate authority.

To see the chain the server actually presents, connect with s_client and inspect the certificates it prints:

openssl s_client -showcerts -connect idsvr.example.com:443 </dev/null

The first certificate printed is the leaf; the certificates after it are the certificate authorities the server sent with the handshake. The key you pin may belong to any of them, or to the root certificate authority the platform used to validate the chain, even if the server does not send that root — compute the root’s hash from its PEM: the certificate you added to the app’s Network Security Config <trust-anchors> (or, in debug builds that trust the user store, installed on the device), or the published certificate of the system authority. Pin the leaf for the tightest possible pin, or a certificate authority higher in the chain if you want the pin to survive a leaf rotation.

A request to a non-https URL, or a HaapiTokenManager build with a non-https token endpoint, reports the error code insecure_transport. Creating an accessor or a HaapiManager with an http address is refused earlier, with insecure_haapi_configuration, unless allowInsecureHttpEndpoints permits it — see HAAPI Request Target Hardening. The insecure_transport cause carries the refused URL’s scheme and host as properties, never its path or query; the cause’s description names only the scheme, so it can be shown to a user:

if case .error(let error) = result,
   let idsvrError = error as? IdsvrError,
   idsvrError.error == HaapiErrorCode.insecureTransport.rawValue
{
    let refusal = idsvrError.cause as? HaapiInsecureTransportRefusal
    // refusal?.scheme, refusal?.host
}

Its recovery suggestion is .unrecoverable(action: .introspectCause): fix the configured URL, do not retry.

A refused server certificate fails the request the way a cancelled trust challenge always has — with the platform’s cancellation error, URLError.cancelled — and logs one line under the Driver’s flow log tag naming the reason: the chain failed system validation (with the platform’s reason), no pin is configured for the host, no certificate of the validated chain matched, the server key type is not supported for pinning, or the challenge carried no server trust. The host in that line goes through the logger’s sensitive-value masking.

Some of the rows below need a fix on your side; others are server misconfigurations to correct on the Curity Identity Server. Each row names the symptom you would see after upgrading.

Every refusal by the platform validation — an untrusted authority, an expired certificate, a forged chain — surfaces as the same “does not trust the server certificate chain” message. The platform’s own reason is the CertificateException’s cause, and HaapiLogger logs it at ERROR as “The platform does not trust the server certificate chain:” followed by that reason.

let clientAuthPinned = try ClientAuthenticationMethodMTLS(
    pkcs12Filename: "client.p12",
    pkcs12Passphrase: "passphrase",
    serverKeyPinnings: [
        // The key currently in use.
        KeyPinning(
            hostname: "idsvr.example.com",
            publicKeyHash: "Kjuy4mT3fbeDozRNP6rTjWRYmbs79Begb5Roq+DUu7s="
        ),
        // The key the server will rotate to next.
        KeyPinning(
            hostname: "idsvr.example.com",
            publicKeyHash: "L1sN0kkq8t1BR8nGZ+58vN5FQ4URtT/nRhrEUUwj9ZQ="
        )
    ],
    bundle: Bundle.main
)

An empty serverKeyPinnings list logs an error, since every connection is then refused.

val mtlsPinned = ClientAuthenticationMethodConfiguration.MtlsKeyHash(
    clientKeyStore = myClientKeyStore,
    clientKeyStorePassword = myClientKeyStorePassword,
    serverKeyPinnings = setOf(
        // The key currently in use.
        ClientAuthenticationMethodConfiguration.MtlsKeyHash.KeyPinning(
            hostname = "idsvr.example.com",
            publicKeyHash = "Kjuy4mT3fbeDozRNP6rTjWRYmbs79Begb5Roq+CNwiG="
        ),
        // The key the server will rotate to next.
        ClientAuthenticationMethodConfiguration.MtlsKeyHash.KeyPinning(
            hostname = "idsvr.example.com",
            publicKeyHash = "L1sN0kkq8t1BR8nGZ+58vN5FQ4URtT/nRhrEUUwj9ZQ="
        )
    )
)

serverKeyPinnings is a Set precisely so a configuration can carry both keys during a rotation. An empty set throws IllegalArgumentException at construction.

The expiry countdown and the single-pin warning are logged at warning level under the Driver’s flow log tag; a refused server certificate is logged at error level under flow, and a refused plain-http request under http. Warnings are enabled by default, but no log tag is, so nothing is logged until you set the tags — before any HAAPI object is created:

HaapiLogger.followUpTags = DriverFollowUpTag.allCases

The countdown names the host and is logged once per pinned key and threshold per app run, at the smallest threshold crossed: The pinned server certificate for <host> expires within 30 days; pin the next key before it is rotated. To get the countdown as an early alarm, forward warnings to your monitoring.

Two settings gate every HaapiLogger line, and both warnings below are logged at WARN. A release build defaults to enabled = false and level ERROR, so setting only one of the two produces no output:

HaapiLogger.enabled = true
HaapiLogger.setLevel(HaapiLogger.LogLevel.WARN)

With both set, you see the certificate-expiry countdown (logged once at 30 days, again at 14, and again at 7, naming the host and the expiry instant; a pinned installed trust anchor that has already expired, which the platform still accepts, is reported with how many days ago it expired) and the single-pin configuration warning. To get the countdown as an early alarm, forward HaapiLogger output at WARN and above to your monitoring. See Driver Layer Logging for the full configuration.

Set both before you construct the configuration, not just before you connect. The single-pin warning is logged from MtlsKeyHash’s own init block, at construction time — enabling logging afterward means you never see it, no matter how correctly the two lines above are set. The expiry countdown does not share this trap: it re-checks shouldLog on every handshake before deciding whether it already logged that threshold, so enabling logging later still surfaces it on the next connection.

The rotation playbook, not the logging, is what protects a deployment. A missed warning is a missed reminder; an unplanned key rotation with a single pin is an outage.