1 /** 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20 /* 21 * XSEC 22 * 23 * XSECCryptoSymmetricKey := Bulk encryption algorithms should all be 24 * implemented via this interface 25 * 26 * Author(s): Berin Lautenbach 27 * 28 * $Id: XSECCryptoSymmetricKey.hpp 1808174 2017-09-12 21:50:30Z scantor $ 29 * 30 */ 31 32 33 34 #ifndef XSECCRYPTOSYMMETRICKEY_INCLUDE 35 #define XSECCRYPTOSYMMETRICKEY_INCLUDE 36 37 #include <xsec/framework/XSECDefs.hpp> 38 #include <xsec/dsig/DSIGConstants.hpp> 39 #include <xsec/enc/XSECCryptoKey.hpp> 40 41 /** 42 * \ingroup crypto 43 */ 44 45 /** 46 * \brief Base interface definition for symmetric key material. 47 * 48 * All symmetric algorithms are implemented via this interface. 49 * Unlike the asymmetric key definitions, this is not further 50 * extended for particular algorithms. Rather it defines 51 * encrypt/decrypt functions that are implemented within particular 52 * providers for a particular algorithm. 53 */ 54 55 class XSEC_EXPORT XSECCryptoSymmetricKey : public XSECCryptoKey { 56 57 public : 58 59 /** 60 * \brief Symmetric Key types understood by the library 61 * 62 * This type defines the list of symmetric key types that the library 63 * understands. 64 */ 65 66 enum SymmetricKeyType { 67 68 KEY_NONE, 69 KEY_3DES_192, /** 192 bit (3-Key) 3DES */ 70 KEY_AES_128, /** 128 bit AES */ 71 KEY_AES_192, /** 192 bit AES */ 72 KEY_AES_256 /** 256 bit AES */ 73 74 }; 75 76 enum SymmetricKeyMode { 77 78 MODE_NONE, /** An error condition */ 79 MODE_ECB, /** Electronic Code Book */ 80 MODE_CBC, /** Cipher Block Chaining */ 81 MODE_GCM /** Galois-Counter Mode */ 82 83 }; 84 85 86 /** @name Constructors and Destructors */ 87 //@{ 88 89 /** 90 * \brief Constructor 91 **/ 92 XSECCryptoSymmetricKey()93 XSECCryptoSymmetricKey() {}; 94 95 /** 96 * \brief Destructor 97 * 98 * Implementations must ensure that the held key is properly destroyed 99 * (overwritten) when key objects are deleted. 100 */ 101 ~XSECCryptoSymmetricKey()102 virtual ~XSECCryptoSymmetricKey() {}; 103 104 //@} 105 106 /** @name Basic CryptoKey Interface methods */ 107 //@{ 108 109 /** 110 * \brief Returns the type of this key. 111 */ 112 getKeyType() const113 virtual KeyType getKeyType() const {return KEY_SYMMETRIC;} 114 115 /** 116 * \brief Returns a string that identifies the crypto owner of this library. 117 */ 118 119 virtual const XMLCh * getProviderName() const = 0; 120 121 /** 122 * \brief Clone the key 123 * 124 * All keys need to be able to copy themselves and return 125 * a pointer to the copy. This allows the library to 126 * duplicate keys. 127 */ 128 129 virtual XSECCryptoKey * clone() const = 0; 130 131 //@} 132 133 /** @name Symmetric key interface methods */ 134 //@{ 135 136 /** 137 * \brief What type of symmetric key is this? 138 * 139 * There are a number of different types of symmetric key. 140 * This method allows callers to determine the type of this 141 * particular key 142 */ 143 144 virtual SymmetricKeyType getSymmetricKeyType(void) const = 0; 145 146 /** 147 * \brief Set the key from the provided bytes 148 * 149 * Symmetric keys can all be loaded from a buffer containing a series 150 * of bytes. 151 * 152 * @param key The buffer containing the key bytes 153 * @param keyLen The number of key bytes in the buffer 154 * 155 */ 156 157 virtual void setKey(const unsigned char * key, unsigned int keyLen) = 0; 158 159 /** 160 * \brief Initialise an decryption process 161 * 162 * Setup the key to get ready for a decryption session. 163 * 164 * Callers can pass in an IV. If one is not provided, 165 * but the algorithm requires one (e.g. 3DES_CBC), then 166 * implementations should assume that the start of the 167 * cipher text stream will in fact be the IV. 168 * 169 * Callers may need to pass a tag to fully initialise an 170 * authenticated encryption algorithm. If a tag is not 171 * supplied, the caller can obtain the length of the required 172 * tag instead, and call this method again once the tag is 173 * obtained. 174 * 175 * @param doPad By default, we perform padding for last block 176 * @param mode mode selection, default is CBC 177 * @param iv Initialisation Vector to be used. NULL if one is 178 * not required, or if IV will be set from data stream 179 * @param tag Authentication tag to be used for AEAD ciphers 180 * @param taglen length of Authentication Tag 181 * @returns true if the initialisation succeeded. 182 */ 183 184 virtual bool decryptInit(bool doPad = true, 185 SymmetricKeyMode mode = MODE_CBC, 186 const unsigned char* iv = NULL, 187 const unsigned char* tag = NULL, 188 unsigned int taglen = 0) = 0; 189 190 /** 191 * \brief Continue a decrypt operation using this key. 192 * 193 * Decryption must have been set up using a decryptInit 194 * call. Takes the inBuf and continues a decryption operation, 195 * writing the output to outBuf. 196 * 197 * This function does not have to guarantee that all input 198 * will be decrypted. In cases where the input is not a length 199 * of the block size, the implementation will need to hold back 200 * cipher-text to be handles during the next operation. 201 * 202 * @param inBuf Octets to be decrypted 203 * @param plainBuf Buffer to place output in 204 * @param inLength Number of bytes to decrypt 205 * @param maxOutLength Maximum number of bytes to place in output 206 * buffer 207 * @returns Bytes placed in output Buffer 208 */ 209 210 virtual unsigned int decrypt(const unsigned char * inBuf, 211 unsigned char * plainBuf, 212 unsigned int inLength, 213 unsigned int maxOutLength) = 0; 214 215 /** 216 * \brief Finish a decryption operation 217 * 218 * Complete a decryption process. No cipher text is passed in, 219 * as this should simply be removing any remaining text from 220 * the plain storage buffer. 221 * 222 * May throw an exception if there is some stored cipher text 223 * that is not the length of the block size for block algorithms. 224 * 225 * @param plainBuf Buffer to place any remaining plain text in 226 * @param maxOutLength Maximum number of bytes to pace in output 227 * @returns Bytes placed in output buffer 228 */ 229 230 virtual unsigned int decryptFinish(unsigned char * plainBuf, 231 unsigned int maxOutLength) = 0; 232 233 /** 234 * \brief Initialise an encryption process 235 * 236 * Setup the key to get ready for a decryption session. 237 * Callers can pass in an IV. If one is not provided, 238 * but the algorithm requires one (e.g. 3DES_CBC), then 239 * implementations are required to generate one. 240 * 241 * @param doPad By default, we perform padding for last block 242 * @param mode What mode to handle blocks. default is CBC 243 * @param iv Initialisation Vector to be used. NULL if one is 244 * not required, or if IV is to be generated 245 * @returns true if the initialisation succeeded. 246 */ 247 248 virtual bool encryptInit(bool doPad = true, 249 SymmetricKeyMode mode = MODE_CBC, 250 const unsigned char * iv = NULL) = 0; 251 252 /** 253 * \brief Continue an encryption operation using this key. 254 * 255 * Encryption must have been set up using an encryptInit 256 * call. Takes the inBuf and continues a encryption operation, 257 * writing the output to outBuf. 258 * 259 * This function does not have to guarantee that all input 260 * will be encrypted. In cases where the input is not a length 261 * of the block size, the implementation will need to hold back 262 * plain-text to be handled during the next operation. 263 * 264 * @param inBuf Octets to be encrypted 265 * @param cipherBuf Buffer to place output in 266 * @param inLength Number of bytes to encrypt 267 * @param maxOutLength Maximum number of bytes to place in output 268 * buffer 269 * @returns Bytes placed in output Buffer 270 */ 271 272 virtual unsigned int encrypt(const unsigned char * inBuf, 273 unsigned char * cipherBuf, 274 unsigned int inLength, 275 unsigned int maxOutLength) = 0; 276 277 /** 278 * \brief Finish an encryption operation 279 * 280 * Complete an encryption process. No plain text is passed in, 281 * as this should simply be removing any remaining text from 282 * the plain storage buffer and creating a final padded block. 283 * 284 * Padding is performed by taking the remaining block, and 285 * setting the last byte to equal the number of bytes of 286 * padding. If the plain was an exact multiple of the block size, 287 * then an extra block of padding will be used. For example, if 288 * the block size is 8 bytes, and there were three remaining plain 289 * text bytes (0x01, 0x02 and 0x03), the final block will be : 290 * 291 * 0x010203????????05 292 * 293 * @param plainBuf Buffer to place final block of cipher text in 294 * @param maxOutLength Maximum number of bytes to pace in output 295 * @param taglen length of Authentication Tag 296 * @returns Bytes placed in output buffer 297 */ 298 299 virtual unsigned int encryptFinish(unsigned char * plainBuf, 300 unsigned int maxOutLength, 301 unsigned int taglen = 0) = 0; 302 303 //@} 304 305 }; 306 307 308 #endif /* XSECCRYPTOSYMMETRICKEY_INCLUDE */ 309