Secure Transport Reference

Framework
Security/Security.h
Declared in
CipherSuite.h
SecureTransport.h

Overview

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:

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 by Task

Configuring an SSL Session

Managing an SSL Session

Managing Ciphers

Managing Certificates

Managing the Peer Domain Name

iOS-Specific SSL Context Functions

Functions

SSLAddDistinguishedName

Unsupported.

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.

Availability
  • Unsupported.
Declared In
SecureTransport.h

SSLClose

Terminates the current SSL session.

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

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLContextGetTypeID

Returns the CFTypeID for SSLContext objects

CFTypeID SSLContextGetTypeID (
   void
);
Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLCopyDistinguishedNames

Retrieves the distinguished names of acceptable certification authorities.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLCopyPeerTrust

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

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLCreateContext

Allocates and returns a new SSLContextRef object.

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

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

protocolSide

Either kSSLServerSide or kSSLClientSide.

connectionType

Either kSSLStreamType or kSSLDatagramType.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetBufferedReadSize

Determines how much data is available to be read.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetClientCertificateState

Retrieves the exchange status of the client certificate.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetConnection

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

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetDatagramWriteSize

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

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetEnabledCiphers

Determines which SSL cipher suites are currently enabled.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetMaxDatagramRecordSize

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

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

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetNegotiatedCipher

Retrieves the cipher suite negotiated for this session.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetNegotiatedProtocolVersion

Obtains the negotiated protocol version of the active session.

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

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetNumberEnabledCiphers

Determines the number of cipher suites currently enabled.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetNumberSupportedCiphers

Determines the number of cipher suites supported.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetPeerDomainName

Retrieves the peer domain name specified previously.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetPeerDomainNameLength

Determines the length of a previously set peer domain name.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetPeerID

Retrieves the current peer ID data.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetProtocolVersionMax

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

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetProtocolVersionMin

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

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetSessionOption

Indicates the current setting of an SSL session option.

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

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetSessionState

Retrieves the state of an SSL session.

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

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLGetSupportedCiphers

Determines the values of the supported cipher suites.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLHandshake

Performs the SSL handshake.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLRead

Performs a normal application-level read operation.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLSetCertificate

Specifies this connection’s certificate or certificates.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLSetClientSideAuthenticate

Specifies the requirements for client-side authentication.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLSetConnection

Specifies an I/O connection for a specific session.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLSetDatagramHelloCookie

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

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLSetEnabledCiphers

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

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLSetEncryptionCertificate

Specifies the encryption certificates used for this connection.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLSetIOFuncs

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

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLSetMaxDatagramRecordSize

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

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

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLSetPeerDomainName

Specifies the fully qualified domain name of the peer.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLSetPeerID

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

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLSetProtocolVersionMax

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

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLSetProtocolVersionMin

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

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLSetSessionOption

Specifies an option for a specific session.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLWrite

Performs a normal application-level write operation.

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

Callbacks

SSLReadFunc

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

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

You would declare your callback function like this if you were to name it MySSLReadFunction:

OSStatus MySSLReadFunction (
   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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLWriteFunc

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

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

You would declare your callback function like this if you were to name it MySSLWriteFunction:

OSStatus MySSLWriteFunction (
   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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

Data Types

SSLConnectionRef

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

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
SecureTransport.h

SSLContextRef

Represents a pointer to an opaque SSL session context object.

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 iOS 5.0 and later.
Declared In
SecureTransport.h

Constants

SSL Authentication Constants

Represents the requirements for client-side authentication.

typedef enum {
   kNeverAuthenticate,
   kAlwaysAuthenticate,
   kTryAuthenticate
} SSLAuthenticate;
Constants
kNeverAuthenticate

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

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

kAlwaysAuthenticate

Indicates that client-side authentication is required.

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

kTryAuthenticate

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

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

SSL Cipher Suite Constants

Represents the cipher suites available.

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

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

Available in iOS 5.0 and later.

Declared in CipherSuite.h.

SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5

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

Available in iOS 5.0 and later.

Declared in CipherSuite.h.

SSL_RSA_EXPORT_WITH_DES40_CBC_SHA

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

Available in iOS 5.0 and later.

Declared in CipherSuite.h.

SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA

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

Available in iOS 5.0 and later.

Declared in CipherSuite.h.

SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA

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

Available in iOS 5.0 and later.

Declared in CipherSuite.h.

SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA

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

Available in iOS 5.0 and later.

Declared in CipherSuite.h.

SSL_DH_anon_EXPORT_WITH_RC4_40_MD5

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

Available in iOS 5.0 and later.

Declared in CipherSuite.h.

SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA

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

Available in iOS 5.0 and later.

Declared in CipherSuite.h.

SSL_RSA_WITH_RC2_CBC_MD5

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

Available in iOS 5.0 and later.

Declared in CipherSuite.h.

SSL_RSA_WITH_IDEA_CBC_MD5

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

Available in iOS 5.0 and later.

Declared in CipherSuite.h.

SSL_RSA_WITH_DES_CBC_MD5

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

Available in iOS 5.0 and later.

Declared in CipherSuite.h.

SSL_RSA_WITH_3DES_EDE_CBC_MD5

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

Available in iOS 5.0 and later.

Declared in CipherSuite.h.

Discussion

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

SSL Client Certificate State Constants

Represents the status of client certificate exchange.

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

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

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

kSSLClientCertRequested

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

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

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 iOS 5.0 and later.

Declared in SecureTransport.h.

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 iOS 5.0 and later.

Declared in SecureTransport.h.

SSL Protocol Constants

Represents the SSL protocol version.

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

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

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

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 iOS 5.0 and later.

Declared in SecureTransport.h.

kTLSProtocol1

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

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

kTLSProtocol11

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

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

kTLSProtocol12

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

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

kSSLProtocol2

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

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

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 iOS 5.0 and later.

Declared in SecureTransport.h.

kTLSProtocol1Only

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

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

kSSLProtocolAll

Specifies all supported versions. Deprecated in iOS.

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

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

SSL Session State Constants

Represents the state of an SSL session.

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

No I/O has been performed yet.

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

kSSLHandshake

The SSL handshake is in progress.

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

kSSLConnected

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

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

kSSLClosed

The connection closed normally.

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

kSSLAborted

The connection aborted.

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

SSL Session Options

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

typedef enum {
   kSSLSessionOptionBreakOnServerAuth,
   kSSLSessionOptionBreakOnCertRequested,
   kSSLSessionOptionBreakOnClientAuth,
   kSSLSessionOptionFalseStart,
   kSSLSessionOptionSendOneByteRecord
} SSLSessionOption;
Constants
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 iOS 5.0 and later.

Declared in SecureTransport.h.

kSSLSessionOptionBreakOnCertRequested

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

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

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 iOS 5.0 and later.

Declared in SecureTransport.h.

kSSLSessionOptionFalseStart

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

Available in iOS 7.0 and later.

Declared in SecureTransport.h.

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 iOS 7.0 and later.

Declared in SecureTransport.h.

Protocol Side Constants

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

typedef enum
{
   kSSLServerSide,
   kSSLClientSide
} SSLProtocolSide;
Constants
kSSLServerSide

Server side.

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

kSSLClientSide

Client side.

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

Connection Type Constants

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

typedef enum
{
   kSSLStreamType,
   kSSLDatagramType
} SSLConnectionType;
Constants
kSSLStreamType

Stream-based communication (TCP).

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

kSSLDatagramType

Datagram-based communication (UDP).

Available in iOS 5.0 and later.

Declared in SecureTransport.h.

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.

Result CodeValueDescription
errSSLProtocol –9800

SSL protocol error.

Available in iOS 5.0 and later.

errSSLNegotiation –9801

The cipher suite negotiation failed.

Available in iOS 5.0 and later.

errSSLFatalAlert –9802

A fatal alert was encountered.

Available in iOS 5.0 and later.

errSSLWouldBlock –9803

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

Available in iOS 5.0 and later.

errSSLSessionNotFound –9804

An attempt to restore an unknown session failed.

Available in iOS 5.0 and later.

errSSLClosedGraceful –9805

The connection closed gracefully.

Available in iOS 5.0 and later.

errSSLClosedAbort –9806

The connection closed due to an error.

Available in iOS 5.0 and later.

errSSLXCertChainInvalid –9807

Invalid certificate chain.

Available in iOS 5.0 and later.

errSSLBadCert –9808

Bad certificate format.

Available in iOS 5.0 and later.

errSSLCrypto –9809

An underlying cryptographic error was encountered.

Available in iOS 5.0 and later.

errSSLInternal –9810

Internal error.

Available in iOS 5.0 and later.

errSSLModuleAttach –9811

Module attach failure.

Available in iOS 5.0 and later.

errSSLUnknownRootCert –9812

Certificate chain is valid, but root is not trusted.

Available in iOS 5.0 and later.

errSSLNoRootCert –9813

No root certificate for the certificate chain.

Available in iOS 5.0 and later.

errSSLCertExpired –9814

The certificate chain had an expired certificate.

Available in iOS 5.0 and later.

errSSLCertNotYetValid –9815

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

Available in iOS 5.0 and later.

errSSLClosedNoNotify –9816

The server closed the session with no notification.

Available in iOS 5.0 and later.

errSSLBufferOverflow –9817

An insufficient buffer was provided.

Available in iOS 5.0 and later.

errSSLBadCipherSuite –9818

A bad SSL cipher suite was encountered.

Available in iOS 5.0 and later.

errSSLPeerUnexpectedMsg –9819

An unexpected message was received.

Available in iOS 5.0 and later.

errSSLPeerBadRecordMac –9820

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

Available in iOS 5.0 and later.

errSSLPeerDecryptionFail –9821

Decryption failed.

Available in iOS 5.0 and later.

errSSLPeerRecordOverflow –9822

A record overflow occurred.

Available in iOS 5.0 and later.

errSSLPeerDecompressFail –9823

Decompression failed.

Available in iOS 5.0 and later.

errSSLPeerHandshakeFail –9824

The handshake failed.

Available in iOS 5.0 and later.

errSSLPeerBadCert –9825

A bad certificate was encountered.

Available in iOS 5.0 and later.

errSSLPeerUnsupportedCert –9826

An unsupported certificate format was encountered.

Available in iOS 5.0 and later.

errSSLPeerCertRevoked –9827

The certificate was revoked.

Available in iOS 5.0 and later.

errSSLPeerCertExpired –9828

The certificate expired.

Available in iOS 5.0 and later.

errSSLPeerCertUnknown –9829

The certificate is unknown.

Available in iOS 5.0 and later.

errSSLIllegalParam –9830

An illegal parameter was encountered.

Available in iOS 5.0 and later.

errSSLPeerUnknownCA –9831

An unknown certificate authority was encountered.

Available in iOS 5.0 and later.

errSSLPeerAccessDenied –9832

Access was denied.

Available in iOS 5.0 and later.

errSSLPeerDecodeError –9833

A decoding error occurred.

Available in iOS 5.0 and later.

errSSLPeerDecryptError –9834

A decryption error occurred.

Available in iOS 5.0 and later.

errSSLPeerExportRestriction –9835

An export restriction occurred.

Available in iOS 5.0 and later.

errSSLPeerProtocolVersion –9836

A bad protocol version was encountered.

Available in iOS 5.0 and later.

errSSLPeerInsufficientSecurity –9837

There is insufficient security for this operation.

Available in iOS 5.0 and later.

errSSLPeerInternalError –9838

An internal error occurred.

Available in iOS 5.0 and later.

errSSLPeerUserCancelled –9839

The user canceled the operation.

Available in iOS 5.0 and later.

errSSLPeerNoRenegotiation –9840

No renegotiation is allowed.

Available in iOS 5.0 and later.

errSSLServerAuthCompleted-9841

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

Available in iOS 5.0 through iOS 6.1.

errSSLClientCertRequested-9842

The server has requested a client certificate.

Available in iOS 5.0 and later.

errSSLHostNameMismatch-9843

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 iOS 5.0 and later.

errSSLConnectionRefused –9844

The peer dropped the connection before responding.

Available in iOS 5.0 and later.

errSSLDecryptionFail –9845

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 iOS 5.0 and later.

errSSLBadRecordMac –9846

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

Available in iOS 5.0 and later.

errSSLRecordOverflow –9847

A record overflow occurred.

Available in iOS 5.0 and later.

errSSLBadConfiguration –9848

A configuration error occurred.

Available in iOS 5.0 and later.