Mac Developer Library

Developer

Security Framework Reference Secure Transport Reference

Options
Deployment Target:

On This Page
Language:

Secure Transport Reference

This document describes the public API for an implementation of the protocols Secure Sockets Layer version 3.0 and Transport Layer Security version 1.0.

There are no transport layer dependencies in this library; it can be used with BSD Sockets and Open Transport, among other protocols. To use this library, you must provide callback functions to perform the actual I/O on underlying network connections. You are also responsible for setting up raw network connections; you pass in an opaque reference to the underlying (connected) entity at the start of an SSL session in the form of an SSLConnectionRef object.

The following terms are used in this document:

  • A client is the initiator of an SSL session. The canonical example of a client is a web browser communicating with an HTTPS URL.

  • A server is an entity that accepts requests for SSL sessions made by clients. An example is a secure web server.

  • An SSL session is bounded by calls to the functions SSLHandshake and SSLClose. An active session is in some state between these two calls, inclusive.

  • An SSL session context, or SSLContextRef, is an opaque reference to the state associated with one session. A session context cannot be reused for multiple sessions.

Most applications need only a few of the functions in this API, which are normally called in the following sequence:

  1. Preparing for a session

    1. Call SSLNewContext (in OS X) or SSLCreateContext (in iOS and OS X) to create a new SSL session context.

    2. Write the SSLWrite andSSLRead I/O functions and call SSLSetIOFuncs to pass them to Secure Transport.

    3. Establish a connection using CFNetwork, BSD Sockets, or Open Transport. Then call SSLSetConnection to specify the connection to which the SSL session context applies.

    4. Call SSLSetPeerDomainName to specify the fully-qualified domain name of the peer to which you want to connect (optional but highly recommended).

    5. Call SSLSetCertificate to specify the certificate to be used in authentication (required for server side, optional for client).

  2. Starting a session

    • Call SSLHandshake to perform the SSL handshake and establish a secure session.

  3. Maintaining the session

    • To transfer data over the secure session, Secure Transport calls your SSLWrite andSSLRead functions as needed (see step 1b).

  4. Ending a session

    1. Call SSLClose to close the secure session.

    2. Close the connection and dispose of the connection reference (SSLConnectionRef).

    3. If you created the context by calling SSLNewContext, call SSLDisposeContext to dispose of the SSL session context.

      If you created the context by calling SSLCreateContext, release the SSL session context by calling CFRelease.

    4. If you have called SSLGetPeerCertificates to obtain any certificates, call CFRelease to release the certificate reference objects.

In many cases, it is easier to use the CFNetwork API than Secure Transport to implement a simple connection to a secure (HTTPS) URL. See CFNetwork Programming Guide for documentation of the CFNetwork API and the CFNetworkHTTPDownload sample code for an example of code that downloads data from a URL. If you specify an HTTPS URL, this routine automatically uses Secure Transport to encrypt the data stream.

For functions to manage and evaluate certificates, see Certificate, Key, and Trust Services Reference and Certificate, Key, and Trust Services Programming Guide.

Functions

  • Creates a new SSL session context.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

  • Disposes of an SSL session context.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

  • Specifies an I/O connection for a specific session.

    Declaration

    Swift

    func SSLSetConnection(_ context: SSLContext!, _ connection: SSLConnectionRef) -> OSStatus

    Objective-C

    OSStatus SSLSetConnection ( SSLContextRef context, SSLConnectionRef connection );

    Parameters

    context

    An SSL session context reference.

    connection

    An SSL session connection reference. The connection data is opaque to Secure Transport; you can set it to any value that your application can use to uniquely identify the connection in the callback functions SSLReadFunc and SSLWriteFunc.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    You must establish a connection before creating a secure session. After calling the SSLNewContext function to create an SSL session context, you call the SSLSetConnection function to specify the connection to which the context applies. You specify a value in the connection parameter that your callback routines can use to identify the connection. This value might be a pointer to a socket (if you are using the Sockets API) or an endpoint (if you are using Open Transport). For example, you might create a socket, start a connection on it, create a context reference, cast the socket to an SSLConnectionRef, and then pass both the context reference and connection reference to the SSLSetConnection function.

    Note that the Sockets API is the preferred networking interface for new development.

    On the client side, it’s assumed that communication has been established with the desired server on this connection. On the server side, it’s assumed that a connection has been established in response to an incoming client request .

    This function must be called prior to the SSLHandshake function; consequently, this function can be called only when no session is active.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Retrieves an I/O connection—such as a socket or endpoint—for a specific session.

    Declaration

    Swift

    func SSLGetConnection(_ context: SSLContext!, _ connection: UnsafeMutablePointer<SSLConnectionRef>) -> OSStatus

    Objective-C

    OSStatus SSLGetConnection ( SSLContextRef context, SSLConnectionRef *connection );

    Parameters

    context

    An SSL session context reference.

    connection

    On return, a pointer to a session connection reference. If no connection has been set using the SSLSetConnection function, then this parameter is NULL on return.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    You can use this function on either the client or server to retrieve the connection associated with a secure session.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Specifies an option for a specific session.

    Declaration

    Swift

    func SSLSetSessionOption(_ context: SSLContext!, _ option: SSLSessionOption, _ value: Boolean) -> OSStatus

    Objective-C

    OSStatus SSLSetSessionOption ( SSLContextRef context, SSLSessionOption option, Boolean value );

    Parameters

    context

    An SSL session context reference.

    option

    An SSL session option. Possible values are listed in SSL Session Options.

    value

    Set to true to enable the option, or false to disable it.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    This function must be called prior to the SSLHandshake function; consequently, this function can be called only when no session is active.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.6 and later.

  • Indicates the current setting of an SSL session option.

    Declaration

    Swift

    func SSLGetSessionOption(_ context: SSLContext!, _ option: SSLSessionOption, _ value: UnsafeMutablePointer<Boolean>) -> OSStatus

    Objective-C

    OSStatus SSLGetSessionOption ( SSLContextRef context, SSLSessionOption option, Boolean *value );

    Parameters

    context

    An SSL session context reference.

    option

    An SSL session option. Possible values are listed in SSL Session Options.

    value

    On return, true if the option is enabled, or false otherwise.

    Return Value

    A result code. See Secure Transport Result Codes.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.6 and later.

  • Specifies callback functions that perform the network I/O operations.

    Declaration

    Swift

    func SSLSetIOFuncs(_ context: SSLContext!, _ read: SSLReadFunc, _ write: SSLWriteFunc) -> OSStatus

    Objective-C

    OSStatus SSLSetIOFuncs ( SSLContextRef context, SSLReadFunc readFunc, SSLWriteFunc writeFunc );

    Parameters

    context

    An SSL session context reference.

    read

    A pointer to your read callback function. See SSLReadFunc for information on defining this function.

    write

    A pointer to your write callback function. See SSLWriteFunc for information on defining this function.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    Secure Transport calls your read and write callback functions to perform network I/O. You must define these functions before calling SSLSetIOFuncs.

    You must call SSLSetIOFuncs prior to calling the SSLHandshake function. SSLSetIOFuncs cannot be called while a session is active.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Sets the allowed SSL protocol versions.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

  • Retrieves the enabled status of a given protocol.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

  • Specifies the requirements for client-side authentication.

    Declaration

    Swift

    func SSLSetClientSideAuthenticate(_ context: SSLContext!, _ auth: SSLAuthenticate) -> OSStatus

    Objective-C

    OSStatus SSLSetClientSideAuthenticate ( SSLContextRef context, SSLAuthenticate auth );

    Parameters

    context

    An SSL session context reference.

    auth

    A flag setting the requirements for client-side authentication. See SSL Authentication Constants for possible values.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    This function can be called only by servers. Use of this function is optional. The default authentication requirement is kNeverAuthenticate. This function may be called only when no session is active.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Enables or disables RSA blinding.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

  • Obtains a value indicating whether RSA blinding is enabled.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

  • Performs the SSL handshake.

    Declaration

    Swift

    func SSLHandshake(_ context: SSLContext!) -> OSStatus

    Objective-C

    OSStatus SSLHandshake ( SSLContextRef context );

    Parameters

    context

    An SSL session context reference.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    On successful return, the session is ready for normal secure communication using the functions SSLRead and SSLWrite.

    If it finds any problems with the peer’s certificate chain, Secure Transport aborts the handshake. You can use the SSLCopyPeerCertificates function to see the peer’s certificate chain. This function can return a wide variety of result codes, including the following:

    • errSSLUnknownRootCert—The peer has a valid certificate chain, but the root of the chain is not a known anchor certificate.

    • errSSLNoRootCert—The peer’s certificate chain was not verifiable to a root certificate.

    • errSSLCertExpired—The peer’s certificate chain has one or more expired certificates.

    • errSSLXCertChainInvalid—The peer has an invalid certificate chain; for example, signature verification within the chain failed, or no certificates were found.

    • errSSLClientCertRequested—The server has requested a client certificate. This result is returned only if you called the SSLSetSessionOption function to set the kSSLSessionOptionBreakOnCertRequested option. After receiving this result, you must call the SSLSetCertificate function to return the client certificate, and then call SSLHandshake again to resume the handshake. Use the SSLCopyDistinguishedNames function to obtain a list of certificates acceptable to the server.

    • errSSLServerAuthCompleted—The server authentication portion of the handshake is complete. This result is returned only if you called the SSLSetSessionOption function to set the kSSLSessionOptionBreakOnServerAuth option, and provides an opportunity to perform application-specific server verification before calling SSLHandshake again to continue.

      Note that in OS X prior to version 10.8, you must also explicitly call SSLSetEnableCertVerify to disable verification.

    A return value of errSSLWouldBlock indicates that the SSLHandshake function must be called again until a different result code is returned.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Retrieves the state of an SSL session.

    Declaration

    Swift

    func SSLGetSessionState(_ context: SSLContext!, _ state: UnsafeMutablePointer<SSLSessionState>) -> OSStatus

    Objective-C

    OSStatus SSLGetSessionState ( SSLContextRef context, SSLSessionState *state );

    Parameters

    context

    An SSL session context reference.

    state

    On return, points to a constant that indicates the state of the SSL session. See SSL Session State Constants for possible values.

    Return Value

    A result code. See Secure Transport Result Codes.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Obtains the negotiated protocol version of the active session.

    Declaration

    Swift

    func SSLGetNegotiatedProtocolVersion(_ context: SSLContext!, _ `protocol`: UnsafeMutablePointer<SSLProtocol>) -> OSStatus

    Objective-C

    OSStatus SSLGetNegotiatedProtocolVersion ( SSLContextRef context, SSLProtocol *protocol );

    Parameters

    context

    An SSL session context reference.

    protocol

    On return, points to the negotiated protocol version of the active session.

    Return Value

    A result code. See Secure Transport Result Codes. This function returns kSSLProtocolUnknown if no SSL session is in progress.

    Discussion

    This function retrieves the version of SSL or TLS protocol negotiated for the session. Note that the negotiated protocol may not be the same as your preferred protocol, depending on which protocol versions you enabled with the SSLSetProtocolVersionEnabled function. This function can return any of the following values:

    • kSSLProtocol2

    • kSSLProtocol3

    • kTLSProtocol1

    • kSSLProtocolUnknown

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Specifies data that is sufficient to uniquely identify the peer of the current session.

    Declaration

    Swift

    func SSLSetPeerID(_ context: SSLContext!, _ peerID: UnsafePointer<Void>, _ peerIDLen: UInt) -> OSStatus

    Objective-C

    OSStatus SSLSetPeerID ( SSLContextRef context, const void *peerID, size_t peerIDLen );

    Parameters

    context

    An SSL session context reference.

    peerID

    A pointer to a buffer containing the peer ID data to set.

    peerIDLen

    The length of the peer ID data buffer.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    Secure Transport uses the peer ID to match the peer of an SSL session with the peer of a previous session in order to resume an interrupted session. If the peer IDs match, Secure Transport attempts to resume the session with the same parameters as used in the previous session with the same peer.

    The data you provide to this function is treated as an opaque blob by Secure Transport but is compared byte for byte with previous peer ID data values set by the current application. An example of peer ID data is an IP address and port, stored in some caller-private manner. Calling this function is optional but is required if you want the session to be resumable. If you do call this function, you must call it prior to the handshake for the current session.

    You can use the SSLGetPeerID function to retrieve the peer ID data for the current session.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Retrieves the current peer ID data.

    Declaration

    Swift

    func SSLGetPeerID(_ context: SSLContext!, _ peerID: UnsafeMutablePointer<UnsafePointer<Void>>, _ peerIDLen: UnsafeMutablePointer<UInt>) -> OSStatus

    Objective-C

    OSStatus SSLGetPeerID ( SSLContextRef context, const void **peerID, size_t *peerIDLen );

    Parameters

    context

    An SSL session context reference.

    peerID

    On return, points to a buffer containing the peer ID data.

    peerIDLen

    On return, the length of the peer ID data buffer.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    If the peer ID data for this context was not set by calling the SSLSetPeerID function, this function returns a NULL pointer in the peerID parameter, and 0 in the peerIDLen parameter.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Determines how much data is available to be read.

    Declaration

    Swift

    func SSLGetBufferedReadSize(_ context: SSLContext!, _ bufSize: UnsafeMutablePointer<UInt>) -> OSStatus

    Objective-C

    OSStatus SSLGetBufferedReadSize ( SSLContextRef context, size_t *bufSize );

    Parameters

    context

    An SSL session context reference.

    bufSize

    On return, the size of the data to be read.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    This function determines how much data you can be guaranteed to obtain in a call to the SSLRead function. This function does not block or cause any low-level read operations to occur.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Performs a normal application-level read operation.

    Declaration

    Swift

    func SSLRead(_ context: SSLContext!, _ data: UnsafeMutablePointer<Void>, _ dataLength: UInt, _ processed: UnsafeMutablePointer<UInt>) -> OSStatus

    Objective-C

    OSStatus SSLRead ( SSLContextRef context, void *data, size_t dataLength, size_t *processed );

    Parameters

    context

    An SSL session context reference.

    data

    On return, points to the data read. You must allocate this buffer before calling the function. The size of this buffer must be equal to or greater than the value in the dataLength parameter.

    dataLength

    The amount of data you would like to read.

    processed

    On return, points to the number of bytes actually read.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    The SSLRead function might call the SSLReadFunc function that you provide (see SSLSetIOFuncs. Because you may configure the underlying connection to operate in a nonblocking manner, a read operation might return errSSLWouldBlock, indicating that less data than requested was actually transferred. In this case, you should repeat the call to SSLRead until some other result is returned.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Performs a normal application-level write operation.

    Declaration

    Swift

    func SSLWrite(_ context: SSLContext!, _ data: UnsafePointer<Void>, _ dataLength: UInt, _ processed: UnsafeMutablePointer<UInt>) -> OSStatus

    Objective-C

    OSStatus SSLWrite ( SSLContextRef context, const void *data, size_t dataLength, size_t *processed );

    Parameters

    context

    An SSL session context reference.

    data

    A pointer to the buffer of data to write.

    dataLength

    The amount, in bytes, of data to write.

    processed

    On return, the length, in bytes, of the data actually written.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    The SSLWrite function might call the SSLWriteFunc function that you provide (see SSLSetIOFuncs). Because you may configure the underlying connection to operate in a no-blocking manner, a write operation might return errSSLWouldBlock, indicating that less data than requested was actually transferred. In this case, you should repeat the call to SSLWrite until some other result is returned.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Terminates the current SSL session.

    Declaration

    Swift

    func SSLClose(_ context: SSLContext!) -> OSStatus

    Objective-C

    OSStatus SSLClose ( SSLContextRef context );

    Parameters

    context

    The SSL session context reference of the session you want to terminate.

    Return Value

    A result code. See Secure Transport Result Codes.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Determines the number of cipher suites supported.

    Declaration

    Swift

    func SSLGetNumberSupportedCiphers(_ context: SSLContext!, _ numCiphers: UnsafeMutablePointer<UInt>) -> OSStatus

    Objective-C

    OSStatus SSLGetNumberSupportedCiphers ( SSLContextRef context, size_t *numCiphers );

    Parameters

    context

    An SSL session context reference.

    numCiphers

    On return, points to the number of supported cipher suites.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    You use the number of enabled cipher suites returned by this function when you call the SSLGetNumberSupportedCiphers function to retrieve the list of currently enabled cipher suites.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Determines the values of the supported cipher suites.

    Declaration

    Swift

    func SSLGetSupportedCiphers(_ context: SSLContext!, _ ciphers: UnsafeMutablePointer<SSLCipherSuite>, _ numCiphers: UnsafeMutablePointer<UInt>) -> OSStatus

    Objective-C

    OSStatus SSLGetSupportedCiphers ( SSLContextRef context, SSLCipherSuite *ciphers, size_t *numCiphers );

    Parameters

    context

    An SSL session context reference.

    ciphers

    On return, points to the values of the supported cipher suites. Before calling, you must allocate this buffer using the number of supported cipher suites retrieved from a call to the SSLGetNumberSupportedCiphers function.

    numCiphers

    Points to the number of supported cipher suites that you want returned. Before calling, retrieve this value by calling the SSLGetNumberSupportedCiphers function.

    Return Value

    A result code. See Secure Transport Result Codes. If the supplied buffer is too small, errSSLBufferOverflow is returned.

    Discussion

    All the supported cipher suites are enabled by default. Use the SSLSetEnabledCiphers function to enable a subset of the supported cipher suites. Use the SSLGetEnabledCiphers function to determine which cipher suites are currently enabled.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Specifies a restricted set of SSL cipher suites to be enabled by the current SSL session context.

    Declaration

    Swift

    func SSLSetEnabledCiphers(_ context: SSLContext!, _ ciphers: UnsafePointer<SSLCipherSuite>, _ numCiphers: UInt) -> OSStatus

    Objective-C

    OSStatus SSLSetEnabledCiphers ( SSLContextRef context, const SSLCipherSuite *ciphers, size_t numCiphers );

    Parameters

    context

    An SSL session context reference.

    ciphers

    A pointer to the cipher suites to enable.

    numCiphers

    The number of cipher suites to enable.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    You can call this function, for example, to limit cipher suites to those that use exportable key sizes or to those supported by a particular protocol version.

    This function can be called only when no session is active. The default set of enabled cipher suites is the complete set of supported cipher suites obtained by calling the SSLGetSupportedCiphers function.

    Call the SSLGetEnabledCiphers function to determine which SSL cipher suites are currently enabled.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Determines the number of cipher suites currently enabled.

    Declaration

    Swift

    func SSLGetNumberEnabledCiphers(_ context: SSLContext!, _ numCiphers: UnsafeMutablePointer<UInt>) -> OSStatus

    Objective-C

    OSStatus SSLGetNumberEnabledCiphers ( SSLContextRef context, size_t *numCiphers );

    Parameters

    context

    An SSL session context reference.

    numCiphers

    On return, points to the number of enabled cipher suites.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    You use the number of enabled cipher suites returned by this function when you call the SSLGetEnabledCiphers function to retrieve the list of currently enabled cipher suites.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Determines which SSL cipher suites are currently enabled.

    Declaration

    Swift

    func SSLGetEnabledCiphers(_ context: SSLContext!, _ ciphers: UnsafeMutablePointer<SSLCipherSuite>, _ numCiphers: UnsafeMutablePointer<UInt>) -> OSStatus

    Objective-C

    OSStatus SSLGetEnabledCiphers ( SSLContextRef context, SSLCipherSuite *ciphers, size_t *numCiphers );

    Parameters

    context

    An SSL session context reference.

    ciphers

    On return, points to the enabled cipher suites. Before calling, you must allocate this buffer using the number of enabled cipher suites retrieved from a call to the SSLGetNumberEnabledCiphers function.

    numCiphers

    Pointer to the number of enabled cipher suites. Before calling, retrieve this value by calling the SSLGetNumberEnabledCiphers function.

    Return Value

    A result code. See Secure Transport Result Codes. If the supplied buffer is too small, errSSLBufferOverflow is returned.

    Discussion

    Call the SSLSetEnabledCiphers function to specify which SSL cipher suites are enabled.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Retrieves the cipher suite negotiated for this session.

    Declaration

    Swift

    func SSLGetNegotiatedCipher(_ context: SSLContext!, _ cipherSuite: UnsafeMutablePointer<SSLCipherSuite>) -> OSStatus

    Objective-C

    OSStatus SSLGetNegotiatedCipher ( SSLContextRef context, SSLCipherSuite *cipherSuite );

    Parameters

    context

    An SSL session context reference.

    cipherSuite

    On return, points to the cipher suite that was negotiated for this session.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    You should call this function only when a session is active.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Specifies Diffie-Hellman parameters.

    Declaration

    Swift

    func SSLSetDiffieHellmanParams(_ context: SSLContext!, _ dhParams: UnsafePointer<Void>, _ dhParamsLen: UInt) -> OSStatus

    Objective-C

    OSStatus SSLSetDiffieHellmanParams ( SSLContextRef context, const void *dhParams, size_t dhParamsLen );

    Parameters

    context

    An SSL session context reference.

    dhParams

    A pointer to a buffer containing the Diffie-Hellman parameters in Open SSL DER format.

    dhParamsLen

    A value representing the size of the buffer pointed to by the dhParams parameter.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    You can use this function to specify a set of Diffie-Hellman parameters to be used by Secure Transport for a specific session. Use of this function is optional. If Diffie-Hellman ciphers are allowed, the server and client negotiate a Diffie-Hellman cipher, and this function has not been called, then Secure Transport calculates a set of process wide parameters. However, that process can take as long as 30 seconds. Diffie-Hellman ciphers are enabled by default; see SSLSetEnabledCiphers.

    In SSL/TLS, Diffie-Hellman parameters are always specified by the server. Therefore, this function can be called only by the server side of the connection.

    You can use the SSLGetDiffieHellmanParams function to retrieve Diffie-Hellman parameters specified in an earlier call to SSLSetDiffieHellmanParams.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Retrieves the Diffie-Hellman parameters specified earlier.

    Declaration

    Swift

    func SSLGetDiffieHellmanParams(_ context: SSLContext!, _ dhParams: UnsafeMutablePointer<UnsafePointer<Void>>, _ dhParamsLen: UnsafeMutablePointer<UInt>) -> OSStatus

    Objective-C

    OSStatus SSLGetDiffieHellmanParams ( SSLContextRef context, const void **dhParams, size_t *dhParamsLen );

    Parameters

    context

    An SSL session context reference.

    dhParams

    On return, points to a buffer containing the Diffie-Hellman parameter block in Open SSL DER format.The returned data is not copied and belongs to the SSL session context reference; therefore, you cannot modify the data and it is released automatically when you dispose of the context.

    dhParamsLen

    On return, points to the length of the buffer pointed to by the dhParams parameter.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    This function returns the parameter block specified in an earlier call to the function SSLSetDiffieHellmanParams. If SSLSetDiffieHellmanParams was never called, the dhParams parameter returns NULL and the dhParamsLen parameter returns 0.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Specifies whether root certificates from unrecognized certification authorities are allowed.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

  • Obtains a value specifying whether an unknown root is allowed.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

  • Specifies whether expired root certificates are allowed.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

  • Retrieves the value indicating whether expired roots are allowed.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

  • Augments or replaces the default set of trusted root certificates for this session.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

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

    Retrieves the current list of trusted root certificates.

    Deprecation Statement

    Use SSLCopyTrustedRoots instead.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

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

    Deprecated in OS X v10.5.

  • Retrieves the current list of trusted root certificates.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.9.

  • Adds one or more certificates to a server's list of certification authorities (CAs) acceptable for client authentication.

    Declaration

    Swift

    func SSLSetCertificateAuthorities(_ context: SSLContext!, _ certificateOrArray: AnyObject!, _ replaceExisting: Boolean) -> OSStatus

    Objective-C

    OSStatus SSLSetCertificateAuthorities ( SSLContextRef context, CFTypeRef certificateOrArray, Boolean replaceExisting );

    Parameters

    context

    An SSL session context reference.

    certificateOrArray

    A value of type SecCertificateRef, or a value of type CFArray containing an array of SecCertificateRef values, representing one or more certificates to be added to the server’s list of acceptable certification authorities (CAs).

    replaceExisting

    A Boolean value specifying whether to replace or append the current set of certification authorities. If this value is true, the specified certificates replace the existing list of acceptable CAs, if any. If false, the specified certificates are appended to the existing list of.

    Return Value

    A result code. See Secure Transport Result Codes. Returns paramErr if this function is called for a session that is configured as a client, or when a session is active.

    Discussion

    Each successive call to this function with the replaceExisting parameter set to false results in accumulation of additional certification authorities. To see the current set of certification authorities, call the SSLCopyCertificateAuthorities function.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

  • Retrieves the current list of certification authorities.

    Declaration

    Swift

    func SSLCopyCertificateAuthorities(_ context: SSLContext!, _ trustedRoots: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

    OSStatus SSLCopyCertificateAuthorities ( SSLContextRef context, CFArrayRef *certificates );

    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 certification authorities (specified with the SSLSetCertificateAuthorities function). Returns a NULL array if SSLSetCertificateAuthorities has not been called. 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.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

  • Unsupported.

    Declaration

    Swift

    func SSLAddDistinguishedName(_ context: SSLContext!, _ derDN : UnsafePointer<Void>, _ derDNLen: UInt) -> OSStatus

    Objective-C

    OSStatus SSLAddDistinguishedName ( SSLContextRef context, const void *derDN, size_t derDNLen );

    Parameters

    context

    An SSL session context reference.

    derDN

    A pointer to a buffer containing a DER-encoded distinguished name.

    derDNLen

    A value of type size_t representing the size of the buffer pointed to by the parameter derDN.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    This function has not been implemented and is unsupported at this time.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Unsupported.

  • Retrieves the distinguished names of acceptable certification authorities.

    Declaration

    Swift

    func SSLCopyDistinguishedNames(_ context: SSLContext!, _ names: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> OSStatus

    Objective-C

    OSStatus SSLCopyDistinguishedNames ( SSLContextRef context, CFArrayRef *names );

    Parameters

    context

    An SSL session context reference.

    names

    On return, an array of CFDataRef objects, each representing one DER-encoded relative distinguished name of an acceptable certification authority. 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

    The list of distinguished names is provided by the server if the context reference represents a client; if the context reference represents a server, the list of distinguished names is specified with the SSLSetCertificateAuthorities function.

    The array retrieved by this function is suitable for use in finding a client identity (that is, a certificate and associated private key) that matches a server's requirements.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.5 and later.

  • Specifies whether certificate expiration times are ignored.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

  • Retrieves the value specifying whether expired certificates are allowed.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

  • Specifies this connection’s certificate or certificates.

    Declaration

    Swift

    func SSLSetCertificate(_ context: SSLContext!, _ certRefs: CFArray!) -> OSStatus

    Objective-C

    OSStatus SSLSetCertificate ( SSLContextRef context, CFArrayRef certRefs );

    Parameters

    context

    An SSL session context reference.

    certRefs

    The certificates to set. This array contains items of type SecCertificateRef, except for certRefs[0], which is of type SecIdentityRef.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    Setting the certificate or certificates is mandatory for server connections, but is optional for clients. Specifying a certificate for a client enables SSL client-side authentication. You must place in certRefs[0] a SecIdentityRef object that identifies the leaf certificate and its corresponding private key. Specifying a root certificate is optional; if it’s not specified, the root certificate that verifies the certificate chain specified here must be present in the system wide set of trusted anchor certificates.

    This function must be called before calling SSLHandshake, or immediately after SSLHandshake has returned errSSLClientCertRequested (that is, before the handshake is resumed by calling SSLHandshake again).

    Secure Transport assumes the following:

    • The certificate references remain valid for the lifetime of the session.

    • The identity specified in certRefs[0] is capable of signing.

    The required capabilities of the identity specified in certRefs[0]—and of the optional certificate specified in the SSLSetEncryptionCertificate function—are highly dependent on the application. For example, to work as a server with Netscape clients, the identity specified here must be capable of both signing and encrypting. Use the SSLCopyDistinguishedNames function to get a list of certificates acceptable to the server.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Retrieves the exchange status of the client certificate.

    Declaration

    Swift

    func SSLGetClientCertificateState(_ context: SSLContext!, _ clientState: UnsafeMutablePointer<SSLClientCertificateState>) -> OSStatus

    Objective-C

    OSStatus SSLGetClientCertificateState ( SSLContextRef context, SSLClientCertificateState *clientState );

    Parameters

    context

    An SSL session context reference.

    clientState

    On return, a pointer to a value indicating the state of the client certificate exchange. See “SSL Client Certificate State Constants” for a list of possible values.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    The value returned reflects the latest change in the state of the client certificate exchange. If either peer initiates a renegotiation attempt, Secure Transport resets the state to kSSLClientCertNone.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.3 and later.

  • Enables or disables peer certificate chain validation.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

  • Determines whether peer certificate chain validation is currently enabled.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.9.

  • Specifies the encryption certificates used for this connection.

    Declaration

    Swift

    func SSLSetEncryptionCertificate(_ context: SSLContext!, _ certRefs: CFArray!) -> OSStatus

    Objective-C

    OSStatus SSLSetEncryptionCertificate ( SSLContextRef context, CFArrayRef certRefs );

    Parameters

    context

    An SSL session context reference.

    certRefs

    A value of type CFArrayRef referring to an array of certificate references. The references are type SecCertificateRef, except for certRefs[0], which is of type SecIdentityRef.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    Use this function in one of the following cases:

    • The leaf certificate specified in the SSLSetCertificate function is not capable of encryption.

    • The leaf certificate specified in the SSLSetCertificate function contains a key that is too large or strong for legal encryption in this session. In this case, a weaker certificate is specified here and is used for server-initiated key exchange.

    The following assumptions are made:

    • The certRefs parameter’s references remain valid for the lifetime of the connection.

    • The specified certRefs[0] value is capable of encryption.

    This function can be called only when no session is active.

    SSL servers that enforce the SSL3 or TLS1 specification to the letter do not accept encryption certificates with key sizes larger than 512 bits for exportable ciphers (that is, for SSL sessions with 40-bit session keys). Therefore, if you wish to support exportable ciphers and your certificate has a key larger than 512 bits, you must specify a separate encryption certificate.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

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

    Retrieves a peer certificate.

    Deprecation Statement

    Use SSLCopyPeerCertificates instead.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import Security;

    Availability

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

    Deprecated in OS X v10.5.

  • Retrieves a peer certificate and its certificate chain.

    Declaration

    Objective-C

    OSStatus SSLCopyPeerCertificates ( 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.)

    Import Statement

    Objective-C

    @import Security;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.9.

  • Retrieves a trust management object for the certificate used by a session.

    Declaration

    Swift

    func SSLCopyPeerTrust(_ context: SSLContext!, _ trust: UnsafeMutablePointer<Unmanaged<SecTrust>?>) -> OSStatus

    Objective-C

    OSStatus SSLCopyPeerTrust ( SSLContextRef context, SecTrustRef *trust );

    Parameters

    context

    An SSL session context reference.

    trust

    On return, a trust management object you can use to evaluate trust for the certificate used by the session. A trust management object includes the certificate to be verified plus the policy or policies to be used in evaluating trust. See Certificate, Key, and Trust Services Reference for functions to create and evaluate trust management objects. You must call the CFRelease function for this object 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.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.6 and later.

  • Specifies the fully qualified domain name of the peer.

    Declaration

    Swift

    func SSLSetPeerDomainName(_ context: SSLContext!, _ peerName: UnsafePointer<Int8>, _ peerNameLen: UInt) -> OSStatus

    Objective-C

    OSStatus SSLSetPeerDomainName ( SSLContextRef context, const char *peerName, size_t peerNameLen );

    Parameters

    context

    An SSL session context reference.

    peerName

    The fully qualified domain name of the peer—for example, store.apple.com. The name is in the form of a C string, except that NULL termination is optional.

    peerNameLen

    The number of bytes passed in the peerName parameter.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    You can use this function to verify the common name field in the peer’s certificate. If you call this function and the common name in the certificate does not match the value you specify in the peerName parameter, then handshake fails and returns errSSLXCertChainInvalid. Use of this function is optional.

    This function can be called only when no session is active.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Determines the length of a previously set peer domain name.

    Declaration

    Swift

    func SSLGetPeerDomainNameLength(_ context: SSLContext!, _ peerNameLen: UnsafeMutablePointer<UInt>) -> OSStatus

    Objective-C

    OSStatus SSLGetPeerDomainNameLength ( SSLContextRef context, size_t *peerNameLen );

    Parameters

    context

    An SSL session context reference.

    peerNameLen

    On return, points to the length of the peer domain name.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    If you previously called the SSLSetPeerDomainName function to specify a fully qualified domain name for the peer certificate, you can use the SSLGetPeerDomainName function to retrieve the peer domain name. Before doing so, you must call the SSLGetPeerDomainNameLength function to retrieve the buffer size needed for the domain name.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Retrieves the peer domain name specified previously.

    Declaration

    Swift

    func SSLGetPeerDomainName(_ context: SSLContext!, _ peerName: UnsafeMutablePointer<Int8>, _ peerNameLen : UnsafeMutablePointer<UInt>) -> OSStatus

    Objective-C

    OSStatus SSLGetPeerDomainName ( SSLContextRef context, char *peerName, size_t *peerNameLen );

    Parameters

    context

    An SSL session context reference.

    peerName

    On return, points to the peer domain name.

    peerNameLen

    A pointer to the length of the peer domain name. Before calling this function, retrieve the peer domain name length by calling the function SSLGetPeerDomainNameLength.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    If you previously called the SSLSetPeerDomainName function to specify a fully qualified domain name for the peer certificate, you can use the SSLGetPeerDomainName function to retrieve the domain name.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Returns the CFTypeID for SSLContext objects

    Declaration

    Swift

    func SSLContextGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID SSLContextGetTypeID ( void );

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.8 and later.

  • Allocates and returns a new SSLContextRef object.

    Declaration

    Swift

    func SSLCreateContext(_ alloc: CFAllocator!, _ protocolSide: SSLProtocolSide, _ connectionType: SSLConnectionType) -> Unmanaged<SSLContext>!

    Objective-C

    SSLContextRef SSLCreateContext ( CFAllocatorRef alloc, SSLProtocolSide protocolSide, SSLConnectionType connectionType );

    Parameters

    alloc

    The allocator to use. Pass NULL or kCFAllocatorDefault to use the default allocator.

    protocolSide
    connectionType

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.8 and later.

  • Provides the largest packet that the OS guarantees it can send without fragmentation.

    Declaration

    Swift

    func SSLGetDatagramWriteSize(_ dtlsContext: SSLContext!, _ bufSize: UnsafeMutablePointer<UInt>) -> OSStatus

    Objective-C

    OSStatus SSLGetDatagramWriteSize ( SSLContextRef dtlsContext, size_t *bufSize );

    Parameters

    dtlsContext

    The SSL context associated with the connection.

    bufSize

    The address of a size_t integer for storing the length.

    Return Value

    Returns 0 on success or an error code from MacErrors.h.

    Discussion

    Although any packet below this threshold size will not be fragmented by the OS when sent using SSLWrite, this function provides no guarantees about whether the packet will be fragmented by routers en route. This size value is equal to the maximum Datagram Record size (set by calling SSLSetMaxDatagramRecordSize) minus the DTLS Record header size.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.8 and later.

  • Obtains the maximum datagram record size (including all Datagram TLS record headers) allowed by the application for a given SSL context.

    Declaration

    Swift

    func SSLGetMaxDatagramRecordSize(_ dtlsContext: SSLContext!, _ bufSize: UnsafeMutablePointer<UInt>) -> OSStatus

    Objective-C

    OSStatus SSLGetMaxDatagramRecordSize ( SSLContextRef dtlsContext, size_t *maxSize );

    Parameters

    dtlsContext

    The SSL context associated with the connection.

    bufSize

    The address of a size_t integer for storing the length.

    Return Value

    Returns 0 on success or an error code from MacErrors.h.

    Discussion

    The application can specify a new value by calling SSLSetMaxDatagramRecordSize, up to the maximum size of a UDP packet (which, in turn, is based on the underlying IP protocol).

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.8 and later.

  • Gets the maximum protocol version allowed by the application for a given SSL context.

    Declaration

    Swift

    func SSLGetProtocolVersionMax(_ dtlsContext: SSLContext!, _ maxVersion: UnsafeMutablePointer<SSLProtocol>) -> OSStatus

    Objective-C

    OSStatus SSLGetProtocolVersionMax ( SSLContextRef context, SSLProtocol *maxVersion );

    Parameters

    dtlsContext

    The SSL context associated with the connection.

    maxVersion

    The address of an SSLProtocol integer where the maximum version should be stored. See SSL Protocol Constants for a list of possible values.

    Return Value

    Returns 0 on success or an error code from MacErrors.h.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.8 and later.

  • Gets the minimum protocol version allowed by the application for a given SSL context.

    Declaration

    Swift

    func SSLGetProtocolVersionMin(_ dtlsContext: SSLContext!, _ minVersion: UnsafeMutablePointer<SSLProtocol>) -> OSStatus

    Objective-C

    OSStatus SSLGetProtocolVersionMin ( SSLContextRef context, SSLProtocol *minVersion );

    Parameters

    dtlsContext

    The SSL context associated with the connection.

    minVersion

    The address of an SSLProtocol integer where the minimum version should be stored. See SSL Protocol Constants for a list of possible values.

    Return Value

    Returns 0 on success or an error code from MacErrors.h.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.8 and later.

  • Sets the cookie value used in the Datagram TLS hello message.

    Declaration

    Swift

    func SSLSetDatagramHelloCookie(_ dtlsContext: SSLContext!, _ cookie: UnsafePointer<Void>, _ cookieLen: UInt) -> OSStatus

    Objective-C

    OSStatus SSLSetDatagramHelloCookie ( SSLContextRef dtlsContext, const void *cookie, size_t cookieLen );

    Parameters

    dtlsContext

    The SSL context associated with the connection.

    cookie

    The cookie value.

    cookieLen

    The length of the cookie (up to 32 bytes).

    Return Value

    Returns 0 on success or an error code from MacErrors.h.

    Discussion

    This function should be called only on the server side, and is optional. The default cookie is a zero-length cookie.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.8 and later.

  • Obtains the maximum datagram record size (including all Datagram TLS record headers) allowed by the application for a given SSL context.

    Declaration

    Swift

    func SSLSetMaxDatagramRecordSize(_ dtlsContext: SSLContext!, _ bufSize: UInt) -> OSStatus

    Objective-C

    OSStatus SSLSetMaxDatagramRecordSize ( SSLContextRef dtlsContext, size_t maxSize );

    Parameters

    dtlsContext

    The SSL context associated with the connection.

    bufSize

    The length value.

    Return Value

    Returns 0 on success or an error code from MacErrors.h.

    Discussion

    The application can specify a new value up to the maximum size of a UDP packet (which, in turn, is based on the underlying IP protocol).

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.8 and later.

  • Sets the maximum protocol version allowed by the application for a given SSL context.

    Declaration

    Swift

    func SSLSetProtocolVersionMax(_ dtlsContext: SSLContext!, _ maxVersion: SSLProtocol) -> OSStatus

    Objective-C

    OSStatus SSLSetProtocolVersionMax ( SSLContextRef context, SSLProtocol maxVersion );

    Parameters

    dtlsContext

    The SSL context associated with the connection.

    maxVersion

    The new maximum version (kTLSProtocol1, for example). See SSL Protocol Constants for a complete list.

    Return Value

    Returns 0 on success or an error code from MacErrors.h.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.8 and later.

  • Sets the minimum protocol version allowed by the application for a given SSL context.

    Declaration

    Swift

    func SSLSetProtocolVersionMin(_ dtlsContext: SSLContext!, _ minVersion: SSLProtocol) -> OSStatus

    Objective-C

    OSStatus SSLSetProtocolVersionMin ( SSLContextRef context, SSLProtocol minVersion );

    Parameters

    dtlsContext

    The SSL context associated with the connection.

    minVersion

    The new minimum version (kTLSProtocol1, for example). See SSL Protocol Constants for a complete list.

    Return Value

    Returns 0 on success or an error code from MacErrors.h.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.8 and later.

Callbacks

  • Defines a pointer to a customized read function that Secure Transport calls to read data from the connection.

    Declaration

    Swift

    typealias SSLReadFunc = CFunctionPointer<((SSLConnectionRef, UnsafeMutablePointer<Void>, UnsafeMutablePointer<UInt>) -> OSStatus)>

    Objective-C

    typedef OSStatus (*SSLReadFunc) ( SSLConnectionRef connection, void *data, size_t *dataLength );

    Parameters

    connection

    A connection reference.

    data

    On return, your callback should overwrite the memory at this location with the data read from the connection.

    dataLength

    On input, a pointer to an integer representing the length of the data in bytes. On return, your callback should overwrite that integer with the number of bytes actually transferred.

    Return Value

    Your callback must return an appropriate result code. See Secure Transport Result Codes.

    Discussion

    Before using the Secure Transport API, you must create a read function (conforming to the SSLReadFunc prototype) and a write function (conforming to the SSLWriteFunc prototype) and provide them to the library by calling the SSLSetIOFuncs function.

    You may configure the underlying connection to operate in a nonblocking manner; in that case, a read operation may well return errSSLWouldBlock, indicating less data than requested was transferred and nothing is wrong except that the requested I/O hasn’t completed. This result is returned to the caller from the functions SSLRead, SSLWrite, or SSLHandshake.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Defines a pointer to a customized write function that Secure Transport calls to write data to the connection.

    Declaration

    Swift

    typealias SSLWriteFunc = CFunctionPointer<((SSLConnectionRef, UnsafePointer<Void>, UnsafeMutablePointer<UInt>) -> OSStatus)>

    Objective-C

    typedef OSStatus (*SSLWriteFunc) ( SSLConnectionRef connection, const void *data, size_t *dataLength );

    Parameters

    connection

    The SSL session connection reference.

    data

    A pointer to the data to write to the connection.You must allocate this memory before calling this function.

    dataLength

    Before calling, an integer representing the length of the data in bytes. On return, this is the number of bytes actually transferred.

    Return Value

    A result code. See Secure Transport Result Codes.

    Discussion

    Before using the Secure Transport API, you must write the functions SSLReadFunc and SSLWriteFunc and provide them to the library by calling the SSLSetIOFuncs function.

    You may configure the underlying connection to operate in a nonblocking manner. In that case, a write operation may well return errSSLWouldBlock, indicating less data than requested was transferred and nothing is wrong except that the requested I/O hasn’t completed. This result is returned to the caller from the functions SSLRead, SSLWrite, or SSLHandshake.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

Data Types

  • Represents a pointer to an opaque I/O connection object.

    Declaration

    Swift

    typealias SSLConnectionRef = UnsafePointer<Void>

    Objective-C

    typedef const void *SSLConnectionRef;

    Discussion

    The I/O connection object refers to data that identifies a connection. The connection data is opaque to Secure Transport; you can set it to any value that your application can use in the callback functions SSLReadFunc and SSLWriteFunc to uniquely identify the connection, such as a socket or endpoint. Use the SSLSetConnection function to assign a value to the connection object.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Represents a pointer to an opaque SSL session context object.

    Declaration

    Swift

    typealias SSLContextRef = SSLContext

    Objective-C

    struct SSLContext; typedef struct SSLContext *SSLContextRef;

    Discussion

    The SSL session context object references the state associated with a session. You cannot reuse an SSL session context in multiple sessions.

    Availability

    Available in OS X v10.2 and later.

Constants

  • Represents the requirements for client-side authentication.

    Declaration

    Swift

    struct SSLAuthenticate { init(_ value: UInt32) var value: UInt32 }

    Objective-C

    typedef enum { kNeverAuthenticate, kAlwaysAuthenticate, kTryAuthenticate } SSLAuthenticate;

    Constants

    • kNeverAuthenticate

      kNeverAuthenticate

      Indicates that client-side authentication is not required. (Default.)

      Available in OS X v10.2 and later.

    • kAlwaysAuthenticate

      kAlwaysAuthenticate

      Indicates that client-side authentication is required.

      Available in OS X v10.2 and later.

    • kTryAuthenticate

      kTryAuthenticate

      Indicates that client-side authentication should be attempted. There is no error if the client doesn’t have a certificate.

      Available in OS X v10.2 and later.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Represents the cipher suites available.

    Declaration

    Swift

    typealias SSLCipherSuite = UInt32

    Objective-C

    typedef UInt32 SSLCipherSuite; enum { SSL_NULL_WITH_NULL_NULL = 0x0000, SSL_RSA_WITH_NULL_MD5 = 0x0001, SSL_RSA_WITH_NULL_SHA = 0x0002, SSL_RSA_EXPORT_WITH_RC4_40_MD5 = 0x0003, SSL_RSA_WITH_RC4_128_MD5 = 0x0004, SSL_RSA_WITH_RC4_128_SHA = 0x0005, SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 = 0x0006, SSL_RSA_WITH_IDEA_CBC_SHA = 0x0007, SSL_RSA_EXPORT_WITH_DES40_CBC_SHA = 0x0008, SSL_RSA_WITH_DES_CBC_SHA = 0x0009, SSL_RSA_WITH_3DES_EDE_CBC_SHA = 0x000A, SSL_DH_DSS_EXPORT_WITH_DES40_CBC_SHA = 0x000B, SSL_DH_DSS_WITH_DES_CBC_SHA = 0x000C, SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA = 0x000D, SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA = 0x000E, SSL_DH_RSA_WITH_DES_CBC_SHA = 0x000F, SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA = 0x0010, SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA = 0x0011, SSL_DHE_DSS_WITH_DES_CBC_SHA = 0x0012, SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA = 0x0013, SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA = 0x0014, SSL_DHE_RSA_WITH_DES_CBC_SHA = 0x0015, SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA = 0x0016, SSL_DH_anon_EXPORT_WITH_RC4_40_MD5 = 0x0017, SSL_DH_anon_WITH_RC4_128_MD5 = 0x0018, SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA = 0x0019, SSL_DH_anon_WITH_DES_CBC_SHA = 0x001A, SSL_DH_anon_WITH_3DES_EDE_CBC_SHA = 0x001B, SSL_FORTEZZA_DMS_WITH_NULL_SHA = 0x001C, SSL_FORTEZZA_DMS_WITH_FORTEZZA_CBC_SHA =0x001D, /* TLS addenda using AES, per RFC 3268 */ TLS_RSA_WITH_AES_128_CBC_SHA = 0x002F, TLS_DH_DSS_WITH_AES_128_CBC_SHA = 0x0030, TLS_DH_RSA_WITH_AES_128_CBC_SHA = 0x0031, TLS_DHE_DSS_WITH_AES_128_CBC_SHA = 0x0032, TLS_DHE_RSA_WITH_AES_128_CBC_SHA = 0x0033, TLS_DH_anon_WITH_AES_128_CBC_SHA = 0x0034, TLS_RSA_WITH_AES_256_CBC_SHA = 0x0035, TLS_DH_DSS_WITH_AES_256_CBC_SHA = 0x0036, TLS_DH_RSA_WITH_AES_256_CBC_SHA = 0x0037, TLS_DHE_DSS_WITH_AES_256_CBC_SHA = 0x0038, TLS_DHE_RSA_WITH_AES_256_CBC_SHA = 0x0039, TLS_DH_anon_WITH_AES_256_CBC_SHA = 0x003A, /* ECDSA addenda, RFC 4492 */ TLS_ECDH_ECDSA_WITH_NULL_SHA = 0xC001, TLS_ECDH_ECDSA_WITH_RC4_128_SHA = 0xC002, TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA = 0xC003, TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA = 0xC004, TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA = 0xC005, TLS_ECDHE_ECDSA_WITH_NULL_SHA = 0xC006, TLS_ECDHE_ECDSA_WITH_RC4_128_SHA = 0xC007, TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA = 0xC008, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA = 0xC009, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA = 0xC00A, TLS_ECDH_RSA_WITH_NULL_SHA = 0xC00B, TLS_ECDH_RSA_WITH_RC4_128_SHA = 0xC00C, TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA = 0xC00D, TLS_ECDH_RSA_WITH_AES_128_CBC_SHA = 0xC00E, TLS_ECDH_RSA_WITH_AES_256_CBC_SHA = 0xC00F, TLS_ECDHE_RSA_WITH_NULL_SHA = 0xC010, TLS_ECDHE_RSA_WITH_RC4_128_SHA = 0xC011, TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA = 0xC012, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA = 0xC013, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA = 0xC014, TLS_ECDH_anon_WITH_NULL_SHA = 0xC015, TLS_ECDH_anon_WITH_RC4_128_SHA = 0xC016, TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA = 0xC017, TLS_ECDH_anon_WITH_AES_128_CBC_SHA = 0xC018, TLS_ECDH_anon_WITH_AES_256_CBC_SHA = 0xC019, /* TLS 1.2 addenda, RFC 5246 */ /* Initial state. */ TLS_NULL_WITH_NULL_NULL = 0x0000, /* Server provided RSA certificate for key exchange. */ TLS_RSA_WITH_NULL_MD5 = 0x0001, TLS_RSA_WITH_NULL_SHA = 0x0002, TLS_RSA_WITH_RC4_128_MD5 = 0x0004, TLS_RSA_WITH_RC4_128_SHA = 0x0005, TLS_RSA_WITH_3DES_EDE_CBC_SHA = 0x000A, TLS_RSA_WITH_NULL_SHA256 = 0x003B, TLS_RSA_WITH_AES_128_CBC_SHA256 = 0x003C, TLS_RSA_WITH_AES_256_CBC_SHA256 = 0x003D, /* Server-authenticated (and optionally client-authenticated ) Diffie-Hellman. */ TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA = 0x000D, TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA = 0x0010, TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA = 0x0013, TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA = 0x0016, TLS_DH_DSS_WITH_AES_128_CBC_SHA256 = 0x003E, TLS_DH_RSA_WITH_AES_128_CBC_SHA256 = 0x003F, TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 = 0x0040, TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 = 0x0067, TLS_DH_DSS_WITH_AES_256_CBC_SHA256 = 0x0068, TLS_DH_RSA_WITH_AES_256_CBC_SHA256 = 0x0069, TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 = 0x006A, TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 = 0x006B, /* Completely anonymous Diffie-Hellman */ TLS_DH_anon_WITH_RC4_128_MD5 = 0x0018, TLS_DH_anon_WITH_3DES_EDE_CBC_SHA = 0x001B, TLS_DH_anon_WITH_AES_128_CBC_SHA256 = 0x006C, TLS_DH_anon_WITH_AES_256_CBC_SHA256 = 0x006D, /* Addendum from RFC 4279, TLS PSK */ TLS_PSK_WITH_RC4_128_SHA = 0x008A, TLS_PSK_WITH_3DES_EDE_CBC_SHA = 0x008B, TLS_PSK_WITH_AES_128_CBC_SHA = 0x008C, TLS_PSK_WITH_AES_256_CBC_SHA = 0x008D, TLS_DHE_PSK_WITH_RC4_128_SHA = 0x008E, TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA = 0x008F, TLS_DHE_PSK_WITH_AES_128_CBC_SHA = 0x0090, TLS_DHE_PSK_WITH_AES_256_CBC_SHA = 0x0091, TLS_RSA_PSK_WITH_RC4_128_SHA = 0x0092, TLS_RSA_PSK_WITH_3DES_EDE_CBC_SHA = 0x0093, TLS_RSA_PSK_WITH_AES_128_CBC_SHA = 0x0094, TLS_RSA_PSK_WITH_AES_256_CBC_SHA = 0x0095, /* RFC 4785 - Pre-Shared Key (PSK ) Ciphersuites with NULL Encryption */ TLS_PSK_WITH_NULL_SHA = 0x002C, TLS_DHE_PSK_WITH_NULL_SHA = 0x002D, TLS_RSA_PSK_WITH_NULL_SHA = 0x002E, /* Addenda from rfc 5288 AES Galois Counter Mode (GCM ) Cipher Suites for TLS. */ TLS_RSA_WITH_AES_128_GCM_SHA256 = 0x009C, TLS_RSA_WITH_AES_256_GCM_SHA384 = 0x009D, TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 = 0x009E, TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 = 0x009F, TLS_DH_RSA_WITH_AES_128_GCM_SHA256 = 0x00A0, TLS_DH_RSA_WITH_AES_256_GCM_SHA384 = 0x00A1, TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 = 0x00A2, TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 = 0x00A3, TLS_DH_DSS_WITH_AES_128_GCM_SHA256 = 0x00A4, TLS_DH_DSS_WITH_AES_256_GCM_SHA384 = 0x00A5, TLS_DH_anon_WITH_AES_128_GCM_SHA256 = 0x00A6, TLS_DH_anon_WITH_AES_256_GCM_SHA384 = 0x00A7, /* RFC 5487 - PSK with SHA-256/384 and AES GCM */ TLS_PSK_WITH_AES_128_GCM_SHA256 = 0x00A8, TLS_PSK_WITH_AES_256_GCM_SHA384 = 0x00A9, TLS_DHE_PSK_WITH_AES_128_GCM_SHA256 = 0x00AA, TLS_DHE_PSK_WITH_AES_256_GCM_SHA384 = 0x00AB, TLS_RSA_PSK_WITH_AES_128_GCM_SHA256 = 0x00AC, TLS_RSA_PSK_WITH_AES_256_GCM_SHA384 = 0x00AD, TLS_PSK_WITH_AES_128_CBC_SHA256 = 0x00AE, TLS_PSK_WITH_AES_256_CBC_SHA384 = 0x00AF, TLS_PSK_WITH_NULL_SHA256 = 0x00B0, TLS_PSK_WITH_NULL_SHA384 = 0x00B1, TLS_DHE_PSK_WITH_AES_128_CBC_SHA256 = 0x00B2, TLS_DHE_PSK_WITH_AES_256_CBC_SHA384 = 0x00B3, TLS_DHE_PSK_WITH_NULL_SHA256 = 0x00B4, TLS_DHE_PSK_WITH_NULL_SHA384 = 0x00B5, TLS_RSA_PSK_WITH_AES_128_CBC_SHA256 = 0x00B6, TLS_RSA_PSK_WITH_AES_256_CBC_SHA384 = 0x00B7, TLS_RSA_PSK_WITH_NULL_SHA256 = 0x00B8, TLS_RSA_PSK_WITH_NULL_SHA384 = 0x00B9, /* Addenda from rfc 5289 Elliptic Curve Cipher Suites with HMAC SHA-256/384. */ TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 = 0xC023, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 = 0xC024, TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 = 0xC025, TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 = 0xC026, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 = 0xC027, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 = 0xC028, TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 = 0xC029, TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 = 0xC02A, /* Addenda from rfc 5289 Elliptic Curve Cipher Suites with SHA-256/384 and AES Galois Counter Mode (GCM ) */ TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 = 0xC02B, TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 = 0xC02C, TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 = 0xC02D, TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 = 0xC02E, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 = 0xC02F, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 = 0xC030, TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 = 0xC031, TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 = 0xC032, /* RFC 5746 - Secure Renegotiation */ TLS_EMPTY_RENEGOTIATION_INFO_SCSV = 0x00FF, /* * Tags for SSL 2 cipher kinds that are not specified * for SSL 3. */ SSL_RSA_WITH_RC2_CBC_MD5 = 0xFF80, SSL_RSA_WITH_IDEA_CBC_MD5 = 0xFF81, SSL_RSA_WITH_DES_CBC_MD5 = 0xFF82, SSL_RSA_WITH_3DES_EDE_CBC_MD5 = 0xFF83, SSL_NO_SUCH_CIPHERSUITE = 0xFFFF };

    Constants

    • SSL_RSA_EXPORT_WITH_RC4_40_MD5

      SSL_RSA_EXPORT_WITH_RC4_40_MD5

      Session key size conforms to pre-1998 US export restrictions.

      Available in OS X v10.2 and later.

    • SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5

      SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5

      Session key size conforms to pre-1998 US export restrictions.

      Available in OS X v10.2 and later.

    • SSL_RSA_EXPORT_WITH_DES40_CBC_SHA

      SSL_RSA_EXPORT_WITH_DES40_CBC_SHA

      Session key size conforms to pre-1998 US export restrictions.

      Available in OS X v10.2 and later.

    • SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA

      SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA

      Session key size conforms to pre-1998 US export restrictions.

      Available in OS X v10.2 and later.

    • SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA

      SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA

      Session key size conforms to pre-1998 US export restrictions.

      Available in OS X v10.2 and later.

    • SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA

      SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA

      Session key size conforms to pre-1998 US export restrictions.

      Available in OS X v10.2 and later.

    • SSL_DH_anon_EXPORT_WITH_RC4_40_MD5

      SSL_DH_anon_EXPORT_WITH_RC4_40_MD5

      Session key size conforms to pre-1998 US export restrictions.

      Available in OS X v10.2 and later.

    • SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA

      SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA

      Session key size conforms to pre-1998 US export restrictions.

      Available in OS X v10.2 and later.

    • SSL_RSA_WITH_RC2_CBC_MD5

      SSL_RSA_WITH_RC2_CBC_MD5

      This value can be specified for SSL 2 but not SSL 3.

      Available in OS X v10.2 and later.

    • SSL_RSA_WITH_IDEA_CBC_MD5

      SSL_RSA_WITH_IDEA_CBC_MD5

      This value can be specified for SSL 2 but not SSL 3.

      Available in OS X v10.2 and later.

    • SSL_RSA_WITH_DES_CBC_MD5

      SSL_RSA_WITH_DES_CBC_MD5

      This value can be specified for SSL 2 but not SSL 3.

      Available in OS X v10.2 and later.

    • SSL_RSA_WITH_3DES_EDE_CBC_MD5

      SSL_RSA_WITH_3DES_EDE_CBC_MD5

      This value can be specified for SSL 2 but not SSL 3.

      Available in OS X v10.2 and later.

    Discussion

    These cipher suite constants are part of the TLS specification. For more information, see RFC 5246.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Represents the status of client certificate exchange.

    Declaration

    Swift

    struct SSLClientCertificateState { init(_ value: UInt32) var value: UInt32 }

    Objective-C

    typedef enum { kSSLClientCertNone, kSSLClientCertRequested, kSSLClientCertSent, kSSLClientCertRejected } SSLClientCertificateState;

    Constants

    • kSSLClientCertNone

      kSSLClientCertNone

      Indicates that the server hasn’t asked for a certificate and that the client hasn’t sent one.

      Available in OS X v10.2 and later.

    • kSSLClientCertRequested

      kSSLClientCertRequested

      Indicates that the server has asked for a certificate, but the client has not sent it.

      Available in OS X v10.2 and later.

    • kSSLClientCertSent

      kSSLClientCertSent

      Indicates that the server asked for a certificate, the client sent one, and the server validated it. The application can inspect the certificate using the function SSLGetPeerCertificates.

      Available in OS X v10.2 and later.

    • kSSLClientCertRejected

      kSSLClientCertRejected

      Indicates that the client sent a certificate but the certificate failed validation. This value is seen only on the server side. The server application can inspect the certificate using the function SSLGetPeerCertificates.

      Available in OS X v10.2 and later.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Represents the SSL protocol version.

    Declaration

    Swift

    struct SSLProtocol { init(_ value: UInt32) var value: UInt32 }

    Objective-C

    typedef enum { kSSLProtocolUnknown = 0, kSSLProtocol3 = 2, kTLSProtocol1 = 4, kTLSProtocol11 = 7, kTLSProtocol12 = 8, kDTLSProtocol1 = 9, /* DEPRECATED on iOS */ kSSLProtocol2 = 1, kSSLProtocol3Only = 3, kTLSProtocol1Only = 5, kSSLProtocolAll = 6, } SSLProtocol;

    Constants

    • kSSLProtocolUnknown

      kSSLProtocolUnknown

      Specifies that no protocol has been or should be negotiated or specified; use default.

      Available in OS X v10.2 and later.

    • kSSLProtocol3

      kSSLProtocol3

      Specifies that the SSL 3.0 protocol is preferred; the SSL 2.0 protocol may be negotiated if the peer cannot use the SSL 3.0 protocol.

      Available in OS X v10.2 and later.

    • kTLSProtocol1

      kTLSProtocol1

      Specifies that the TLS 1.0 protocol is preferred but lower versions may be negotiated.

      Available in OS X v10.2 and later.

    • kTLSProtocol11

      kTLSProtocol11

      Specifies that the TLS 1.1 protocol is preferred but lower versions may be negotiated.

      Available in OS X v10.8 and later.

    • kTLSProtocol12

      kTLSProtocol12

      Specifies that the TLS 1.2 protocol is preferred but lower versions may be negotiated.

      Available in OS X v10.8 and later.

    • kSSLProtocol2

      kSSLProtocol2

      Specifies that only the SSL 2.0 protocol may be negotiated. Deprecated in iOS.

      Available in OS X v10.2 and later.

    • kSSLProtocol3Only

      kSSLProtocol3Only

      Specifies that only the SSL 3.0 protocol may be negotiated; fails if the peer tries to negotiate the SSL 2.0 protocol. Deprecated in iOS.

      Available in OS X v10.2 and later.

    • kTLSProtocol1Only

      kTLSProtocol1Only

      Specifies that only the TLS 1.0 protocol may be negotiated. Deprecated in iOS.

      Available in OS X v10.2 and later.

    • kSSLProtocolAll

      kSSLProtocolAll

      Specifies all supported versions. Deprecated in iOS.

      Available in OS X v10.3 and later.

    Discussion

    The descriptions given here apply to the functions SSLSetProtocolVersion and SSLGetProtocolVersion. For the functions SSLSetProtocolVersionEnabled and SSLGetProtocolVersionEnabled, only the following values are used. For these functions, each constant except kSSLProtocolAll specifies a single protocol version.

    • kSSLProtocol2

    • kSSLProtocol3

    • kTLSProtocol1

    • kSSLProtocolAll

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Represents the state of an SSL session.

    Declaration

    Swift

    struct SSLSessionState { init(_ value: UInt32) var value: UInt32 }

    Objective-C

    typedef enum { kSSLIdle, kSSLHandshake, kSSLConnected, kSSLClosed, kSSLAborted } SSLSessionState;

    Constants

    • kSSLIdle

      kSSLIdle

      No I/O has been performed yet.

      Available in OS X v10.2 and later.

    • kSSLHandshake

      kSSLHandshake

      The SSL handshake is in progress.

      Available in OS X v10.2 and later.

    • kSSLConnected

      kSSLConnected

      The SSL handshake is complete; the connection is ready for normal I/O.

      Available in OS X v10.2 and later.

    • kSSLClosed

      kSSLClosed

      The connection closed normally.

      Available in OS X v10.2 and later.

    • kSSLAborted

      kSSLAborted

      The connection aborted.

      Available in OS X v10.2 and later.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.2 and later.

  • Options that can be set for an SSL session with the SSLSetSessionOption function.

    Declaration

    Swift

    struct SSLSessionOption { init(_ value: UInt32) var value: UInt32 }

    Objective-C

    typedef enum { kSSLSessionOptionBreakOnServerAuth, kSSLSessionOptionBreakOnCertRequested, kSSLSessionOptionBreakOnClientAuth, kSSLSessionOptionFalseStart, kSSLSessionOptionSendOneByteRecord } SSLSessionOption;

    Constants

    • kSSLSessionOptionBreakOnServerAuth

      kSSLSessionOptionBreakOnServerAuth

      Enables returning from SSLHandshake (with a result of errSSLServerAuthCompleted) when the server authentication portion of the handshake is complete to allow your application to perform its own certificate verification.

      Note that in iOS (all versions) and OS X 10.8 and later, setting this option disables Secure Transport's automatic verification of server certificates.

      If you set this option, your application should perform its own certificate verification when errSSLServerAuthCompleted is returned before continuing with the handshake.

      Available in OS X v10.6 and later.

    • kSSLSessionOptionBreakOnCertRequested

      kSSLSessionOptionBreakOnCertRequested

      Enables returning from SSLHandshake (with a result of errSSLClientCertRequested) when the server requests a client certificate.

      Available in OS X v10.6 and later.

    • kSSLSessionOptionBreakOnClientAuth

      kSSLSessionOptionBreakOnClientAuth

      Enables returning from SSLHandshake (with a result of errSSLClientAuthCompleted) when the client authentication portion of the handshake is complete to allow your application to perform its own certificate verification.

      Note that in iOS (all versions) and OS X 10.8 and later, setting this option disables Secure Transport's automatic verification of client certificates.

      If you set this option, your application should perform its own certificate verification when errSSLClientAuthCompleted is returned before continuing with the handshake.

      Available in OS X v10.8 and later.

    • kSSLSessionOptionFalseStart

      kSSLSessionOptionFalseStart

      When enabled, TLS False Start is used if an adequate cipher-suite is negotiated.

      Available in OS X v10.9 and later.

    • kSSLSessionOptionSendOneByteRecord

      kSSLSessionOptionSendOneByteRecord

      Enables 1/n-1 record splitting for BEAST attack mitigation. When enabled, record splitting is performed only for TLS 1.0 connections based on a block cipher.

      Available in OS X v10.9 and later.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.6 and later.

  • Specifies whether a new SSL context created by SSLCreateContext should describe the server side or client side of a connection.

    Declaration

    Swift

    struct SSLProtocolSide { init(_ value: UInt32) var value: UInt32 }

    Objective-C

    typedef enum { kSSLServerSide, kSSLClientSide } SSLProtocolSide;

    Constants

    • kSSLServerSide

      kSSLServerSide

      Server side.

      Available in OS X v10.8 and later.

    • kSSLClientSide

      kSSLClientSide

      Client side.

      Available in OS X v10.8 and later.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.8 and later.

  • Specifies whether a new SSL context created by SSLCreateContext is intended for use in stream-based or datagram-based communication.

    Declaration

    Swift

    struct SSLConnectionType { init(_ value: UInt32) var value: UInt32 }

    Objective-C

    typedef enum { kSSLStreamType, kSSLDatagramType } SSLConnectionType;

    Constants

    • kSSLStreamType

      kSSLStreamType

      Stream-based communication (TCP).

      Available in OS X v10.8 and later.

    • kSSLDatagramType

      kSSLDatagramType

      Datagram-based communication (UDP).

      Available in OS X v10.8 and later.

    Import Statement

    Objective-C

    @import Security;

    Swift

    import Security

    Availability

    Available in OS X v10.8 and later.

Result Codes

The most common result codes returned by Secure Transport functions are listed in the table below.

Errors in the range of –9819 through –9840 are fatal errors that are detected by the peer.

  • SSL protocol error.

    Value

    –9800

    Description

    SSL protocol error.

    Available in OS X v10.2 and later.

  • The cipher suite negotiation failed.

    Value

    –9801

    Description

    The cipher suite negotiation failed.

    Available in OS X v10.2 and later.

  • A fatal alert was encountered.

    Value

    –9802

    Description

    A fatal alert was encountered.

    Available in OS X v10.2 and later.

  • Function is blocked; waiting for I/O. This is not fatal.

    Value

    –9803

    Description

    Function is blocked; waiting for I/O. This is not fatal.

    Available in OS X v10.2 and later.

  • An attempt to restore an unknown session failed.

    Value

    –9804

    Description

    An attempt to restore an unknown session failed.

    Available in OS X v10.2 and later.

  • The connection closed gracefully.

    Value

    –9805

    Description

    The connection closed gracefully.

    Available in OS X v10.2 and later.

  • The connection closed due to an error.

    Value

    –9806

    Description

    The connection closed due to an error.

    Available in OS X v10.2 and later.

  • Invalid certificate chain.

    Value

    –9807

    Description

    Invalid certificate chain.

    Available in OS X v10.2 and later.

  • Bad certificate format.

    Value

    –9808

    Description

    Bad certificate format.

    Available in OS X v10.2 and later.

  • An underlying cryptographic error was encountered.

    Value

    –9809

    Description

    An underlying cryptographic error was encountered.

    Available in OS X v10.2 and later.

  • Internal error.

    Value

    –9810

    Description

    Internal error.

    Available in OS X v10.2 and later.

  • Module attach failure.

    Value

    –9811

    Description

    Module attach failure.

    Available in OS X v10.2 and later.

  • Certificate chain is valid, but root is not trusted.

    Value

    –9812

    Description

    Certificate chain is valid, but root is not trusted.

    Available in OS X v10.2 and later.

  • No root certificate for the certificate chain.

    Value

    –9813

    Description

    No root certificate for the certificate chain.

    Available in OS X v10.2 and later.

  • The certificate chain had an expired certificate.

    Value

    –9814

    Description

    The certificate chain had an expired certificate.

    Available in OS X v10.2 and later.

  • The certificate chain had a certificate that is not yet valid.

    Value

    –9815

    Description

    The certificate chain had a certificate that is not yet valid.

    Available in OS X v10.2 and later.

  • The server closed the session with no notification.

    Value

    –9816

    Description

    The server closed the session with no notification.

    Available in OS X v10.2 and later.

  • An insufficient buffer was provided.

    Value

    –9817

    Description

    An insufficient buffer was provided.

    Available in OS X v10.2 and later.

  • A bad SSL cipher suite was encountered.

    Value

    –9818

    Description

    A bad SSL cipher suite was encountered.

    Available in OS X v10.2 and later.

  • An unexpected message was received.

    Value

    –9819

    Description

    An unexpected message was received.

    Available in OS X v10.3 and later.

  • A record with a bad message authentication code (MAC) was encountered.

    Value

    –9820

    Description

    A record with a bad message authentication code (MAC) was encountered.

    Available in OS X v10.3 and later.

  • Decryption failed.

    Value

    –9821

    Description

    Decryption failed.

    Available in OS X v10.3 and later.

  • A record overflow occurred.

    Value

    –9822

    Description

    A record overflow occurred.

    Available in OS X v10.3 and later.

  • Decompression failed.

    Value

    –9823

    Description

    Decompression failed.

    Available in OS X v10.3 and later.

  • The handshake failed.

    Value

    –9824

    Description

    The handshake failed.

    Available in OS X v10.3 and later.

  • A bad certificate was encountered.

    Value

    –9825

    Description

    A bad certificate was encountered.

    Available in OS X v10.3 and later.

  • An unsupported certificate format was encountered.

    Value

    –9826

    Description

    An unsupported certificate format was encountered.

    Available in OS X v10.3 and later.

  • The certificate was revoked.

    Value

    –9827

    Description

    The certificate was revoked.

    Available in OS X v10.3 and later.

  • The certificate expired.

    Value

    –9828

    Description

    The certificate expired.

    Available in OS X v10.3 and later.

  • The certificate is unknown.

    Value

    –9829

    Description

    The certificate is unknown.

    Available in OS X v10.3 and later.

  • An illegal parameter was encountered.

    Value

    –9830

    Description

    An illegal parameter was encountered.

    Available in OS X v10.3 and later.

  • An unknown certificate authority was encountered.

    Value

    –9831

    Description

    An unknown certificate authority was encountered.

    Available in OS X v10.3 and later.

  • Access was denied.

    Value

    –9832

    Description

    Access was denied.

    Available in OS X v10.3 and later.

  • A decoding error occurred.

    Value

    –9833

    Description

    A decoding error occurred.

    Available in OS X v10.3 and later.

  • A decryption error occurred.

    Value

    –9834

    Description

    A decryption error occurred.

    Available in OS X v10.3 and later.

  • An export restriction occurred.

    Value

    –9835

    Description

    An export restriction occurred.

    Available in OS X v10.3 and later.

  • A bad protocol version was encountered.

    Value

    –9836

    Description

    A bad protocol version was encountered.

    Available in OS X v10.3 and later.

  • There is insufficient security for this operation.

    Value

    –9837

    Description

    There is insufficient security for this operation.

    Available in OS X v10.3 and later.

  • An internal error occurred.

    Value

    –9838

    Description

    An internal error occurred.

    Available in OS X v10.3 and later.

  • The user canceled the operation.

    Value

    –9839

    Description

    The user canceled the operation.

    Available in OS X v10.3 and later.

  • No renegotiation is allowed.

    Value

    –9840

    Description

    No renegotiation is allowed.

    Available in OS X v10.3 and later.

  • The server certificate is either valid or was ignored if verification is disabled.

    Value

    -9841

    Description

    The server certificate is either valid or was ignored if verification is disabled.

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

  • The server has requested a client certificate.

    Value

    -9842

    Description

    The server has requested a client certificate.

    Available in OS X v10.6 and later.

  • The host name you connected with does not match any of the host names allowed by the certificate. This is commonly caused by an incorrect value for the kCFStreamSSLPeerName property within the dictionary associated with the stream’s kCFStreamPropertySSLSettings key.

    Value

    -9843

    Description

    The host name you connected with does not match any of the host names allowed by the certificate. This is commonly caused by an incorrect value for the kCFStreamSSLPeerName property within the dictionary associated with the stream’s kCFStreamPropertySSLSettings key.

    Available in OS X v10.4 and later.

  • The peer dropped the connection before responding.

    Value

    –9844

    Description

    The peer dropped the connection before responding.

    Available in OS X v10.4 and later.

  • Decryption failed. Among other causes, this may be caused by invalid data coming from the remote host, a damaged crypto key, or insufficient permission to use a key that is stored in the keychain.

    Value

    –9845

    Description

    Decryption failed. Among other causes, this may be caused by invalid data coming from the remote host, a damaged crypto key, or insufficient permission to use a key that is stored in the keychain.

    Available in OS X v10.3 and later.

  • A record with a bad message authentication code (MAC) was encountered.

    Value

    –9846

    Description

    A record with a bad message authentication code (MAC) was encountered.

    Available in OS X v10.3 and later.

  • A record overflow occurred.

    Value

    –9847

    Description

    A record overflow occurred.

    Available in OS X v10.3 and later.

  • A configuration error occurred.

    Value

    –9848

    Description

    A configuration error occurred.

    Available in OS X v10.3 and later.