kmac_prov.c 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543
  1. /*
  2. * Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
  3. *
  4. * Licensed under the Apache License 2.0 (the "License"). You may not use
  5. * this file except in compliance with the License. You can obtain a copy
  6. * in the file LICENSE in the source distribution or at
  7. * https://www.openssl.org/source/license.html
  8. */
  9. /*
  10. * See SP800-185 "Appendix A - KMAC, .... in Terms of Keccak[c]"
  11. *
  12. * Inputs are:
  13. * K = Key (len(K) < 2^2040 bits)
  14. * X = Input
  15. * L = Output length (0 <= L < 2^2040 bits)
  16. * S = Customization String Default="" (len(S) < 2^2040 bits)
  17. *
  18. * KMAC128(K, X, L, S)
  19. * {
  20. * newX = bytepad(encode_string(K), 168) || X || right_encode(L).
  21. * T = bytepad(encode_string("KMAC") || encode_string(S), 168).
  22. * return KECCAK[256](T || newX || 00, L).
  23. * }
  24. *
  25. * KMAC256(K, X, L, S)
  26. * {
  27. * newX = bytepad(encode_string(K), 136) || X || right_encode(L).
  28. * T = bytepad(encode_string("KMAC") || encode_string(S), 136).
  29. * return KECCAK[512](T || newX || 00, L).
  30. * }
  31. *
  32. * KMAC128XOF(K, X, L, S)
  33. * {
  34. * newX = bytepad(encode_string(K), 168) || X || right_encode(0).
  35. * T = bytepad(encode_string("KMAC") || encode_string(S), 168).
  36. * return KECCAK[256](T || newX || 00, L).
  37. * }
  38. *
  39. * KMAC256XOF(K, X, L, S)
  40. * {
  41. * newX = bytepad(encode_string(K), 136) || X || right_encode(0).
  42. * T = bytepad(encode_string("KMAC") || encode_string(S), 136).
  43. * return KECCAK[512](T || newX || 00, L).
  44. * }
  45. *
  46. */
  47. #include <stdlib.h>
  48. #include <string.h>
  49. #include <openssl/core_numbers.h>
  50. #include <openssl/core_names.h>
  51. #include <openssl/params.h>
  52. #include <openssl/evp.h>
  53. #include <openssl/err.h>
  54. #include "internal/providercommonerr.h"
  55. #include "internal/provider_algs.h"
  56. #include "internal/provider_ctx.h"
  57. #include "internal/provider_util.h"
  58. /*
  59. * Forward declaration of everything implemented here. This is not strictly
  60. * necessary for the compiler, but provides an assurance that the signatures
  61. * of the functions in the dispatch table are correct.
  62. */
  63. static OSSL_OP_mac_newctx_fn kmac128_new;
  64. static OSSL_OP_mac_newctx_fn kmac256_new;
  65. static OSSL_OP_mac_dupctx_fn kmac_dup;
  66. static OSSL_OP_mac_freectx_fn kmac_free;
  67. static OSSL_OP_mac_gettable_ctx_params_fn kmac_gettable_ctx_params;
  68. static OSSL_OP_mac_get_ctx_params_fn kmac_get_ctx_params;
  69. static OSSL_OP_mac_settable_ctx_params_fn kmac_settable_ctx_params;
  70. static OSSL_OP_mac_set_ctx_params_fn kmac_set_ctx_params;
  71. static OSSL_OP_mac_size_fn kmac_size;
  72. static OSSL_OP_mac_init_fn kmac_init;
  73. static OSSL_OP_mac_update_fn kmac_update;
  74. static OSSL_OP_mac_final_fn kmac_final;
  75. #define KMAC_MAX_BLOCKSIZE ((1600 - 128*2) / 8) /* 168 */
  76. #define KMAC_MIN_BLOCKSIZE ((1600 - 256*2) / 8) /* 136 */
  77. /* Length encoding will be a 1 byte size + length in bits (2 bytes max) */
  78. #define KMAC_MAX_ENCODED_HEADER_LEN 3
  79. /*
  80. * Custom string max size is chosen such that:
  81. * len(encoded_string(custom) + len(kmac_encoded_string) <= KMAC_MIN_BLOCKSIZE
  82. * i.e: (KMAC_MAX_CUSTOM + KMAC_MAX_ENCODED_LEN) + 6 <= 136
  83. */
  84. #define KMAC_MAX_CUSTOM 127
  85. /* Maximum size of encoded custom string */
  86. #define KMAC_MAX_CUSTOM_ENCODED (KMAC_MAX_CUSTOM + KMAC_MAX_ENCODED_HEADER_LEN)
  87. /* Maximum key size in bytes = 2040 / 8 */
  88. #define KMAC_MAX_KEY 255
  89. /*
  90. * Maximum Encoded Key size will be padded to a multiple of the blocksize
  91. * i.e KMAC_MAX_KEY + KMAC_MAX_ENCODED_LEN = 258
  92. * Padded to a multiple of KMAC_MAX_BLOCKSIZE
  93. */
  94. #define KMAC_MAX_KEY_ENCODED (KMAC_MAX_BLOCKSIZE * 2)
  95. /* Fixed value of encode_string("KMAC") */
  96. static const unsigned char kmac_string[] = {
  97. 0x01, 0x20, 0x4B, 0x4D, 0x41, 0x43
  98. };
  99. #define KMAC_FLAG_XOF_MODE 1
  100. struct kmac_data_st {
  101. void *provctx;
  102. EVP_MD_CTX *ctx;
  103. PROV_DIGEST digest;
  104. size_t out_len;
  105. int key_len;
  106. int custom_len;
  107. /* If xof_mode = 1 then we use right_encode(0) */
  108. int xof_mode;
  109. /* key and custom are stored in encoded form */
  110. unsigned char key[KMAC_MAX_KEY_ENCODED];
  111. unsigned char custom[KMAC_MAX_CUSTOM_ENCODED];
  112. };
  113. static int encode_string(unsigned char *out, int *out_len,
  114. const unsigned char *in, int in_len);
  115. static int right_encode(unsigned char *out, int *out_len, size_t bits);
  116. static int bytepad(unsigned char *out, int *out_len,
  117. const unsigned char *in1, int in1_len,
  118. const unsigned char *in2, int in2_len,
  119. int w);
  120. static int kmac_bytepad_encode_key(unsigned char *out, int *out_len,
  121. const unsigned char *in, int in_len,
  122. int w);
  123. static void kmac_free(void *vmacctx)
  124. {
  125. struct kmac_data_st *kctx = vmacctx;
  126. if (kctx != NULL) {
  127. EVP_MD_CTX_free(kctx->ctx);
  128. ossl_prov_digest_reset(&kctx->digest);
  129. OPENSSL_cleanse(kctx->key, kctx->key_len);
  130. OPENSSL_cleanse(kctx->custom, kctx->custom_len);
  131. OPENSSL_free(kctx);
  132. }
  133. }
  134. /*
  135. * We have KMAC implemented as a hash, which we can use instead of
  136. * reimplementing the EVP functionality with direct use of
  137. * keccak_mac_init() and friends.
  138. */
  139. static struct kmac_data_st *kmac_new(void *provctx)
  140. {
  141. struct kmac_data_st *kctx;
  142. if ((kctx = OPENSSL_zalloc(sizeof(*kctx))) == NULL
  143. || (kctx->ctx = EVP_MD_CTX_new()) == NULL) {
  144. kmac_free(kctx);
  145. return NULL;
  146. }
  147. kctx->provctx = provctx;
  148. return kctx;
  149. }
  150. static void *kmac_fetch_new(void *provctx, const OSSL_PARAM *params)
  151. {
  152. struct kmac_data_st *kctx = kmac_new(provctx);
  153. if (kctx == NULL)
  154. return 0;
  155. if (!ossl_prov_digest_load_from_params(&kctx->digest, params,
  156. PROV_LIBRARY_CONTEXT_OF(provctx))) {
  157. kmac_free(kctx);
  158. return 0;
  159. }
  160. kctx->out_len = EVP_MD_size(ossl_prov_digest_md(&kctx->digest));
  161. return kctx;
  162. }
  163. static void *kmac128_new(void *provctx)
  164. {
  165. static const OSSL_PARAM kmac128_params[] = {
  166. OSSL_PARAM_utf8_string("digest", OSSL_DIGEST_NAME_KECCAK_KMAC128,
  167. sizeof(OSSL_DIGEST_NAME_KECCAK_KMAC128)),
  168. OSSL_PARAM_END
  169. };
  170. return kmac_fetch_new(provctx, kmac128_params);
  171. }
  172. static void *kmac256_new(void *provctx)
  173. {
  174. static const OSSL_PARAM kmac256_params[] = {
  175. OSSL_PARAM_utf8_string("digest", OSSL_DIGEST_NAME_KECCAK_KMAC256,
  176. sizeof(OSSL_DIGEST_NAME_KECCAK_KMAC256)),
  177. OSSL_PARAM_END
  178. };
  179. return kmac_fetch_new(provctx, kmac256_params);
  180. }
  181. static void *kmac_dup(void *vsrc)
  182. {
  183. struct kmac_data_st *src = vsrc;
  184. struct kmac_data_st *dst = kmac_new(src->provctx);
  185. if (dst == NULL)
  186. return NULL;
  187. if (!EVP_MD_CTX_copy(dst->ctx, src->ctx)
  188. || !ossl_prov_digest_copy(&dst->digest, &src->digest)) {
  189. kmac_free(dst);
  190. return NULL;
  191. }
  192. dst->out_len = src->out_len;
  193. dst->key_len = src->key_len;
  194. dst->custom_len = src->custom_len;
  195. dst->xof_mode = src->xof_mode;
  196. memcpy(dst->key, src->key, src->key_len);
  197. memcpy(dst->custom, src->custom, dst->custom_len);
  198. return dst;
  199. }
  200. /*
  201. * The init() assumes that any ctrl methods are set beforehand for
  202. * md, key and custom. Setting the fields afterwards will have no
  203. * effect on the output mac.
  204. */
  205. static int kmac_init(void *vmacctx)
  206. {
  207. struct kmac_data_st *kctx = vmacctx;
  208. EVP_MD_CTX *ctx = kctx->ctx;
  209. unsigned char out[KMAC_MAX_BLOCKSIZE];
  210. int out_len, block_len;
  211. /* Check key has been set */
  212. if (kctx->key_len == 0) {
  213. EVPerr(EVP_F_KMAC_INIT, EVP_R_NO_KEY_SET);
  214. return 0;
  215. }
  216. if (!EVP_DigestInit_ex(kctx->ctx, ossl_prov_digest_md(&kctx->digest),
  217. NULL))
  218. return 0;
  219. block_len = EVP_MD_block_size(ossl_prov_digest_md(&kctx->digest));
  220. /* Set default custom string if it is not already set */
  221. if (kctx->custom_len == 0) {
  222. const OSSL_PARAM params[] = {
  223. OSSL_PARAM_octet_string(OSSL_MAC_PARAM_CUSTOM, "", 0),
  224. OSSL_PARAM_END
  225. };
  226. (void)kmac_set_ctx_params(kctx, params);
  227. }
  228. return bytepad(out, &out_len, kmac_string, sizeof(kmac_string),
  229. kctx->custom, kctx->custom_len, block_len)
  230. && EVP_DigestUpdate(ctx, out, out_len)
  231. && EVP_DigestUpdate(ctx, kctx->key, kctx->key_len);
  232. }
  233. static size_t kmac_size(void *vmacctx)
  234. {
  235. struct kmac_data_st *kctx = vmacctx;
  236. return kctx->out_len;
  237. }
  238. static int kmac_update(void *vmacctx, const unsigned char *data,
  239. size_t datalen)
  240. {
  241. struct kmac_data_st *kctx = vmacctx;
  242. return EVP_DigestUpdate(kctx->ctx, data, datalen);
  243. }
  244. static int kmac_final(void *vmacctx, unsigned char *out, size_t *outl,
  245. size_t outsize)
  246. {
  247. struct kmac_data_st *kctx = vmacctx;
  248. EVP_MD_CTX *ctx = kctx->ctx;
  249. int lbits, len;
  250. unsigned char encoded_outlen[KMAC_MAX_ENCODED_HEADER_LEN];
  251. int ok;
  252. /* KMAC XOF mode sets the encoded length to 0 */
  253. lbits = (kctx->xof_mode ? 0 : (kctx->out_len * 8));
  254. ok = right_encode(encoded_outlen, &len, lbits)
  255. && EVP_DigestUpdate(ctx, encoded_outlen, len)
  256. && EVP_DigestFinalXOF(ctx, out, kctx->out_len);
  257. if (ok && outl != NULL)
  258. *outl = kctx->out_len;
  259. return ok;
  260. }
  261. static const OSSL_PARAM known_gettable_ctx_params[] = {
  262. OSSL_PARAM_size_t(OSSL_MAC_PARAM_SIZE, NULL),
  263. OSSL_PARAM_END
  264. };
  265. static const OSSL_PARAM *kmac_gettable_ctx_params(void)
  266. {
  267. return known_gettable_ctx_params;
  268. }
  269. static int kmac_get_ctx_params(void *vmacctx, OSSL_PARAM params[])
  270. {
  271. OSSL_PARAM *p;
  272. if ((p = OSSL_PARAM_locate(params, OSSL_MAC_PARAM_SIZE)) != NULL)
  273. return OSSL_PARAM_set_size_t(p, kmac_size(vmacctx));
  274. return 1;
  275. }
  276. static const OSSL_PARAM known_settable_ctx_params[] = {
  277. OSSL_PARAM_int(OSSL_MAC_PARAM_XOF, NULL),
  278. OSSL_PARAM_size_t(OSSL_MAC_PARAM_SIZE, NULL),
  279. OSSL_PARAM_octet_string(OSSL_MAC_PARAM_KEY, NULL, 0),
  280. OSSL_PARAM_octet_string(OSSL_MAC_PARAM_CUSTOM, NULL, 0),
  281. OSSL_PARAM_END
  282. };
  283. static const OSSL_PARAM *kmac_settable_ctx_params(void)
  284. {
  285. return known_settable_ctx_params;
  286. }
  287. /*
  288. * The following params can be set any time before final():
  289. * - "outlen" or "size": The requested output length.
  290. * - "xof": If set, this indicates that right_encoded(0)
  291. * is part of the digested data, otherwise it
  292. * uses right_encoded(requested output length).
  293. *
  294. * All other params should be set before init().
  295. */
  296. static int kmac_set_ctx_params(void *vmacctx, const OSSL_PARAM *params)
  297. {
  298. struct kmac_data_st *kctx = vmacctx;
  299. const OSSL_PARAM *p;
  300. const EVP_MD *digest = ossl_prov_digest_md(&kctx->digest);
  301. if ((p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_XOF)) != NULL
  302. && !OSSL_PARAM_get_int(p, &kctx->xof_mode))
  303. return 0;
  304. if (((p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_SIZE)) != NULL)
  305. && !OSSL_PARAM_get_size_t(p, &kctx->out_len))
  306. return 0;
  307. if ((p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_KEY)) != NULL) {
  308. if (p->data_size < 4 || p->data_size > KMAC_MAX_KEY) {
  309. ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_KEY_LENGTH);
  310. return 0;
  311. }
  312. if (!kmac_bytepad_encode_key(kctx->key, &kctx->key_len,
  313. p->data, p->data_size,
  314. EVP_MD_block_size(digest)))
  315. return 0;
  316. }
  317. if ((p = OSSL_PARAM_locate_const(params, OSSL_MAC_PARAM_CUSTOM))
  318. != NULL) {
  319. if (p->data_size > KMAC_MAX_CUSTOM) {
  320. ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_CUSTOM_LENGTH);
  321. return 0;
  322. }
  323. if (!encode_string(kctx->custom, &kctx->custom_len,
  324. p->data, p->data_size))
  325. return 0;
  326. }
  327. return 1;
  328. }
  329. /*
  330. * Encoding/Padding Methods.
  331. */
  332. /* Returns the number of bytes required to store 'bits' into a byte array */
  333. static unsigned int get_encode_size(size_t bits)
  334. {
  335. unsigned int cnt = 0, sz = sizeof(size_t);
  336. while (bits && (cnt < sz)) {
  337. ++cnt;
  338. bits >>= 8;
  339. }
  340. /* If bits is zero 1 byte is required */
  341. if (cnt == 0)
  342. cnt = 1;
  343. return cnt;
  344. }
  345. /*
  346. * Convert an integer into bytes . The number of bytes is appended
  347. * to the end of the buffer. Returns an array of bytes 'out' of size
  348. * *out_len.
  349. *
  350. * e.g if bits = 32, out[2] = { 0x20, 0x01 }
  351. *
  352. */
  353. static int right_encode(unsigned char *out, int *out_len, size_t bits)
  354. {
  355. unsigned int len = get_encode_size(bits);
  356. int i;
  357. /* The length is constrained to a single byte: 2040/8 = 255 */
  358. if (len > 0xFF)
  359. return 0;
  360. /* MSB's are at the start of the bytes array */
  361. for (i = len - 1; i >= 0; --i) {
  362. out[i] = (unsigned char)(bits & 0xFF);
  363. bits >>= 8;
  364. }
  365. /* Tack the length onto the end */
  366. out[len] = (unsigned char)len;
  367. /* The Returned length includes the tacked on byte */
  368. *out_len = len + 1;
  369. return 1;
  370. }
  371. /*
  372. * Encodes a string with a left encoded length added. Note that the
  373. * in_len is converted to bits (*8).
  374. *
  375. * e.g- in="KMAC" gives out[6] = { 0x01, 0x20, 0x4B, 0x4D, 0x41, 0x43 }
  376. * len bits K M A C
  377. */
  378. static int encode_string(unsigned char *out, int *out_len,
  379. const unsigned char *in, int in_len)
  380. {
  381. if (in == NULL) {
  382. *out_len = 0;
  383. } else {
  384. int i, bits, len;
  385. bits = 8 * in_len;
  386. len = get_encode_size(bits);
  387. if (len > 0xFF)
  388. return 0;
  389. out[0] = len;
  390. for (i = len; i > 0; --i) {
  391. out[i] = (bits & 0xFF);
  392. bits >>= 8;
  393. }
  394. memcpy(out + len + 1, in, in_len);
  395. *out_len = (1 + len + in_len);
  396. }
  397. return 1;
  398. }
  399. /*
  400. * Returns a zero padded encoding of the inputs in1 and an optional
  401. * in2 (can be NULL). The padded output must be a multiple of the blocksize 'w'.
  402. * The value of w is in bytes (< 256).
  403. *
  404. * The returned output is:
  405. * zero_padded(multiple of w, (left_encode(w) || in1 [|| in2])
  406. */
  407. static int bytepad(unsigned char *out, int *out_len,
  408. const unsigned char *in1, int in1_len,
  409. const unsigned char *in2, int in2_len, int w)
  410. {
  411. int len;
  412. unsigned char *p = out;
  413. int sz = w;
  414. /* Left encoded w */
  415. *p++ = 1;
  416. *p++ = w;
  417. /* || in1 */
  418. memcpy(p, in1, in1_len);
  419. p += in1_len;
  420. /* [ || in2 ] */
  421. if (in2 != NULL && in2_len > 0) {
  422. memcpy(p, in2, in2_len);
  423. p += in2_len;
  424. }
  425. /* Figure out the pad size (divisible by w) */
  426. len = p - out;
  427. while (len > sz) {
  428. sz += w;
  429. }
  430. /* zero pad the end of the buffer */
  431. memset(p, 0, sz - len);
  432. *out_len = sz;
  433. return 1;
  434. }
  435. /*
  436. * Returns out = bytepad(encode_string(in), w)
  437. */
  438. static int kmac_bytepad_encode_key(unsigned char *out, int *out_len,
  439. const unsigned char *in, int in_len,
  440. int w)
  441. {
  442. unsigned char tmp[KMAC_MAX_KEY + KMAC_MAX_ENCODED_HEADER_LEN];
  443. int tmp_len;
  444. if (!encode_string(tmp, &tmp_len, in, in_len))
  445. return 0;
  446. return bytepad(out, out_len, tmp, tmp_len, NULL, 0, w);
  447. }
  448. const OSSL_DISPATCH kmac128_functions[] = {
  449. { OSSL_FUNC_MAC_NEWCTX, (void (*)(void))kmac128_new },
  450. { OSSL_FUNC_MAC_DUPCTX, (void (*)(void))kmac_dup },
  451. { OSSL_FUNC_MAC_FREECTX, (void (*)(void))kmac_free },
  452. { OSSL_FUNC_MAC_INIT, (void (*)(void))kmac_init },
  453. { OSSL_FUNC_MAC_UPDATE, (void (*)(void))kmac_update },
  454. { OSSL_FUNC_MAC_FINAL, (void (*)(void))kmac_final },
  455. { OSSL_FUNC_MAC_GETTABLE_CTX_PARAMS,
  456. (void (*)(void))kmac_gettable_ctx_params },
  457. { OSSL_FUNC_MAC_GET_CTX_PARAMS, (void (*)(void))kmac_get_ctx_params },
  458. { OSSL_FUNC_MAC_SETTABLE_CTX_PARAMS,
  459. (void (*)(void))kmac_settable_ctx_params },
  460. { OSSL_FUNC_MAC_SET_CTX_PARAMS, (void (*)(void))kmac_set_ctx_params },
  461. { 0, NULL }
  462. };
  463. const OSSL_DISPATCH kmac256_functions[] = {
  464. { OSSL_FUNC_MAC_NEWCTX, (void (*)(void))kmac256_new },
  465. { OSSL_FUNC_MAC_DUPCTX, (void (*)(void))kmac_dup },
  466. { OSSL_FUNC_MAC_FREECTX, (void (*)(void))kmac_free },
  467. { OSSL_FUNC_MAC_INIT, (void (*)(void))kmac_init },
  468. { OSSL_FUNC_MAC_UPDATE, (void (*)(void))kmac_update },
  469. { OSSL_FUNC_MAC_FINAL, (void (*)(void))kmac_final },
  470. { OSSL_FUNC_MAC_GETTABLE_CTX_PARAMS,
  471. (void (*)(void))kmac_gettable_ctx_params },
  472. { OSSL_FUNC_MAC_GET_CTX_PARAMS, (void (*)(void))kmac_get_ctx_params },
  473. { OSSL_FUNC_MAC_SETTABLE_CTX_PARAMS,
  474. (void (*)(void))kmac_settable_ctx_params },
  475. { OSSL_FUNC_MAC_SET_CTX_PARAMS, (void (*)(void))kmac_set_ctx_params },
  476. { 0, NULL }
  477. };