How Safari Handles mTLS Client Certificate Prompts

This article provides a complete overview of how the Safari web browser interacts with macOS Keychain Access to authenticate users during a mutual TLS (mTLS) handshake. When a web server requests a client certificate, Safari relies on native macOS security frameworks to search the local Keychain for valid cryptographic identities, displays a browser-level dialog for certificate selection, and triggers a system-level authorization prompt to access the associated private key before completing the secure connection.

1. The Server Request

The process begins during the TLS handshake when the user navigates to a secure server requiring mTLS. The server sends a CertificateRequest message to Safari. This message contains specific criteria, most notably a list of Distinguished Names (DNs) of Certificate Authorities (CAs) that the server trusts, alongside supported cryptographic signature algorithms.

2. Querying Keychain Access

Safari does not manage certificates directly; instead, it delegates this task to Apple’s native networking and security frameworks (Network.framework and the Security framework). Upon receiving the server's request, Safari queries the macOS Keychain (typically searching the user's login keychain, the System keychain, and any connected smart cards or hardware tokens) for valid "identities."

In macOS terminology, an identity is a combination of a client certificate and its corresponding private key. Safari filters the Keychain results based on the following rules:

  • The certificate must have a matching private key stored in the Keychain.
  • The certificate must be issued by one of the CAs specified in the server's CertificateRequest message (or chain up to one).
  • The certificate must be currently valid (not expired) and designated for client authentication in its Extended Key Usage (EKU) extension.

If no matching identities are found, Safari automatically responds to the server with an empty certificate message, which usually results in the server returning an access denied error.

3. Checking for Identity Preferences

Before prompting the user, Safari checks Keychain Access for an existing "Identity Preference." If the user has previously connected to this specific URL and selected a certificate, macOS creates an Identity Preference item in the Keychain that maps the URL to that specific certificate. If a valid preference exists, Safari skips the browser selection prompt and automatically selects that certificate.

4. The Safari Selection Prompt

If no Identity Preference exists and one or more valid identities are found, Safari pauses the TLS handshake and presents a native modal sheet attached to the active browser tab.

This prompt informs the user that the specific website requires a certificate to identify them. It presents a list of the filtered, valid certificates showing the Common Name (CN), the issuing authority, and the expiration date. The user must highlight the desired certificate and click Continue (or Cancel to abort the authentication). Once the user clicks Continue, Safari automatically writes a new Identity Preference to the Keychain so the user will not have to select the certificate from the dropdown on future visits to that exact domain.

5. Private Key Authorization

Selecting the certificate in Safari only tells the browser which public certificate to present; it does not grant Safari permission to use the private key required to cryptographically sign the handshake.

Immediately after clicking Continue in Safari, the macOS security daemon (securityd) triggers a second, system-level modal dialog. This prompt states that "Safari wants to sign using key [Key Name] in your keychain." To proceed, the user must authenticate using their macOS login password or Touch ID, and choose one of three options:

  • Always Allow: Grants Safari permanent access to this private key without prompting again in the future.
  • Allow: Grants one-time access to the private key for the current session.
  • Deny: Blocks access to the private key, causing the mTLS handshake to fail.

6. Completing the Handshake

Once the user authorizes access to the private key, Keychain Access performs the cryptographic signing operation on behalf of Safari. Safari then sends the selected public certificate and the signed CertificateVerify payload back to the server, successfully completing the mTLS handshake and loading the web page.