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