OSX/libsecurity_cdsa_utils/lib/cuCdsaUtils.h

   1 /*
   2  * Copyright (c) 2001-2003,2011,2014 Apple Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please
   7  * obtain a copy of the License at http://www.apple.com/publicsource and
   8  * read it before using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  12  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  13  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  14  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  15  * Please see the License for the specific language governing rights and
  16  * limitations under the License.
  17  */
  18
  19 /*
  20         File:            cuCdsaUtils.h
  21
  22         Description: common CDSA access utilities
  23
  24         Author:          dmitch
  25 */
  26
  27 #ifndef _COMMON_CDSA_UTILS_H_
  28 #define _COMMON_CDSA_UTILS_H_
  29
  30 #include <Security/cssm.h>
  31 #include <Security/SecKeychain.h>
  32
  33 #ifdef  __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /* common memory allocators shared by app and CSSM */
  38 extern void * cuAppMalloc (CSSM_SIZE size, void *allocRef);
  39 extern void cuAppFree (void *mem_ptr, void *allocRef);
  40 extern void * cuAppRealloc (void *ptr, CSSM_SIZE size, void *allocRef);
  41 extern void * cuAppCalloc (uint32 num, CSSM_SIZE size, void *allocRef);
  42
  43 #define APP_MALLOC(s)           cuAppMalloc(s, NULL)
  44 #define APP_FREE(p)                     cuAppFree(p, NULL)
  45 #define APP_REALLOC(p, s)       cuAppRealloc(p, s, NULL)
  46 #define APP_CALLOC(n, s)        cuAppRealloc(n, s, NULL)
  47
  48 extern CSSM_BOOL cuCompareCssmData(
  49         const CSSM_DATA *d1,
  50         const CSSM_DATA *d2);
  51
  52 /* OID flavor of same, which will break when an OID is not a CSSM_DATA */
  53 #define cuCompareOid(o1, o2)    cuCompareCssmData(o1, o2)
  54
  55 void cuPrintError(const char *op, CSSM_RETURN err);
  56
  57 /* Init CSSM; returns CSSM_FALSE on error. Reusable. */
  58 extern CSSM_BOOL cuCssmStartup();
  59
  60 /* Attach to CSP. Returns zero on error. */
  61 extern CSSM_CSP_HANDLE cuCspStartup(
  62         CSSM_BOOL bareCsp);                                     // true ==> CSP, false ==> CSP/DL
  63
  64 /* Attach to DL side of CSPDL. */
  65 extern CSSM_DL_HANDLE cuDlStartup();
  66
  67 /* Attach to CL, TP */
  68 extern CSSM_CL_HANDLE cuClStartup();
  69 extern CSSM_TP_HANDLE cuTpStartup();
  70
  71 /* Open a DB, ensure it's empty. */
  72 CSSM_DB_HANDLE cuDbStartup(
  73         CSSM_DL_HANDLE          dlHand,                 // from dlStartup()
  74         const char                      *dbName);
  75
  76 /* Attach to existing DB or create an empty new one. */
  77 CSSM_DB_HANDLE cuDbStartupByName(CSSM_DL_HANDLE dlHand,
  78         char            *dbName,
  79         CSSM_BOOL       doCreate,
  80         CSSM_BOOL       quiet);
  81
  82 /* detach and unload */
  83 CSSM_RETURN cuCspDetachUnload(
  84         CSSM_CSP_HANDLE cspHand,
  85         CSSM_BOOL bareCsp);                                     // true ==> CSP, false ==> CSP/DL
  86 CSSM_RETURN cuClDetachUnload(
  87         CSSM_CL_HANDLE  clHand);
  88 CSSM_RETURN cuDlDetachUnload(
  89         CSSM_DL_HANDLE  dlHand);
  90 CSSM_RETURN cuTpDetachUnload(
  91         CSSM_TP_HANDLE  tpHand);
  92 /*
  93  * Derive symmetric key using PBE.
  94  */
  95 extern CSSM_RETURN cuCspDeriveKey(CSSM_CSP_HANDLE cspHand,
  96                 uint32                          keyAlg,                 // CSSM_ALGID_RC5, etc.
  97                 const char                      *keyLabel,
  98                 unsigned                        keyLabelLen,
  99                 uint32                          keyUsage,               // CSSM_KEYUSE_ENCRYPT, etc.
 100                 uint32                          keySizeInBits,
 101                 CSSM_DATA_PTR           password,               // in PKCS-5 lingo
 102                 CSSM_DATA_PTR           salt,                   // ditto
 103                 uint32                          iterationCnt,   // ditto
 104                 CSSM_KEY_PTR            key);
 105
 106 /*
 107  * Generate key pair of arbitrary algorithm.
 108  */
 109 extern CSSM_RETURN cuCspGenKeyPair(CSSM_CSP_HANDLE cspHand,
 110         CSSM_DL_DB_HANDLE *dlDbHand,    // optional
 111         uint32 algorithm,
 112         const char *keyLabel,
 113         unsigned keyLabelLen,
 114         uint32 keySize,                                 // in bits
 115         CSSM_KEY_PTR pubKey,                    // mallocd by caller
 116         CSSM_KEYUSE pubKeyUsage,                // CSSM_KEYUSE_ENCRYPT, etc.
 117         CSSM_KEYATTR_FLAGS pubAttrs,    // CSSM_KEYATTR_EXTRACTABLE, etc.
 118         CSSM_KEY_PTR privKey,                   // mallocd by caller
 119         CSSM_KEYUSE privKeyUsage,               // CSSM_KEYUSE_DECRYPT, etc.
 120         CSSM_KEYATTR_FLAGS privAttrs);  // CSSM_KEYATTR_EXTRACTABLE, etc.
 121
 122 /* Convert a reference key to a raw key. */
 123 CSSM_RETURN cuRefKeyToRaw(CSSM_CSP_HANDLE cspHand,
 124         const CSSM_KEY                  *refKey,
 125         CSSM_KEY_PTR                    rawKey);                // RETURNED
 126
 127 /*
 128  * Add a certificate to a keychain.
 129  */
 130 CSSM_RETURN cuAddCertToKC(
 131         SecKeychainRef          keychain,
 132         const CSSM_DATA         *cert,
 133         CSSM_CERT_TYPE          certType,
 134         CSSM_CERT_ENCODING      certEncoding,
 135         const char                      *printName,             // C string
 136         const CSSM_DATA         *keyLabel);             // ??
 137
 138 /*
 139  * Convert a CSSM_DATA_PTR, referring to a DER-encoded int, to an
 140  * unsigned.
 141  */
 142 unsigned cuDER_ToInt(
 143         const CSSM_DATA         *DER_Data);
 144
 145 /*
 146  * Verify a CRL against system anchors and intermediate certs.
 147  */
 148 CSSM_RETURN cuCrlVerify(
 149         CSSM_TP_HANDLE                  tpHand,
 150         CSSM_CL_HANDLE                  clHand,
 151         CSSM_CSP_HANDLE                 cspHand,
 152         const CSSM_DATA                 *crlData,
 153         CSSM_DL_DB_HANDLE_PTR   certKeychain,   // intermediate certs
 154         const CSSM_DATA                 *anchors,               // optional - if NULL, use Trust Settings
 155         uint32                                  anchorCount);
 156
 157 #ifdef  __cplusplus
 158 }
 159 #endif
 160
 161 #endif  /* _COMMON_CDSA_UTILS_H_ */