PolarSSL is now part of ARM Official announcement and rebranded as mbed TLS.

API Documentation (Doxygen generated)

These pages are generated with doxygen directly from the source code!

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: 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 
25 #ifndef MBEDTLS_PK_H
26 #define MBEDTLS_PK_H
27 
28 #if !defined(MBEDTLS_CONFIG_FILE)
29 #include "config.h"
30 #else
31 #include MBEDTLS_CONFIG_FILE
32 #endif
33 
34 #include "md.h"
35 
36 #if defined(MBEDTLS_RSA_C)
37 #include "rsa.h"
38 #endif
39 
40 #if defined(MBEDTLS_ECP_C)
41 #include "ecp.h"
42 #endif
43 
44 #if defined(MBEDTLS_ECDSA_C)
45 #include "ecdsa.h"
46 #endif
47 
48 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
49  !defined(inline) && !defined(__cplusplus)
50 #define inline __inline
51 #endif
52 
53 #define MBEDTLS_ERR_PK_ALLOC_FAILED -0x3F80
54 #define MBEDTLS_ERR_PK_TYPE_MISMATCH -0x3F00
55 #define MBEDTLS_ERR_PK_BAD_INPUT_DATA -0x3E80
56 #define MBEDTLS_ERR_PK_FILE_IO_ERROR -0x3E00
57 #define MBEDTLS_ERR_PK_KEY_INVALID_VERSION -0x3D80
58 #define MBEDTLS_ERR_PK_KEY_INVALID_FORMAT -0x3D00
59 #define MBEDTLS_ERR_PK_UNKNOWN_PK_ALG -0x3C80
60 #define MBEDTLS_ERR_PK_PASSWORD_REQUIRED -0x3C00
61 #define MBEDTLS_ERR_PK_PASSWORD_MISMATCH -0x3B80
62 #define MBEDTLS_ERR_PK_INVALID_PUBKEY -0x3B00
63 #define MBEDTLS_ERR_PK_INVALID_ALG -0x3A80
64 #define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE -0x3A00
65 #define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980
66 #define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH -0x3900
68 /* MBEDTLS_ERR_PK_HW_ACCEL_FAILED is deprecated and should not be used. */
69 #define MBEDTLS_ERR_PK_HW_ACCEL_FAILED -0x3880
71 #ifdef __cplusplus
72 extern "C" {
73 #endif
74 
78 typedef enum {
87 
93 {
96 
98 
102 typedef enum
103 {
108 
112 typedef struct mbedtls_pk_debug_item
113 {
115  const char *name;
116  void *value;
118 
120 #define MBEDTLS_PK_DEBUG_MAX_ITEMS 3
121 
126 
130 typedef struct mbedtls_pk_context
131 {
133  void * pk_ctx;
135 
136 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
137 
140 typedef struct
141 {
142  const mbedtls_pk_info_t * pk_info;
143  void * rs_ctx;
145 #else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
146 /* Now we can declare functions that take a pointer to that */
148 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
149 
150 #if defined(MBEDTLS_RSA_C)
151 
158 {
159  return( (mbedtls_rsa_context *) (pk).pk_ctx );
160 }
161 #endif /* MBEDTLS_RSA_C */
162 
163 #if defined(MBEDTLS_ECP_C)
164 
171 {
172  return( (mbedtls_ecp_keypair *) (pk).pk_ctx );
173 }
174 #endif /* MBEDTLS_ECP_C */
175 
176 #if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
177 
180 typedef int (*mbedtls_pk_rsa_alt_decrypt_func)( void *ctx, int mode, size_t *olen,
181  const unsigned char *input, unsigned char *output,
182  size_t output_max_len );
183 typedef int (*mbedtls_pk_rsa_alt_sign_func)( void *ctx,
184  int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
185  int mode, mbedtls_md_type_t md_alg, unsigned int hashlen,
186  const unsigned char *hash, unsigned char *sig );
187 typedef size_t (*mbedtls_pk_rsa_alt_key_len_func)( void *ctx );
188 #endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
189 
198 
206 
214 
215 #if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
216 
222 void mbedtls_pk_restart_init( mbedtls_pk_restart_ctx *ctx );
223 
230 void mbedtls_pk_restart_free( mbedtls_pk_restart_ctx *ctx );
231 #endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
232 
248 int mbedtls_pk_setup( mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info );
249 
250 #if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
251 
266 int mbedtls_pk_setup_rsa_alt( mbedtls_pk_context *ctx, void * key,
267  mbedtls_pk_rsa_alt_decrypt_func decrypt_func,
269  mbedtls_pk_rsa_alt_key_len_func key_len_func );
270 #endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
271 
279 size_t mbedtls_pk_get_bitlen( const mbedtls_pk_context *ctx );
280 
288 static inline size_t mbedtls_pk_get_len( const mbedtls_pk_context *ctx )
289 {
290  return( ( mbedtls_pk_get_bitlen( ctx ) + 7 ) / 8 );
291 }
292 
306 
332  const unsigned char *hash, size_t hash_len,
333  const unsigned char *sig, size_t sig_len );
334 
356  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  mbedtls_pk_restart_ctx *rs_ctx );
360 
390 int mbedtls_pk_verify_ext( mbedtls_pk_type_t type, const void *options,
392  const unsigned char *hash, size_t hash_len,
393  const unsigned char *sig, size_t sig_len );
394 
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 
449  mbedtls_md_type_t md_alg,
450  const unsigned char *hash, size_t hash_len,
451  unsigned char *sig, size_t *sig_len,
452  int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
453  mbedtls_pk_restart_ctx *rs_ctx );
454 
473  const unsigned char *input, size_t ilen,
474  unsigned char *output, size_t *olen, size_t osize,
475  int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
476 
494  const unsigned char *input, size_t ilen,
495  unsigned char *output, size_t *olen, size_t osize,
496  int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
497 
506 int mbedtls_pk_check_pair( const mbedtls_pk_context *pub, const mbedtls_pk_context *prv );
507 
517 
525 const char * mbedtls_pk_get_name( const mbedtls_pk_context *ctx );
526 
536 
537 #if defined(MBEDTLS_PK_PARSE_C)
538 
568  const unsigned char *key, size_t keylen,
569  const unsigned char *pwd, size_t pwdlen );
570 
594  const unsigned char *key, size_t keylen );
595 
596 #if defined(MBEDTLS_FS_IO)
597 
619  const char *path, const char *password );
620 
638 int mbedtls_pk_parse_public_keyfile( mbedtls_pk_context *ctx, const char *path );
639 #endif /* MBEDTLS_FS_IO */
640 #endif /* MBEDTLS_PK_PARSE_C */
641 
642 #if defined(MBEDTLS_PK_WRITE_C)
643 
656 int mbedtls_pk_write_key_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
657 
671 int mbedtls_pk_write_pubkey_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
672 
673 #if defined(MBEDTLS_PEM_WRITE_C)
674 
684 int mbedtls_pk_write_pubkey_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
685 
696 int mbedtls_pk_write_key_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
697 #endif /* MBEDTLS_PEM_WRITE_C */
698 #endif /* MBEDTLS_PK_WRITE_C */
699 
700 /*
701  * WARNING: Low-level functions. You probably do not want to use these unless
702  * you are certain you do ;)
703  */
704 
705 #if defined(MBEDTLS_PK_PARSE_C)
706 
716 int mbedtls_pk_parse_subpubkey( unsigned char **p, const unsigned char *end,
717  mbedtls_pk_context *pk );
718 #endif /* MBEDTLS_PK_PARSE_C */
719 
720 #if defined(MBEDTLS_PK_WRITE_C)
721 
731 int mbedtls_pk_write_pubkey( unsigned char **p, unsigned char *start,
732  const mbedtls_pk_context *key );
733 #endif /* MBEDTLS_PK_WRITE_C */
734 
735 /*
736  * Internal module functions. You probably do not want to use these unless you
737  * know you do.
738  */
739 #if defined(MBEDTLS_FS_IO)
740 int mbedtls_pk_load_file( const char *path, unsigned char **buf, size_t *n );
741 #endif
742 
743 #ifdef __cplusplus
744 }
745 #endif
746 
747 #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.
Definition: pk.h:92
Public key container.
Definition: pk.h:130
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)
Quick access to an RSA context inside a PK context.
Definition: pk.h:157
mbedtls_pk_debug_type
Types for interfacing with the debug module.
Definition: pk.h:102
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.
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.
The ECP key-pair structure.
Definition: ecp.h:332
This file contains ECDSA definitions and functions.
const mbedtls_pk_info_t * pk_info
Public key information.
Definition: pk.h:132
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:78
Configuration options (set of defines)
void * value
Definition: pk.h:116
static size_t mbedtls_pk_get_len(const mbedtls_pk_context *ctx)
Get the length in bytes of the underlying key.
Definition: pk.h:288
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:147
const char * name
Definition: pk.h:115
int mbedtls_pk_debug(const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *items)
Export debug information.
void * pk_ctx
Underlying public key context.
Definition: pk.h:133
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:94
size_t(* mbedtls_pk_rsa_alt_key_len_func)(void *ctx)
Definition: pk.h:187
int mbedtls_pk_parse_keyfile(mbedtls_pk_context *ctx, const char *path, const char *password)
Load and parse a private key.
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:180
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:183
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)
Quick access to an EC context inside a PK context.
Definition: pk.h:170
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:114
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:58
struct mbedtls_pk_debug_item mbedtls_pk_debug_item
Item to send to the debug module.
The RSA context structure.
Definition: rsa.h:100
Item to send to the debug module.
Definition: pk.h:112
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).