pk.h

Go to the documentation of this file.

/*
 *  Copyright The Mbed TLS Contributors
 *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
 */

#ifndef MBEDTLS_PK_H
#define MBEDTLS_PK_H
#define MBEDTLS_PK_HAVE_PRIVATE_HEADER

#include "mbedtls/private_access.h"

#include "tf-psa-crypto/build_info.h"
#include "mbedtls/compat-3-crypto.h"

#include "mbedtls/md.h"

#if defined(MBEDTLS_PSA_CRYPTO_CLIENT)
#include "psa/crypto.h"
#endif

#define MBEDTLS_ERR_PK_TYPE_MISMATCH       -0x3F00

#define MBEDTLS_ERR_PK_FILE_IO_ERROR       -0x3E00

#define MBEDTLS_ERR_PK_KEY_INVALID_VERSION -0x3D80

#define MBEDTLS_ERR_PK_KEY_INVALID_FORMAT  -0x3D00

#define MBEDTLS_ERR_PK_UNKNOWN_PK_ALG      -0x3C80

#define MBEDTLS_ERR_PK_PASSWORD_REQUIRED   -0x3C00

#define MBEDTLS_ERR_PK_PASSWORD_MISMATCH   -0x3B80

#define MBEDTLS_ERR_PK_INVALID_PUBKEY      -0x3B00

#define MBEDTLS_ERR_PK_INVALID_ALG         -0x3A80

#define MBEDTLS_ERR_PK_UNKNOWN_NAMED_CURVE -0x3A00

#define MBEDTLS_ERR_PK_FEATURE_UNAVAILABLE -0x3980

#ifdef __cplusplus
extern "C" {
#endif

typedef enum {
    MBEDTLS_PK_SIGALG_NONE = 0,
    MBEDTLS_PK_SIGALG_RSA_PKCS1V15, // PSA_ALG_RSA_PKCS1V15_SIGN
    MBEDTLS_PK_SIGALG_RSA_PSS,      // PSA_ALG_RSA_PSS_ANY_SALT
    MBEDTLS_PK_SIGALG_ECDSA,        // MBEDTLS_PK_ALG_ECDSA
} mbedtls_pk_sigalg_t;

/* We need to set MBEDTLS_PK_SIGNATURE_MAX_SIZE to the maximum signature
 * size among the supported signature types. Do it by starting at 0,
 * then incrementally increasing to be large enough for each supported
 * signature mechanism.
 *
 * The resulting value can be 0, for example if MBEDTLS_ECDH_C is enabled
 * (which allows the pk module to be included) but neither MBEDTLS_ECDSA_C
 * nor MBEDTLS_RSA_C nor any PSA signature mechanism (PSA).
 */
#define MBEDTLS_PK_SIGNATURE_MAX_SIZE 0

#if defined(MBEDTLS_RSA_C) && \
    MBEDTLS_MPI_MAX_SIZE > MBEDTLS_PK_SIGNATURE_MAX_SIZE
/* For RSA, the signature can be as large as the bignum module allows.*/
#undef MBEDTLS_PK_SIGNATURE_MAX_SIZE
#define MBEDTLS_PK_SIGNATURE_MAX_SIZE MBEDTLS_MPI_MAX_SIZE
#endif

#if defined(MBEDTLS_ECDSA_C) &&                                 \
    MBEDTLS_ECDSA_MAX_LEN > MBEDTLS_PK_SIGNATURE_MAX_SIZE
/* For ECDSA, the ecdsa module exports a constant for the maximum
 * signature size. */
#undef MBEDTLS_PK_SIGNATURE_MAX_SIZE
#define MBEDTLS_PK_SIGNATURE_MAX_SIZE MBEDTLS_ECDSA_MAX_LEN
#endif

#if PSA_SIGNATURE_MAX_SIZE > MBEDTLS_PK_SIGNATURE_MAX_SIZE
/* PSA_SIGNATURE_MAX_SIZE is the maximum size of a signature made
 * through the PSA API in the PSA representation. */
#undef MBEDTLS_PK_SIGNATURE_MAX_SIZE
#define MBEDTLS_PK_SIGNATURE_MAX_SIZE PSA_SIGNATURE_MAX_SIZE
#endif

#if PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE + 11 > MBEDTLS_PK_SIGNATURE_MAX_SIZE
/* The Mbed TLS representation is different for ECDSA signatures:
 * PSA uses the raw concatenation of r and s,
 * whereas Mbed TLS uses the ASN.1 representation (SEQUENCE of two INTEGERs).
 * Add the overhead of ASN.1: up to (1+2) + 2 * (1+2+1) for the
 * types, lengths (represented by up to 2 bytes), and potential leading
 * zeros of the INTEGERs and the SEQUENCE. */
#undef MBEDTLS_PK_SIGNATURE_MAX_SIZE
#define MBEDTLS_PK_SIGNATURE_MAX_SIZE (PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE + 11)
#endif

/* Keep this symbol for backward compatibility. There is code in the framework
 * which depends on this. Once 3.6 LTS branch will reach end-of-life framework's
 * code can be adjusted and this define removed. */
#define MBEDTLS_PK_USE_PSA_EC_DATA

/* This is identical to MBEDTLS_PK_USE_PSA_EC_DATA above, but for RSA keys.
 * The main reason for having it is that framework code is shared between
 * the develoment branch and the 3.6 LTS one and we need a way to tell from which
 * of the two we're building.
 * This symbol is not used in builtin driver and tests and it can be removed
 * at the same time as MBEDTLS_PK_USE_PSA_EC_DATA. */
#define MBEDTLS_PK_USE_PSA_RSA_DATA

/* Opaque internal type */
typedef struct mbedtls_pk_info_t mbedtls_pk_info_t;

#define MBEDTLS_PK_MAX_EC_PUBKEY_RAW_LEN \
    PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_ECC_MAX_CURVE_BITS)

#define MBEDTLS_PK_MAX_RSA_PUBKEY_RAW_LEN \
    PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(PSA_VENDOR_RSA_MAX_KEY_BITS)

#define MBEDTLS_PK_MAX_PUBKEY_RAW_LEN \
    (MBEDTLS_PK_MAX_EC_PUBKEY_RAW_LEN > MBEDTLS_PK_MAX_RSA_PUBKEY_RAW_LEN) ? \
    MBEDTLS_PK_MAX_EC_PUBKEY_RAW_LEN : MBEDTLS_PK_MAX_RSA_PUBKEY_RAW_LEN

typedef enum {
    MBEDTLS_PK_RSA_PKCS_V15 = 0,
    MBEDTLS_PK_RSA_PKCS_V21,
} mbedtls_pk_rsa_padding_t;

typedef struct mbedtls_pk_context {
    /* Public key information. */
    const mbedtls_pk_info_t *MBEDTLS_PRIVATE(pk_info);
    /* Previously: underlying public key context.
     * Now unused (by public functions at least). */
    void *MBEDTLS_PRIVATE(pk_ctx);

    /* The following field is used to store the ID of a private key for:
     * - EC keys (MBEDTLS_PK_ECKEY, MBEDTLS_PK_ECKEY_DH, MBEDTLS_PK_ECDSA)
     * - Wrapped keys (EC or RSA).
     *
     * priv_id = MBEDTLS_SVC_KEY_ID_INIT when PK context wraps only the public
     * key.
     *
     * Other keys still use the pk_ctx to store their own context. */
    mbedtls_svc_key_id_t MBEDTLS_PRIVATE(priv_id);

#if defined(PSA_WANT_KEY_TYPE_RSA_PUBLIC_KEY) || defined(PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY)
    /* Public EC or RSA key in raw format, where raw here means the format returned
     * by psa_export_public_key(). */
    uint8_t MBEDTLS_PRIVATE(pub_raw)[MBEDTLS_PK_MAX_PUBKEY_RAW_LEN];

    /* Lenght of the raw key above in bytes. */
    size_t MBEDTLS_PRIVATE(pub_raw_len);

    /* Bits of the private/public key. */
    size_t MBEDTLS_PRIVATE(bits);
#endif /* PSA_WANT_KEY_TYPE_RSA_PUBLIC_KEY || PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY */

#if defined(PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY)
    /* EC family. Only applies to EC keys. */
    psa_ecc_family_t MBEDTLS_PRIVATE(ec_family);
#endif /* PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY */

#if defined(PSA_WANT_KEY_TYPE_RSA_PUBLIC_KEY)
    /* Padding associated to the RSA key. It only affects RSA public key since
     * the private one is imported into PSA with v1.5 as main algorithm and
     * v2.1 as enrollment algorithm. */
    mbedtls_pk_rsa_padding_t MBEDTLS_PRIVATE(rsa_padding);

    /* Hash algorithm to be used with RSA public key. */
    psa_algorithm_t MBEDTLS_PRIVATE(rsa_hash_alg);
#endif /* PSA_WANT_KEY_TYPE_RSA_PUBLIC_KEY */
} mbedtls_pk_context;

#if defined(MBEDTLS_ECP_RESTARTABLE)

typedef struct {
    const mbedtls_pk_info_t *MBEDTLS_PRIVATE(pk_info);    /* Public key information         */
    void *MBEDTLS_PRIVATE(rs_ctx);                        /* Underlying restart context     */
} mbedtls_pk_restart_ctx;

#else /* MBEDTLS_ECP_RESTARTABLE */
/* Now we can declare functions that take a pointer to that */
typedef void mbedtls_pk_restart_ctx;
#endif /* MBEDTLS_ECP_RESTARTABLE */

#if defined(PSA_WANT_ALG_DETERMINISTIC_ECDSA)
#define MBEDTLS_PK_ALG_ECDSA(hash_alg) PSA_ALG_DETERMINISTIC_ECDSA(hash_alg)
#else
#define MBEDTLS_PK_ALG_ECDSA(hash_alg) PSA_ALG_ECDSA(hash_alg)
#endif

void mbedtls_pk_init(mbedtls_pk_context *ctx);

void mbedtls_pk_free(mbedtls_pk_context *ctx);

#if defined(MBEDTLS_ECP_RESTARTABLE)

void mbedtls_pk_restart_init(mbedtls_pk_restart_ctx *ctx);

void mbedtls_pk_restart_free(mbedtls_pk_restart_ctx *ctx);
#endif /* MBEDTLS_ECP_RESTARTABLE */

int mbedtls_pk_wrap_psa(mbedtls_pk_context *ctx,
                        const mbedtls_svc_key_id_t key);

size_t mbedtls_pk_get_bitlen(const mbedtls_pk_context *ctx);

int mbedtls_pk_can_do_psa(const mbedtls_pk_context *pk, psa_algorithm_t alg,
                          psa_key_usage_t usage);

#if defined(MBEDTLS_PSA_CRYPTO_CLIENT)

int mbedtls_pk_get_psa_attributes(const mbedtls_pk_context *pk,
                                  psa_key_usage_t usage,
                                  psa_key_attributes_t *attributes);

int mbedtls_pk_import_into_psa(const mbedtls_pk_context *pk,
                               const psa_key_attributes_t *attributes,
                               mbedtls_svc_key_id_t *key_id);

int mbedtls_pk_copy_from_psa(mbedtls_svc_key_id_t key_id, mbedtls_pk_context *pk);

int mbedtls_pk_copy_public_from_psa(mbedtls_svc_key_id_t key_id, mbedtls_pk_context *pk);
#endif /* MBEDTLS_PSA_CRYPTO_CLIENT */

int mbedtls_pk_verify(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
                      const unsigned char *hash, size_t hash_len,
                      const unsigned char *sig, size_t sig_len);

int mbedtls_pk_verify_restartable(mbedtls_pk_context *ctx,
                                  mbedtls_md_type_t md_alg,
                                  const unsigned char *hash, size_t hash_len,
                                  const unsigned char *sig, size_t sig_len,
                                  mbedtls_pk_restart_ctx *rs_ctx);

int mbedtls_pk_verify_ext(mbedtls_pk_sigalg_t type,
                          mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
                          const unsigned char *hash, size_t hash_len,
                          const unsigned char *sig, size_t sig_len);

int mbedtls_pk_sign(mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg,
                    const unsigned char *hash, size_t hash_len,
                    unsigned char *sig, size_t sig_size, size_t *sig_len);

int mbedtls_pk_sign_restartable(mbedtls_pk_context *ctx,
                                mbedtls_md_type_t md_alg,
                                const unsigned char *hash, size_t hash_len,
                                unsigned char *sig, size_t sig_size, size_t *sig_len,
                                mbedtls_pk_restart_ctx *rs_ctx);

int mbedtls_pk_sign_ext(mbedtls_pk_sigalg_t sig_type,
                        mbedtls_pk_context *ctx,
                        mbedtls_md_type_t md_alg,
                        const unsigned char *hash, size_t hash_len,
                        unsigned char *sig, size_t sig_size, size_t *sig_len);

int mbedtls_pk_check_pair(const mbedtls_pk_context *pub,
                          const mbedtls_pk_context *prv);

#if defined(MBEDTLS_PK_PARSE_C)

int mbedtls_pk_parse_key(mbedtls_pk_context *ctx,
                         const unsigned char *key, size_t keylen,
                         const unsigned char *pwd, size_t pwdlen);

int mbedtls_pk_parse_public_key(mbedtls_pk_context *ctx,
                                const unsigned char *key, size_t keylen);

#if defined(MBEDTLS_FS_IO)

int mbedtls_pk_parse_keyfile(mbedtls_pk_context *ctx,
                             const char *path, const char *password);

int mbedtls_pk_parse_public_keyfile(mbedtls_pk_context *ctx, const char *path);
#endif /* MBEDTLS_FS_IO */
#endif /* MBEDTLS_PK_PARSE_C */

#if defined(MBEDTLS_PK_WRITE_C)

int mbedtls_pk_write_key_der(const mbedtls_pk_context *ctx, unsigned char *buf, size_t size);

int mbedtls_pk_write_pubkey_der(const mbedtls_pk_context *ctx, unsigned char *buf, size_t size);

#if defined(MBEDTLS_PEM_WRITE_C)

int mbedtls_pk_write_pubkey_pem(const mbedtls_pk_context *ctx, unsigned char *buf, size_t size);

int mbedtls_pk_write_key_pem(const mbedtls_pk_context *ctx, unsigned char *buf, size_t size);
#endif /* MBEDTLS_PEM_WRITE_C */
#endif /* MBEDTLS_PK_WRITE_C */

#ifdef __cplusplus
}
#endif

#endif /* MBEDTLS_PK_H */