1/* 2 * Copyright (c) 1999-2002,2005-2012 Apple Inc. All Rights Reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23 24/* 25 * SecureTransport.h - Public API for Apple SSL/TLS Implementation 26 */ 27 28#ifndef _SECURITY_SECURETRANSPORT_H_ 29#define _SECURITY_SECURETRANSPORT_H_ 30 31/* 32 * This file describes the public API for an implementation of the 33 * Secure Socket Layer, V. 3.0, Transport Layer Security, V. 1.0 to V. 1.2 34 * and Datagram Transport Layer Security V. 1.0 35 * 36 * There are no transport layer dependencies in this library; 37 * it can be used with sockets, Open Transport, etc. Applications using 38 * this library provide callback functions which do the actual I/O 39 * on underlying network connections. Applications are also responsible 40 * for setting up raw network connections; the application passes in 41 * an opaque reference to the underlying (connected) entity at the 42 * start of an SSL session in the form of an SSLConnectionRef. 43 * 44 * Some terminology: 45 * 46 * A "client" is the initiator of an SSL Session. The canonical example 47 * of a client is a web browser, when it's talking to an https URL. 48 * 49 * A "server" is an entity which accepts requests for SSL sessions made 50 * by clients. E.g., a secure web server. 51 52 * An "SSL Session", or "session", is bounded by calls to SSLHandshake() 53 * and SSLClose(). An "Active session" is in some state between these 54 * two calls, inclusive. 55 * 56 * An SSL Session Context, or SSLContextRef, is an opaque reference in this 57 * library to the state associated with one session. A SSLContextRef cannot 58 * be reused for multiple sessions. 59 */ 60 61#include <CoreFoundation/CFArray.h> 62#include <Security/CipherSuite.h> 63#include <Security/SecTrust.h> 64#include <sys/types.h> 65#include <Availability.h> 66 67#ifdef __cplusplus 68extern "C" { 69#endif 70 71/*********************** 72 *** Common typedefs *** 73 ***********************/ 74 75/* Opaque reference to an SSL session context */ 76struct SSLContext; 77typedef struct SSLContext *SSLContextRef; 78 79/* Opaque reference to an I/O connection (socket, endpoint, etc.) */ 80typedef const void * SSLConnectionRef; 81 82/* SSL Protocol version */ 83typedef enum { 84 kSSLProtocolUnknown = 0, /* no protocol negotiated/specified; use default */ 85 kSSLProtocol3 = 2, /* SSL 3.0 */ 86 kTLSProtocol1 = 4, /* TLS 1.0 */ 87 kTLSProtocol11 = 7, /* TLS 1.1 */ 88 kTLSProtocol12 = 8, /* TLS 1.2 */ 89 kDTLSProtocol1 = 9, /* DTLS 1.0 */ 90 91 /* DEPRECATED on iOS */ 92 kSSLProtocol2 = 1, /* SSL 2.0 */ 93 kSSLProtocol3Only = 3, /* SSL 3.0 Only */ 94 kTLSProtocol1Only = 5, /* TLS 1.0 Only */ 95 kSSLProtocolAll = 6, /* All TLS supported protocols */ 96 97} SSLProtocol; 98 99/* SSL session options */ 100typedef enum { 101 /* 102 * Set this option to enable returning from SSLHandshake (with a result of 103 * errSSLServerAuthCompleted) when the server authentication portion of the 104 * handshake is complete. This disable certificate verification and 105 * provides an opportunity to perform application-specific server 106 * verification before deciding to continue. 107 */ 108 kSSLSessionOptionBreakOnServerAuth, 109 /* 110 * Set this option to enable returning from SSLHandshake (with a result of 111 * errSSLClientCertRequested) when the server requests a client certificate. 112 */ 113 kSSLSessionOptionBreakOnCertRequested, 114 /* 115 * This option is the same as kSSLSessionOptionBreakOnServerAuth but applies 116 * to the case where SecureTransport is the server and the client has presented 117 * its certificates allowing the server to verify whether these should be 118 * allowed to authenticate. 119 */ 120 kSSLSessionOptionBreakOnClientAuth, 121 /* 122 * Enable/Disable TLS False Start 123 * When enabled, False Start will only be performed if a adequate cipher-suite is 124 * negotiated. 125 */ 126 kSSLSessionOptionFalseStart, 127 /* 128 * Enable/Disable 1/n-1 record splitting for BEAST attack mitigation. 129 * When enabled, record splitting will only be performed for TLS 1.0 connections 130 * using a block cipher. 131 */ 132 kSSLSessionOptionSendOneByteRecord, 133 /* 134 * Allow/Disallow server identity change on renegotiation. Disallow by default 135 * to avoid Triple Handshake attack. 136 */ 137 kSSLSessionOptionAllowServerIdentityChange, 138 139} SSLSessionOption; 140 141/* State of an SSLSession */ 142typedef enum { 143 kSSLIdle, /* no I/O performed yet */ 144 kSSLHandshake, /* SSL handshake in progress */ 145 kSSLConnected, /* Handshake complete, ready for normal I/O */ 146 kSSLClosed, /* connection closed normally */ 147 kSSLAborted /* connection aborted */ 148} SSLSessionState; 149 150/* 151 * Status of client certificate exchange (which is optional 152 * for both server and client). 153 */ 154typedef enum { 155 /* Server hasn't asked for a cert. Client hasn't sent one. */ 156 kSSLClientCertNone, 157 /* Server has asked for a cert, but client didn't send it. */ 158 kSSLClientCertRequested, 159 /* 160 * Server side: We asked for a cert, client sent one, we validated 161 * it OK. App can inspect the cert via 162 * SSLGetPeerCertificates(). 163 * Client side: server asked for one, we sent it. 164 */ 165 kSSLClientCertSent, 166 /* 167 * Client sent a cert but failed validation. Server side only. 168 * Server app can inspect the cert via SSLGetPeerCertificates(). 169 */ 170 kSSLClientCertRejected 171} SSLClientCertificateState; 172 173/* 174 * R/W functions. The application using this library provides 175 * these functions via SSLSetIOFuncs(). 176 * 177 * Data's memory is allocated by caller; on entry to these two functions 178 * the *length argument indicates both the size of the available data and the 179 * requested byte count. Number of bytes actually transferred is returned in 180 * *length. 181 * 182 * The application may configure the underlying connection to operate 183 * in a non-blocking manner; in such a case, a read operation may 184 * well return errSSLWouldBlock, indicating "I transferred less data than 185 * you requested (maybe even zero bytes), nothing is wrong, except 186 * requested I/O hasn't completed". This will be returned back up to 187 * the application as a return from SSLRead(), SSLWrite(), SSLHandshake(), 188 * etc. 189 */ 190typedef OSStatus 191(*SSLReadFunc) (SSLConnectionRef connection, 192 void *data, /* owned by 193 * caller, data 194 * RETURNED */ 195 size_t *dataLength); /* IN/OUT */ 196typedef OSStatus 197(*SSLWriteFunc) (SSLConnectionRef connection, 198 const void *data, 199 size_t *dataLength); /* IN/OUT */ 200 201 202/************************************************* 203 *** OSStatus values unique to SecureTransport *** 204 *************************************************/ 205 206/* 207 Note: the comments that appear after these errors are used to create SecErrorMessages.strings. 208 The comments must not be multi-line, and should be in a form meaningful to an end user. If 209 a different or additional comment is needed, it can be put in the header doc format, or on a 210 line that does not start with errZZZ. 211*/ 212 213enum { 214 errSSLProtocol = -9800, /* SSL protocol error */ 215 errSSLNegotiation = -9801, /* Cipher Suite negotiation failure */ 216 errSSLFatalAlert = -9802, /* Fatal alert */ 217 errSSLWouldBlock = -9803, /* I/O would block (not fatal) */ 218 errSSLSessionNotFound = -9804, /* attempt to restore an unknown session */ 219 errSSLClosedGraceful = -9805, /* connection closed gracefully */ 220 errSSLClosedAbort = -9806, /* connection closed via error */ 221 errSSLXCertChainInvalid = -9807, /* invalid certificate chain */ 222 errSSLBadCert = -9808, /* bad certificate format */ 223 errSSLCrypto = -9809, /* underlying cryptographic error */ 224 errSSLInternal = -9810, /* Internal error */ 225 errSSLModuleAttach = -9811, /* module attach failure */ 226 errSSLUnknownRootCert = -9812, /* valid cert chain, untrusted root */ 227 errSSLNoRootCert = -9813, /* cert chain not verified by root */ 228 errSSLCertExpired = -9814, /* chain had an expired cert */ 229 errSSLCertNotYetValid = -9815, /* chain had a cert not yet valid */ 230 errSSLClosedNoNotify = -9816, /* server closed session with no notification */ 231 errSSLBufferOverflow = -9817, /* insufficient buffer provided */ 232 errSSLBadCipherSuite = -9818, /* bad SSLCipherSuite */ 233 234 /* fatal errors detected by peer */ 235 errSSLPeerUnexpectedMsg = -9819, /* unexpected message received */ 236 errSSLPeerBadRecordMac = -9820, /* bad MAC */ 237 errSSLPeerDecryptionFail = -9821, /* decryption failed */ 238 errSSLPeerRecordOverflow = -9822, /* record overflow */ 239 errSSLPeerDecompressFail = -9823, /* decompression failure */ 240 errSSLPeerHandshakeFail = -9824, /* handshake failure */ 241 errSSLPeerBadCert = -9825, /* misc. bad certificate */ 242 errSSLPeerUnsupportedCert = -9826, /* bad unsupported cert format */ 243 errSSLPeerCertRevoked = -9827, /* certificate revoked */ 244 errSSLPeerCertExpired = -9828, /* certificate expired */ 245 errSSLPeerCertUnknown = -9829, /* unknown certificate */ 246 errSSLIllegalParam = -9830, /* illegal parameter */ 247 errSSLPeerUnknownCA = -9831, /* unknown Cert Authority */ 248 errSSLPeerAccessDenied = -9832, /* access denied */ 249 errSSLPeerDecodeError = -9833, /* decoding error */ 250 errSSLPeerDecryptError = -9834, /* decryption error */ 251 errSSLPeerExportRestriction = -9835, /* export restriction */ 252 errSSLPeerProtocolVersion = -9836, /* bad protocol version */ 253 errSSLPeerInsufficientSecurity = -9837, /* insufficient security */ 254 errSSLPeerInternalError = -9838, /* internal error */ 255 errSSLPeerUserCancelled = -9839, /* user canceled */ 256 errSSLPeerNoRenegotiation = -9840, /* no renegotiation allowed */ 257 258 /* non-fatal result codes */ 259 errSSLPeerAuthCompleted = -9841, /* peer cert is valid, or was ignored if verification disabled */ 260 errSSLClientCertRequested = -9842, /* server has requested a client cert */ 261 262 /* more errors detected by us */ 263 errSSLHostNameMismatch = -9843, /* peer host name mismatch */ 264 errSSLConnectionRefused = -9844, /* peer dropped connection before responding */ 265 errSSLDecryptionFail = -9845, /* decryption failure */ 266 errSSLBadRecordMac = -9846, /* bad MAC */ 267 errSSLRecordOverflow = -9847, /* record overflow */ 268 errSSLBadConfiguration = -9848, /* configuration error */ 269 errSSLUnexpectedRecord = -9849, /* unexpected (skipped) record in DTLS */ 270}; 271 272/* DEPRECATED aliases for errSSLPeerAuthCompleted */ 273#define errSSLServerAuthCompleted errSSLPeerAuthCompleted 274#define errSSLClientAuthCompleted errSSLPeerAuthCompleted 275 276/* DEPRECATED alias for the end of the error range */ 277#define errSSLLast errSSLUnexpectedRecord 278 279typedef enum 280{ 281 kSSLServerSide, 282 kSSLClientSide 283} SSLProtocolSide; 284 285typedef enum 286{ 287 kSSLStreamType, 288 kSSLDatagramType 289} SSLConnectionType; 290 291/****************** 292 *** Public API *** 293 ******************/ 294 295/* 296 * Secure Transport APIs require a SSLContextRef, which is an opaque 297 * reference to the SSL session and its parameters. On Mac OS X 10.7 298 * and earlier versions, a new context is created using SSLNewContext, 299 * and is disposed by calling SSLDisposeContext. 300 * 301 * On i0S 5.0 and later, as well as Mac OS X versions after 10.7, the 302 * SSLContextRef is a true CFType object with retain-release semantics. 303 * New code should create a new context using SSLCreateContext (instead 304 * of SSLNewContext), and dispose the context by calling CFRelease 305 * (instead of SSLDisposeContext) when finished with it. 306 */ 307 308/* 309 * Return the CFTypeID for SSLContext objects. 310 */ 311CFTypeID 312SSLContextGetTypeID(void) 313 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); 314 315/* 316 * Create a new instance of an SSLContextRef using the specified allocator. 317 */ 318SSLContextRef 319SSLCreateContext(CFAllocatorRef alloc, SSLProtocolSide protocolSide, SSLConnectionType connectionType) 320 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); 321 322 323#if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) 324/* 325 * Create a new session context. 326 * 327 * ========================== 328 * MAC OS X ONLY (DEPRECATED) 329 * ========================== 330 * NOTE: this function is not available on iOS, and should be considered 331 * deprecated on Mac OS X. Your code should use SSLCreateContext instead. 332 */ 333OSStatus 334SSLNewContext (Boolean isServer, 335 SSLContextRef *contextPtr) /* RETURNED */ 336 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); 337 338/* 339 * Dispose of a session context. 340 * 341 * ========================== 342 * MAC OS X ONLY (DEPRECATED) 343 * ========================== 344 * NOTE: this function is not available on iOS, and should be considered 345 * deprecated on Mac OS X. Your code should use CFRelease to dispose a session 346 * created with SSLCreateContext. 347 */ 348OSStatus 349SSLDisposeContext (SSLContextRef context) 350 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); 351 352#endif /* MAC OS X */ 353 354/* 355 * Determine the state of an SSL/DTLS session. 356 */ 357OSStatus 358SSLGetSessionState (SSLContextRef context, 359 SSLSessionState *state) /* RETURNED */ 360 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 361 362/* 363 * Set options for an SSL session. Must be called prior to SSLHandshake(); 364 * subsequently cannot be called while session is active. 365 */ 366OSStatus 367SSLSetSessionOption (SSLContextRef context, 368 SSLSessionOption option, 369 Boolean value) 370 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_5_0); 371 372/* 373 * Determine current value for the specified option in a given SSL session. 374 */ 375OSStatus 376SSLGetSessionOption (SSLContextRef context, 377 SSLSessionOption option, 378 Boolean *value) 379 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_5_0); 380 381/******************************************************************** 382 *** Session context configuration, common to client and servers. *** 383 ********************************************************************/ 384 385/* 386 * Specify functions which do the network I/O. Must be called prior 387 * to SSLHandshake(); subsequently cannot be called while a session is 388 * active. 389 */ 390OSStatus 391SSLSetIOFuncs (SSLContextRef context, 392 SSLReadFunc readFunc, 393 SSLWriteFunc writeFunc) 394 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 395 396/* 397 * Set the minimum SSL protocol version allowed. Optional. 398 * The default is the lower supported protocol. 399 * 400 * This can only be called when no session is active. 401 * 402 * For TLS contexts, legal values for minVersion are : 403 * kSSLProtocol3 404 * kTLSProtocol1 405 * kTLSProtocol11 406 * kTLSProtocol12 407 * 408 * For DTLS contexts, legal values for minVersion are : 409 * kDTLSProtocol1 410 */ 411OSStatus 412SSLSetProtocolVersionMin (SSLContextRef context, 413 SSLProtocol minVersion) 414 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); 415 416/* 417 * Get minimum protocol version allowed 418 */ 419OSStatus 420SSLGetProtocolVersionMin (SSLContextRef context, 421 SSLProtocol *minVersion) 422 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); 423 424/* 425 * Set the maximum SSL protocol version allowed. Optional. 426 * The default is the highest supported protocol. 427 * 428 * This can only be called when no session is active. 429 * 430 * For TLS contexts, legal values for minVersion are : 431 * kSSLProtocol3 432 * kTLSProtocol1 433 * kTLSProtocol11 434 * kTLSProtocol12 435 * 436 * For DTLS contexts, legal values for minVersion are : 437 * kDTLSProtocol1 438 */ 439OSStatus 440SSLSetProtocolVersionMax (SSLContextRef context, 441 SSLProtocol maxVersion) 442 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); 443 444/* 445 * Get maximum protocol version allowed 446 */ 447OSStatus 448SSLGetProtocolVersionMax (SSLContextRef context, 449 SSLProtocol *maxVersion) 450 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); 451 452 453#if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) 454/* 455 * Set allowed SSL protocol versions. Optional. 456 * Specifying kSSLProtocolAll for SSLSetProtocolVersionEnabled results in 457 * specified 'enable' boolean to be applied to all supported protocols. 458 * The default is "all supported protocols are enabled". 459 * This can only be called when no session is active. 460 * 461 * Legal values for protocol are : 462 * kSSLProtocol2 463 * kSSLProtocol3 464 * kTLSProtocol1 465 * kSSLProtocolAll 466 * 467 * ========================== 468 * MAC OS X ONLY (DEPRECATED) 469 * ========================== 470 * NOTE: this function is not available on iOS, and should be considered 471 * deprecated on Mac OS X. You can use SSLSetProtocolVersionMin and/or 472 * SSLSetProtocolVersionMax to specify which protocols are enabled. 473 */ 474OSStatus 475SSLSetProtocolVersionEnabled (SSLContextRef context, 476 SSLProtocol protocol, 477 Boolean enable) 478 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); 479 480/* 481 * Obtain a value specified in SSLSetProtocolVersionEnabled. 482 * 483 * ========================== 484 * MAC OS X ONLY (DEPRECATED) 485 * ========================== 486 * NOTE: this function is not available on iOS, and should be considered 487 * deprecated on Mac OS X. You can use SSLGetProtocolVersionMin and/or 488 * SSLGetProtocolVersionMax to check whether a protocol is enabled. 489 */ 490OSStatus 491SSLGetProtocolVersionEnabled(SSLContextRef context, 492 SSLProtocol protocol, 493 Boolean *enable) /* RETURNED */ 494 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); 495 496/* 497 * Get/set SSL protocol version; optional. Default is kSSLProtocolUnknown, 498 * in which case the highest possible version is attempted, but a lower 499 * version is accepted if the peer requires it. 500 * SSLSetProtocolVersion cannot be called when a session is active. 501 * 502 * ========================== 503 * MAC OS X ONLY (DEPRECATED) 504 * ========================== 505 * NOTE: this function is not available on iOS, and deprecated on Mac OS X 10.8. 506 * Use SSLSetProtocolVersionMin and/or SSLSetProtocolVersionMax to specify 507 * which protocols are enabled. 508 */ 509OSStatus 510SSLSetProtocolVersion (SSLContextRef context, 511 SSLProtocol version) 512 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_8,__IPHONE_NA,__IPHONE_NA); 513 514/* 515 * Obtain the protocol version specified in SSLSetProtocolVersion. 516 * If SSLSetProtocolVersionEnabled() has been called for this session, 517 * SSLGetProtocolVersion() may return errSecParam if the protocol enable 518 * state can not be represented by the SSLProtocol enums (e.g., 519 * SSL2 and TLS1 enabled, SSL3 disabled). 520 * 521 * ========================== 522 * MAC OS X ONLY (DEPRECATED) 523 * ========================== 524 * NOTE: this function is not available on iOS, and deprecated on Mac OS X 10.8. 525 * Use SSLGetProtocolVersionMin and/or SSLGetProtocolVersionMax to check 526 * whether a protocol is enabled. 527 */ 528OSStatus 529SSLGetProtocolVersion (SSLContextRef context, 530 SSLProtocol *protocol) /* RETURNED */ 531 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_8,__IPHONE_NA,__IPHONE_NA); 532 533#endif /* MAC OS X */ 534 535/* 536 * Specify this connection's certificate(s). This is mandatory for 537 * server connections, optional for clients. Specifying a certificate 538 * for a client enables SSL client-side authentication. The end-entity 539 * cert is in certRefs[0]. Specifying a root cert is optional; if it's 540 * not specified, the root cert which verifies the cert chain specified 541 * here must be present in the system-wide set of trusted anchor certs. 542 * 543 * The certRefs argument is a CFArray containing SecCertificateRefs, 544 * except for certRefs[0], which is a SecIdentityRef. 545 * 546 * Must be called prior to SSLHandshake(), or immediately after 547 * SSLHandshake has returned errSSLClientCertRequested (i.e. before the 548 * handshake is resumed by calling SSLHandshake again.) 549 * 550 * SecureTransport assumes the following: 551 * 552 * -- The certRef references remain valid for the lifetime of the session. 553 * -- The certificate specified in certRefs[0] is capable of signing. 554 * -- The required capabilities of the certRef[0], and of the optional cert 555 * specified in SSLSetEncryptionCertificate (see below), are highly 556 * dependent on the application. For example, to work as a server with 557 * Netscape clients, the cert specified here must be capable of both 558 * signing and encrypting. 559 */ 560OSStatus 561SSLSetCertificate (SSLContextRef context, 562 CFArrayRef certRefs) 563 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 564 565/* 566 * Specify I/O connection - a socket, endpoint, etc., which is 567 * managed by caller. On the client side, it's assumed that communication 568 * has been established with the desired server on this connection. 569 * On the server side, it's assumed that an incoming client request 570 * has been established. 571 * 572 * Must be called prior to SSLHandshake(); subsequently can only be 573 * called when no session is active. 574 */ 575OSStatus 576SSLSetConnection (SSLContextRef context, 577 SSLConnectionRef connection) 578 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 579 580OSStatus 581SSLGetConnection (SSLContextRef context, 582 SSLConnectionRef *connection) 583 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 584 585/* 586 * Specify the fully qualified doman name of the peer, e.g., "store.apple.com." 587 * Optional; used to verify the common name field in peer's certificate. 588 * Name is in the form of a C string; NULL termination optional, i.e., 589 * peerName[peerNameLen+1] may or may not have a NULL. In any case peerNameLen 590 * is the number of bytes of the peer domain name. 591 */ 592OSStatus 593SSLSetPeerDomainName (SSLContextRef context, 594 const char *peerName, 595 size_t peerNameLen) 596 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 597 598/* 599 * Determine the buffer size needed for SSLGetPeerDomainName(). 600 */ 601OSStatus 602SSLGetPeerDomainNameLength (SSLContextRef context, 603 size_t *peerNameLen) // RETURNED 604 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 605 606/* 607 * Obtain the value specified in SSLSetPeerDomainName(). 608 */ 609OSStatus 610SSLGetPeerDomainName (SSLContextRef context, 611 char *peerName, // returned here 612 size_t *peerNameLen) // IN/OUT 613 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 614 615/* 616 * Specify the Datagram TLS Hello Cookie. 617 * This is to be called for server side only and is optional. 618 * The default is a zero len cookie. The maximum cookieLen is 32 bytes. 619 */ 620OSStatus 621SSLSetDatagramHelloCookie (SSLContextRef dtlsContext, 622 const void *cookie, 623 size_t cookieLen) 624 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); 625 626/* 627 * Specify the maximum record size, including all DTLS record headers. 628 * This should be set appropriately to avoid fragmentation 629 * of Datagrams during handshake, as fragmented datagrams may 630 * be dropped by some network. 631 * This is for Datagram TLS only 632 */ 633OSStatus 634SSLSetMaxDatagramRecordSize (SSLContextRef dtlsContext, 635 size_t maxSize) 636 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); 637 638/* 639 * Get the maximum record size, including all Datagram TLS record headers. 640 * This is for Datagram TLS only 641 */ 642OSStatus 643SSLGetMaxDatagramRecordSize (SSLContextRef dtlsContext, 644 size_t *maxSize) 645 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); 646 647/* 648 * Obtain the actual negotiated protocol version of the active 649 * session, which may be different that the value specified in 650 * SSLSetProtocolVersion(). Returns kSSLProtocolUnknown if no 651 * SSL session is in progress. 652 */ 653OSStatus 654SSLGetNegotiatedProtocolVersion (SSLContextRef context, 655 SSLProtocol *protocol) /* RETURNED */ 656 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 657 658/* 659 * Determine number and values of all of the SSLCipherSuites we support. 660 * Caller allocates output buffer for SSLGetSupportedCiphers() and passes in 661 * its size in *numCiphers. If supplied buffer is too small, errSSLBufferOverflow 662 * will be returned. 663 */ 664OSStatus 665SSLGetNumberSupportedCiphers (SSLContextRef context, 666 size_t *numCiphers) 667 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 668 669OSStatus 670SSLGetSupportedCiphers (SSLContextRef context, 671 SSLCipherSuite *ciphers, /* RETURNED */ 672 size_t *numCiphers) /* IN/OUT */ 673 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 674 675/* 676 * Specify a (typically) restricted set of SSLCipherSuites to be enabled by 677 * the current SSLContext. Can only be called when no session is active. Default 678 * set of enabled SSLCipherSuites is the same as the complete set of supported 679 * SSLCipherSuites as obtained by SSLGetSupportedCiphers(). 680 */ 681OSStatus 682SSLSetEnabledCiphers (SSLContextRef context, 683 const SSLCipherSuite *ciphers, 684 size_t numCiphers) 685 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 686 687/* 688 * Determine number and values of all of the SSLCipherSuites currently enabled. 689 * Caller allocates output buffer for SSLGetEnabledCiphers() and passes in 690 * its size in *numCiphers. If supplied buffer is too small, errSSLBufferOverflow 691 * will be returned. 692 */ 693OSStatus 694SSLGetNumberEnabledCiphers (SSLContextRef context, 695 size_t *numCiphers) 696 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 697 698OSStatus 699SSLGetEnabledCiphers (SSLContextRef context, 700 SSLCipherSuite *ciphers, /* RETURNED */ 701 size_t *numCiphers) /* IN/OUT */ 702 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 703 704 705#if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) 706/* 707 * Enable/disable peer certificate chain validation. Default is enabled. 708 * If caller disables, it is the caller's responsibility to call 709 * SSLCopyPeerCertificates() upon successful completion of the handshake 710 * and then to perform external validation of the peer certificate 711 * chain before proceeding with data transfer. 712 * 713 * ========================== 714 * MAC OS X ONLY (DEPRECATED) 715 * ========================== 716 * NOTE: this function is not available on iOS, and should be considered 717 * deprecated on Mac OS X. To disable peer certificate chain validation, you 718 * can instead use SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth 719 * to true. This will disable verification and cause SSLHandshake to return with 720 * an errSSLServerAuthCompleted result when the peer certificates have been 721 * received; at that time, you can choose to evaluate peer trust yourself, or 722 * simply call SSLHandshake again to proceed with the handshake. 723 */ 724OSStatus 725SSLSetEnableCertVerify (SSLContextRef context, 726 Boolean enableVerify) 727 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); 728 729/* 730 * Check whether peer certificate chain validation is enabled. 731 * 732 * ========================== 733 * MAC OS X ONLY (DEPRECATED) 734 * ========================== 735 * NOTE: this function is not available on iOS, and should be considered 736 * deprecated on Mac OS X. To check whether peer certificate chain validation 737 * is enabled in a context, call SSLGetSessionOption to obtain the value of 738 * the kSSLSessionOptionBreakOnServerAuth session option flag. If the value 739 * of this option flag is true, then verification is disabled. 740 */ 741OSStatus 742SSLGetEnableCertVerify (SSLContextRef context, 743 Boolean *enableVerify) /* RETURNED */ 744 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); 745 746/* 747 * Specify the option of ignoring certificates' "expired" times. 748 * This is a common failure in the real SSL world. Default setting for this 749 * flag is false, meaning expired certs result in an errSSLCertExpired error. 750 * 751 * ========================== 752 * MAC OS X ONLY (DEPRECATED) 753 * ========================== 754 * NOTE: this function is not available on iOS, and should be considered 755 * deprecated on Mac OS X. To ignore expired certificate errors, first disable 756 * Secure Transport's automatic verification of peer certificates by calling 757 * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When 758 * SSLHandshake subsequently returns an errSSLServerAuthCompleted result, 759 * your code should obtain the SecTrustRef for the peer's certificates and 760 * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h). 761 * The SecTrustSetOptions function allows you to specify that the expiration 762 * status of certificates should be ignored for this evaluation. 763 * 764 * Example: 765 * 766 * status = SSLSetSessionOption(ctx, kSSLSessionOptionBreakOnServerAuth, true); 767 * do { 768 * status = SSLHandshake(ctx); 769 * 770 * if (status == errSSLServerAuthCompleted) { 771 * SecTrustRef peerTrust = NULL; 772 * status = SSLCopyPeerTrust(ctx, &peerTrust); 773 * if (status == errSecSuccess) { 774 * SecTrustResultType trustResult; 775 * // set flag to allow expired certificates 776 * SecTrustSetOptions(peerTrust, kSecTrustOptionAllowExpired); 777 * status = SecTrustEvaluate(peerTrust, &trustResult); 778 * if (status == errSecSuccess) { 779 * // A "proceed" result means the cert is explicitly trusted, 780 * // e.g. "Always Trust" was clicked; 781 * // "Unspecified" means the cert has no explicit trust settings, 782 * // but is implicitly OK since it chains back to a trusted root. 783 * // Any other result means the cert is not trusted. 784 * // 785 * if (trustResult == kSecTrustResultProceed || 786 * trustResult == kSecTrustResultUnspecified) { 787 * // certificate is trusted 788 * status = errSSLWouldBlock; // so we call SSLHandshake again 789 * } else if (trustResult == kSecTrustResultRecoverableTrustFailure) { 790 * // not trusted, for some reason other than being expired; 791 * // could ask the user whether to allow the connection here 792 * // 793 * status = errSSLXCertChainInvalid; 794 * } else { 795 * // cannot use this certificate (fatal) 796 * status = errSSLBadCert; 797 * } 798 * } 799 * if (peerTrust) { 800 * CFRelease(peerTrust); 801 * } 802 * } 803 * } // errSSLServerAuthCompleted 804 * 805 * } while (status == errSSLWouldBlock); 806 * 807 */ 808OSStatus 809SSLSetAllowsExpiredCerts (SSLContextRef context, 810 Boolean allowsExpired) 811 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); 812 813/* 814 * Obtain the current value of an SSLContext's "allowExpiredCerts" flag. 815 * 816 * ========================== 817 * MAC OS X ONLY (DEPRECATED) 818 * ========================== 819 * NOTE: this function is not available on iOS, and should be considered 820 * deprecated on Mac OS X. 821 */ 822OSStatus 823SSLGetAllowsExpiredCerts (SSLContextRef context, 824 Boolean *allowsExpired) /* RETURNED */ 825 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); 826 827/* 828 * Similar to SSLSetAllowsExpiredCerts, SSLSetAllowsExpiredRoots allows the 829 * option of ignoring "expired" status for root certificates only. 830 * Default setting is false, i.e., expired root certs result in an 831 * errSSLCertExpired error. 832 * 833 * ========================== 834 * MAC OS X ONLY (DEPRECATED) 835 * ========================== 836 * NOTE: this function is not available on iOS, and should be considered 837 * deprecated on Mac OS X. To ignore expired certificate errors, first disable 838 * Secure Transport's automatic verification of peer certificates by calling 839 * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When 840 * SSLHandshake subsequently returns an errSSLServerAuthCompleted result, 841 * your code should obtain the SecTrustRef for the peer's certificates and 842 * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h). 843 * The SecTrustSetOptions function allows you to specify that the expiration 844 * status of certificates should be ignored for this evaluation. 845 * 846 * See the description of the SSLSetAllowsExpiredCerts function (above) 847 * for a code example. The kSecTrustOptionAllowExpiredRoot option can be used 848 * instead of kSecTrustOptionAllowExpired to allow expired roots only. 849 */ 850OSStatus 851SSLSetAllowsExpiredRoots (SSLContextRef context, 852 Boolean allowsExpired) 853 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); 854 855/* 856 * Obtain the current value of an SSLContext's "allow expired roots" flag. 857 * 858 * ========================== 859 * MAC OS X ONLY (DEPRECATED) 860 * ========================== 861 * NOTE: this function is not available on iOS, and should be considered 862 * deprecated on Mac OS X. 863 */ 864OSStatus 865SSLGetAllowsExpiredRoots (SSLContextRef context, 866 Boolean *allowsExpired) /* RETURNED */ 867 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); 868 869/* 870 * Specify option of allowing for an unknown root cert, i.e., one which 871 * this software can not verify as one of a list of known good root certs. 872 * Default for this flag is false, in which case one of the following two 873 * errors may occur: 874 * -- The peer returns a cert chain with a root cert, and the chain 875 * verifies to that root, but the root is not one of our trusted 876 * roots. This results in errSSLUnknownRootCert on handshake. 877 * -- The peer returns a cert chain which does not contain a root cert, 878 * and we can't verify the chain to one of our trusted roots. This 879 * results in errSSLNoRootCert on handshake. 880 * 881 * Both of these error conditions are ignored when the AllowAnyRoot flag is 882 * true, allowing connection to a totally untrusted peer. 883 * 884 * ========================== 885 * MAC OS X ONLY (DEPRECATED) 886 * ========================== 887 * NOTE: this function is not available on iOS, and should be considered 888 * deprecated on Mac OS X. To ignore unknown root cert errors, first disable 889 * Secure Transport's automatic verification of peer certificates by calling 890 * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When 891 * SSLHandshake subsequently returns an errSSLServerAuthCompleted result, 892 * your code should obtain the SecTrustRef for the peer's certificates and 893 * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h). 894 * 895 * See the description of the SSLSetAllowsExpiredCerts function (above) 896 * for a code example. Note that an unknown root certificate will cause 897 * SecTrustEvaluate to report kSecTrustResultRecoverableTrustFailure as the 898 * trust result. 899 */ 900OSStatus 901SSLSetAllowsAnyRoot (SSLContextRef context, 902 Boolean anyRoot) 903 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); 904 905/* 906 * Obtain the current value of an SSLContext's "allow any root" flag. 907 * 908 * ========================== 909 * MAC OS X ONLY (DEPRECATED) 910 * ========================== 911 * NOTE: this function is not available on iOS, and should be considered 912 * deprecated on Mac OS X. 913 */ 914OSStatus 915SSLGetAllowsAnyRoot (SSLContextRef context, 916 Boolean *anyRoot) /* RETURNED */ 917 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); 918 919/* 920 * Augment or replace the system's default trusted root certificate set 921 * for this session. If replaceExisting is true, the specified roots will 922 * be the only roots which are trusted during this session. If replaceExisting 923 * is false, the specified roots will be added to the current set of trusted 924 * root certs. If this function has never been called, the current trusted 925 * root set is the same as the system's default trusted root set. 926 * Successive calls with replaceExisting false result in accumulation 927 * of additional root certs. 928 * 929 * The trustedRoots array contains SecCertificateRefs. 930 * 931 * ========================== 932 * MAC OS X ONLY (DEPRECATED) 933 * ========================== 934 * NOTE: this function is not available on iOS, and should be considered 935 * deprecated on Mac OS X. To trust specific roots in a session, first disable 936 * Secure Transport's automatic verification of peer certificates by calling 937 * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. When 938 * SSLHandshake subsequently returns an errSSLServerAuthCompleted result, 939 * your code should obtain the SecTrustRef for the peer's certificates and 940 * perform a custom trust evaluation with SecTrust APIs (see SecTrust.h). 941 * 942 * See the description of the SSLSetAllowsExpiredCerts function (above) 943 * for a code example. You can call SecTrustSetAnchorCertificates to 944 * augment the system's trusted root set, or SecTrustSetAnchorCertificatesOnly 945 * to make these the only trusted roots, prior to calling SecTrustEvaluate. 946 */ 947OSStatus 948SSLSetTrustedRoots (SSLContextRef context, 949 CFArrayRef trustedRoots, 950 Boolean replaceExisting) 951 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); 952 953/* 954 * Obtain an array of SecCertificateRefs representing the current 955 * set of trusted roots. If SSLSetTrustedRoots() has never been called 956 * for this session, this returns the system's default root set. 957 * 958 * Caller must CFRelease the returned CFArray. 959 * 960 * ========================== 961 * MAC OS X ONLY (DEPRECATED) 962 * ========================== 963 * NOTE: this function is not available on iOS, and should be considered 964 * deprecated on Mac OS X. To get the current set of trusted roots, call the 965 * SSLCopyPeerTrust function to obtain the SecTrustRef for the peer certificate 966 * chain, then SecTrustCopyCustomAnchorCertificates (see SecTrust.h). 967 */ 968OSStatus 969SSLCopyTrustedRoots (SSLContextRef context, 970 CFArrayRef *trustedRoots) /* RETURNED */ 971 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); 972 973/* 974 * Request peer certificates. Valid anytime, subsequent to a handshake attempt. 975 * 976 * The certs argument is a CFArray containing SecCertificateRefs. 977 * Caller must CFRelease the returned array. 978 * 979 * The cert at index 0 of the returned array is the subject (end 980 * entity) cert; the root cert (or the closest cert to it) is at 981 * the end of the returned array. 982 * 983 * ========================== 984 * MAC OS X ONLY (DEPRECATED) 985 * ========================== 986 * NOTE: this function is not available on iOS, and should be considered 987 * deprecated on Mac OS X. To get peer certificates, call SSLCopyPeerTrust 988 * to obtain the SecTrustRef for the peer certificate chain, then use the 989 * SecTrustGetCertificateCount and SecTrustGetCertificateAtIndex functions 990 * to retrieve individual certificates in the chain (see SecTrust.h). 991 */ 992OSStatus 993SSLCopyPeerCertificates (SSLContextRef context, 994 CFArrayRef *certs) /* RETURNED */ 995 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_5,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); 996 997#endif /* MAC OS X */ 998 999/* 1000 * Obtain a SecTrustRef representing peer certificates. Valid anytime, 1001 * subsequent to a handshake attempt. Caller must CFRelease the returned 1002 * trust reference. 1003 * 1004 * The returned trust reference will have already been evaluated for you, 1005 * unless one of the following is true: 1006 * - Your code has disabled automatic certificate verification, by calling 1007 * SSLSetSessionOption to set kSSLSessionOptionBreakOnServerAuth to true. 1008 * - Your code has called SSLSetPeerID, and this session has been resumed 1009 * from an earlier cached session. 1010 * 1011 * In these cases, your code should call SecTrustEvaluate prior to 1012 * examining the peer certificate chain or trust results (see SecTrust.h). 1013 * 1014 * NOTE: if you have not called SSLHandshake at least once prior to 1015 * calling this function, the returned trust reference will be NULL. 1016 */ 1017OSStatus 1018SSLCopyPeerTrust (SSLContextRef context, 1019 SecTrustRef *trust) /* RETURNED */ 1020 __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_5_0); 1021 1022/* 1023 * Specify some data, opaque to this library, which is sufficient 1024 * to uniquely identify the peer of the current session. An example 1025 * would be IP address and port, stored in some caller-private manner. 1026 * To be optionally called prior to SSLHandshake for the current 1027 * session. This is mandatory if this session is to be resumable. 1028 * 1029 * SecureTransport allocates its own copy of the incoming peerID. The 1030 * data provided in *peerID, while opaque to SecureTransport, is used 1031 * in a byte-for-byte compare to other previous peerID values set by the 1032 * current application. Matching peerID blobs result in SecureTransport 1033 * attempting to resume an SSL session with the same parameters as used 1034 * in the previous session which specified the same peerID bytes. 1035 */ 1036OSStatus 1037SSLSetPeerID (SSLContextRef context, 1038 const void *peerID, 1039 size_t peerIDLen) 1040 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 1041 1042/* 1043 * Obtain current PeerID. Returns NULL pointer, zero length if 1044 * SSLSetPeerID has not been called for this context. 1045 */ 1046OSStatus 1047SSLGetPeerID (SSLContextRef context, 1048 const void **peerID, 1049 size_t *peerIDLen) 1050 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 1051 1052/* 1053 * Obtain the SSLCipherSuite (e.g., SSL_RSA_WITH_DES_CBC_SHA) negotiated 1054 * for this session. Only valid when a session is active. 1055 */ 1056OSStatus 1057SSLGetNegotiatedCipher (SSLContextRef context, 1058 SSLCipherSuite *cipherSuite) 1059 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 1060 1061 1062/******************************************************** 1063 *** Session context configuration, server side only. *** 1064 ********************************************************/ 1065 1066/* 1067 * Specify this connection's encryption certificate(s). This is 1068 * used in one of the following cases: 1069 * 1070 * -- The end-entity certificate specified in SSLSetCertificate() is 1071 * not capable of encryption. 1072 * 1073 * -- The end-entity certificate specified in SSLSetCertificate() 1074 * contains a key which is too large (i.e., too strong) for legal 1075 * encryption in this session. In this case a weaker cert is 1076 * specified here and is used for server-initiated key exchange. 1077 * 1078 * The certRefs argument is a CFArray containing SecCertificateRefs, 1079 * except for certRefs[0], which is a SecIdentityRef. 1080 * 1081 * The following assumptions are made: 1082 * 1083 * -- The certRefs references remains valid for the lifetime of the 1084 * connection. 1085 * -- The specified certRefs[0] is capable of encryption. 1086 * 1087 * Can only be called when no session is active. 1088 * 1089 * Notes: 1090 * ------ 1091 * 1092 * -- SSL servers which enforce the SSL3 spec to the letter will 1093 * not accept encryption certs with RSA keys larger than 512 1094 * bits for exportable ciphers. Apps which wish to use encryption 1095 * certs with key sizes larger than 512 bits should disable the 1096 * use of exportable ciphers via the SSLSetEnabledCiphers() call. 1097 */ 1098OSStatus 1099SSLSetEncryptionCertificate (SSLContextRef context, 1100 CFArrayRef certRefs) 1101 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 1102 1103/* 1104 * Specify requirements for client-side authentication. 1105 * Optional; Default is kNeverAuthenticate. 1106 * 1107 * Can only be called when no session is active. 1108 */ 1109typedef enum { 1110 kNeverAuthenticate, /* skip client authentication */ 1111 kAlwaysAuthenticate, /* require it */ 1112 kTryAuthenticate /* try to authenticate, but not an error 1113 * if client doesn't have a cert */ 1114} SSLAuthenticate; 1115 1116OSStatus 1117SSLSetClientSideAuthenticate (SSLContextRef context, 1118 SSLAuthenticate auth) 1119 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 1120 1121/* 1122 * Add a DER-encoded distinguished name to list of acceptable names 1123 * to be specified in requests for client certificates. 1124 */ 1125OSStatus 1126SSLAddDistinguishedName (SSLContextRef context, 1127 const void *derDN, 1128 size_t derDNLen) 1129 __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_5_0); 1130 1131 1132#if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) 1133/* 1134 * Add a SecCertificateRef, or a CFArray of them, to a server's list 1135 * of acceptable Certificate Authorities (CAs) to present to the client 1136 * when client authentication is performed. 1137 * 1138 * If replaceExisting is true, the specified certificate(s) will replace 1139 * a possible existing list of acceptable CAs. If replaceExisting is 1140 * false, the specified certificate(s) will be appended to the existing 1141 * list of acceptable CAs, if any. 1142 * 1143 * Returns errSecParam if this is called on a SSLContextRef which 1144 * is configured as a client, or when a session is active. 1145 * 1146 * NOTE: this function is currently not available on iOS. 1147 */ 1148OSStatus 1149SSLSetCertificateAuthorities(SSLContextRef context, 1150 CFTypeRef certificateOrArray, 1151 Boolean replaceExisting) 1152 __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA); 1153 1154/* 1155 * Obtain the certificates specified in SSLSetCertificateAuthorities(), 1156 * if any. Returns a NULL array if SSLSetCertificateAuthorities() has not 1157 * been called. 1158 * Caller must CFRelease the returned array. 1159 * 1160 * NOTE: this function is currently not available on iOS. 1161 */ 1162OSStatus 1163SSLCopyCertificateAuthorities(SSLContextRef context, 1164 CFArrayRef *certificates) /* RETURNED */ 1165 __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA); 1166 1167#endif /* MAC OS X */ 1168 1169/* 1170 * Obtain the list of acceptable distinguished names as provided by 1171 * a server (if the SSLContextRef is configured as a client), or as 1172 * specified by SSLSetCertificateAuthorities (if the SSLContextRef 1173 * is configured as a server). 1174 * The returned array contains CFDataRefs, each of which represents 1175 * one DER-encoded RDN. 1176 * 1177 * Caller must CFRelease the returned array. 1178 */ 1179OSStatus 1180SSLCopyDistinguishedNames (SSLContextRef context, 1181 CFArrayRef *names) 1182 __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_5_0); 1183 1184/* 1185 * Obtain client certificate exchange status. Can be called 1186 * any time. Reflects the *last* client certificate state change; 1187 * subsequent to a renegotiation attempt by either peer, the state 1188 * is reset to kSSLClientCertNone. 1189 */ 1190OSStatus 1191SSLGetClientCertificateState (SSLContextRef context, 1192 SSLClientCertificateState *clientState) 1193 __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_5_0); 1194 1195 1196#if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) 1197/* 1198 * Specify Diffie-Hellman parameters. Optional; if we are configured to allow 1199 * for D-H ciphers and a D-H cipher is negotiated, and this function has not 1200 * been called, a set of process-wide parameters will be calculated. However 1201 * that can take a long time (30 seconds). 1202 * 1203 * NOTE: this function is currently not available on iOS. 1204 */ 1205OSStatus SSLSetDiffieHellmanParams (SSLContextRef context, 1206 const void *dhParams, 1207 size_t dhParamsLen) 1208 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); 1209 1210/* 1211 * Return parameter block specified in SSLSetDiffieHellmanParams. 1212 * Returned data is not copied and belongs to the SSLContextRef. 1213 * 1214 * NOTE: this function is currently not available on iOS. 1215 */ 1216OSStatus SSLGetDiffieHellmanParams (SSLContextRef context, 1217 const void **dhParams, 1218 size_t *dhParamsLen) 1219 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA); 1220 1221/* 1222 * Enable/Disable RSA blinding. This feature thwarts a known timing 1223 * attack to which RSA keys are vulnerable; enabling it is a tradeoff 1224 * between performance and security. The default for RSA blinding is 1225 * enabled. 1226 * 1227 * ========================== 1228 * MAC OS X ONLY (DEPRECATED) 1229 * ========================== 1230 * NOTE: this function is not available on iOS, and should be considered 1231 * deprecated on Mac OS X. RSA blinding is enabled unconditionally, as 1232 * it prevents a known way for an attacker to recover the private key, 1233 * and the performance gain of disabling it is negligible. 1234 */ 1235OSStatus SSLSetRsaBlinding (SSLContextRef context, 1236 Boolean blinding) 1237 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); 1238 1239OSStatus SSLGetRsaBlinding (SSLContextRef context, 1240 Boolean *blinding) 1241 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2,__MAC_10_9,__IPHONE_NA,__IPHONE_NA); 1242 1243#endif /* MAC OS X */ 1244 1245/******************************* 1246 ******** I/O Functions ******** 1247 *******************************/ 1248 1249/* 1250 * Note: depending on the configuration of the underlying I/O 1251 * connection, all SSL I/O functions can return errSSLWouldBlock, 1252 * indicating "not complete, nothing is wrong, except required 1253 * I/O hasn't completed". Caller may need to repeat I/Os as necessary 1254 * if the underlying connection has been configured to behave in 1255 * a non-blocking manner. 1256 */ 1257 1258/* 1259 * Perform the SSL handshake. On successful return, session is 1260 * ready for normal secure application I/O via SSLWrite and SSLRead. 1261 * 1262 * Interesting error returns: 1263 * 1264 * errSSLUnknownRootCert: Peer had a valid cert chain, but the root of 1265 * the chain is unknown. 1266 * 1267 * errSSLNoRootCert: Peer had a cert chain which did not end in a root. 1268 * 1269 * errSSLCertExpired: Peer's cert chain had one or more expired certs. 1270 * 1271 * errSSLXCertChainInvalid: Peer had an invalid cert chain (i.e., 1272 * signature verification within the chain failed, or no certs 1273 * were found). 1274 * 1275 * In all of the above errors, the handshake was aborted; the peer's 1276 * cert chain is available via SSLCopyPeerTrust or SSLCopyPeerCertificates. 1277 * 1278 * Other interesting result codes: 1279 * 1280 * errSSLPeerAuthCompleted: Peer's cert chain is valid, or was ignored if 1281 * cert verification was disabled via SSLSetEnableCertVerify. The application 1282 * may decide to continue with the handshake (by calling SSLHandshake 1283 * again), or close the connection at this point. 1284 * 1285 * errSSLClientCertRequested: The server has requested a client certificate. 1286 * The client may choose to examine the server's certificate and 1287 * distinguished name list, then optionally call SSLSetCertificate prior 1288 * to resuming the handshake by calling SSLHandshake again. 1289 * 1290 * A return value of errSSLWouldBlock indicates that SSLHandshake has to be 1291 * called again (and again and again until something else is returned). 1292 */ 1293OSStatus 1294SSLHandshake (SSLContextRef context) 1295 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 1296 1297/* 1298 * Normal application-level read/write. On both of these, a errSSLWouldBlock 1299 * return and a partially completed transfer - or even zero bytes transferred - 1300 * are NOT mutually exclusive. 1301 */ 1302OSStatus 1303SSLWrite (SSLContextRef context, 1304 const void * data, 1305 size_t dataLength, 1306 size_t *processed) /* RETURNED */ 1307 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 1308 1309/* 1310 * data is mallocd by caller; available size specified in 1311 * dataLength; actual number of bytes read returned in 1312 * *processed. 1313 */ 1314OSStatus 1315SSLRead (SSLContextRef context, 1316 void * data, /* RETURNED */ 1317 size_t dataLength, 1318 size_t *processed) /* RETURNED */ 1319 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 1320 1321/* 1322 * Determine how much data the client can be guaranteed to 1323 * obtain via SSLRead() without blocking or causing any low-level 1324 * read operations to occur. 1325 */ 1326OSStatus 1327SSLGetBufferedReadSize (SSLContextRef context, 1328 size_t *bufSize) /* RETURNED */ 1329 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 1330 1331/* 1332 * Determine how much data the application can be guaranteed to write 1333 * with SSLWrite() without causing fragmentation. The value is based on 1334 * the maximum Datagram Record size defined by the application with 1335 * SSLSetMaxDatagramRecordSize(), minus the DTLS Record header size. 1336 */ 1337OSStatus 1338SSLGetDatagramWriteSize (SSLContextRef dtlsContext, 1339 size_t *bufSize) 1340 __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_5_0); 1341 1342/* 1343 * Terminate current SSL session. 1344 */ 1345OSStatus 1346SSLClose (SSLContextRef context) 1347 __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_5_0); 1348 1349#ifdef __cplusplus 1350} 1351#endif 1352 1353#endif /* !_SECURITY_SECURETRANSPORT_H_ */ 1354