Deprecated Secure Transport Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Available in OS X v10.2 through OS X v10.7

SSLGetPeerCertificates

Retrieves a peer certificate. (Available in OS X v10.2 through OS X v10.7. Use SSLCopyPeerCertificates instead.)

OSStatus SSLGetPeerCertificates (
   SSLContextRef context,
   CFArrayRef *certs
);
Parameters
context

An SSL session context reference.

certs

On return, a pointer to an array of values of type SecCertificateRef representing the peer certificate and the certificate chain used to validate it. The certificate at index 0 of the returned array is the peer certificate (the subject of the function call—the end certificate in the chain); the root certificate (or the closest certificate to it) is at the end of the returned array. The entire array is created by the Secure Transport library; you must call the CFRelease function for this array and for each SecCertificateRef value in the array when you are finished with them.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

This function is valid any time after a handshake attempt. You can use it to examine a peer certificate, to examine a certificate chain to determine why a handshake attempt failed, or to retrieve the certificate chain in order to validate the certificate yourself. (To disable validation so that you can validate the certificate yourself, use the SSLSetSessionOption function to set the session’s kSSLSessionOptionBreakOnServerAuth flag.)

Special Considerations

Because this function requires separately releasing each certificate reference returned, it has been deprecated in favor of SSLCopyPeerCertificates, which conforms to standard Core Foundation semantics.

Availability
  • Available in OS X v10.2 through OS X v10.7.
  • Deprecated in OS X v10.5.
Declared In
SecureTransport.h

SSLGetTrustedRoots

Retrieves the current list of trusted root certificates. (Available in OS X v10.2 through OS X v10.7. Use SSLCopyTrustedRoots instead.)

OSStatus SSLGetTrustedRoots (
   SSLContextRef context,
   CFArrayRef *trustedRoots
);
Parameters
context

An SSL session context reference.

trustedRoots

On return, a pointer to a value of type CFArrayRef. This array contains values of type SecCertificateRef representing the current set of trusted roots. You must call the CFRelease function for this array and for each SecCertificateRef value in the array when you are finished with them.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

You can use the SSLSetTrustedRoots function to replace or add to the set of trusted root certificates. If SSLSetTrustedRoots has never been called for this session, the SSLGetTrustedRoots function returns the system’s default set of trusted root certificates.

Special Considerations

Because this function requires separately releasing each certificate reference returned, it has been deprecated in favor of SSLCopyTrustedRoots, which conforms to standard Core Foundation semantics.

Availability
  • Available in OS X v10.2 through OS X v10.7.
  • Deprecated in OS X v10.5.
Declared In
SecureTransport.h

Deprecated in OS X v10.8

SSLGetProtocolVersion

Gets the SSL protocol version. This function is deprecated. (Deprecated in OS X v10.8.)

OSStatus SSLGetProtocolVersion (
   SSLContextRef context,
   SSLProtocol *protocol
);
Parameters
context

An SSL session context reference.

protocol

On return, a pointer to the SSL protocol version.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

Use the SSLGetProtocolVersionEnabled function instead.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
Declared In
SecureTransport.h

SSLSetProtocolVersion

Sets the SSL protocol version. This function is deprecated. (Deprecated in OS X v10.8.)

OSStatus SSLSetProtocolVersion (
   SSLContextRef context,
   SSLProtocol version
);
Parameters
context

An SSL session context reference.

version

The SSL protocol version to negotiate.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

Use the SSLSetProtocolVersionEnabled function instead.

This function cannot be called when a session is active.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
Declared In
SecureTransport.h

Deprecated in OS X v10.9

SSLCopyPeerCertificates

Retrieves a peer certificate and its certificate chain. (Deprecated in OS X v10.9.)

OSStatus SSLGetPeerCertificates (
   SSLContextRef context,
   CFArrayRef *certs
);
Parameters
context

An SSL session context reference.

certs

On return, a pointer to an array of values of type SecCertificateRef representing the peer certificate and the certificate chain used to validate it. The certificate at index 0 of the returned array is the peer certificate (the subject of the function call—the end certificate in the chain); the root certificate (or the closest certificate to it) is at the end of the returned array. The entire array is created by the Secure Transport library; you must call the CFRelease function for this array when you are finished with it.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

This function is valid any time after a handshake attempt. You can use it to examine a peer certificate, to examine a certificate chain to determine why a handshake attempt failed, or to retrieve the certificate chain in order to validate the certificate yourself. (To disable validation so that you can validate the certificate yourself, use the SSLSetSessionOption function to set the session’s kSSLSessionOptionBreakOnServerAuth flag.)

Availability
  • Available in OS X v10.5 and later.
  • Deprecated in OS X v10.9.
Declared In
SecureTransport.h

SSLCopyTrustedRoots

Retrieves the current list of trusted root certificates. (Deprecated in OS X v10.9.)

OSStatus SSLCopyTrustedRoots (
   SSLContextRef context,
   CFArrayRef *trustedRoots
);
Parameters
context

An SSL session context reference.

trustedRoots

On return, a pointer to a value of type CFArrayRef. This array contains values of type SecCertificateRef representing the current set of trusted roots. You must call the CFRelease function to release this array when you are finished with it.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

You can use the SSLSetTrustedRoots function to replace or add to the set of trusted root certificates. If SSLSetTrustedRoots has never been called for this session, the SSLCopyTrustedRoots function returns the system’s default set of trusted root certificates.

Availability
  • Available in OS X v10.5 and later.
  • Deprecated in OS X v10.9.
Declared In
SecureTransport.h

SSLDisposeContext

Disposes of an SSL session context. (Deprecated in OS X v10.9.)

OSStatus SSLDisposeContext (
   SSLContextRef context
);
Parameters
context

A reference to the SSL session context to dispose.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

When you are completely finished with a secure session, you should dispose of the SSL session context in order to release the memory associated with the session.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.9.
Declared In
SecureTransport.h

SSLGetAllowsAnyRoot

Obtains a value specifying whether an unknown root is allowed. (Deprecated in OS X v10.9.)

OSStatus SSLGetAllowsAnyRoot (
   SSLContextRef context,
   Boolean *anyRoot
);
Parameters
context

An SSL session context reference.

anyRoot

On return, a Boolean indicating the current setting of the anyRoot flag.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

Use the SSLSetAllowsAnyRoot function to set the value of the anyRoot flag. The effect and meaning of this flag is described in the discussion of the SSLSetAllowsAnyRoot function.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.9.
Declared In
SecureTransport.h

SSLGetAllowsExpiredCerts

Retrieves the value specifying whether expired certificates are allowed. (Deprecated in OS X v10.9.)

OSStatus SSLGetAllowsExpiredCerts (
   SSLContextRef context,
   Boolean *allowsExpired
);
Parameters
context

An SSL session context reference.

allowsExpired

On return, this flag is set to the value of the Boolean flag that specifies whether expired certificates are ignored. If this value is true, then Secure Transport does not return an error if any certificates in the certificate chain are expired.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

You can set the allowsExpired flag to allow the handshake to succeed even if one or more certificates in the certificate chain have expired. This function returns the current setting of this flag. Use the SSLSetAllowsExpiredCerts function to set the value of the allowsExpired flag.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.9.
Declared In
SecureTransport.h

SSLGetAllowsExpiredRoots

Retrieves the value indicating whether expired roots are allowed. (Deprecated in OS X v10.9.)

OSStatus SSLGetAllowsExpiredRoots (
   SSLContextRef context,
   Boolean *allowsExpired
);
Parameters
context

An SSL session context reference.

allowsExpired

On return, points to a Boolean value indicating whether expired roots are allowed. If this value is true, no errors are returned if the certificate chain ends in an expired root.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

Use the SSLSetAllowsExpiredRoots function to change the setting of the allowsExpired flag.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.9.
Declared In
SecureTransport.h

SSLGetEnableCertVerify

Determines whether peer certificate chain validation is currently enabled. (Deprecated in OS X v10.9.)

OSStatus SSLGetEnableCertVerify (
   SSLContextRef context,
   Boolean *enableVerify
);
Parameters
context

An SSL session context reference.

enableVerify

On return, a pointer to a Boolean value specifying whether peer certificate chain validation is enabled. If this value is true, then Secure Transport automatically attempts to verify the certificate chain during exchange of peer certificates.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

Use the SSLSetEnableCertVerify function to set the value of the enableVerify flag.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.9.
Declared In
SecureTransport.h

SSLGetProtocolVersionEnabled

Retrieves the enabled status of a given protocol. (Deprecated in OS X v10.9.)

OSStatus SSLGetProtocolVersionEnabled (
   SSLContextRef context,
   SSLProtocol protocol,
   Boolean *enable
);
Parameters
context

An SSL session context reference.

protocol

A value of type SSLProtocol representing an SSL protocol version.

enable

On return, points to a Boolean value indicating whether the specified protocol version is enabled. If this value is true, the protocol is enabled.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

You can specify any one of the following values for the protocol parameter:

  • kSSLProtocol2

  • kSSLProtocol3

  • kTLSProtocol1

  • kSSLProtocolAll Specify this value to determine whether all protocols are enabled.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.9.
Declared In
SecureTransport.h

SSLGetRsaBlinding

Obtains a value indicating whether RSA blinding is enabled. (Deprecated in OS X v10.9.)

OSStatus SSLGetRsaBlinding (
   SSLContextRef context,
   Boolean *blinding
);
Parameters
context

An SSL session context reference.

blinding

On return, a pointer to a Boolean value indicating whether RSA blinding is enabled.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

This function is used only on the server side of a connection.

Call the SSLSetRsaBlinding function to enable or disable RSA blinding.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.9.
Declared In
SecureTransport.h

SSLNewContext

Creates a new SSL session context. (Deprecated in OS X v10.9.)

OSStatus SSLNewContext (
   Boolean isServer,
   SSLContextRef *contextPtr
);
Parameters
isServer

Set true if the calling process is a server.

contextPtr

On return, points to a new SSL session context reference.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

The SSL session context is an opaque data structure that identifies a session and stores session information. You must pass this object to every other function in the Secure Transport API.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.9.
Declared In
SecureTransport.h

SSLSetAllowsAnyRoot

Specifies whether root certificates from unrecognized certification authorities are allowed. (Deprecated in OS X v10.9.)

OSStatus SSLSetAllowsAnyRoot (
   SSLContextRef context,
   Boolean anyRoot
);
Parameters
context

An SSL session context reference.

anyRoot

A Boolean flag specifying whether root certificates from unrecognized certification authorities (CAs) are allowed. The default for this flag is false, specifying that roots from unrecognized CAs are not allowed.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

The system maintains a set of root certificates signed by known, trusted root CAs. When the anyRoot flag is true, Secure Transport does not return an error if one of the following two conditions occurs:

  • The peer returns a certificate chain with a root certificate, and the chain verifies to that root, but the CA for the root certificate is not one of the known, trusted root CAs. This results in an errSSLUnknownRootCert result code when the anyRoot flag is false.

  • The peer returns a certificate chain that does not contain a root certificate, and the server can’t verify the chain to one of the trusted root certificates. This results in an errSSLNoRootCert result code when the anyRoot flag is false.

Both of these error conditions are ignored when the anyRoot flag is true, allowing connection to a peer for which trust could not be established.

If you use this function to allow an untrusted root to be used for validation of a certificate—for example, after prompting the user for permission to do so—remember to set the anyRoot Boolean value back to false. If you don’t, any random root certificate can be used for signing a certificate chain. To add a certificate to the list of trusted roots, use the SecTrustSetAnchorCertificates function.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.9.
Declared In
SecureTransport.h

SSLSetAllowsExpiredCerts

Specifies whether certificate expiration times are ignored. (Deprecated in OS X v10.9.)

OSStatus SSLSetAllowsExpiredCerts (
   SSLContextRef context,
   Boolean allowsExpired
);
Parameters
context

An SSL session context reference.

allowsExpired

A Boolean flag representing whether the certificate expiration times are ignored. The default for this flag is false, meaning expired certificates result in an errSSLCertExpired result code.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

You can use this function to allow the handshake to succeed even if one or more certificates in the certificate chain have expired. You can use the SSLGetAllowsExpiredCerts function to determine the current setting of the allowsExpired flag.

Use the SSLSetAllowsExpiredRoots function to set a flag specifying whether expired root certificates are allowed.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.9.
Declared In
SecureTransport.h

SSLSetAllowsExpiredRoots

Specifies whether expired root certificates are allowed. (Deprecated in OS X v10.9.)

OSStatus SSLSetAllowsExpiredRoots (
   SSLContextRef context,
   Boolean allowsExpired
);
Parameters
context

An SSL session context reference.

allowsExpired

A Boolean value indicating whether to allow expired root certificates. Pass true to allow expired roots.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

The default value for the allowsExpired flag is false. When this flag is false, Secure Transport returns an errSSLCertExpired result code during handshake if the root certificate is expired.

You can use the SSLGetAllowsExpiredRoots function to determine the current setting of the allowsExpired flag.

Use the SSLSetAllowsExpiredCerts function to set a value that determines whether expired non-root certificates are allowed.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.9.
Declared In
SecureTransport.h

SSLSetEnableCertVerify

Enables or disables peer certificate chain validation. (Deprecated in OS X v10.9.)

OSStatus SSLSetEnableCertVerify (
   SSLContextRef context,
   Boolean enableVerify
);
Parameters
context

An SSL session context reference.

enableVerify

A Boolean value specifying whether peer certificate chain validation is enabled. Certificate chain validation is enabled by default. Specify false to disable validation.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

By default, Secure Transport attempts to verify the certificate chain during an exchange of peer certificates. If you disable peer certificate chain validation, it is your responsibility to call SSLCopyPeerCertificates upon successful completion of the handshake and then to validate the peer certificate chain before transferring the data.

You can use the SSLGetEnableCertVerify function to determine the current setting of the enableVerify flag.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.9.
Declared In
SecureTransport.h

SSLSetProtocolVersionEnabled

Sets the allowed SSL protocol versions. (Deprecated in OS X v10.9.)

OSStatus SSLSetProtocolVersionEnabled (
   SSLContextRef context,
   SSLProtocol protocol,
   Boolean enable
);
Parameters
context

An SSL session context reference.

protocol

The SSL protocol version to enable. Pass kSSLProtocolAll to enable all protocols.

enable

A Boolean value indicating whether to enable or disable the specified protocol. Specify true to enable the protocol.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

Calling this function is optional. The default is that all supported protocols are enabled. When you call this function, only the specified protocol is affected. Therefore, if you call it once to disable SSL version 2 (for example), the other protocols all remain enabled. You may call this function as many times as you wish to enable and disable specific protocols. You can specify one of the following values for the protocol parameter:

  • kSSLProtocol2

  • kSSLProtocol3

  • kTLSProtocol1

  • kSSLProtocolAll

This function cannot be called when a session is active.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.9.
Declared In
SecureTransport.h

SSLSetRsaBlinding

Enables or disables RSA blinding. (Deprecated in OS X v10.9.)

OSStatus SSLSetRsaBlinding (
   SSLContextRef context,
   Boolean blinding
);
Parameters
context

An SSL session context reference.

blinding

A Boolean value indicating whether to enable RSA blinding. Pass true to enable RSA blinding.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

This function is used only on the server side of a connection.

This feature thwarts a known attack to which RSA keys are vulnerable: It is possible to guess the RSA key by timing how long it takes the server to calculate the response to certain queries. RSA blinding adds a random calculation to each query response, thus making the attack impossible. Enabling RSA blinding is a trade-off between performance and security.

RSA blinding is enabled by default. Use the SSLGetRsaBlinding function to determine the current setting.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.9.
Declared In
SecureTransport.h

SSLSetTrustedRoots

Augments or replaces the default set of trusted root certificates for this session. (Deprecated in OS X v10.9.)

OSStatus SSLSetTrustedRoots (
   SSLContextRef context,
   CFArrayRef trustedRoots,
   Boolean replaceExisting
);
Parameters
context

An SSL session context reference.

trustedRoots

A reference to an array of trusted root certificates of type SecCertificateRef.

replaceExisting

A Boolean value indicating whether to replace or append the current trusted root certificate set. If this value is true, the specified root certificates become the only roots that are trusted during this session. If this value is false, the specified root certificates are added to the current set of trusted root certificates.

Return Value

A result code. See “Secure Transport Result Codes.”

Discussion

Each successive call to this function with the replaceExisting parameter set to false results in accumulation of additional root certificates. To see the current set of trusted root certificates, call the SSLCopyTrustedRoots function.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.9.
Declared In
SecureTransport.h