le_iks_rsa API Reference

Files

file  le_iks_rsa_common.h
 
file  le_iks_rsa_interface.h
 

Macros

#define LE_IKS_RSA_PUB_EXP   65537
 
#define LE_IKS_RSA_MAX_LABEL_SIZE   256
 

Typedefs

typedef void(* le_iks_rsa_DisconnectHandler_t) (void *)
 

Functions

void le_iks_rsa_ConnectService (void)
 
le_result_t le_iks_rsa_TryConnectService (void)
 
LE_FULL_API void le_iks_rsa_SetServerDisconnectHandler (le_iks_rsa_DisconnectHandler_t disconnectHandler, void *contextPtr)
 
void le_iks_rsa_DisconnectService (void)
 
le_result_t le_iks_rsa_Oaep_Encrypt (uint64_t keyRef, const uint8_t *labelPtr, size_t labelSize, const uint8_t *plaintextPtr, size_t plaintextSize, uint8_t *ciphertextPtr, size_t *ciphertextSizePtr)
 
le_result_t le_iks_rsa_Oaep_Decrypt (uint64_t keyRef, const uint8_t *labelPtr, size_t labelSize, const uint8_t *ciphertextPtr, size_t ciphertextSize, uint8_t *plaintextPtr, size_t *plaintextSizePtr)
 
le_result_t le_iks_rsa_Pss_GenSig (uint64_t keyRef, uint32_t saltSize, const uint8_t *digestPtr, size_t digestSize, uint8_t *signaturePtr, size_t *signatureSizePtr)
 
le_result_t le_iks_rsa_Pss_VerifySig (uint64_t keyRef, uint32_t saltSize, const uint8_t *digestPtr, size_t digestSize, const uint8_t *signaturePtr, size_t signatureSize)
 

Detailed Description

Macro Definition Documentation

◆ LE_IKS_RSA_MAX_LABEL_SIZE

#define LE_IKS_RSA_MAX_LABEL_SIZE   256

The RSA public exponent used by all IOT Key Store RSA functions.

◆ LE_IKS_RSA_PUB_EXP

#define LE_IKS_RSA_PUB_EXP   65537

The RSA public exponent used by all IOT Key Store RSA functions.

Typedef Documentation

◆ le_iks_rsa_DisconnectHandler_t

typedef void(* le_iks_rsa_DisconnectHandler_t) (void *)

Type for handler called when a server disconnects.

Function Documentation

◆ le_iks_rsa_ConnectService()

void le_iks_rsa_ConnectService ( void  )

Connect the current client thread to the service providing this API. Block until the service is available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client Specific Functions.

This function is created automatically.

◆ le_iks_rsa_DisconnectService()

void le_iks_rsa_DisconnectService ( void  )

Disconnect the current client thread from the service providing this API.

Normally, this function doesn't need to be called. After this function is called, there's no longer a connection to the service, and the functions in this API can't be used. For details, see Client Specific Functions.

This function is created automatically.

◆ le_iks_rsa_Oaep_Decrypt()

le_result_t le_iks_rsa_Oaep_Decrypt ( uint64_t  keyRef,
const uint8_t *  labelPtr,
size_t  labelSize,
const uint8_t *  ciphertextPtr,
size_t  ciphertextSize,
uint8_t *  plaintextPtr,
size_t *  plaintextSizePtr 
)

Decrypts a message with RSAES-OAEP (RSA Encryption Scheme - Optimal Asymmetric Encryption Padding).

The maximum plaintext size (pLen bytes) depends on the key size (kLen bytes) and the hash digest size (hLen bytes) according to the equation: pLen = kLen - 2*hLen - 2 For example, with a 2048 bit key using SHA-224 the maximum plaintext size is 226 bytes. The plaintextPtr buffer is assumed to be large enough to hold the plaintext. A safe size for this buffer is kLen.

The optional label associated with the message is restricted to less than or equal to MAX_LABEL_SIZE and should be the same label used for encryption.

The ciphertext size is expected to be the same as the key size (kLen).

Returns
LE_OK if successful. LE_BAD_PARAMETER if the key reference is invalid or if the key type is invalid or if the either the ciphertextPtr or plaintextSizePtr is NULL. LE_OUT_OF_RANGE if the labelSize is too big. LE_FORMAT_ERROR if the ciphertextSize does not match the key size. LE_OVERFLOW if the plaintextSizePtr is too small to hold the plaintext. LE_FAULT if the decryption failed.
Parameters
[in]keyRefKey reference.
[in]labelPtrLabel. NULL if not used.
[in]labelSize
[in]ciphertextPtrCiphertext.
[in]ciphertextSize
[out]plaintextPtrBuffer to hold the plaintext.
[in,out]plaintextSizePtr

◆ le_iks_rsa_Oaep_Encrypt()

le_result_t le_iks_rsa_Oaep_Encrypt ( uint64_t  keyRef,
const uint8_t *  labelPtr,
size_t  labelSize,
const uint8_t *  plaintextPtr,
size_t  plaintextSize,
uint8_t *  ciphertextPtr,
size_t *  ciphertextSizePtr 
)

Encrypts a message with RSAES-OAEP (RSA Encryption Scheme - Optimal Asymmetric Encryption Padding).

The maximum plaintext size (pLen bytes) depends on the key size (kLen bytes) and the hash digest size (hLen bytes) according to the equation: pLen = kLen - 2*hLen - 2 For example, with a 2048 bit key using SHA-224 the maximum plaintext size is 226 bytes.

An optional label associated with the message can be added. The label is restricted to less than or equal to MAX_LABEL_SIZE. The same label must be provided during decryption.

The ciphertext size is always kLen bytes (key size) and the ciphertextPtr buffer should be large enough to hold the ciphertext.

Returns
LE_OK if successful. LE_BAD_PARAMETER if the key reference is invalid of if the key type is invalid or if plaintextPtr, ciphertextPtr or ciphertextSizePtr is NULL. LE_OUT_OF_RANGE if either the labelSize or the plaintextSize is too big. LE_OVERFLOW if the ciphertext buffer is too small. LE_FAULT if there was an internal error.
Parameters
[in]keyRefKey reference.
[in]labelPtrLabel. NULL if not used.
[in]labelSize
[in]plaintextPtrPlaintext. NULL if not used.
[in]plaintextSize
[out]ciphertextPtrBuffer to hold the ciphertext.
[in,out]ciphertextSizePtr

◆ le_iks_rsa_Pss_GenSig()

le_result_t le_iks_rsa_Pss_GenSig ( uint64_t  keyRef,
uint32_t  saltSize,
const uint8_t *  digestPtr,
size_t  digestSize,
uint8_t *  signaturePtr,
size_t *  signatureSizePtr 
)

Generates a signature on the hash digest of a message with RSASSA-PSS (RSA Signature Scheme with Appendix - Probabilistic Signature Scheme).

Signatures are generally only created on a hash of a message rather than directly on the message itself this function follows this paradigm. However, the same hash function used to create the signature must be used to create the digest of the message. For example, if the key type is LE_IKS_KEY_TYPE_PRIV_RSASSA_PSS_SHA512 then SHA512 muust be used to create the digest for the message. The digest size should be the output size of the hash function being used.

The salt size should generally be small between 8 and 16 bytes. Strictly, it must be less than keySize - hLen - 2 where hLen is the output size of the hash function used to create the signature.

The signature size is always the size of the key. The signature buffer should be large enough to hold the signature.

Returns
LE_OK if successful. LE_BAD_PARAMETER if the key reference is invalid or if the key type is invalid or if digestPtr, signaturePtr or signatureSizePtr are NULL. LE_OUT_OF_RANGE if either the saltSize or the digestSize is too big. LE_OVERFLOW if the signature buffer is too small. LE_FAULT if there was an internal error.
Parameters
[in]keyRefKey reference.
[in]saltSizeSalt size.
[in]digestPtrDigest to sign.
[in]digestSize
[out]signaturePtrBuffer to hold the signature.
[in,out]signatureSizePtr

◆ le_iks_rsa_Pss_VerifySig()

le_result_t le_iks_rsa_Pss_VerifySig ( uint64_t  keyRef,
uint32_t  saltSize,
const uint8_t *  digestPtr,
size_t  digestSize,
const uint8_t *  signaturePtr,
size_t  signatureSize 
)

Verifies a signature of the hash digest of a message with RSASSA-PSS (RSA Signature Scheme with Appendix - Probabilistic Signature Scheme).

Signatures are generally only created on a hash of a message rather than directly on the message itself this function follows this paradigm. However, the same hash function used to create the signature must be used to create the digest of the message. For example, if the key type is LE_IKS_KEY_TYPE_PRIV_RSASSA_PSS_SHA512 then SHA512 muust be used to create the digest for the message. The digest size should be the output size of the hash function being used.

The salt size should generally be small between 8 and 16 bytes. Strictly, it must be less than keySize - hLen - 2 where hLen is the output size of the hash function used to create the signature.

The signature size should always the size of the key.

Returns
LE_OK if successful. LE_BAD_PARAMETER if the key reference is invalid or if the key type is invalid or if either digestPtr or signaturePtr are NULL. LE_OUT_OF_RANGE if either the saltSize or the digestSize is too big. LE_FORMAT_ERROR if signatureSize does not match the key size. LE_FAULT if the signature is not valid.
Parameters
[in]keyRefKey reference.
[in]saltSizeSalt size.
[in]digestPtrDigest to sign.
[in]digestSize
[in]signaturePtrSignature of the message.
[in]signatureSize

◆ le_iks_rsa_SetServerDisconnectHandler()

LE_FULL_API void le_iks_rsa_SetServerDisconnectHandler ( le_iks_rsa_DisconnectHandler_t  disconnectHandler,
void *  contextPtr 
)

Set handler called when server disconnection is detected.

When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants to continue without exiting, it should call longjmp() from inside the handler.

◆ le_iks_rsa_TryConnectService()

le_result_t le_iks_rsa_TryConnectService ( void  )

Try to connect the current client thread to the service providing this API. Return with an error if the service is not available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client Specific Functions.

This function is created automatically.

Returns
  • LE_OK if the client connected successfully to the service.
  • LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  • LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  • LE_COMM_ERROR if the Service Directory cannot be reached.