mbed TLS v2.16.6
pk.h
Go to the documentation of this file.
1 
6 /*
7  * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
8  * SPDX-License-Identifier: GPL-2.0
9  *
10  * This program is free software; you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License as published by
12  * the Free Software Foundation; either version 2 of the License, or
13  * (at your option) any later version.
14  *
15  * This program is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18  * GNU General Public License for more details.
19  *
20  * You should have received a copy of the GNU General Public License along
21  * with this program; if not, write to the Free Software Foundation, Inc.,
22  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
23  *
24  * This file is part of mbed TLS (https://tls.mbed.org)
25  */
26 
27 #ifndef MBEDTLS_PK_H
28 #define MBEDTLS_PK_H
29 
30 #if !defined(MBEDTLS_CONFIG_FILE)
31 #include "config.h"
32 #else
33 #include MBEDTLS_CONFIG_FILE
34 #endif
35 
36 #include "md.h"
37 
38 #if defined(MBEDTLS_RSA_C)
39 #include "rsa.h"
40 #endif
41 
42 #if defined(MBEDTLS_ECP_C)
43 #include "ecp.h"
44 #endif
45 
46 #if defined(MBEDTLS_ECDSA_C)
47 #include "ecdsa.h"
48 #endif
49 
50 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
51  !defined(inline) && !defined(__cplusplus)
52 #define inline __inline
53 #endif
54 
55 #define MBEDTLS_ERR_PK_ALLOC_FAILED -0x3F80
56 #define MBEDTLS_ERR_PK_TYPE_MISMATCH -0x3F00
57 #define MBEDTLS_ERR_PK_BAD_INPUT_DATA -0x3E80
58 #define MBEDTLS_ERR_PK_FILE_IO_ERROR -0x3E00
59 #define MBEDTLS_ERR_PK_KEY_INVALID_VERSION -0x3D80
60 #define MBEDTLS_ERR_PK_KEY_INVALID_FORMAT -0x3D00
61 #define MBEDTLS_ERR_PK_UNKNOWN_PK_ALG -0x3C80
62 #define MBEDTLS_ERR_PK_PASSWORD_REQUIRED -0x3C00
63 #define MBEDTLS_ERR_PK_PASSWORD_MISMATCH -0x3B80
64 #define MBEDTLS_ERR_PK_INVALID_PUBKEY -0x3B00
65 #define MBEDTLS_ERR_PK_INVALID_ALG -0x3A80
66 #define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE -0x3A00
67 #define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980
68 #define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH -0x3900
70 /* MBEDTLS_ERR_PK_HW_ACCEL_FAILED is deprecated and should not be used. */
71 #define MBEDTLS_ERR_PK_HW_ACCEL_FAILED -0x3880
73 #ifdef __cplusplus
74 extern "C" {
75 #endif
76 
80 typedef enum {
89 
95 {
98 
100 
104 typedef enum
105 {
110 
114 typedef struct mbedtls_pk_debug_item
115 {
117  const char *name;
118  void *value;
120 
122 #define MBEDTLS_PK_DEBUG_MAX_ITEMS 3
123 
128 
132 typedef struct mbedtls_pk_context
133 {
135  void * pk_ctx;
137 
138 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
139 
142 typedef struct
143 {
144  const mbedtls_pk_info_t * pk_info;
145  void * rs_ctx;
147 #else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
148 /* Now we can declare functions that take a pointer to that */
150 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
151 
152 #if defined(MBEDTLS_RSA_C)
153 
160 {
161  return( (mbedtls_rsa_context *) (pk).pk_ctx );
162 }
163 #endif /* MBEDTLS_RSA_C */
164 
165 #if defined(MBEDTLS_ECP_C)
166 
173 {
174  return( (mbedtls_ecp_keypair *) (pk).pk_ctx );
175 }
176 #endif /* MBEDTLS_ECP_C */
177 
178 #if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
179 
182 typedef int (*mbedtls_pk_rsa_alt_decrypt_func)( void *ctx, int mode, size_t *olen,
183  const unsigned char *input, unsigned char *output,
184  size_t output_max_len );
185 typedef int (*mbedtls_pk_rsa_alt_sign_func)( void *ctx,
186  int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
187  int mode, mbedtls_md_type_t md_alg, unsigned int hashlen,
188  const unsigned char *hash, unsigned char *sig );
189 typedef size_t (*mbedtls_pk_rsa_alt_key_len_func)( void *ctx );
190 #endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
191 
200 
208 
216 
217 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
218 
224 void mbedtls_pk_restart_init( mbedtls_pk_restart_ctx *ctx );
225 
232 void mbedtls_pk_restart_free( mbedtls_pk_restart_ctx *ctx );
233 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
234 
250 int mbedtls_pk_setup( mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info );
251 
252 #if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
253 
268 int mbedtls_pk_setup_rsa_alt( mbedtls_pk_context *ctx, void * key,
269  mbedtls_pk_rsa_alt_decrypt_func decrypt_func,
271  mbedtls_pk_rsa_alt_key_len_func key_len_func );
272 #endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
273 
281 size_t mbedtls_pk_get_bitlen( const mbedtls_pk_context *ctx );
282 
290 static inline size_t mbedtls_pk_get_len( const mbedtls_pk_context *ctx )
291 {
292  return( ( mbedtls_pk_get_bitlen( ctx ) + 7 ) / 8 );
293 }
294 
308 
334  const unsigned char *hash, size_t hash_len,
335  const unsigned char *sig, size_t sig_len );
336 
358  mbedtls_md_type_t md_alg,
359  const unsigned char *hash, size_t hash_len,
360  const unsigned char *sig, size_t sig_len,
361  mbedtls_pk_restart_ctx *rs_ctx );
362 
392 int mbedtls_pk_verify_ext( mbedtls_pk_type_t type, const void *options,
394  const unsigned char *hash, size_t hash_len,
395  const unsigned char *sig, size_t sig_len );
396 
427  const unsigned char *hash, size_t hash_len,
428  unsigned char *sig, size_t *sig_len,
429  int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
430 
459  mbedtls_md_type_t md_alg,
460  const unsigned char *hash, size_t hash_len,
461  unsigned char *sig, size_t *sig_len,
462  int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
463  mbedtls_pk_restart_ctx *rs_ctx );
464 
483  const unsigned char *input, size_t ilen,
484  unsigned char *output, size_t *olen, size_t osize,
485  int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
486 
504  const unsigned char *input, size_t ilen,
505  unsigned char *output, size_t *olen, size_t osize,
506  int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
507 
516 int mbedtls_pk_check_pair( const mbedtls_pk_context *pub, const mbedtls_pk_context *prv );
517 
527 
535 const char * mbedtls_pk_get_name( const mbedtls_pk_context *ctx );
536 
546 
547 #if defined(MBEDTLS_PK_PARSE_C)
548 
578  const unsigned char *key, size_t keylen,
579  const unsigned char *pwd, size_t pwdlen );
580 
604  const unsigned char *key, size_t keylen );
605 
606 #if defined(MBEDTLS_FS_IO)
607 
629  const char *path, const char *password );
630 
648 int mbedtls_pk_parse_public_keyfile( mbedtls_pk_context *ctx, const char *path );
649 #endif /* MBEDTLS_FS_IO */
650 #endif /* MBEDTLS_PK_PARSE_C */
651 
652 #if defined(MBEDTLS_PK_WRITE_C)
653 
666 int mbedtls_pk_write_key_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
667 
681 int mbedtls_pk_write_pubkey_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
682 
683 #if defined(MBEDTLS_PEM_WRITE_C)
684 
694 int mbedtls_pk_write_pubkey_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
695 
706 int mbedtls_pk_write_key_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
707 #endif /* MBEDTLS_PEM_WRITE_C */
708 #endif /* MBEDTLS_PK_WRITE_C */
709 
710 /*
711  * WARNING: Low-level functions. You probably do not want to use these unless
712  * you are certain you do ;)
713  */
714 
715 #if defined(MBEDTLS_PK_PARSE_C)
716 
726 int mbedtls_pk_parse_subpubkey( unsigned char **p, const unsigned char *end,
727  mbedtls_pk_context *pk );
728 #endif /* MBEDTLS_PK_PARSE_C */
729 
730 #if defined(MBEDTLS_PK_WRITE_C)
731 
741 int mbedtls_pk_write_pubkey( unsigned char **p, unsigned char *start,
742  const mbedtls_pk_context *key );
743 #endif /* MBEDTLS_PK_WRITE_C */
744 
745 /*
746  * Internal module functions. You probably do not want to use these unless you
747  * know you do.
748  */
749 #if defined(MBEDTLS_FS_IO)
750 int mbedtls_pk_load_file( const char *path, unsigned char **buf, size_t *n );
751 #endif
752 
753 #ifdef __cplusplus
754 }
755 #endif
756 
757 #endif /* MBEDTLS_PK_H */
int mbedtls_pk_write_pubkey_pem(mbedtls_pk_context *ctx, unsigned char *buf, size_t size)
Write a public key to a PEM string.
Options for RSASSA-PSS signature verification. See mbedtls_rsa_rsassa_pss_verify_ext() ...
Definition: pk.h:94
Public key container.
Definition: pk.h:132
int mbedtls_pk_setup_rsa_alt(mbedtls_pk_context *ctx, void *key, mbedtls_pk_rsa_alt_decrypt_func decrypt_func, mbedtls_pk_rsa_alt_sign_func sign_func, mbedtls_pk_rsa_alt_key_len_func key_len_func)
Initialize an RSA-alt context.
int mbedtls_pk_parse_subpubkey(unsigned char **p, const unsigned char *end, mbedtls_pk_context *pk)
Parse a SubjectPublicKeyInfo DER structure.
void mbedtls_pk_init(mbedtls_pk_context *ctx)
Initialize a mbedtls_pk_context (as NONE).
static mbedtls_rsa_context * mbedtls_pk_rsa(const mbedtls_pk_context pk)
Definition: pk.h:159
mbedtls_pk_debug_type
Types for interfacing with the debug module.
Definition: pk.h:104
int mbedtls_pk_sign_restartable(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, unsigned char *sig, size_t *sig_len, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng, mbedtls_pk_restart_ctx *rs_ctx)
Restartable version of mbedtls_pk_sign()
struct mbedtls_pk_rsassa_pss_options mbedtls_pk_rsassa_pss_options
Options for RSASSA-PSS signature verification. See mbedtls_rsa_rsassa_pss_verify_ext() ...
int mbedtls_pk_can_do(const mbedtls_pk_context *ctx, mbedtls_pk_type_t type)
Tell if a context can do the operation given by type.
int mbedtls_pk_write_pubkey_der(mbedtls_pk_context *ctx, unsigned char *buf, size_t size)
Write a public key to a SubjectPublicKeyInfo DER structure Note: data is written at the end of the bu...
int mbedtls_pk_write_pubkey(unsigned char **p, unsigned char *start, const mbedtls_pk_context *key)
Write a subjectPublicKey to ASN.1 data Note: function works backwards in data buffer.
This file provides an API for Elliptic Curves over GF(P) (ECP).
int mbedtls_pk_verify_ext(mbedtls_pk_type_t type, const void *options, mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, const unsigned char *sig, size_t sig_len)
Verify signature, with options. (Includes verification of the padding depending on type...
The ECP key-pair structure.
Definition: ecp.h:334
This file contains ECDSA definitions and functions.
const mbedtls_pk_info_t * pk_info
Definition: pk.h:134
int mbedtls_pk_encrypt(mbedtls_pk_context *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen, size_t osize, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
Encrypt message (including padding if relevant).
int mbedtls_pk_verify_restartable(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, const unsigned char *sig, size_t sig_len, mbedtls_pk_restart_ctx *rs_ctx)
Restartable version of mbedtls_pk_verify()
size_t mbedtls_pk_get_bitlen(const mbedtls_pk_context *ctx)
Get the size in bits of the underlying key.
mbedtls_pk_type_t
Public key types.
Definition: pk.h:80
Configuration options (set of defines)
void * value
Definition: pk.h:118
static size_t mbedtls_pk_get_len(const mbedtls_pk_context *ctx)
Get the length in bytes of the underlying key.
Definition: pk.h:290
int mbedtls_pk_sign(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, unsigned char *sig, size_t *sig_len, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
Make signature, including padding if relevant.
void mbedtls_pk_restart_ctx
Definition: pk.h:149
const char * name
Definition: pk.h:117
int mbedtls_pk_debug(const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *items)
Export debug information.
void * pk_ctx
Definition: pk.h:135
int mbedtls_pk_parse_public_key(mbedtls_pk_context *ctx, const unsigned char *key, size_t keylen)
Parse a public key in PEM or DER format.
int mbedtls_pk_parse_key(mbedtls_pk_context *ctx, const unsigned char *key, size_t keylen, const unsigned char *pwd, size_t pwdlen)
Parse a private key in PEM or DER format.
void mbedtls_pk_free(mbedtls_pk_context *ctx)
Free the components of a mbedtls_pk_context.
mbedtls_md_type_t mgf1_hash_id
Definition: pk.h:96
size_t(* mbedtls_pk_rsa_alt_key_len_func)(void *ctx)
Definition: pk.h:189
int mbedtls_pk_parse_keyfile(mbedtls_pk_context *ctx, const char *path, const char *password)
Load and parse a private key.
struct mbedtls_pk_info_t mbedtls_pk_info_t
Public key information and operations.
Definition: pk.h:127
This file contains the generic message-digest wrapper.
This file provides an API for the RSA public-key cryptosystem.
int(* mbedtls_pk_rsa_alt_decrypt_func)(void *ctx, int mode, size_t *olen, const unsigned char *input, unsigned char *output, size_t output_max_len)
Types for RSA-alt abstraction.
Definition: pk.h:182
int mbedtls_pk_verify(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, const unsigned char *sig, size_t sig_len)
Verify signature (including padding if relevant).
mbedtls_pk_type_t mbedtls_pk_get_type(const mbedtls_pk_context *ctx)
Get the key type.
int mbedtls_pk_write_key_pem(mbedtls_pk_context *ctx, unsigned char *buf, size_t size)
Write a private key to a PKCS#1 or SEC1 PEM string.
int(* mbedtls_pk_rsa_alt_sign_func)(void *ctx, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng, int mode, mbedtls_md_type_t md_alg, unsigned int hashlen, const unsigned char *hash, unsigned char *sig)
Definition: pk.h:185
int mbedtls_pk_write_key_der(mbedtls_pk_context *ctx, unsigned char *buf, size_t size)
Write a private key to a PKCS#1 or SEC1 DER structure Note: data is written at the end of the buffer!...
const char * mbedtls_pk_get_name(const mbedtls_pk_context *ctx)
Access the type name.
int mbedtls_pk_load_file(const char *path, unsigned char **buf, size_t *n)
static mbedtls_ecp_keypair * mbedtls_pk_ec(const mbedtls_pk_context pk)
Definition: pk.h:172
int mbedtls_pk_setup(mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info)
Initialize a PK context with the information given and allocates the type-specific PK subcontext...
struct mbedtls_pk_context mbedtls_pk_context
Public key container.
mbedtls_pk_debug_type type
Definition: pk.h:116
int mbedtls_pk_check_pair(const mbedtls_pk_context *pub, const mbedtls_pk_context *prv)
Check if a public-private pair of keys matches.
mbedtls_md_type_t
Supported message digests.
Definition: md.h:60
struct mbedtls_pk_debug_item mbedtls_pk_debug_item
Item to send to the debug module.
The RSA context structure.
Definition: rsa.h:102
Item to send to the debug module.
Definition: pk.h:114
int mbedtls_pk_parse_public_keyfile(mbedtls_pk_context *ctx, const char *path)
Load and parse a public key.
const mbedtls_pk_info_t * mbedtls_pk_info_from_type(mbedtls_pk_type_t pk_type)
Return information associated with the given PK type.
int mbedtls_pk_decrypt(mbedtls_pk_context *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen, size_t osize, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
Decrypt message (including padding if relevant).