mbed TLS v2.16.1
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 
423  const unsigned char *hash, size_t hash_len,
424  unsigned char *sig, size_t *sig_len,
425  int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
426 
451  mbedtls_md_type_t md_alg,
452  const unsigned char *hash, size_t hash_len,
453  unsigned char *sig, size_t *sig_len,
454  int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
455  mbedtls_pk_restart_ctx *rs_ctx );
456 
475  const unsigned char *input, size_t ilen,
476  unsigned char *output, size_t *olen, size_t osize,
477  int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
478 
496  const unsigned char *input, size_t ilen,
497  unsigned char *output, size_t *olen, size_t osize,
498  int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
499 
508 int mbedtls_pk_check_pair( const mbedtls_pk_context *pub, const mbedtls_pk_context *prv );
509 
519 
527 const char * mbedtls_pk_get_name( const mbedtls_pk_context *ctx );
528 
538 
539 #if defined(MBEDTLS_PK_PARSE_C)
540 
570  const unsigned char *key, size_t keylen,
571  const unsigned char *pwd, size_t pwdlen );
572 
596  const unsigned char *key, size_t keylen );
597 
598 #if defined(MBEDTLS_FS_IO)
599 
621  const char *path, const char *password );
622 
640 int mbedtls_pk_parse_public_keyfile( mbedtls_pk_context *ctx, const char *path );
641 #endif /* MBEDTLS_FS_IO */
642 #endif /* MBEDTLS_PK_PARSE_C */
643 
644 #if defined(MBEDTLS_PK_WRITE_C)
645 
658 int mbedtls_pk_write_key_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
659 
673 int mbedtls_pk_write_pubkey_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
674 
675 #if defined(MBEDTLS_PEM_WRITE_C)
676 
686 int mbedtls_pk_write_pubkey_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
687 
698 int mbedtls_pk_write_key_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
699 #endif /* MBEDTLS_PEM_WRITE_C */
700 #endif /* MBEDTLS_PK_WRITE_C */
701 
702 /*
703  * WARNING: Low-level functions. You probably do not want to use these unless
704  * you are certain you do ;)
705  */
706 
707 #if defined(MBEDTLS_PK_PARSE_C)
708 
718 int mbedtls_pk_parse_subpubkey( unsigned char **p, const unsigned char *end,
719  mbedtls_pk_context *pk );
720 #endif /* MBEDTLS_PK_PARSE_C */
721 
722 #if defined(MBEDTLS_PK_WRITE_C)
723 
733 int mbedtls_pk_write_pubkey( unsigned char **p, unsigned char *start,
734  const mbedtls_pk_context *key );
735 #endif /* MBEDTLS_PK_WRITE_C */
736 
737 /*
738  * Internal module functions. You probably do not want to use these unless you
739  * know you do.
740  */
741 #if defined(MBEDTLS_FS_IO)
742 int mbedtls_pk_load_file( const char *path, unsigned char **buf, size_t *n );
743 #endif
744 
745 #ifdef __cplusplus
746 }
747 #endif
748 
749 #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).