Documentation
Rate This Document
Findability
Accuracy
Completeness
Readability
SubmitClose

Data Structures

This section describes data structures and field definitions related to cryptographic devices, providing unified data structure specifications for developers to streamline development, debugging, and integration with cryptographic devices.

Device Information Definition

Field Name

Data Length (Byte)

Description

IssuerName

40

Device vendor name.

DeviceName

16

Device model.

DeviceSerial

16

Device ID, which consists of the date (8 characters), batch number (3 characters), and serial number (5 characters).

DeviceVersion

4

Internal software version of the cryptographic device.

StandardVersion

4

Interface specifications version supported by the cryptographic device.

AsymAlgAbility

8

The first four bytes identify the supported asymmetric algorithms, which are represented as the result of the bitwise OR operation on the identifiers of the supported algorithms. The last four bytes identify the maximum modulus lengths of the algorithms, which are represented as the result of the bitwise OR operation on the maximum modulus lengths of the supported algorithms.

SymAlgAbility

4

Supported symmetric algorithms, represented as the result of the bitwise OR operation on their identifiers.

HashAlgAbility

4

Supported hash algorithms, represented as the result of the bitwise OR operation on their identifiers.

BufferSize

4

Maximum file storage space (unit: byte).

Data structure definition:

typedef struct { 
unsigned char IssuerName[40]; 
unsigned char DeviceName[16]; 
unsigned char DeviceSerial[16]; 
unsigned int DeviceVersion; 
unsigned int StandardVersion; 
unsigned int AsymAlgAbility[2]; 
unsigned int SymAlgAbility; 
unsigned int HashAlgAbility; 
unsigned int BufferSize; 
} DEVICEINFO;

Key Type and Storage Definition

  • Device key and internal user keys
    • The device key can be generated or installed only during device initialization. Internal user keys can be generated or installed using the cryptographic device management tool.
    • The device key and internal user keys are stored in the key storage area. Their index numbers start from 0. Each index number corresponds to a signature key pair and an encryption key pair. The index number 0 indicates the device key. The index numbers starting from 1 indicate user keys.

      Key Pair Index

      Public Key

      Private Key

      0x00

      Device signature

      Device signature

      Device encryption

      Device encryption

      0x01

      User signature

      User signature

      User encryption

      User encryption

      ...

      ...

      ...

      ...

      ...
  • KEKs

    KEKs are generated or installed using the cryptographic device management tool, and stored in the key storage area with index numbers starting from 1. Their length is 128 bits.

    Key Index

    KEK

    0x01

    KEK 001

    ...

    ...

Session Keys

Session keys are generated or imported using device API functions, and are retrieved using handles.

ECC Key Data Structure Definition

A key is stored in order from the most significant bit to the least significant bit; that is, when placing a key into the key structure array, the highest byte is stored at the highest position. If the key is shorter than the array length, the remaining bits are padded with zeros.

Table 1 Public key data structure definition

Field Name

Data Length (Byte)

Description

bits

4

Key length.

x

ECCref_MAX_LEN

x-coordinate of the public key.

y

ECCref_MAX_LEN

y-coordinate of the public key.
Table 2 Private key data structure definition

Field Name

Data Length (Byte)

Description

bits

4

Key length.

K

ECCref_MAX_LEN

Private key.

Actual data structure definition:

#define ECCref_MAX_BITS 512 
#define ECCref_MAX_LEN ((ECCref_MAX_BITS+7) / 8) 
typedef struct ECCrefPublicKey_st { 
unsigned int bits; 
unsigned char x[ECCref_MAX_LEN]; 
unsigned char y[ECCref_MAX_LEN]; 
} ECCrefPublicKey; 
typedef struct ECCrefPrivateKey_st { 
unsigned int bits; 
unsigned char K[ECCref_MAX_LEN]; 
} ECCrefPrivateKey;

ECC Encryption Data Structure Definition

Table 3 Encryption data structure definition

Field Name

Data Length (Byte)

Description

x

ECCref_MAX_LEN

X component.

y

ECCref_MAX_LEN

Y component.

M

32

Hash value of the plaintext.

L

4

Ciphertext data length.

C

L

Ciphertext data.

Actual data structure definition:

typedef struct ECCCipher_st { 
unsigned char x[ECCref_MAX_LEN]; 
unsigned char y[ECCref_MAX_LEN]; 
unsigned char M[32]; 
unsigned int L; 
unsigned char C[]; 
} ECCCipher;

ECC Signature Data Structure Definition

Table 4 Signature data structure definition

Field Name

Data Length (Byte)

Description

r

ECCref_MAX_LEN

r part of the signature.

s

ECCref_MAX_LEN

s part of the signature.

Actual data structure definition:

typedef struct ECCSignature_st { 
unsigned char r[ECCref_MAX_LEN]; 
unsigned char s[ECCref_MAX_LEN]; 
} ECCSignature;

Digital envelope data structure definition:

typedef struct EnvelopedKey_st {
unsigned int Version;
unsigned int ulSymmAlgID;
unsigned int ulBits;
unsigned char cbEncryptedKey[ECCref_MAX_LEN];
ECCrefPublicKey PubKey;
ECCCipher ECCCipherBlob;
} ECCEnvelopedKey;
Table 5 Length and description of each field in the digital envelope data structure

Field Name

Data Length (Byte)

Description

Version

4

Digital envelope version

ulSymmAlgID

4

ID of the digital envelope's symmetric algorithm (ECB format required by the specifications)

ulBits

4

Key length

cbEncryptedKey

ECCref_MAX_LEN

Private key encrypted using the symmetric algorithm or symmetric key ciphertext

PubKey

2 * ECCref_MAX_LEN + 4

Public key of the ECC key pair

ECCCipherBlob

2 * ECCref_MAX_LEN + M_LENGTH + L

Structure for storing the symmetric key ciphertext encrypted using the public key