le_iks_rsa_interface.h

    1 
    2 
    3 /*
    4  * ====================== WARNING ======================
    5  *
    6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    7  * DO NOT MODIFY IN ANY WAY.
    8  *
    9  * ====================== WARNING ======================
   10  */
   11 
   12 /**
   13  * @page c_iks_rsa IoT Keystore RSA API
   14  *
   15  * @ref le_iks_rsa_interface.h "API Reference"
   16  *
   17  * <HR>
   18  *
   19  * Legato IoT Keystore APIs for performing generation/verification of signatures with RSA-PSS as
   20  * well as encryption/decryption of short messages using RSA OAEP.
   21  *
   22  * <HR>
   23  *
   24  * Copyright (C) Sierra Wireless Inc.
   25  */
   26 /**
   27  * @file le_iks_rsa_interface.h
   28  *
   29  * Legato @ref c_iks_rsa API
   30  *
   31  * Copyright (C) Sierra Wireless Inc.
   32  */
   33 
   34 #ifndef LE_IKS_RSA_INTERFACE_H_INCLUDE_GUARD
   35 #define LE_IKS_RSA_INTERFACE_H_INCLUDE_GUARD
   36 
   37 
   38 #include "legato.h"
   39 
   40 // Interface specific includes
   41 #include "le_iks_interface.h"
   42 
   43 // Internal includes for this interface
   44 #include "le_iks_rsa_common.h"
   45 /** @addtogroup le_iks_rsa le_iks_rsa API Reference
   46  * @{
   47  * @file le_iks_rsa_common.h
   48  * @file le_iks_rsa_interface.h **/
   49 //--------------------------------------------------------------------------------------------------
   50 /**
   51  * Type for handler called when a server disconnects.
   52  */
   53 //--------------------------------------------------------------------------------------------------
   54 typedef void (*le_iks_rsa_DisconnectHandler_t)(void *);
   55 
   56 //--------------------------------------------------------------------------------------------------
   57 /**
   58  *
   59  * Connect the current client thread to the service providing this API. Block until the service is
   60  * available.
   61  *
   62  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   63  * called before any other functions in this API.  Normally, ConnectService is automatically called
   64  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   65  *
   66  * This function is created automatically.
   67  */
   68 //--------------------------------------------------------------------------------------------------
   69 void le_iks_rsa_ConnectService
   70 (
   71     void
   72 );
   73 
   74 //--------------------------------------------------------------------------------------------------
   75 /**
   76  *
   77  * Try to connect the current client thread to the service providing this API. Return with an error
   78  * if the service is not available.
   79  *
   80  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   81  * called before any other functions in this API.  Normally, ConnectService is automatically called
   82  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   83  *
   84  * This function is created automatically.
   85  *
   86  * @return
   87  *  - LE_OK if the client connected successfully to the service.
   88  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
   89  *    bound.
   90  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
   91  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
   92  */
   93 //--------------------------------------------------------------------------------------------------
   94 le_result_t le_iks_rsa_TryConnectService
   95 (
   96     void
   97 );
   98 
   99 //--------------------------------------------------------------------------------------------------
  100 /**
  101  * Set handler called when server disconnection is detected.
  102  *
  103  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  104  * to continue without exiting, it should call longjmp() from inside the handler.
  105  */
  106 //--------------------------------------------------------------------------------------------------
  107 LE_FULL_API void le_iks_rsa_SetServerDisconnectHandler
  108 (
  109     le_iks_rsa_DisconnectHandler_t disconnectHandler,
  110     void *contextPtr
  111 );
  112 
  113 //--------------------------------------------------------------------------------------------------
  114 /**
  115  *
  116  * Disconnect the current client thread from the service providing this API.
  117  *
  118  * Normally, this function doesn't need to be called. After this function is called, there's no
  119  * longer a connection to the service, and the functions in this API can't be used. For details, see
  120  * @ref apiFilesC_client.
  121  *
  122  * This function is created automatically.
  123  */
  124 //--------------------------------------------------------------------------------------------------
  125 void le_iks_rsa_DisconnectService
  126 (
  127     void
  128 );
  129 
  130 
  131 //--------------------------------------------------------------------------------------------------
  132 /**
  133  * Encrypts a message with RSAES-OAEP (RSA Encryption Scheme - Optimal Asymmetric Encryption
  134  * Padding).
  135  *
  136  * The maximum plaintext size (pLen bytes) depends on the key size (kLen bytes) and the hash digest
  137  * size (hLen bytes) according to the equation:  pLen = kLen - 2*hLen - 2
  138  * For example, with a 2048 bit key using SHA-224 the maximum plaintext size is 226 bytes.
  139  *
  140  * An optional label associated with the message can be added.  The label is restricted to less than
  141  * or equal to MAX_LABEL_SIZE.  The same label must be provided during decryption.
  142  *
  143  * The ciphertext size is always kLen bytes (key size) and the ciphertextPtr buffer should be large
  144  * enough to hold the ciphertext.
  145  *
  146  * @return
  147  *      LE_OK if successful.
  148  *      LE_BAD_PARAMETER if the key reference is invalid
  149  *                       of if the key type is invalid
  150  *                       or if plaintextPtr, ciphertextPtr or ciphertextSizePtr is NULL.
  151  *      LE_OUT_OF_RANGE if either the labelSize or the plaintextSize is too big.
  152  *      LE_OVERFLOW if the ciphertext buffer is too small.
  153  *      LE_FAULT if there was an internal error.
  154  */
  155 //--------------------------------------------------------------------------------------------------
  156 le_result_t le_iks_rsa_Oaep_Encrypt
  157 (
  158     uint64_t keyRef,
  159         ///< [IN] Key reference.
  160     const uint8_t* labelPtr,
  161         ///< [IN] Label. NULL if not used.
  162     size_t labelSize,
  163         ///< [IN]
  164     const uint8_t* plaintextPtr,
  165         ///< [IN] Plaintext. NULL if not used.
  166     size_t plaintextSize,
  167         ///< [IN]
  168     uint8_t* ciphertextPtr,
  169         ///< [OUT] Buffer to hold the ciphertext.
  170     size_t* ciphertextSizePtr
  171         ///< [INOUT]
  172 );
  173 
  174 //--------------------------------------------------------------------------------------------------
  175 /**
  176  * Decrypts a message with RSAES-OAEP (RSA Encryption Scheme - Optimal Asymmetric Encryption
  177  * Padding).
  178  *
  179  * The maximum plaintext size (pLen bytes) depends on the key size (kLen bytes) and the hash digest
  180  * size (hLen bytes) according to the equation:  pLen = kLen - 2*hLen - 2
  181  * For example, with a 2048 bit key using SHA-224 the maximum plaintext size is 226 bytes.
  182  * The plaintextPtr buffer is assumed to be large enough to hold the plaintext.  A safe size for
  183  * this buffer is kLen.
  184  *
  185  * The optional label associated with the message is restricted to less than or equal to
  186  * MAX_LABEL_SIZE and should be the same label used for encryption.
  187  *
  188  * The ciphertext size is expected to be the same as the key size (kLen).
  189  *
  190  * @return
  191  *      LE_OK if successful.
  192  *      LE_BAD_PARAMETER if the key reference is invalid
  193  *                       or if the key type is invalid
  194  *                       or if the either the ciphertextPtr or plaintextSizePtr is NULL.
  195  *      LE_OUT_OF_RANGE if the labelSize is too big.
  196  *      LE_FORMAT_ERROR if the ciphertextSize does not match the key size.
  197  *      LE_OVERFLOW if the plaintextSizePtr is too small to hold the plaintext.
  198  *      LE_FAULT if the decryption failed.
  199  */
  200 //--------------------------------------------------------------------------------------------------
  201 le_result_t le_iks_rsa_Oaep_Decrypt
  202 (
  203     uint64_t keyRef,
  204         ///< [IN] Key reference.
  205     const uint8_t* labelPtr,
  206         ///< [IN] Label. NULL if not used.
  207     size_t labelSize,
  208         ///< [IN]
  209     const uint8_t* ciphertextPtr,
  210         ///< [IN] Ciphertext.
  211     size_t ciphertextSize,
  212         ///< [IN]
  213     uint8_t* plaintextPtr,
  214         ///< [OUT] Buffer to hold the plaintext.
  215     size_t* plaintextSizePtr
  216         ///< [INOUT]
  217 );
  218 
  219 //--------------------------------------------------------------------------------------------------
  220 /**
  221  * Generates a signature on the hash digest of a message with RSASSA-PSS (RSA Signature Scheme with
  222  * Appendix - Probabilistic Signature Scheme).
  223  *
  224  * Signatures are generally only created on a hash of a message rather than directly on the message
  225  * itself this function follows this paradigm.  However, the same hash function used to create the
  226  * signature must be used to create the digest of the message.  For example, if the key type is
  227  * LE_IKS_KEY_TYPE_PRIV_RSASSA_PSS_SHA512 then SHA512 muust be used to create the digest for the
  228  * message.  The digest size should be the output size of the hash function being used.
  229  *
  230  * The salt size should generally be small between 8 and 16 bytes.  Strictly, it must be less than
  231  * keySize - hLen - 2 where hLen is the output size of the hash function used to create the
  232  * signature.
  233  *
  234  * The signature size is always the size of the key.  The signature buffer should be large enough to
  235  * hold the signature.
  236  *
  237  * @return
  238  *      LE_OK if successful.
  239  *      LE_BAD_PARAMETER if the key reference is invalid
  240  *                       or if the key type is invalid
  241  *                       or if digestPtr, signaturePtr or signatureSizePtr are NULL.
  242  *      LE_OUT_OF_RANGE if either the saltSize or the digestSize is too big.
  243  *      LE_OVERFLOW if the signature buffer is too small.
  244  *      LE_FAULT if there was an internal error.
  245  */
  246 //--------------------------------------------------------------------------------------------------
  247 le_result_t le_iks_rsa_Pss_GenSig
  248 (
  249     uint64_t keyRef,
  250         ///< [IN] Key reference.
  251     uint32_t saltSize,
  252         ///< [IN] Salt size.
  253     const uint8_t* digestPtr,
  254         ///< [IN] Digest to sign.
  255     size_t digestSize,
  256         ///< [IN]
  257     uint8_t* signaturePtr,
  258         ///< [OUT] Buffer to hold the signature.
  259     size_t* signatureSizePtr
  260         ///< [INOUT]
  261 );
  262 
  263 //--------------------------------------------------------------------------------------------------
  264 /**
  265  * Verifies a signature of the hash digest of a message with RSASSA-PSS (RSA Signature Scheme with
  266  * Appendix - Probabilistic Signature Scheme).
  267  *
  268  * Signatures are generally only created on a hash of a message rather than directly on the message
  269  * itself this function follows this paradigm.  However, the same hash function used to create the
  270  * signature must be used to create the digest of the message.  For example, if the key type is
  271  * LE_IKS_KEY_TYPE_PRIV_RSASSA_PSS_SHA512 then SHA512 muust be used to create the digest for the
  272  * message.  The digest size should be the output size of the hash function being used.
  273  *
  274  * The salt size should generally be small between 8 and 16 bytes.  Strictly, it must be less than
  275  * keySize - hLen - 2 where hLen is the output size of the hash function used to create the
  276  * signature.
  277  *
  278  * The signature size should always the size of the key.
  279  *
  280  * @return
  281  *      LE_OK if successful.
  282  *      LE_BAD_PARAMETER if the key reference is invalid
  283  *                       or if the key type is invalid
  284  *                       or if either digestPtr or signaturePtr are NULL.
  285  *      LE_OUT_OF_RANGE if either the saltSize or the digestSize is too big.
  286  *      LE_FORMAT_ERROR if signatureSize does not match the key size.
  287  *      LE_FAULT if the signature is not valid.
  288  */
  289 //--------------------------------------------------------------------------------------------------
  290 le_result_t le_iks_rsa_Pss_VerifySig
  291 (
  292     uint64_t keyRef,
  293         ///< [IN] Key reference.
  294     uint32_t saltSize,
  295         ///< [IN] Salt size.
  296     const uint8_t* digestPtr,
  297         ///< [IN] Digest to sign.
  298     size_t digestSize,
  299         ///< [IN]
  300     const uint8_t* signaturePtr,
  301         ///< [IN] Signature of the message.
  302     size_t signatureSize
  303         ///< [IN]
  304 );
  305 
  306 /** @} **/
  307 
  308 #endif // LE_IKS_RSA_INTERFACE_H_INCLUDE_GUARD
le_iks_rsa_TryConnectService
le_result_t le_iks_rsa_TryConnectService(void)
le_result_t
le_result_t
Definition: le_basics.h:46
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)
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)
le_iks_rsa_SetServerDisconnectHandler
LE_FULL_API void le_iks_rsa_SetServerDisconnectHandler(le_iks_rsa_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_iks_rsa_common.h
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
legato.h
le_iks_rsa_ConnectService
void le_iks_rsa_ConnectService(void)
le_iks_interface.h
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)
le_iks_rsa_DisconnectHandler_t
void(* le_iks_rsa_DisconnectHandler_t)(void *)
Definition: le_iks_rsa_interface.h:54
le_iks_rsa_DisconnectService
void le_iks_rsa_DisconnectService(void)
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)