OSX/libsecurity_apple_csp/lib/BinaryKey.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 // BinaryKey.h - CSP-wide BinaryKey base class
  21 //
  22
  23 #ifndef _H_BINARY_KEY_
  24 #define _H_BINARY_KEY_
  25
  26 #include <Security/cssmtype.h>
  27 #include <security_cdsa_utilities/cssmkey.h>
  28
  29 // opaque key reference type
  30 typedef CSSM_INTPTR     KeyRef;
  31
  32 class AppleCSPSession;
  33
  34 /*
  35  * unique blob type passed to generateKeyBlob() for key digest calculation
  36  */
  37 #define CSSM_KEYBLOB_RAW_FORMAT_DIGEST  \
  38         (CSSM_KEYBLOB_RAW_FORMAT_VENDOR_DEFINED + 0x12345)
  39
  40
  41 // frame for Binary key; all modules (BSAFE, CryptKit) must subclass
  42 // this and add a member whose type is the native raw key object.
  43 // Subclasses must implement constructor, destructor, and generateKeyBlob().
  44 class BinaryKey
  45 {
  46 public:
  47                                                 BinaryKey() : mKeyRef(0), mDescData(Allocator::standard()) { }
  48         virtual                         ~BinaryKey() { mKeyRef = 0; }
  49
  50         /*
  51          * Generate raw key blob.
  52          * The format argument is an in/out parameter and is optionally used
  53          * to request a specific keyblob format for providers which can generate
  54          * multipleÊformats. This value comes from an optional
  55          * CSSM_ATTRIBUTE_{PUBLIC,PRIVATE,SYMMETRIC}_KEY_FORMAT attribute in the current
  56          * context. If so such attribute is present, the default value
  57          * CSSM_KEYBLOB_RAW_FORMAT_NONE is specified as the default input param.
  58          *
  59          * All BinaryKeys must handle the special case format
  60          * CSSM_KEYBLOB_RAW_FORMAT_DIGEST, which creates a blob suitable for use
  61          * in calcuating the digest of the key blob.
  62          *
  63          * The session and paramKey arguments facilitate the conversion of a partial
  64          * BinaryKey to a fully formed raw key, i.e., a null wrap to get a fully formed
  65          * raw key. The attrFlags aregument is used to indicate that this operation
  66          * did in fact convert a partial binary key to a fully formed raw key
  67          * (in which case the subclass clears the CSSM_KEYATTR_PARTIAL bit
  68          * in attrFlags before returning).
  69          */
  70         virtual void            generateKeyBlob(
  71                 Allocator               &allocator,
  72                 CssmData                        &blob,
  73                 CSSM_KEYBLOB_FORMAT     &format,        // in/out, CSSM_KEYBLOB_RAW_FORMAT_PKCS1,
  74                                                                                 //   etc.
  75                 AppleCSPSession         &session,
  76                 const CssmKey           *paramKey,      // optional
  77                 CSSM_KEYATTR_FLAGS      &attrFlags)     // IN/OUT
  78
  79                 {
  80                         CssmError::throwMe(CSSMERR_CSP_FUNCTION_NOT_IMPLEMENTED);
  81                 }
  82
  83         CssmKey::Header         mKeyHeader;
  84         KeyRef                          mKeyRef;
  85         const CssmData          &descData()             { return mDescData; }
  86         void                            descData(const CssmData &inDescData)
  87                                                                                 { mDescData.copy(inDescData); }
  88
  89 private:
  90         /* optional DescriptiveData specified by app during WrapKey */
  91         CssmAutoData            mDescData;
  92 };
  93
  94 // Binary key representing a symmetric key.
  95 class SymmetricBinaryKey : public BinaryKey
  96 {
  97 public:
  98         SymmetricBinaryKey(
  99                 unsigned keySizeInBits);
 100         ~SymmetricBinaryKey();
 101         void generateKeyBlob(
 102                 Allocator               &allocator,
 103                 CssmData                        &blob,
 104                 CSSM_KEYBLOB_FORMAT     &format,                /* CSSM_KEYBLOB_RAW_FORMAT_PKCS1, etc. */
 105                 AppleCSPSession         &session,
 106                 const CssmKey           *paramKey,              /* optional, unused here */
 107                 CSSM_KEYATTR_FLAGS      &attrFlags);    /* IN/OUT */
 108
 109         CssmData                        mKeyData;
 110         Allocator               &mAllocator;
 111 };
 112
 113 /*
 114  * Stateless function to cook up a BinaryKey given a
 115  * symmetric CssmKey in RAW format. Returns true on
 116  * success, false if we can't deal with this type of key,
 117  * throws exception on other runtime errors.
 118  */
 119 bool symmetricCssmKeyToBinary(
 120         const CssmKey           &cssmKey,
 121         BinaryKey                       **binKey);      // RETURNED
 122
 123 #endif  // _H_BINARY_KEY_
 124