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