 |
xilsecure
Vitis Drivers API Documentation
|
|
xilsecure
Vitis Drivers API Documentation
|
This file contains structures, constants and defines used in LMS OTS and provides interface to LMS OTS operations.
MODIFICATION HISTORY:
Ver Who Date Changes ----- ---- -------- ---------------------------------------------------------- 5.4 kal 07/24/24 Initial release
Data Structures | |
| union | XSecure_LmsOtsPublicKey_ |
| LMS OTS Public key structure. More... | |
| union | XSecure_LmsOtsHashPerDigit_ |
| Temporary buffer, used in LMS OTS signature verification, used in hash chain to arrive at values which will be concatenated and hashed to get public value. More... | |
| union | XSecure_LmsOtsSignToPubKeyHash_ |
| Structure used when validating LMS OTS, once hash chain is completed, result needs to be stored so that they can be further concatenated and hashed to get OTS public key, this provides a way to access members and fill data in a structured way. More... | |
| struct | XSecure_LmsOtsSignature_ |
| Partial LMS OTS Signature structure. More... | |
| union | XSecure_LmsDataDigestFixedFields_ |
| Temporary buffer, used to send prefix fields to calculate digest for data to be authenticate. More... | |
| union | XSecure_LmsDataDigest_ |
| Digest for message to be authenticated, along with checksum. More... | |
Macros | |
| #define | XSECURE_LMS_OTS_TYPE_MAX_SUPPORTED (7U) |
| Max supported types, used for creating lookup table for parameters for types supported number should be max valid + 1 (as first slot will be for invalid parameterXSecure_LmsOtsType XSecure_LmsOtsType. More... | |
| #define | XSECURE_LMS_DIGEST_CHECKSUM_SIZE |
| Digest of data to be authenticated concatenated with checksum value. More... | |
| #define | XSECURE_LMS_MESSAGE_TO_DIGEST_PREFIX_SIZE |
| Prefix fields length, before sending actual data to sha engine for digest. More... | |
| #define | XSECURE_LMS_OTS_PUB_KEY_TOTAL_SIZE |
| OTS Public key total size. More... | |
| #define | XSECURE_LMS_OTS_SIGN_VERIF_TMP_BUFF_TOTAL_SIZE |
| Total size of buffer, XSecure_LmsOtsHashPerDigit. More... | |
| #define | XSECURE_LMS_OTS_SIGN_VERIF_CHAIN_TMP_BUFF_TOTAL_SIZE |
Max possible size as supported only till XSECURE_LMS_OTS_W2 More... | |
| #define | XSECURE_LMS_OTS_SIGN_VERIF_CHAIN_TMP_BUFF_CURRENT_SIZE(p) |
| Total Size of buffer used in OTS verification, while considering current 'p' parameter. More... | |
| #define | XSECURE_LMS_OTS_PUBKEY_I_OFFSET (0U) |
| Offset of 'I' field in OTS Public key. More... | |
| #define | XSECURE_LMS_OTS_PUBKEY_Q_OFFSET |
| Offset of 'q' field in OTS Public key. More... | |
| #define | XSECURE_LMS_OTS_SIGN_TYPE_FIELD_OFFSET (0U) |
| Offset of 'Type' field in OTS Signature buffer. More... | |
| #define | XSECURE_LMS_OTS_SIGN_C_FIELD_OFFSET |
| Offset of 'C' field in OTS Signature buffer. More... | |
| #define | XSECURE_LMS_OTS_SIGN_Y_FIELD_OFFSET |
| Offset of 'Y' field in OTS Signature buffer. More... | |
| #define | XSECURE_LMS_OTS_SIGN_VERIF_TMP_BUFF_I_OFFSET (1U) |
| Offset of 'I' field in temporary buffer, where inner loops result are stored, for reprocessing during OTS operations. More... | |
| #define | XSECURE_LMS_OTS_SIGN_VERIF_TMP_BUFF_Q_OFFSET |
| Offset of 'q' field in temporary buffer, where inner loops result are stored, for reprocessing during OTS operations. More... | |
| #define | XSECURE_LMS_OTS_SIGN_VERIF_TMP_BUFF_i_OFFSET |
| Offset of 'i' field in temporary buffer, where inner loops result are stored, for reprocessing during OTS operations. More... | |
| #define | XSECURE_LMS_OTS_SIGN_VERIF_TMP_BUFF_j_OFFSET |
| Offset of 'j' field in temporary buffer, where inner loops result are stored, for reprocessing during OTS operations. More... | |
| #define | XSECURE_LMS_OTS_SIGN_VERIF_TMP_BUFF_Y_OFFSET |
| Offset of 'Y' field in temporary buffer, where inner loops result are stored, for reprocessing during OTS operations. More... | |
| #define | XSECURE_LMS_OTS_SIGN_VERIF_CHAIN_TMP_BUFF_I_OFFSET (0U) |
| Offset of 'I' field in temporary buffer, where inner loops result is concatenated during OTS operations. More... | |
| #define | XSECURE_LMS_OTS_SIGN_VERIF_CHAIN_TMP_BUFF_Q_OFFSET |
| Offset of 'q' field in temporary buffer, where inner loops result is concatenated during OTS operations. More... | |
| #define | XSECURE_LMS_OTS_SIGN_VERIF_CHAIN_TMP_BUFF_D_PBLC_OFFSET |
| Offset of D_PBLC field in temporary buffer, where inner loops result is concatenated during OTS operations. More... | |
| #define | XSECURE_LMS_OTS_SIGN_VERIF_CHAIN_TMP_BUFF_Z_OFFSET |
| Offset of 'z' field in temporary buffer, where inner loops result is concatenated during OTS operations. More... | |
Typedefs | |
| typedef union XSecure_LmsOtsPublicKey_ | XSecure_LmsOtsPublicKey |
| LMS OTS Public key structure. More... | |
| typedef union XSecure_LmsOtsHashPerDigit_ | XSecure_LmsOtsHashPerDigit |
| Temporary buffer, used in LMS OTS signature verification, used in hash chain to arrive at values which will be concatenated and hashed to get public value. More... | |
| typedef union XSecure_LmsOtsSignToPubKeyHash_ | XSecure_LmsOtsSignToPubKeyHash |
| Structure used when validating LMS OTS, once hash chain is completed, result needs to be stored so that they can be further concatenated and hashed to get OTS public key, this provides a way to access members and fill data in a structured way. More... | |
| typedef struct XSecure_LmsOtsSignature_ | XSecure_LmsOtsSignature |
| Partial LMS OTS Signature structure. More... | |
| typedef union XSecure_LmsDataDigestFixedFields_ | XSecure_LmsDataDigestFixedFields |
| Temporary buffer, used to send prefix fields to calculate digest for data to be authenticate. More... | |
| typedef union XSecure_LmsDataDigest_ | XSecure_LmsDataDigest |
| Digest for message to be authenticated, along with checksum. More... | |
Enumerations | |
| enum | XSecure_LmsOtsType { , XSECURE_LMS_OTS_SHA256_N32_W4 = 0x00000003U, XSECURE_LMS_OTS_SHA256_N32_W8 = 0x00000004U, XSECURE_LMS_OTS_SHAKE_N32_W2 = 0x0000000AU, XSECURE_LMS_OTS_SHAKE_N32_W4 = 0x0000000BU, XSECURE_LMS_OTS_SHAKE_N32_W8 = 0x0000000CU, XSECURE_LMS_OTS_NOT_SUPPORTED } |
| Types of LMS_OTS supported. More... | |
| enum | XSecure_LmsOtsWIndex { , XSECURE_LMS_OTS_W4 = 4U, XSECURE_LMS_OTS_W8 = 8U } |
| Number of bits per digit Possible values are as supported by ROM, w=1 is not supported. More... | |
| enum | XSecure_LmsOtsuIndex { , XSECURE_LMS_OTS_W4_U = 64U, XSECURE_LMS_OTS_W8_U = 32U } |
| Number of 'w' width digits possible in message Digest, excluding checksum Possible values are as supported by ROM. More... | |
| enum | XSecure_LmsOtsvIndex { , XSECURE_LMS_OTS_W4_V = 3U, XSECURE_LMS_OTS_W8_V = 2U } |
| Is the number of 'w' width digits possible in checksum Possible values are as supported by ROM. More... | |
| enum | XSecure_LmsOtslsIndex { , XSECURE_LMS_OTS_W4_LS = 4U, XSECURE_LMS_OTS_W8_LS = 0U, XSECURE_LMS_OTS_LS_NOT_SUPPORTED = 16U } |
| No.of bits to left-shift in Checksum, in the 16 bit value Possible values are as supported by ROM. More... | |
| enum | XSecure_LmsOtspIndex { , XSECURE_LMS_OTS_W4_P = 67U, XSECURE_LMS_OTS_W8_P = 34U } |
| Is a sum of U + V, it is number of 'w' width digits possible in digest + checksum buffer Possible values are as supported by ROM. More... | |
Functions | |
| u32 | XSecure_LmsOtsCoeff (u8 const *const Arr, const u32 ArrayIndex, const u32 w) |
| This function extracts the digits from the array for bytes. More... | |
| int | XSecure_LmsOtsComputeChecksum (const u8 *const Array, const u32 ArrayLen, const u32 w, const u32 ls, u32 *const Checksum) |
| This function calculates the checksum for a given array. More... | |
| int | XSecure_LmsOtsLookupParamSet (XSecure_LmsOtsType Type, XSecure_LmsOtsParam **Parameters) |
| This function returns the parameters for the type of LMS OTS type. More... | |
Variables | |
| XSecure_LmsOtsType | Type |
| Type XSecure_LmsOtsType Size - 4 bytes, 0 to 3 bytes in public key. More... | |
| u8 | I [XSECURE_LMS_I_FIELD_SIZE] |
| I - Merkle Tree's unique identifier (uniformly random 16-byte string) Size - 16 bytes, 4 to 19 bytes in public key. More... | |
| u32 | q |
| q - The leaf number q, goes from 0 on left most leaf to right most (2^h -1), in a single tree Size - 4 bytes, 20 to 23 bytes in public key More... | |
| u8 | K [XSECURE_LMS_OTS_PUB_KEY_K_FIELD_SIZE] |
| K - H(I || u32str(q) || u16str(D_PBLC) || y[0] || ... More... | |
| u8 | Reserved |
| 1 reserved byte added at start of buffer, to manage word aligned sha finish copies to buffer More... | |
| u16 | i |
| i - Digit position in (Digest || Checksum), 0 to (p-1) digits. More... | |
| u8 | j |
| j - Index for inner loop during signature verification, starts at digit value in (Digest || Checksum) ends at (2^w - 1). More... | |
| u8 | y [XSECURE_LMS_OTS_SIGN_VERIF_TMP_BUFF_Y_SIZE] |
| y[] - 'n' bytes picked from LMS OTS signatures. More... | |
| u8 | D_PBLC [2U] |
| D_PBLC - XSECURE_D_PBLC Size - 2 Bytes, 20 to 21 bytes. More... | |
| u8 | z [XSECURE_LMS_OTS_SIGN_VERIF_CHAIN_TMP_BUFF_z_SIZE] |
| z - Each z is a XSECURE_LMS_N_FIELD_SIZE byte length, and ranges from 0 to p-1 Size - (32 Bytes * p) More... | |
| u8 | D_MESG [XSECURE_LMS_D_MESG_FIELD_SIZE] |
| D_MESG - XSECURE_D_MESG Size - 2 Bytes, 20 to 21 bytes. More... | |
| u8 | C [XSECURE_LMS_C_FIELD_SIZE] |
| C - Randomizer per data Size - 32 Byte, 22 to 53 bytes. More... | |
| u8 | Digest [XSECURE_LMS_DIGEST_SIZE] |
| Digest - Digest of data to be authenticated Size - 32 bytes, 0 to 31 bytes. More... | |
| u8 | Checksum [XSECURE_LMS_CHECKSUM_FIELD_SIZE] |
| Checksum - Checksum on Digest Size - 2 bytes, 32nd & 33rd byte. More... | |
| #define XSECURE_LMS_DIGEST_CHECKSUM_SIZE |
Digest of data to be authenticated concatenated with checksum value.
| #define XSECURE_LMS_MESSAGE_TO_DIGEST_PREFIX_SIZE |
Prefix fields length, before sending actual data to sha engine for digest.
Referenced by XSecure_LmsHashMessage().
| #define XSECURE_LMS_OTS_PUB_KEY_TOTAL_SIZE |
OTS Public key total size.
| #define XSECURE_LMS_OTS_PUBKEY_I_OFFSET (0U) |
Offset of 'I' field in OTS Public key.
| #define XSECURE_LMS_OTS_PUBKEY_Q_OFFSET |
Offset of 'q' field in OTS Public key.
| #define XSECURE_LMS_OTS_SIGN_C_FIELD_OFFSET |
Offset of 'C' field in OTS Signature buffer.
Referenced by XSecure_HssInit().
| #define XSECURE_LMS_OTS_SIGN_TYPE_FIELD_OFFSET (0U) |
Offset of 'Type' field in OTS Signature buffer.
Referenced by XSecure_LmsSignatureVerification().
| #define XSECURE_LMS_OTS_SIGN_VERIF_CHAIN_TMP_BUFF_CURRENT_SIZE | ( | p | ) |
Total Size of buffer used in OTS verification, while considering current 'p' parameter.
| #define XSECURE_LMS_OTS_SIGN_VERIF_CHAIN_TMP_BUFF_D_PBLC_OFFSET |
Offset of D_PBLC field in temporary buffer, where inner loops result is concatenated during OTS operations.
| #define XSECURE_LMS_OTS_SIGN_VERIF_CHAIN_TMP_BUFF_I_OFFSET (0U) |
Offset of 'I' field in temporary buffer, where inner loops result is concatenated during OTS operations.
| #define XSECURE_LMS_OTS_SIGN_VERIF_CHAIN_TMP_BUFF_Q_OFFSET |
Offset of 'q' field in temporary buffer, where inner loops result is concatenated during OTS operations.
| #define XSECURE_LMS_OTS_SIGN_VERIF_CHAIN_TMP_BUFF_TOTAL_SIZE |
Max possible size as supported
only till XSECURE_LMS_OTS_W2
Total MAX Size of buffer used in OTS verification
| #define XSECURE_LMS_OTS_SIGN_VERIF_CHAIN_TMP_BUFF_Z_OFFSET |
Offset of 'z' field in temporary buffer, where inner loops result is concatenated during OTS operations.
| #define XSECURE_LMS_OTS_SIGN_VERIF_TMP_BUFF_I_OFFSET (1U) |
Offset of 'I' field in temporary buffer, where inner loops result are stored, for reprocessing during OTS operations.
| #define XSECURE_LMS_OTS_SIGN_VERIF_TMP_BUFF_i_OFFSET |
Offset of 'i' field in temporary buffer, where inner loops result are stored, for reprocessing during OTS operations.
| #define XSECURE_LMS_OTS_SIGN_VERIF_TMP_BUFF_j_OFFSET |
Offset of 'j' field in temporary buffer, where inner loops result are stored, for reprocessing during OTS operations.
| #define XSECURE_LMS_OTS_SIGN_VERIF_TMP_BUFF_Q_OFFSET |
Offset of 'q' field in temporary buffer, where inner loops result are stored, for reprocessing during OTS operations.
| #define XSECURE_LMS_OTS_SIGN_VERIF_TMP_BUFF_TOTAL_SIZE |
Total size of buffer, XSecure_LmsOtsHashPerDigit.
| #define XSECURE_LMS_OTS_SIGN_VERIF_TMP_BUFF_Y_OFFSET |
Offset of 'Y' field in temporary buffer, where inner loops result are stored, for reprocessing during OTS operations.
| #define XSECURE_LMS_OTS_SIGN_Y_FIELD_OFFSET |
Offset of 'Y' field in OTS Signature buffer.
| #define XSECURE_LMS_OTS_TYPE_MAX_SUPPORTED (7U) |
Max supported types, used for creating lookup table for parameters for types supported number should be max valid + 1 (as first slot will be for invalid parameterXSecure_LmsOtsType XSecure_LmsOtsType.
Referenced by XSecure_LmsOtsLookupParamSet().
| typedef union XSecure_LmsDataDigest_ XSecure_LmsDataDigest |
Digest for message to be authenticated, along with checksum.
Size = Digest (32) + Check sum (2) = 34 Bytes
Temporary buffer, used to send prefix fields to calculate digest for data to be authenticate.
Size = I (16) + q (4) + D_MESG (2) + C (32) = 54 Bytes
| typedef union XSecure_LmsOtsHashPerDigit_ XSecure_LmsOtsHashPerDigit |
Temporary buffer, used in LMS OTS signature verification, used in hash chain to arrive at values which will be concatenated and hashed to get public value.
Size = 1 + 16 + 4 + 2 + 1 + H Len (32) = 56 Bytes
| typedef union XSecure_LmsOtsPublicKey_ XSecure_LmsOtsPublicKey |
LMS OTS Public key structure.
Size = 4 + 16 + 4 + H Len (32) = 56 Bytes
| typedef struct XSecure_LmsOtsSignature_ XSecure_LmsOtsSignature |
Partial LMS OTS Signature structure.
struct Size = 4 + 32 Sign size = 4 + 32 + (p * n) = 4 + n * (p+1)
Structure used when validating LMS OTS, once hash chain is completed, result needs to be stored so that they can be further concatenated and hashed to get OTS public key, this provides a way to access members and fill data in a structured way.
Size = 16(I) + 4(q) + 2(D_PBLC) + (p * H Len (32))
| enum XSecure_LmsOtspIndex |
| enum XSecure_LmsOtsType |
Types of LMS_OTS supported.
| enum XSecure_LmsOtsuIndex |
| enum XSecure_LmsOtsvIndex |
| enum XSecure_LmsOtsWIndex |
| u32 XSecure_LmsOtsCoeff | ( | u8 const *const | Arr, |
| const u32 | ArrayIndex, | ||
| const u32 | w | ||
| ) |
This function extracts the digits from the array for bytes.
[1, 2, 3, 4] ^ | coef(S, 0, 4)
If i is larger than the number of w-bit values in S, then coef(S, i, w) is undefined, this cant be checked here
| Array | - Byte array from where the digit needs to be picked |
| ArrayIndex | - When array is divided into array of digits, i represents the index of digit |
| w - Width in bits, for each digit allowed values |
Referenced by XSecure_LmsOtsComputeChecksum().
| int XSecure_LmsOtsComputeChecksum | ( | const u8 *const | Array, |
| const u32 | ArrayLen, | ||
| const u32 | w, | ||
| const u32 | ls, | ||
| u32 *const | Checksum | ||
| ) |
This function calculates the checksum for a given array.
| Array | - Byte array ffor which checksum needs to be calculated |
| ArrayLen- | Length of input array |
| w | - Width in bits, for each digit allowed values |
| ls | - Number of bits to left-shift the calculated checksum |
| Checksum- | Pointer to address, where computed checksum needs to be copied |
References XSECURE_LMS_OTS_CHECKSUM_BUFF_INVALID_LEN_ERROR, and XSecure_LmsOtsCoeff().
| int XSecure_LmsOtsLookupParamSet | ( | XSecure_LmsOtsType | Type, |
| XSecure_LmsOtsParam ** | Parameters | ||
| ) |
This function returns the parameters for the type of LMS OTS type.
| Type | XSecure_LmsOtsType, type of OTS algorithm selected |
| Parameters | Pointer to array location where all predefined parameter values are present XSecure_LmsOtsParam |
lookup table for 'n', 'w', 'p', 'ls' & Signature lengths
References XSECURE_LMS_OTS_LS_NOT_SUPPORTED, XSECURE_LMS_OTS_NOT_SUPPORTED, XSECURE_LMS_OTS_SHA256_N32_W4, XSECURE_LMS_OTS_SHA256_N32_W8, XSECURE_LMS_OTS_SHAKE_N32_W2, XSECURE_LMS_OTS_SHAKE_N32_W4, XSECURE_LMS_OTS_SHAKE_N32_W8, XSECURE_LMS_OTS_TYPE_LOOKUP_GLITCH_ERROR, XSECURE_LMS_OTS_TYPE_MAX_SUPPORTED, XSECURE_LMS_OTS_TYPE_UNSUPPORTED_ERROR, XSECURE_LMS_OTS_W4, XSECURE_LMS_OTS_W4_LS, XSECURE_LMS_OTS_W4_P, XSECURE_LMS_OTS_W4_U, XSECURE_LMS_OTS_W4_V, XSECURE_LMS_OTS_W8, XSECURE_LMS_OTS_W8_LS, XSECURE_LMS_OTS_W8_P, XSECURE_LMS_OTS_W8_U, XSECURE_LMS_OTS_W8_V, XSECURE_SHA2_256_HASH_LEN, XSECURE_SHAKE_256, and XSECURE_SHAKE_256_HASH_LEN.
Referenced by XSecure_HssFinish(), XSecure_HssInit(), and XSecure_LmsSignatureVerification().
| u8 C[XSECURE_LMS_C_FIELD_SIZE] |
C - Randomizer per data Size - 32 Byte, 22 to 53 bytes.
| u8 Checksum[XSECURE_LMS_CHECKSUM_FIELD_SIZE] |
Checksum - Checksum on Digest Size - 2 bytes, 32nd & 33rd byte.
| u8 D_MESG[XSECURE_LMS_D_MESG_FIELD_SIZE] |
D_MESG - XSECURE_D_MESG Size - 2 Bytes, 20 to 21 bytes.
| u8 D_PBLC[2U] |
D_PBLC - XSECURE_D_PBLC Size - 2 Bytes, 20 to 21 bytes.
| u8 Digest[XSECURE_LMS_DIGEST_SIZE] |
Digest - Digest of data to be authenticated Size - 32 bytes, 0 to 31 bytes.
| u8 I[XSECURE_LMS_I_FIELD_SIZE] |
I - Merkle Tree's unique identifier (uniformly random 16-byte string) Size - 16 bytes, 4 to 19 bytes in public key.
I - Merkle Tree's unique identifier (uniformly random 16-byte string) Size - 16 bytes, 0 to 15 bytes.
I - Merkle Tree's unique identifier (uniformly random 16-byte string) Size - 16 bytes, 1 to 16 bytes.
| u16 i |
i - Digit position in (Digest || Checksum), 0 to (p-1) digits.
Size - 2 Bytes, 21 to 22 bytes
| u8 j |
j - Index for inner loop during signature verification, starts at digit value in (Digest || Checksum) ends at (2^w - 1).
Size - 1 Byte, 23nd byte
| u8 K[XSECURE_LMS_OTS_PUB_KEY_K_FIELD_SIZE] |
K - H(I || u32str(q) || u16str(D_PBLC) || y[0] || ...
|| y[p-1]) H is a hash function, ROM supports only SHA2-256 and SHAKE-256 both are of 32Byte output len I & q remain same as described above D_PBLC is a constant XSECURE_D_PBLC y[0] to y[p-1] is calculated from private key
Referenced by XSecure_EllipticGenerateSignature_64Bit(), XSecure_EllipticPwct(), XSecure_EllipticSignGenerateKat(), and XSecure_GetKatEccEphemeralKey().
| u32 q |
q - The leaf number q, goes from 0 on left most leaf to right most (2^h -1), in a single tree Size - 4 bytes, 20 to 23 bytes in public key
q - The leaf number q, goes from 0 on left most leaf to right most (2^h -1), in a single tree Size - 4 bytes, 16 to 19 bytes
q - The leaf number q, goes from 0 on left most leaf to right most (2^h -1), in a single tree Size - 4 bytes, 17 to 20 bytes
| u8 Reserved |
1 reserved byte added at start of buffer, to manage word aligned sha finish copies to buffer
| XSecure_LmsOtsType Type |
Type XSecure_LmsOtsType Size - 4 bytes, 0 to 3 bytes in public key.
| u8 y[XSECURE_LMS_OTS_SIGN_VERIF_TMP_BUFF_Y_SIZE] |
y[] - 'n' bytes picked from LMS OTS signatures.
y[0] to y[p-1], each 'n' sized bytes will be copied here and passed into HASH engine along with other fields. Size - 32 Bytes, 24 to 55 bytes
| u8 z[XSECURE_LMS_OTS_SIGN_VERIF_CHAIN_TMP_BUFF_z_SIZE] |
z - Each z is a XSECURE_LMS_N_FIELD_SIZE byte length, and ranges from 0 to p-1 Size - (32 Bytes * p)