xilsecure
Vitis Drivers API Documentation
Functions
xsecure_lms_core.c File Reference

Overview

This file consists definitions of LMS authentication routines. 

MODIFICATION HISTORY:
Ver   Who  Date        Changes
----- ---- -------- -------------------------------------------------------
5.4   kal  07/24/24  Initial release
      kal  01/30/25  Update LMS/HSS APIs to accept the original data instead
                     of pre calculated hash.
 
Note





Functions


int XSecure_LmsSignatureVerification (XSecure_Sha *ShaInstPtr, XPmcDma *DmaPtr, XSecure_LmsSignVerifyParams *LmsSignVerifyParams)


 This function performs LMS level signature verification.  More...


 


int XSecure_HssInit (XSecure_Sha *ShaInstPtr, XPmcDma *DmaPtr, XSecure_HssInitParams *HssInitParams)


 This function Initiates LMS Signature verification process.  More...


 


int XSecure_LmsHashMessage (XSecure_Sha *ShaInstPtr, u8 *Data, u32 DataLen, XSecure_ShaMode Mode)


 This function calculates the Digest of data to authenticate to initiate the process of LMS verification.  More...


 


int XSecure_HssFinish (XSecure_Sha *ShaInstPtr, XPmcDma *DmaPtr, u8 *SignBuff, u32 SignatureLen)


 This function Completes LMS Signature verification process.  More...


 


int XSecure_GetLmsHashAlgo (u32 PubAlgo, const u8 *const PubKey, XSecure_ShaMode *SignAlgo)


 This function returns public key LMS type.  More...


 




Function Documentation






      

        

          int XSecure_GetLmsHashAlgo 
          (
          u32 
          PubAlgo, 
        

        

          
          
          const u8 *const 
          PubKey, 
        

        

          
          
          XSecure_ShaMode * 
          SignAlgo 
        

        

          
          )
          
        

      





This function returns public key LMS type. 


Parameters

  

    
PubAlgo- Algorithm selected by current PDI 

    
PubKey- pointer to PPK location, PPK is used to detect the variant of LMS selected

  

  




Returns
    

  • XST_SUCCESS - If operation success, otherwise following errors
    • 

  • XSECURE_LMS_KAT_PUB_KEY_UNSUPPORTED_LMS_TYPE_ERROR 
    • 





Public key's LMS type


LMS Parameters extracted from Public Key 



References XSECURE_LMS_HSS_L0_PUB_KEY_LMS_TYPE_UNSUPPORTED_ERROR, XSECURE_LMS_NOT_SUPPORTED, XSecure_LmsLookupParamSet(), and XSecure_Printf.











      

        

          int XSecure_HssFinish 
          (
          XSecure_Sha * 
          ShaInstPtr, 
        

        

          
          
          XPmcDma * 
          DmaPtr, 
        

        

          
          
          u8 * 
          SignBuff, 
        

        

          
          
          u32 
          SignatureLen 
        

        

          
          )
          
        

      





This function Completes LMS Signature verification process. 


    Data should have been pre-processed before calling this function, by
    calling @ref XSecure_HssInit & @ref XSecure_LmsHashMessage in sequence

Parameters

  

    
SignBuff- Pointer to Signature buffer 

    
SignatureLen- Length of signature buffer

  

  




Returns
XST_SUCCESS - If operation success, otherwise following errors 


Signature Length should be at least 4 bytes 



References XSecure_LmsParam::mh, XSECURE_LMS_HSS_L0_PUB_KEY_AUTH_FAILED_ERROR, XSECURE_LMS_HSS_L1_PUB_KEY_LMS_OTS_TYPE_UNSUPPORTED_ERROR, XSECURE_LMS_HSS_L1_PUB_KEY_LMS_TYPE_2_UNSUPPORTED_ERROR, XSECURE_LMS_HSS_L1_SIGN_INVALID_LEN_2_ERROR, XSECURE_LMS_HSS_OTS_SIGN_INVALID_LEN_1_ERROR, XSECURE_LMS_NOT_SUPPORTED, XSECURE_LMS_OTS_NOT_SUPPORTED, XSecure_LmsLookupParamSet(), XSecure_LmsOtsLookupParamSet(), XSecure_LmsSignatureVerification(), and XSecure_Printf.



Referenced by XSecure_HssSha2256Kat(), and XSecure_HssShake256Kat().











      

        

          int XSecure_HssInit 
          (
          XSecure_Sha * 
          ShaInstPtr, 
        

        

          
          
          XPmcDma * 
          DmaPtr, 
        

        

          
          
          XSecure_HssInitParams * 
          HssInitParams 
        

        

          
          )
          
        

      





This function Initiates LMS Signature verification process. 


            Completes all upper level Merkle trees verification and prepares
            for data's Digest calculation

Parameters

  

    
[in]Signature- Pointer to Signature buffer 

    
[in]SignatureLen- Length of signature buffer 

    
[in]PublicKey- Pointer to public key buffer 

    
[in]PublicKeyLen- Length of public key buffer

  

  




Returns
    

  • XST_SUCCESS - If operation success, otherwise following errors 
    • 





Signature structure u32str(Nspk) || signed_pub_key[0] || ... || signed_pub_key[Nspk-1] || sig[Nspk] u32str(Nspk) || sig[0] || pub[1] || ... || sig[Nspk-1] || pub[Nspk] || sig[Nspk]


Public key of lower level is used as a message to be authenticated, and signature of that level to back calculate the public key at that level. if this is happening for top most tree then value will be HSS public key saved as PPK or SPK, in turn all the levels above [levels - 1] are verified, so when the actual message is verified using lowest tree's leaf node, as the public key for that tree (lowest) is already verified, message is authenticated.


PLM Supports two levels trees, level-0 & 1 namely. For KAT, only 1 levels is required, which is level-0. for KAT the following condition is skipped


Parse HSS/Current level's public key provided, determine the expected signature length of sig[0]



References XSecure_LmsDataDigestFixedFields_::C, XSecure_LmsPublicKey_::I, XSecure_LmsDataDigestFixedFields_::I, XSecure_LmsParam::mh, XSecure_LmsDataDigestFixedFields_::q, XSECURE_HSS_PUBLIC_KEY_TOTAL_SIZE, XSECURE_LMS_HSS_L0_PUB_KEY_AUTH_FAILED_ERROR, XSECURE_LMS_HSS_L0_PUB_KEY_LMS_OTS_TYPE_UNSUPPORTED_ERROR, XSECURE_LMS_HSS_L0_PUB_KEY_LMS_TYPE_UNSUPPORTED_ERROR, XSECURE_LMS_HSS_L0_SIGN_INVALID_LEN_2_ERROR, XSECURE_LMS_HSS_L1_PUB_KEY_LMS_TYPE_1_UNSUPPORTED_ERROR, XSECURE_LMS_HSS_PUB_KEY_INVALID_LEN_2_ERROR, XSECURE_LMS_HSS_SIGN_LEVEL_UNSUPPORTED_ERROR, XSECURE_LMS_HSS_SIGN_PUB_KEY_LEVEL_MISMATCH_ERROR, XSECURE_LMS_NOT_SUPPORTED, XSECURE_LMS_OTS_NOT_SUPPORTED, XSECURE_LMS_OTS_SIGN_C_FIELD_OFFSET, XSECURE_LMS_PUB_OP_FAILED_1_ERROR, XSECURE_LMS_PUB_OP_FAILED_ERROR, XSECURE_LMS_SIGN_VERIFY_BH_AND_TYPE_SHA_ALGO_MISMATCH_L0_ERROR, XSecure_LmsLookupParamSet(), XSecure_LmsOtsLookupParamSet(), XSecure_LmsSignatureVerification(), and XSecure_Printf.



Referenced by XSecure_HssSha2256Kat(), and XSecure_HssShake256Kat().











      

        

          int XSecure_LmsHashMessage 
          (
          XSecure_Sha * 
          ShaInstPtr, 
        

        

          
          
          u8 * 
          Data, 
        

        

          
          
          u32 
          DataLen, 
        

        

          
          
          XSecure_ShaMode 
          Mode 
        

        

          
          )
          
        

      





This function calculates the Digest of data to authenticate to initiate the process of LMS verification. 


Parameters

  

    
Data- Data to be authenticated 

    
DataLen- Length of data to be authenticated

  

  




Returns
    

  • XST_SUCCESS - If operation success, otherwise following errors 
    • 






References XSecure_LmsDataDigestFixedFields_::D_MESG, and XSECURE_LMS_MESSAGE_TO_DIGEST_PREFIX_SIZE.



Referenced by XSecure_HssSha2256Kat(), and XSecure_HssShake256Kat().











      

        

          int XSecure_LmsSignatureVerification 
          (
          XSecure_Sha * 
          ShaInstPtr, 
        

        

          
          
          XPmcDma * 
          DmaPtr, 
        

        

          
          
          XSecure_LmsSignVerifyParams * 
          LmsSignVerifyParams 
        

        

          
          )
          
        

      





This function performs LMS level signature verification. 


Parameters

  

    
Data- Data to be authenticated, will be passed to LMS OTS signature verification 

    
DataLen- Length of data to be authenticated, will be passed to LMS OTS signature verification 

    
PreHashedMsg- If TRUE, then Data contains digest, if FALSE contains raw msg to be authenticated 

    
LmsSign- Pointer to LMS signature buffer for a tree 

    
LmsSignLen- Length of LMS signature 

    
ExpectedPubKey- Pointer to expected LMS public key 

    
PubKeyLen- Length of LMS public key

  

  




Returns
XST_SUCCESS - if operation success, otherwise following errors 


Used to find 32 byte value from LMS signature array


    

  1. Public key checks 1, 2a, 2b - Length should be atleast 8 bytes to be able to fetch Type of algo used for LMS & LMS OTS 2c - Once Type is extracted, set m 2d - Public key should be == 24 + m otherwise stop process and raise error
    2. 



6.1: Standard recommends less than 8 is not valid, this check covers 4a.1


6.2a Extracting Public key LMS Type, Big Endian to Little Endian


6.2b Extracting Public key LMS OTS Type, Big Endian to Little Endian


6.2d: Length of key check, should be equal to 24 + m, covers 4a.2b


6a. Signature checks 1 - Length should be atleast 8 bytes long 2a - Parse 'q', OTS 'Type' 2b,2c - OTS 'Type' should match with pub key OTS 'Type' 2d - Set 'n', 'p' from signature OTS 'Type', 2d - Length should be AT LEAST (12 + n * (p + 1)), this is to check if signature has enough for OTS signature component 2e,2f - OTS signature [4 to (7 + n (p + 1))] 2g - Set LMS signature Type [(8 + n (p + 1)) to (11 + n (p + 1)) bytes], LMS signature Type should match with LMS public 'Type' 2h - Set 'm', 'h' according to LMS signature Type 2i - 'q' >= 2^h or LMS signature Length != 12 + n * (p + 1) + m * h) then error


6a.1 Length should be at least 8 bytes


6a.2a parse q from LMS signature, Big Endian to Little Endian


6.2e parse I from LMS Public key


6a.2d: Total signature length check, should have at least LMS OTS signature required Length to proceed


6a.2h: Fetch the params for LMS signature from Type of signature, if not a valid/supported Type return error


6a.2i: Leaf nodes for a tree range from [0 to (2^h - 1)], to be a valid node number LMS signature length should be 12 + (n * (p + 1)) + (m * h) bytes


6a.3: LMS OTS candidate public key 'Kc'


6.4, Now that we have arrived at root value, compare with expected to see if it matches, comparision should be single glitch resistant



References XSecure_LmsPubKeyTmp_::D, XSecure_LmsParam::h, XSecure_LmsPubKeyTmp_::half_node_number, XSecure_LmsPubKeyTmp_::I, XSecure_LmsDataDigestFixedFields_::I, XSecure_LmsParam::m, XSecure_LmsParam::mh, XSecure_LmsDataDigestFixedFields_::q, XSecure_LmsPubKeyTmp_::Tmp, XSECURE_LMS_NOT_SUPPORTED, XSECURE_LMS_OTS_NOT_SUPPORTED, XSECURE_LMS_OTS_PUB_KEY_LMS_OTS_SIGN_TYPE_MISMATCH_ERROR, XSECURE_LMS_OTS_SIGN_TYPE_FIELD_OFFSET, XSECURE_LMS_PUB_KEY_AUTHENTICATION_FAILED_ERROR, XSECURE_LMS_PUB_KEY_AUTHENTICATION_GLITCH_ERROR, XSECURE_LMS_PUB_KEY_LMS_SIGN_TYPE_MISMATCH_ERROR, XSECURE_LMS_PUB_KEY_UNSUPPORTED_TYPE_1_ERROR, XSECURE_LMS_SIGN_EXPECTED_PUB_KEY_LEN_2_ERROR, XSECURE_LMS_SIGN_INVALID_NODE_NUMBER_ERROR, XSECURE_LMS_SIGN_LEN_1_ERROR, XSECURE_LMS_SIGN_LEN_2_ERROR, XSECURE_LMS_SIGN_LEN_3_ERROR, XSECURE_LMS_SIGN_OTS_OP_ERROR, XSECURE_LMS_SIGN_UNSUPPORTED_OTS_TYPE_1_ERROR, XSECURE_LMS_SIGN_UNSUPPORTED_TYPE_1_ERROR, XSECURE_LMS_SIGN_VERIF_SHA_DIGEST_INTR_EVEN_FAILED_ERROR, XSECURE_LMS_SIGN_VERIF_SHA_DIGEST_INTR_ODD_FAILED_ERROR, XSECURE_LMS_SIGN_VERIF_SHA_DIGEST_LEAF_FAILED_ERROR, XSecure_LmsLookupParamSet(), XSecure_LmsOtsLookupParamSet(), and XSecure_Printf.



Referenced by XSecure_HssFinish(), XSecure_HssInit(), XSecure_LmsSha2256Kat(), and XSecure_LmsShake256Kat().