pk.h 29 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755
  1. /**
  2. * \file pk.h
  3. *
  4. * \brief Public Key abstraction layer
  5. */
  6. /*
  7. * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  8. * SPDX-License-Identifier: Apache-2.0
  9. *
  10. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  11. * not use this file except in compliance with the License.
  12. * You may obtain a copy of the License at
  13. *
  14. * http://www.apache.org/licenses/LICENSE-2.0
  15. *
  16. * Unless required by applicable law or agreed to in writing, software
  17. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  18. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19. * See the License for the specific language governing permissions and
  20. * limitations under the License.
  21. *
  22. * This file is part of mbed TLS (https://tls.mbed.org)
  23. */
  24. #ifndef MBEDTLS_PK_H
  25. #define MBEDTLS_PK_H
  26. #if !defined(MBEDTLS_CONFIG_FILE)
  27. #include "config.h"
  28. #else
  29. #include MBEDTLS_CONFIG_FILE
  30. #endif
  31. #include "md.h"
  32. #if defined(MBEDTLS_RSA_C)
  33. #include "rsa.h"
  34. #endif
  35. #if defined(MBEDTLS_ECP_C)
  36. #include "ecp.h"
  37. #endif
  38. #if defined(MBEDTLS_ECDSA_C)
  39. #include "ecdsa.h"
  40. #endif
  41. #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
  42. !defined(inline) && !defined(__cplusplus)
  43. #define inline __inline
  44. #endif
  45. #define MBEDTLS_ERR_PK_ALLOC_FAILED -0x3F80 /**< Memory allocation failed. */
  46. #define MBEDTLS_ERR_PK_TYPE_MISMATCH -0x3F00 /**< Type mismatch, eg attempt to encrypt with an ECDSA key */
  47. #define MBEDTLS_ERR_PK_BAD_INPUT_DATA -0x3E80 /**< Bad input parameters to function. */
  48. #define MBEDTLS_ERR_PK_FILE_IO_ERROR -0x3E00 /**< Read/write of file failed. */
  49. #define MBEDTLS_ERR_PK_KEY_INVALID_VERSION -0x3D80 /**< Unsupported key version */
  50. #define MBEDTLS_ERR_PK_KEY_INVALID_FORMAT -0x3D00 /**< Invalid key tag or value. */
  51. #define MBEDTLS_ERR_PK_UNKNOWN_PK_ALG -0x3C80 /**< Key algorithm is unsupported (only RSA and EC are supported). */
  52. #define MBEDTLS_ERR_PK_PASSWORD_REQUIRED -0x3C00 /**< Private key password can't be empty. */
  53. #define MBEDTLS_ERR_PK_PASSWORD_MISMATCH -0x3B80 /**< Given private key password does not allow for correct decryption. */
  54. #define MBEDTLS_ERR_PK_INVALID_PUBKEY -0x3B00 /**< The pubkey tag or value is invalid (only RSA and EC are supported). */
  55. #define MBEDTLS_ERR_PK_INVALID_ALG -0x3A80 /**< The algorithm tag or value is invalid. */
  56. #define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE -0x3A00 /**< Elliptic curve is unsupported (only NIST curves are supported). */
  57. #define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980 /**< Unavailable feature, e.g. RSA disabled for RSA key. */
  58. #define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH -0x3900 /**< The buffer contains a valid signature followed by more data. */
  59. /* MBEDTLS_ERR_PK_HW_ACCEL_FAILED is deprecated and should not be used. */
  60. #define MBEDTLS_ERR_PK_HW_ACCEL_FAILED -0x3880 /**< PK hardware accelerator failed. */
  61. #ifdef __cplusplus
  62. extern "C" {
  63. #endif
  64. /**
  65. * \brief Public key types
  66. */
  67. typedef enum {
  68. MBEDTLS_PK_NONE=0,
  69. MBEDTLS_PK_RSA,
  70. MBEDTLS_PK_ECKEY,
  71. MBEDTLS_PK_ECKEY_DH,
  72. MBEDTLS_PK_ECDSA,
  73. MBEDTLS_PK_RSA_ALT,
  74. MBEDTLS_PK_RSASSA_PSS,
  75. } mbedtls_pk_type_t;
  76. /**
  77. * \brief Options for RSASSA-PSS signature verification.
  78. * See \c mbedtls_rsa_rsassa_pss_verify_ext()
  79. */
  80. typedef struct mbedtls_pk_rsassa_pss_options
  81. {
  82. mbedtls_md_type_t mgf1_hash_id;
  83. int expected_salt_len;
  84. } mbedtls_pk_rsassa_pss_options;
  85. /**
  86. * \brief Types for interfacing with the debug module
  87. */
  88. typedef enum
  89. {
  90. MBEDTLS_PK_DEBUG_NONE = 0,
  91. MBEDTLS_PK_DEBUG_MPI,
  92. MBEDTLS_PK_DEBUG_ECP,
  93. } mbedtls_pk_debug_type;
  94. /**
  95. * \brief Item to send to the debug module
  96. */
  97. typedef struct mbedtls_pk_debug_item
  98. {
  99. mbedtls_pk_debug_type type;
  100. const char *name;
  101. void *value;
  102. } mbedtls_pk_debug_item;
  103. /** Maximum number of item send for debugging, plus 1 */
  104. #define MBEDTLS_PK_DEBUG_MAX_ITEMS 3
  105. /**
  106. * \brief Public key information and operations
  107. */
  108. typedef struct mbedtls_pk_info_t mbedtls_pk_info_t;
  109. /**
  110. * \brief Public key container
  111. */
  112. typedef struct mbedtls_pk_context
  113. {
  114. const mbedtls_pk_info_t * pk_info; /**< Public key information */
  115. void * pk_ctx; /**< Underlying public key context */
  116. } mbedtls_pk_context;
  117. #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
  118. /**
  119. * \brief Context for resuming operations
  120. */
  121. typedef struct
  122. {
  123. const mbedtls_pk_info_t * pk_info; /**< Public key information */
  124. void * rs_ctx; /**< Underlying restart context */
  125. } mbedtls_pk_restart_ctx;
  126. #else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
  127. /* Now we can declare functions that take a pointer to that */
  128. typedef void mbedtls_pk_restart_ctx;
  129. #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
  130. #if defined(MBEDTLS_RSA_C)
  131. /**
  132. * Quick access to an RSA context inside a PK context.
  133. *
  134. * \warning You must make sure the PK context actually holds an RSA context
  135. * before using this function!
  136. */
  137. static inline mbedtls_rsa_context *mbedtls_pk_rsa( const mbedtls_pk_context pk )
  138. {
  139. return( (mbedtls_rsa_context *) (pk).pk_ctx );
  140. }
  141. #endif /* MBEDTLS_RSA_C */
  142. #if defined(MBEDTLS_ECP_C)
  143. /**
  144. * Quick access to an EC context inside a PK context.
  145. *
  146. * \warning You must make sure the PK context actually holds an EC context
  147. * before using this function!
  148. */
  149. static inline mbedtls_ecp_keypair *mbedtls_pk_ec( const mbedtls_pk_context pk )
  150. {
  151. return( (mbedtls_ecp_keypair *) (pk).pk_ctx );
  152. }
  153. #endif /* MBEDTLS_ECP_C */
  154. #if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
  155. /**
  156. * \brief Types for RSA-alt abstraction
  157. */
  158. typedef int (*mbedtls_pk_rsa_alt_decrypt_func)( void *ctx, int mode, size_t *olen,
  159. const unsigned char *input, unsigned char *output,
  160. size_t output_max_len );
  161. typedef int (*mbedtls_pk_rsa_alt_sign_func)( void *ctx,
  162. int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
  163. int mode, mbedtls_md_type_t md_alg, unsigned int hashlen,
  164. const unsigned char *hash, unsigned char *sig );
  165. typedef size_t (*mbedtls_pk_rsa_alt_key_len_func)( void *ctx );
  166. #endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
  167. /**
  168. * \brief Return information associated with the given PK type
  169. *
  170. * \param pk_type PK type to search for.
  171. *
  172. * \return The PK info associated with the type or NULL if not found.
  173. */
  174. const mbedtls_pk_info_t *mbedtls_pk_info_from_type( mbedtls_pk_type_t pk_type );
  175. /**
  176. * \brief Initialize a #mbedtls_pk_context (as NONE).
  177. *
  178. * \param ctx The context to initialize.
  179. * This must not be \c NULL.
  180. */
  181. void mbedtls_pk_init( mbedtls_pk_context *ctx );
  182. /**
  183. * \brief Free the components of a #mbedtls_pk_context.
  184. *
  185. * \param ctx The context to clear. It must have been initialized.
  186. * If this is \c NULL, this function does nothing.
  187. */
  188. void mbedtls_pk_free( mbedtls_pk_context *ctx );
  189. #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
  190. /**
  191. * \brief Initialize a restart context
  192. *
  193. * \param ctx The context to initialize.
  194. * This must not be \c NULL.
  195. */
  196. void mbedtls_pk_restart_init( mbedtls_pk_restart_ctx *ctx );
  197. /**
  198. * \brief Free the components of a restart context
  199. *
  200. * \param ctx The context to clear. It must have been initialized.
  201. * If this is \c NULL, this function does nothing.
  202. */
  203. void mbedtls_pk_restart_free( mbedtls_pk_restart_ctx *ctx );
  204. #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
  205. /**
  206. * \brief Initialize a PK context with the information given
  207. * and allocates the type-specific PK subcontext.
  208. *
  209. * \param ctx Context to initialize. It must not have been set
  210. * up yet (type #MBEDTLS_PK_NONE).
  211. * \param info Information to use
  212. *
  213. * \return 0 on success,
  214. * MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input,
  215. * MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.
  216. *
  217. * \note For contexts holding an RSA-alt key, use
  218. * \c mbedtls_pk_setup_rsa_alt() instead.
  219. */
  220. int mbedtls_pk_setup( mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info );
  221. #if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
  222. /**
  223. * \brief Initialize an RSA-alt context
  224. *
  225. * \param ctx Context to initialize. It must not have been set
  226. * up yet (type #MBEDTLS_PK_NONE).
  227. * \param key RSA key pointer
  228. * \param decrypt_func Decryption function
  229. * \param sign_func Signing function
  230. * \param key_len_func Function returning key length in bytes
  231. *
  232. * \return 0 on success, or MBEDTLS_ERR_PK_BAD_INPUT_DATA if the
  233. * context wasn't already initialized as RSA_ALT.
  234. *
  235. * \note This function replaces \c mbedtls_pk_setup() for RSA-alt.
  236. */
  237. int mbedtls_pk_setup_rsa_alt( mbedtls_pk_context *ctx, void * key,
  238. mbedtls_pk_rsa_alt_decrypt_func decrypt_func,
  239. mbedtls_pk_rsa_alt_sign_func sign_func,
  240. mbedtls_pk_rsa_alt_key_len_func key_len_func );
  241. #endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
  242. /**
  243. * \brief Get the size in bits of the underlying key
  244. *
  245. * \param ctx The context to query. It must have been initialized.
  246. *
  247. * \return Key size in bits, or 0 on error
  248. */
  249. size_t mbedtls_pk_get_bitlen( const mbedtls_pk_context *ctx );
  250. /**
  251. * \brief Get the length in bytes of the underlying key
  252. *
  253. * \param ctx The context to query. It must have been initialized.
  254. *
  255. * \return Key length in bytes, or 0 on error
  256. */
  257. static inline size_t mbedtls_pk_get_len( const mbedtls_pk_context *ctx )
  258. {
  259. return( ( mbedtls_pk_get_bitlen( ctx ) + 7 ) / 8 );
  260. }
  261. /**
  262. * \brief Tell if a context can do the operation given by type
  263. *
  264. * \param ctx The context to query. It must have been initialized.
  265. * \param type The desired type.
  266. *
  267. * \return 1 if the context can do operations on the given type.
  268. * \return 0 if the context cannot do the operations on the given
  269. * type. This is always the case for a context that has
  270. * been initialized but not set up, or that has been
  271. * cleared with mbedtls_pk_free().
  272. */
  273. int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type );
  274. /**
  275. * \brief Verify signature (including padding if relevant).
  276. *
  277. * \param ctx The PK context to use. It must have been set up.
  278. * \param md_alg Hash algorithm used (see notes)
  279. * \param hash Hash of the message to sign
  280. * \param hash_len Hash length or 0 (see notes)
  281. * \param sig Signature to verify
  282. * \param sig_len Signature length
  283. *
  284. * \return 0 on success (signature is valid),
  285. * #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid
  286. * signature in sig but its length is less than \p siglen,
  287. * or a specific error code.
  288. *
  289. * \note For RSA keys, the default padding type is PKCS#1 v1.5.
  290. * Use \c mbedtls_pk_verify_ext( MBEDTLS_PK_RSASSA_PSS, ... )
  291. * to verify RSASSA_PSS signatures.
  292. *
  293. * \note If hash_len is 0, then the length associated with md_alg
  294. * is used instead, or an error returned if it is invalid.
  295. *
  296. * \note md_alg may be MBEDTLS_MD_NONE, only if hash_len != 0
  297. */
  298. int mbedtls_pk_verify( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
  299. const unsigned char *hash, size_t hash_len,
  300. const unsigned char *sig, size_t sig_len );
  301. /**
  302. * \brief Restartable version of \c mbedtls_pk_verify()
  303. *
  304. * \note Performs the same job as \c mbedtls_pk_verify(), but can
  305. * return early and restart according to the limit set with
  306. * \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
  307. * operations. For RSA, same as \c mbedtls_pk_verify().
  308. *
  309. * \param ctx The PK context to use. It must have been set up.
  310. * \param md_alg Hash algorithm used (see notes)
  311. * \param hash Hash of the message to sign
  312. * \param hash_len Hash length or 0 (see notes)
  313. * \param sig Signature to verify
  314. * \param sig_len Signature length
  315. * \param rs_ctx Restart context (NULL to disable restart)
  316. *
  317. * \return See \c mbedtls_pk_verify(), or
  318. * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
  319. * operations was reached: see \c mbedtls_ecp_set_max_ops().
  320. */
  321. int mbedtls_pk_verify_restartable( mbedtls_pk_context *ctx,
  322. mbedtls_md_type_t md_alg,
  323. const unsigned char *hash, size_t hash_len,
  324. const unsigned char *sig, size_t sig_len,
  325. mbedtls_pk_restart_ctx *rs_ctx );
  326. /**
  327. * \brief Verify signature, with options.
  328. * (Includes verification of the padding depending on type.)
  329. *
  330. * \param type Signature type (inc. possible padding type) to verify
  331. * \param options Pointer to type-specific options, or NULL
  332. * \param ctx The PK context to use. It must have been set up.
  333. * \param md_alg Hash algorithm used (see notes)
  334. * \param hash Hash of the message to sign
  335. * \param hash_len Hash length or 0 (see notes)
  336. * \param sig Signature to verify
  337. * \param sig_len Signature length
  338. *
  339. * \return 0 on success (signature is valid),
  340. * #MBEDTLS_ERR_PK_TYPE_MISMATCH if the PK context can't be
  341. * used for this type of signatures,
  342. * #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid
  343. * signature in sig but its length is less than \p siglen,
  344. * or a specific error code.
  345. *
  346. * \note If hash_len is 0, then the length associated with md_alg
  347. * is used instead, or an error returned if it is invalid.
  348. *
  349. * \note md_alg may be MBEDTLS_MD_NONE, only if hash_len != 0
  350. *
  351. * \note If type is MBEDTLS_PK_RSASSA_PSS, then options must point
  352. * to a mbedtls_pk_rsassa_pss_options structure,
  353. * otherwise it must be NULL.
  354. */
  355. int mbedtls_pk_verify_ext( mbedtls_pk_type_t type, const void *options,
  356. mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
  357. const unsigned char *hash, size_t hash_len,
  358. const unsigned char *sig, size_t sig_len );
  359. /**
  360. * \brief Make signature, including padding if relevant.
  361. *
  362. * \param ctx The PK context to use. It must have been set up
  363. * with a private key.
  364. * \param md_alg Hash algorithm used (see notes)
  365. * \param hash Hash of the message to sign
  366. * \param hash_len Hash length or 0 (see notes)
  367. * \param sig Place to write the signature
  368. * \param sig_len Number of bytes written
  369. * \param f_rng RNG function
  370. * \param p_rng RNG parameter
  371. *
  372. * \return 0 on success, or a specific error code.
  373. *
  374. * \note For RSA keys, the default padding type is PKCS#1 v1.5.
  375. * There is no interface in the PK module to make RSASSA-PSS
  376. * signatures yet.
  377. *
  378. * \note If hash_len is 0, then the length associated with md_alg
  379. * is used instead, or an error returned if it is invalid.
  380. *
  381. * \note For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0.
  382. * For ECDSA, md_alg may never be MBEDTLS_MD_NONE.
  383. *
  384. * \note In order to ensure enough space for the signature, the
  385. * \p sig buffer size must be of at least
  386. * `max(MBEDTLS_ECDSA_MAX_LEN, MBEDTLS_MPI_MAX_SIZE)` bytes.
  387. */
  388. int mbedtls_pk_sign( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
  389. const unsigned char *hash, size_t hash_len,
  390. unsigned char *sig, size_t *sig_len,
  391. int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
  392. /**
  393. * \brief Restartable version of \c mbedtls_pk_sign()
  394. *
  395. * \note Performs the same job as \c mbedtls_pk_sign(), but can
  396. * return early and restart according to the limit set with
  397. * \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
  398. * operations. For RSA, same as \c mbedtls_pk_sign().
  399. *
  400. * \note In order to ensure enough space for the signature, the
  401. * \p sig buffer size must be of at least
  402. * `max(MBEDTLS_ECDSA_MAX_LEN, MBEDTLS_MPI_MAX_SIZE)` bytes.
  403. *
  404. * \param ctx The PK context to use. It must have been set up
  405. * with a private key.
  406. * \param md_alg Hash algorithm used (see notes)
  407. * \param hash Hash of the message to sign
  408. * \param hash_len Hash length or 0 (see notes)
  409. * \param sig Place to write the signature
  410. * \param sig_len Number of bytes written
  411. * \param f_rng RNG function
  412. * \param p_rng RNG parameter
  413. * \param rs_ctx Restart context (NULL to disable restart)
  414. *
  415. * \return See \c mbedtls_pk_sign(), or
  416. * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
  417. * operations was reached: see \c mbedtls_ecp_set_max_ops().
  418. */
  419. int mbedtls_pk_sign_restartable( mbedtls_pk_context *ctx,
  420. mbedtls_md_type_t md_alg,
  421. const unsigned char *hash, size_t hash_len,
  422. unsigned char *sig, size_t *sig_len,
  423. int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
  424. mbedtls_pk_restart_ctx *rs_ctx );
  425. /**
  426. * \brief Decrypt message (including padding if relevant).
  427. *
  428. * \param ctx The PK context to use. It must have been set up
  429. * with a private key.
  430. * \param input Input to decrypt
  431. * \param ilen Input size
  432. * \param output Decrypted output
  433. * \param olen Decrypted message length
  434. * \param osize Size of the output buffer
  435. * \param f_rng RNG function
  436. * \param p_rng RNG parameter
  437. *
  438. * \note For RSA keys, the default padding type is PKCS#1 v1.5.
  439. *
  440. * \return 0 on success, or a specific error code.
  441. */
  442. int mbedtls_pk_decrypt( mbedtls_pk_context *ctx,
  443. const unsigned char *input, size_t ilen,
  444. unsigned char *output, size_t *olen, size_t osize,
  445. int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
  446. /**
  447. * \brief Encrypt message (including padding if relevant).
  448. *
  449. * \param ctx The PK context to use. It must have been set up.
  450. * \param input Message to encrypt
  451. * \param ilen Message size
  452. * \param output Encrypted output
  453. * \param olen Encrypted output length
  454. * \param osize Size of the output buffer
  455. * \param f_rng RNG function
  456. * \param p_rng RNG parameter
  457. *
  458. * \note For RSA keys, the default padding type is PKCS#1 v1.5.
  459. *
  460. * \return 0 on success, or a specific error code.
  461. */
  462. int mbedtls_pk_encrypt( mbedtls_pk_context *ctx,
  463. const unsigned char *input, size_t ilen,
  464. unsigned char *output, size_t *olen, size_t osize,
  465. int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
  466. /**
  467. * \brief Check if a public-private pair of keys matches.
  468. *
  469. * \param pub Context holding a public key.
  470. * \param prv Context holding a private (and public) key.
  471. *
  472. * \return 0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
  473. */
  474. int mbedtls_pk_check_pair( const mbedtls_pk_context *pub, const mbedtls_pk_context *prv );
  475. /**
  476. * \brief Export debug information
  477. *
  478. * \param ctx The PK context to use. It must have been initialized.
  479. * \param items Place to write debug items
  480. *
  481. * \return 0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
  482. */
  483. int mbedtls_pk_debug( const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *items );
  484. /**
  485. * \brief Access the type name
  486. *
  487. * \param ctx The PK context to use. It must have been initialized.
  488. *
  489. * \return Type name on success, or "invalid PK"
  490. */
  491. const char * mbedtls_pk_get_name( const mbedtls_pk_context *ctx );
  492. /**
  493. * \brief Get the key type
  494. *
  495. * \param ctx The PK context to use. It must have been initialized.
  496. *
  497. * \return Type on success.
  498. * \return #MBEDTLS_PK_NONE for a context that has not been set up.
  499. */
  500. mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx );
  501. #if defined(MBEDTLS_PK_PARSE_C)
  502. /** \ingroup pk_module */
  503. /**
  504. * \brief Parse a private key in PEM or DER format
  505. *
  506. * \param ctx The PK context to fill. It must have been initialized
  507. * but not set up.
  508. * \param key Input buffer to parse.
  509. * The buffer must contain the input exactly, with no
  510. * extra trailing material. For PEM, the buffer must
  511. * contain a null-terminated string.
  512. * \param keylen Size of \b key in bytes.
  513. * For PEM data, this includes the terminating null byte,
  514. * so \p keylen must be equal to `strlen(key) + 1`.
  515. * \param pwd Optional password for decryption.
  516. * Pass \c NULL if expecting a non-encrypted key.
  517. * Pass a string of \p pwdlen bytes if expecting an encrypted
  518. * key; a non-encrypted key will also be accepted.
  519. * The empty password is not supported.
  520. * \param pwdlen Size of the password in bytes.
  521. * Ignored if \p pwd is \c NULL.
  522. *
  523. * \note On entry, ctx must be empty, either freshly initialised
  524. * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
  525. * specific key type, check the result with mbedtls_pk_can_do().
  526. *
  527. * \note The key is also checked for correctness.
  528. *
  529. * \return 0 if successful, or a specific PK or PEM error code
  530. */
  531. int mbedtls_pk_parse_key( mbedtls_pk_context *ctx,
  532. const unsigned char *key, size_t keylen,
  533. const unsigned char *pwd, size_t pwdlen );
  534. /** \ingroup pk_module */
  535. /**
  536. * \brief Parse a public key in PEM or DER format
  537. *
  538. * \param ctx The PK context to fill. It must have been initialized
  539. * but not set up.
  540. * \param key Input buffer to parse.
  541. * The buffer must contain the input exactly, with no
  542. * extra trailing material. For PEM, the buffer must
  543. * contain a null-terminated string.
  544. * \param keylen Size of \b key in bytes.
  545. * For PEM data, this includes the terminating null byte,
  546. * so \p keylen must be equal to `strlen(key) + 1`.
  547. *
  548. * \note On entry, ctx must be empty, either freshly initialised
  549. * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
  550. * specific key type, check the result with mbedtls_pk_can_do().
  551. *
  552. * \note The key is also checked for correctness.
  553. *
  554. * \return 0 if successful, or a specific PK or PEM error code
  555. */
  556. int mbedtls_pk_parse_public_key( mbedtls_pk_context *ctx,
  557. const unsigned char *key, size_t keylen );
  558. #if defined(MBEDTLS_FS_IO)
  559. /** \ingroup pk_module */
  560. /**
  561. * \brief Load and parse a private key
  562. *
  563. * \param ctx The PK context to fill. It must have been initialized
  564. * but not set up.
  565. * \param path filename to read the private key from
  566. * \param password Optional password to decrypt the file.
  567. * Pass \c NULL if expecting a non-encrypted key.
  568. * Pass a null-terminated string if expecting an encrypted
  569. * key; a non-encrypted key will also be accepted.
  570. * The empty password is not supported.
  571. *
  572. * \note On entry, ctx must be empty, either freshly initialised
  573. * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
  574. * specific key type, check the result with mbedtls_pk_can_do().
  575. *
  576. * \note The key is also checked for correctness.
  577. *
  578. * \return 0 if successful, or a specific PK or PEM error code
  579. */
  580. int mbedtls_pk_parse_keyfile( mbedtls_pk_context *ctx,
  581. const char *path, const char *password );
  582. /** \ingroup pk_module */
  583. /**
  584. * \brief Load and parse a public key
  585. *
  586. * \param ctx The PK context to fill. It must have been initialized
  587. * but not set up.
  588. * \param path filename to read the public key from
  589. *
  590. * \note On entry, ctx must be empty, either freshly initialised
  591. * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If
  592. * you need a specific key type, check the result with
  593. * mbedtls_pk_can_do().
  594. *
  595. * \note The key is also checked for correctness.
  596. *
  597. * \return 0 if successful, or a specific PK or PEM error code
  598. */
  599. int mbedtls_pk_parse_public_keyfile( mbedtls_pk_context *ctx, const char *path );
  600. #endif /* MBEDTLS_FS_IO */
  601. #endif /* MBEDTLS_PK_PARSE_C */
  602. #if defined(MBEDTLS_PK_WRITE_C)
  603. /**
  604. * \brief Write a private key to a PKCS#1 or SEC1 DER structure
  605. * Note: data is written at the end of the buffer! Use the
  606. * return value to determine where you should start
  607. * using the buffer
  608. *
  609. * \param ctx PK context which must contain a valid private key.
  610. * \param buf buffer to write to
  611. * \param size size of the buffer
  612. *
  613. * \return length of data written if successful, or a specific
  614. * error code
  615. */
  616. int mbedtls_pk_write_key_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
  617. /**
  618. * \brief Write a public key to a SubjectPublicKeyInfo DER structure
  619. * Note: data is written at the end of the buffer! Use the
  620. * return value to determine where you should start
  621. * using the buffer
  622. *
  623. * \param ctx PK context which must contain a valid public or private key.
  624. * \param buf buffer to write to
  625. * \param size size of the buffer
  626. *
  627. * \return length of data written if successful, or a specific
  628. * error code
  629. */
  630. int mbedtls_pk_write_pubkey_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
  631. #if defined(MBEDTLS_PEM_WRITE_C)
  632. /**
  633. * \brief Write a public key to a PEM string
  634. *
  635. * \param ctx PK context which must contain a valid public or private key.
  636. * \param buf Buffer to write to. The output includes a
  637. * terminating null byte.
  638. * \param size Size of the buffer in bytes.
  639. *
  640. * \return 0 if successful, or a specific error code
  641. */
  642. int mbedtls_pk_write_pubkey_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
  643. /**
  644. * \brief Write a private key to a PKCS#1 or SEC1 PEM string
  645. *
  646. * \param ctx PK context which must contain a valid private key.
  647. * \param buf Buffer to write to. The output includes a
  648. * terminating null byte.
  649. * \param size Size of the buffer in bytes.
  650. *
  651. * \return 0 if successful, or a specific error code
  652. */
  653. int mbedtls_pk_write_key_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
  654. #endif /* MBEDTLS_PEM_WRITE_C */
  655. #endif /* MBEDTLS_PK_WRITE_C */
  656. /*
  657. * WARNING: Low-level functions. You probably do not want to use these unless
  658. * you are certain you do ;)
  659. */
  660. #if defined(MBEDTLS_PK_PARSE_C)
  661. /**
  662. * \brief Parse a SubjectPublicKeyInfo DER structure
  663. *
  664. * \param p the position in the ASN.1 data
  665. * \param end end of the buffer
  666. * \param pk The PK context to fill. It must have been initialized
  667. * but not set up.
  668. *
  669. * \return 0 if successful, or a specific PK error code
  670. */
  671. int mbedtls_pk_parse_subpubkey( unsigned char **p, const unsigned char *end,
  672. mbedtls_pk_context *pk );
  673. #endif /* MBEDTLS_PK_PARSE_C */
  674. #if defined(MBEDTLS_PK_WRITE_C)
  675. /**
  676. * \brief Write a subjectPublicKey to ASN.1 data
  677. * Note: function works backwards in data buffer
  678. *
  679. * \param p reference to current position pointer
  680. * \param start start of the buffer (for bounds-checking)
  681. * \param key PK context which must contain a valid public or private key.
  682. *
  683. * \return the length written or a negative error code
  684. */
  685. int mbedtls_pk_write_pubkey( unsigned char **p, unsigned char *start,
  686. const mbedtls_pk_context *key );
  687. #endif /* MBEDTLS_PK_WRITE_C */
  688. /*
  689. * Internal module functions. You probably do not want to use these unless you
  690. * know you do.
  691. */
  692. #if defined(MBEDTLS_FS_IO)
  693. int mbedtls_pk_load_file( const char *path, unsigned char **buf, size_t *n );
  694. #endif
  695. #ifdef __cplusplus
  696. }
  697. #endif
  698. #endif /* MBEDTLS_PK_H */