Data structures

These structures are used in the API of the current libica version.

For the definitions of older functions, see previous versions of this book. The older functions are no longer recommended for use, but they are supported.

typedef struct {
unsigned int key_length;
unsigned char* modulus;
unsigned char* exponent;
} ica_rsa_key_mod_expo_t;

typedef struct {
unsigned int key_length;
unsigned char* p;
unsigned char* q;
unsigned char* dp;
unsigned char* dq;
unsigned char* qInverse;
} ica_rsa_key_crt_t;

typedef struct {
unsigned int mech_mode_id;
unsigned int flags;
unsigned int property;
} libica_func_list_element;

typedef struct { 
unsigned char vendor_id[16];
unsigned char machine_type[16];
} libica_hw_info;

typedef struct kma_ctx_t kma_ctx;

* mech_mode_id: Unique mechanism ID for each mechanism implemented in libica, as follows:


#define SHA1              1
#define SHA224            2
#define SHA256            3
#define SHA384            4
#define SHA512            5
#define SHA3_224          6
#define SHA3_256          7
#define SHA3_384          8
#define SHA3_512          9   
#define G_HASH           10
#define SHAKE_128        11
#define SHAKE_256        12
#define DES_ECB          20
#define DES_CBC          21
#define DES_CBC_CS       22
#define DES_OFB          23
#define DES_CFB          24
#define DES_CTR          25
#define DES_CTRLST       26
#define DES_CBC_MAC      27
#define DES_CMAC         28
#define DES3_ECB         41
#define DES3_CBC         42
#define DES3_CBC_CS      43
#define DES3_OFB         44
#define DES3_CFB         45
#define DES3_CTR         46
#define DES3_CTRLST      47
#define DES3_CBC_MAC     48
#define DES3_CMAC        49
#define AES_ECB          60
#define AES_CBC          61
#define AES_CBC_CS       62
#define AES_OFB          63
#define AES_CFB          64
#define AES_CTR          65
#define AES_CTRLST       66
#define AES_CBC_MAC      67
#define AES_CMAC         68
#define AES_CCM          69
#define AES_GCM          70
#define AES_XTS          71
#define AES_GCM_KMA      72
#define P_RNG            80
#define EC_DH            85
#define EC_DSA_SIGN      86
#define EC_DSA_VERIFY    87
#define EC_KGEN          88
#define RSA_ME           90
#define RSA_CRT          91
#define RSA_KEY_GEN_ME   92
#define RSA_KEY_GEN_CRT  93
#define SHA512_DRNG      94
#define SHA512_224       95
#define SHA512_256       96
#define ED25519_KEYGEN   100
#define ED25519_SIGN     101
#define ED25519_VERIFY   102
#define ED448_KEYGEN     103
#define ED448_SIGN       104
#define ED448_VERIFY     105
#define X25519_KEYGEN    106
#define X25519_DERIVE    107
#define X448_KEYGEN      108
#define X448_DERIVE      109

For more details regarding these mechanisms, refer to openCryptoki - An Open Source Implementation of PKCS #11.

* flags

This flag represents the type of hardware/software support for each mechanism.

#define ICA_FLAG_SHW 4

Static hardware support (operations on CPACF). Hardware support will be available unless a hardware error occurs.

#define ICA_FLAG_DHW 2

Dynamic hardware support (operations on crypto cards). Hardware support will be available unless the hardware is reconfigured.

#define ICA_FLAG_SW 1

Software support. If both static and dynamic hardware support as well as software support are available, then software support is used as fall back if hardware support fails.

* property

This property field is optional depending on the mechanism. It is used to declare mechanism specific parameters, such as key sizes for RSA and AES.

For RSA mechanisms:

- bit 0: 512 bit key size support
- bit 1: 1024 bit key size support

- bit 2: 2048 bit key size support
- bit 3: 4096 bit key size support

For ECC mechanisms:

- bit 0: support for Brainpool curves
- bit 1: support for NIST curves
- bit 2: support for Edwards curves

For AES mechanisms:

- bit 0: 128 bit key size support
- bit 1: 192 bit key size support
- bit 2: 256 bit key size support

For all non-RSA/AES/ECC mechanisms this field is empty.

Take note of these considerations:

The buffers pointed to by members of type unsigned char * must be manually allocated and deallocated by the user.
Key parts must always be right-aligned in their fields.
All buffers pointed to by members modulus and exponent in struct ica_rsa_key_mod_expo_t must be of length key_length.
All buffers pointed to by members p, q, dp, dq, and qInverse in struct ica_rsa_key_crt_t must be of size key_length / 2 or larger.
In the struct ica_rsa_key_crt_t, the buffers p, dp, and qInverse must contain 8 bytes of zero padding in front of the actual values.
If an exponent is set in struct ica_rsa_key_mod_expo_t as part of a public key for key generation, be aware that due to a restriction in OpenSSL, the public exponent cannot be larger than a size of unsigned long. Therefore, you must have zeros left-padded in the buffer pointed to by exponent in the struct ica_rsa_key_mod_expo_t struct. Be aware that this buffer also must be of size key_length.
This key_length value should be calculated from the length of the modulus in bits, according to this calculation:
```
key_length = (modulus_bits + 7) / 8
```


typedef struct {
        uint64_t runningLength;
        unsigned char shaHash[LENGTH_SHA_HASH];
} sha_context_t;

typedef struct {
        uint64_t runningLength;
        unsigned char sha256Hash[LENGTH_SHA256_HASH];
} sha256_context_t;


typedef struct {
        uint64_t runningLengthHigh;
        uint64_t runningLengthLow;
        unsigned char sha512Hash[LENGTH_SHA512_HASH];
} sha512_context_t;


typedef struct {
        uint64_t runningLength;
        unsigned char sha3_224Hash[SHA3_224_HASH_LENGTH];
} sha3_224_context_t;


typedef struct {
        uint64_t runningLength;
        unsigned char sha3_256Hash[SHA3_256_HASH_LENGTH];
} sha3_256_context_t;


typedef struct {
        uint64_t runningLengthHigh;
        uint64_t runningLengthLow;
        unsigned char sha3_384Hash[SHA3_384_HASH_LENGTH];
} sha3_384_context_t;


typedef struct {
        uint64_t runningLengthHigh;
        uint64_t runningLengthLow;
        unsigned char sha3_512Hash[SHA3_512_HASH_LENGTH];
} sha3_512_context_t;


typedef struct {
        uint64_t runningLengthHigh;
        uint64_t runningLengthLow;
        unsigned int output_length;
        unsigned char shake_128Hash[200];
} shake_128_context_t;


typedef struct {
        uint64_t runningLengthHigh;
        uint64_t runningLengthLow;
        unsigned int output_length;
        unsigned char shake_256Hash[200];
} shake_256_context_t;


typedef struct {
        unsigned int major_version;
        unsigned int minor_version;
        unsigned int fixpack_version;
} libica_version_info;