Framework | Security/Security.h |
Declared in | CipherSuite.h SecureTransport.h |
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:
Preparing for a session
Call SSLNewContext
to create a new SSL session context.
Write I/O functions and call SSLSetIOFuncs
to pass them to Secure Transpport.
Establish a connection using CFNetwork, BSD Sockets, or Open Transport. Then call SSLSetConnection
to specify the connection to which the SSL session context applies.
Call SSLSetPeerDomainName
to specify the fully-qualified domain name of the peer to which you want to connect (optional but highly recommended).
Call SSLSetCertificate
to specify the certificate to be used in authentication (required for server side, optional for client).
Starting a session
Call SSLHandshake
to perform the SSL handshake and establish a secure session.
Maintaining the session
Ending a session
Call SSLClose
to close the secure session.
Close the connection and dispose of the connection reference (SSLConnectionRef
).
Call SSLDisposeContext
to dispose of the SSL session context.
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.
SSLSetConnection
SSLGetConnection
SSLSetIOFuncs
SSLSetProtocolVersionEnabled
SSLGetProtocolVersionEnabled
SSLSetClientSideAuthenticate
SSLSetRsaBlinding
SSLGetRsaBlinding
SSLHandshake
SSLGetSessionState
SSLGetNegotiatedProtocolVersion
SSLSetPeerID
SSLGetPeerID
SSLGetBufferedReadSize
SSLRead
SSLWrite
SSLClose
SSLGetNumberSupportedCiphers
SSLGetSupportedCiphers
SSLSetEnabledCiphers
SSLGetNumberEnabledCiphers
SSLGetEnabledCiphers
SSLGetNegotiatedCipher
SSLSetDiffieHellmanParams
SSLGetDiffieHellmanParams
SSLSetAllowsAnyRoot
SSLGetAllowsAnyRoot
SSLSetAllowsExpiredRoots
SSLGetAllowsExpiredRoots
SSLSetTrustedRoots
SSLGetTrustedRoots
Deprecated in Mac OS X v10.5
SSLAddDistinguishedName
SSLSetAllowsExpiredCerts
SSLGetAllowsExpiredCerts
SSLSetCertificate
SSLGetClientCertificateState
SSLSetEnableCertVerify
SSLGetEnableCertVerify
SSLSetEncryptionCertificate
SSLGetPeerCertificates
Deprecated in Mac OS X v10.5
Unsupported.
OSStatus SSLAddDistinguishedName ( SSLContextRef context, const void *derDN, size_t derDNLen );
An SSL session context reference.
A pointer to a buffer containing a DER-encoded distinguished name.
A value of type size_t
representing
the size of the buffer pointed to by the parameter derDN.
A result code. See “Secure Transport Result Codes.”
This function has not been implemented and is unsupported at this time.
SecureTransport.h
Terminates the current SSL session.
OSStatus SSLClose ( SSLContextRef context );
The SSL session context reference of the session you want to terminate.
A result code. See “Secure Transport Result Codes.”
SecureTransport.h
Disposes of an SSL session context.
OSStatus SSLDisposeContext ( SSLContextRef context );
A reference to the SSL session context to dispose.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Obtains a value specifying whether an unknown root is allowed.
OSStatus SSLGetAllowsAnyRoot ( SSLContextRef context, Boolean *anyRoot );
An SSL session context reference.
On return, a Boolean indicating the current
setting of the anyRoot
flag.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Retrieves the value specifying whether expired certificates are allowed.
OSStatus SSLGetAllowsExpiredCerts ( SSLContextRef context, Boolean *allowsExpired );
An SSL session context reference.
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.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Retrieves the value indicating whether expired roots are allowed.
OSStatus SSLGetAllowsExpiredRoots ( SSLContextRef context, Boolean *allowsExpired );
An SSL session context reference.
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.
A result code. See “Secure Transport Result Codes.”
Use the SSLSetAllowsExpiredRoots
function to
change the setting of the allowsExpired
flag.
SecureTransport.h
Determines how much data is available to be read.
OSStatus SSLGetBufferedReadSize ( SSLContextRef context, size_t *bufSize );
An SSL session context reference.
On return, the size of the data to be read.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Retrieves the exchange status of the client certificate.
OSStatus SSLGetClientCertificateState ( SSLContextRef context, SSLClientCertificateState *clientState );
An SSL session context reference.
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.
A result code. See “Secure Transport Result Codes.”
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
.
SecureTransport.h
Retrieves an I/O connection—such as a socket or endpoint—for a specific session.
OSStatus SSLGetConnection ( SSLContextRef context, SSLConnectionRef *connection );
An SSL session context reference.
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.
A result code. See “Secure Transport Result Codes.”
You can use this function on either the client or server to retrieve the connection associated with a secure session.
SecureTransport.h
Retrieves the Diffie-Hellman parameters specified earlier.
OSStatus SSLGetDiffieHellmanParams ( SSLContextRef context, const void **dhParams, size_t *dhParamsLen );
An SSL session context reference.
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.
On return, points to the length of the buffer pointed to by the dhParams parameter.
A result code. See “Secure Transport Result Codes.”
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
.
SecureTransport.h
Determines whether peer certificate chain validation is currently enabled.
OSStatus SSLGetEnableCertVerify ( SSLContextRef context, Boolean *enableVerify );
An SSL session context reference.
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.
A result code. See “Secure Transport Result Codes.”
Use the SSLSetEnableCertVerify
function to set
the value of the enableVerify
flag.
SecureTransport.h
Determines which SSL cipher suites are currently enabled.
OSStatus SSLGetEnabledCiphers ( SSLContextRef context, SSLCipherSuite *ciphers, size_t *numCiphers );
An SSL session context reference.
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.
Pointer to the number of enabled cipher suites.
Before calling, retrieve this value by calling the SSLGetNumberEnabledCiphers
function.
A result code. See “Secure Transport Result Codes.” If the supplied buffer is too small, errSSLBufferOverflow
is
returned.
Call the SSLSetEnabledCiphers
function
to specify which SSL cipher suites are enabled.
SecureTransport.h
Retrieves the cipher suite negotiated for this session.
OSStatus SSLGetNegotiatedCipher ( SSLContextRef context, SSLCipherSuite *cipherSuite );
An SSL session context reference.
On return, points to the cipher suite that was negotiated for this session.
A result code. See “Secure Transport Result Codes.”
You should call this function only when a session is active.
SecureTransport.h
Obtains the negotiated protocol version of the active session.
OSStatus SSLGetNegotiatedProtocolVersion ( SSLContextRef context, SSLProtocol *protocol );
An SSL session context reference.
On return, points to the negotiated protocol version of the active session.
A result code. See “Secure Transport Result Codes.” This function returns kSSLProtocolUnknown
if
no SSL session is in progress.
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
SecureTransport.h
Determines the number of cipher suites currently enabled.
OSStatus SSLGetNumberEnabledCiphers ( SSLContextRef context, size_t *numCiphers );
An SSL session context reference.
On return, points to the number of enabled cipher suites.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Determines the number of cipher suites supported.
OSStatus SSLGetNumberSupportedCiphers ( SSLContextRef context, size_t *numCiphers );
An SSL session context reference.
On return, points to the number of supported cipher suites.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Retrieves the peer domain name specified previously.
OSStatus SSLGetPeerDomainName ( SSLContextRef context, char *peerName, size_t *peerNameLen );
An SSL session context reference.
On return, points to the peer domain name.
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
.
A result code. See “Secure Transport Result Codes.”
If you previouslly 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.
SecureTransport.h
Determines the length of a previously set peer domain name.
OSStatus SSLGetPeerDomainNameLength ( SSLContextRef context, size_t *peerNameLen );
An SSL session context reference.
On return, points to the length of the peer domain name.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Retrieves the current peer ID data.
OSStatus SSLGetPeerID ( SSLContextRef context, const void **peerID, size_t *peerIDLen );
An SSL session context reference.
On return, points to a buffer containing the peer ID data.
On return, the length of the peer ID data buffer.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Gets the SSL protocol version. This function is deprecated.
OSStatus SSLGetProtocolVersion ( SSLContextRef context, SSLProtocol *protocol );
An SSL session context reference.
On return, a pointer to the SSL protocol version.
A result code. See “Secure Transport Result Codes.”
Use the SSLGetProtocolVersionEnabled
function
instead.
SecureTransport.h
Retrieves the enabled status of a given protocol.
OSStatus SSLGetProtocolVersionEnabled ( SSLContextRef context, SSLProtocol protocol, Boolean *enable );
An SSL session context reference.
A value of type SSLProtocol
representing
an SSL protocol version.
On return, points to a Boolean value indicating
whether the specified protocol version is enabled. If this value
is true
, the protocol
is enabled.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Obtains a value indicating whether RSA blinding is enabled.
OSStatus SSLGetRsaBlinding ( SSLContextRef context, Boolean *blinding );
An SSL session context reference.
On return, a pointer to a Boolean value indicating whether RSA blinding is enabled.
A result code. See “Secure Transport Result Codes.”
This function is used only on the server side of a connection.
Call the SSLSetRsaBlinding
function
to enable or disable RSA blinding.
SecureTransport.h
Retrieves the state of an SSL session.
OSStatus SSLGetSessionState ( SSLContextRef context, SSLSessionState *state );
An SSL session context reference.
On return, points to a constant that indicates the state of the SSL session. See “SSL Session State Constants” for possible values.
A result code. See “Secure Transport Result Codes.”
SecureTransport.h
Determines the values of the supported cipher suites.
OSStatus SSLGetSupportedCiphers ( SSLContextRef context, SSLCipherSuite *ciphers, size_t *numCiphers );
An SSL session context reference.
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.
Points to the number of supported cipher suites
that you want returned. Before calling, retrieve this value by calling
the SSLGetNumberSupportedCiphers
function.
A result code. See “Secure Transport Result Codes.” If the supplied buffer is too small, errSSLBufferOverflow
is
returned.
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.
SecureTransport.h
Performs the SSL handshake.
OSStatus SSLHandshake ( SSLContextRef context );
An SSL session context reference.
A result code. See “Secure Transport Result Codes.”
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 SSLGetPeerCertificates
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.
A return value of errSSLWouldBlock
indicates
that the SSLHandshake
function
must be called again until a different result code is returned.
SecureTransport.h
Creates a new SSL session context.
OSStatus SSLNewContext ( Boolean isServer, SSLContextRef *contextPtr );
A Boolean value; True
if
the calling process is a server.
On return, points to a new SSL session context reference.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Performs a normal application-level read operation.
OSStatus SSLRead ( SSLContextRef context, void *data, size_t dataLength, size_t *processed );
An SSL session context reference.
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.
The amount of data you would like to read.
On return, points to the number of bytes actually read.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Specifies whether root certificates from unrecognized certification authorities are allowed.
OSStatus SSLSetAllowsAnyRoot ( SSLContextRef context, Boolean anyRoot );
An SSL session context reference.
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.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Specifies whether certificate expiration times are ignored.
OSStatus SSLSetAllowsExpiredCerts ( SSLContextRef context, Boolean allowsExpired );
An SSL session context reference.
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.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Specifies whether expired root certificates are allowed.
OSStatus SSLSetAllowsExpiredRoots ( SSLContextRef context, Boolean allowsExpired );
An SSL session context reference.
A Boolean value indicating whether to allow
expired root certificates. Pass true
to
allow expired roots.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Specifies this connection’s certificate or certificates.
OSStatus SSLSetCertificate ( SSLContextRef context, CFArrayRef certRefs );
An SSL session context reference.
The certificates to set. This array contains
items of type SecCertificateRef
, except
for certRefs[0]
, which
is of type SecIdentityRef
.
A result code. See “Secure Transport Result Codes.”
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 can be called only when no session is active.
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.
SecureTransport.h
Specifies the requirements for client-side authentication.
OSStatus SSLSetClientSideAuthenticate ( SSLContextRef context, SSLAuthenticate auth );
An SSL session context reference.
A flag setting the requirements for client-side authentication. See “SSL Authentication Constants” for possible values.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Specifies an I/O connection for a specific session.
OSStatus SSLSetConnection ( SSLContextRef context, SSLConnectionRef connection );
An SSL session context reference.
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
.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Specifies Diffie-Hellman parameters.
OSStatus SSLSetDiffieHellmanParams ( SSLContextRef context, const void *dhParams, size_t dhParamsLen );
An SSL session context reference.
A pointer to a buffer containing the Diffie-Hellman parameters in Open SSL DER format.
A value representing the size of the buffer pointed to by the dhParams parameter.
A result code. See “Secure Transport Result Codes.”
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-Hellmand 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
.
SecureTransport.h
Enables or disables peer certificate chain validation.
OSStatus SSLSetEnableCertVerify ( SSLContextRef context, Boolean enableVerify );
An SSL session context reference.
A Boolean value specifying whether peer certificate
chain validation is enabled. Certificate chain validation is enabled
by default. Specify false
to disable
validation.
A result code. See “Secure Transport Result Codes.”
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 SSLGetPeerCertificates
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.
SecureTransport.h
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 );
An SSL session context reference.
A pointer to the cipher suites to enable.
The number of cipher suites to enable.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Specifies the encryption certificates used for this connection.
OSStatus SSLSetEncryptionCertificate ( SSLContextRef context, CFArrayRef certRefs );
An SSL session context reference.
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
.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Specifies callback functions that perform the network I/O operations.
OSStatus SSLSetIOFuncs ( SSLContextRef context, SSLReadFunc read, SSLWriteFunc write );
An SSL session context reference.
A pointer to your read callback function.
See SSLReadFunc
for information
on defining this function.
A pointer to your write callback function.
See SSLWriteFunc
for information on
defining this function.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Specifies the fully qualified domain name of the peer.
OSStatus SSLSetPeerDomainName ( SSLContextRef context, const char *peerName, size_t peerNameLen );
An SSL session context reference.
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.
The number of bytes passed in the peerName
parameter.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Specifies data that is sufficient to uniquely identify the peer of the current session.
OSStatus SSLSetPeerID ( SSLContextRef context, const void *peerID, size_t peerIDLen );
An SSL session context reference.
A pointer to a buffer containing the peer ID data to set.
The length of the peer ID data buffer.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Sets the SSL protocol version. This function is deprecated.
OSStatus SSLSetProtocolVersion ( SSLContextRef context, SSLProtocol version );
An SSL session context reference.
The SSL protocol version to negotiate.
A result code. See “Secure Transport Result Codes.”
Use the SSLSetProtocolVersionEnabled
function
instead.
This function cannot be called when a session is active.
SecureTransport.h
Sets the allowed SSL protocol versions.
OSStatus SSLSetProtocolVersionEnabled ( SSLContextRef context, SSLProtocol protocol, Boolean enable );
An SSL session context reference.
The SSL protocol version to enable. Pass kSSLProtocolAll
to
enable all protocols.
A Boolean value indicating whether to enable
or disable the specified protocol. Specify true
to
enable the protocol.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
Enables or disables RSA blinding.
OSStatus SSLSetRsaBlinding ( SSLContextRef context, Boolean blinding );
An SSL session context reference.
A Boolean value indicating whether to enable
RSA blinding. Pass true
to enable
RSA blinding.
A result code. See “Secure Transport Result Codes.”
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 calcuate 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.
SecureTransport.h
Augments or replaces the default set of trusted root certificates for this session.
OSStatus SSLSetTrustedRoots ( SSLContextRef context, CFArrayRef trustedRoots, Boolean replaceExisting );
An SSL session context reference.
A reference to an array of trusted root certificates
of type SecCertificateRef
.
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.
A result code. See “Secure Transport Result Codes.”
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 SSLGetTrustedRoots
function.
SecureTransport.h
Performs a normal application-level write operation.
OSStatus SSLWrite ( SSLContextRef context, const void *data, size_t dataLength, size_t *processed );
An SSL session context reference.
A pointer to the buffer of data to write.
The amount, in bytes, of data to write.
On return, the length, in bytes, of the data actually written.
A result code. See “Secure Transport Result Codes.”
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.
SecureTransport.h
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 );
A connection reference.
On return, points to the data read from the connection. You must allocate this memory before calling this function.
On input, a pointer to an integer representing the length of the data in bytes. On return, points to the number of bytes actually transferred.
A result code. See “Secure Transport Result Codes.”
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 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
.
SecureTransport.h
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, void *data, size_t *dataLength );
The SSL session connection reference.
A pointer to the data to write to the connection.You must allocate this memory before calling this function.
Before calling, an integer representing the length of the data in bytes. On return, this is the number of bytes actually transferred.
A result code. See “Secure Transport Result Codes.”
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
.
SecureTransport.h
Represents a pointer to an opaque I/O connection object.
typedef const void *SSLConnectionRef;
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.
SecureTransport.h
Represents a pointer to an opaque SSL session context object.
struct SSLContext; typedef struct SSLContext *SSLContextRef;
The SSL session context object references the state associated with a session. You cannot reuse an SSL session context in multiple sessions.
SecureTransport.h
Represents the requirements for client-side authentication.
typedef enum { kNeverAuthenticate, kAlwaysAuthenticate, kTryAuthenticate } SSLAuthenticate;
kNeverAuthenticate
Indicates that client-side authentication is not required. (Default.)
Available in Mac OS X v10.2 and later.
Declared in SecureTransport.h
.
kAlwaysAuthenticate
Indicates that client-side authentication is required.
Available in Mac OS X v10.2 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 Mac OS X v10.2 and later.
Declared in SecureTransport.h
.
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, 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 };
SSL_RSA_EXPORT_WITH_RC4_40_MD5
Session key size conforms to pre-1998 US export restrictions.
Available in Mac OS X v10.2 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 Mac OS X v10.2 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 Mac OS X v10.2 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 Mac OS X v10.2 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 Mac OS X v10.2 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 Mac OS X v10.2 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 Mac OS X v10.2 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 Mac OS X v10.2 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 Mac OS X v10.2 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 Mac OS X v10.2 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 Mac OS X v10.2 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 Mac OS X v10.2 and later.
Declared in CipherSuite.h
.
Represents the status of client certificate exchange.
typedef enum { kSSLClientCertNone, kSSLClientCertRequested, kSSLClientCertSent, kSSLClientCertRejected } SSLClientCertificateState;
kSSLClientCertNone
Indicates that the server hasn’t asked for a certificate and that the client hasn’t sent one.
Available in Mac OS X v10.2 and later.
Declared in SecureTransport.h
.
kSSLClientCertRequested
Indicates that the server has asked for a certificat, but the client has not sent it.
Available in Mac OS X v10.2 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 Mac OS X v10.2 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 Mac OS X v10.2 and later.
Declared in SecureTransport.h
.
Represents the SSL protocol version.
typedef enum { kSSLProtocolUnknown, kSSLProtocol2, kSSLProtocol3, kSSLProtocol3Only, kTLSProtocol1, kTLSProtocol1Only, kSSLProtocolAll } SSLProtocol;
kSSLProtocolUnknown
Specifies that no protocol has been or should be negotiated or specified; use default.
Available in Mac OS X v10.2 and later.
Declared in SecureTransport.h
.
kSSLProtocol2
Specifies that only the SSL 2.0 protocol may be negotiated.
Available in Mac OS X v10.2 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 Mac OS X v10.2 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.
Available in Mac OS X v10.2 and later.
Declared in SecureTransport.h
.
kTLSProtocol1
Specifies that the TLS 1.0 protocol is preferred but lower versions may be negotiated.
Available in Mac OS X v10.2 and later.
Declared in SecureTransport.h
.
kTLSProtocol1Only
Specifies that only the TLS 1.0 protocol may be negotiated.
Available in Mac OS X v10.2 and later.
Declared in SecureTransport.h
.
kSSLProtocolAll
Specifies all supported versions.
Available in Mac OS X v10.3 and later.
Declared in SecureTransport.h
.
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
Represents the state of an SSL session.
typedef enum { kSSLIdle, kSSLHandshake, kSSLConnected, kSSLClosed, kSSLAborted } SSLSessionState;
kSSLIdle
No I/O has been performed yet.
Available in Mac OS X v10.2 and later.
Declared in SecureTransport.h
.
kSSLHandshake
The SSL handshake is in progress.
Available in Mac OS X v10.2 and later.
Declared in SecureTransport.h
.
kSSLConnected
The SSL handshake is complete; the connection is ready for normal I/O.
Available in Mac OS X v10.2 and later.
Declared in SecureTransport.h
.
kSSLClosed
The connection closed normally.
Available in Mac OS X v10.2 and later.
Declared in SecureTransport.h
.
kSSLAborted
The connection aborted.
Available in Mac OS X v10.2 and later.
Declared in SecureTransport.h
.
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.
© 2003, 2004 Apple Computer, Inc. All Rights Reserved. (Last updated: 2004-08-31)