AppleCSP/AppleCSP/AppleCSPUtils.h

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