OSX/libsecurity_apple_csp/lib/AppleCSPUtils.h

   1 /*
   2  * Copyright (c) 2000-2001,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 obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * 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 EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18
  19 //
  20 // AppleCSPUtils.h - CSP-wide utility functions
  21 //
  22
  23 #ifndef _H_APPLE_CSP_UTILS
  24 #define _H_APPLE_CSP_UTILS
  25
  26 #include "cspdebugging.h"
  27 #include <Security/cssmtype.h>
  28 #include <security_utilities/alloc.h>
  29 #include <security_cdsa_utilities/context.h>
  30
  31 #ifdef  __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /* Key type */
  36 typedef enum {
  37         CKT_Session,
  38         CKT_Private,
  39         CKT_Public
  40 } cspKeyType;
  41
  42 /* Key storage type returned from cspParseKeyAttr() */
  43 typedef enum {
  44          CKS_Ref,
  45          CKS_Data,
  46          CKS_None
  47 } cspKeyStorage;
  48
  49 #define KEY_ATTR_RETURN_MASK    (CSSM_KEYATTR_RETURN_DATA |             \
  50                                                                  CSSM_KEYATTR_RETURN_REF  |             \
  51                                                                  CSSM_KEYATTR_RETURN_NONE)
  52
  53 /*
  54  * Validate key attribute bits per specified key type.
  55  *
  56  * Used to check requested key attributes for new keys and for validating
  57  * incoming existing keys. For checking key attributes for new keys,
  58  * assumes that KEYATTR_RETURN_xxx bits have been checked elsewhere
  59  * and stripped off before coming here.
  60  */
  61 void cspValidateKeyAttr(
  62         cspKeyType      keyType,
  63         uint32          keyAttr);
  64
  65 /*
  66  * Perform sanity check of incoming key attribute bits for a given
  67  * key type, and return a malKeyStorage value.
  68  *
  69  * Called from any routine which generates a new key. This specifically
  70  * excludes WrapKey().
  71  */
  72 cspKeyStorage cspParseKeyAttr(
  73         cspKeyType      keyType,
  74         uint32          keyAttr);
  75
  76 /*
  77  * Validate key usage bits for specified key type.
  78  */
  79 void cspValidateKeyUsageBits (
  80         cspKeyType      keyType,
  81         uint32          keyUsage);
  82
  83 /*
  84  * Validate existing key's usage bits against intended use.
  85  */
  86 void cspValidateIntendedKeyUsage(
  87         const CSSM_KEYHEADER    *hdr,
  88         CSSM_KEYUSE                             intendedUsage);
  89
  90 /*
  91  * Set up a key header.
  92  */
  93 void setKeyHeader(
  94         CSSM_KEYHEADER &hdr,
  95         const Guid &myGuid,
  96         CSSM_ALGORITHMS alg,
  97         CSSM_KEYCLASS keyClass,
  98         CSSM_KEYATTR_FLAGS attrs,
  99         CSSM_KEYUSE use);
 100
 101 /*
 102  * Ensure that indicated CssmData can handle 'length' bytes
 103  * of data. Malloc the Data ptr if necessary.
 104  */
 105 void setUpCssmData(
 106         CssmData                        &data,
 107         size_t                          length,
 108         Allocator               &allocator);
 109
 110 void setUpData(
 111         CSSM_DATA                       &data,
 112         size_t                          length,
 113         Allocator               &allocator);
 114
 115 void freeCssmData(
 116         CssmData                        &data,
 117         Allocator               &allocator);
 118
 119 void freeData(
 120         CSSM_DATA                       *data,
 121         Allocator               &allocator,
 122         bool                            freeStruct);            // free the CSSM_DATA itself
 123
 124 /*
 125  * Copy source to destination, mallocing destination if necessary.
 126  */
 127 void copyCssmData(
 128         const CssmData          &src,
 129         CssmData                        &dst,
 130         Allocator               &allocator);
 131
 132 void copyData(
 133         const CSSM_DATA         &src,
 134         CSSM_DATA                       &dst,
 135         Allocator               &allocator);
 136
 137 /*
 138  * Compare two CSSM_DATAs, return CSSM_TRUE if identical.
 139  */
 140 CSSM_BOOL cspCompareCssmData(
 141         const CSSM_DATA         *data1,
 142         const CSSM_DATA         *data2);
 143
 144 /*
 145  * This takes care of mallocing the and KeyLabel field.
 146  */
 147 void copyCssmHeader(
 148         const CssmKey::Header   &src,
 149         CssmKey::Header                 &dst,
 150         Allocator                       &allocator);
 151
 152 /*
 153  * Given a wrapped key, infer its raw format.
 154  * This is a real kludge; it only works as long as each {algorithm, keyClass}
 155  * maps to exactly one format.
 156  */
 157 CSSM_KEYBLOB_FORMAT inferFormat(
 158         const CssmKey   &wrappedKey);
 159
 160 /*
 161  * Given a key and a Context, obtain the optional associated
 162  * CSSM_ATTRIBUTE_{PUBLIC,PRIVATE,SYMMETRIC}_KEY_FORMAT attribute as a
 163  * CSSM_KEYBLOB_FORMAT.
 164  */
 165 CSSM_KEYBLOB_FORMAT requestedKeyFormat(
 166         const Context   &context,
 167         const CssmKey   &key);
 168
 169 /* stateless function to calculate SHA-1 hash of a blob */
 170
 171 #define SHA1_DIGEST_SIZE        20
 172 void cspGenSha1Hash(
 173         const void              *inData,
 174         size_t                  inDataLen,
 175         void                    *out);                  // caller mallocs, digest goes here
 176
 177 void cspVerifyKeyTimes(
 178         const CSSM_KEYHEADER &hdr);
 179
 180 #ifdef  __cplusplus
 181 }
 182 #endif
 183
 184 #endif  //  _H_APPLE_CSP_UTILS