blob: 476bce15f64b6bb604d2b4c6956f3ca666b8d1f7 [file] [log] [blame]
Paul Bakkered27a042013-04-18 22:46:23 +02001/**
2 * \file pk.h
3 *
4 * \brief Public Key abstraction layer
Darryl Greena40a1012018-01-05 15:33:17 +00005 */
6/*
Manuel Pégourié-Gonnard6fb81872015-07-27 11:11:48 +02007 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
Manuel Pégourié-Gonnard37ff1402015-09-04 14:21:07 +02008 * 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.
Paul Bakkered27a042013-04-18 22:46:23 +020021 *
Manuel Pégourié-Gonnardfe446432015-03-06 13:17:10 +000022 * This file is part of mbed TLS (https://tls.mbed.org)
Paul Bakkered27a042013-04-18 22:46:23 +020023 */
Manuel Pégourié-Gonnardd73b3c12013-08-12 17:06:05 +020024
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020025#ifndef MBEDTLS_PK_H
26#define MBEDTLS_PK_H
Paul Bakkered27a042013-04-18 22:46:23 +020027
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020028#if !defined(MBEDTLS_CONFIG_FILE)
Manuel Pégourié-Gonnard244569f2013-07-10 09:46:30 +020029#include "config.h"
Manuel Pégourié-Gonnardcef4ad22014-04-29 12:39:06 +020030#else
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020031#include MBEDTLS_CONFIG_FILE
Manuel Pégourié-Gonnardcef4ad22014-04-29 12:39:06 +020032#endif
Manuel Pégourié-Gonnard244569f2013-07-10 09:46:30 +020033
Manuel Pégourié-Gonnardf73da022013-08-17 14:36:32 +020034#include "md.h"
35
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020036#if defined(MBEDTLS_RSA_C)
Manuel Pégourié-Gonnard244569f2013-07-10 09:46:30 +020037#include "rsa.h"
38#endif
39
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020040#if defined(MBEDTLS_ECP_C)
Manuel Pégourié-Gonnardd73b3c12013-08-12 17:06:05 +020041#include "ecp.h"
42#endif
43
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020044#if defined(MBEDTLS_ECDSA_C)
Manuel Pégourié-Gonnard211a64c2013-08-09 15:04:26 +020045#include "ecdsa.h"
46#endif
47
Jarno Lamsab1760922019-04-18 15:58:34 +030048#if defined(MBEDTLS_USE_TINYCRYPT)
Hanno Becker496b83f2019-08-20 13:33:49 +010049#include "tinycrypt/ecc.h"
Jarno Lamsab1760922019-04-18 15:58:34 +030050#endif
51
Manuel Pégourié-Gonnard2ac9c602015-10-05 16:18:23 +010052#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
53 !defined(inline) && !defined(__cplusplus)
54#define inline __inline
55#endif
56
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +020057#define MBEDTLS_ERR_PK_ALLOC_FAILED -0x3F80 /**< Memory allocation failed. */
Manuel Pégourié-Gonnardeed55a42015-04-09 17:31:59 +020058#define MBEDTLS_ERR_PK_TYPE_MISMATCH -0x3F00 /**< Type mismatch, eg attempt to encrypt with an ECDSA key */
59#define MBEDTLS_ERR_PK_BAD_INPUT_DATA -0x3E80 /**< Bad input parameters to function. */
60#define MBEDTLS_ERR_PK_FILE_IO_ERROR -0x3E00 /**< Read/write of file failed. */
61#define MBEDTLS_ERR_PK_KEY_INVALID_VERSION -0x3D80 /**< Unsupported key version */
62#define MBEDTLS_ERR_PK_KEY_INVALID_FORMAT -0x3D00 /**< Invalid key tag or value. */
63#define MBEDTLS_ERR_PK_UNKNOWN_PK_ALG -0x3C80 /**< Key algorithm is unsupported (only RSA and EC are supported). */
64#define MBEDTLS_ERR_PK_PASSWORD_REQUIRED -0x3C00 /**< Private key password can't be empty. */
65#define MBEDTLS_ERR_PK_PASSWORD_MISMATCH -0x3B80 /**< Given private key password does not allow for correct decryption. */
66#define MBEDTLS_ERR_PK_INVALID_PUBKEY -0x3B00 /**< The pubkey tag or value is invalid (only RSA and EC are supported). */
67#define MBEDTLS_ERR_PK_INVALID_ALG -0x3A80 /**< The algorithm tag or value is invalid. */
68#define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE -0x3A00 /**< Elliptic curve is unsupported (only NIST curves are supported). */
69#define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980 /**< Unavailable feature, e.g. RSA disabled for RSA key. */
Gilles Peskine5114d3e2018-03-30 07:12:15 +020070#define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH -0x3900 /**< The buffer contains a valid signature followed by more data. */
Ron Eldor9924bdc2018-10-04 10:59:13 +030071
72/* MBEDTLS_ERR_PK_HW_ACCEL_FAILED is deprecated and should not be used. */
Gilles Peskine7ecab3d2018-01-26 17:56:38 +010073#define MBEDTLS_ERR_PK_HW_ACCEL_FAILED -0x3880 /**< PK hardware accelerator failed. */
Paul Bakker1a7550a2013-09-15 13:01:22 +020074
Paul Bakkered27a042013-04-18 22:46:23 +020075#ifdef __cplusplus
76extern "C" {
77#endif
78
79/**
80 * \brief Public key types
81 */
82typedef enum {
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020083 MBEDTLS_PK_NONE=0,
84 MBEDTLS_PK_RSA,
85 MBEDTLS_PK_ECKEY,
86 MBEDTLS_PK_ECKEY_DH,
87 MBEDTLS_PK_ECDSA,
88 MBEDTLS_PK_RSA_ALT,
89 MBEDTLS_PK_RSASSA_PSS,
90} mbedtls_pk_type_t;
Paul Bakkered27a042013-04-18 22:46:23 +020091
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +020092/**
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +020093 * \brief Options for RSASSA-PSS signature verification.
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020094 * See \c mbedtls_rsa_rsassa_pss_verify_ext()
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +020095 */
Dawid Drozd428cc522018-07-24 10:02:47 +020096typedef struct mbedtls_pk_rsassa_pss_options
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +020097{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020098 mbedtls_md_type_t mgf1_hash_id;
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +020099 int expected_salt_len;
100
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200101} mbedtls_pk_rsassa_pss_options;
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200102
103/**
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200104 * \brief Types for interfacing with the debug module
105 */
106typedef enum
107{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200108 MBEDTLS_PK_DEBUG_NONE = 0,
109 MBEDTLS_PK_DEBUG_MPI,
110 MBEDTLS_PK_DEBUG_ECP,
111} mbedtls_pk_debug_type;
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200112
113/**
114 * \brief Item to send to the debug module
115 */
Dawid Drozd428cc522018-07-24 10:02:47 +0200116typedef struct mbedtls_pk_debug_item
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200117{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200118 mbedtls_pk_debug_type type;
Paul Bakkerfcc17212013-10-11 09:36:52 +0200119 const char *name;
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200120 void *value;
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200121} mbedtls_pk_debug_item;
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200122
123/** Maximum number of item send for debugging, plus 1 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200124#define MBEDTLS_PK_DEBUG_MAX_ITEMS 3
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200125
126/**
Manuel Pégourié-Gonnard3fb5c5e2013-08-14 18:26:41 +0200127 * \brief Public key information and operations
Manuel Pégourié-Gonnardd73b3c12013-08-12 17:06:05 +0200128 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200129typedef struct mbedtls_pk_info_t mbedtls_pk_info_t;
Manuel Pégourié-Gonnard020d9ba2019-09-19 10:45:14 +0200130typedef const mbedtls_pk_info_t *mbedtls_pk_handle_t;
131#define MBEDTLS_PK_INVALID_HANDLE ( (mbedtls_pk_handle_t) NULL )
Manuel Pégourié-Gonnardd73b3c12013-08-12 17:06:05 +0200132
133/**
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200134 * \brief Public key container
135 */
Dawid Drozd428cc522018-07-24 10:02:47 +0200136typedef struct mbedtls_pk_context
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200137{
Manuel Pégourié-Gonnard020d9ba2019-09-19 10:45:14 +0200138 mbedtls_pk_handle_t pk_info; /**< Public key information */
Manuel Pégourié-Gonnarda79efde2015-04-09 10:58:56 +0200139 void * pk_ctx; /**< Underlying public key context */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200140} mbedtls_pk_context;
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200141
Jarno Lamsab1760922019-04-18 15:58:34 +0300142#if defined(MBEDTLS_USE_TINYCRYPT)
143typedef struct
144{
145 uint8_t private_key[NUM_ECC_BYTES];
146 uint8_t public_key[2*NUM_ECC_BYTES];
147} mbedtls_uecc_keypair;
148#endif
149
Manuel Pégourié-Gonnardaaa98142017-08-18 17:30:37 +0200150#if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200151/**
152 * \brief Context for resuming operations
153 */
154typedef struct
155{
Manuel Pégourié-Gonnard020d9ba2019-09-19 10:45:14 +0200156 mbedtls_pk_handle_t pk_info; /**< Public key information */
Manuel Pégourié-Gonnard0bbc66c2017-08-18 16:22:06 +0200157 void * rs_ctx; /**< Underlying restart context */
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200158} mbedtls_pk_restart_ctx;
Manuel Pégourié-Gonnardaaa98142017-08-18 17:30:37 +0200159#else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200160/* Now we can declare functions that take a pointer to that */
161typedef void mbedtls_pk_restart_ctx;
Manuel Pégourié-Gonnardaaa98142017-08-18 17:30:37 +0200162#endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200163
Manuel Pégourié-Gonnarda79efde2015-04-09 10:58:56 +0200164#if defined(MBEDTLS_RSA_C)
165/**
166 * Quick access to an RSA context inside a PK context.
167 *
168 * \warning You must make sure the PK context actually holds an RSA context
169 * before using this function!
170 */
171static inline mbedtls_rsa_context *mbedtls_pk_rsa( const mbedtls_pk_context pk )
172{
173 return( (mbedtls_rsa_context *) (pk).pk_ctx );
174}
175#endif /* MBEDTLS_RSA_C */
176
Jarno Lamsa9c9e77a2019-04-18 16:13:19 +0300177#if defined(MBEDTLS_USE_TINYCRYPT)
Hanno Beckerda779712019-08-21 13:22:59 +0100178static inline mbedtls_uecc_keypair *mbedtls_pk_uecc( const mbedtls_pk_context pk )
Jarno Lamsa9c9e77a2019-04-18 16:13:19 +0300179{
180 return( (mbedtls_uecc_keypair *) (pk).pk_ctx );
181}
182#endif
183
Manuel Pégourié-Gonnarda79efde2015-04-09 10:58:56 +0200184#if defined(MBEDTLS_ECP_C)
185/**
186 * Quick access to an EC context inside a PK context.
187 *
188 * \warning You must make sure the PK context actually holds an EC context
189 * before using this function!
190 */
191static inline mbedtls_ecp_keypair *mbedtls_pk_ec( const mbedtls_pk_context pk )
192{
193 return( (mbedtls_ecp_keypair *) (pk).pk_ctx );
194}
195#endif /* MBEDTLS_ECP_C */
196
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200197#if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200198/**
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200199 * \brief Types for RSA-alt abstraction
200 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200201typedef int (*mbedtls_pk_rsa_alt_decrypt_func)( void *ctx, int mode, size_t *olen,
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200202 const unsigned char *input, unsigned char *output,
203 size_t output_max_len );
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200204typedef int (*mbedtls_pk_rsa_alt_sign_func)( void *ctx,
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200205 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200206 int mode, mbedtls_md_type_t md_alg, unsigned int hashlen,
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200207 const unsigned char *hash, unsigned char *sig );
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200208typedef size_t (*mbedtls_pk_rsa_alt_key_len_func)( void *ctx );
209#endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200210
211/**
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200212 * \brief Return information associated with the given PK type
213 *
Paul Bakkerdcbfdcc2013-09-10 16:16:50 +0200214 * \param pk_type PK type to search for.
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200215 *
216 * \return The PK info associated with the type or NULL if not found.
217 */
Manuel Pégourié-Gonnard020d9ba2019-09-19 10:45:14 +0200218mbedtls_pk_handle_t mbedtls_pk_info_from_type( mbedtls_pk_type_t pk_type );
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200219
220/**
Gilles Peskinea310b412018-12-19 00:51:21 +0100221 * \brief Initialize a #mbedtls_pk_context (as NONE).
222 *
223 * \param ctx The context to initialize.
224 * This must not be \c NULL.
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200225 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200226void mbedtls_pk_init( mbedtls_pk_context *ctx );
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200227
228/**
Gilles Peskinea310b412018-12-19 00:51:21 +0100229 * \brief Free the components of a #mbedtls_pk_context.
230 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100231 * \param ctx The context to clear. It must have been initialized.
Gilles Peskinea310b412018-12-19 00:51:21 +0100232 * If this is \c NULL, this function does nothing.
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200233 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200234void mbedtls_pk_free( mbedtls_pk_context *ctx );
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200235
Manuel Pégourié-Gonnardaaa98142017-08-18 17:30:37 +0200236#if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200237/**
238 * \brief Initialize a restart context
Gilles Peskinea310b412018-12-19 00:51:21 +0100239 *
240 * \param ctx The context to initialize.
241 * This must not be \c NULL.
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200242 */
243void mbedtls_pk_restart_init( mbedtls_pk_restart_ctx *ctx );
244
245/**
246 * \brief Free the components of a restart context
Gilles Peskinea310b412018-12-19 00:51:21 +0100247 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100248 * \param ctx The context to clear. It must have been initialized.
Gilles Peskinea310b412018-12-19 00:51:21 +0100249 * If this is \c NULL, this function does nothing.
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200250 */
251void mbedtls_pk_restart_free( mbedtls_pk_restart_ctx *ctx );
Manuel Pégourié-Gonnardaaa98142017-08-18 17:30:37 +0200252#endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200253
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200254/**
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200255 * \brief Initialize a PK context with the information given
256 * and allocates the type-specific PK subcontext.
257 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100258 * \param ctx Context to initialize. It must not have been set
259 * up yet (type #MBEDTLS_PK_NONE).
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200260 * \param info Information to use
261 *
262 * \return 0 on success,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200263 * MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input,
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200264 * MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200265 *
Paul Bakker42099c32014-01-27 11:45:49 +0100266 * \note For contexts holding an RSA-alt key, use
Manuel Pégourié-Gonnardd9e6a3a2015-05-14 19:41:36 +0200267 * \c mbedtls_pk_setup_rsa_alt() instead.
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200268 */
Manuel Pégourié-Gonnard020d9ba2019-09-19 10:45:14 +0200269int mbedtls_pk_setup( mbedtls_pk_context *ctx, mbedtls_pk_handle_t info );
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200270
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200271#if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200272/**
Paul Bakker4fc090a2013-09-18 15:43:25 +0200273 * \brief Initialize an RSA-alt context
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200274 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100275 * \param ctx Context to initialize. It must not have been set
276 * up yet (type #MBEDTLS_PK_NONE).
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200277 * \param key RSA key pointer
278 * \param decrypt_func Decryption function
279 * \param sign_func Signing function
Manuel Pégourié-Gonnard01488752014-04-03 22:09:18 +0200280 * \param key_len_func Function returning key length in bytes
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200281 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200282 * \return 0 on success, or MBEDTLS_ERR_PK_BAD_INPUT_DATA if the
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200283 * context wasn't already initialized as RSA_ALT.
284 *
Manuel Pégourié-Gonnardd9e6a3a2015-05-14 19:41:36 +0200285 * \note This function replaces \c mbedtls_pk_setup() for RSA-alt.
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200286 */
Manuel Pégourié-Gonnardd9e6a3a2015-05-14 19:41:36 +0200287int mbedtls_pk_setup_rsa_alt( mbedtls_pk_context *ctx, void * key,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200288 mbedtls_pk_rsa_alt_decrypt_func decrypt_func,
289 mbedtls_pk_rsa_alt_sign_func sign_func,
290 mbedtls_pk_rsa_alt_key_len_func key_len_func );
291#endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200292
293/**
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200294 * \brief Get the size in bits of the underlying key
295 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100296 * \param ctx The context to query. It must have been initialized.
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200297 *
298 * \return Key size in bits, or 0 on error
299 */
Manuel Pégourié-Gonnard097c7bb2015-06-18 16:43:38 +0200300size_t mbedtls_pk_get_bitlen( const mbedtls_pk_context *ctx );
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200301
302/**
Manuel Pégourié-Gonnard0d420492013-08-21 16:14:26 +0200303 * \brief Get the length in bytes of the underlying key
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100304 *
305 * \param ctx The context to query. It must have been initialized.
Manuel Pégourié-Gonnard0d420492013-08-21 16:14:26 +0200306 *
Paul Bakker4fc090a2013-09-18 15:43:25 +0200307 * \return Key length in bytes, or 0 on error
Manuel Pégourié-Gonnard0d420492013-08-21 16:14:26 +0200308 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200309static inline size_t mbedtls_pk_get_len( const mbedtls_pk_context *ctx )
Manuel Pégourié-Gonnard0d420492013-08-21 16:14:26 +0200310{
Manuel Pégourié-Gonnard097c7bb2015-06-18 16:43:38 +0200311 return( ( mbedtls_pk_get_bitlen( ctx ) + 7 ) / 8 );
Manuel Pégourié-Gonnard0d420492013-08-21 16:14:26 +0200312}
313
314/**
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200315 * \brief Tell if a context can do the operation given by type
316 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100317 * \param ctx The context to query. It must have been initialized.
318 * \param type The desired type.
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200319 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100320 * \return 1 if the context can do operations on the given type.
321 * \return 0 if the context cannot do the operations on the given
322 * type. This is always the case for a context that has
323 * been initialized but not set up, or that has been
324 * cleared with mbedtls_pk_free().
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200325 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200326int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type );
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200327
328/**
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200329 * \brief Verify signature (including padding if relevant).
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200330 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100331 * \param ctx The PK context to use. It must have been set up.
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200332 * \param md_alg Hash algorithm used (see notes)
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200333 * \param hash Hash of the message to sign
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200334 * \param hash_len Hash length or 0 (see notes)
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200335 * \param sig Signature to verify
336 * \param sig_len Signature length
337 *
338 * \return 0 on success (signature is valid),
Gilles Peskine5114d3e2018-03-30 07:12:15 +0200339 * #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid
340 * signature in sig but its length is less than \p siglen,
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200341 * or a specific error code.
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200342 *
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200343 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200344 * Use \c mbedtls_pk_verify_ext( MBEDTLS_PK_RSASSA_PSS, ... )
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200345 * to verify RSASSA_PSS signatures.
346 *
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200347 * \note If hash_len is 0, then the length associated with md_alg
348 * is used instead, or an error returned if it is invalid.
349 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200350 * \note md_alg may be MBEDTLS_MD_NONE, only if hash_len != 0
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200351 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200352int mbedtls_pk_verify( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
Manuel Pégourié-Gonnardf73da022013-08-17 14:36:32 +0200353 const unsigned char *hash, size_t hash_len,
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200354 const unsigned char *sig, size_t sig_len );
355
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200356/**
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200357 * \brief Restartable version of \c mbedtls_pk_verify()
358 *
359 * \note Performs the same job as \c mbedtls_pk_verify(), but can
360 * return early and restart according to the limit set with
361 * \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
362 * operations. For RSA, same as \c mbedtls_pk_verify().
363 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100364 * \param ctx The PK context to use. It must have been set up.
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200365 * \param md_alg Hash algorithm used (see notes)
366 * \param hash Hash of the message to sign
367 * \param hash_len Hash length or 0 (see notes)
368 * \param sig Signature to verify
369 * \param sig_len Signature length
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200370 * \param rs_ctx Restart context (NULL to disable restart)
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200371 *
372 * \return See \c mbedtls_pk_verify(), or
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200373 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200374 * operations was reached: see \c mbedtls_ecp_set_max_ops().
375 */
376int mbedtls_pk_verify_restartable( mbedtls_pk_context *ctx,
377 mbedtls_md_type_t md_alg,
378 const unsigned char *hash, size_t hash_len,
379 const unsigned char *sig, size_t sig_len,
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200380 mbedtls_pk_restart_ctx *rs_ctx );
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200381
382/**
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200383 * \brief Verify signature, with options.
384 * (Includes verification of the padding depending on type.)
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200385 *
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200386 * \param type Signature type (inc. possible padding type) to verify
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200387 * \param options Pointer to type-specific options, or NULL
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100388 * \param ctx The PK context to use. It must have been set up.
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200389 * \param md_alg Hash algorithm used (see notes)
390 * \param hash Hash of the message to sign
391 * \param hash_len Hash length or 0 (see notes)
392 * \param sig Signature to verify
393 * \param sig_len Signature length
394 *
395 * \return 0 on success (signature is valid),
Gilles Peskine5114d3e2018-03-30 07:12:15 +0200396 * #MBEDTLS_ERR_PK_TYPE_MISMATCH if the PK context can't be
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200397 * used for this type of signatures,
Gilles Peskine5114d3e2018-03-30 07:12:15 +0200398 * #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid
399 * signature in sig but its length is less than \p siglen,
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200400 * or a specific error code.
401 *
402 * \note If hash_len is 0, then the length associated with md_alg
403 * is used instead, or an error returned if it is invalid.
404 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200405 * \note md_alg may be MBEDTLS_MD_NONE, only if hash_len != 0
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200406 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200407 * \note If type is MBEDTLS_PK_RSASSA_PSS, then options must point
408 * to a mbedtls_pk_rsassa_pss_options structure,
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200409 * otherwise it must be NULL.
410 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200411int mbedtls_pk_verify_ext( mbedtls_pk_type_t type, const void *options,
412 mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200413 const unsigned char *hash, size_t hash_len,
414 const unsigned char *sig, size_t sig_len );
415
416/**
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200417 * \brief Make signature, including padding if relevant.
Manuel Pégourié-Gonnard8df27692013-08-21 10:34:38 +0200418 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100419 * \param ctx The PK context to use. It must have been set up
420 * with a private key.
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200421 * \param md_alg Hash algorithm used (see notes)
Manuel Pégourié-Gonnard8df27692013-08-21 10:34:38 +0200422 * \param hash Hash of the message to sign
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200423 * \param hash_len Hash length or 0 (see notes)
Manuel Pégourié-Gonnard8df27692013-08-21 10:34:38 +0200424 * \param sig Place to write the signature
425 * \param sig_len Number of bytes written
426 * \param f_rng RNG function
427 * \param p_rng RNG parameter
428 *
429 * \return 0 on success, or a specific error code.
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200430 *
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200431 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
432 * There is no interface in the PK module to make RSASSA-PSS
433 * signatures yet.
434 *
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200435 * \note If hash_len is 0, then the length associated with md_alg
436 * is used instead, or an error returned if it is invalid.
437 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200438 * \note For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0.
439 * For ECDSA, md_alg may never be MBEDTLS_MD_NONE.
Manuel Pégourié-Gonnard8df27692013-08-21 10:34:38 +0200440 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200441int mbedtls_pk_sign( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
Manuel Pégourié-Gonnard8df27692013-08-21 10:34:38 +0200442 const unsigned char *hash, size_t hash_len,
443 unsigned char *sig, size_t *sig_len,
444 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
445
446/**
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200447 * \brief Restartable version of \c mbedtls_pk_sign()
448 *
449 * \note Performs the same job as \c mbedtls_pk_sign(), but can
450 * return early and restart according to the limit set with
451 * \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
452 * operations. For RSA, same as \c mbedtls_pk_sign().
453 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100454 * \param ctx The PK context to use. It must have been set up
455 * with a private key.
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200456 * \param md_alg Hash algorithm used (see notes)
457 * \param hash Hash of the message to sign
458 * \param hash_len Hash length or 0 (see notes)
459 * \param sig Place to write the signature
460 * \param sig_len Number of bytes written
461 * \param f_rng RNG function
462 * \param p_rng RNG parameter
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200463 * \param rs_ctx Restart context (NULL to disable restart)
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200464 *
465 * \return See \c mbedtls_pk_sign(), or
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200466 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200467 * operations was reached: see \c mbedtls_ecp_set_max_ops().
468 */
469int mbedtls_pk_sign_restartable( mbedtls_pk_context *ctx,
470 mbedtls_md_type_t md_alg,
471 const unsigned char *hash, size_t hash_len,
472 unsigned char *sig, size_t *sig_len,
473 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200474 mbedtls_pk_restart_ctx *rs_ctx );
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200475
476/**
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200477 * \brief Decrypt message (including padding if relevant).
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200478 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100479 * \param ctx The PK context to use. It must have been set up
480 * with a private key.
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200481 * \param input Input to decrypt
482 * \param ilen Input size
483 * \param output Decrypted output
Paul Bakker4fc090a2013-09-18 15:43:25 +0200484 * \param olen Decrypted message length
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200485 * \param osize Size of the output buffer
Paul Bakkerdcbfdcc2013-09-10 16:16:50 +0200486 * \param f_rng RNG function
487 * \param p_rng RNG parameter
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200488 *
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200489 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
490 *
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200491 * \return 0 on success, or a specific error code.
492 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200493int mbedtls_pk_decrypt( mbedtls_pk_context *ctx,
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200494 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
498/**
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200499 * \brief Encrypt message (including padding if relevant).
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200500 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100501 * \param ctx The PK context to use. It must have been set up.
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200502 * \param input Message to encrypt
503 * \param ilen Message size
504 * \param output Encrypted output
505 * \param olen Encrypted output length
506 * \param osize Size of the output buffer
Paul Bakkerdcbfdcc2013-09-10 16:16:50 +0200507 * \param f_rng RNG function
508 * \param p_rng RNG parameter
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200509 *
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200510 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
511 *
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200512 * \return 0 on success, or a specific error code.
513 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200514int mbedtls_pk_encrypt( mbedtls_pk_context *ctx,
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200515 const unsigned char *input, size_t ilen,
516 unsigned char *output, size_t *olen, size_t osize,
517 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
518
519/**
Manuel Pégourié-Gonnard70bdadf2014-11-06 16:51:20 +0100520 * \brief Check if a public-private pair of keys matches.
521 *
522 * \param pub Context holding a public key.
523 * \param prv Context holding a private (and public) key.
524 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200525 * \return 0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
Manuel Pégourié-Gonnard70bdadf2014-11-06 16:51:20 +0100526 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200527int mbedtls_pk_check_pair( const mbedtls_pk_context *pub, const mbedtls_pk_context *prv );
Manuel Pégourié-Gonnard70bdadf2014-11-06 16:51:20 +0100528
529/**
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200530 * \brief Export debug information
531 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100532 * \param ctx The PK context to use. It must have been initialized.
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200533 * \param items Place to write debug items
534 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200535 * \return 0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200536 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200537int mbedtls_pk_debug( const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *items );
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200538
Manuel Pégourié-Gonnard3fb5c5e2013-08-14 18:26:41 +0200539/**
540 * \brief Access the type name
541 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100542 * \param ctx The PK context to use. It must have been initialized.
Manuel Pégourié-Gonnard3fb5c5e2013-08-14 18:26:41 +0200543 *
544 * \return Type name on success, or "invalid PK"
545 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200546const char * mbedtls_pk_get_name( const mbedtls_pk_context *ctx );
Manuel Pégourié-Gonnard3fb5c5e2013-08-14 18:26:41 +0200547
Manuel Pégourié-Gonnard8053da42013-09-11 22:28:30 +0200548/**
Paul Bakker4fc090a2013-09-18 15:43:25 +0200549 * \brief Get the key type
Manuel Pégourié-Gonnard8053da42013-09-11 22:28:30 +0200550 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100551 * \param ctx The PK context to use. It must have been initialized.
Manuel Pégourié-Gonnard8053da42013-09-11 22:28:30 +0200552 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100553 * \return Type on success.
554 * \return #MBEDTLS_PK_NONE for a context that has not been set up.
Manuel Pégourié-Gonnard8053da42013-09-11 22:28:30 +0200555 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200556mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx );
Manuel Pégourié-Gonnard8053da42013-09-11 22:28:30 +0200557
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200558#if defined(MBEDTLS_PK_PARSE_C)
Paul Bakkerff3a5182013-09-16 22:42:19 +0200559/** \ingroup pk_module */
Paul Bakker1a7550a2013-09-15 13:01:22 +0200560/**
Manuel Pégourié-Gonnard43b37cb2015-05-12 11:20:10 +0200561 * \brief Parse a private key in PEM or DER format
Paul Bakker1a7550a2013-09-15 13:01:22 +0200562 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100563 * \param ctx The PK context to fill. It must have been initialized
564 * but not set up.
Gilles Peskine159171b2018-12-19 17:03:28 +0100565 * \param key Input buffer to parse.
566 * The buffer must contain the input exactly, with no
567 * extra trailing material. For PEM, the buffer must
568 * contain a null-terminated string.
569 * \param keylen Size of \b key in bytes.
570 * For PEM data, this includes the terminating null byte,
571 * so \p keylen must be equal to `strlen(key) + 1`.
Gilles Peskined54b9752018-12-19 17:12:01 +0100572 * \param pwd Optional password for decryption.
573 * Pass \c NULL if expecting a non-encrypted key.
574 * Pass a string of \p pwdlen bytes if expecting an encrypted
575 * key; a non-encrypted key will also be accepted.
576 * The empty password is not supported.
577 * \param pwdlen Size of the password in bytes.
578 * Ignored if \p pwd is \c NULL.
Paul Bakker1a7550a2013-09-15 13:01:22 +0200579 *
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100580 * \note On entry, ctx must be empty, either freshly initialised
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200581 * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
582 * specific key type, check the result with mbedtls_pk_can_do().
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100583 *
584 * \note The key is also checked for correctness.
585 *
Paul Bakker1a7550a2013-09-15 13:01:22 +0200586 * \return 0 if successful, or a specific PK or PEM error code
587 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200588int mbedtls_pk_parse_key( mbedtls_pk_context *ctx,
Paul Bakker1a7550a2013-09-15 13:01:22 +0200589 const unsigned char *key, size_t keylen,
590 const unsigned char *pwd, size_t pwdlen );
591
Paul Bakkerff3a5182013-09-16 22:42:19 +0200592/** \ingroup pk_module */
Paul Bakker1a7550a2013-09-15 13:01:22 +0200593/**
Manuel Pégourié-Gonnard43b37cb2015-05-12 11:20:10 +0200594 * \brief Parse a public key in PEM or DER format
Paul Bakker1a7550a2013-09-15 13:01:22 +0200595 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100596 * \param ctx The PK context to fill. It must have been initialized
597 * but not set up.
Gilles Peskine159171b2018-12-19 17:03:28 +0100598 * \param key Input buffer to parse.
599 * The buffer must contain the input exactly, with no
600 * extra trailing material. For PEM, the buffer must
601 * contain a null-terminated string.
602 * \param keylen Size of \b key in bytes.
603 * For PEM data, this includes the terminating null byte,
604 * so \p keylen must be equal to `strlen(key) + 1`.
Paul Bakker1a7550a2013-09-15 13:01:22 +0200605 *
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100606 * \note On entry, ctx must be empty, either freshly initialised
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200607 * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
608 * specific key type, check the result with mbedtls_pk_can_do().
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100609 *
610 * \note The key is also checked for correctness.
611 *
Paul Bakker1a7550a2013-09-15 13:01:22 +0200612 * \return 0 if successful, or a specific PK or PEM error code
613 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200614int mbedtls_pk_parse_public_key( mbedtls_pk_context *ctx,
Paul Bakker1a7550a2013-09-15 13:01:22 +0200615 const unsigned char *key, size_t keylen );
616
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200617#if defined(MBEDTLS_FS_IO)
Paul Bakkerff3a5182013-09-16 22:42:19 +0200618/** \ingroup pk_module */
Paul Bakker1a7550a2013-09-15 13:01:22 +0200619/**
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200620 * \brief Load and parse a private key
621 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100622 * \param ctx The PK context to fill. It must have been initialized
623 * but not set up.
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200624 * \param path filename to read the private key from
Gilles Peskined54b9752018-12-19 17:12:01 +0100625 * \param password Optional password to decrypt the file.
626 * Pass \c NULL if expecting a non-encrypted key.
627 * Pass a null-terminated string if expecting an encrypted
628 * key; a non-encrypted key will also be accepted.
629 * The empty password is not supported.
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200630 *
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100631 * \note On entry, ctx must be empty, either freshly initialised
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200632 * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
633 * specific key type, check the result with mbedtls_pk_can_do().
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100634 *
635 * \note The key is also checked for correctness.
636 *
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200637 * \return 0 if successful, or a specific PK or PEM error code
638 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200639int mbedtls_pk_parse_keyfile( mbedtls_pk_context *ctx,
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200640 const char *path, const char *password );
641
Paul Bakkerff3a5182013-09-16 22:42:19 +0200642/** \ingroup pk_module */
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200643/**
Paul Bakker1a7550a2013-09-15 13:01:22 +0200644 * \brief Load and parse a public key
645 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100646 * \param ctx The PK context to fill. It must have been initialized
647 * but not set up.
Simon Butcher295639b2016-05-10 19:39:36 +0100648 * \param path filename to read the public key from
Paul Bakker1a7550a2013-09-15 13:01:22 +0200649 *
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100650 * \note On entry, ctx must be empty, either freshly initialised
Simon Butcher295639b2016-05-10 19:39:36 +0100651 * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If
652 * you need a specific key type, check the result with
653 * mbedtls_pk_can_do().
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100654 *
655 * \note The key is also checked for correctness.
656 *
Paul Bakker1a7550a2013-09-15 13:01:22 +0200657 * \return 0 if successful, or a specific PK or PEM error code
658 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200659int mbedtls_pk_parse_public_keyfile( mbedtls_pk_context *ctx, const char *path );
660#endif /* MBEDTLS_FS_IO */
661#endif /* MBEDTLS_PK_PARSE_C */
Paul Bakker1a7550a2013-09-15 13:01:22 +0200662
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200663#if defined(MBEDTLS_PK_WRITE_C)
Paul Bakker1a7550a2013-09-15 13:01:22 +0200664/**
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200665 * \brief Write a private key to a PKCS#1 or SEC1 DER structure
666 * Note: data is written at the end of the buffer! Use the
667 * return value to determine where you should start
668 * using the buffer
669 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100670 * \param ctx PK context which must contain a valid private key.
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200671 * \param buf buffer to write to
672 * \param size size of the buffer
673 *
674 * \return length of data written if successful, or a specific
675 * error code
676 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200677int mbedtls_pk_write_key_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200678
679/**
680 * \brief Write a public key to a SubjectPublicKeyInfo DER structure
681 * Note: data is written at the end of the buffer! Use the
682 * return value to determine where you should start
683 * using the buffer
684 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100685 * \param ctx PK context which must contain a valid public or private key.
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200686 * \param buf buffer to write to
687 * \param size size of the buffer
688 *
689 * \return length of data written if successful, or a specific
690 * error code
691 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200692int mbedtls_pk_write_pubkey_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200693
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200694#if defined(MBEDTLS_PEM_WRITE_C)
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200695/**
696 * \brief Write a public key to a PEM string
697 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100698 * \param ctx PK context which must contain a valid public or private key.
Gilles Peskine159171b2018-12-19 17:03:28 +0100699 * \param buf Buffer to write to. The output includes a
700 * terminating null byte.
701 * \param size Size of the buffer in bytes.
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200702 *
Manuel Pégourié-Gonnard81abefd2015-05-29 12:53:47 +0200703 * \return 0 if successful, or a specific error code
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200704 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200705int mbedtls_pk_write_pubkey_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200706
707/**
708 * \brief Write a private key to a PKCS#1 or SEC1 PEM string
709 *
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100710 * \param ctx PK context which must contain a valid private key.
Gilles Peskine159171b2018-12-19 17:03:28 +0100711 * \param buf Buffer to write to. The output includes a
712 * terminating null byte.
713 * \param size Size of the buffer in bytes.
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200714 *
Manuel Pégourié-Gonnard81abefd2015-05-29 12:53:47 +0200715 * \return 0 if successful, or a specific error code
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200716 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200717int mbedtls_pk_write_key_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
718#endif /* MBEDTLS_PEM_WRITE_C */
719#endif /* MBEDTLS_PK_WRITE_C */
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200720
721/*
722 * WARNING: Low-level functions. You probably do not want to use these unless
723 * you are certain you do ;)
724 */
725
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200726#if defined(MBEDTLS_PK_PARSE_C)
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200727/**
Paul Bakker1a7550a2013-09-15 13:01:22 +0200728 * \brief Parse a SubjectPublicKeyInfo DER structure
729 *
730 * \param p the position in the ASN.1 data
731 * \param end end of the buffer
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100732 * \param pk The PK context to fill. It must have been initialized
733 * but not set up.
Paul Bakker1a7550a2013-09-15 13:01:22 +0200734 *
735 * \return 0 if successful, or a specific PK error code
736 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200737int mbedtls_pk_parse_subpubkey( unsigned char **p, const unsigned char *end,
738 mbedtls_pk_context *pk );
739#endif /* MBEDTLS_PK_PARSE_C */
Paul Bakker1a7550a2013-09-15 13:01:22 +0200740
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200741#if defined(MBEDTLS_PK_WRITE_C)
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200742/**
743 * \brief Write a subjectPublicKey to ASN.1 data
744 * Note: function works backwards in data buffer
745 *
746 * \param p reference to current position pointer
747 * \param start start of the buffer (for bounds-checking)
Gilles Peskine6af45ec2018-12-19 17:52:05 +0100748 * \param key PK context which must contain a valid public or private key.
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200749 *
750 * \return the length written or a negative error code
751 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200752int mbedtls_pk_write_pubkey( unsigned char **p, unsigned char *start,
753 const mbedtls_pk_context *key );
754#endif /* MBEDTLS_PK_WRITE_C */
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200755
Manuel Pégourié-Gonnard9439f932014-11-21 09:49:43 +0100756/*
757 * Internal module functions. You probably do not want to use these unless you
758 * know you do.
759 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200760#if defined(MBEDTLS_FS_IO)
761int mbedtls_pk_load_file( const char *path, unsigned char **buf, size_t *n );
Manuel Pégourié-Gonnard9439f932014-11-21 09:49:43 +0100762#endif
763
Paul Bakkered27a042013-04-18 22:46:23 +0200764#ifdef __cplusplus
765}
766#endif
767
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200768#endif /* MBEDTLS_PK_H */