ed448.h 31 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968
  1. /*!
  2. \ingroup ED448
  3. \brief This function generates the Ed448 public key from the private key.
  4. It stores the public key in the buffer pubKey, and sets the bytes
  5. written to this buffer in pubKeySz.
  6. \return 0 Returned upon successfully making the public key.
  7. \return BAD_FUNC_ARG Returned ifi key or pubKey evaluate to NULL, or if the
  8. specified key size is not 57 bytes (Ed448 has 57 byte keys).
  9. \return MEMORY_E Returned if there is an error allocating memory
  10. during function execution.
  11. \param [in] key Pointer to the ed448_key for which to generate a key.
  12. \param [out] out Pointer to the buffer in which to store the public key.
  13. \param [in,out] outLen Pointer to a word32 object with the size available
  14. in out. Set with the number of bytes written to out after successfully
  15. exporting the public key.
  16. _Example_
  17. \code
  18. int ret;
  19. ed448_key key;
  20. byte priv[] = { initialize with 57 byte private key };
  21. byte pub[57];
  22. word32 pubSz = sizeof(pub);
  23. wc_ed448_init(&key);
  24. wc_ed448_import_private_only(priv, sizeof(priv), &key);
  25. ret = wc_ed448_make_public(&key, pub, &pubSz);
  26. if (ret != 0) {
  27. // error making public key
  28. }
  29. \endcode
  30. \sa wc_ed448_init
  31. \sa wc_ed448_import_private_only
  32. \sa wc_ed448_make_key
  33. */
  34. int wc_ed448_make_public(ed448_key* key, unsigned char* pubKey,
  35. word32 pubKeySz);
  36. /*!
  37. \ingroup ED448
  38. \brief This function generates a new Ed448 key and stores it in key.
  39. \return 0 Returned upon successfully making an ed448_key.
  40. \return BAD_FUNC_ARG Returned if rng or key evaluate to NULL, or if the
  41. specified key size is not 57 bytes (Ed448 has 57 byte keys).
  42. \return MEMORY_E Returned if there is an error allocating memory
  43. during function execution.
  44. \param [in] rng Pointer to an initialized RNG object with which to
  45. generate the key.
  46. \param [in] keysize Length of key to generate. Should always be 57 for
  47. Ed448.
  48. \param [in,out] key Pointer to the ed448_key for which to generate a key.
  49. _Example_
  50. \code
  51. int ret;
  52. WC_RNG rng;
  53. ed448_key key;
  54. wc_InitRng(&rng);
  55. wc_ed448_init(&key);
  56. ret = wc_ed448_make_key(&rng, 57, &key);
  57. if (ret != 0) {
  58. // error making key
  59. }
  60. \endcode
  61. \sa wc_ed448_init
  62. */
  63. int wc_ed448_make_key(WC_RNG* rng, int keysize, ed448_key* key);
  64. /*!
  65. \ingroup ED448
  66. \brief This function signs a message using an ed448_key object
  67. to guarantee authenticity.
  68. \return 0 Returned upon successfully generating a signature for the
  69. message.
  70. \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
  71. NULL, or if the output buffer is too small to store the generated signature.
  72. \return MEMORY_E Returned if there is an error allocating memory during
  73. function execution.
  74. \param [in] in Pointer to the buffer containing the message to sign.
  75. \param [in] inlen Length of the message to sign.
  76. \param [out] out Buffer in which to store the generated signature.
  77. \param [in,out] outlen Maximum length of the output buffer. Will store the
  78. bytes written to out upon successfully generating a message signature.
  79. \param [in] key Pointer to a private ed448_key with which to generate the
  80. signature.
  81. _Example_
  82. \code
  83. ed448_key key;
  84. WC_RNG rng;
  85. int ret, sigSz;
  86. byte sig[114]; // will hold generated signature
  87. sigSz = sizeof(sig);
  88. byte message[] = { initialize with message };
  89. wc_InitRng(&rng); // initialize rng
  90. wc_ed448_init(&key); // initialize key
  91. wc_ed448_make_key(&rng, 57, &key); // make public/private key pair
  92. ret = wc_ed448_sign_msg(message, sizeof(message), sig, &sigSz, &key);
  93. if (ret != 0 ) {
  94. // error generating message signature
  95. }
  96. \endcode
  97. \sa wc_ed448ph_sign_hash
  98. \sa wc_ed448ph_sign_msg
  99. \sa wc_ed448_verify_msg
  100. */
  101. int wc_ed448_sign_msg(const byte* in, word32 inlen, byte* out,
  102. word32 *outlen, ed448_key* key);
  103. /*!
  104. \ingroup ED448
  105. \brief This function signs a message digest using an ed448_key object
  106. to guarantee authenticity. The context is included as part of the data
  107. signed. The hash is the pre-hashed message before signature calculation.
  108. The hash algorithm used to create message digest must be SHAKE-256.
  109. \return 0 Returned upon successfully generating a signature for the
  110. message digest.
  111. \return BAD_FUNC_ARG Returned any of the input parameters evaluate to
  112. NULL, or if the output buffer is too small to store the generated signature.
  113. \return MEMORY_E Returned if there is an error allocating memory during
  114. function execution.
  115. \param [in] hash Pointer to the buffer containing the hash of the message
  116. to sign.
  117. \param [in] hashLen Length of the hash of the message to sign.
  118. \param [out] out Buffer in which to store the generated signature.
  119. \param [in,out] outlen Maximum length of the output buffer. Will store the
  120. bytes written to out upon successfully generating a message signature.
  121. \param [in] key Pointer to a private ed448_key with which to generate the
  122. signature.
  123. \param [in] context Pointer to the buffer containing the context for which
  124. message is being signed.
  125. \param [in] contextLen Length of the context buffer.
  126. _Example_
  127. \code
  128. ed448_key key;
  129. WC_RNG rng;
  130. int ret, sigSz;
  131. byte sig[114]; // will hold generated signature
  132. sigSz = sizeof(sig);
  133. byte hash[] = { initialize with SHAKE-256 hash of message };
  134. byte context[] = { initialize with context of signing };
  135. wc_InitRng(&rng); // initialize rng
  136. wc_ed448_init(&key); // initialize key
  137. wc_ed448_make_key(&rng, 57, &key); // make public/private key pair
  138. ret = wc_ed448ph_sign_hash(hash, sizeof(hash), sig, &sigSz, &key,
  139. context, sizeof(context));
  140. if (ret != 0) {
  141. // error generating message signature
  142. }
  143. \endcode
  144. \sa wc_ed448_sign_msg
  145. \sa wc_ed448ph_sign_msg
  146. \sa wc_ed448ph_verify_hash
  147. */
  148. int wc_ed448ph_sign_hash(const byte* hash, word32 hashLen, byte* out,
  149. word32 *outLen, ed448_key* key,
  150. const byte* context, byte contextLen);
  151. /*!
  152. \ingroup ED448
  153. \brief This function signs a message using an ed448_key object
  154. to guarantee authenticity. The context is included as part of the data
  155. signed. The message is pre-hashed before signature calculation.
  156. \return 0 Returned upon successfully generating a signature for the
  157. message.
  158. \return BAD_FUNC_ARG Returned any of the input parameters evaluate to
  159. NULL, or if the output buffer is too small to store the generated signature.
  160. \return MEMORY_E Returned if there is an error allocating memory during
  161. function execution.
  162. \param [in] in Pointer to the buffer containing the message to sign.
  163. \param [in] inlen Length of the message to sign.
  164. \param [out] out Buffer in which to store the generated signature.
  165. \param [in,out] outlen Maximum length of the output buffer. Will store the
  166. bytes written to out upon successfully generating a message signature.
  167. \param [in] key Pointer to a private ed448_key with which to generate the
  168. signature.
  169. \param [in] context Pointer to the buffer containing the context for which
  170. message is being signed.
  171. \param [in] contextLen Length of the context buffer.
  172. _Example_
  173. \code
  174. ed448_key key;
  175. WC_RNG rng;
  176. int ret, sigSz;
  177. byte sig[114]; // will hold generated signature
  178. sigSz = sizeof(sig);
  179. byte message[] = { initialize with message };
  180. byte context[] = { initialize with context of signing };
  181. wc_InitRng(&rng); // initialize rng
  182. wc_ed448_init(&key); // initialize key
  183. wc_ed448_make_key(&rng, 57, &key); // make public/private key pair
  184. ret = wc_ed448ph_sign_msg(message, sizeof(message), sig, &sigSz, &key,
  185. context, sizeof(context));
  186. if (ret != 0) {
  187. // error generating message signature
  188. }
  189. \endcode
  190. \sa wc_ed448_sign_msg
  191. \sa wc_ed448ph_sign_hash
  192. \sa wc_ed448ph_verify_msg
  193. */
  194. int wc_ed448ph_sign_msg(const byte* in, word32 inLen, byte* out,
  195. word32 *outLen, ed448_key* key, const byte* context,
  196. byte contextLen);
  197. /*!
  198. \ingroup ED448
  199. \brief This function verifies the Ed448 signature of a message to ensure
  200. authenticity. The context is included as part of the data
  201. verified. The answer is returned through res, with 1 corresponding to
  202. a valid signature, and 0 corresponding to an invalid signature.
  203. \return 0 Returned upon successfully performing the signature
  204. verification and authentication.
  205. \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
  206. NULL, or if the siglen does not match the actual length of a signature.
  207. \return SIG_VERIFY_E Returned if verification completes, but the signature
  208. generated does not match the signature provided.
  209. \param [in] sig Pointer to the buffer containing the signature to verify.
  210. \param [in] siglen Length of the signature to verify.
  211. \param [in] msg Pointer to the buffer containing the message to verify.
  212. \param [in] msgLen Length of the message to verify.
  213. \param [in] key Pointer to a public Ed448 key with which to verify the
  214. signature.
  215. \param [in] context Pointer to the buffer containing the context for which
  216. the message was signed.
  217. \param [in] contextLen Length of the context buffer.
  218. _Example_
  219. \code
  220. ed448_key key;
  221. int ret, verified = 0;
  222. byte sig[] { initialize with received signature };
  223. byte msg[] = { initialize with message };
  224. byte context[] = { initialize with context of signature };
  225. // initialize key with received public key
  226. ret = wc_ed448_verify_msg(sig, sizeof(sig), msg, sizeof(msg), &verified,
  227. &key, context, sizeof(context));
  228. if (ret < 0) {
  229. // error performing verification
  230. } else if (verified == 0)
  231. // the signature is invalid
  232. }
  233. \endcode
  234. \sa wc_ed448ph_verify_hash
  235. \sa wc_ed448ph_verify_msg
  236. \sa wc_ed448_sign_msg
  237. */
  238. int wc_ed448_verify_msg(const byte* sig, word32 siglen, const byte* msg,
  239. word32 msgLen, int* res, ed448_key* key,
  240. const byte* context, byte contextLen);
  241. /*!
  242. \ingroup ED448
  243. \brief This function verifies the Ed448 signature of the digest of a message
  244. to ensure authenticity. The context is included as part of the data
  245. verified. The hash is the pre-hashed message before signature calculation.
  246. The hash algorithm used to create message digest must be SHAKE-256.
  247. The answer is returned through res, with 1 corresponding to a valid
  248. signature, and 0 corresponding to an invalid signature.
  249. \return 0 Returned upon successfully performing the signature
  250. verification and authentication.
  251. \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
  252. NULL, or if the siglen does not match the actual length of a signature.
  253. \return SIG_VERIFY_E Returned if verification completes, but the signature
  254. generated does not match the signature provided.
  255. \param [in] sig Pointer to the buffer containing the signature to verify.
  256. \param [in] siglen Length of the signature to verify.
  257. \param [in] hash Pointer to the buffer containing the hash of the message
  258. to verify.
  259. \param [in] hashLen Length of the hash to verify.
  260. \param [in] key Pointer to a public Ed448 key with which to verify the
  261. signature.
  262. \param [in] context Pointer to the buffer containing the context for which
  263. the message was signed.
  264. \param [in] contextLen Length of the context buffer.
  265. _Example_
  266. \code
  267. ed448_key key;
  268. int ret, verified = 0;
  269. byte sig[] { initialize with received signature };
  270. byte hash[] = { initialize with SHAKE-256 hash of message };
  271. byte context[] = { initialize with context of signature };
  272. // initialize key with received public key
  273. ret = wc_ed448ph_verify_hash(sig, sizeof(sig), hash, sizeof(hash),
  274. &verified, &key, context, sizeof(context));
  275. if (ret < 0) {
  276. // error performing verification
  277. } else if (verified == 0)
  278. // the signature is invalid
  279. }
  280. \endcode
  281. \sa wc_ed448_verify_msg
  282. \sa wc_ed448ph_verify_msg
  283. \sa wc_ed448ph_sign_hash
  284. */
  285. int wc_ed448ph_verify_hash(const byte* sig, word32 siglen, const byte* hash,
  286. word32 hashlen, int* res, ed448_key* key,
  287. const byte* context, byte contextLen);
  288. /*!
  289. \ingroup ED448
  290. \brief This function verifies the Ed448 signature of a message to ensure
  291. authenticity. The context is included as part of the data
  292. verified. The message is pre-hashed before verification. The answer is
  293. returned through res, with 1 corresponding to a valid signature, and 0
  294. corresponding to an invalid signature.
  295. \return 0 Returned upon successfully performing the signature
  296. verification and authentication.
  297. \return BAD_FUNC_ARG Returned if any of the input parameters evaluate to
  298. NULL, or if the siglen does not match the actual length of a signature.
  299. \return SIG_VERIFY_E Returned if verification completes, but the signature
  300. generated does not match the signature provided.
  301. \param [in] sig Pointer to the buffer containing the signature to verify.
  302. \param [in] siglen Length of the signature to verify.
  303. \param [in] msg Pointer to the buffer containing the message to verify.
  304. \param [in] msgLen Length of the message to verify.
  305. \param [in] key Pointer to a public Ed448 key with which to verify the
  306. signature.
  307. \param [in] context Pointer to the buffer containing the context for which
  308. the message was signed.
  309. \param [in] contextLen Length of the context buffer.
  310. _Example_
  311. \code
  312. ed448_key key;
  313. int ret, verified = 0;
  314. byte sig[] { initialize with received signature };
  315. byte msg[] = { initialize with message };
  316. byte context[] = { initialize with context of signature };
  317. // initialize key with received public key
  318. ret = wc_ed448ph_verify_msg(sig, sizeof(sig), msg, sizeof(msg), &verified,
  319. &key, context, sizeof(context));
  320. if (ret < 0) {
  321. // error performing verification
  322. } else if (verified == 0)
  323. // the signature is invalid
  324. }
  325. \endcode
  326. \sa wc_ed448_verify_msg
  327. \sa wc_ed448ph_verify_hash
  328. \sa wc_ed448ph_sign_msg
  329. */
  330. int wc_ed448ph_verify_msg(const byte* sig, word32 siglen, const byte* msg,
  331. word32 msgLen, int* res, ed448_key* key,
  332. const byte* context, byte contextLen);
  333. /*!
  334. \ingroup ED448
  335. \brief This function initializes an ed448_key object for future use
  336. with message verification.
  337. \return 0 Returned upon successfully initializing the ed448_key object.
  338. \return BAD_FUNC_ARG Returned if key is NULL.
  339. \param [in,out] key Pointer to the ed448_key object to initialize.
  340. _Example_
  341. \code
  342. ed448_key key;
  343. wc_ed448_init(&key);
  344. \endcode
  345. \sa wc_ed448_make_key
  346. \sa wc_ed448_free
  347. */
  348. int wc_ed448_init(ed448_key* key);
  349. /*!
  350. \ingroup ED448
  351. \brief This function frees an Ed448 object after it has been used.
  352. \param [in,out] key Pointer to the ed448_key object to free
  353. _Example_
  354. \code
  355. ed448_key key;
  356. // initialize key and perform secure exchanges
  357. ...
  358. wc_ed448_free(&key);
  359. \endcode
  360. \sa wc_ed448_init
  361. */
  362. void wc_ed448_free(ed448_key* key);
  363. /*!
  364. \ingroup ED448
  365. \brief This function imports a public ed448_key pair from a buffer
  366. containing the public key. This function will handle both compressed and
  367. uncompressed keys. The public key is checked that it matches the private
  368. key when one is present.
  369. \return 0 Returned on successfully importing the ed448_key.
  370. \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or inLen is
  371. less than the size of an Ed448 key.
  372. \param [in] in Pointer to the buffer containing the public key.
  373. \param [in] inLen Length of the buffer containing the public key.
  374. \param [in,out] key Pointer to the ed448_key object in which to store the
  375. public key.
  376. _Example_
  377. \code
  378. int ret;
  379. byte pub[] = { initialize Ed448 public key };
  380. ed_448 key;
  381. wc_ed448_init_key(&key);
  382. ret = wc_ed448_import_public(pub, sizeof(pub), &key);
  383. if (ret != 0) {
  384. // error importing key
  385. }
  386. \endcode
  387. \sa wc_ed448_import_public_ex
  388. \sa wc_ed448_import_private_key
  389. \sa wc_ed448_import_private_key_ex
  390. \sa wc_ed448_export_public
  391. */
  392. int wc_ed448_import_public(const byte* in, word32 inLen, ed448_key* key);
  393. /*!
  394. \ingroup ED448
  395. \brief This function imports a public ed448_key pair from a buffer
  396. containing the public key. This function will handle both compressed and
  397. uncompressed keys. Check public key matches private key, when present,
  398. when not trusted.
  399. \return 0 Returned on successfully importing the ed448_key.
  400. \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or inLen is
  401. less than the size of an Ed448 key.
  402. \param [in] in Pointer to the buffer containing the public key.
  403. \param [in] inLen Length of the buffer containing the public key.
  404. \param [in,out] key Pointer to the ed448_key object in which to store the
  405. public key.
  406. \param [in] trusted Public key data is trusted or not.
  407. _Example_
  408. \code
  409. int ret;
  410. byte pub[] = { initialize Ed448 public key };
  411. ed_448 key;
  412. wc_ed448_init_key(&key);
  413. ret = wc_ed448_import_public_ex(pub, sizeof(pub), &key, 1);
  414. if (ret != 0) {
  415. // error importing key
  416. }
  417. \endcode
  418. \sa wc_ed448_import_public
  419. \sa wc_ed448_import_private_key
  420. \sa wc_ed448_import_private_key_ex
  421. \sa wc_ed448_export_public
  422. */
  423. int wc_ed448_import_public_ex(const byte* in, word32 inLen, ed448_key* key,
  424. int trusted);
  425. /*!
  426. \ingroup ED448
  427. \brief This function imports an Ed448 private key only from a
  428. buffer.
  429. \return 0 Returned on successfully importing the Ed448 private key.
  430. \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or if
  431. privSz is less than ED448_KEY_SIZE.
  432. \param [in] priv Pointer to the buffer containing the private key.
  433. \param [in] privSz Length of the private key.
  434. \param [in,out] key Pointer to the ed448_key object in which to store the
  435. imported private key.
  436. _Example_
  437. \code
  438. int ret;
  439. byte priv[] = { initialize with 57 byte private key };
  440. ed448_key key;
  441. wc_ed448_init_key(&key);
  442. ret = wc_ed448_import_private_only(priv, sizeof(priv), &key);
  443. if (ret != 0) {
  444. // error importing private key
  445. }
  446. \endcode
  447. \sa wc_ed448_import_public
  448. \sa wc_ed448_import_public_ex
  449. \sa wc_ed448_import_private_key
  450. \sa wc_ed448_import_private_key_ex
  451. \sa wc_ed448_export_private_only
  452. */
  453. int wc_ed448_import_private_only(const byte* priv, word32 privSz,
  454. ed448_key* key);
  455. /*!
  456. \ingroup ED448
  457. \brief This function imports a public/private Ed448 key pair from a
  458. pair of buffers. This function will handle both compressed and
  459. uncompressed keys.
  460. \return 0 Returned on successfully importing the Ed448 key.
  461. \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or if
  462. either privSz is less than ED448_KEY_SIZE or pubSz is less than
  463. ED448_PUB_KEY_SIZE.
  464. \param [in] priv Pointer to the buffer containing the private key.
  465. \param [in] privSz Length of the private key.
  466. \param [in] pub Pointer to the buffer containing the public key.
  467. \param [in] pubSz Length of the public key.
  468. \param [in,out] key Pointer to the ed448_key object in which to store the
  469. imported private/public key pair.
  470. _Example_
  471. \code
  472. int ret;
  473. byte priv[] = { initialize with 57 byte private key };
  474. byte pub[] = { initialize with the corresponding public key };
  475. ed448_key key;
  476. wc_ed448_init_key(&key);
  477. ret = wc_ed448_import_private_key(priv, sizeof(priv), pub, sizeof(pub),
  478. &key);
  479. if (ret != 0) {
  480. // error importing key
  481. }
  482. \endcode
  483. \sa wc_ed448_import_public
  484. \sa wc_ed448_import_public_ex
  485. \sa wc_ed448_import_private_only
  486. \sa wc_ed448_import_private_key_ex
  487. \sa wc_ed448_export_private
  488. */
  489. int wc_ed448_import_private_key(const byte* priv, word32 privSz,
  490. const byte* pub, word32 pubSz, ed448_key* key);
  491. /*!
  492. \ingroup ED448
  493. \brief This function imports a public/private Ed448 key pair from a
  494. pair of buffers. This function will handle both compressed and
  495. uncompressed keys. The public is checked against private key if not trusted.
  496. \return 0 Returned on successfully importing the Ed448 key.
  497. \return BAD_FUNC_ARG Returned if in or key evaluate to NULL, or if
  498. either privSz is less than ED448_KEY_SIZE or pubSz is less than
  499. ED448_PUB_KEY_SIZE.
  500. \param [in] priv Pointer to the buffer containing the private key.
  501. \param [in] privSz Length of the private key.
  502. \param [in] pub Pointer to the buffer containing the public key.
  503. \param [in] pubSz Length of the public key.
  504. \param [in,out] key Pointer to the ed448_key object in which to store the
  505. imported private/public key pair.
  506. \param [in] trusted Public key data is trusted or not.
  507. _Example_
  508. \code
  509. int ret;
  510. byte priv[] = { initialize with 57 byte private key };
  511. byte pub[] = { initialize with the corresponding public key };
  512. ed448_key key;
  513. wc_ed448_init_key(&key);
  514. ret = wc_ed448_import_private_key_ex(priv, sizeof(priv), pub, sizeof(pub),
  515. &key, 1);
  516. if (ret != 0) {
  517. // error importing key
  518. }
  519. \endcode
  520. \sa wc_ed448_import_public
  521. \sa wc_ed448_import_public_ex
  522. \sa wc_ed448_import_private_only
  523. \sa wc_ed448_import_private_key
  524. \sa wc_ed448_export_private
  525. */
  526. int wc_ed448_import_private_key_ex(const byte* priv, word32 privSz,
  527. const byte* pub, word32 pubSz, ed448_key* key, int trusted);
  528. /*!
  529. \ingroup ED448
  530. \brief This function exports the private key from an ed448_key
  531. structure. It stores the public key in the buffer out, and sets the bytes
  532. written to this buffer in outLen.
  533. \return 0 Returned upon successfully exporting the public key.
  534. \return BAD_FUNC_ARG Returned if any of the input values evaluate to NULL.
  535. \return BUFFER_E Returned if the buffer provided is not large enough to
  536. store the private key. Upon returning this error, the function sets the
  537. size required in outLen.
  538. \param [in] key Pointer to an ed448_key structure from which to export the
  539. public key.
  540. \param [out] out Pointer to the buffer in which to store the public key.
  541. \param [in,out] outLen Pointer to a word32 object with the size available
  542. in out. Set with the number of bytes written to out after successfully
  543. exporting the public key.
  544. _Example_
  545. \code
  546. int ret;
  547. ed448_key key;
  548. // initialize key, make key
  549. char pub[57];
  550. word32 pubSz = sizeof(pub);
  551. ret = wc_ed448_export_public(&key, pub, &pubSz);
  552. if (ret != 0) {
  553. // error exporting public key
  554. }
  555. \endcode
  556. \sa wc_ed448_import_public
  557. \sa wc_ed448_import_public_ex
  558. \sa wc_ed448_export_private_only
  559. */
  560. int wc_ed448_export_public(ed448_key* key, byte* out, word32* outLen);
  561. /*!
  562. \ingroup ED448
  563. \brief This function exports only the private key from an ed448_key
  564. structure. It stores the private key in the buffer out, and sets
  565. the bytes written to this buffer in outLen.
  566. \return 0 Returned upon successfully exporting the private key.
  567. \return ECC_BAD_ARG_E Returned if any of the input values evaluate to NULL.
  568. \return BUFFER_E Returned if the buffer provided is not large enough
  569. to store the private key.
  570. \param [in] key Pointer to an ed448_key structure from which to export
  571. the private key.
  572. \param [out] out Pointer to the buffer in which to store the private key.
  573. \param [in,out] outLen Pointer to a word32 object with the size available in
  574. out. Set with the number of bytes written to out after successfully
  575. exporting the private key.
  576. _Example_
  577. \code
  578. int ret;
  579. ed448_key key;
  580. // initialize key, make key
  581. char priv[57]; // 57 bytes because only private key
  582. word32 privSz = sizeof(priv);
  583. ret = wc_ed448_export_private_only(&key, priv, &privSz);
  584. if (ret != 0) {
  585. // error exporting private key
  586. }
  587. \endcode
  588. \sa wc_ed448_export_public
  589. \sa wc_ed448_import_private_key
  590. \sa wc_ed448_import_private_key_ex
  591. */
  592. int wc_ed448_export_private_only(ed448_key* key, byte* out, word32* outLen);
  593. /*!
  594. \ingroup ED448
  595. \brief This function exports the key pair from an ed448_key
  596. structure. It stores the key pair in the buffer out, and sets
  597. the bytes written to this buffer in outLen.
  598. \return 0 Returned upon successfully exporting the key pair.
  599. \return ECC_BAD_ARG_E Returned if any of the input values evaluate to NULL.
  600. \return BUFFER_E Returned if the buffer provided is not large enough
  601. to store the key pair.
  602. \param [in] key Pointer to an ed448_key structure from which to export
  603. the key pair.
  604. \param [out] out Pointer to the buffer in which to store the key pair.
  605. \param [in,out] outLen Pointer to a word32 object with the size available in
  606. out. Set with the number of bytes written to out after successfully
  607. exporting the key pair.
  608. _Example_
  609. \code
  610. ed448_key key;
  611. wc_ed448_init(&key);
  612. WC_RNG rng;
  613. wc_InitRng(&rng);
  614. wc_ed448_make_key(&rng, 57, &key); // initialize 57 byte Ed448 key
  615. byte out[114]; // out needs to be a sufficient buffer size
  616. word32 outLen = sizeof(out);
  617. int key_size = wc_ed448_export_private(&key, out, &outLen);
  618. if (key_size == BUFFER_E) {
  619. // Check size of out compared to outLen to see if function reset outLen
  620. }
  621. \endcode
  622. \sa wc_ed448_import_private
  623. \sa wc_ed448_export_private_only
  624. */
  625. int wc_ed448_export_private(ed448_key* key, byte* out, word32* outLen);
  626. /*!
  627. \ingroup ED448
  628. \brief This function exports the private and public key separately from an
  629. ed448_key structure. It stores the private key in the buffer priv, and sets
  630. the bytes written to this buffer in privSz. It stores the public key in the
  631. buffer pub, and sets the bytes written to this buffer in pubSz.
  632. \return 0 Returned upon successfully exporting the key pair.
  633. \return ECC_BAD_ARG_E Returned if any of the input values evaluate to NULL.
  634. \return BUFFER_E Returned if the buffer provided is not large enough
  635. to store the key pair.
  636. \param [in] key Pointer to an ed448_key structure from which to export
  637. the key pair.
  638. \param [out] priv Pointer to the buffer in which to store the private key.
  639. \param [in,out] privSz Pointer to a word32 object with the size available in
  640. out. Set with the number of bytes written to out after successfully
  641. exporting the private key.
  642. \param [out] pub Pointer to the buffer in which to store the public key.
  643. \param [in,out] pubSz Pointer to a word32 object with the size available in
  644. out. Set with the number of bytes written to out after successfully
  645. exporting the public key.
  646. _Example_
  647. \code
  648. int ret;
  649. ed448_key key;
  650. // initialize key, make key
  651. char pub[57];
  652. word32 pubSz = sizeof(pub);
  653. char priv[57];
  654. word32 privSz = sizeof(priv);
  655. ret = wc_ed448_export_key(&key, priv, &pubSz, pub, &pubSz);
  656. if (ret != 0) {
  657. // error exporting private and public key
  658. }
  659. \endcode
  660. \sa wc_ed448_export_private
  661. \sa wc_ed448_export_public
  662. */
  663. int wc_ed448_export_key(ed448_key* key,
  664. byte* priv, word32 *privSz,
  665. byte* pub, word32 *pubSz);
  666. /*!
  667. \ingroup ED448
  668. \brief This function checks the public key in ed448_key structure matches
  669. the private key.
  670. \return 0 Returned if the private and public key matched.
  671. \return BAD_FUNC_ARGS Returned if the given key is NULL.
  672. \param [in] key Pointer to an ed448_key structure holding a private and
  673. public key.
  674. _Example_
  675. \code
  676. int ret;
  677. byte priv[] = { initialize with 57 byte private key };
  678. byte pub[] = { initialize with the corresponding public key };
  679. ed448_key key;
  680. wc_ed448_init_key(&key);
  681. wc_ed448_import_private_key_ex(priv, sizeof(priv), pub, sizeof(pub), &key,
  682. 1);
  683. ret = wc_ed448_check_key(&key);
  684. if (ret != 0) {
  685. // error checking key
  686. }
  687. \endcode
  688. \sa wc_ed448_import_private_key
  689. \sa wc_ed448_import_private_key_ex
  690. */
  691. int wc_ed448_check_key(ed448_key* key);
  692. /*!
  693. \ingroup ED448
  694. \brief This function returns the size of an Ed448 private key - 57 bytes.
  695. \return ED448_KEY_SIZE The size of a valid private key (57 bytes).
  696. \return BAD_FUNC_ARGS Returned if the given key is NULL.
  697. \param [in] key Pointer to an ed448_key structure for which to get the
  698. key size.
  699. _Example_
  700. \code
  701. int keySz;
  702. ed448_key key;
  703. // initialize key, make key
  704. keySz = wc_ed448_size(&key);
  705. if (keySz == 0) {
  706. // error determining key size
  707. }
  708. \endcode
  709. \sa wc_ed448_make_key
  710. */
  711. int wc_ed448_size(ed448_key* key);
  712. /*!
  713. \ingroup ED448
  714. \brief This function returns the private key size (secret + public) in
  715. bytes.
  716. \return ED448_PRV_KEY_SIZE The size of the private key (114 bytes).
  717. \return BAD_FUNC_ARG Returns if key argument is NULL.
  718. \param [in] key Pointer to an ed448_key structure for which to get the
  719. key size.
  720. _Example_
  721. \code
  722. ed448_key key;
  723. wc_ed448_init(&key);
  724. WC_RNG rng;
  725. wc_InitRng(&rng);
  726. wc_ed448_make_key(&rng, 57, &key); // initialize 57 byte Ed448 key
  727. int key_size = wc_ed448_priv_size(&key);
  728. \endcode
  729. \sa wc_ed448_pub_size
  730. */
  731. int wc_ed448_priv_size(ed448_key* key);
  732. /*!
  733. \ingroup ED448
  734. \brief This function returns the compressed key size in bytes (public key).
  735. \return ED448_PUB_KEY_SIZE The size of the compressed public key (57 bytes).
  736. \return BAD_FUNC_ARG Returns if key argument is NULL.
  737. \param [in] key Pointer to an ed448_key structure for which to get the
  738. key size.
  739. _Example_
  740. \code
  741. ed448_key key;
  742. wc_ed448_init(&key);
  743. WC_RNG rng;
  744. wc_InitRng(&rng);
  745. wc_ed448_make_key(&rng, 57, &key); // initialize 57 byte Ed448 key
  746. int key_size = wc_ed448_pub_size(&key);
  747. \endcode
  748. \sa wc_ed448_priv_size
  749. */
  750. int wc_ed448_pub_size(ed448_key* key);
  751. /*!
  752. \ingroup ED448
  753. \brief This function returns the size of an Ed448 signature (114 in bytes).
  754. \return ED448_SIG_SIZE The size of an Ed448 signature (114 bytes).
  755. \return BAD_FUNC_ARG Returns if key argument is NULL.
  756. \param [in] key Pointer to an ed448_key structure for which to get the
  757. signature size.
  758. _Example_
  759. \code
  760. int sigSz;
  761. ed448_key key;
  762. // initialize key, make key
  763. sigSz = wc_ed448_sig_size(&key);
  764. if (sigSz == 0) {
  765. // error determining sig size
  766. }
  767. \endcode
  768. \sa wc_ed448_sign_msg
  769. */
  770. int wc_ed448_sig_size(ed448_key* key);