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),

3.3.5.9. APIs

group sss_crypto_asymmetric

Asymmetric cryptographic operations like RSA / ECC/etc.

Functions

void sss_asymmetric_context_free(sss_asymmetric_t *context)

Asymmetric context release. The function frees asymmetric context.

Parameters
  • context: Pointer to asymmetric context.

sss_status_t sss_asymmetric_context_init(sss_asymmetric_t *context, sss_session_t *session, sss_object_t *keyObject, sss_algorithm_t algorithm, sss_mode_t mode)

Asymmetric context init. The function initializes asymmetric context with initial values.

Return

Status of the operation

Parameters
  • context: Pointer to asymmetric crypto context.

  • session: Associate SSS session with asymmetric context.

  • keyObject: Associate SSS key object with asymmetric context.

  • algorithm: One of the asymmetric algorithms defined by sss_algorithm_t.

  • mode: One of the modes defined by sss_mode_t.

Return Value

sss_status_t sss_asymmetric_decrypt(sss_asymmetric_t *context, const uint8_t *srcData, size_t srcLen, uint8_t *destData, size_t *destLen)

Asymmetric decryption The function uses asymmetric algorithm to decrypt data. Private key portion of a key pair is used for decryption.

Return

Status of the operation

Parameters
  • context: Pointer to asymmetric context.

  • srcData: Input buffer

  • srcLen: Length of the input in bytes

  • destData: Output buffer

  • destLen: Length of the output in bytes

Return Value

sss_status_t sss_asymmetric_encrypt(sss_asymmetric_t *context, const uint8_t *srcData, size_t srcLen, uint8_t *destData, size_t *destLen)

Asymmetric encryption The function uses asymmetric algorithm to encrypt data. Public key portion of a key pair is used for encryption.

Return

Status of the operation

Parameters
  • context: Pointer to asymmetric context.

  • srcData: Input buffer

  • srcLen: Length of the input in bytes

  • destData: Output buffer

  • destLen: Length of the output in bytes

Return Value

sss_status_t sss_asymmetric_sign_digest(sss_asymmetric_t *context, uint8_t *digest, size_t digestLen, uint8_t *signature, size_t *signatureLen)

Asymmetric signature of a message digest The function signs a message digest.

Return

Status of the operation

Parameters
  • context: Pointer to asymmetric context.

  • digest: Input buffer containing the input message digest

  • digestLen: Length of the digest in bytes

  • signature: Output buffer written with the signature of the digest

  • signatureLen: Length of the signature in bytes

Return Value

sss_status_t sss_asymmetric_verify_digest(sss_asymmetric_t *context, uint8_t *digest, size_t digestLen, uint8_t *signature, size_t signatureLen)

Asymmetric verify of a message digest The function verifies a message digest.

Return

Status of the operation

Parameters
  • context: Pointer to asymmetric context.

  • digest: Input buffer containing the input message digest

  • digestLen: Length of the digest in bytes

  • signature: Input buffer containing the signature to verify

  • signatureLen: Length of the signature in bytes

Return Value