blob: 8beb2af4158657f4d0a1e86d98ca7c0d6d7788c8 [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
Manuel Pégourié-Gonnard2ac9c602015-10-05 16:18:23 +010048#if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
49 !defined(inline) && !defined(__cplusplus)
50#define inline __inline
51#endif
52
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +020053#define MBEDTLS_ERR_PK_ALLOC_FAILED -0x3F80 /**< Memory allocation failed. */
Manuel Pégourié-Gonnardeed55a42015-04-09 17:31:59 +020054#define MBEDTLS_ERR_PK_TYPE_MISMATCH -0x3F00 /**< Type mismatch, eg attempt to encrypt with an ECDSA key */
55#define MBEDTLS_ERR_PK_BAD_INPUT_DATA -0x3E80 /**< Bad input parameters to function. */
56#define MBEDTLS_ERR_PK_FILE_IO_ERROR -0x3E00 /**< Read/write of file failed. */
57#define MBEDTLS_ERR_PK_KEY_INVALID_VERSION -0x3D80 /**< Unsupported key version */
58#define MBEDTLS_ERR_PK_KEY_INVALID_FORMAT -0x3D00 /**< Invalid key tag or value. */
59#define MBEDTLS_ERR_PK_UNKNOWN_PK_ALG -0x3C80 /**< Key algorithm is unsupported (only RSA and EC are supported). */
60#define MBEDTLS_ERR_PK_PASSWORD_REQUIRED -0x3C00 /**< Private key password can't be empty. */
61#define MBEDTLS_ERR_PK_PASSWORD_MISMATCH -0x3B80 /**< Given private key password does not allow for correct decryption. */
62#define MBEDTLS_ERR_PK_INVALID_PUBKEY -0x3B00 /**< The pubkey tag or value is invalid (only RSA and EC are supported). */
63#define MBEDTLS_ERR_PK_INVALID_ALG -0x3A80 /**< The algorithm tag or value is invalid. */
64#define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE -0x3A00 /**< Elliptic curve is unsupported (only NIST curves are supported). */
65#define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980 /**< Unavailable feature, e.g. RSA disabled for RSA key. */
Gilles Peskine5114d3e2018-03-30 07:12:15 +020066#define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH -0x3900 /**< The buffer contains a valid signature followed by more data. */
Gilles Peskine7ecab3d2018-01-26 17:56:38 +010067#define MBEDTLS_ERR_PK_HW_ACCEL_FAILED -0x3880 /**< PK hardware accelerator failed. */
Paul Bakker1a7550a2013-09-15 13:01:22 +020068
Paul Bakkered27a042013-04-18 22:46:23 +020069#ifdef __cplusplus
70extern "C" {
71#endif
72
73/**
74 * \brief Public key types
75 */
76typedef enum {
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020077 MBEDTLS_PK_NONE=0,
78 MBEDTLS_PK_RSA,
79 MBEDTLS_PK_ECKEY,
80 MBEDTLS_PK_ECKEY_DH,
81 MBEDTLS_PK_ECDSA,
82 MBEDTLS_PK_RSA_ALT,
83 MBEDTLS_PK_RSASSA_PSS,
84} mbedtls_pk_type_t;
Paul Bakkered27a042013-04-18 22:46:23 +020085
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +020086/**
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +020087 * \brief Options for RSASSA-PSS signature verification.
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020088 * See \c mbedtls_rsa_rsassa_pss_verify_ext()
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +020089 */
90typedef struct
91{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020092 mbedtls_md_type_t mgf1_hash_id;
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +020093 int expected_salt_len;
94
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020095} mbedtls_pk_rsassa_pss_options;
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +020096
97/**
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +020098 * \brief Types for interfacing with the debug module
99 */
100typedef enum
101{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200102 MBEDTLS_PK_DEBUG_NONE = 0,
103 MBEDTLS_PK_DEBUG_MPI,
104 MBEDTLS_PK_DEBUG_ECP,
105} mbedtls_pk_debug_type;
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200106
107/**
108 * \brief Item to send to the debug module
109 */
110typedef struct
111{
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200112 mbedtls_pk_debug_type type;
Paul Bakkerfcc17212013-10-11 09:36:52 +0200113 const char *name;
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200114 void *value;
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200115} mbedtls_pk_debug_item;
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200116
117/** Maximum number of item send for debugging, plus 1 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200118#define MBEDTLS_PK_DEBUG_MAX_ITEMS 3
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200119
120/**
Manuel Pégourié-Gonnard3fb5c5e2013-08-14 18:26:41 +0200121 * \brief Public key information and operations
Manuel Pégourié-Gonnardd73b3c12013-08-12 17:06:05 +0200122 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200123typedef struct mbedtls_pk_info_t mbedtls_pk_info_t;
Manuel Pégourié-Gonnardd73b3c12013-08-12 17:06:05 +0200124
125/**
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200126 * \brief Public key container
127 */
128typedef struct
129{
Manuel Pégourié-Gonnarda79efde2015-04-09 10:58:56 +0200130 const mbedtls_pk_info_t * pk_info; /**< Public key informations */
131 void * pk_ctx; /**< Underlying public key context */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200132} mbedtls_pk_context;
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200133
Manuel Pégourié-Gonnarda79efde2015-04-09 10:58:56 +0200134#if defined(MBEDTLS_RSA_C)
135/**
136 * Quick access to an RSA context inside a PK context.
137 *
138 * \warning You must make sure the PK context actually holds an RSA context
139 * before using this function!
140 */
141static inline mbedtls_rsa_context *mbedtls_pk_rsa( const mbedtls_pk_context pk )
142{
143 return( (mbedtls_rsa_context *) (pk).pk_ctx );
144}
145#endif /* MBEDTLS_RSA_C */
146
147#if defined(MBEDTLS_ECP_C)
148/**
149 * Quick access to an EC context inside a PK context.
150 *
151 * \warning You must make sure the PK context actually holds an EC context
152 * before using this function!
153 */
154static inline mbedtls_ecp_keypair *mbedtls_pk_ec( const mbedtls_pk_context pk )
155{
156 return( (mbedtls_ecp_keypair *) (pk).pk_ctx );
157}
158#endif /* MBEDTLS_ECP_C */
159
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200160#if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200161/**
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200162 * \brief Types for RSA-alt abstraction
163 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200164typedef int (*mbedtls_pk_rsa_alt_decrypt_func)( void *ctx, int mode, size_t *olen,
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200165 const unsigned char *input, unsigned char *output,
166 size_t output_max_len );
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200167typedef int (*mbedtls_pk_rsa_alt_sign_func)( void *ctx,
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200168 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200169 int mode, mbedtls_md_type_t md_alg, unsigned int hashlen,
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200170 const unsigned char *hash, unsigned char *sig );
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200171typedef size_t (*mbedtls_pk_rsa_alt_key_len_func)( void *ctx );
172#endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200173
174/**
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200175 * \brief Return information associated with the given PK type
176 *
Paul Bakkerdcbfdcc2013-09-10 16:16:50 +0200177 * \param pk_type PK type to search for.
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200178 *
179 * \return The PK info associated with the type or NULL if not found.
180 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200181const mbedtls_pk_info_t *mbedtls_pk_info_from_type( mbedtls_pk_type_t pk_type );
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200182
183/**
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200184 * \brief Initialize a mbedtls_pk_context (as NONE)
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200185 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200186void mbedtls_pk_init( mbedtls_pk_context *ctx );
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200187
188/**
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200189 * \brief Free a mbedtls_pk_context
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200190 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200191void mbedtls_pk_free( mbedtls_pk_context *ctx );
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200192
193/**
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200194 * \brief Initialize a PK context with the information given
195 * and allocates the type-specific PK subcontext.
196 *
197 * \param ctx Context to initialize. Must be empty (type NONE).
198 * \param info Information to use
199 *
200 * \return 0 on success,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200201 * MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input,
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200202 * MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200203 *
Paul Bakker42099c32014-01-27 11:45:49 +0100204 * \note For contexts holding an RSA-alt key, use
Manuel Pégourié-Gonnardd9e6a3a2015-05-14 19:41:36 +0200205 * \c mbedtls_pk_setup_rsa_alt() instead.
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200206 */
Manuel Pégourié-Gonnardd9e6a3a2015-05-14 19:41:36 +0200207int mbedtls_pk_setup( mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info );
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200208
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200209#if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200210/**
Paul Bakker4fc090a2013-09-18 15:43:25 +0200211 * \brief Initialize an RSA-alt context
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200212 *
213 * \param ctx Context to initialize. Must be empty (type NONE).
214 * \param key RSA key pointer
215 * \param decrypt_func Decryption function
216 * \param sign_func Signing function
Manuel Pégourié-Gonnard01488752014-04-03 22:09:18 +0200217 * \param key_len_func Function returning key length in bytes
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200218 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200219 * \return 0 on success, or MBEDTLS_ERR_PK_BAD_INPUT_DATA if the
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200220 * context wasn't already initialized as RSA_ALT.
221 *
Manuel Pégourié-Gonnardd9e6a3a2015-05-14 19:41:36 +0200222 * \note This function replaces \c mbedtls_pk_setup() for RSA-alt.
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200223 */
Manuel Pégourié-Gonnardd9e6a3a2015-05-14 19:41:36 +0200224int mbedtls_pk_setup_rsa_alt( mbedtls_pk_context *ctx, void * key,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200225 mbedtls_pk_rsa_alt_decrypt_func decrypt_func,
226 mbedtls_pk_rsa_alt_sign_func sign_func,
227 mbedtls_pk_rsa_alt_key_len_func key_len_func );
228#endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200229
230/**
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200231 * \brief Get the size in bits of the underlying key
232 *
233 * \param ctx Context to use
234 *
235 * \return Key size in bits, or 0 on error
236 */
Manuel Pégourié-Gonnard097c7bb2015-06-18 16:43:38 +0200237size_t mbedtls_pk_get_bitlen( const mbedtls_pk_context *ctx );
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200238
239/**
Manuel Pégourié-Gonnard0d420492013-08-21 16:14:26 +0200240 * \brief Get the length in bytes of the underlying key
241 * \param ctx Context to use
242 *
Paul Bakker4fc090a2013-09-18 15:43:25 +0200243 * \return Key length in bytes, or 0 on error
Manuel Pégourié-Gonnard0d420492013-08-21 16:14:26 +0200244 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200245static inline size_t mbedtls_pk_get_len( const mbedtls_pk_context *ctx )
Manuel Pégourié-Gonnard0d420492013-08-21 16:14:26 +0200246{
Manuel Pégourié-Gonnard097c7bb2015-06-18 16:43:38 +0200247 return( ( mbedtls_pk_get_bitlen( ctx ) + 7 ) / 8 );
Manuel Pégourié-Gonnard0d420492013-08-21 16:14:26 +0200248}
249
250/**
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200251 * \brief Tell if a context can do the operation given by type
252 *
253 * \param ctx Context to test
254 * \param type Target type
255 *
256 * \return 0 if context can't do the operations,
257 * 1 otherwise.
258 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200259int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type );
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200260
261/**
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200262 * \brief Verify signature (including padding if relevant).
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200263 *
264 * \param ctx PK context to use
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200265 * \param md_alg Hash algorithm used (see notes)
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200266 * \param hash Hash of the message to sign
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200267 * \param hash_len Hash length or 0 (see notes)
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200268 * \param sig Signature to verify
269 * \param sig_len Signature length
270 *
271 * \return 0 on success (signature is valid),
Gilles Peskine5114d3e2018-03-30 07:12:15 +0200272 * #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid
273 * signature in sig but its length is less than \p siglen,
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200274 * or a specific error code.
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200275 *
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200276 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200277 * Use \c mbedtls_pk_verify_ext( MBEDTLS_PK_RSASSA_PSS, ... )
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200278 * to verify RSASSA_PSS signatures.
279 *
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200280 * \note If hash_len is 0, then the length associated with md_alg
281 * is used instead, or an error returned if it is invalid.
282 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200283 * \note md_alg may be MBEDTLS_MD_NONE, only if hash_len != 0
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200284 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200285int mbedtls_pk_verify( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
Manuel Pégourié-Gonnardf73da022013-08-17 14:36:32 +0200286 const unsigned char *hash, size_t hash_len,
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200287 const unsigned char *sig, size_t sig_len );
288
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200289/**
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200290 * \brief Verify signature, with options.
291 * (Includes verification of the padding depending on type.)
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200292 *
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200293 * \param type Signature type (inc. possible padding type) to verify
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200294 * \param options Pointer to type-specific options, or NULL
295 * \param ctx PK context to use
296 * \param md_alg Hash algorithm used (see notes)
297 * \param hash Hash of the message to sign
298 * \param hash_len Hash length or 0 (see notes)
299 * \param sig Signature to verify
300 * \param sig_len Signature length
301 *
302 * \return 0 on success (signature is valid),
Gilles Peskine5114d3e2018-03-30 07:12:15 +0200303 * #MBEDTLS_ERR_PK_TYPE_MISMATCH if the PK context can't be
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200304 * used for this type of signatures,
Gilles Peskine5114d3e2018-03-30 07:12:15 +0200305 * #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid
306 * signature in sig but its length is less than \p siglen,
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200307 * or a specific error code.
308 *
309 * \note If hash_len is 0, then the length associated with md_alg
310 * is used instead, or an error returned if it is invalid.
311 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200312 * \note md_alg may be MBEDTLS_MD_NONE, only if hash_len != 0
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200313 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200314 * \note If type is MBEDTLS_PK_RSASSA_PSS, then options must point
315 * to a mbedtls_pk_rsassa_pss_options structure,
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200316 * otherwise it must be NULL.
317 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200318int mbedtls_pk_verify_ext( mbedtls_pk_type_t type, const void *options,
319 mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200320 const unsigned char *hash, size_t hash_len,
321 const unsigned char *sig, size_t sig_len );
322
323/**
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200324 * \brief Make signature, including padding if relevant.
Manuel Pégourié-Gonnard8df27692013-08-21 10:34:38 +0200325 *
Manuel Pégourié-Gonnardfb84d382015-10-30 10:56:25 +0100326 * \param ctx PK context to use - must hold a private key
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200327 * \param md_alg Hash algorithm used (see notes)
Manuel Pégourié-Gonnard8df27692013-08-21 10:34:38 +0200328 * \param hash Hash of the message to sign
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200329 * \param hash_len Hash length or 0 (see notes)
Manuel Pégourié-Gonnard8df27692013-08-21 10:34:38 +0200330 * \param sig Place to write the signature
331 * \param sig_len Number of bytes written
332 * \param f_rng RNG function
333 * \param p_rng RNG parameter
334 *
335 * \return 0 on success, or a specific error code.
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200336 *
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200337 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
338 * There is no interface in the PK module to make RSASSA-PSS
339 * signatures yet.
340 *
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200341 * \note If hash_len is 0, then the length associated with md_alg
342 * is used instead, or an error returned if it is invalid.
343 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200344 * \note For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0.
345 * For ECDSA, md_alg may never be MBEDTLS_MD_NONE.
k-stachowiakeee98e92019-05-31 20:16:50 +0200346 *
347 * \note In order to ensure enough space for the signature, the
348 * \p sig buffer size must be of at least
349 * `max(MBEDTLS_ECDSA_MAX_LEN, MBEDTLS_MPI_MAX_SIZE)` bytes.
Manuel Pégourié-Gonnard8df27692013-08-21 10:34:38 +0200350 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200351int mbedtls_pk_sign( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
Manuel Pégourié-Gonnard8df27692013-08-21 10:34:38 +0200352 const unsigned char *hash, size_t hash_len,
353 unsigned char *sig, size_t *sig_len,
354 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
355
356/**
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200357 * \brief Decrypt message (including padding if relevant).
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200358 *
Manuel Pégourié-Gonnardfb84d382015-10-30 10:56:25 +0100359 * \param ctx PK context to use - must hold a private key
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200360 * \param input Input to decrypt
361 * \param ilen Input size
362 * \param output Decrypted output
Paul Bakker4fc090a2013-09-18 15:43:25 +0200363 * \param olen Decrypted message length
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200364 * \param osize Size of the output buffer
Paul Bakkerdcbfdcc2013-09-10 16:16:50 +0200365 * \param f_rng RNG function
366 * \param p_rng RNG parameter
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200367 *
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200368 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
369 *
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200370 * \return 0 on success, or a specific error code.
371 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200372int mbedtls_pk_decrypt( mbedtls_pk_context *ctx,
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200373 const unsigned char *input, size_t ilen,
374 unsigned char *output, size_t *olen, size_t osize,
375 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
376
377/**
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200378 * \brief Encrypt message (including padding if relevant).
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200379 *
380 * \param ctx PK context to use
381 * \param input Message to encrypt
382 * \param ilen Message size
383 * \param output Encrypted output
384 * \param olen Encrypted output length
385 * \param osize Size of the output buffer
Paul Bakkerdcbfdcc2013-09-10 16:16:50 +0200386 * \param f_rng RNG function
387 * \param p_rng RNG parameter
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200388 *
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200389 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
390 *
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200391 * \return 0 on success, or a specific error code.
392 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200393int mbedtls_pk_encrypt( mbedtls_pk_context *ctx,
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200394 const unsigned char *input, size_t ilen,
395 unsigned char *output, size_t *olen, size_t osize,
396 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
397
398/**
Manuel Pégourié-Gonnard70bdadf2014-11-06 16:51:20 +0100399 * \brief Check if a public-private pair of keys matches.
400 *
401 * \param pub Context holding a public key.
402 * \param prv Context holding a private (and public) key.
403 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200404 * \return 0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
Manuel Pégourié-Gonnard70bdadf2014-11-06 16:51:20 +0100405 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200406int mbedtls_pk_check_pair( const mbedtls_pk_context *pub, const mbedtls_pk_context *prv );
Manuel Pégourié-Gonnard70bdadf2014-11-06 16:51:20 +0100407
408/**
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200409 * \brief Export debug information
410 *
411 * \param ctx Context to use
412 * \param items Place to write debug items
413 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200414 * \return 0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200415 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200416int mbedtls_pk_debug( const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *items );
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200417
Manuel Pégourié-Gonnard3fb5c5e2013-08-14 18:26:41 +0200418/**
419 * \brief Access the type name
420 *
421 * \param ctx Context to use
422 *
423 * \return Type name on success, or "invalid PK"
424 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200425const char * mbedtls_pk_get_name( const mbedtls_pk_context *ctx );
Manuel Pégourié-Gonnard3fb5c5e2013-08-14 18:26:41 +0200426
Manuel Pégourié-Gonnard8053da42013-09-11 22:28:30 +0200427/**
Paul Bakker4fc090a2013-09-18 15:43:25 +0200428 * \brief Get the key type
Manuel Pégourié-Gonnard8053da42013-09-11 22:28:30 +0200429 *
430 * \param ctx Context to use
431 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200432 * \return Type on success, or MBEDTLS_PK_NONE
Manuel Pégourié-Gonnard8053da42013-09-11 22:28:30 +0200433 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200434mbedtls_pk_type_t mbedtls_pk_get_type( const mbedtls_pk_context *ctx );
Manuel Pégourié-Gonnard8053da42013-09-11 22:28:30 +0200435
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200436#if defined(MBEDTLS_PK_PARSE_C)
Paul Bakkerff3a5182013-09-16 22:42:19 +0200437/** \ingroup pk_module */
Paul Bakker1a7550a2013-09-15 13:01:22 +0200438/**
Manuel Pégourié-Gonnard43b37cb2015-05-12 11:20:10 +0200439 * \brief Parse a private key in PEM or DER format
Paul Bakker1a7550a2013-09-15 13:01:22 +0200440 *
441 * \param ctx key to be initialized
442 * \param key input buffer
443 * \param keylen size of the buffer
Manuel Pégourié-Gonnard43b37cb2015-05-12 11:20:10 +0200444 * (including the terminating null byte for PEM data)
Paul Bakker1a7550a2013-09-15 13:01:22 +0200445 * \param pwd password for decryption (optional)
446 * \param pwdlen size of the password
447 *
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100448 * \note On entry, ctx must be empty, either freshly initialised
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200449 * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
450 * specific key type, check the result with mbedtls_pk_can_do().
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100451 *
452 * \note The key is also checked for correctness.
453 *
Paul Bakker1a7550a2013-09-15 13:01:22 +0200454 * \return 0 if successful, or a specific PK or PEM error code
455 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200456int mbedtls_pk_parse_key( mbedtls_pk_context *ctx,
Paul Bakker1a7550a2013-09-15 13:01:22 +0200457 const unsigned char *key, size_t keylen,
458 const unsigned char *pwd, size_t pwdlen );
459
Paul Bakkerff3a5182013-09-16 22:42:19 +0200460/** \ingroup pk_module */
Paul Bakker1a7550a2013-09-15 13:01:22 +0200461/**
Manuel Pégourié-Gonnard43b37cb2015-05-12 11:20:10 +0200462 * \brief Parse a public key in PEM or DER format
Paul Bakker1a7550a2013-09-15 13:01:22 +0200463 *
464 * \param ctx key to be initialized
465 * \param key input buffer
466 * \param keylen size of the buffer
Manuel Pégourié-Gonnard43b37cb2015-05-12 11:20:10 +0200467 * (including the terminating null byte for PEM data)
Paul Bakker1a7550a2013-09-15 13:01:22 +0200468 *
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100469 * \note On entry, ctx must be empty, either freshly initialised
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200470 * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
471 * specific key type, check the result with mbedtls_pk_can_do().
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100472 *
473 * \note The key is also checked for correctness.
474 *
Paul Bakker1a7550a2013-09-15 13:01:22 +0200475 * \return 0 if successful, or a specific PK or PEM error code
476 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200477int mbedtls_pk_parse_public_key( mbedtls_pk_context *ctx,
Paul Bakker1a7550a2013-09-15 13:01:22 +0200478 const unsigned char *key, size_t keylen );
479
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200480#if defined(MBEDTLS_FS_IO)
Paul Bakkerff3a5182013-09-16 22:42:19 +0200481/** \ingroup pk_module */
Paul Bakker1a7550a2013-09-15 13:01:22 +0200482/**
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200483 * \brief Load and parse a private key
484 *
485 * \param ctx key to be initialized
486 * \param path filename to read the private key from
487 * \param password password to decrypt the file (can be NULL)
488 *
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100489 * \note On entry, ctx must be empty, either freshly initialised
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200490 * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
491 * specific key type, check the result with mbedtls_pk_can_do().
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100492 *
493 * \note The key is also checked for correctness.
494 *
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200495 * \return 0 if successful, or a specific PK or PEM error code
496 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200497int mbedtls_pk_parse_keyfile( mbedtls_pk_context *ctx,
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200498 const char *path, const char *password );
499
Paul Bakkerff3a5182013-09-16 22:42:19 +0200500/** \ingroup pk_module */
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200501/**
Paul Bakker1a7550a2013-09-15 13:01:22 +0200502 * \brief Load and parse a public key
503 *
504 * \param ctx key to be initialized
Simon Butcher295639b2016-05-10 19:39:36 +0100505 * \param path filename to read the public key from
Paul Bakker1a7550a2013-09-15 13:01:22 +0200506 *
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100507 * \note On entry, ctx must be empty, either freshly initialised
Simon Butcher295639b2016-05-10 19:39:36 +0100508 * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If
509 * you need a specific key type, check the result with
510 * mbedtls_pk_can_do().
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100511 *
512 * \note The key is also checked for correctness.
513 *
Paul Bakker1a7550a2013-09-15 13:01:22 +0200514 * \return 0 if successful, or a specific PK or PEM error code
515 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200516int mbedtls_pk_parse_public_keyfile( mbedtls_pk_context *ctx, const char *path );
517#endif /* MBEDTLS_FS_IO */
518#endif /* MBEDTLS_PK_PARSE_C */
Paul Bakker1a7550a2013-09-15 13:01:22 +0200519
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200520#if defined(MBEDTLS_PK_WRITE_C)
Paul Bakker1a7550a2013-09-15 13:01:22 +0200521/**
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200522 * \brief Write a private key to a PKCS#1 or SEC1 DER structure
523 * Note: data is written at the end of the buffer! Use the
524 * return value to determine where you should start
525 * using the buffer
526 *
Paul Bakkera36d23e2013-12-30 17:57:27 +0100527 * \param ctx private to write away
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200528 * \param buf buffer to write to
529 * \param size size of the buffer
530 *
531 * \return length of data written if successful, or a specific
532 * error code
533 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200534int mbedtls_pk_write_key_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200535
536/**
537 * \brief Write a public key to a SubjectPublicKeyInfo DER structure
538 * Note: data is written at the end of the buffer! Use the
539 * return value to determine where you should start
540 * using the buffer
541 *
Paul Bakkera36d23e2013-12-30 17:57:27 +0100542 * \param ctx public key to write away
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200543 * \param buf buffer to write to
544 * \param size size of the buffer
545 *
546 * \return length of data written if successful, or a specific
547 * error code
548 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200549int mbedtls_pk_write_pubkey_der( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200550
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200551#if defined(MBEDTLS_PEM_WRITE_C)
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200552/**
553 * \brief Write a public key to a PEM string
554 *
Paul Bakkera36d23e2013-12-30 17:57:27 +0100555 * \param ctx public key to write away
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200556 * \param buf buffer to write to
557 * \param size size of the buffer
558 *
Manuel Pégourié-Gonnard81abefd2015-05-29 12:53:47 +0200559 * \return 0 if successful, or a specific error code
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200560 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200561int mbedtls_pk_write_pubkey_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200562
563/**
564 * \brief Write a private key to a PKCS#1 or SEC1 PEM string
565 *
Paul Bakkera36d23e2013-12-30 17:57:27 +0100566 * \param ctx private to write away
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200567 * \param buf buffer to write to
568 * \param size size of the buffer
569 *
Manuel Pégourié-Gonnard81abefd2015-05-29 12:53:47 +0200570 * \return 0 if successful, or a specific error code
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200571 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200572int mbedtls_pk_write_key_pem( mbedtls_pk_context *ctx, unsigned char *buf, size_t size );
573#endif /* MBEDTLS_PEM_WRITE_C */
574#endif /* MBEDTLS_PK_WRITE_C */
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200575
576/*
577 * WARNING: Low-level functions. You probably do not want to use these unless
578 * you are certain you do ;)
579 */
580
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200581#if defined(MBEDTLS_PK_PARSE_C)
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200582/**
Paul Bakker1a7550a2013-09-15 13:01:22 +0200583 * \brief Parse a SubjectPublicKeyInfo DER structure
584 *
585 * \param p the position in the ASN.1 data
586 * \param end end of the buffer
587 * \param pk the key to fill
588 *
589 * \return 0 if successful, or a specific PK error code
590 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200591int mbedtls_pk_parse_subpubkey( unsigned char **p, const unsigned char *end,
592 mbedtls_pk_context *pk );
593#endif /* MBEDTLS_PK_PARSE_C */
Paul Bakker1a7550a2013-09-15 13:01:22 +0200594
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200595#if defined(MBEDTLS_PK_WRITE_C)
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200596/**
597 * \brief Write a subjectPublicKey to ASN.1 data
598 * Note: function works backwards in data buffer
599 *
600 * \param p reference to current position pointer
601 * \param start start of the buffer (for bounds-checking)
602 * \param key public key to write away
603 *
604 * \return the length written or a negative error code
605 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200606int mbedtls_pk_write_pubkey( unsigned char **p, unsigned char *start,
607 const mbedtls_pk_context *key );
608#endif /* MBEDTLS_PK_WRITE_C */
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200609
Manuel Pégourié-Gonnard9439f932014-11-21 09:49:43 +0100610/*
611 * Internal module functions. You probably do not want to use these unless you
612 * know you do.
613 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200614#if defined(MBEDTLS_FS_IO)
615int mbedtls_pk_load_file( const char *path, unsigned char **buf, size_t *n );
Manuel Pégourié-Gonnard9439f932014-11-21 09:49:43 +0100616#endif
617
Paul Bakkered27a042013-04-18 22:46:23 +0200618#ifdef __cplusplus
619}
620#endif
621
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200622#endif /* MBEDTLS_PK_H */