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.

sec_protocol_options_append_tls_ciphersuite_group

Adds a supported TLS ciphersuite group to the configuration.

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.

Configuring TLS Versions

sec_protocol_options_set_min_tls_protocol_version

Sets the oldest TLS version to negotiate.

sec_protocol_options_set_max_tls_protocol_version

Sets the newest TLS version to negotiate.

sec_protocol_options_get_default_min_tls_protocol_version

Accesses the system's default oldest TLS version.

sec_protocol_options_get_default_max_tls_protocol_version

Accesses the system's default newest TLS version.

sec_protocol_options_get_default_min_dtls_protocol_version

Accesses the system's default oldest DTLS version.

sec_protocol_options_get_default_max_dtls_protocol_version

Accesses the system's default newest DTLS version.

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.

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.

sec_protocol_pre_shared_key_selection_t

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

sec_protocol_pre_shared_key_selection_complete_t

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

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_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.

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.

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.