WinCAPICryptoSymmetricKey Class Reference
[Windows Crypto API Interface]

#include <WinCAPICryptoSymmetricKey.hpp>

Inheritance diagram for WinCAPICryptoSymmetricKey:

[legend]Collaboration diagram for WinCAPICryptoSymmetricKey:

[legend]List of all members.

---

Detailed Description

Base interface definition for symmetric key material.

This is the implementation for a wrapper of Windows CryptoAPI symmetric crypto functions.

Windows utility functions
static HCRYPTKEY	createWindowsKey (const unsigned char *key, unsigned int keyLen, XSECCryptoSymmetricKey::SymmetricKeyType type, HCRYPTPROV *prov)
	Create a symmetric key from a octet string.
Public Member Functions
Constructors and Destructors
	WinCAPICryptoSymmetricKey (HCRYPTPROV prov, XSECCryptoSymmetricKey::SymmetricKeyType type)
	Constructor.
virtual	~WinCAPICryptoSymmetricKey ()
	Destructor.
Basic CryptoKey Interface methods
virtual const XMLCh *	getProviderName ()
	Returns a string that identifies the crypto owner of this library.
virtual XSECCryptoKey *	clone ()
	Clone the key.
Symmetric key interface methods
SymmetricKeyType	getSymmetricKeyType (void)
	What type of symmetric key is this?
void	setKey (const unsigned char *key, unsigned int keyLen)
	Set the key from the provided bytes.
virtual bool	decryptInit (bool doPad=true, SymmetricKeyMode mode=MODE_CBC, const unsigned char *iv=NULL)
	Initialise an decryption process.
virtual unsigned int	decrypt (const unsigned char *inBuf, unsigned char *plainBuf, unsigned int inLength, unsigned int maxOutLength)
	Continue an decrypt operation using this key.
virtual unsigned int	decryptFinish (unsigned char *plainBuf, unsigned int maxOutLength)
	Finish a decryption operation.
virtual bool	encryptInit (bool doPad=true, SymmetricKeyMode mode=MODE_CBC, const unsigned char *iv=NULL)
	Initialise an encryption process.
virtual unsigned int	encrypt (const unsigned char *inBuf, unsigned char *cipherBuf, unsigned int inLength, unsigned int maxOutLength)
	Continue an encryption operation using this key.
virtual unsigned int	encryptFinish (unsigned char *plainBuf, unsigned int maxOutLength)
	Finish a encryption operation.

---

Constructor & Destructor Documentation

WinCAPICryptoSymmetricKey::WinCAPICryptoSymmetricKey (  HCRYPTPROV  prov, XSECCryptoSymmetricKey::SymmetricKeyType  type )

Constructor. Can only construct a Symmetric key if we know what type it is Parameters: prov  The appropriate provider that supports the required algorithm. Can be 0 if the app is going to pass in an octet via setKey, as the library will use its own internal key store and handle to CSP. type  The type of key (i.e. algorithm) to create

virtual WinCAPICryptoSymmetricKey::~WinCAPICryptoSymmetricKey (   )  [virtual]

Destructor. Implementations must ensure that the held key is properly destroyed (overwritten) when key objects are deleted.

---

Member Function Documentation

virtual XSECCryptoKey* WinCAPICryptoSymmetricKey::clone (   )  [virtual]

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. Implements XSECCryptoSymmetricKey.

static HCRYPTKEY WinCAPICryptoSymmetricKey::createWindowsKey (  const unsigned char *  key, unsigned int  keyLen, XSECCryptoSymmetricKey::SymmetricKeyType  type, HCRYPTPROV *  prov )  [static]

Create a symmetric key from a octet string. Uses the ApacheKeyStore to wrap an octet string in a public key and then load it into the Apache Key Container within the defined CSP Parameters: key  The buffer of bytes to load from keyLen  The number of bytes to load type  The key type to create from the bytes prov  If NULL, ignored. If non-null, but *prov == 0, the function will use an internal handle to a CSP and return the value in *prov. If *prov != 0, use contents of *prov as the provider to load the key into. NOTE - The provider must have a AT_KEYEXCHANGE key pair available. Returns: a pointer to the key or 0 on failure

virtual unsigned int WinCAPICryptoSymmetricKey::decrypt (  const unsigned char *  inBuf, unsigned char *  plainBuf, unsigned int  inLength, unsigned int  maxOutLength )  [virtual]

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. Note: While maxOutLength is defined, the WinCAPI library will not read the value, so the onus is on the caller to ensure the buffer is long enough to hold the output! Parameters: inBuf  Octets to be decrypted plainBuf  Buffer to place output in inLength  Number of bytes to decrypt maxOutLength  Maximum number of bytes to place in output buffer Returns: Bytes placed in output Buffer Implements XSECCryptoSymmetricKey.

virtual unsigned int WinCAPICryptoSymmetricKey::decryptFinish (  unsigned char *  plainBuf, unsigned int  maxOutLength )  [virtual]

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. Note: While maxOutLength is defined, the WinCAPI library will not read the value, so the onus is on the caller to ensure the buffer is long enough to hold the output! Parameters: plainBuf  Buffer to place any remaining plain text in maxOutLength  Maximum number of bytes to pace in output Returns: Bytes placed in output buffer Implements XSECCryptoSymmetricKey.

virtual bool WinCAPICryptoSymmetricKey::decryptInit (  bool  doPad = true, SymmetricKeyMode  mode = MODE_CBC, const unsigned char *  iv = NULL )  [virtual]

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. Parameters: doPad  By default, we perform padding for last block mode  mode selection (Currently ECB or CBC mode only) 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. Implements XSECCryptoSymmetricKey.

virtual unsigned int WinCAPICryptoSymmetricKey::encrypt (  const unsigned char *  inBuf, unsigned char *  cipherBuf, unsigned int  inLength, unsigned int  maxOutLength )  [virtual]

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. Parameters: inBuf  Octets to be encrypted cipherBuf  Buffer to place output in inLength  Number of bytes to encrypt maxOutLength  Maximum number of bytes to place in output buffer Returns: Bytes placed in output Buffer Implements XSECCryptoSymmetricKey.

virtual unsigned int WinCAPICryptoSymmetricKey::encryptFinish (  unsigned char *  plainBuf, unsigned int  maxOutLength )  [virtual]

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 Parameters: plainBuf  Buffer to place final block of cipher text in maxOutLength  Maximum number of bytes to pace in output Returns: Bytes placed in output buffer Implements XSECCryptoSymmetricKey.

virtual bool WinCAPICryptoSymmetricKey::encryptInit (  bool  doPad = true, SymmetricKeyMode  mode = MODE_CBC, const unsigned char *  iv = NULL )  [virtual]

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. Parameters: doPad  By default, we perform padding for last block mode  What mode to handle blocks (Currently CBC or ECB) 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. Implements XSECCryptoSymmetricKey.

virtual const XMLCh* WinCAPICryptoSymmetricKey::getProviderName (   )  [virtual]

Returns a string that identifies the crypto owner of this library. Implements XSECCryptoSymmetricKey.

SymmetricKeyType WinCAPICryptoSymmetricKey::getSymmetricKeyType (  void   )  [virtual]

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 Implements XSECCryptoSymmetricKey.

void WinCAPICryptoSymmetricKey::setKey (  const unsigned char *  key, unsigned int  keyLen )  [virtual]

Set the key from the provided bytes. Symmetric keys can all be loaded from a buffer containing a series of bytes. Parameters: key  The buffer containing the key bytes keyLen  The number of key bytes in the buffer Implements XSECCryptoSymmetricKey.

---

The documentation for this class was generated from the following file:

• WinCAPICryptoSymmetricKey.hpp

---