OpenKODE Core extension: KD_KHR_crypto


NameKHR_crypto
Name stringsKD_KHR_crypto
ContributorsLeon Clarke, Tim Renouf
ContactsThe OpenKODE Working Group, Khronos
StatusDRAFT – DO NOT SHIP
VersionVersion 5, 2007-10-22
NumberTBD
Dependencies Requires OpenKODE Core 1.0 Provisional. This extension is written based on the wording of the OpenKODE Core 1.0 Provisional specification.

1. Overview

This OpenKODE Core extension provides cryptographic functions.

2. Header file

When this extension is present, its facilities are accessed by including its header file:

#include <KD/KHR_crypto.h>

3. New functions

3.1. kdCipherInitKHR

Initializes a cipher.

Synopsis

typedef struct KDCipherKHR KDCipherKHR;
KDCipherKHR *kdCipherInitKHR(KDint  type,
 const KDuint8 * key,
 KDint  keyLen,
 const KDuint8 * iv,
 KDint  ivLen);

Description

This function creates and initializes a cipher object. It fails if the arguments do not make sense for the requested cipher, if the cipher is not supported, or if there are insufficient resources.

The value of type determines the cipher type, and is one of the types listed below. It encodes the cipher algorithm, block chaining (if relevant), the padding (if relevant) and whether it is encrypting or decrypting.

key is a pointer to the key, and keyLen is the key length. iv points to the initialization vector, and ivLen is its length. If no initialization vector is required, iv and ivLen should be KD_NULL and 0 respectively.

Cipher types

KD_AES_128_CBC_SSL_ENCRYPT_KHR

Encrypt using AES with 128 bit key, CBC chaining, SSL padding.

KD_AES_128_CBC_SSL_DECRYPT_KHR

Decrypt using AES with 128 bit key, CBC chaining, SSL padding.

KD_AES_128_ECB_SSL_ENCRYPT_KHR

Encrypt using AES with 128 bit key, ECB chaining, SSL padding.

KD_AES_128_ECB_SSL_DECRYPT_KHR

Decrypt using AES with 128 bit key, ECB chaining, SSL padding.

KD_AES_128_CBC_NONE_ENCRYPT_KHR

Encrypt using AES with 128 bit key, CBC chaining, no padding.

KD_AES_128_CBC_NONE_DECRYPT_KHR

Decrypt using AES with 128 bit key, CBC chaining, no padding.

KD_AES_128_ECB_NONE_ENCRYPT_KHR

Encrypt using AES with 128 bit key, ECB chaining, no padding.

KD_AES_128_ECB_NONE_DECRYPT_KHR

Decrypt using AES with 128 bit key, ECB chaining, no padding.

KD_AES_192_CBC_SSL_ENCRYPT_KHR

Encrypt using AES with 192 bit key, CBC chaining, SSL padding.

KD_AES_192_CBC_SSL_DECRYPT_KHR

Decrypt using AES with 192 bit key, CBC chaining, SSL padding.

KD_AES_192_ECB_SSL_ENCRYPT_KHR

Encrypt using AES with 192 bit key, ECB chaining, SSL padding.

KD_AES_192_ECB_SSL_DECRYPT_KHR

Decrypt using AES with 192 bit key, ECB chaining, SSL padding.

KD_AES_192_CBC_NONE_ENCRYPT_KHR

Encrypt using AES with 192 bit key, CBC chaining, no padding.

KD_AES_192_CBC_NONE_DECRYPT_KHR

Decrypt using AES with 192 bit key, CBC chaining, no padding.

KD_AES_192_ECB_NONE_ENCRYPT_KHR

Encrypt using AES with 192 bit key, ECB chaining, no padding.

KD_AES_192_ECB_NONE_DECRYPT_KHR

Decrypt using AES with 192 bit key, ECB chaining, no padding.

KD_AES_256_CBC_SSL_ENCRYPT_KHR

Encrypt using AES with 256 bit key, CBC chaining, SSL padding.

KD_AES_256_CBC_SSL_DECRYPT_KHR

Decrypt using AES with 256 bit key, CBC chaining, SSL padding.

KD_AES_256_ECB_SSL_ENCRYPT_KHR

Encrypt using AES with 256 bit key, ECB chaining, SSL padding.

KD_AES_256_ECB_SSL_DECRYPT_KHR

Decrypt using AES with 256 bit key, ECB chaining, SSL padding.

KD_AES_256_CBC_NONE_ENCRYPT_KHR

Encrypt using AES with 256 bit key, CBC chaining, no padding.

KD_AES_256_CBC_NONE_DECRYPT_KHR

Decrypt using AES with 256 bit key, CBC chaining, no padding.

KD_AES_256_ECB_NONE_ENCRYPT_KHR

Encrypt using AES with 256 bit key, ECB chaining, no padding.

KD_AES_256_ECB_NONE_DECRYPT_KHR

Decrypt using AES with 256 bit key, ECB chaining, no padding.

Currently only the most minimal set, AES, is supported, as it is most likely to be hardware accelerated.

Return value

The function returns an initialized cipher object, or KD_NULL if the arguments do not make sense for the requested cipher, or if there are insufficient resources.

3.2. kdCipherKHR

Encrypt or decrypt data.

Synopsis

KDint kdCipherKHR(KDCipherKHR * c,
 const KDuint8 * data,
 KDint  dataLen,
 KDuint8 * out,
 KDint * outLen);

Description

Encrypt or decrypt data.

Return value

The amount of input consumed, or -1 if there was an error.

3.3. kdCipherFinalKHR

Finishes encrypting or decrypting data.

Synopsis

KDint kdCipherFinalKHR(KDCipherKHR * c,
 const KDuint8 * data,
 KDint  dataLen,
 KDuint8 * out,
 KDint * outLen);

Description

Finishes encrypting or decrypting data. Note that this function won't actually finish if it doesn't have enough output space. It will add padding if appropriate.

Return value

The amount of input consumed or -1 if there was an error. If this is not equal to dataLen, then the function has behaved like kdCipherKHR and must be called again with enough output space to consume the remaining input.

3.4. kdCipherResultKHR

Returns an encryption result.

Synopsis

KDint kdCipherResultKHR(KDCipherKHR * c,
 const KDuint8 * data,
 KDint  dataLen,
 KDuint8 * out,
 KDint * outLen);

Description

Finishes encrypting or decrypting data but leaves the cipher object to be re-used for another encryption. Note that this function won't actually finish if it doesn't have enough output space. It will add padding if appropriate.

If all input has been consumed, the cipher object is in an undefined state. It must be re-initialized with kdCipherReinitKHR.

Return value

The amount of input consumed or -1 if there was an error. If this is not equal to dataLen, then the function has behaved like kdCipherKHR and must be called again with enough output space to consume the remaining input.

3.5. kdCipherReinitKHR

Re-initializes a cipher.

Synopsis

KDCipherKHR *kdCipherReinitKHR(KDCipherKHR * c,
 const KDuint8 * key,
 KDint  keyLen,
 const KDuint8 * iv,
 KDint  ivLen);

Description

This function re-initializes an existing cipher, using the same cipher type.

key is a pointer to the key, and keyLen is the key length. A value of KD_NULL for key and 0 for keyLen indicates that the previous key should be used. iv points to the initialization vector, and ivLen is its length. If no initialization vector is required, iv and ivLen should be KD_NULL and 0 respectively.

Return value

An initialized cipher object or KD_NULL if the re-initialization fails.

3.6. kdHashInitKHR

Initializes a hash.

Synopsis

typedef struct KDHashKHR KDHashKHR;
KDHashKHR *kdHashInitKHR(KDint  type);

Description

This function creates and initializes a hash object. type is the hash algorithm to use, selected from the list below.

Hash types

KD_SHA1_KHR (104)

Use the SHA-1 hash algorithm, which returns a 20 byte hash.

Return value

On success, the function returns an initialized hash object. If the hash type is not supported, or there are insufficient resources, then the function returns KD_NULL.

3.7. kdHashKHR

Hash data.

Synopsis

typedef KDint kdHashKHR(KDHashKHR * c,
 const KDuint8 * data,
 KDint  dataLen);

Description

Hash data.

Return value

The amount of input consumed, or -1 if there was an error. Note that all input will always be consumed; returning the amount is simply for consistency with kdCipherKHR

3.8. kdHashFinalKHR

Finishes hashing data.

Synopsis

KDint kdHashFinalKHR(KDHashKHR * c,
 const KDuint8 * data,
 KDint  dataLen,
 KDuint8 * out,
 KDint * outLen);

Description

Finishes hashing data and destroys the hash object..

Return value

The amount of input consumed or -1 if there was an error.

3.9. kdHashResultKHR

Finishes hashing data without deleting the hash object.

Synopsis

KDint kdHashResultKHR(KDHashKHR * c,
 const KDuint8 * data,
 KDint  dataLen,
 KDuint8 * out,
 KDint * outLen);

Description

Finishes hashing data but leaves the hash object to be re-used.

The hash object will have been re-initialized even if the output buffer was unsuitable.

Return value

The amount of input consumed or -1 if there was an error.

4. Revision history

4.1. Version 5, 2007-10-22

Changed constants from enums to #defines. Changed functions back from function pointer typedefs.

4.2. Version 4, 2007-10-17

Constants renumbered in line with allocation from OpenKODE Core registry.

4.3. Version 3, 2007-05-18

  • Removed KD_CRYPTO_RANDOM_FAILURE_KHR as nothing was using it.

4.4. Version 2, 2007-03-30

  • Changed function declarations to be typedefs of function pointers.

  • Tidied extension header and added contributor list.

4.5. Version 1, 2007-02-08

Initial version.