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 2, 2007-03-30
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. New constants

KD_CRYPTO_RANDOM_FAIL_KHR (-1)

A request for a high quality random number has failed.

3. New types

3.1. KDCipherKHR

The opaque representation of a cipher state.

Synopsis

typedef struct KDCipherKHR KDCipherKHR;

Description

3.2. KDHashKHR

The opaque representation of a digest state.

Synopsis

typedef struct KDHashKHR KDHashKHR;

Description

3.3. KDcipherTypeKHR

Enums for supported ciphers.

Synopsis

typedef enum {
    KD_AES_128_CBC_SSL_ENCRYPT_KHR, 
    KD_AES_128_CBC_SSL_DECRYPT_KHR, 
    KD_AES_128_ECB_SSL_ENCRYPT_KHR, 
    KD_AES_128_ECB_SSL_DECRYPT_KHR, 
    KD_AES_128_CBC_NONE_ENCRYPT_KHR, 
    KD_AES_128_CBC_NONE_DECRYPT_KHR, 
    KD_AES_128_ECB_NONE_ENCRYPT_KHR, 
    KD_AES_128_ECB_NONE_DECRYPT_KHR, 
    KD_AES_192_CBC_SSL_ENCRYPT_KHR, 
    KD_AES_192_CBC_SSL_DECRYPT_KHR, 
    KD_AES_192_ECB_SSL_ENCRYPT_KHR, 
    KD_AES_192_ECB_SSL_DECRYPT_KHR, 
    KD_AES_192_CBC_NONE_ENCRYPT_KHR, 
    KD_AES_192_CBC_NONE_DECRYPT_KHR, 
    KD_AES_192_ECB_NONE_ENCRYPT_KHR, 
    KD_AES_192_ECB_NONE_DECRYPT_KHR, 
    KD_AES_256_CBC_SSL_ENCRYPT_KHR, 
    KD_AES_256_CBC_SSL_DECRYPT_KHR, 
    KD_AES_256_ECB_SSL_ENCRYPT_KHR, 
    KD_AES_256_ECB_SSL_DECRYPT_KHR, 
    KD_AES_256_CBC_NONE_ENCRYPT_KHR, 
    KD_AES_256_CBC_NONE_DECRYPT_KHR, 
    KD_AES_256_ECB_NONE_ENCRYPT_KHR, 
    KD_AES_256_ECB_NONE_DECRYPT_KHR
} KDcipherTypeKHR;

Description

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 is supported, AES as it is most likely to be hardware accelerated.

3.4. KDhashTypeKHR

The type of hash.

Synopsis

typedef enum {
  KD_SHA1_KHR
} KDhashTypeKHR;

Description

KD_SHA1_KHR

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

4. New functions

4.1. kdCipherInitKHR

Initializes a cipher.

Synopsis

typedef KDCipherKHR *(*PFNKDCIPHERINITKHR)(KDcipherTypeKHR type, const KDuint8 *key, KDint keyLen, const KDuint8 *iv, KDint ivLen);

Description

Initializes a cipher. This can fail if the arguments don't make sense for the requested cipher, the cipher is not supported, or there are insufficient resources.

Return value

an initialized cipher object or KD_NULL

4.2. kdCipherKHR

Encrypt or decrypt data.

Synopsis

typedef KDint (*PFNKDCIPHERKHR)(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.

4.3. kdCipherFinalKHR

Finishes encrypting or decrypting data.

Synopsis

typedef KDint (*PFNKDCIPHERFINALKHR)(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.

4.4. kdCipherResultKHR

Returns an encryption result.

Synopsis

typedef KDint (*PFNKDCIPHERRESULTKHR)(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.

4.5. kdCipherReinitKHR

Re-initializes a cipher.

Synopsis

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

Description

Re-initializes a cipher.

Return value

an initialized cipher object or KD_NULL if the re-initialization fails

4.6. kdHashInitKHR

Initializes a hash.

Synopsis

typedef KDHashKHR *(*PFNKDHASHINITKHR)(KDhashTypeKHR type);

Description

Initializes a hash. This can fail if the arguments don't mae sense for the requested hash, the hash is not supported, or there are insufficient resources.

Return value

an initialized hash object or KD_NULL

4.7. kdHashKHR

Hash data.

Synopsis

typedef KDint (*PFNKDHASHKHR)(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

4.8. kdHashFinalKHR

Finishes hashing data.

Synopsis

typedef KDint (*PFNKDHASHFINALKHR)(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.

4.9. kdHashResultKHR

Finishes hashing data without deleting the hash object.

Synopsis

typedef KDint (*PFNKDHASHRESULTKHR)(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.

5. Revision history

5.1. Version 2, 2007-03-30

  • Changed function declarations to be typedefs of function pointers.

  • Tidied extension header and added contributor list.

5.2. Version 1, 2007-02-08

Initial version.