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