/* * Copyright (c) 1999-2002,2005-2012 Apple Inc. All Rights Reserved. * * @APPLE_LICENSE_HEADER_START@ * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this * file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_LICENSE_HEADER_END@ */ /* * SecureTransport.h - Public API for Apple SSL/TLS Implementation */ #ifndef _SECURITY_SECURETRANSPORT_H_ #define _SECURITY_SECURETRANSPORT_H_ /* * This file describes the public API for an implementation of the * Secure Socket Layer, V. 3.0, Transport Layer Security, V. 1.0 to V. 1.2 * and Datagram Transport Layer Security V. 1.0 * * There are no transport layer dependencies in this library; * it can be used with sockets, Open Transport, etc. Applications using * this library provide callback functions which do the actual I/O * on underlying network connections. Applications are also responsible * for setting up raw network connections; the application passes in * an opaque reference to the underlying (connected) entity at the * start of an SSL session in the form of an SSLConnectionRef. * * Some terminology: * * A "client" is the initiator of an SSL Session. The canonical example * of a client is a web browser, when it's talking to an https URL. * * A "server" is an entity which accepts requests for SSL sessions made * by clients. E.g., a secure web server. * An "SSL Session", or "session", is bounded by calls to 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 in this * library to the state associated with one session. A SSLContextRef cannot * be reused for multiple sessions. */ #include <CoreFoundation/CFArray.h> #include <Security/CipherSuite.h> #include <Security/SecTrust.h> #include <sys/types.h> #include <Availability.h> #ifdef __cplusplus extern "C" { #endif /*********************** *** Common typedefs *** ***********************/ /* Opaque reference to an SSL session context */ struct SSLContext; typedef struct SSLContext *SSLContextRef; /* Opaque reference to an I/O conection (socket, Endpoint, etc.) */ typedef const void * SSLConnectionRef; /* SSL Protocol version */ typedef enum { kSSLProtocolUnknown = 0, /* no protocol negotiated/specified; use default */ kSSLProtocol3 = 2, /* SSL 3.0 */ kTLSProtocol1 = 4, /* TLS 1.0 */ kTLSProtocol11 = 7, /* TLS 1.1 */ kTLSProtocol12 = 8, /* TLS 1.2 */ kDTLSProtocol1 = 9, /* DTLS 1.0 */ /* DEPRECATED on iOS */ kSSLProtocol2 = 1, /* SSL 2.0 */ kSSLProtocol3Only = 3, /* SSL 3.0 Only */ kTLSProtocol1Only = 5, /* TLS 1.0 Only */ kSSLProtocolAll = 6, /* All TLS supported protocols */ } SSLProtocol; /* SSL session options */ typedef enum { /* * Set this option to enable returning from SSLHandshake (with a result of * errSSLServerAuthCompleted) when the server authentication portion of the * handshake is complete. This disable certificate verification and * provides an opportunity to perform application-specific server * verification before deciding to continue. */ kSSLSessionOptionBreakOnServerAuth, /* * Set this option to enable returning from SSLHandshake (with a result of * errSSLClientCertRequested) when the server requests a client certificate. */ kSSLSessionOptionBreakOnCertRequested, /* * This option is the same as kSSLSessionOptionBreakOnServerAuth but applies * to the case where SecureTransport is the server and the client has presented * its certificates allowing the server to verify whether these should be * allowed to authenticate. */ kSSLSessionOptionBreakOnClientAuth } SSLSessionOption; /* State of an SSLSession */ typedef enum { kSSLIdle, /* no I/O performed yet */ kSSLHandshake, /* SSL handshake in progress */ kSSLConnected, /* Handshake complete, ready for normal I/O */ kSSLClosed, /* connection closed normally */ kSSLAborted /* connection aborted */ } SSLSessionState; /* * Status of client certificate exchange (which is optional * for both server and client). */ typedef enum { /* Server hasn't asked for a cert. Client hasn't sent one. */ kSSLClientCertNone, /* Server has asked for a cert, but client didn't send it. */ kSSLClientCertRequested, /* * Server side: We asked for a cert, client sent one, we validated * it OK. App can inspect the cert via * SSLGetPeerCertificates(). * Client side: server asked for one, we sent it. */ kSSLClientCertSent, /* * Client sent a cert but failed validation. Server side only. * Server app can inspect the cert via SSLGetPeerCertificates(). */ kSSLClientCertRejected } SSLClientCertificateState; /* * R/W functions. The application using this library provides * these functions via SSLSetIOFuncs(). * * Data's memory is allocated by caller; on entry to these two functions * the *length argument indicates both the size of the available data and the * requested byte count. Number of bytes actually transferred is returned in * *length. * * The application may configure the underlying connection to operate * in a non-blocking manner; in such a case, a read operation may * well return errSSLWouldBlock, indicating "I transferred less data than * you requested (maybe even zero bytes), nothing is wrong, except * requested I/O hasn't completed". This will be returned back up to * the application as a return from SSLRead(), SSLWrite(), SSLHandshake(), * etc. */ typedef OSStatus (*SSLReadFunc) (SSLConnectionRef connection, void *data, /* owned by * caller, data * RETURNED */ size_t *dataLength); /* IN/OUT */ typedef OSStatus (*SSLWriteFunc) (SSLConnectionRef connection, const void *data, size_t *dataLength); /* IN/OUT */ /************************************************* *** OSStatus values unique to SecureTransport *** *************************************************/ /* Note: the comments that appear after these errors are used to create SecErrorMessages.strings. The comments must not be multi-line, and should be in a form meaningful to an end user. If a different or additional comment is needed, it can be put in the header doc format, or on a line that does not start with errZZZ. */ enum { errSSLProtocol = -9800, /* SSL protocol error */ errSSLNegotiation = -9801, /* Cipher Suite negotiation failure */ errSSLFatalAlert = -9802, /* Fatal alert */ errSSLWouldBlock = -9803, /* I/O would block (not fatal) */ errSSLSessionNotFound = -9804, /* attempt to restore an unknown session */ errSSLClosedGraceful = -9805, /* connection closed gracefully */ errSSLClosedAbort = -9806, /* connection closed via error */ errSSLXCertChainInvalid = -9807, /* invalid certificate chain */ errSSLBadCert = -9808, /* bad certificate format */ errSSLCrypto = -9809, /* underlying cryptographic error */ errSSLInternal = -9810, /* Internal error */ errSSLModuleAttach = -9811, /* module attach failure */ errSSLUnknownRootCert = -9812, /* valid cert chain, untrusted root */ errSSLNoRootCert = -9813, /* cert chain not verified by root */ errSSLCertExpired = -9814, /* chain had an expired cert */ errSSLCertNotYetValid = -9815, /* chain had a cert not yet valid */ errSSLClosedNoNotify = -9816, /* server closed session with no notification */ errSSLBufferOverflow = -9817, /* insufficient buffer provided */ errSSLBadCipherSuite = -9818, /* bad SSLCipherSuite */ /* fatal errors detected by peer */ errSSLPeerUnexpectedMsg = -9819, /* unexpected message received */ errSSLPeerBadRecordMac = -9820, /* bad MAC */ errSSLPeerDecryptionFail = -9821, /* decryption failed */ errSSLPeerRecordOverflow = -9822, /* record overflow */ errSSLPeerDecompressFail = -9823, /* decompression failure */ errSSLPeerHandshakeFail = -9824, /* handshake failure */ errSSLPeerBadCert = -9825, /* misc. bad certificate */ errSSLPeerUnsupportedCert = -9826, /* bad unsupported cert format */ errSSLPeerCertRevoked = -9827, /* certificate revoked */ errSSLPeerCertExpired = -9828, /* certificate expired */ errSSLPeerCertUnknown = -9829, /* unknown certificate */ errSSLIllegalParam = -9830, /* illegal parameter */ errSSLPeerUnknownCA = -9831, /* unknown Cert Authority */ errSSLPeerAccessDenied = -9832, /* access denied */ errSSLPeerDecodeError = -9833, /* decoding error */ errSSLPeerDecryptError = -9834, /* decryption error */ errSSLPeerExportRestriction = -9835, /* export restriction */ errSSLPeerProtocolVersion = -9836, /* bad protocol version */ errSSLPeerInsufficientSecurity = -9837, /* insufficient security */ errSSLPeerInternalError = -9838, /* internal error */ errSSLPeerUserCancelled = -9839, /* user canceled */ errSSLPeerNoRenegotiation = -9840, /* no renegotiation allowed */ /* non-fatal result codes */ errSSLPeerAuthCompleted = -9841, /* peer cert is valid, or was ignored if verification disabled */ errSSLClientCertRequested = -9842, /* server has requested a client cert */ /* more errors detected by us */ errSSLHostNameMismatch = -9843, /* peer host name mismatch */ errSSLConnectionRefused = -9844, /* peer dropped connection before responding */ errSSLDecryptionFail = -9845, /* decryption failure */ errSSLBadRecordMac = -9846, /* bad MAC */ errSSLRecordOverflow = -9847, /* record overflow */ errSSLBadConfiguration = -9848, /* configuration error */ errSSLLast = -9849, /* end of range, to be deleted */ }; /* DEPRECATED aliases for errSSLPeerAuthCompleted */ #define errSSLServerAuthCompleted errSSLPeerAuthCompleted #define errSSLClientAuthCompleted errSSLPeerAuthCompleted typedef enum { kSSLServerSide, kSSLClientSide } SSLProtocolSide; typedef enum { kSSLStreamType, kSSLDatagramType } SSLConnectionType; /****************** *** Public API *** ******************/ /* * Secure Transport APIs require a SSLContextRef, which is an opaque * reference to the SSL session and its parameters. On Mac OS X 10.7 * and earlier versions, a new context is created using SSLNewContext, * and is disposed by calling SSLDisposeContext. * * On i0S 5.0 and later, as well as Mac OS X versions after 10.7, the * SSLContextRef is a true CFType object with retain-release semantics. * New code should create a new context using SSLCreateContext (instead * of SSLNewContext), and dispose the context by calling CFRelease * (instead of SSLDisposeContext) when finished with it. */ /* * Return the CFTypeID for SSLContext objects. */ CFTypeID SSLContextGetTypeID(void) __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); /* * Create a new instance of an SSLContextRef using the specified allocator. */ SSLContextRef SSLCreateContext(CFAllocatorRef alloc, SSLProtocolSide protocolSide, SSLConnectionType connectionType) __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) /* * Create a new session context. * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and should be considered * deprecated on Mac OS X. Your code should use SSLCreateContext instead. */ OSStatus SSLNewContext (Boolean isServer, SSLContextRef *contextPtr) /* RETURNED */ __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); /* * Dispose of a session context. * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and should be considered * deprecated on Mac OS X. Your code should use CFRelease to dispose a session * created with SSLCreateContext. */ OSStatus SSLDisposeContext (SSLContextRef context) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); #endif /* MAC OS X */ /* * Determine the state of an SSL/DTLS session. */ OSStatus SSLGetSessionState (SSLContextRef context, SSLSessionState *state) /* RETURNED */ __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * Set options for an SSL session. Must be called prior to SSLHandshake(); * subsequently cannot be called while session is active. */ OSStatus SSLSetSessionOption (SSLContextRef context, SSLSessionOption option, Boolean value) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_5_0); /* * Determine current value for the specified option in a given SSL session. */ OSStatus SSLGetSessionOption (SSLContextRef context, SSLSessionOption option, Boolean *value) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_5_0); /******************************************************************** *** Session context configuration, common to client and servers. *** ********************************************************************/ /* * Specify functions which do the network I/O. Must be called prior * to SSLHandshake(); subsequently cannot be called while a session is * active. */ OSStatus SSLSetIOFuncs (SSLContextRef context, SSLReadFunc readFunc, SSLWriteFunc writeFunc) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * Set the minimum SSL protocol version allowed. Optional. * The default is the lower supported protocol. * * This can only be called when no session is active. * * For TLS contexts, legal values for minVersion are : * kSSLProtocol3 * kTLSProtocol1 * kTLSProtocol11 * kTLSProtocol12 * * For DTLS contexts, legal values for minVersion are : * kDTLSProtocol1 */ OSStatus SSLSetProtocolVersionMin (SSLContextRef context, SSLProtocol minVersion) __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); /* * Get minimum protocol version allowed */ OSStatus SSLGetProtocolVersionMin (SSLContextRef context, SSLProtocol *minVersion) __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); /* * Set the maximum SSL protocol version allowed. Optional. * The default is the highest supported protocol. * * This can only be called when no session is active. * * For TLS contexts, legal values for minVersion are : * kSSLProtocol3 * kTLSProtocol1 * kTLSProtocol11 * kTLSProtocol12 * * For DTLS contexts, legal values for minVersion are : * kDTLSProtocol1 */ OSStatus SSLSetProtocolVersionMax (SSLContextRef context, SSLProtocol maxVersion) __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); /* * Get maximum protocol version allowed */ OSStatus SSLGetProtocolVersionMax (SSLContextRef context, SSLProtocol *maxVersion) __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) /* * Set allowed SSL protocol versions. Optional. * Specifying kSSLProtocolAll for SSLSetProtocolVersionEnabled results in * specified 'enable' boolean to be applied to all supported protocols. * The default is "all supported protocols are enabled". * This can only be called when no session is active. * * Legal values for protocol are : * kSSLProtocol2 * kSSLProtocol3 * kTLSProtocol1 * kSSLProtocolAll * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and should be considered * deprecated on Mac OS X. You can use SSLSetProtocolVersionMin and/or * SSLSetProtocolVersionMax to specify which protocols are enabled. */ OSStatus SSLSetProtocolVersionEnabled (SSLContextRef context, SSLProtocol protocol, Boolean enable) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); /* * Obtain a value specified in SSLSetProtocolVersionEnabled. * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and should be considered * deprecated on Mac OS X. You can use SSLGetProtocolVersionMin and/or * SSLGetProtocolVersionMax to check whether a protocol is enabled. */ OSStatus SSLGetProtocolVersionEnabled(SSLContextRef context, SSLProtocol protocol, Boolean *enable) /* RETURNED */ __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); /* * Get/set SSL protocol version; optional. Default is kSSLProtocolUnknown, * in which case the highest possible version is attempted, but a lower * version is accepted if the peer requires it. * SSLSetProtocolVersion cannot be called when a session is active. * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and deprecated on Mac OS X 10.8. * Use SSLSetProtocolVersionMin and/or SSLSetProtocolVersionMax to specify * which protocols are enabled. */ OSStatus SSLSetProtocolVersion (SSLContextRef context, SSLProtocol version) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_8,__IPHONE_NA,__IPHONE_NA); /* * Obtain the protocol version specified in SSLSetProtocolVersion. * If SSLSetProtocolVersionEnabled() has been called for this session, * SSLGetProtocolVersion() may return paramErr if the protocol enable * state can not be represented by the SSLProtocol enums (e.g., * SSL2 and TLS1 enabled, SSL3 disabled). * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and deprecated on Mac OS X 10.8. * Use SSLGetProtocolVersionMin and/or SSLGetProtocolVersionMax to check * whether a protocol is enabled. */ OSStatus SSLGetProtocolVersion (SSLContextRef context, SSLProtocol *protocol) /* RETURNED */ __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_8,__IPHONE_NA,__IPHONE_NA); #endif /* MAC OS X */ /* * Specify this connection's certificate(s). This is mandatory for * server connections, optional for clients. Specifying a certificate * for a client enables SSL client-side authentication. The end-entity * cert is in certRefs[0]. Specifying a root cert is optional; if it's * not specified, the root cert which verifies the cert chain specified * here must be present in the system-wide set of trusted anchor certs. * * The certRefs argument is a CFArray containing SecCertificateRefs, * except for certRefs[0], which is a SecIdentityRef. * * Must be called prior to SSLHandshake(), or immediately after * SSLHandshake has returned errSSLClientCertRequested (i.e. before the * handshake is resumed by calling SSLHandshake again.) * * SecureTransport assumes the following: * * -- The certRef references remain valid for the lifetime of the session. * -- The certificate specified in certRefs[0] is capable of signing. * -- The required capabilities of the certRef[0], and of the optional cert * specified in SSLSetEncryptionCertificate (see below), are highly * dependent on the application. For example, to work as a server with * Netscape clients, the cert specified here must be capable of both * signing and encrypting. */ OSStatus SSLSetCertificate (SSLContextRef context, CFArrayRef certRefs) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * Specify I/O connection - a socket, endpoint, etc., which is * managed by caller. 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 an incoming client request * has been established. * * Must be called prior to SSLHandshake(); subsequently can only be * called when no session is active. */ OSStatus SSLSetConnection (SSLContextRef context, SSLConnectionRef connection) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); OSStatus SSLGetConnection (SSLContextRef context, SSLConnectionRef *connection) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * Specify the fully qualified doman name of the peer, e.g., "store.apple.com." * Optional; used to verify the common name field in peer's certificate. * Name is in the form of a C string; NULL termination optional, i.e., * peerName[peerNameLen+1] may or may not have a NULL. In any case peerNameLen * is the number of bytes of the peer domain name. */ OSStatus SSLSetPeerDomainName (SSLContextRef context, const char *peerName, size_t peerNameLen) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * Determine the buffer size needed for SSLGetPeerDomainName(). */ OSStatus SSLGetPeerDomainNameLength (SSLContextRef context, size_t *peerNameLen) // RETURNED __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * Obtain the value specified in SSLSetPeerDomainName(). */ OSStatus SSLGetPeerDomainName (SSLContextRef context, char *peerName, // returned here size_t *peerNameLen) // IN/OUT __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * Specify the Datagram TLS Hello Cookie. * This is to be called for server side only and is optional. * The default is a zero len cookie. The maximum cookieLen is 32 bytes. */ OSStatus SSLSetDatagramHelloCookie (SSLContextRef dtlsContext, const void *cookie, size_t cookieLen) __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); /* * Specify the maximum record size, including all DTLS record headers. * This should be set appropriately to avoid fragmentation * of Datagrams during handshake, as fragmented datagrams may * be dropped by some network. * This is for Datagram TLS only */ OSStatus SSLSetMaxDatagramRecordSize (SSLContextRef dtlsContext, size_t maxSize) __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); /* * Get the maximum record size, including all Datagram TLS record headers. * This is for Datagram TLS only */ OSStatus SSLGetMaxDatagramRecordSize (SSLContextRef dtlsContext, size_t *maxSize) __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); /* * Obtain the actual negotiated protocol version of the active * session, which may be different that the value specified in * SSLSetProtocolVersion(). Returns kSSLProtocolUnknown if no * SSL session is in progress. */ OSStatus SSLGetNegotiatedProtocolVersion (SSLContextRef context, SSLProtocol *protocol) /* RETURNED */ __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * Determine number and values of all of the SSLCipherSuites we support. * Caller allocates output buffer for SSLGetSupportedCiphers() and passes in * its size in *numCiphers. If supplied buffer is too small, errSSLBufferOverflow * will be returned. */ OSStatus SSLGetNumberSupportedCiphers (SSLContextRef context, size_t *numCiphers) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); OSStatus SSLGetSupportedCiphers (SSLContextRef context, SSLCipherSuite *ciphers, /* RETURNED */ size_t *numCiphers) /* IN/OUT */ __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * Specify a (typically) restricted set of SSLCipherSuites to be enabled by * the current SSLContext. Can only be called when no session is active. Default * set of enabled SSLCipherSuites is the same as the complete set of supported * SSLCipherSuites as obtained by SSLGetSupportedCiphers(). */ OSStatus SSLSetEnabledCiphers (SSLContextRef context, const SSLCipherSuite *ciphers, size_t numCiphers) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * Determine number and values of all of the SSLCipherSuites currently enabled. * Caller allocates output buffer for SSLGetEnabledCiphers() and passes in * its size in *numCiphers. If supplied buffer is too small, errSSLBufferOverflow * will be returned. */ OSStatus SSLGetNumberEnabledCiphers (SSLContextRef context, size_t *numCiphers) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); OSStatus SSLGetEnabledCiphers (SSLContextRef context, SSLCipherSuite *ciphers, /* RETURNED */ size_t *numCiphers) /* IN/OUT */ __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) /* * Enable/disable peer certificate chain validation. Default is enabled. * If caller disables, it is the caller's responsibility to call * SSLCopyPeerCertificates() upon successful completion of the handshake * and then to perform external validation of the peer certificate * chain before proceeding with data transfer. * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and should be considered * deprecated on Mac OS X. To disable peer certificate chain validation, you * can instead use SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth * to true. This will disable verification and cause SSLHandshake to return with * an errSSLServerAuthCompleted result when the peer certificates have been * received; at that time, you can choose to evaluate peer trust yourself, or * simply call SSLHandshake again to proceed with the handshake. */ OSStatus SSLSetEnableCertVerify (SSLContextRef context, Boolean enableVerify) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); /* * Check whether peer certificate chain validation is enabled. * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and should be considered * deprecated on Mac OS X. To check whether peer certificate chain validation * is enabled in a context, call SSLGetSessionOption to obtain the value of * the kSSLSessionOptionBreakOnServerAuth session option flag. If the value * of this option flag is true, then verification is disabled. */ OSStatus SSLGetEnableCertVerify (SSLContextRef context, Boolean *enableVerify) /* RETURNED */ __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); /* * Specify the option of ignoring certificates' "expired" times. * This is a common failure in the real SSL world. Default setting for this * flag is false, meaning expired certs result in an errSSLCertExpired error. * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and should be considered * deprecated on Mac OS X. To ignore expired certificate errors, first disable * Secure Transport's automatic verification of peer certificates by calling * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When * SSLHandshake subsequently returns an errSSLServerAuthCompleted result, * your code should obtain the SecTrustRef for the peer's certificates and * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h). * The SecTrustSetOptions function allows you to specify that the expiration * status of certificates should be ignored for this evaluation. * * Example: * * status = SSLSetSessionOption(ctx, kSSLSessionOptionBreakOnServerAuth, true); * do { * status = SSLHandshake(ctx); * * if (status == errSSLServerAuthCompleted) { * SecTrustRef peerTrust = NULL; * status = SSLCopyPeerTrust(ctx, &peerTrust); * if (status == noErr) { * SecTrustResultType trustResult; * // set flag to allow expired certificates * SecTrustSetOptions(peerTrust, kSecTrustOptionAllowExpired); * status = SecTrustEvaluate(peerTrust, &trustResult); * if (status == noErr) { * // A "proceed" result means the cert is explicitly trusted, * // e.g. "Always Trust" was clicked; * // "Unspecified" means the cert has no explicit trust settings, * // but is implicitly OK since it chains back to a trusted root. * // Any other result means the cert is not trusted. * // * if (trustResult == kSecTrustResultProceed || * trustResult == kSecTrustResultUnspecified) { * // certificate is trusted * status = errSSLWouldBlock; // so we call SSLHandshake again * } else if (trustResult == kSecTrustResultRecoverableTrustFailure) { * // not trusted, for some reason other than being expired; * // could ask the user whether to allow the connection here * // * status = errSSLXCertChainInvalid; * } else { * // cannot use this certificate (fatal) * status = errSSLBadCert; * } * } * if (peerTrust) { * CFRelease(peerTrust); * } * } * } // errSSLServerAuthCompleted * * } while (status == errSSLWouldBlock); * */ OSStatus SSLSetAllowsExpiredCerts (SSLContextRef context, Boolean allowsExpired) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); /* * Obtain the current value of an SSLContext's "allowExpiredCerts" flag. * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and should be considered * deprecated on Mac OS X. */ OSStatus SSLGetAllowsExpiredCerts (SSLContextRef context, Boolean *allowsExpired) /* RETURNED */ __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); /* * Similar to SSLSetAllowsExpiredCerts, SSLSetAllowsExpiredRoots allows the * option of ignoring "expired" status for root certificates only. * Default setting is false, i.e., expired root certs result in an * errSSLCertExpired error. * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and should be considered * deprecated on Mac OS X. To ignore expired certificate errors, first disable * Secure Transport's automatic verification of peer certificates by calling * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When * SSLHandshake subsequently returns an errSSLServerAuthCompleted result, * your code should obtain the SecTrustRef for the peer's certificates and * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h). * The SecTrustSetOptions function allows you to specify that the expiration * status of certificates should be ignored for this evaluation. * * See the description of the SSLSetAllowsExpiredCerts function (above) * for a code example. The kSecTrustOptionAllowExpiredRoot option can be used * instead of kSecTrustOptionAllowExpired to allow expired roots only. */ OSStatus SSLSetAllowsExpiredRoots (SSLContextRef context, Boolean allowsExpired) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); /* * Obtain the current value of an SSLContext's "allow expired roots" flag. * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and should be considered * deprecated on Mac OS X. */ OSStatus SSLGetAllowsExpiredRoots (SSLContextRef context, Boolean *allowsExpired) /* RETURNED */ __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); /* * Specify option of allowing for an unknown root cert, i.e., one which * this software can not verify as one of a list of known good root certs. * Default for this flag is false, in which case one of the following two * errors may occur: * -- The peer returns a cert chain with a root cert, and the chain * verifies to that root, but the root is not one of our trusted * roots. This results in errSSLUnknownRootCert on handshake. * -- The peer returns a cert chain which does not contain a root cert, * and we can't verify the chain to one of our trusted roots. This * results in errSSLNoRootCert on handshake. * * Both of these error conditions are ignored when the AllowAnyRoot flag is * true, allowing connection to a totally untrusted peer. * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and should be considered * deprecated on Mac OS X. To ignore unknown root cert errors, first disable * Secure Transport's automatic verification of peer certificates by calling * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When * SSLHandshake subsequently returns an errSSLServerAuthCompleted result, * your code should obtain the SecTrustRef for the peer's certificates and * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h). * * See the description of the SSLSetAllowsExpiredCerts function (above) * for a code example. Note that an unknown root certificate will cause * SecTrustEvaluate to report kSecTrustResultRecoverableTrustFailure as the * trust result. */ OSStatus SSLSetAllowsAnyRoot (SSLContextRef context, Boolean anyRoot) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); /* * Obtain the current value of an SSLContext's "allow any root" flag. * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and should be considered * deprecated on Mac OS X. */ OSStatus SSLGetAllowsAnyRoot (SSLContextRef context, Boolean *anyRoot) /* RETURNED */ __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); /* * Augment or replace the system's default trusted root certificate set * for this session. If replaceExisting is true, the specified roots will * be the only roots which are trusted during this session. If replaceExisting * is false, the specified roots will be added to the current set of trusted * root certs. If this function has never been called, the current trusted * root set is the same as the system's default trusted root set. * Successive calls with replaceExisting false result in accumulation * of additional root certs. * * The trustedRoots array contains SecCertificateRefs. * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and should be considered * deprecated on Mac OS X. To trust specific roots in a session, first disable * Secure Transport's automatic verification of peer certificates by calling * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When * SSLHandshake subsequently returns an errSSLServerAuthCompleted result, * your code should obtain the SecTrustRef for the peer's certificates and * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h). * * See the description of the SSLSetAllowsExpiredCerts function (above) * for a code example. You can call SecTrustSetAnchorCertificates to * augment the system's trusted root set, or SecTrustSetAnchorCertificatesOnly * to make these the only trusted roots, prior to calling SecTrustEvaluate. */ OSStatus SSLSetTrustedRoots (SSLContextRef context, CFArrayRef trustedRoots, Boolean replaceExisting) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); /* * Obtain an array of SecCertificateRefs representing the current * set of trusted roots. If SSLSetTrustedRoots() has never been called * for this session, this returns the system's default root set. * * Caller must CFRelease the returned CFArray. * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and should be considered * deprecated on Mac OS X. To get the current set of trusted roots, call the * SSLCopyPeerTrust function to obtain the SecTrustRef for the peer certificate * chain, then SecTrustCopyCustomAnchorCertificates (see SecTrust.h). */ OSStatus SSLCopyTrustedRoots (SSLContextRef context, CFArrayRef *trustedRoots) /* RETURNED */ __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA); /* * Request peer certificates. Valid anytime, subsequent to a handshake attempt. * * The certs argument is a CFArray containing SecCertificateRefs. * Caller must CFRelease the returned array. * * The cert at index 0 of the returned array is the subject (end * entity) cert; the root cert (or the closest cert to it) is at * the end of the returned array. * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and should be considered * deprecated on Mac OS X. To get peer certificates, call SSLCopyPeerTrust * to obtain the SecTrustRef for the peer certificate chain, then use the * SecTrustGetCertificateCount and SecTrustGetCertificateAtIndex functions * to retrieve individual certificates in the chain (see SecTrust.h). */ OSStatus SSLCopyPeerCertificates (SSLContextRef context, CFArrayRef *certs) /* RETURNED */ __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA); #endif /* MAC OS X */ /* * Obtain a SecTrustRef representing peer certificates. Valid anytime, * subsequent to a handshake attempt. Caller must CFRelease the returned * trust reference. * * The returned trust reference will have already been evaluated for you, * unless one of the following is true: * - Your code has disabled automatic certificate verification, by calling * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. * - Your code has called SSLSetPeerID, and this session has been resumed * from an earlier cached session. * * In these cases, your code should call SecTrustEvaluate prior to * examining the peer certificate chain or trust results (see SecTrust.h). * * NOTE: if you have not called SSLHandshake at least once prior to * calling this function, the returned trust reference will be NULL. */ OSStatus SSLCopyPeerTrust (SSLContextRef context, SecTrustRef *trust) /* RETURNED */ __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_5_0); /* * Specify some data, opaque to this library, which is sufficient * to uniquely identify the peer of the current session. An example * would be IP address and port, stored in some caller-private manner. * To be optionally called prior to SSLHandshake for the current * session. This is mandatory if this session is to be resumable. * * SecureTransport allocates its own copy of the incoming peerID. The * data provided in *peerID, while opaque to SecureTransport, is used * in a byte-for-byte compare to other previous peerID values set by the * current application. Matching peerID blobs result in SecureTransport * attempting to resume an SSL session with the same parameters as used * in the previous session which specified the same peerID bytes. */ OSStatus SSLSetPeerID (SSLContextRef context, const void *peerID, size_t peerIDLen) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * Obtain current PeerID. Returns NULL pointer, zero length if * SSLSetPeerID has not been called for this context. */ OSStatus SSLGetPeerID (SSLContextRef context, const void **peerID, size_t *peerIDLen) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * Obtain the SSLCipherSuite (e.g., SSL_RSA_WITH_DES_CBC_SHA) negotiated * for this session. Only valid when a session is active. */ OSStatus SSLGetNegotiatedCipher (SSLContextRef context, SSLCipherSuite *cipherSuite) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /******************************************************** *** Session context configuration, server side only. *** ********************************************************/ /* * Specify this connection's encryption certificate(s). This is * used in one of the following cases: * * -- The end-entity certificate specified in SSLSetCertificate() is * not capable of encryption. * * -- The end-entity certificate specified in SSLSetCertificate() * contains a key which is too large (i.e., too strong) for legal * encryption in this session. In this case a weaker cert is * specified here and is used for server-initiated key exchange. * * The certRefs argument is a CFArray containing SecCertificateRefs, * except for certRefs[0], which is a SecIdentityRef. * * The following assumptions are made: * * -- The certRefs references remains valid for the lifetime of the * connection. * -- The specified certRefs[0] is capable of encryption. * * Can only be called when no session is active. * * Notes: * ------ * * -- SSL servers which enforce the SSL3 spec to the letter will * not accept encryption certs with RSA keys larger than 512 * bits for exportable ciphers. Apps which wish to use encryption * certs with key sizes larger than 512 bits should disable the * use of exportable ciphers via the SSLSetEnabledCiphers() call. */ OSStatus SSLSetEncryptionCertificate (SSLContextRef context, CFArrayRef certRefs) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * Specify requirements for client-side authentication. * Optional; Default is kNeverAuthenticate. * * Can only be called when no session is active. */ typedef enum { kNeverAuthenticate, /* skip client authentication */ kAlwaysAuthenticate, /* require it */ kTryAuthenticate /* try to authenticate, but not an error * if client doesn't have a cert */ } SSLAuthenticate; OSStatus SSLSetClientSideAuthenticate (SSLContextRef context, SSLAuthenticate auth) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * Add a DER-encoded distinguished name to list of acceptable names * to be specified in requests for client certificates. */ OSStatus SSLAddDistinguishedName (SSLContextRef context, const void *derDN, size_t derDNLen) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_5_0); #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) /* * Add a SecCertificateRef, or a CFArray of them, to a server's list * of acceptable Certificate Authorities (CAs) to present to the client * when client authentication is performed. * * If replaceExisting is true, the specified certificate(s) will replace * a possible existing list of acceptable CAs. If replaceExisting is * false, the specified certificate(s) will be appended to the existing * list of acceptable CAs, if any. * * Returns paramErr if this is called on a SSLContextRef which * is configured as a client, or when a session is active. * * NOTE: this function is currently not available on iOS. */ OSStatus SSLSetCertificateAuthorities(SSLContextRef context, CFTypeRef certificateOrArray, Boolean replaceExisting) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA); /* * Obtain the certificates specified in SSLSetCertificateAuthorities(), * if any. Returns a NULL array if SSLSetCertificateAuthorities() has not * been called. * Caller must CFRelease the returned array. * * NOTE: this function is currently not available on iOS. */ OSStatus SSLCopyCertificateAuthorities(SSLContextRef context, CFArrayRef *certificates) /* RETURNED */ __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA); #endif /* MAC OS X */ /* * Obtain the list of acceptable distinguished names as provided by * a server (if the SSLContextRef is configured as a client), or as * specified by SSLSetCertificateAuthorities (if the SSLContextRef * is configured as a server). * The returned array contains CFDataRefs, each of which represents * one DER-encoded RDN. * * Caller must CFRelease the returned array. */ OSStatus SSLCopyDistinguishedNames (SSLContextRef context, CFArrayRef *names) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_5_0); /* * Obtain client certificate exchange status. Can be called * any time. Reflects the *last* client certificate state change; * subsequent to a renegotiation attempt by either peer, the state * is reset to kSSLClientCertNone. */ OSStatus SSLGetClientCertificateState (SSLContextRef context, SSLClientCertificateState *clientState) __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_5_0); #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) /* * Specify Diffie-Hellman parameters. Optional; if we are configured to allow * for D-H ciphers and a D-H cipher is negotiated, and this function has not * been called, a set of process-wide parameters will be calculated. However * that can take a long time (30 seconds). * * NOTE: this function is currently not available on iOS. */ OSStatus SSLSetDiffieHellmanParams (SSLContextRef context, const void *dhParams, size_t dhParamsLen) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); /* * Return parameter block specified in SSLSetDiffieHellmanParams. * Returned data is not copied and belongs to the SSLContextRef. * * NOTE: this function is currently not available on iOS. */ OSStatus SSLGetDiffieHellmanParams (SSLContextRef context, const void **dhParams, size_t *dhParamsLen) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); /* * Enable/Disable RSA blinding. This feature thwarts a known timing * attack to which RSA keys are vulnerable; enabling it is a tradeoff * between performance and security. The default for RSA blinding is * enabled. * * ========================== * MAC OS X ONLY (DEPRECATED) * ========================== * NOTE: this function is not available on iOS, and should be considered * deprecated on Mac OS X. RSA blinding is enabled unconditionally, as * it prevents a known way for an attacker to recover the private key, * and the performance gain of disabling it is negligible. */ OSStatus SSLSetRsaBlinding (SSLContextRef context, Boolean blinding) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); OSStatus SSLGetRsaBlinding (SSLContextRef context, Boolean *blinding) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); #endif /* MAC OS X */ /******************************* ******** I/O Functions ******** *******************************/ /* * Note: depending on the configuration of the underlying I/O * connection, all SSL I/O functions can return errSSLWouldBlock, * indicating "not complete, nothing is wrong, except required * I/O hasn't completed". Caller may need to repeat I/Os as necessary * if the underlying connection has been configured to behave in * a non-blocking manner. */ /* * Perform the SSL handshake. On successful return, session is * ready for normal secure application I/O via SSLWrite and SSLRead. * * Interesting error returns: * * errSSLUnknownRootCert: Peer had a valid cert chain, but the root of * the chain is unknown. * * errSSLNoRootCert: Peer had a cert chain which did not end in a root. * * errSSLCertExpired: Peer's cert chain had one or more expired certs. * * errSSLXCertChainInvalid: Peer had an invalid cert chain (i.e., * signature verification within the chain failed, or no certs * were found). * * In all of the above errors, the handshake was aborted; the peer's * cert chain is available via SSLCopyPeerTrust or SSLCopyPeerCertificates. * * Other interesting result codes: * * errSSLPeerAuthCompleted: Peer's cert chain is valid, or was ignored if * cert verification was disabled via SSLSetEnableCertVerify. The application * may decide to continue with the handshake (by calling SSLHandshake * again), or close the connection at this point. * * errSSLClientCertRequested: The server has requested a client certificate. * The client may choose to examine the server's certificate and * distinguished name list, then optionally call SSLSetCertificate prior * to resuming the handshake by calling SSLHandshake again. * * A return value of errSSLWouldBlock indicates that SSLHandshake has to be * called again (and again and again until something else is returned). */ OSStatus SSLHandshake (SSLContextRef context) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * Normal application-level read/write. On both of these, a errSSLWouldBlock * return and a partially completed transfer - or even zero bytes transferred - * are NOT mutually exclusive. */ OSStatus SSLWrite (SSLContextRef context, const void * data, size_t dataLength, size_t *processed) /* RETURNED */ __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * data is mallocd by caller; available size specified in * dataLength; actual number of bytes read returned in * *processed. */ OSStatus SSLRead (SSLContextRef context, void * data, /* RETURNED */ size_t dataLength, size_t *processed) /* RETURNED */ __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * Determine how much data the client can be guaranteed to * obtain via SSLRead() without blocking or causing any low-level * read operations to occur. */ OSStatus SSLGetBufferedReadSize (SSLContextRef context, size_t *bufSize) /* RETURNED */ __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); /* * Determine how much data the application can be guaranteed to write * with SSLWrite() without causing fragmentation. The value is based on * the maximum Datagram Record size defined by the application with * SSLSetMaxDatagramRecordSize(), minus the DTLS Record header size. */ OSStatus SSLGetDatagramWriteSize (SSLContextRef dtlsContext, size_t *bufSize) __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); /* * Terminate current SSL session. */ OSStatus SSLClose (SSLContextRef context) __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); #ifdef __cplusplus } #endif #endif /* !_SECURITY_SECURETRANSPORT_H_ */