sample_libcrypto.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240
  1. /*
  2. * Copyright (C) 2011-2018 Intel Corporation. All rights reserved.
  3. *
  4. * Redistribution and use in source and binary forms, with or without
  5. * modification, are permitted provided that the following conditions
  6. * are met:
  7. *
  8. * * Redistributions of source code must retain the above copyright
  9. * notice, this list of conditions and the following disclaimer.
  10. * * Redistributions in binary form must reproduce the above copyright
  11. * notice, this list of conditions and the following disclaimer in
  12. * the documentation and/or other materials provided with the
  13. * distribution.
  14. * * Neither the name of Intel Corporation nor the names of its
  15. * contributors may be used to endorse or promote products derived
  16. * from this software without specific prior written permission.
  17. *
  18. * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19. * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20. * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21. * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22. * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23. * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24. * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25. * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26. * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27. * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28. * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29. *
  30. */
  31. /**
  32. * File: sample_libcrypto.h
  33. * Description:
  34. * Interface for generic crypto library APIs.
  35. * Do NOT use this library in your actual product.
  36. * The purpose of this sample library is to aid the debugging of a
  37. * remote attestation service.
  38. * To achieve that goal, the sample remote attestation application
  39. * will use this sample library to generate reproducible messages.
  40. */
  41. #ifndef SAMPLE_LIBCRYPTO_H
  42. #define SAMPLE_LIBCRYPTO_H
  43. #include <stdint.h>
  44. typedef enum sample_status_t
  45. {
  46. SAMPLE_SUCCESS = 0,
  47. SAMPLE_ERROR_UNEXPECTED , // Unexpected error
  48. SAMPLE_ERROR_INVALID_PARAMETER , // The parameter is incorrect
  49. SAMPLE_ERROR_OUT_OF_MEMORY , // Not enough memory is available to complete this operation
  50. } sample_status_t;
  51. #define SAMPLE_SHA256_HASH_SIZE 32
  52. #define SAMPLE_ECP256_KEY_SIZE 32
  53. #define SAMPLE_NISTP_ECP256_KEY_SIZE (SAMPLE_ECP256_KEY_SIZE/sizeof(uint32_t))
  54. #define SAMPLE_AESGCM_IV_SIZE 12
  55. #define SAMPLE_AESGCM_KEY_SIZE 16
  56. #define SAMPLE_AESGCM_MAC_SIZE 16
  57. #define SAMPLE_CMAC_KEY_SIZE 16
  58. #define SAMPLE_CMAC_MAC_SIZE 16
  59. #define SAMPLE_AESCTR_KEY_SIZE 16
  60. typedef struct sample_ec256_dh_shared_t
  61. {
  62. uint8_t s[SAMPLE_ECP256_KEY_SIZE];
  63. } sample_ec256_dh_shared_t;
  64. typedef struct sample_ec256_private_t
  65. {
  66. uint8_t r[SAMPLE_ECP256_KEY_SIZE];
  67. } sample_ec256_private_t;
  68. typedef struct sample_ec256_public_t
  69. {
  70. uint8_t gx[SAMPLE_ECP256_KEY_SIZE];
  71. uint8_t gy[SAMPLE_ECP256_KEY_SIZE];
  72. } sample_ec256_public_t;
  73. typedef struct sample_ec256_signature_t
  74. {
  75. uint32_t x[SAMPLE_NISTP_ECP256_KEY_SIZE];
  76. uint32_t y[SAMPLE_NISTP_ECP256_KEY_SIZE];
  77. } sample_ec256_signature_t;
  78. typedef void* sample_sha_state_handle_t;
  79. typedef void* sample_cmac_state_handle_t;
  80. typedef void* sample_ecc_state_handle_t;
  81. typedef uint8_t sample_sha256_hash_t[SAMPLE_SHA256_HASH_SIZE];
  82. typedef uint8_t sample_aes_gcm_128bit_key_t[SAMPLE_AESGCM_KEY_SIZE];
  83. typedef uint8_t sample_aes_gcm_128bit_tag_t[SAMPLE_AESGCM_MAC_SIZE];
  84. typedef uint8_t sample_cmac_128bit_key_t[SAMPLE_CMAC_KEY_SIZE];
  85. typedef uint8_t sample_cmac_128bit_tag_t[SAMPLE_CMAC_MAC_SIZE];
  86. typedef uint8_t sample_aes_ctr_128bit_key_t[SAMPLE_AESCTR_KEY_SIZE];
  87. #ifdef __cplusplus
  88. #define EXTERN_C extern "C"
  89. #else
  90. #define EXTERN_C
  91. #endif
  92. #define SAMPLE_LIBCRYPTO_API EXTERN_C
  93. /* Rijndael AES-GCM
  94. * Parameters:
  95. * Return: sample_status_t - SAMPLE_SUCCESS on success, error code otherwise.
  96. * Inputs: sample_aes_gcm_128bit_key_t *p_key - Pointer to key used in encryption/decryption operation
  97. * uint8_t *p_src - Pointer to input stream to be encrypted/decrypted
  98. * uint32_t src_len - Length of input stream to be encrypted/decrypted
  99. * uint8_t *p_iv - Pointer to initialization vector to use
  100. * uint32_t iv_len - Length of initialization vector
  101. * uint8_t *p_aad - Pointer to input stream of additional authentication data
  102. * uint32_t aad_len - Length of additional authentication data stream
  103. * sample_aes_gcm_128bit_tag_t *p_in_mac - Pointer to expected MAC in decryption process
  104. * Output: uint8_t *p_dst - Pointer to cipher text. Size of buffer should be >= src_len.
  105. * sample_aes_gcm_128bit_tag_t *p_out_mac - Pointer to MAC generated from encryption process
  106. * NOTE: Wrapper is responsible for confirming decryption tag matches encryption tag */
  107. SAMPLE_LIBCRYPTO_API sample_status_t sample_rijndael128GCM_encrypt(const sample_aes_gcm_128bit_key_t *p_key, const uint8_t *p_src, uint32_t src_len,
  108. uint8_t *p_dst, const uint8_t *p_iv, uint32_t iv_len, const uint8_t *p_aad, uint32_t aad_len,
  109. sample_aes_gcm_128bit_tag_t *p_out_mac);
  110. /* Message Authentication - Rijndael 128 CMAC
  111. * Parameters:
  112. * Return: sample_status_t - SAMPLE_SUCCESS on success, error code otherwise.
  113. * Inputs: sample_cmac_128bit_key_t *p_key - Pointer to key used in encryption/decryption operation
  114. * uint8_t *p_src - Pointer to input stream to be MAC
  115. * uint32_t src_len - Length of input stream to be MAC
  116. * Output: sample_cmac_gcm_128bit_tag_t *p_mac - Pointer to resultant MAC */
  117. SAMPLE_LIBCRYPTO_API sample_status_t sample_rijndael128_cmac_msg(const sample_cmac_128bit_key_t *p_key, const uint8_t *p_src,
  118. uint32_t src_len, sample_cmac_128bit_tag_t *p_mac);
  119. /*
  120. * Elliptic Curve Crytpography - Based on GF(p), 256 bit
  121. */
  122. /* Allocates and initializes ecc context
  123. * Parameters:
  124. * Return: sample_status_t - SAMPLE_SUCCESS or failure as defined SAMPLE_Error.h.
  125. * Output: sample_ecc_state_handle_t ecc_handle - Handle to ECC crypto system */
  126. SAMPLE_LIBCRYPTO_API sample_status_t sample_ecc256_open_context(sample_ecc_state_handle_t* ecc_handle);
  127. /* Cleans up ecc context
  128. * Parameters:
  129. * Return: sample_status_t - SAMPLE_SUCCESS or failure as defined SAMPLE_Error.h.
  130. * Output: sample_ecc_state_handle_t ecc_handle - Handle to ECC crypto system */
  131. SAMPLE_LIBCRYPTO_API sample_status_t sample_ecc256_close_context(sample_ecc_state_handle_t ecc_handle);
  132. /* Populates private/public key pair - caller code allocates memory
  133. * Parameters:
  134. * Return: sample_status_t - SAMPLE_SUCCESS on success, error code otherwise.
  135. * Inputs: sample_ecc_state_handle_t ecc_handle - Handle to ECC crypto system
  136. * Outputs: sample_ec256_private_t *p_private - Pointer to the private key
  137. * sample_ec256_public_t *p_public - Pointer to the public key */
  138. SAMPLE_LIBCRYPTO_API sample_status_t sample_ecc256_create_key_pair(sample_ec256_private_t *p_private,
  139. sample_ec256_public_t *p_public,
  140. sample_ecc_state_handle_t ecc_handle);
  141. /* Computes DH shared key based on private B key (local) and remote public Ga Key
  142. * Parameters:
  143. * Return: sample_status_t - SAMPLE_SUCCESS on success, error code otherwise.
  144. * Inputs: sample_ecc_state_handle_t ecc_handle - Handle to ECC crypto system
  145. * sample_ec256_private_t *p_private_b - Pointer to the local private key - LITTLE ENDIAN
  146. * sample_ec256_public_t *p_public_ga - Pointer to the remote public key - LITTLE ENDIAN
  147. * Output: sample_ec256_dh_shared_t *p_shared_key - Pointer to the shared DH key - LITTLE ENDIAN
  148. x-coordinate of (privKeyB - pubKeyA) */
  149. SAMPLE_LIBCRYPTO_API sample_status_t sample_ecc256_compute_shared_dhkey(sample_ec256_private_t *p_private_b,
  150. sample_ec256_public_t *p_public_ga,
  151. sample_ec256_dh_shared_t *p_shared_key,
  152. sample_ecc_state_handle_t ecc_handle);
  153. /* Computes signature for data based on private key
  154. *
  155. * A message digest is a fixed size number derived from the original message with
  156. * an applied hash function over the binary code of the message. (SHA256 in this case)
  157. * The signer's private key and the message digest are used to create a signature.
  158. *
  159. * A digital signature over a message consists of a pair of large numbers, 256-bits each,
  160. * which the given function computes.
  161. *
  162. * The scheme used for computing a digital signature is of the ECDSA scheme,
  163. * an elliptic curve of the DSA scheme.
  164. *
  165. * The keys can be generated and set up by the function: sgx_ecc256_create_key_pair.
  166. *
  167. * The elliptic curve domain parameters must be created by function:
  168. * sample_ecc256_open_context
  169. *
  170. * Return: If context, private key, signature or data pointer is NULL,
  171. * SAMPLE_ERROR_INVALID_PARAMETER is returned.
  172. * If the signature creation process fails then SAMPLE_ERROR_UNEXPECTED is returned.
  173. *
  174. * Parameters:
  175. * Return: sample_status_t - SAMPLE_SUCCESS, success, error code otherwise.
  176. * Inputs: sample_ecc_state_handle_t ecc_handle - Handle to the ECC crypto system
  177. * sample_ec256_private_t *p_private - Pointer to the private key - LITTLE ENDIAN
  178. * uint8_t *p_data - Pointer to the data to be signed
  179. * uint32_t data_size - Size of the data to be signed
  180. * Output: ec256_signature_t *p_signature - Pointer to the signature - LITTLE ENDIAN */
  181. SAMPLE_LIBCRYPTO_API sample_status_t sample_ecdsa_sign(const uint8_t *p_data,
  182. uint32_t data_size,
  183. sample_ec256_private_t *p_private,
  184. sample_ec256_signature_t *p_signature,
  185. sample_ecc_state_handle_t ecc_handle);
  186. /* Allocates and initializes sha256 state
  187. * Parameters:
  188. * Return: sample_status_t - SAMPLE_SUCCESS on success, error code otherwise.
  189. * Output: sample_sha_state_handle_t sha_handle - Handle to the SHA256 state */
  190. SAMPLE_LIBCRYPTO_API sample_status_t sample_sha256_init(sample_sha_state_handle_t* p_sha_handle);
  191. /* Updates sha256 has calculation based on the input message
  192. * Parameters:
  193. * Return: sample_status_t - SAMPLE_SUCCESS or failure.
  194. * Input: sample_sha_state_handle_t sha_handle - Handle to the SHA256 state
  195. * uint8_t *p_src - Pointer to the input stream to be hashed
  196. * uint32_t src_len - Length of the input stream to be hashed */
  197. SAMPLE_LIBCRYPTO_API sample_status_t sample_sha256_update(const uint8_t *p_src, uint32_t src_len, sample_sha_state_handle_t sha_handle);
  198. /* Returns Hash calculation
  199. * Parameters:
  200. * Return: sample_status_t - SAMPLE_SUCCESS on success, error code otherwise.
  201. * Input: sample_sha_state_handle_t sha_handle - Handle to the SHA256 state
  202. * Output: sample_sha256_hash_t *p_hash - Resultant hash from operation */
  203. SAMPLE_LIBCRYPTO_API sample_status_t sample_sha256_get_hash(sample_sha_state_handle_t sha_handle, sample_sha256_hash_t *p_hash);
  204. /* Cleans up sha state
  205. * Parameters:
  206. * Return: sample_status_t - SAMPLE_SUCCESS on success, error code otherwise.
  207. * Input: sample_sha_state_handle_t sha_handle - Handle to the SHA256 state */
  208. SAMPLE_LIBCRYPTO_API sample_status_t sample_sha256_close(sample_sha_state_handle_t sha_handle);
  209. #endif