Function

SSLSetCertificate

Specifies this connection’s certificate or certificates.

Declaration

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.

See Also

Authentication

SSLAddDistinguishedName

Adds a DER-encoded distinguished name to a list of acceptable names to be specified in requests for client certificates.

SSLCopyDistinguishedNames

Retrieves the distinguished names of acceptable certification authorities.

SSLGetClientCertificateState

Retrieves the exchange status of the client certificate.

SSLCopyPeerTrust

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

SSLClientCertificateState

An enumeration of the states of client certificate exchange.

SSLSetOCSPResponse

Sets the OCSP response for the given SSL session.

SSLSetSessionTicketsEnabled

Enables or disables session ticket resumption.