Security Options

Configure security options for TLS handshakes.

Topics

Configuring TLS Handshake Options

sec_protocol_options_t

An object that contains security options to use for TLS handshakes.

OS_sec_protocol_options

An interface that supports the object containing security options to use for TLS handshakes.

sec_protocol_options_set_tls_server_name

Sets the server name to request in the TLS handshake.

sec_protocol_options_add_pre_shared_key

Adds a preshared key to use for authentication.

sec_protocol_options_add_tls_application_protocol

Adds an Application-Layer Protocol Negotiation (ALPN) value to present in the TLS handshake.

sec_protocol_options_append_tls_ciphersuite

Adds a supported TLS ciphersuite to the configuration.

Beta
sec_protocol_options_append_tls_ciphersuite_group

Adds a supported TLS ciphersuite group to the configuration.

Beta
sec_protocol_options_add_tls_ciphersuite

Adds a supported TLS ciphersuite to the configuration.

Deprecated
sec_protocol_options_add_tls_ciphersuite_group

Adds a supported TLS ciphersuite group to the configuration.

Deprecated
sec_protocol_options_set_tls_diffie_hellman_parameters

Configures legacy Diffie-Hellman parameters.

Deprecated
sec_protocol_options_are_equal

Checks if two security options objects are equivalent.

Beta

Configuring TLS Versions

sec_protocol_options_set_min_tls_protocol_version

Sets the oldest TLS version to negotiate.

Beta
sec_protocol_options_set_max_tls_protocol_version

Sets the newest TLS version to negotiate.

Beta
sec_protocol_options_get_default_min_tls_protocol_version

Accesses the system's default oldest TLS version.

Beta
sec_protocol_options_get_default_max_tls_protocol_version

Accesses the system's default newest TLS version.

Beta
sec_protocol_options_get_default_min_dtls_protocol_version

Accesses the system's default oldest DTLS version.

Beta
sec_protocol_options_get_default_max_dtls_protocol_version

Accesses the system's default newest DTLS version.

Beta
sec_protocol_options_set_tls_min_version

Sets the oldest TLS version to negotiate.

Deprecated
sec_protocol_options_set_tls_max_version

Sets the newest TLS version to negotiate.

Deprecated

Configuring TLS Behavior

sec_protocol_options_set_tls_tickets_enabled

Enables the use of TLS session tickets.

sec_protocol_options_set_tls_false_start_enabled

Enables TLS false start, as defined in RFC 7918.

sec_protocol_options_set_tls_sct_enabled

Enables Signed Certificate Timestamp support.

sec_protocol_options_set_tls_renegotiation_enabled

Enables TLS session renegotiation for versions 1.2 and earlier.

sec_protocol_options_set_peer_authentication_required

Configures TLS to require peer authentication.

sec_protocol_options_set_tls_is_fallback_attempt

Indicates that this TLS handshake is a fallback attempt with more relaxed requirements than a previous attempt.

sec_protocol_options_set_tls_pre_shared_key_identity_hint

Sets the PSK identity hint to use by servers when negotiating a PSK ciphersuite.

Beta

Handling TLS Events

sec_protocol_options_set_verify_block

Sets a handler to override trust verification for TLS handshakes.

sec_protocol_verify_t

A block that delivers a trust object for verification during a TLS handshake.

sec_protocol_verify_complete_t

A block you return to indicate the result of a trust verification, where true indicates verification success.

sec_protocol_options_set_challenge_block

Sets a handler to receive identity challenges.

sec_protocol_challenge_t

A block that delivers the current TLS state for a handshake upon an identity challenge.

sec_protocol_challenge_complete_t

A block you return to indicate the identity with which to reply to a challenge.

sec_protocol_options_set_key_update_block

Sets a handler to receive notifications of TLS key updates.

sec_protocol_key_update_t

A block that delivers the current TLS state upon a key update.

sec_protocol_key_update_complete_t

A block you return to indicate that you have finished responding to a key update.

sec_protocol_options_set_pre_shared_key_selection_block

Sets a handler to receive notifications about PSK selection.

Beta
sec_protocol_pre_shared_key_selection_t

A block that delivers a PSK identity given a hint from its peers.

Beta
sec_protocol_pre_shared_key_selection_complete_t

A block you return to indicate that you have chosen a PSK identity.

Beta

Inspecting TLS State

sec_protocol_metadata_t

An object that represents the TLS state associated with a connection.

OS_sec_protocol_metadata

An interface used to define the object that represents the TLS state associated with a connection.

sec_protocol_metadata_get_negotiated_protocol

Accesses the application protocol (ALPN) negotiated by TLS.

sec_protocol_metadata_get_server_name

Accesses the server name presented in the TLS handshake.

sec_protocol_metadata_get_negotiated_tls_protocol_version

Accesses the negotiated TLS version.

Beta
sec_protocol_metadata_get_negotiated_tls_ciphersuite

Accesses the negotiated TLS ciphersuite.

sec_protocol_metadata_get_negotiated_protocol_version

Accesses the negotiated TLS version.

Deprecated
sec_protocol_metadata_get_negotiated_ciphersuite

Accesses the negotiated TLS ciphersuite.

Deprecated
sec_protocol_metadata_get_early_data_accepted

Checks if TLS early data was successfully accepted.

sec_protocol_metadata_copy_peer_public_key

Accesses the public key presented by the peer in the TLS handshake.

Handling TLS Challenges

sec_protocol_metadata_access_distinguished_names

Accesses the X.509 Distinguished Names presented by the peer.

sec_protocol_metadata_access_ocsp_response

Accesses the contents of the OCSP response.

sec_protocol_metadata_access_peer_certificate_chain

Accesses the certificate chain presented by the peer.

sec_protocol_metadata_access_supported_signature_algorithms

Accesses the list of signature algorithms supported by the peer.

sec_protocol_metadata_access_pre_shared_keys

Accesses the PSKs supported by the local instance.

Beta
sec_protocol_metadata_create_secret

Exports a cryptographic key derived from the protocol metadata using a label string.

sec_protocol_metadata_create_secret_with_context

Exports a cryptographic key derived from the protocol metadata using a label and context string.

sec_protocol_metadata_peers_are_equal

Compares peer information for two security metadata instances.

sec_protocol_metadata_challenge_parameters_are_equal

Compares challenge-relevant information for two security metadata instances.

Handling Certificates

OS_sec_certificate

An interface for supporting the certificate wrapper type.

Handling Identities

sec_protocol_options_set_local_identity

Configures a specific local identity to present in the TLS handshake.

OS_sec_identity

An interface for supporting the identity wrapper type.

sec_identity_access_certificates

Accesses the list of certificates associated with an identity.

Beta
sec_identity_copy_certificates_ref

Copies the array of certificates associated with an identity.

Handling Trust

sec_trust_t

A wrapper around SecTrustRef.

OS_sec_trust

An interface for supporting the trust wrapper type.

Managing Security Objects

sec_release

Releases a reference count on a security object.

sec_retain

Adds a reference count to a security object.

sec_object_t

The generic type for security objects used with the Network framework.

OS_sec_object

An interface that supports the generic type for security objects used with the Network framework.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software