libsecurity_ssl/lib/tls_ssl.h

   1 /*
   2  * Copyright (c) 2002,2005-2007,2010-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  * tls_ssl.h - Declarations of callout struct to provide indirect calls to
  26  *     SSLv3 and TLS routines.
  27  */
  28
  29 #ifndef _TLS_SSL_H_
  30 #define _TLS_SSL_H_
  31
  32 #ifdef  __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 #include "ssl.h"
  37 #include "sslPriv.h"
  38 #include "sslContext.h"
  39 #include "sslRecord.h"
  40 #include "cryptType.h"
  41
  42 /***
  43  *** Each of {TLS, SSLv3} implements each of these functions.
  44  ***/
  45
  46 /* unpack, decrypt, validate one record */
  47 typedef OSStatus (*decryptRecordFcn) (
  48         UInt8 type,
  49         SSLBuffer *payload,
  50         SSLContext *ctx);
  51
  52 /* pack, encrypt, mac, queue one outgoing record */
  53 typedef OSStatus (*writeRecordFcn) (
  54         SSLRecord rec,
  55         SSLContext *ctx);
  56
  57 /* initialize a per-CipherContext HashHmacContext for use in MACing each record */
  58 typedef OSStatus (*initMacFcn) (
  59         CipherContext *cipherCtx,               // macRef, macSecret valid on entry
  60                                                                         // macCtx valid on return
  61         SSLContext *ctx);
  62
  63 /* free per-CipherContext HashHmacContext */
  64 typedef OSStatus (*freeMacFcn) (
  65         CipherContext *cipherCtx);
  66
  67 /* compute MAC on one record */
  68 typedef OSStatus (*computeMacFcn) (
  69         UInt8 type,
  70         SSLBuffer data,
  71         SSLBuffer mac,                                  // caller mallocs data
  72         CipherContext *cipherCtx,               // assumes macCtx, macRef
  73         sslUint64 seqNo,
  74         SSLContext *ctx);
  75
  76 typedef OSStatus (*generateKeyMaterialFcn) (
  77         SSLBuffer key,                                  // caller mallocs and specifies length of
  78                                                                         //   required key material here
  79         SSLContext *ctx);
  80
  81 typedef OSStatus (*generateExportKeyAndIvFcn) (
  82         SSLContext *ctx,                                // clientRandom, serverRandom valid
  83         const SSLBuffer clientWriteKey,
  84         const SSLBuffer serverWriteKey,
  85         SSLBuffer finalClientWriteKey,  // RETURNED, mallocd by caller
  86         SSLBuffer finalServerWriteKey,  // RETURNED, mallocd by caller
  87         SSLBuffer finalClientIV,                // RETURNED, mallocd by caller
  88         SSLBuffer finalServerIV);               // RETURNED, mallocd by caller
  89
  90 /*
  91  * On entry: clientRandom, serverRandom, preMasterSecret valid
  92  * On return: masterSecret valid
  93  */
  94 typedef OSStatus (*generateMasterSecretFcn) (
  95         SSLContext *ctx);
  96
  97 typedef OSStatus (*computeFinishedMacFcn) (
  98         SSLContext *ctx,
  99         SSLBuffer finished,             // output - mallocd by caller
 100         Boolean isServer);
 101
 102 typedef OSStatus (*computeCertVfyMacFcn) (
 103         SSLContext *ctx,
 104     SSLBuffer *finished,                // output - mallocd by caller
 105     SSL_HashAlgorithm hash);    //only used in TLS 1.2
 106
 107 typedef struct _SslTlsCallouts {
 108         decryptRecordFcn                        decryptRecord;
 109         writeRecordFcn                          writeRecord;
 110         initMacFcn                                      initMac;
 111         freeMacFcn                                      freeMac;
 112         computeMacFcn                           computeMac;
 113         generateKeyMaterialFcn          generateKeyMaterial;
 114         generateExportKeyAndIvFcn       generateExportKeyAndIv;
 115         generateMasterSecretFcn         generateMasterSecret;
 116         computeFinishedMacFcn           computeFinishedMac;
 117         computeCertVfyMacFcn            computeCertVfyMac;
 118 } SslTlsCallouts;
 119
 120 /* From ssl3Callouts.c and tls1Callouts.c */
 121 extern const SslTlsCallouts     Ssl3Callouts;
 122 extern const SslTlsCallouts     Tls1Callouts;
 123 extern const SslTlsCallouts Tls12Callouts;
 124
 125 /* one callout routine used in common (for now) */
 126 OSStatus ssl3WriteRecord(
 127         SSLRecord rec,
 128         SSLContext *ctx);
 129
 130 #ifdef  __cplusplus
 131 }
 132 #endif
 133
 134 #endif  /* _TLS_SSL_H_ */