3.3.5. Asymmetric

3.3.5.1. Sign

To perform sign operation , the sequence of APIs looks as under.

../../_images/asymm-sign.png

Note

  1. To perform rsa sign and verify on plain data (with hash calculated inside SE), use sss_se05x_asymmetric_sign and sss_se05x_asymmetric_verify apis.

  2. Sign / Verify operations with Twisted Edward curve is supported only on plain data with hash calculated inside SE. Use sss_se05x_asymmetric_sign and sss_se05x_asymmetric_verify apis. Only SHA512 is supported.

3.3.5.2. Verify

To perform sign verify operation , the sequence of APIs looks as under:

../../_images/asymm-verify.png

3.3.5.3. Encryption

To encrypt the data , the API sequence is as under:

../../_images/asymm-encrypt.png

3.3.5.4. Decryption

To Decrypt the encrypted data , the API sequence is as under:

../../_images/asymm-decrypt.png

3.3.5.5. Reference Example

Before we use any Cryptographic operations, we need relevent Keys to be declared.

Here is a reference snippet to inject a key into the Secure Domain. (If the key was already existing in the Key Store, these steps are not needed)

    /* Pre-requisite for Signing Part*/
    status = sss_key_object_init(&keyPair, &pCtx->ks);
    ENSURE_OR_GO_CLEANUP(status == kStatus_SSS_Success);

    status = sss_key_object_allocate_handle(&keyPair,
        MAKE_TEST_ID(__LINE__),
        kSSS_KeyPart_Pair,
        kSSS_CipherType_EC_NIST_P,
        sizeof(keyPairData),
        kKeyObject_Mode_Persistent);
    ENSURE_OR_GO_CLEANUP(status == kStatus_SSS_Success);

    status = sss_key_store_set_key(&pCtx->ks, &keyPair, keyPairData, sizeof(keyPairData), EC_KEY_BIT_LEN, NULL, 0);
    ENSURE_OR_GO_CLEANUP(status == kStatus_SSS_Success);

Signing on a digest of length digestLen is performed as below.

    status = sss_asymmetric_context_init(&ctx_asymm, &pCtx->session, &keyPair, kAlgorithm_SSS_SHA256, kMode_SSS_Sign);
    ENSURE_OR_GO_CLEANUP(status == kStatus_SSS_Success);

    signatureLen = sizeof(signature);
    /* Do Signing */
    LOG_I("Do Signing");
    LOG_MAU8_I("digest", digest, digestLen);
    status = sss_asymmetric_sign_digest(&ctx_asymm, digest, digestLen, signature, &signatureLen);
    ENSURE_OR_GO_CLEANUP(status == kStatus_SSS_Success);
    LOG_MAU8_I("signature", signature, signatureLen);
    LOG_I("Signing Successful !!!");
    sss_asymmetric_context_free(&ctx_asymm);

After the above operation, signature has the signature using the key object keyPair.

3.3.5.6. RSA Encryption algorithms supported

Supported rsa encyption / decryption algotithms - PKCS1_OAEP and PKCS1_V1_5.

    kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA1   = SSS_ENUM_ALGORITHM(RSAES_PKCS1_OAEP, 0x01),
    kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA224 = SSS_ENUM_ALGORITHM(RSAES_PKCS1_OAEP, 0x02),
    kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA256 = SSS_ENUM_ALGORITHM(RSAES_PKCS1_OAEP, 0x03),
    kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA384 = SSS_ENUM_ALGORITHM(RSAES_PKCS1_OAEP, 0x04),
    kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA512 = SSS_ENUM_ALGORITHM(RSAES_PKCS1_OAEP, 0x05),
    kAlgorithm_SSS_RSAES_PKCS1_V1_5        = SSS_ENUM_ALGORITHM(RSAES_PKCS1_V1_5, 0x01),

3.3.5.7. RSA Signature algorithms supported

Supported rsa sign / verify algotithms - PKCS1_PSS_MGF1 , PKCS1_V1_5 and No_Padding.

Hash algorithms supported for sign/verify - SHA1, SHA224, SHA256, SHA384, SHA512

    kAlgorithm_SSS_RSASSA_PKCS1_V1_5_NO_HASH    = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, 0x01),
    kAlgorithm_SSS_RSASSA_PKCS1_V1_5_SHA1       = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, 0x02),
    kAlgorithm_SSS_RSASSA_PKCS1_V1_5_SHA224     = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, 0x03),
    kAlgorithm_SSS_RSASSA_PKCS1_V1_5_SHA256     = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, 0x04),
    kAlgorithm_SSS_RSASSA_PKCS1_V1_5_SHA384     = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, 0x05),
    kAlgorithm_SSS_RSASSA_PKCS1_V1_5_SHA512     = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, 0x06),
    kAlgorithm_SSS_RSASSA_PKCS1_PSS_MGF1_SHA1   = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_PSS_MGF1, 0x01),
    kAlgorithm_SSS_RSASSA_PKCS1_PSS_MGF1_SHA224 = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_PSS_MGF1, 0x02),
    kAlgorithm_SSS_RSASSA_PKCS1_PSS_MGF1_SHA256 = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_PSS_MGF1, 0x03),
    kAlgorithm_SSS_RSASSA_PKCS1_PSS_MGF1_SHA384 = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_PSS_MGF1, 0x04),
    kAlgorithm_SSS_RSASSA_PKCS1_PSS_MGF1_SHA512 = SSS_ENUM_ALGORITHM(RSASSA_PKCS1_PSS_MGF1, 0x05),
    kAlgorithm_SSS_RSASSA_NO_PADDING = SSS_ENUM_ALGORITHM(RSASSA_NO_PADDING, 0x01),

When using PKCS1_PSS_MGF1 padding, there are few limitations on hash algorithm with rsa key size as below,

RSA Bit Length

Valid Hash Algorithm

512

SHA1, SHA224

1024

SHA1, SHA224, SHA256, SHA384

1152

SHA1, SHA224, SHA256, SHA384, SHA512

2048

SHA1, SHA224, SHA256, SHA384, SHA512

3072

SHA1, SHA224, SHA256, SHA384, SHA512

4096

SHA1, SHA224, SHA256, SHA384, SHA512

3.3.5.8. ECC Signature algorithms supported

Supported hash values for ecc sign / verify - SHA1, SHA224, SHA256, SHA384, SHA512

    kAlgorithm_SSS_ECDSA_SHA1   = SSS_ENUM_ALGORITHM(ECDSA, 0x01),
    kAlgorithm_SSS_ECDSA_SHA224 = SSS_ENUM_ALGORITHM(ECDSA, 0x02),
    kAlgorithm_SSS_ECDSA_SHA256 = SSS_ENUM_ALGORITHM(ECDSA, 0x03),
    kAlgorithm_SSS_ECDSA_SHA384 = SSS_ENUM_ALGORITHM(ECDSA, 0x04),
    kAlgorithm_SSS_ECDSA_SHA512 = SSS_ENUM_ALGORITHM(ECDSA, 0x05),

OR

    kAlgorithm_SSS_SHA1   = SSS_ENUM_ALGORITHM(SHA, 0x01),
    kAlgorithm_SSS_SHA224 = SSS_ENUM_ALGORITHM(SHA, 0x02),
    kAlgorithm_SSS_SHA256 = SSS_ENUM_ALGORITHM(SHA, 0x03),
    kAlgorithm_SSS_SHA384 = SSS_ENUM_ALGORITHM(SHA, 0x04),
    kAlgorithm_SSS_SHA512 = SSS_ENUM_ALGORITHM(SHA, 0x05),

ECDAA algorithm

    kAlgorithm_SSS_ECDAA = SSS_ENUM_ALGORITHM(ECDAA, 0x01),