OSX/libsecurity_pkcs12/lib/pkcs12Crypto.h

   1 /*
   2  * Copyright (c) 2003-2004,2011,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  * p12Crypto.h - PKCS12 Crypto routines.
  26  */
  27
  28 #ifndef _PKCS12_CRYPTO_H_
  29 #define _PKCS12_CRYPTO_H_
  30
  31 #include <Security/Security.h>
  32 #include <security_asn1/SecNssCoder.h>
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /*
  39  * Given appropriate P12-style parameters, cook up a CSSM_KEY.
  40  */
  41 CSSM_RETURN p12KeyGen(
  42         CSSM_CSP_HANDLE         cspHand,
  43         CSSM_KEY                        &key,
  44         bool                            isForEncr,      // true: en/decrypt   false: MAC
  45         CSSM_ALGORITHMS         keyAlg,
  46         CSSM_ALGORITHMS         pbeHashAlg,     // SHA1, MD5 only
  47         uint32                          keySizeInBits,
  48         uint32                          iterCount,
  49         const CSSM_DATA         &salt,
  50
  51         /* exactly one of the following two must be valid */
  52         const CSSM_DATA         *pwd,           // unicode, double null terminated
  53         const CSSM_KEY          *passKey,
  54         CSSM_DATA                       &iv);           // referent is optional
  55
  56 /*
  57  * Decrypt (typically, an encrypted P7 ContentInfo contents or
  58  * a P12 ShroudedKeyBag).
  59  */
  60 CSSM_RETURN p12Decrypt(
  61         CSSM_CSP_HANDLE         cspHand,
  62         const CSSM_DATA         &cipherText,
  63         CSSM_ALGORITHMS         keyAlg,
  64         CSSM_ALGORITHMS         encrAlg,
  65         CSSM_ALGORITHMS         pbeHashAlg,                     // SHA1, MD5 only
  66         uint32                          keySizeInBits,
  67         uint32                          blockSizeInBytes,       // for IV
  68         CSSM_PADDING            padding,                        // CSSM_PADDING_PKCS7, etc.
  69         CSSM_ENCRYPT_MODE       mode,                           // CSSM_ALGMODE_CBCPadIV8, etc.
  70         uint32                          iterCount,
  71         const CSSM_DATA         &salt,
  72         /* exactly one of the following two must be valid */
  73         const CSSM_DATA         *pwd,           // unicode, double null terminated
  74         const CSSM_KEY          *passKey,
  75         SecNssCoder                     &coder,         // for mallocing KeyData and plainText
  76         CSSM_DATA                       &plainText);
  77
  78 /*
  79  * Decrypt (typically, an encrypted P7 ContentInfo contents)
  80  */
  81 CSSM_RETURN p12Encrypt(
  82         CSSM_CSP_HANDLE         cspHand,
  83         const CSSM_DATA         &plainText,
  84         CSSM_ALGORITHMS         keyAlg,
  85         CSSM_ALGORITHMS         encrAlg,
  86         CSSM_ALGORITHMS         pbeHashAlg,                     // SHA1, MD5 only
  87         uint32                          keySizeInBits,
  88         uint32                          blockSizeInBytes,       // for IV
  89         CSSM_PADDING            padding,                        // CSSM_PADDING_PKCS7, etc.
  90         CSSM_ENCRYPT_MODE       mode,                           // CSSM_ALGMODE_CBCPadIV8, etc.
  91         uint32                          iterCount,
  92         const CSSM_DATA         &salt,
  93         const CSSM_DATA         *pwd,           // unicode, double null terminated
  94         const CSSM_KEY          *passKey,
  95         SecNssCoder                     &coder,         // for mallocing cipherText
  96         CSSM_DATA                       &cipherText);
  97
  98 /*
  99  * Calculate the MAC for a PFX. Caller is either going compare
 100  * the result against an existing PFX's MAC or drop the result into
 101  * a newly created PFX.
 102  */
 103 CSSM_RETURN p12GenMac(
 104         CSSM_CSP_HANDLE         cspHand,
 105         const CSSM_DATA         &ptext, // e.g., NSS_P12_DecodedPFX.derAuthSaafe
 106         CSSM_ALGORITHMS         alg,    // better be SHA1!
 107         unsigned                        iterCount,
 108         const CSSM_DATA         &salt,
 109         /* exactly one of the following two must be valid */
 110         const CSSM_DATA         *pwd,           // unicode, double null terminated
 111         const CSSM_KEY          *passKey,
 112         SecNssCoder                     &coder,         // for mallocing macData
 113         CSSM_DATA                       &macData);      // RETURNED
 114
 115 /*
 116  * Unwrap a shrouded key.
 117  */
 118 CSSM_RETURN p12UnwrapKey(
 119         CSSM_CSP_HANDLE         cspHand,
 120         CSSM_DL_DB_HANDLE_PTR   dlDbHand,               // optional
 121         int                                     keyIsPermanent,         // nonzero - store in DB
 122         const CSSM_DATA         &shroudedKeyBits,
 123         CSSM_ALGORITHMS         keyAlg,                         // of the unwrapping key
 124         CSSM_ALGORITHMS         encrAlg,
 125         CSSM_ALGORITHMS         pbeHashAlg,                     // SHA1, MD5 only
 126         uint32                          keySizeInBits,
 127         uint32                          blockSizeInBytes,       // for IV
 128         CSSM_PADDING            padding,                        // CSSM_PADDING_PKCS7, etc.
 129         CSSM_ENCRYPT_MODE       mode,                           // CSSM_ALGMODE_CBCPadIV8, etc.
 130         uint32                          iterCount,
 131         const CSSM_DATA         &salt,
 132         /* exactly one of the following two must be valid */
 133         const CSSM_DATA         *pwd,           // unicode, double null terminated
 134         const CSSM_KEY          *passKey,
 135         SecNssCoder                     &coder,         // for mallocing privKey
 136         const CSSM_DATA         &labelData,
 137         SecAccessRef            access,         // optional; use default ACL if NULL and !noAcl
 138         bool                            noAcl,          // true ==> no ACL
 139         CSSM_KEYUSE                     keyUsage,
 140         CSSM_KEYATTR_FLAGS      keyAttrs,
 141
 142         /*
 143          * Result: a private key, reference format, optionaly stored
 144          * in dlDbHand
 145          */
 146         CSSM_KEY_PTR            &privKey);
 147
 148 CSSM_RETURN p12WrapKey(
 149         CSSM_CSP_HANDLE         cspHand,
 150         CSSM_KEY_PTR            privKey,
 151         const CSSM_ACCESS_CREDENTIALS *privKeyCreds,
 152         CSSM_ALGORITHMS         keyAlg,                         // of the unwrapping key
 153         CSSM_ALGORITHMS         encrAlg,
 154         CSSM_ALGORITHMS         pbeHashAlg,                     // SHA1, MD5 only
 155         uint32                          keySizeInBits,
 156         uint32                          blockSizeInBytes,       // for IV
 157         CSSM_PADDING            padding,                        // CSSM_PADDING_PKCS7, etc.
 158         CSSM_ENCRYPT_MODE       mode,                           // CSSM_ALGMODE_CBCPadIV8, etc.
 159         uint32                          iterCount,
 160         const CSSM_DATA         &salt,
 161         /* exactly one of the following two must be valid */
 162         const CSSM_DATA         *pwd,           // unicode, double null terminated
 163         const CSSM_KEY          *passKey,
 164         SecNssCoder                     &coder,         // for mallocing keyBits
 165         CSSM_DATA                       &shroudedKeyBits);      // RETURNED
 166
 167 #ifdef __cplusplus
 168 }
 169 #endif
 170
 171 #endif  /* _PKCS12_CRYPTO_H_ */
 172