blob: b5c02b0d0167d225b704947ff1d985a7a392b7e6 [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/*
Bence Szépkúti1e148272020-08-07 13:07:28 +02007 * Copyright The Mbed TLS Contributors
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é-Gonnardd73b3c12013-08-12 17:06:05 +020022
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020023#ifndef MBEDTLS_PK_H
24#define MBEDTLS_PK_H
Mateusz Starzyk846f0212021-05-19 19:44:07 +020025#include "mbedtls/private_access.h"
Paul Bakkered27a042013-04-18 22:46:23 +020026
Bence Szépkútic662b362021-05-27 11:25:03 +020027#include "mbedtls/build_info.h"
Manuel Pégourié-Gonnard244569f2013-07-10 09:46:30 +020028
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010029#include "mbedtls/md.h"
Manuel Pégourié-Gonnardf73da022013-08-17 14:36:32 +020030
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020031#if defined(MBEDTLS_RSA_C)
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010032#include "mbedtls/rsa.h"
Manuel Pégourié-Gonnard244569f2013-07-10 09:46:30 +020033#endif
34
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020035#if defined(MBEDTLS_ECP_C)
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010036#include "mbedtls/ecp.h"
Manuel Pégourié-Gonnardd73b3c12013-08-12 17:06:05 +020037#endif
38
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020039#if defined(MBEDTLS_ECDSA_C)
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010040#include "mbedtls/ecdsa.h"
Manuel Pégourié-Gonnard211a64c2013-08-09 15:04:26 +020041#endif
42
Manuel Pégourié-Gonnard20678b22018-10-22 12:11:15 +020043#if defined(MBEDTLS_USE_PSA_CRYPTO)
44#include "psa/crypto.h"
45#endif
46
Gilles Peskined2971572021-07-26 18:48:10 +020047/** Memory allocation failed. */
48#define MBEDTLS_ERR_PK_ALLOC_FAILED -0x3F80
49/** Type mismatch, eg attempt to encrypt with an ECDSA key */
50#define MBEDTLS_ERR_PK_TYPE_MISMATCH -0x3F00
51/** Bad input parameters to function. */
52#define MBEDTLS_ERR_PK_BAD_INPUT_DATA -0x3E80
53/** Read/write of file failed. */
54#define MBEDTLS_ERR_PK_FILE_IO_ERROR -0x3E00
55/** Unsupported key version */
56#define MBEDTLS_ERR_PK_KEY_INVALID_VERSION -0x3D80
57/** Invalid key tag or value. */
58#define MBEDTLS_ERR_PK_KEY_INVALID_FORMAT -0x3D00
59/** Key algorithm is unsupported (only RSA and EC are supported). */
60#define MBEDTLS_ERR_PK_UNKNOWN_PK_ALG -0x3C80
61/** Private key password can't be empty. */
62#define MBEDTLS_ERR_PK_PASSWORD_REQUIRED -0x3C00
63/** Given private key password does not allow for correct decryption. */
64#define MBEDTLS_ERR_PK_PASSWORD_MISMATCH -0x3B80
65/** The pubkey tag or value is invalid (only RSA and EC are supported). */
66#define MBEDTLS_ERR_PK_INVALID_PUBKEY -0x3B00
67/** The algorithm tag or value is invalid. */
68#define MBEDTLS_ERR_PK_INVALID_ALG -0x3A80
69/** Elliptic curve is unsupported (only NIST curves are supported). */
70#define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE -0x3A00
71/** Unavailable feature, e.g. RSA disabled for RSA key. */
72#define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980
73/** The buffer contains a valid signature followed by more data. */
74#define MBEDTLS_ERR_PK_SIG_LEN_MISMATCH -0x3900
75/** The output buffer is too small. */
76#define MBEDTLS_ERR_PK_BUFFER_TOO_SMALL -0x3880
Ron Eldor9924bdc2018-10-04 10:59:13 +030077
Paul Bakkered27a042013-04-18 22:46:23 +020078#ifdef __cplusplus
79extern "C" {
80#endif
81
82/**
83 * \brief Public key types
84 */
85typedef enum {
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020086 MBEDTLS_PK_NONE=0,
87 MBEDTLS_PK_RSA,
88 MBEDTLS_PK_ECKEY,
89 MBEDTLS_PK_ECKEY_DH,
90 MBEDTLS_PK_ECDSA,
91 MBEDTLS_PK_RSA_ALT,
92 MBEDTLS_PK_RSASSA_PSS,
Manuel Pégourié-Gonnard69baf702018-11-06 09:34:30 +010093 MBEDTLS_PK_OPAQUE,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020094} mbedtls_pk_type_t;
Paul Bakkered27a042013-04-18 22:46:23 +020095
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +020096/**
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +020097 * \brief Options for RSASSA-PSS signature verification.
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020098 * See \c mbedtls_rsa_rsassa_pss_verify_ext()
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +020099 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100100typedef struct mbedtls_pk_rsassa_pss_options {
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200101 mbedtls_md_type_t MBEDTLS_PRIVATE(mgf1_hash_id);
102 int MBEDTLS_PRIVATE(expected_salt_len);
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200103
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200104} mbedtls_pk_rsassa_pss_options;
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200105
106/**
Gilles Peskineda252be2019-11-05 16:23:49 +0100107 * \brief Maximum size of a signature made by mbedtls_pk_sign().
108 */
Gilles Peskine54605652019-11-08 16:24:16 +0100109/* We need to set MBEDTLS_PK_SIGNATURE_MAX_SIZE to the maximum signature
110 * size among the supported signature types. Do it by starting at 0,
111 * then incrementally increasing to be large enough for each supported
112 * signature mechanism.
113 *
114 * The resulting value can be 0, for example if MBEDTLS_ECDH_C is enabled
115 * (which allows the pk module to be included) but neither MBEDTLS_ECDSA_C
116 * nor MBEDTLS_RSA_C nor any opaque signature mechanism (PSA or RSA_ALT).
117 */
118#define MBEDTLS_PK_SIGNATURE_MAX_SIZE 0
119
Gilles Peskine449bd832023-01-11 14:50:10 +0100120#if (defined(MBEDTLS_RSA_C) || defined(MBEDTLS_PK_RSA_ALT_SUPPORT)) && \
Gilles Peskineb22a24b2019-11-05 16:56:39 +0100121 MBEDTLS_MPI_MAX_SIZE > MBEDTLS_PK_SIGNATURE_MAX_SIZE
Gilles Peskine54605652019-11-08 16:24:16 +0100122/* For RSA, the signature can be as large as the bignum module allows.
123 * For RSA_ALT, the signature size is not necessarily tied to what the
124 * bignum module can do, but in the absence of any specific setting,
Chris Jones3848e312021-03-11 16:17:59 +0000125 * we use that (rsa_alt_sign_wrap in library/pk_wrap.h will check). */
Gilles Peskineb22a24b2019-11-05 16:56:39 +0100126#undef MBEDTLS_PK_SIGNATURE_MAX_SIZE
127#define MBEDTLS_PK_SIGNATURE_MAX_SIZE MBEDTLS_MPI_MAX_SIZE
128#endif
Gilles Peskine54605652019-11-08 16:24:16 +0100129
Gilles Peskineb22a24b2019-11-05 16:56:39 +0100130#if defined(MBEDTLS_ECDSA_C) && \
131 MBEDTLS_ECDSA_MAX_LEN > MBEDTLS_PK_SIGNATURE_MAX_SIZE
Gilles Peskine54605652019-11-08 16:24:16 +0100132/* For ECDSA, the ecdsa module exports a constant for the maximum
133 * signature size. */
Gilles Peskineb22a24b2019-11-05 16:56:39 +0100134#undef MBEDTLS_PK_SIGNATURE_MAX_SIZE
135#define MBEDTLS_PK_SIGNATURE_MAX_SIZE MBEDTLS_ECDSA_MAX_LEN
136#endif
Gilles Peskine54605652019-11-08 16:24:16 +0100137
138#if defined(MBEDTLS_USE_PSA_CRYPTO)
Gilles Peskine89d8c5c2019-11-26 17:01:59 +0100139#if PSA_SIGNATURE_MAX_SIZE > MBEDTLS_PK_SIGNATURE_MAX_SIZE
140/* PSA_SIGNATURE_MAX_SIZE is the maximum size of a signature made
Gilles Peskine54605652019-11-08 16:24:16 +0100141 * through the PSA API in the PSA representation. */
142#undef MBEDTLS_PK_SIGNATURE_MAX_SIZE
Gilles Peskine89d8c5c2019-11-26 17:01:59 +0100143#define MBEDTLS_PK_SIGNATURE_MAX_SIZE PSA_SIGNATURE_MAX_SIZE
Gilles Peskine54605652019-11-08 16:24:16 +0100144#endif
145
146#if PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE + 11 > MBEDTLS_PK_SIGNATURE_MAX_SIZE
147/* The Mbed TLS representation is different for ECDSA signatures:
Gilles Peskineb22a24b2019-11-05 16:56:39 +0100148 * PSA uses the raw concatenation of r and s,
149 * whereas Mbed TLS uses the ASN.1 representation (SEQUENCE of two INTEGERs).
150 * Add the overhead of ASN.1: up to (1+2) + 2 * (1+2+1) for the
151 * types, lengths (represented by up to 2 bytes), and potential leading
152 * zeros of the INTEGERs and the SEQUENCE. */
153#undef MBEDTLS_PK_SIGNATURE_MAX_SIZE
Gilles Peskine449bd832023-01-11 14:50:10 +0100154#define MBEDTLS_PK_SIGNATURE_MAX_SIZE (PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE + 11)
Gilles Peskineb22a24b2019-11-05 16:56:39 +0100155#endif
Gilles Peskine54605652019-11-08 16:24:16 +0100156#endif /* defined(MBEDTLS_USE_PSA_CRYPTO) */
Gilles Peskineda252be2019-11-05 16:23:49 +0100157
158/**
Valerio Setticf084ae2023-01-26 14:30:12 +0100159 * \brief The following defines are meant to list ECDSA capabilities of the
160 * PK module in a general way (without any reference to how this
161 * is achieved, which can be either through PSA driver or
162 * MBEDTLS_ECDSA_C)
163 */
164#if !defined(MBEDTLS_USE_PSA_CRYPTO)
165#if defined(MBEDTLS_ECDSA_C)
166#define MBEDTLS_PK_CAN_ECDSA_SIGN
167#define MBEDTLS_PK_CAN_ECDSA_VERIFY
168#endif
169#else /* MBEDTLS_USE_PSA_CRYPTO */
170#if defined(PSA_WANT_ALG_ECDSA)
171#if defined(PSA_WANT_KEY_TYPE_ECC_KEY_PAIR)
172#define MBEDTLS_PK_CAN_ECDSA_SIGN
173#endif
174#if defined(PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY)
175#define MBEDTLS_PK_CAN_ECDSA_VERIFY
176#endif
177#endif /* PSA_WANT_ALG_ECDSA */
178#endif /* MBEDTLS_USE_PSA_CRYPTO */
179
Valerio Setti178b5bd2023-02-13 10:04:28 +0100180#if defined(MBEDTLS_PK_CAN_ECDSA_VERIFY) || defined(MBEDTLS_PK_CAN_ECDSA_SIGN)
181#define MBEDTLS_PK_CAN_ECDSA_SOME
182#endif
183
Valerio Setticf084ae2023-01-26 14:30:12 +0100184/**
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200185 * \brief Types for interfacing with the debug module
186 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100187typedef enum {
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200188 MBEDTLS_PK_DEBUG_NONE = 0,
189 MBEDTLS_PK_DEBUG_MPI,
190 MBEDTLS_PK_DEBUG_ECP,
191} mbedtls_pk_debug_type;
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200192
193/**
194 * \brief Item to send to the debug module
195 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100196typedef struct mbedtls_pk_debug_item {
Mateusz Starzyk846f0212021-05-19 19:44:07 +0200197 mbedtls_pk_debug_type MBEDTLS_PRIVATE(type);
198 const char *MBEDTLS_PRIVATE(name);
199 void *MBEDTLS_PRIVATE(value);
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200200} mbedtls_pk_debug_item;
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200201
202/** Maximum number of item send for debugging, plus 1 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200203#define MBEDTLS_PK_DEBUG_MAX_ITEMS 3
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200204
205/**
Manuel Pégourié-Gonnard3fb5c5e2013-08-14 18:26:41 +0200206 * \brief Public key information and operations
Gilles Peskine2e9d65f2021-08-31 23:05:19 +0200207 *
208 * \note The library does not support custom pk info structures,
209 * only built-in structures returned by
210 * mbedtls_cipher_info_from_type().
Manuel Pégourié-Gonnardd73b3c12013-08-12 17:06:05 +0200211 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200212typedef struct mbedtls_pk_info_t mbedtls_pk_info_t;
Manuel Pégourié-Gonnardd73b3c12013-08-12 17:06:05 +0200213
214/**
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200215 * \brief Public key container
216 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100217typedef struct mbedtls_pk_context {
218 const mbedtls_pk_info_t *MBEDTLS_PRIVATE(pk_info); /**< Public key information */
219 void *MBEDTLS_PRIVATE(pk_ctx); /**< Underlying public key context */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200220} mbedtls_pk_context;
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200221
Manuel Pégourié-Gonnardaaa98142017-08-18 17:30:37 +0200222#if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200223/**
224 * \brief Context for resuming operations
225 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100226typedef struct {
227 const mbedtls_pk_info_t *MBEDTLS_PRIVATE(pk_info); /**< Public key information */
228 void *MBEDTLS_PRIVATE(rs_ctx); /**< Underlying restart context */
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200229} mbedtls_pk_restart_ctx;
Manuel Pégourié-Gonnardaaa98142017-08-18 17:30:37 +0200230#else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200231/* Now we can declare functions that take a pointer to that */
232typedef void mbedtls_pk_restart_ctx;
Manuel Pégourié-Gonnardaaa98142017-08-18 17:30:37 +0200233#endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200234
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200235#if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200236/**
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200237 * \brief Types for RSA-alt abstraction
238 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100239typedef int (*mbedtls_pk_rsa_alt_decrypt_func)(void *ctx, size_t *olen,
240 const unsigned char *input, unsigned char *output,
241 size_t output_max_len);
242typedef int (*mbedtls_pk_rsa_alt_sign_func)(void *ctx,
243 int (*f_rng)(void *, unsigned char *, size_t),
244 void *p_rng,
245 mbedtls_md_type_t md_alg, unsigned int hashlen,
246 const unsigned char *hash, unsigned char *sig);
247typedef size_t (*mbedtls_pk_rsa_alt_key_len_func)(void *ctx);
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200248#endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200249
250/**
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200251 * \brief Return information associated with the given PK type
252 *
Paul Bakkerdcbfdcc2013-09-10 16:16:50 +0200253 * \param pk_type PK type to search for.
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200254 *
255 * \return The PK info associated with the type or NULL if not found.
256 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100257const mbedtls_pk_info_t *mbedtls_pk_info_from_type(mbedtls_pk_type_t pk_type);
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200258
259/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500260 * \brief Initialize a #mbedtls_pk_context (as NONE).
261 *
262 * \param ctx The context to initialize.
263 * This must not be \c NULL.
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200264 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100265void mbedtls_pk_init(mbedtls_pk_context *ctx);
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200266
267/**
Andrzej Kurekb274f272019-02-05 05:06:35 -0500268 * \brief Free the components of a #mbedtls_pk_context.
Manuel Pégourié-Gonnard01a12c42018-10-31 10:28:01 +0100269 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500270 * \param ctx The context to clear. It must have been initialized.
271 * If this is \c NULL, this function does nothing.
272 *
Manuel Pégourié-Gonnard01a12c42018-10-31 10:28:01 +0100273 * \note For contexts that have been set up with
Manuel Pégourié-Gonnard69baf702018-11-06 09:34:30 +0100274 * mbedtls_pk_setup_opaque(), this does not free the underlying
Gilles Peskine11392492019-05-27 14:53:19 +0200275 * PSA key and you still need to call psa_destroy_key()
Manuel Pégourié-Gonnard01a12c42018-10-31 10:28:01 +0100276 * independently if you want to destroy that key.
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200277 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100278void mbedtls_pk_free(mbedtls_pk_context *ctx);
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200279
Manuel Pégourié-Gonnardaaa98142017-08-18 17:30:37 +0200280#if defined(MBEDTLS_ECDSA_C) && defined(MBEDTLS_ECP_RESTARTABLE)
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200281/**
282 * \brief Initialize a restart context
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500283 *
284 * \param ctx The context to initialize.
285 * This must not be \c NULL.
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200286 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100287void mbedtls_pk_restart_init(mbedtls_pk_restart_ctx *ctx);
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200288
289/**
290 * \brief Free the components of a restart context
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500291 *
292 * \param ctx The context to clear. It must have been initialized.
293 * If this is \c NULL, this function does nothing.
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200294 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100295void mbedtls_pk_restart_free(mbedtls_pk_restart_ctx *ctx);
Manuel Pégourié-Gonnardaaa98142017-08-18 17:30:37 +0200296#endif /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200297
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200298/**
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200299 * \brief Initialize a PK context with the information given
300 * and allocates the type-specific PK subcontext.
301 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500302 * \param ctx Context to initialize. It must not have been set
303 * up yet (type #MBEDTLS_PK_NONE).
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200304 * \param info Information to use
305 *
306 * \return 0 on success,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200307 * MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input,
Manuel Pégourié-Gonnard6a8ca332015-05-28 09:33:39 +0200308 * MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200309 *
Paul Bakker42099c32014-01-27 11:45:49 +0100310 * \note For contexts holding an RSA-alt key, use
Manuel Pégourié-Gonnardd9e6a3a2015-05-14 19:41:36 +0200311 * \c mbedtls_pk_setup_rsa_alt() instead.
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200312 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100313int mbedtls_pk_setup(mbedtls_pk_context *ctx, const mbedtls_pk_info_t *info);
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200314
Manuel Pégourié-Gonnard20678b22018-10-22 12:11:15 +0200315#if defined(MBEDTLS_USE_PSA_CRYPTO)
316/**
Gilles Peskine11392492019-05-27 14:53:19 +0200317 * \brief Initialize a PK context to wrap a PSA key.
Manuel Pégourié-Gonnard20678b22018-10-22 12:11:15 +0200318 *
Manuel Pégourié-Gonnard392dc042018-11-13 10:48:23 +0100319 * \note This function replaces mbedtls_pk_setup() for contexts
Gilles Peskine11392492019-05-27 14:53:19 +0200320 * that wrap a (possibly opaque) PSA key instead of
Manuel Pégourié-Gonnard392dc042018-11-13 10:48:23 +0100321 * storing and manipulating the key material directly.
322 *
323 * \param ctx The context to initialize. It must be empty (type NONE).
Neil Armstrongb3547422022-03-22 10:22:28 +0100324 * \param key The PSA key to wrap, which must hold an ECC or RSA key
325 * pair (see notes below).
Manuel Pégourié-Gonnard20678b22018-10-22 12:11:15 +0200326 *
Gilles Peskine11392492019-05-27 14:53:19 +0200327 * \note The wrapped key must remain valid as long as the
Manuel Pégourié-Gonnard01a12c42018-10-31 10:28:01 +0100328 * wrapping PK context is in use, that is at least between
329 * the point this function is called and the point
330 * mbedtls_pk_free() is called on this context. The wrapped
Gilles Peskine11392492019-05-27 14:53:19 +0200331 * key might then be independently used or destroyed.
Manuel Pégourié-Gonnard01a12c42018-10-31 10:28:01 +0100332 *
Neil Armstrongb3547422022-03-22 10:22:28 +0100333 * \note This function is currently only available for ECC or RSA
334 * key pairs (that is, keys containing private key material).
Manuel Pégourié-Gonnard392dc042018-11-13 10:48:23 +0100335 * Support for other key types may be added later.
336 *
337 * \return \c 0 on success.
Manuel Pégourié-Gonnard920c0632018-10-31 10:57:29 +0100338 * \return #MBEDTLS_ERR_PK_BAD_INPUT_DATA on invalid input
Ronald Croncf56a0a2020-08-04 09:51:30 +0200339 * (context already used, invalid key identifier).
Manuel Pégourié-Gonnard920c0632018-10-31 10:57:29 +0100340 * \return #MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE if the key is not an
Manuel Pégourié-Gonnard392dc042018-11-13 10:48:23 +0100341 * ECC key pair.
Manuel Pégourié-Gonnard920c0632018-10-31 10:57:29 +0100342 * \return #MBEDTLS_ERR_PK_ALLOC_FAILED on allocation failure.
Manuel Pégourié-Gonnard20678b22018-10-22 12:11:15 +0200343 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100344int mbedtls_pk_setup_opaque(mbedtls_pk_context *ctx,
345 const mbedtls_svc_key_id_t key);
Manuel Pégourié-Gonnard20678b22018-10-22 12:11:15 +0200346#endif /* MBEDTLS_USE_PSA_CRYPTO */
347
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200348#if defined(MBEDTLS_PK_RSA_ALT_SUPPORT)
Manuel Pégourié-Gonnardab466942013-08-15 11:30:27 +0200349/**
Paul Bakker4fc090a2013-09-18 15:43:25 +0200350 * \brief Initialize an RSA-alt context
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200351 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500352 * \param ctx Context to initialize. It must not have been set
353 * up yet (type #MBEDTLS_PK_NONE).
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200354 * \param key RSA key pointer
355 * \param decrypt_func Decryption function
356 * \param sign_func Signing function
Manuel Pégourié-Gonnard01488752014-04-03 22:09:18 +0200357 * \param key_len_func Function returning key length in bytes
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200358 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200359 * \return 0 on success, or MBEDTLS_ERR_PK_BAD_INPUT_DATA if the
Manuel Pégourié-Gonnard12c1ff02013-08-21 12:28:31 +0200360 * context wasn't already initialized as RSA_ALT.
361 *
Manuel Pégourié-Gonnardd9e6a3a2015-05-14 19:41:36 +0200362 * \note This function replaces \c mbedtls_pk_setup() for RSA-alt.
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200363 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100364int mbedtls_pk_setup_rsa_alt(mbedtls_pk_context *ctx, void *key,
365 mbedtls_pk_rsa_alt_decrypt_func decrypt_func,
366 mbedtls_pk_rsa_alt_sign_func sign_func,
367 mbedtls_pk_rsa_alt_key_len_func key_len_func);
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200368#endif /* MBEDTLS_PK_RSA_ALT_SUPPORT */
Manuel Pégourié-Gonnard12e0ed92013-07-04 13:31:32 +0200369
370/**
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200371 * \brief Get the size in bits of the underlying key
372 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500373 * \param ctx The context to query. It must have been initialized.
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200374 *
375 * \return Key size in bits, or 0 on error
376 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100377size_t mbedtls_pk_get_bitlen(const mbedtls_pk_context *ctx);
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200378
379/**
Manuel Pégourié-Gonnard0d420492013-08-21 16:14:26 +0200380 * \brief Get the length in bytes of the underlying key
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500381 *
382 * \param ctx The context to query. It must have been initialized.
Manuel Pégourié-Gonnard0d420492013-08-21 16:14:26 +0200383 *
Paul Bakker4fc090a2013-09-18 15:43:25 +0200384 * \return Key length in bytes, or 0 on error
Manuel Pégourié-Gonnard0d420492013-08-21 16:14:26 +0200385 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100386static inline size_t mbedtls_pk_get_len(const mbedtls_pk_context *ctx)
Manuel Pégourié-Gonnard0d420492013-08-21 16:14:26 +0200387{
Gilles Peskine449bd832023-01-11 14:50:10 +0100388 return (mbedtls_pk_get_bitlen(ctx) + 7) / 8;
Manuel Pégourié-Gonnard0d420492013-08-21 16:14:26 +0200389}
390
391/**
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200392 * \brief Tell if a context can do the operation given by type
393 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500394 * \param ctx The context to query. It must have been initialized.
395 * \param type The desired type.
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200396 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500397 * \return 1 if the context can do operations on the given type.
398 * \return 0 if the context cannot do the operations on the given
399 * type. This is always the case for a context that has
400 * been initialized but not set up, or that has been
401 * cleared with mbedtls_pk_free().
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200402 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100403int mbedtls_pk_can_do(const mbedtls_pk_context *ctx, mbedtls_pk_type_t type);
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200404
Neil Armstrong0b529582022-05-11 10:10:20 +0200405#if defined(MBEDTLS_USE_PSA_CRYPTO)
406/**
Neil Armstrongcec133a2022-05-17 11:56:01 +0200407 * \brief Tell if context can do the operation given by PSA algorithm
Neil Armstrong0b529582022-05-11 10:10:20 +0200408 *
409 * \param ctx The context to query. It must have been initialized.
410 * \param alg PSA algorithm to check against, the following are allowed:
411 * PSA_ALG_RSA_PKCS1V15_SIGN(hash),
412 * PSA_ALG_RSA_PSS(hash),
413 * PSA_ALG_RSA_PKCS1V15_CRYPT,
414 * PSA_ALG_ECDSA(hash),
415 * PSA_ALG_ECDH, where hash is a specific hash.
Neil Armstrong408f6a62022-05-17 14:23:20 +0200416 * \param usage PSA usage flag to check against, must be composed of:
417 * PSA_KEY_USAGE_SIGN_HASH
418 * PSA_KEY_USAGE_DECRYPT
419 * PSA_KEY_USAGE_DERIVE.
420 * Context key must match all passed usage flags.
Neil Armstrong0b529582022-05-11 10:10:20 +0200421 *
Neil Armstrongb2f2b022022-05-20 12:00:56 +0200422 * \warning Since the set of allowed algorithms and usage flags may be
423 * expanded in the future, the return value \c 0 should not
424 * be taken in account for non-allowed algorithms and usage
425 * flags.
426 *
Neil Armstrong0b529582022-05-11 10:10:20 +0200427 * \return 1 if the context can do operations on the given type.
428 * \return 0 if the context cannot do the operations on the given
Neil Armstrongb2f2b022022-05-20 12:00:56 +0200429 * type, for non-allowed algorithms and usage flags, or
430 * for a context that has been initialized but not set up
431 * or that has been cleared with mbedtls_pk_free().
Neil Armstrong0b529582022-05-11 10:10:20 +0200432 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100433int mbedtls_pk_can_do_ext(const mbedtls_pk_context *ctx, psa_algorithm_t alg,
434 psa_key_usage_t usage);
Neil Armstrong0b529582022-05-11 10:10:20 +0200435#endif /* MBEDTLS_USE_PSA_CRYPTO */
436
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200437/**
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200438 * \brief Verify signature (including padding if relevant).
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200439 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500440 * \param ctx The PK context to use. It must have been set up.
Gilles Peskine9dbbc292021-06-22 18:28:13 +0200441 * \param md_alg Hash algorithm used.
442 * This can be #MBEDTLS_MD_NONE if the signature algorithm
443 * does not rely on a hash algorithm (non-deterministic
444 * ECDSA, RSA PKCS#1 v1.5).
445 * For PKCS#1 v1.5, if \p md_alg is #MBEDTLS_MD_NONE, then
446 * \p hash is the DigestInfo structure used by RFC 8017
447 * &sect;9.2 steps 3&ndash;6. If \p md_alg is a valid hash
448 * algorithm then \p hash is the digest itself, and this
449 * function calculates the DigestInfo encoding internally.
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200450 * \param hash Hash of the message to sign
Gilles Peskine9dbbc292021-06-22 18:28:13 +0200451 * \param hash_len Hash length
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200452 * \param sig Signature to verify
453 * \param sig_len Signature length
454 *
455 * \return 0 on success (signature is valid),
Gilles Peskine5114d3e2018-03-30 07:12:15 +0200456 * #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid
457 * signature in sig but its length is less than \p siglen,
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200458 * or a specific error code.
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200459 *
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200460 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200461 * Use \c mbedtls_pk_verify_ext( MBEDTLS_PK_RSASSA_PSS, ... )
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200462 * to verify RSASSA_PSS signatures.
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200463 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100464int mbedtls_pk_verify(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
465 const unsigned char *hash, size_t hash_len,
466 const unsigned char *sig, size_t sig_len);
Manuel Pégourié-Gonnardb3d91872013-08-14 15:56:19 +0200467
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200468/**
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200469 * \brief Restartable version of \c mbedtls_pk_verify()
470 *
471 * \note Performs the same job as \c mbedtls_pk_verify(), but can
472 * return early and restart according to the limit set with
473 * \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
474 * operations. For RSA, same as \c mbedtls_pk_verify().
475 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500476 * \param ctx The PK context to use. It must have been set up.
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200477 * \param md_alg Hash algorithm used (see notes)
478 * \param hash Hash of the message to sign
479 * \param hash_len Hash length or 0 (see notes)
480 * \param sig Signature to verify
481 * \param sig_len Signature length
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200482 * \param rs_ctx Restart context (NULL to disable restart)
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200483 *
484 * \return See \c mbedtls_pk_verify(), or
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200485 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200486 * operations was reached: see \c mbedtls_ecp_set_max_ops().
487 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100488int mbedtls_pk_verify_restartable(mbedtls_pk_context *ctx,
489 mbedtls_md_type_t md_alg,
490 const unsigned char *hash, size_t hash_len,
491 const unsigned char *sig, size_t sig_len,
492 mbedtls_pk_restart_ctx *rs_ctx);
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200493
494/**
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200495 * \brief Verify signature, with options.
496 * (Includes verification of the padding depending on type.)
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200497 *
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200498 * \param type Signature type (inc. possible padding type) to verify
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200499 * \param options Pointer to type-specific options, or NULL
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500500 * \param ctx The PK context to use. It must have been set up.
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200501 * \param md_alg Hash algorithm used (see notes)
502 * \param hash Hash of the message to sign
503 * \param hash_len Hash length or 0 (see notes)
504 * \param sig Signature to verify
505 * \param sig_len Signature length
506 *
507 * \return 0 on success (signature is valid),
Gilles Peskine5114d3e2018-03-30 07:12:15 +0200508 * #MBEDTLS_ERR_PK_TYPE_MISMATCH if the PK context can't be
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200509 * used for this type of signatures,
Gilles Peskine5114d3e2018-03-30 07:12:15 +0200510 * #MBEDTLS_ERR_PK_SIG_LEN_MISMATCH if there is a valid
511 * signature in sig but its length is less than \p siglen,
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200512 * or a specific error code.
513 *
514 * \note If hash_len is 0, then the length associated with md_alg
515 * is used instead, or an error returned if it is invalid.
516 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200517 * \note md_alg may be MBEDTLS_MD_NONE, only if hash_len != 0
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200518 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200519 * \note If type is MBEDTLS_PK_RSASSA_PSS, then options must point
520 * to a mbedtls_pk_rsassa_pss_options structure,
Manuel Pégourié-Gonnarda6e02912022-12-21 09:59:33 +0100521 * otherwise it must be NULL. Note that if
522 * #MBEDTLS_USE_PSA_CRYPTO is defined, the salt length is not
523 * verified as PSA_ALG_RSA_PSS_ANY_SALT is used.
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200524 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100525int mbedtls_pk_verify_ext(mbedtls_pk_type_t type, const void *options,
526 mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
527 const unsigned char *hash, size_t hash_len,
528 const unsigned char *sig, size_t sig_len);
Manuel Pégourié-Gonnard20422e92014-06-05 13:41:44 +0200529
530/**
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200531 * \brief Make signature, including padding if relevant.
Manuel Pégourié-Gonnard8df27692013-08-21 10:34:38 +0200532 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500533 * \param ctx The PK context to use. It must have been set up
534 * with a private key.
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200535 * \param md_alg Hash algorithm used (see notes)
Manuel Pégourié-Gonnard8df27692013-08-21 10:34:38 +0200536 * \param hash Hash of the message to sign
Gilles Peskine9dbbc292021-06-22 18:28:13 +0200537 * \param hash_len Hash length
Gilles Peskineda252be2019-11-05 16:23:49 +0100538 * \param sig Place to write the signature.
539 * It must have enough room for the signature.
540 * #MBEDTLS_PK_SIGNATURE_MAX_SIZE is always enough.
541 * You may use a smaller buffer if it is large enough
542 * given the key type.
Gilles Peskinef00f1522021-06-22 00:09:00 +0200543 * \param sig_size The size of the \p sig buffer in bytes.
Gilles Peskineda252be2019-11-05 16:23:49 +0100544 * \param sig_len On successful return,
545 * the number of bytes written to \p sig.
Manuel Pégourié-Gonnard34d37562021-06-15 11:29:26 +0200546 * \param f_rng RNG function, must not be \c NULL.
Manuel Pégourié-Gonnard8df27692013-08-21 10:34:38 +0200547 * \param p_rng RNG parameter
548 *
549 * \return 0 on success, or a specific error code.
Manuel Pégourié-Gonnardbfe32ef2013-08-22 14:55:30 +0200550 *
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200551 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
552 * There is no interface in the PK module to make RSASSA-PSS
553 * signatures yet.
554 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200555 * \note For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0.
556 * For ECDSA, md_alg may never be MBEDTLS_MD_NONE.
Manuel Pégourié-Gonnard8df27692013-08-21 10:34:38 +0200557 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100558int mbedtls_pk_sign(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
559 const unsigned char *hash, size_t hash_len,
560 unsigned char *sig, size_t sig_size, size_t *sig_len,
561 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);
Manuel Pégourié-Gonnard8df27692013-08-21 10:34:38 +0200562
Jerry Yubc18c232022-03-12 19:40:29 +0800563#if defined(MBEDTLS_PSA_CRYPTO_C)
Manuel Pégourié-Gonnard8df27692013-08-21 10:34:38 +0200564/**
Jerry Yu406cf272022-03-22 11:33:42 +0800565 * \brief Make signature given a signature type.
Jerry Yud69439a2022-02-24 15:52:15 +0800566 *
Jerry Yu8beb9e12022-03-12 16:23:53 +0800567 * \param pk_type Signature type.
Jerry Yud69439a2022-02-24 15:52:15 +0800568 * \param ctx The PK context to use. It must have been set up
569 * with a private key.
570 * \param md_alg Hash algorithm used (see notes)
571 * \param hash Hash of the message to sign
572 * \param hash_len Hash length
573 * \param sig Place to write the signature.
574 * It must have enough room for the signature.
575 * #MBEDTLS_PK_SIGNATURE_MAX_SIZE is always enough.
576 * You may use a smaller buffer if it is large enough
577 * given the key type.
578 * \param sig_size The size of the \p sig buffer in bytes.
579 * \param sig_len On successful return,
580 * the number of bytes written to \p sig.
581 * \param f_rng RNG function, must not be \c NULL.
582 * \param p_rng RNG parameter
583 *
584 * \return 0 on success, or a specific error code.
585 *
Jerry Yue6e73d62022-03-24 13:05:08 +0800586 * \note When \p pk_type is #MBEDTLS_PK_RSASSA_PSS,
587 * see #PSA_ALG_RSA_PSS for a description of PSS options used.
Jerry Yud69439a2022-02-24 15:52:15 +0800588 *
589 * \note For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0.
590 * For ECDSA, md_alg may never be MBEDTLS_MD_NONE.
591 *
Jerry Yud69439a2022-02-24 15:52:15 +0800592 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100593int mbedtls_pk_sign_ext(mbedtls_pk_type_t pk_type,
594 mbedtls_pk_context *ctx,
595 mbedtls_md_type_t md_alg,
596 const unsigned char *hash, size_t hash_len,
597 unsigned char *sig, size_t sig_size, size_t *sig_len,
598 int (*f_rng)(void *, unsigned char *, size_t),
599 void *p_rng);
Jerry Yubc18c232022-03-12 19:40:29 +0800600#endif /* MBEDTLS_PSA_CRYPTO_C */
Jerry Yud69439a2022-02-24 15:52:15 +0800601
602/**
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200603 * \brief Restartable version of \c mbedtls_pk_sign()
604 *
605 * \note Performs the same job as \c mbedtls_pk_sign(), but can
606 * return early and restart according to the limit set with
607 * \c mbedtls_ecp_set_max_ops() to reduce blocking for ECC
608 * operations. For RSA, same as \c mbedtls_pk_sign().
609 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500610 * \param ctx The PK context to use. It must have been set up
611 * with a private key.
Gilles Peskine9db14fa2019-11-08 18:37:19 +0100612 * \param md_alg Hash algorithm used (see notes for mbedtls_pk_sign())
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200613 * \param hash Hash of the message to sign
Gilles Peskine9dbbc292021-06-22 18:28:13 +0200614 * \param hash_len Hash length
Gilles Peskine9db14fa2019-11-08 18:37:19 +0100615 * \param sig Place to write the signature.
616 * It must have enough room for the signature.
617 * #MBEDTLS_PK_SIGNATURE_MAX_SIZE is always enough.
618 * You may use a smaller buffer if it is large enough
619 * given the key type.
Gilles Peskinef00f1522021-06-22 00:09:00 +0200620 * \param sig_size The size of the \p sig buffer in bytes.
Gilles Peskine9db14fa2019-11-08 18:37:19 +0100621 * \param sig_len On successful return,
622 * the number of bytes written to \p sig.
Manuel Pégourié-Gonnard34d37562021-06-15 11:29:26 +0200623 * \param f_rng RNG function, must not be \c NULL.
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200624 * \param p_rng RNG parameter
Manuel Pégourié-Gonnard15d7df22017-08-17 14:33:31 +0200625 * \param rs_ctx Restart context (NULL to disable restart)
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200626 *
Gilles Peskine9db14fa2019-11-08 18:37:19 +0100627 * \return See \c mbedtls_pk_sign().
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200628 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200629 * operations was reached: see \c mbedtls_ecp_set_max_ops().
630 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100631int mbedtls_pk_sign_restartable(mbedtls_pk_context *ctx,
632 mbedtls_md_type_t md_alg,
633 const unsigned char *hash, size_t hash_len,
634 unsigned char *sig, size_t sig_size, size_t *sig_len,
635 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
636 mbedtls_pk_restart_ctx *rs_ctx);
Manuel Pégourié-Gonnard82cb27b2017-05-03 10:59:45 +0200637
638/**
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200639 * \brief Decrypt message (including padding if relevant).
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200640 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500641 * \param ctx The PK context to use. It must have been set up
642 * with a private key.
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200643 * \param input Input to decrypt
644 * \param ilen Input size
645 * \param output Decrypted output
Paul Bakker4fc090a2013-09-18 15:43:25 +0200646 * \param olen Decrypted message length
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200647 * \param osize Size of the output buffer
Manuel Pégourié-Gonnard34d37562021-06-15 11:29:26 +0200648 * \param f_rng RNG function, must not be \c NULL.
Paul Bakkerdcbfdcc2013-09-10 16:16:50 +0200649 * \param p_rng RNG parameter
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200650 *
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200651 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
652 *
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200653 * \return 0 on success, or a specific error code.
654 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100655int mbedtls_pk_decrypt(mbedtls_pk_context *ctx,
656 const unsigned char *input, size_t ilen,
657 unsigned char *output, size_t *olen, size_t osize,
658 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200659
660/**
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200661 * \brief Encrypt message (including padding if relevant).
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200662 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500663 * \param ctx The PK context to use. It must have been set up.
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200664 * \param input Message to encrypt
665 * \param ilen Message size
666 * \param output Encrypted output
667 * \param olen Encrypted output length
668 * \param osize Size of the output buffer
Manuel Pégourié-Gonnard34d37562021-06-15 11:29:26 +0200669 * \param f_rng RNG function, must not be \c NULL.
Paul Bakkerdcbfdcc2013-09-10 16:16:50 +0200670 * \param p_rng RNG parameter
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200671 *
Manuel Pégourié-Gonnard34d37562021-06-15 11:29:26 +0200672 * \note \p f_rng is used for padding generation.
673 *
Manuel Pégourié-Gonnardd543a582014-06-25 14:04:36 +0200674 * \note For RSA keys, the default padding type is PKCS#1 v1.5.
675 *
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200676 * \return 0 on success, or a specific error code.
677 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100678int mbedtls_pk_encrypt(mbedtls_pk_context *ctx,
679 const unsigned char *input, size_t ilen,
680 unsigned char *output, size_t *olen, size_t osize,
681 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);
Manuel Pégourié-Gonnarda2d3f222013-08-21 11:51:08 +0200682
683/**
Manuel Pégourié-Gonnard70bdadf2014-11-06 16:51:20 +0100684 * \brief Check if a public-private pair of keys matches.
685 *
686 * \param pub Context holding a public key.
687 * \param prv Context holding a private (and public) key.
Manuel Pégourié-Gonnard39be1412021-06-15 11:29:26 +0200688 * \param f_rng RNG function, must not be \c NULL.
689 * \param p_rng RNG parameter
Manuel Pégourié-Gonnard70bdadf2014-11-06 16:51:20 +0100690 *
Manuel Pégourié-Gonnardeaeb7b22018-10-24 12:37:44 +0200691 * \return \c 0 on success (keys were checked and match each other).
692 * \return #MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE if the keys could not
693 * be checked - in that case they may or may not match.
694 * \return #MBEDTLS_ERR_PK_BAD_INPUT_DATA if a context is invalid.
695 * \return Another non-zero value if the keys do not match.
Manuel Pégourié-Gonnard70bdadf2014-11-06 16:51:20 +0100696 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100697int mbedtls_pk_check_pair(const mbedtls_pk_context *pub,
698 const mbedtls_pk_context *prv,
699 int (*f_rng)(void *, unsigned char *, size_t),
700 void *p_rng);
Manuel Pégourié-Gonnard70bdadf2014-11-06 16:51:20 +0100701
702/**
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200703 * \brief Export debug information
704 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500705 * \param ctx The PK context to use. It must have been initialized.
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200706 * \param items Place to write debug items
707 *
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200708 * \return 0 on success or MBEDTLS_ERR_PK_BAD_INPUT_DATA
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200709 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100710int mbedtls_pk_debug(const mbedtls_pk_context *ctx, mbedtls_pk_debug_item *items);
Manuel Pégourié-Gonnardc6ac8872013-08-14 18:04:18 +0200711
Manuel Pégourié-Gonnard3fb5c5e2013-08-14 18:26:41 +0200712/**
713 * \brief Access the type name
714 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500715 * \param ctx The PK context to use. It must have been initialized.
Manuel Pégourié-Gonnard3fb5c5e2013-08-14 18:26:41 +0200716 *
717 * \return Type name on success, or "invalid PK"
718 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100719const char *mbedtls_pk_get_name(const mbedtls_pk_context *ctx);
Manuel Pégourié-Gonnard3fb5c5e2013-08-14 18:26:41 +0200720
Manuel Pégourié-Gonnard8053da42013-09-11 22:28:30 +0200721/**
Paul Bakker4fc090a2013-09-18 15:43:25 +0200722 * \brief Get the key type
Manuel Pégourié-Gonnard8053da42013-09-11 22:28:30 +0200723 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500724 * \param ctx The PK context to use. It must have been initialized.
Manuel Pégourié-Gonnard8053da42013-09-11 22:28:30 +0200725 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500726 * \return Type on success.
727 * \return #MBEDTLS_PK_NONE for a context that has not been set up.
Manuel Pégourié-Gonnard8053da42013-09-11 22:28:30 +0200728 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100729mbedtls_pk_type_t mbedtls_pk_get_type(const mbedtls_pk_context *ctx);
Manuel Pégourié-Gonnard8053da42013-09-11 22:28:30 +0200730
Manuel Pégourié-Gonnard22e84de2022-06-10 09:48:38 +0200731#if defined(MBEDTLS_RSA_C)
732/**
733 * Quick access to an RSA context inside a PK context.
734 *
735 * \warning This function can only be used when the type of the context, as
736 * returned by mbedtls_pk_get_type(), is #MBEDTLS_PK_RSA.
737 * Ensuring that is the caller's responsibility.
738 * Alternatively, you can check whether this function returns NULL.
739 *
740 * \return The internal RSA context held by the PK context, or NULL.
741 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100742static inline mbedtls_rsa_context *mbedtls_pk_rsa(const mbedtls_pk_context pk)
Manuel Pégourié-Gonnard22e84de2022-06-10 09:48:38 +0200743{
Gilles Peskine449bd832023-01-11 14:50:10 +0100744 switch (mbedtls_pk_get_type(&pk)) {
Manuel Pégourié-Gonnard4cfaae52022-06-23 09:43:39 +0200745 case MBEDTLS_PK_RSA:
Gilles Peskine449bd832023-01-11 14:50:10 +0100746 return (mbedtls_rsa_context *) (pk).MBEDTLS_PRIVATE(pk_ctx);
Manuel Pégourié-Gonnard4cfaae52022-06-23 09:43:39 +0200747 default:
Gilles Peskine449bd832023-01-11 14:50:10 +0100748 return NULL;
Manuel Pégourié-Gonnard4cfaae52022-06-23 09:43:39 +0200749 }
Manuel Pégourié-Gonnard22e84de2022-06-10 09:48:38 +0200750}
751#endif /* MBEDTLS_RSA_C */
752
753#if defined(MBEDTLS_ECP_C)
754/**
755 * Quick access to an EC context inside a PK context.
756 *
757 * \warning This function can only be used when the type of the context, as
758 * returned by mbedtls_pk_get_type(), is #MBEDTLS_PK_ECKEY,
759 * #MBEDTLS_PK_ECKEY_DH, or #MBEDTLS_PK_ECDSA.
760 * Ensuring that is the caller's responsibility.
761 * Alternatively, you can check whether this function returns NULL.
762 *
763 * \return The internal EC context held by the PK context, or NULL.
764 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100765static inline mbedtls_ecp_keypair *mbedtls_pk_ec(const mbedtls_pk_context pk)
Manuel Pégourié-Gonnard22e84de2022-06-10 09:48:38 +0200766{
Gilles Peskine449bd832023-01-11 14:50:10 +0100767 switch (mbedtls_pk_get_type(&pk)) {
Manuel Pégourié-Gonnard4cfaae52022-06-23 09:43:39 +0200768 case MBEDTLS_PK_ECKEY:
769 case MBEDTLS_PK_ECKEY_DH:
770 case MBEDTLS_PK_ECDSA:
Gilles Peskine449bd832023-01-11 14:50:10 +0100771 return (mbedtls_ecp_keypair *) (pk).MBEDTLS_PRIVATE(pk_ctx);
Manuel Pégourié-Gonnard4cfaae52022-06-23 09:43:39 +0200772 default:
Gilles Peskine449bd832023-01-11 14:50:10 +0100773 return NULL;
Manuel Pégourié-Gonnard4cfaae52022-06-23 09:43:39 +0200774 }
Manuel Pégourié-Gonnard22e84de2022-06-10 09:48:38 +0200775}
776#endif /* MBEDTLS_ECP_C */
777
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200778#if defined(MBEDTLS_PK_PARSE_C)
Paul Bakkerff3a5182013-09-16 22:42:19 +0200779/** \ingroup pk_module */
Paul Bakker1a7550a2013-09-15 13:01:22 +0200780/**
Manuel Pégourié-Gonnard43b37cb2015-05-12 11:20:10 +0200781 * \brief Parse a private key in PEM or DER format
Paul Bakker1a7550a2013-09-15 13:01:22 +0200782 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500783 * \param ctx The PK context to fill. It must have been initialized
784 * but not set up.
785 * \param key Input buffer to parse.
786 * The buffer must contain the input exactly, with no
787 * extra trailing material. For PEM, the buffer must
788 * contain a null-terminated string.
789 * \param keylen Size of \b key in bytes.
790 * For PEM data, this includes the terminating null byte,
791 * so \p keylen must be equal to `strlen(key) + 1`.
792 * \param pwd Optional password for decryption.
793 * Pass \c NULL if expecting a non-encrypted key.
794 * Pass a string of \p pwdlen bytes if expecting an encrypted
795 * key; a non-encrypted key will also be accepted.
796 * The empty password is not supported.
797 * \param pwdlen Size of the password in bytes.
798 * Ignored if \p pwd is \c NULL.
Manuel Pégourié-Gonnard84dea012021-06-15 11:29:26 +0200799 * \param f_rng RNG function, must not be \c NULL. Used for blinding.
800 * \param p_rng RNG parameter
Paul Bakker1a7550a2013-09-15 13:01:22 +0200801 *
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100802 * \note On entry, ctx must be empty, either freshly initialised
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200803 * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
804 * specific key type, check the result with mbedtls_pk_can_do().
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100805 *
806 * \note The key is also checked for correctness.
807 *
Paul Bakker1a7550a2013-09-15 13:01:22 +0200808 * \return 0 if successful, or a specific PK or PEM error code
809 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100810int mbedtls_pk_parse_key(mbedtls_pk_context *ctx,
811 const unsigned char *key, size_t keylen,
812 const unsigned char *pwd, size_t pwdlen,
813 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);
Paul Bakker1a7550a2013-09-15 13:01:22 +0200814
Paul Bakkerff3a5182013-09-16 22:42:19 +0200815/** \ingroup pk_module */
Paul Bakker1a7550a2013-09-15 13:01:22 +0200816/**
Manuel Pégourié-Gonnard43b37cb2015-05-12 11:20:10 +0200817 * \brief Parse a public key in PEM or DER format
Paul Bakker1a7550a2013-09-15 13:01:22 +0200818 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500819 * \param ctx The PK context to fill. It must have been initialized
820 * but not set up.
821 * \param key Input buffer to parse.
822 * The buffer must contain the input exactly, with no
823 * extra trailing material. For PEM, the buffer must
824 * contain a null-terminated string.
825 * \param keylen Size of \b key in bytes.
826 * For PEM data, this includes the terminating null byte,
827 * so \p keylen must be equal to `strlen(key) + 1`.
Paul Bakker1a7550a2013-09-15 13:01:22 +0200828 *
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100829 * \note On entry, ctx must be empty, either freshly initialised
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200830 * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
831 * specific key type, check the result with mbedtls_pk_can_do().
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100832 *
833 * \note The key is also checked for correctness.
834 *
Paul Bakker1a7550a2013-09-15 13:01:22 +0200835 * \return 0 if successful, or a specific PK or PEM error code
836 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100837int mbedtls_pk_parse_public_key(mbedtls_pk_context *ctx,
838 const unsigned char *key, size_t keylen);
Paul Bakker1a7550a2013-09-15 13:01:22 +0200839
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200840#if defined(MBEDTLS_FS_IO)
Paul Bakkerff3a5182013-09-16 22:42:19 +0200841/** \ingroup pk_module */
Paul Bakker1a7550a2013-09-15 13:01:22 +0200842/**
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200843 * \brief Load and parse a private key
844 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500845 * \param ctx The PK context to fill. It must have been initialized
846 * but not set up.
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200847 * \param path filename to read the private key from
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500848 * \param password Optional password to decrypt the file.
849 * Pass \c NULL if expecting a non-encrypted key.
850 * Pass a null-terminated string if expecting an encrypted
851 * key; a non-encrypted key will also be accepted.
852 * The empty password is not supported.
Manuel Pégourié-Gonnard84dea012021-06-15 11:29:26 +0200853 * \param f_rng RNG function, must not be \c NULL. Used for blinding.
854 * \param p_rng RNG parameter
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200855 *
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100856 * \note On entry, ctx must be empty, either freshly initialised
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200857 * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a
858 * specific key type, check the result with mbedtls_pk_can_do().
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100859 *
860 * \note The key is also checked for correctness.
861 *
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200862 * \return 0 if successful, or a specific PK or PEM error code
863 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100864int mbedtls_pk_parse_keyfile(mbedtls_pk_context *ctx,
865 const char *path, const char *password,
866 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200867
Paul Bakkerff3a5182013-09-16 22:42:19 +0200868/** \ingroup pk_module */
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200869/**
Paul Bakker1a7550a2013-09-15 13:01:22 +0200870 * \brief Load and parse a public key
871 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500872 * \param ctx The PK context to fill. It must have been initialized
873 * but not set up.
Simon Butcher295639b2016-05-10 19:39:36 +0100874 * \param path filename to read the public key from
Paul Bakker1a7550a2013-09-15 13:01:22 +0200875 *
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100876 * \note On entry, ctx must be empty, either freshly initialised
Simon Butcher295639b2016-05-10 19:39:36 +0100877 * with mbedtls_pk_init() or reset with mbedtls_pk_free(). If
878 * you need a specific key type, check the result with
879 * mbedtls_pk_can_do().
Manuel Pégourié-Gonnarde3b3d192014-03-13 19:21:49 +0100880 *
881 * \note The key is also checked for correctness.
882 *
Paul Bakker1a7550a2013-09-15 13:01:22 +0200883 * \return 0 if successful, or a specific PK or PEM error code
884 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100885int mbedtls_pk_parse_public_keyfile(mbedtls_pk_context *ctx, const char *path);
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200886#endif /* MBEDTLS_FS_IO */
887#endif /* MBEDTLS_PK_PARSE_C */
Paul Bakker1a7550a2013-09-15 13:01:22 +0200888
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200889#if defined(MBEDTLS_PK_WRITE_C)
Paul Bakker1a7550a2013-09-15 13:01:22 +0200890/**
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200891 * \brief Write a private key to a PKCS#1 or SEC1 DER structure
892 * Note: data is written at the end of the buffer! Use the
893 * return value to determine where you should start
894 * using the buffer
895 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500896 * \param ctx PK context which must contain a valid private key.
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200897 * \param buf buffer to write to
898 * \param size size of the buffer
899 *
900 * \return length of data written if successful, or a specific
901 * error code
902 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100903int mbedtls_pk_write_key_der(const mbedtls_pk_context *ctx, unsigned char *buf, size_t size);
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200904
905/**
906 * \brief Write a public key to a SubjectPublicKeyInfo DER structure
907 * Note: data is written at the end of the buffer! Use the
908 * return value to determine where you should start
909 * using the buffer
910 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500911 * \param ctx PK context which must contain a valid public or private key.
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200912 * \param buf buffer to write to
913 * \param size size of the buffer
914 *
915 * \return length of data written if successful, or a specific
916 * error code
917 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100918int mbedtls_pk_write_pubkey_der(const mbedtls_pk_context *ctx, unsigned char *buf, size_t size);
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200919
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200920#if defined(MBEDTLS_PEM_WRITE_C)
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200921/**
922 * \brief Write a public key to a PEM string
923 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500924 * \param ctx PK context which must contain a valid public or private key.
925 * \param buf Buffer to write to. The output includes a
926 * terminating null byte.
927 * \param size Size of the buffer in bytes.
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200928 *
Manuel Pégourié-Gonnard81abefd2015-05-29 12:53:47 +0200929 * \return 0 if successful, or a specific error code
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200930 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100931int mbedtls_pk_write_pubkey_pem(const mbedtls_pk_context *ctx, unsigned char *buf, size_t size);
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200932
933/**
934 * \brief Write a private key to a PKCS#1 or SEC1 PEM string
935 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500936 * \param ctx PK context which must contain a valid private key.
937 * \param buf Buffer to write to. The output includes a
938 * terminating null byte.
939 * \param size Size of the buffer in bytes.
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200940 *
Manuel Pégourié-Gonnard81abefd2015-05-29 12:53:47 +0200941 * \return 0 if successful, or a specific error code
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200942 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100943int mbedtls_pk_write_key_pem(const mbedtls_pk_context *ctx, unsigned char *buf, size_t size);
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200944#endif /* MBEDTLS_PEM_WRITE_C */
945#endif /* MBEDTLS_PK_WRITE_C */
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200946
947/*
948 * WARNING: Low-level functions. You probably do not want to use these unless
949 * you are certain you do ;)
950 */
951
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200952#if defined(MBEDTLS_PK_PARSE_C)
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200953/**
Paul Bakker1a7550a2013-09-15 13:01:22 +0200954 * \brief Parse a SubjectPublicKeyInfo DER structure
955 *
956 * \param p the position in the ASN.1 data
957 * \param end end of the buffer
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500958 * \param pk The PK context to fill. It must have been initialized
959 * but not set up.
Paul Bakker1a7550a2013-09-15 13:01:22 +0200960 *
961 * \return 0 if successful, or a specific PK error code
962 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100963int mbedtls_pk_parse_subpubkey(unsigned char **p, const unsigned char *end,
964 mbedtls_pk_context *pk);
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200965#endif /* MBEDTLS_PK_PARSE_C */
Paul Bakker1a7550a2013-09-15 13:01:22 +0200966
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200967#if defined(MBEDTLS_PK_WRITE_C)
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200968/**
969 * \brief Write a subjectPublicKey to ASN.1 data
970 * Note: function works backwards in data buffer
971 *
972 * \param p reference to current position pointer
973 * \param start start of the buffer (for bounds-checking)
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500974 * \param key PK context which must contain a valid public or private key.
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200975 *
976 * \return the length written or a negative error code
977 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100978int mbedtls_pk_write_pubkey(unsigned char **p, unsigned char *start,
979 const mbedtls_pk_context *key);
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200980#endif /* MBEDTLS_PK_WRITE_C */
Paul Bakkerc7bb02b2013-09-15 14:54:56 +0200981
Manuel Pégourié-Gonnard9439f932014-11-21 09:49:43 +0100982/*
983 * Internal module functions. You probably do not want to use these unless you
984 * know you do.
985 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200986#if defined(MBEDTLS_FS_IO)
Gilles Peskine449bd832023-01-11 14:50:10 +0100987int mbedtls_pk_load_file(const char *path, unsigned char **buf, size_t *n);
Manuel Pégourié-Gonnard9439f932014-11-21 09:49:43 +0100988#endif
989
Manuel Pégourié-Gonnard347a00e2018-11-19 12:25:37 +0100990#if defined(MBEDTLS_USE_PSA_CRYPTO)
991/**
Neil Armstrong23143dc2022-04-21 11:33:54 +0200992 * \brief Turn an EC or RSA key into an opaque one.
Manuel Pégourié-Gonnard347a00e2018-11-19 12:25:37 +0100993 *
994 * \warning This is a temporary utility function for tests. It might
995 * change or be removed at any time without notice.
996 *
Neil Armstrong23143dc2022-04-21 11:33:54 +0200997 * \param pk Input: the EC or RSA key to import to a PSA key.
Gilles Peskine11392492019-05-27 14:53:19 +0200998 * Output: a PK context wrapping that PSA key.
Ronald Croncf56a0a2020-08-04 09:51:30 +0200999 * \param key Output: a PSA key identifier.
Gilles Peskine11392492019-05-27 14:53:19 +02001000 * It's the caller's responsibility to call
Ronald Croncf56a0a2020-08-04 09:51:30 +02001001 * psa_destroy_key() on that key identifier after calling
Gilles Peskine11392492019-05-27 14:53:19 +02001002 * mbedtls_pk_free() on the PK context.
Neil Armstronga1fc18f2022-04-22 13:57:14 +02001003 * \param alg The algorithm to allow for use with that key.
1004 * \param usage The usage to allow for use with that key.
1005 * \param alg2 The secondary algorithm to allow for use with that key.
Manuel Pégourié-Gonnard347a00e2018-11-19 12:25:37 +01001006 *
1007 * \return \c 0 if successful.
1008 * \return An Mbed TLS error code otherwise.
1009 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001010int mbedtls_pk_wrap_as_opaque(mbedtls_pk_context *pk,
1011 mbedtls_svc_key_id_t *key,
1012 psa_algorithm_t alg,
1013 psa_key_usage_t usage,
1014 psa_algorithm_t alg2);
Manuel Pégourié-Gonnard347a00e2018-11-19 12:25:37 +01001015#endif /* MBEDTLS_USE_PSA_CRYPTO */
1016
Paul Bakkered27a042013-04-18 22:46:23 +02001017#ifdef __cplusplus
1018}
1019#endif
1020
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +02001021#endif /* MBEDTLS_PK_H */