sgx_tseal.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259
  1. /*
  2. * Copyright (C) 2011-2017 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. #ifndef _SGX_TSEAL_H_
  32. #define _SGX_TSEAL_H_
  33. #include <stddef.h>
  34. #include <stdint.h>
  35. #include "sgx_key.h"
  36. #include "sgx_error.h"
  37. #include "sgx_defs.h"
  38. #include "sgx_attributes.h"
  39. #include "sgx_tcrypto.h"
  40. #define SGX_SEAL_TAG_SIZE SGX_AESGCM_MAC_SIZE
  41. #define SGX_SEAL_IV_SIZE 12
  42. typedef struct _aes_gcm_data_t
  43. {
  44. uint32_t payload_size; /* 0: Size of the payload which includes both the encrypted data and the optional additional MAC text */
  45. uint8_t reserved[12]; /* 4: Reserved bits */
  46. uint8_t payload_tag[SGX_SEAL_TAG_SIZE]; /* 16: AES-GMAC of the plain text, payload, and the sizes */
  47. uint8_t payload[]; /* 32: The payload data which includes the encrypted data followed by the optional additional MAC text */
  48. } sgx_aes_gcm_data_t;
  49. typedef struct _sealed_data_t
  50. {
  51. sgx_key_request_t key_request; /* 00: The key request used to obtain the sealing key */
  52. uint32_t plain_text_offset; /* 64: Offset within aes_data.playload to the start of the optional additional MAC text */
  53. uint8_t reserved[12]; /* 68: Reserved bits */
  54. sgx_aes_gcm_data_t aes_data; /* 80: Data structure holding the AES/GCM related data */
  55. } sgx_sealed_data_t;
  56. #ifdef __cplusplus
  57. extern "C" {
  58. #endif
  59. /* sgx_calc_sealed_data_size
  60. * Purpose: This function is used to determine how much memory to allocate for sgx_sealed_data_t structure.
  61. *
  62. * Paramters:
  63. * add_mac_txt_size - [IN] Length of the optional additional data stream in bytes
  64. * txt_encrypt_size - [IN] Length of the data stream to be encrypted in bytes
  65. *
  66. * Return Value:
  67. * uint32_t - The minimum number of bytes that need to be allocated for the sgx_sealed_data_t structure
  68. * If the function fails, the return value is UINT32_MAX
  69. */
  70. uint32_t sgx_calc_sealed_data_size(const uint32_t add_mac_txt_size, const uint32_t txt_encrypt_size);
  71. /* sgx_get_add_mac_txt_len
  72. * Purpose: This function is used to determine how much memory to allocate for the additional_MAC_text buffer
  73. *
  74. * Parameter:
  75. * p_sealed_data - [IN] Pointer to the sgx_sealed_data_t structure which was populated by the sgx_seal_data function
  76. *
  77. * Return Value:
  78. * uint32_t - The number of bytes in the optional additional MAC buffer
  79. * If the function fails, the return value is UINT32_MAX
  80. */
  81. uint32_t sgx_get_add_mac_txt_len(const sgx_sealed_data_t* p_sealed_data);
  82. /* sgx_get_encrypt_txt_len
  83. * Purpose: This function is used to determine how much memory to allocate for the decrypted data returned by the sgx_unseal_data function
  84. *
  85. * Parameter:
  86. * p_sealed_data - [IN] Pointer to the sgx_sealed_data_t structure which was populated by the sgx_seal_data function
  87. *
  88. * Return Value:
  89. * uint32_t - The number of bytes in the encrypted data buffer
  90. * If the function fails, the return value is UINT32_MAX
  91. */
  92. uint32_t sgx_get_encrypt_txt_len(const sgx_sealed_data_t* p_sealed_data);
  93. /* sgx_seal_data
  94. * Purpose: This algorithm is used to AES-GCM encrypt the input data. Specifically,
  95. * two input data sets can be provided, one is the text to encrypt (p_text2encrypt)
  96. * the second being optional additional text that should not be encrypted but will
  97. * be part of the GCM MAC calculation.
  98. * The sgx_sealed_data_t structure should be allocated prior to the API call and
  99. * should include buffer storage for the MAC text and encrypted text.
  100. * The sgx_sealed_data_t structure contains the data required to unseal the data on
  101. * the same system it was sealed.
  102. *
  103. * Parameters:
  104. * additional_MACtext_length - [IN] length of the plaintext data stream in bytes
  105. * The additional data is optional and thus the length
  106. * can be zero if no data is provided
  107. * p_additional_MACtext - [IN] pointer to the plaintext data stream to be GCM protected
  108. * The additional data is optional. You may pass a NULL pointer
  109. * but additional_MACtext_length must be zero in that case
  110. * text2encrypt_length - [IN] length of the data stream to encrypt in bytes
  111. * p_text2encrypt - [IN] pointer to data stream to encrypt
  112. * sealed_data_size - [IN] Size of the sealed data buffer passed in
  113. * p_sealed_data - [OUT] pointer to the sealed data structure containing protected data
  114. *
  115. * Return Value:
  116. * sgx_status_t - SGX Error code
  117. */
  118. sgx_status_t SGXAPI sgx_seal_data(const uint32_t additional_MACtext_length,
  119. const uint8_t *p_additional_MACtext,
  120. const uint32_t text2encrypt_length,
  121. const uint8_t *p_text2encrypt,
  122. const uint32_t sealed_data_size,
  123. sgx_sealed_data_t *p_sealed_data);
  124. /* sgx_seal_data_ex
  125. * Purpose: Expert version of sgx_seal_data which is used if the key_policy/attribute_mask/misc_mask
  126. * need to be modified from the default values.
  127. *
  128. * Parameters:
  129. * key_policy - [IN] Specifies the measurement to use in key derivation
  130. * attribute_mask - [IN] Identifies which platform/enclave attributes to use in key derivation
  131. * misc_mask - [IN] The mask for MISC_SELECT
  132. * additional_MACtext_length - [IN] length of the plaintext data stream in bytes
  133. * The additional data is optional and thus the length
  134. * can be zero if no data is provided
  135. * p_additional_MACtext - [IN] pointer to the plaintext data stream to be GCM protected
  136. * The additional data is optional. You may pass a NULL pointer
  137. * but additional_MACtext_length must be zero in that case
  138. * text2encrypt_length - [IN] length of the data stream to encrypt in bytes
  139. * p_text2encrypt - [IN] pointer to data stream to encrypt
  140. * sealed_data_size - [IN] Size of the sealed data buffer passed in
  141. * p_sealed_data - [OUT] pointer to the sealed data structure containing protected data
  142. *
  143. * Return Value:
  144. * sgx_status_t - SGX Error code
  145. */
  146. sgx_status_t SGXAPI sgx_seal_data_ex(const uint16_t key_policy,
  147. const sgx_attributes_t attribute_mask,
  148. const sgx_misc_select_t misc_mask,
  149. const uint32_t additional_MACtext_length,
  150. const uint8_t *p_additional_MACtext,
  151. const uint32_t text2encrypt_length,
  152. const uint8_t *p_text2encrypt,
  153. const uint32_t sealed_data_size,
  154. sgx_sealed_data_t *p_sealed_data);
  155. /* sgx_unseal_data
  156. * Purpose: Unseal the sealed data structure passed in and populate the MAC text and decrypted text
  157. * buffers with the appropriate data from the sealed data structure.
  158. *
  159. * Parameters:
  160. * p_sealed_data - [IN] pointer to the sealed data structure containing protected data
  161. * p_additional_MACtext - [OUT] pointer to the plaintext data stream which was GCM protected
  162. * The additiona data is optional. You may pass a NULL pointer but
  163. * p_additional_MACtext_length must be zero in that case
  164. * p_additional_MACtext_length - [IN/OUT] pointer to length of the plaintext data stream in bytes
  165. * If there is not additional data, this parameter should be zero.
  166. * p_decrypted_text - [OUT] pointer to decrypted data stream
  167. * p_decrypted_text_length - [IN/OUT] pointer to length of the decrypted data stream to encrypt in bytes
  168. *
  169. * Return Value:
  170. * sgx_status_t - SGX Error code
  171. */
  172. sgx_status_t SGXAPI sgx_unseal_data(const sgx_sealed_data_t *p_sealed_data,
  173. uint8_t *p_additional_MACtext,
  174. uint32_t *p_additional_MACtext_length,
  175. uint8_t *p_decrypted_text,
  176. uint32_t *p_decrypted_text_length);
  177. /* sgx_mac_aadata
  178. * Purpose: Use AES-GCM algorithm to generate a sealed data structure with integrity protection.
  179. * Specifically, the input data set is ONLY the plaintext data stream, or
  180. * additional authenticated data(AAD), no encrypt data.
  181. * The sgx_sealed_data_t structure should be allocated prior to the API call and
  182. * should include buffer storage for the plaintext data.
  183. * The sgx_sealed_data_t structure contains the data required to unseal the data on
  184. * the same system it was sealed.
  185. *
  186. * Parameters:
  187. * additional_MACtext_length - [IN] length of the plaintext data stream in bytes
  188. * p_additional_MACtext - [IN] pointer to the plaintext data stream to be GCM protected
  189. * sealed_data_size - [IN] Size of the sealed data buffer passed in
  190. * p_sealed_data - [OUT] pointer to the sealed data structure containing protected data
  191. *
  192. * Return Value:
  193. * sgx_status_t - SGX Error code
  194. */
  195. sgx_status_t sgx_mac_aadata(const uint32_t additional_MACtext_length,
  196. const uint8_t *p_additional_MACtext,
  197. const uint32_t sealed_data_size,
  198. sgx_sealed_data_t *p_sealed_data);
  199. /* sgx_mac_aadata_ex
  200. * Purpose: Expert version of sgx_mac_aadata which is used if the key_policy/attribute_mask/misc_mask
  201. * need to be modified from the default values.
  202. *
  203. * Parameters:
  204. * key_policy - [IN] Specifies the measurement to use in key derivation
  205. * attribute_mask - [IN] Identifies which platform/enclave attributes to use in key derivation
  206. * misc_mask - [IN] The mask for MISC_SELECT
  207. * additional_MACtext_length - [IN] length of the plaintext data stream in bytes
  208. * p_additional_MACtext - [IN] pointer to the plaintext data stream to be GCM protected
  209. * sealed_data_size - [IN] Size of the sealed data buffer passed in
  210. * p_sealed_data - [OUT] pointer to the sealed data structure containing protected data
  211. *
  212. * Return Value:
  213. * sgx_status_t - SGX Error code
  214. */
  215. sgx_status_t sgx_mac_aadata_ex(const uint16_t key_policy,
  216. const sgx_attributes_t attribute_mask,
  217. const sgx_misc_select_t misc_mask,
  218. const uint32_t additional_MACtext_length,
  219. const uint8_t *p_additional_MACtext,
  220. const uint32_t sealed_data_size,
  221. sgx_sealed_data_t *p_sealed_data);
  222. /* sgx_unmac_aadata
  223. * Purpose: Unseal the sealed data structure passed in and populate the plaintext data stream
  224. * with the appropriate data from the sealed data structure.
  225. *
  226. * Parameters:
  227. * p_sealed_data - [IN] pointer to the sealed data structure containing protected data
  228. * p_additional_MACtext - [OUT] pointer to the plaintext data stream which was GCM protected
  229. * p_additional_MACtext_length - [IN/OUT] pointer to length of the plaintext data stream in bytes
  230. *
  231. * Return Value:
  232. * sgx_status_t - SGX Error code
  233. */
  234. sgx_status_t sgx_unmac_aadata(const sgx_sealed_data_t *p_sealed_data,
  235. uint8_t *p_additional_MACtext,
  236. uint32_t *p_additional_MACtext_length);
  237. #ifdef __cplusplus
  238. }
  239. #endif
  240. #endif