libsecurity_ssl/Security/SecureTransportPriv.h

   1 /*
   2  * Copyright (c) 1999-2001,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  * SecureTransportPriv.h - Apple-private exported routines
  26  */
  27
  28 #ifndef _SECURE_TRANSPORT_PRIV_H_
  29 #define _SECURE_TRANSPORT_PRIV_H_       1
  30
  31 #include <Security/SecureTransport.h>
  32 #include <Security/SecTrust.h>
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /* The size of of client- and server-generated random numbers in hello messages. */
  39 #define SSL_CLIENT_SRVR_RAND_SIZE               32
  40
  41 /* The size of the pre-master and master secrets. */
  42 #define SSL_RSA_PREMASTER_SECRET_SIZE   48
  43 #define SSL_MASTER_SECRET_SIZE                  48
  44
  45 /*
  46  * For the following three functions, *size is the available
  47  * buffer size on entry and the actual size of the data returned
  48  * on return. The above consts are for convenience.
  49  */
  50 OSStatus SSLInternalMasterSecret(
  51    SSLContextRef context,
  52    void *secret,         // mallocd by caller, SSL_MASTER_SECRET_SIZE
  53    size_t *secretSize);  // in/out
  54
  55 OSStatus SSLInternalServerRandom(
  56    SSLContextRef context,
  57    void *randBuf,                       // mallocd by caller, SSL_CLIENT_SRVR_RAND_SIZE
  58    size_t *randSize);   // in/out
  59
  60 OSStatus SSLInternalClientRandom(
  61    SSLContextRef context,
  62    void *randBuf,               // mallocd by caller, SSL_CLIENT_SRVR_RAND_SIZE
  63    size_t *randSize);   // in/out
  64
  65 /*
  66  * Obtain the sizes of the currently negotiated HMAC digest, session
  67  * key, and session key IV.
  68  */
  69 OSStatus SSLGetCipherSizes(
  70         SSLContextRef context,
  71         size_t *digestSize,
  72         size_t *symmetricKeySize,
  73         size_t *ivSize);
  74
  75 OSStatus SSLInternal_PRF(
  76    SSLContextRef context,
  77    const void *secret,
  78    size_t secretLen,
  79    const void *label,
  80    size_t labelLen,
  81    const void *seed,
  82    size_t seedLen,
  83    void *out,                   // mallocd by caller, length >= outLen
  84    size_t outLen);
  85
  86 /*
  87  * Obtain a SecTrustRef representing peer certificates. Valid anytime,
  88  * subsequent to a handshake attempt. The returned SecTrustRef is valid
  89  * only as long as the SSLContextRef is.
  90  */
  91 OSStatus
  92 SSLGetPeerSecTrust                      (SSLContextRef          context,
  93                                                          SecTrustRef            *secTrust);     /* RETURNED */
  94
  95 /*
  96  * Obtain resumable session info. Can be called anytime subsequent to
  97  * handshake attempt.
  98  *
  99  * if sessionWasResumed is True on return, the session is indeed a
 100  * resumed session; the sessionID (an opaque blob generated by the
 101  * server) is returned in *sessionID. The length of the sessionID
 102  * is returned in *sessionIDLength. Caller must allocate the
 103  * sessionID buffer; it max size is MAX_SESSION_ID_LENGTH bytes.
 104  */
 105 #define MAX_SESSION_ID_LENGTH   32
 106
 107 OSStatus
 108 SSLGetResumableSessionInfo      (
 109         SSLContextRef   context,
 110         Boolean                 *sessionWasResumed,             // RETURNED
 111         void                    *sessionID,                             // RETURNED, mallocd by caller
 112         size_t                  *sessionIDLength);              // IN/OUT
 113
 114 /*
 115  * Getters for SSLSetCertificate() and SSLSetEncryptionCertificate()
 116  */
 117 OSStatus
 118 SSLGetCertificate (
 119         SSLContextRef   context,
 120         CFArrayRef              *certRefs);                             // RETURNED, *not* retained
 121
 122 OSStatus
 123 SSLGetEncryptionCertificate (
 124         SSLContextRef   context,
 125         CFArrayRef              *certRefs);                             // RETURNED, *not* retained
 126
 127 /*
 128  * Getter for SSLSetClientSideAuthenticate()
 129  */
 130 OSStatus
 131 SSLGetClientSideAuthenticate (
 132         SSLContextRef   context,
 133         SSLAuthenticate *auth);                                 // RETURNED
 134
 135 /*
 136  * Get/set array of trusted leaf certificates.
 137  *
 138  * If none have been set previously with SSLSetTrustedLeafCertificates(),
 139  * then SSLCopyTrustedLeafCertificates() will return NULL with noErr.
 140  */
 141 OSStatus
 142 SSLSetTrustedLeafCertificates (
 143         SSLContextRef   context,
 144         CFArrayRef              certRefs);
 145
 146 OSStatus
 147 SSLCopyTrustedLeafCertificates (
 148         SSLContextRef   context,
 149         CFArrayRef              *certRefs);                             // RETURNED, caller must release
 150
 151 /*
 152  * Get/set enable of anonymous ciphers. Default is enabled.
 153  *
 154  * SSLSetAllowAnonymousCiphers() returns badReqErr if SSLSetEnabledCiphers()
 155  * has already been called.
 156  *
 157  * The enable state set by SSLSetAllowAnonymousCiphers() is ignored if
 158  * SSLSetEnabledCiphers() is called after SSLSetAllowAnonymousCiphers() is
 159  * called, i.e., SSLSetEnabledCiphers() overrides SSLSetAllowAnonymousCiphers().
 160  *
 161  * NOTE: "Anonymous" ciphers include those ciphers that perform no encryption,
 162  * as well as ciphers that perform no authentication, since neither are secure.
 163  */
 164 OSStatus
 165 SSLSetAllowAnonymousCiphers(
 166         SSLContextRef   context,
 167         Boolean                 enable);
 168
 169 OSStatus
 170 SSLGetAllowAnonymousCiphers(
 171         SSLContextRef   context,
 172         Boolean                 *enable);
 173
 174 /*
 175  * Override the default session cache timeout for a cache entry created for
 176  * the current session.
 177  */
 178 OSStatus
 179 SSLSetSessionCacheTimeout(
 180         SSLContextRef context,
 181         uint32_t timeoutInSeconds);
 182
 183 /*
 184  * Callback function for EAP-style PAC-based session resumption.
 185  * This function is called by SecureTransport to obtain the
 186  * master secret.
 187  */
 188 typedef void (*SSLInternalMasterSecretFunction)(
 189         SSLContextRef ctx,
 190         const void *arg,                /* opaque to SecureTransport; app-specific */
 191         void *secret,                   /* mallocd by caller, SSL_MASTER_SECRET_SIZE */
 192         size_t *secretLength);  /* in/out */
 193
 194 /*
 195  * Register a callback for obtaining the master_secret when performing
 196  * PAC-based session resumption. At the time the callback is called,
 197  * the following are guaranteed to be valid:
 198  *
 199  *  -- serverRandom (via SSLInternalServerRandom())
 200  *  -- clientRandom (via SSLInternalClientRandom())
 201  *  -- negotiated protocol version (via SSLGetNegotiatedProtocolVersion())
 202  *  -- negotiated CipherSuite (via SSLGetNegotiatedCipher())
 203  *
 204  * Currently, PAC-based session resumption is only implemented on
 205  * the client side for Deployment builds.
 206  *
 207  * On the client side, this callback occurs if/when the server sends a
 208  * ChangeCipherSpec message immediately following its ServerHello
 209  * message (i.e., it's skipped the entire Key Exchange phase of
 210  * negotiation).
 211  *
 212  * On the server side (Development builds only) this callback occurs
 213  * immediately upon receipt of the Client Hello message, before we send
 214  * the Server Hello.
 215  */
 216 OSStatus
 217 SSLInternalSetMasterSecretFunction(
 218         SSLContextRef ctx,
 219         SSLInternalMasterSecretFunction mFunc,
 220         const void *arg);               /* opaque to SecureTransport; app-specific */
 221
 222 /*
 223  * Provide an opaque SessionTicket for use in PAC-based session
 224  * resumption. Client side only. The provided ticket is sent in
 225  * the ClientHello message as a SessionTicket extension.
 226  * The maximum ticketLength is 2**16-1.
 227  */
 228 OSStatus SSLInternalSetSessionTicket(
 229    SSLContextRef ctx,
 230    const void *ticket,
 231    size_t ticketLength);
 232
 233 /*
 234  * Support for specifying and obtaining ECC curves, used with the ECDH-based
 235  * ciphersuites.
 236  */
 237
 238 /*
 239  * These are the named curves from RFC 4492
 240  * section 5.1.1, with the exception of SSL_Curve_None which means
 241  * "ECDSA not negotiated".
 242  */
 243 typedef enum
 244 {
 245         SSL_Curve_None = -1,
 246
 247     SSL_Curve_sect163k1 = 1,
 248     SSL_Curve_sect163r1 = 2,
 249     SSL_Curve_sect163r2 = 3,
 250     SSL_Curve_sect193r1 = 4,
 251     SSL_Curve_sect193r2 = 5,
 252     SSL_Curve_sect233k1 = 6,
 253     SSL_Curve_sect233r1 = 7,
 254     SSL_Curve_sect239k1 = 8,
 255     SSL_Curve_sect283k1 = 9,
 256     SSL_Curve_sect283r1 = 10,
 257     SSL_Curve_sect409k1 = 11,
 258     SSL_Curve_sect409r1 = 12,
 259     SSL_Curve_sect571k1 = 13,
 260     SSL_Curve_sect571r1 = 14,
 261     SSL_Curve_secp160k1 = 15,
 262     SSL_Curve_secp160r1 = 16,
 263     SSL_Curve_secp160r2 = 17,
 264     SSL_Curve_secp192k1 = 18,
 265     SSL_Curve_secp192r1 = 19,
 266     SSL_Curve_secp224k1 = 20,
 267     SSL_Curve_secp224r1 = 21,
 268     SSL_Curve_secp256k1 = 22,
 269
 270     /* These are the ones we actually support */
 271         SSL_Curve_secp256r1 = 23,
 272         SSL_Curve_secp384r1 = 24,
 273         SSL_Curve_secp521r1 = 25
 274 } SSL_ECDSA_NamedCurve;
 275
 276 /*
 277  * Obtain the SSL_ECDSA_NamedCurve negotiated during a handshake.
 278  * Returns paramErr if no ECDH-related ciphersuite was negotiated.
 279  */
 280 extern OSStatus SSLGetNegotiatedCurve(
 281    SSLContextRef ctx,
 282    SSL_ECDSA_NamedCurve *namedCurve);    /* RETURNED */
 283
 284 /*
 285  * Obtain the number of currently enabled SSL_ECDSA_NamedCurves.
 286  */
 287 extern OSStatus SSLGetNumberOfECDSACurves(
 288    SSLContextRef ctx,
 289    unsigned *numCurves);                                /* RETURNED */
 290
 291 /*
 292  * Obtain the ordered list of currently enabled SSL_ECDSA_NamedCurves.
 293  * Caller allocates returned array and specifies its size (in
 294  * SSL_ECDSA_NamedCurves) in *numCurves on entry; *numCurves
 295  * is the actual size of the returned array on successful return.
 296  */
 297 extern OSStatus SSLGetECDSACurves(
 298    SSLContextRef ctx,
 299    SSL_ECDSA_NamedCurve *namedCurves,   /* RETURNED */
 300    unsigned *numCurves);                                /* IN/OUT */
 301
 302 /*
 303  * Specify ordered list of allowable named curves.
 304  */
 305 extern OSStatus SSLSetECDSACurves(
 306    SSLContextRef ctx,
 307    const SSL_ECDSA_NamedCurve *namedCurves,
 308    unsigned numCurves);
 309
 310 /*
 311  * Server-specified client authentication mechanisms.
 312  */
 313 typedef enum {
 314         /* doesn't appear on the wire */
 315         SSLClientAuthNone = -1,
 316         /* RFC 2246 7.4.6 */
 317         SSLClientAuth_RSASign = 1,
 318         SSLClientAuth_DSSSign = 2,
 319         SSLClientAuth_RSAFixedDH = 3,
 320         SSLClientAuth_DSS_FixedDH = 4,
 321         /* RFC 4492 5.5 */
 322         SSLClientAuth_ECDSASign = 64,
 323         SSLClientAuth_RSAFixedECDH = 65,
 324         SSLClientAuth_ECDSAFixedECDH = 66
 325 } SSLClientAuthenticationType;
 326
 327 /* TLS 1.2 Signature Algorithms extension values for hash field. */
 328 typedef enum {
 329     SSL_HashAlgorithmNone = 0,
 330     SSL_HashAlgorithmMD5 = 1,
 331     SSL_HashAlgorithmSHA1 = 2,
 332     SSL_HashAlgorithmSHA224 = 3,
 333     SSL_HashAlgorithmSHA256 = 4,
 334     SSL_HashAlgorithmSHA384 = 5,
 335     SSL_HashAlgorithmSHA512 = 6
 336 } SSL_HashAlgorithm;
 337
 338 /* TLS 1.2 Signature Algorithms extension values for signature field. */
 339 typedef enum {
 340     SSL_SignatureAlgorithmAnonymous = 0,
 341     SSL_SignatureAlgorithmRSA = 1,
 342     SSL_SignatureAlgorithmDSA = 2,
 343     SSL_SignatureAlgorithmECDSA = 3
 344 } SSL_SignatureAlgorithm;
 345
 346 typedef struct {
 347     SSL_HashAlgorithm hash;
 348     SSL_SignatureAlgorithm signature;
 349 } SSLSignatureAndHashAlgorithm;
 350
 351 /*
 352  * Obtain the number of client authentication mechanisms specified by
 353  * the server in its Certificate Request message.
 354  * Returns paramErr if server hasn't sent a Certificate Request message
 355  * (i.e., client certificate state is kSSLClientCertNone).
 356  */
 357 extern OSStatus SSLGetNumberOfClientAuthTypes(
 358         SSLContextRef ctx,
 359         unsigned *numTypes);
 360
 361 /*
 362  * Obtain the client authentication mechanisms specified by
 363  * the server in its Certificate Request message.
 364  * Caller allocates returned array and specifies its size (in
 365  * SSLClientAuthenticationTypes) in *numType on entry; *numTypes
 366  * is the actual size of the returned array on successful return.
 367  */
 368 extern OSStatus SSLGetClientAuthTypes(
 369    SSLContextRef ctx,
 370    SSLClientAuthenticationType *authTypes,              /* RETURNED */
 371    unsigned *numTypes);                                                 /* IN/OUT */
 372
 373 /*
 374  * Obtain the SSLClientAuthenticationType actually performed.
 375  * Only valid if client certificate state is kSSLClientCertSent
 376  * or kSSLClientCertRejected; SSLClientAuthNone is returned as
 377  * the negotiated auth type otherwise.
 378  */
 379 extern OSStatus SSLGetNegotiatedClientAuthType(
 380    SSLContextRef ctx,
 381    SSLClientAuthenticationType *authType);              /* RETURNED */
 382
 383 /*
 384  * Obtain the number of supported_signature_algorithms specified by
 385  * the server in its Certificate Request message.
 386  * Returns paramErr if server hasn't sent a Certificate Request message
 387  * (i.e., client certificate state is kSSLClientCertNone).
 388  */
 389 extern OSStatus SSLGetNumberOfSignatureAlgorithms(
 390     SSLContextRef ctx,
 391     unsigned *numSigAlgs);
 392
 393 /*
 394  * Obtain the supported_signature_algorithms specified by
 395  * the server in its Certificate Request message.
 396  * Caller allocates returned array and specifies its size (in
 397  * SSLClientAuthenticationTypes) in *numType on entry; *numTypes
 398  * is the actual size of the returned array on successful return.
 399  */
 400 extern OSStatus SSLGetSignatureAlgorithms(
 401     SSLContextRef ctx,
 402     SSLSignatureAndHashAlgorithm *sigAlgs,              /* RETURNED */
 403     unsigned *numSigAlgs);                                                      /* IN/OUT */
 404
 405 /*
 406  * Create a new Datagram TLS session context.
 407  * Use in place of SSLNewContext to create a DTLS session.
 408  * Deprecated: please use the allocator based functions, when available.
 409  */
 410 OSStatus
 411 SSLNewDatagramContext           (Boolean                        isServer,
 412                              SSLContextRef              *dtlsContextPtr);       /* RETURNED */
 413
 414
 415
 416 /* Private SSL session options */
 417 typedef enum {
 418         /*
 419          * This option can be used to enable sending the first byte
 420          * of application data in its own SSL record in order to
 421          * mitigate a known-IV weakness, a.k.a. the BEAST attack.
 422          */
 423         kSSLSessionOptionSendOneByteRecord = -1
 424 } SSLPrivateSessionOption;
 425
 426 #ifdef __cplusplus
 427 }
 428 #endif
 429
 430 #endif  /* _SECURE_TRANSPORT_PRIV_H_ */