| /* |
| * Copyright 2002-2005 The Apache Software Foundation. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| /* |
| * XSEC |
| * |
| * XSECCryptoSymmetricKey := Bulk encryption algorithms should all be |
| * implemented via this interface |
| * |
| * Author(s): Berin Lautenbach |
| * |
| * $Id$ |
| * |
| */ |
| |
| |
| |
| #ifndef XSECCRYPTOSYMMETRICKEY_INCLUDE |
| #define XSECCRYPTOSYMMETRICKEY_INCLUDE |
| |
| #include <xsec/framework/XSECDefs.hpp> |
| #include <xsec/dsig/DSIGConstants.hpp> |
| #include <xsec/enc/XSECCryptoKey.hpp> |
| |
| /** |
| * \ingroup crypto |
| */ |
| |
| /** |
| * \brief Base interface definition for symmetric key material. |
| * |
| * All symmetric algorithms are implemented via this interface. |
| * Unlike the asymmetric key definitions, this is not further |
| * extended for particular algorithms. Rather it defines |
| * encrypt/decrypt functions that are implemented within particular |
| * providers for a particular algorithm. |
| */ |
| |
| class DSIG_EXPORT XSECCryptoSymmetricKey : public XSECCryptoKey { |
| |
| public : |
| |
| /** |
| * \brief Symmetric Key types understood by the library |
| * |
| * This type defines the list of symmetric key types that the library |
| * understands. |
| */ |
| |
| enum SymmetricKeyType { |
| |
| KEY_NONE, |
| KEY_3DES_192, /** 192 bit (3-Key) 3DES */ |
| KEY_AES_128, /** 128 bit AES */ |
| KEY_AES_192, /** 192 bit AES */ |
| KEY_AES_256 /** 256 bit AES */ |
| |
| }; |
| |
| enum SymmetricKeyMode { |
| |
| MODE_NONE, /** An error condition */ |
| MODE_ECB, /** Electronic Code Book */ |
| MODE_CBC /** Cipher Block Chaining */ |
| |
| }; |
| |
| |
| /** @name Constructors and Destructors */ |
| //@{ |
| |
| /** |
| * \brief Constructor |
| **/ |
| |
| XSECCryptoSymmetricKey() {}; |
| |
| /** |
| * \brief Destructor |
| * |
| * Implementations must ensure that the held key is properly destroyed |
| * (overwritten) when key objects are deleted. |
| */ |
| |
| virtual ~XSECCryptoSymmetricKey() {}; |
| |
| //@} |
| |
| /** @name Basic CryptoKey Interface methods */ |
| //@{ |
| |
| /** |
| * \brief Returns the type of this key. |
| */ |
| |
| virtual KeyType getKeyType() {return KEY_SYMMETRIC;} |
| |
| /** |
| * \brief Returns a string that identifies the crypto owner of this library. |
| */ |
| |
| virtual const XMLCh * getProviderName() = 0; |
| |
| /** |
| * \brief Clone the key |
| * |
| * All keys need to be able to copy themselves and return |
| * a pointer to the copy. This allows the library to |
| * duplicate keys. |
| */ |
| |
| virtual XSECCryptoKey * clone() = 0; |
| |
| //@} |
| |
| /** @name Symmetric key interface methods */ |
| //@{ |
| |
| /** |
| * \brief What type of symmetric key is this? |
| * |
| * There are a number of different types of symmetric key. |
| * This method allows callers to determine the type of this |
| * particular key |
| */ |
| |
| virtual SymmetricKeyType getSymmetricKeyType(void) = 0; |
| |
| /** |
| * \brief Set the key from the provided bytes |
| * |
| * Symmetric keys can all be loaded from a buffer containing a series |
| * of bytes. |
| * |
| * @param key The buffer containing the key bytes |
| * @param keyLen The number of key bytes in the buffer |
| * |
| */ |
| |
| virtual void setKey(const unsigned char * key, unsigned int keyLen) = 0; |
| |
| /** |
| * \brief Initialise an decryption process |
| * |
| * Setup the key to get ready for a decryption session. |
| * Callers can pass in an IV. If one is not provided, |
| * but the algorithm requires one (e.g. 3DES_CBC), then |
| * implementations should assume that the start of the |
| * cipher text stream will in fact be the IV. |
| * |
| * @param doPad By default, we perform padding for last block |
| * @param mode mode selection (Currently ECB or CBC mode only). |
| * Default is CBC |
| * @param iv Initialisation Vector to be used. NULL if one is |
| * not required, or if IV will be set from data stream |
| * @returns true if the initialisation succeeded. |
| */ |
| |
| virtual bool decryptInit(bool doPad = true, |
| SymmetricKeyMode mode = MODE_CBC, |
| const unsigned char * iv = NULL) = 0; |
| |
| /** |
| * \brief Continue an decrypt operation using this key. |
| * |
| * Decryption must have been set up using an encryptInit |
| * call. Takes the inBuf and continues a decryption operation, |
| * writing the output to outBuf. |
| * |
| * This function does not have to guarantee that all input |
| * will be decrypted. In cases where the input is not a length |
| * of the block size, the implementation will need to hold back |
| * cipher-text to be handles during the next operation. |
| * |
| * @param inBuf Octets to be decrypted |
| * @param plainBuf Buffer to place output in |
| * @param inLength Number of bytes to decrypt |
| * @param maxOutLength Maximum number of bytes to place in output |
| * buffer |
| * @returns Bytes placed in output Buffer |
| */ |
| |
| virtual unsigned int decrypt(const unsigned char * inBuf, |
| unsigned char * plainBuf, |
| unsigned int inLength, |
| unsigned int maxOutLength) = 0; |
| |
| /** |
| * \brief Finish a decryption operation |
| * |
| * Complete a decryption process. No cipher text is passed in, |
| * as this should simply be removing any remaining text from |
| * the plain storage buffer. |
| * |
| * May throw an exception if there is some stored cipher text |
| * that is not the length of the block size for block algorithms. |
| * |
| * @param plainBuf Buffer to place any remaining plain text in |
| * @param maxOutLength Maximum number of bytes to pace in output |
| * @returns Bytes placed in output buffer |
| */ |
| |
| virtual unsigned int decryptFinish(unsigned char * plainBuf, |
| unsigned int maxOutLength) = 0; |
| |
| /** |
| * \brief Initialise an encryption process |
| * |
| * Setup the key to get ready for a decryption session. |
| * Callers can pass in an IV. If one is not provided, |
| * but the algorithm requires one (e.g. 3DES_CBC), then |
| * implementations are required to generate one. |
| * |
| * @param doPad By default, we perform padding for last block |
| * @param mode What mode to handle blocks (Currently CBC or ECB) |
| * Default is CBC. |
| * @param iv Initialisation Vector to be used. NULL if one is |
| * not required, or if IV is to be generated |
| * @returns true if the initialisation succeeded. |
| */ |
| |
| virtual bool encryptInit(bool doPad = true, |
| SymmetricKeyMode mode = MODE_CBC, |
| const unsigned char * iv = NULL) = 0; |
| |
| /** |
| * \brief Continue an encryption operation using this key. |
| * |
| * Encryption must have been set up using an encryptInit |
| * call. Takes the inBuf and continues a encryption operation, |
| * writing the output to outBuf. |
| * |
| * This function does not have to guarantee that all input |
| * will be encrypted. In cases where the input is not a length |
| * of the block size, the implementation will need to hold back |
| * plain-text to be handled during the next operation. |
| * |
| * @param inBuf Octets to be encrypted |
| * @param cipherBuf Buffer to place output in |
| * @param inLength Number of bytes to encrypt |
| * @param maxOutLength Maximum number of bytes to place in output |
| * buffer |
| * @returns Bytes placed in output Buffer |
| */ |
| |
| virtual unsigned int encrypt(const unsigned char * inBuf, |
| unsigned char * cipherBuf, |
| unsigned int inLength, |
| unsigned int maxOutLength) = 0; |
| |
| /** |
| * \brief Finish a encryption operation |
| * |
| * Complete a encryption process. No plain text is passed in, |
| * as this should simply be removing any remaining text from |
| * the plain storage buffer and creating a final padded block. |
| * |
| * Padding is performed by taking the remaining block, and |
| * setting the last byte to equal the number of bytes of |
| * padding. If the plain was an exact multiple of the block size, |
| * then an extra block of padding will be used. For example, if |
| * the block size is 8 bytes, and there were three remaining plain |
| * text bytes (0x01, 0x02 and 0x03), the final block will be : |
| * |
| * 0x010203????????05 |
| * |
| * @param plainBuf Buffer to place final block of cipher text in |
| * @param maxOutLength Maximum number of bytes to pace in output |
| * @returns Bytes placed in output buffer |
| */ |
| |
| virtual unsigned int encryptFinish(unsigned char * plainBuf, |
| unsigned int maxOutLength) = 0; |
| |
| //@} |
| |
| }; |
| |
| |
| #endif /* XSECCRYPTOSYMMETRICKEY_INCLUDE */ |