libsecurity_apple_csp/lib/BlockCryptor.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  * BlockCryptor.h - common context for block-oriented encryption algorithms
  21  *
  22  * Created March 5 2001 by dmitch
  23  */
  24
  25 #ifndef _BLOCK_CRYPTOR_H_
  26 #define _BLOCK_CRYPTOR_H_
  27
  28 #include "AppleCSPContext.h"
  29 #include <CoreServices/../Frameworks/CarbonCore.framework/Headers/MacTypes.h>
  30
  31 /*
  32  * Base class for AppleCSPContexts associated with BlockCryptObjects.
  33  * The main purpose of this class is to abstract out the very common work
  34  * of buffering incoming data (per CSSM-style update, ..., final) and
  35  * doing single-block ops on the underlying encrypt/decrypt algorithm
  36  * objects. Standard PKSC5 padding is handled here. All other chaining,
  37  * padding, IV, et al, logic is handled by subclasses.
  38  */
  39 class BlockCryptor : public AppleCSPContext
  40 {
  41 public:
  42         BlockCryptor(
  43                 AppleCSPSession &session) :
  44                         AppleCSPContext(session),
  45                         mOpStarted(false),
  46                         mCbcCapable(false),
  47                         mMultiBlockCapable(false),
  48                         mInBuf(NULL),
  49                         mChainBuf(NULL) { }
  50         virtual ~BlockCryptor();
  51
  52         /*
  53          * Note standard init(const Context &context, bool encoding) is totally
  54          * subclass-specific.
  55          *
  56          * These are implemented here using the subclass's {en,de}cryptBlock functions.
  57          * Note PKCS5 padding is implemented here if mPkcs5Padding is true. PKCS5
  58          * padding can only be accomplished if the result of decrypting
  59          * cipherBlockSize() bytes of ciphertext yields exactly plainBlockSize()
  60          * bytes of plaintext. (Sound odd? FEED does not meet that restriction...)
  61          */
  62         void update(
  63                 void                    *inp,
  64                 size_t                  &inSize,                        // in/out
  65                 void                    *outp,
  66                 size_t                  &outSize);                      // in/out
  67
  68         void final(
  69                 CssmData                &out);
  70
  71         /*
  72          * Our implementation of these three query functions are only valid
  73          * for algorithms for which encrypting one block of plaintext always
  74          * yields exactly one block of ciphertext, and vice versa for decrypt.
  75          * The block sizes for plaintext and ciphertext do NOT have to be the same.
  76          * Subclasses (e.g. FEED) which do not meet this criterion will have to override.
  77          */
  78         virtual size_t inputSize(
  79                 size_t                  outSize);                       // input for given output size
  80         virtual size_t outputSize(
  81                 bool                    final = false,
  82                 size_t                  inSize = 0);            // output for given input size
  83         virtual void minimumProgress(
  84                 size_t                  &in,
  85                 size_t                  &out);                          // minimum progress chunks
  86
  87 protected:
  88         typedef enum {
  89                 BCM_ECB,                        // no chaining
  90                 BCM_CBC                         // requires inBlockSize == outBlockSize
  91         } BC_Mode;
  92
  93         /* accessors (see comments below re: the member variables) */
  94         bool    pkcs5Padding()          { return mPkcsPadding; }
  95         bool    needFinalData()         { return mNeedFinalData; }
  96         void    *inBuf()                        { return mInBuf; }
  97         size_t  inBufSize()                     { return mInBufSize; }
  98         void    *chainBuf()                     { return mChainBuf; }
  99         size_t  inBlockSize()           { return mInBlockSize; }
 100         size_t  outBlockSize()          { return mOutBlockSize; }
 101         BC_Mode mode()                          { return mMode; }
 102         bool    opStarted()                     { return mOpStarted; }
 103         bool    cbcCapable()            { return mCbcCapable; }
 104         void    cbcCapable(bool c)      { mCbcCapable = c; }
 105         bool    multiBlockCapable()     { return mMultiBlockCapable; }
 106         void    multiBlockCapable(bool c)       { mMultiBlockCapable = c; }
 107
 108         /*
 109          * Reusable setup functions called from subclass's init.
 110          * This is the general purpose one....
 111          */
 112         void    setup(
 113                 size_t                  blockSizeIn,    // block size of input in bytes
 114                 size_t                  blockSizeOut,   // block size of output in bytes
 115                 bool                    pkcsPad,                // this class performs PKCS{5,7} padding
 116                 bool                    needsFinal,             // needs final update with valid data
 117                 BC_Mode                 mode,                   // ECB, CBC
 118                 const CssmData  *iv);                   // init vector, required for CBC
 119                                                                                 //Ê  must be at least blockSizeIn bytes
 120
 121         /*
 122          * This one is used by simple, well-behaved algorithms which don't do their own
 123          * padding and which rely on us to do everything but one-block-at-a-time
 124          * encrypt and decrypt.
 125          */
 126         void setup(
 127                 size_t                  blockSize,              // block size of input and output
 128                 const Context   &context);
 129
 130         /***
 131          *** Routines to be implemented by subclass.
 132          ***/
 133
 134         /*
 135         virtual void init(const Context &context, bool encoding = true);
 136         */
 137
 138         /*
 139          * encrypt/decrypt exactly one block. Output buffers mallocd by caller.
 140          * On encrypt, it may be acceptable for plainTextLen to be less than
 141          * one plainBlockSize() if:
 142          *   -- final is true, and
 143          *   -- the subclass permits this. That is generally only true
 144          *      when the subclass implements some padding other than our
 145          *      standard PKCS5.
 146          *
 147          * The subclass throws CSSMERR_CSP_INPUT_LENGTH_ERROR if the above
 148          * conditions are not met.
 149          */
 150         virtual void encryptBlock(
 151                 const void              *plainText,                     // length implied (one block)
 152                 size_t                  plainTextLen,
 153                 void                    *cipherText,
 154                 size_t                  &cipherTextLen,         // in/out, subclass throws on overflow
 155                 bool                    final) = 0;
 156
 157         /*
 158          * Decrypt one block. Incoming cipherText length is ALWAYS cipherBlockSize().
 159          */
 160         virtual void decryptBlock(
 161                 const void              *cipherText,            // length implied (one cipher block)
 162                 size_t                  cipherTextLen,
 163                 void                    *plainText,
 164                 size_t                  &plainTextLen,          // in/out, subclass throws on overflow
 165                 bool                    final) = 0;
 166
 167 private:
 168         bool                            mOpStarted;                     // for optional use by subclasses when
 169                                                                                         //   resuing context after encrypt/decrypt
 170                                                                                         //   ops occur
 171         bool                            mCbcCapable;            // when true, algorithm can do its own CBC
 172         bool                            mMultiBlockCapable;     // when true, algorithm can do multi-block ops
 173
 174         /* these are all init'd via setup(), called from subclass-specific init */
 175         bool                            mPkcsPadding;           // PKCS{5,7} padding enabled
 176         bool                            mNeedFinalData;         // subclass needs an update(final) with
 177                                                                                         //   valid data; if true we always keep
 178                                                                                         //   some data in mInBuf after an update.
 179                                                                                         //   Mutually exclusive with mPkcsPadding.
 180         uint8                           *mInBuf;                        // for buffering input
 181         size_t                          mInBufSize;                     // valid bytes in mInBuf
 182         uint8                           *mChainBuf;                     // for CBC, decrypting only
 183         size_t                          mInBlockSize;           // block size of input in bytes; also
 184                                                                                         //    mallocd size of mInBuf
 185         size_t                          mOutBlockSize;          // block size of output in bytes
 186         BC_Mode                         mMode;                          // ECB, CBC
 187
 188 };
 189
 190 #endif  /* _BLOCK_CRYPTOR_H_ */