_ Git - BoarSSL/blob - Crypto/IBlockCipher.cs

   1 /*
   2  * Copyright (c) 2017 Thomas Pornin <pornin@bolet.org>
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining
   5  * a copy of this software and associated documentation files (the
   6  * "Software"), to deal in the Software without restriction, including
   7  * without limitation the rights to use, copy, modify, merge, publish,
   8  * distribute, sublicense, and/or sell copies of the Software, and to
   9  * permit persons to whom the Software is furnished to do so, subject to
  10  * the following conditions:
  11  *
  12  * The above copyright notice and this permission notice shall be
  13  * included in all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  18  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
  19  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
  20  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  21  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  22  * SOFTWARE.
  23  */
  24
  25 using System;
  26
  27 namespace Crypto {
  28
  29 /*
  30  * Interface for a block cipher implementation. Each instance has a
  31  * state, which contains (at least) the current secret key, but may also
  32  * have other internal values. Thereby, instances are not thread-safe.
  33  * The Dup() method may be used to "clone" an instance into a new,
  34  * independent instance that starts its life configured with the same
  35  * secret key.
  36  */
  37
  38 public interface IBlockCipher {
  39
  40         /*
  41          * Get the block size in bytes.
  42          */
  43         int BlockSize { get; }
  44
  45         /*
  46          * Set the key.
  47          */
  48         void SetKey(byte[] key);
  49
  50         /*
  51          * Set the key.
  52          */
  53         void SetKey(byte[] key, int off, int len);
  54
  55         /*
  56          * Encrypt one block.
  57          */
  58         void BlockEncrypt(byte[] buf);
  59
  60         /*
  61          * Encrypt one block.
  62          */
  63         void BlockEncrypt(byte[] buf, int off);
  64
  65         /*
  66          * Decrypt one block.
  67          */
  68         void BlockDecrypt(byte[] buf);
  69
  70         /*
  71          * Encrypt one block.
  72          */
  73         void BlockDecrypt(byte[] buf, int off);
  74
  75         /*
  76          * Do CBC encryption. There is no padding; the source array
  77          * must already have a length multiple of the block size.
  78          * The provided iv[] array must have the same length as a
  79          * block. The data is encrypted in-place. The iv[] array is
  80          * unmodified.
  81          */
  82         void CBCEncrypt(byte[] iv, byte[] data);
  83
  84         /*
  85          * Do CBC encryption. There is no padding; the source array
  86          * must already have a length multiple of the block size.
  87          * The provided iv[] array must have the same length as a
  88          * block. The data is encrypted in-place. The iv[] array is
  89          * unmodified.
  90          */
  91         void CBCEncrypt(byte[] iv, byte[] data, int off, int len);
  92
  93         /*
  94          * Do CBC decryption. The source array must have a length
  95          * multiple of the block size; no attempt at padding removal is
  96          * performed. The provided iv[] array must have the same length
  97          * as a block. The data is decrypted in-place. The iv[] array is
  98          * unmodified.
  99          */
 100         void CBCDecrypt(byte[] iv, byte[] data);
 101
 102         /*
 103          * Do CBC decryption. The source array must have a length
 104          * multiple of the block size; no attempt at padding removal is
 105          * performed. The provided iv[] array must have the same length
 106          * as a block. The data is decrypted in-place. The iv[] array is
 107          * unmodified.
 108          */
 109         void CBCDecrypt(byte[] iv, byte[] data, int off, int len);
 110
 111         /*
 112          * Do CTR encryption or decryption. This implements the variant
 113          * used in GCM:
 114          *  - IV length is 4 bytes less than the block length
 115          *  - The block counter is used for the last 4 bytes of the
 116          *    block input; big-endian encoding is used.
 117          *  - Counter arithmetic is done modulo 2^32.
 118          *
 119          * The starting counter value is provided as parameter; the new
 120          * counter value is returned. This allows computing a long CTR
 121          * run in several chunks, as long as all chunks (except possibly
 122          * the last one) have a length which is multiple of the block size.
 123          */
 124         uint CTRRun(byte[] iv, uint cc, byte[] data);
 125
 126         /*
 127          * Do CTR encryption or decryption. This implements the variant
 128          * used in GCM:
 129          *  - IV length is 4 bytes less than the block length
 130          *  - The block counter is used for the last 4 bytes of the
 131          *    block input; big-endian encoding is used.
 132          *  - Counter arithmetic is done modulo 2^32.
 133          *
 134          * The starting counter value is provided as parameter; the new
 135          * counter value is returned. This allows computing a long CTR
 136          * run in several chunks, as long as all chunks (except possibly
 137          * the last one) have a length which is multiple of the block size.
 138          */
 139         uint CTRRun(byte[] iv, uint cc, byte[] data, int off, int len);
 140
 141         /*
 142          * Do combined CTR encryption/decryption and CBC-MAC. The CTR
 143          * mode uses full-block increments (counter value is the
 144          * big-endian interpretation of the complete block); the ctr[]
 145          * array contains the initial value for the counter (used to
 146          * encrypt or decrypt the full block) and it is updated by
 147          * this method as blocks are processed.
 148          *
 149          * The cbcmac[] array has full block width and contains the
 150          * running value for CBC-MAC, computed over the _encrypted_ data.
 151          *
 152          * The flag 'encrypt' is true when encrypting, false when
 153          * decrypting. Note that CTR encryption and decryption are
 154          * identical; thus, the only effect of this flag is to decide
 155          * whether CBC-MAC should be applied on the blocks before or
 156          * after CTR encryption/decryption.
 157          *
 158          * The data is provided in the data[] buffer, and is
 159          * encrypted/decrypted in place. Its length MUST be a multiple
 160          * of the block size.
 161          */
 162         void CTRCBCRun(byte[] ctr, byte[] cbcmac, bool encrypt, byte[] data);
 163
 164         /*
 165          * Do combined CTR encryption/decryption and CBC-MAC. The CTR
 166          * mode uses full-block increments (counter value is the
 167          * big-endian interpretation of the complete block); the ctr[]
 168          * array contains the initial value for the counter (used to
 169          * encrypt or decrypt the full block) and it is updated by
 170          * this method as blocks are processed.
 171          *
 172          * The cbcmac[] array has full block width and contains the
 173          * running value for CBC-MAC, computed over the _encrypted_ data.
 174          *
 175          * The flag 'encrypt' is true when encrypting, false when
 176          * decrypting. Note that CTR encryption and decryption are
 177          * identical; thus, the only effect of this flag is to decide
 178          * whether CBC-MAC should be applied on the blocks before or
 179          * after CTR encryption/decryption.
 180          *
 181          * The data is provided in the data[] buffer, and is
 182          * encrypted/decrypted in place. Its length MUST be a multiple
 183          * of the block size.
 184          */
 185         void CTRCBCRun(byte[] ctr, byte[] cbcmac, bool encrypt,
 186                 byte[] data, int off, int len);
 187
 188         /*
 189          * Perform CBC-MAC: the cbcmac[] block is updated with the
 190          * CBC-MAC of the data. Data length must be a multiple of the
 191          * block size.
 192          */
 193         void CBCMac(byte[] cbcmac, byte[] data, int off, int len);
 194
 195         /*
 196          * Duplicate this engine. This creates a new, independent
 197          * instance that implements the same function, and starts with
 198          * the same currently set key.
 199          */
 200         IBlockCipher Dup();
 201 }
 202
 203 }