include/openssl/hpke.h

0001 /*
0002  * Copyright 2022-2024 The OpenSSL Project Authors. All Rights Reserved.
0003  *
0004  * Licensed under the Apache License 2.0 (the "License").  You may not use
0005  * this file except in compliance with the License.  You can obtain a copy
0006  * in the file LICENSE in the source distribution or at
0007  * https://www.openssl.org/source/license.html
0008  */
0009
0010 /* APIs and data structures for HPKE (RFC9180)  */
0011 #ifndef OSSL_HPKE_H
0012 # define OSSL_HPKE_H
0013 # pragma once
0014
0015 # include <openssl/types.h>
0016
0017 /* HPKE modes */
0018 # define OSSL_HPKE_MODE_BASE              0 /* Base mode  */
0019 # define OSSL_HPKE_MODE_PSK               1 /* Pre-shared key mode */
0020 # define OSSL_HPKE_MODE_AUTH              2 /* Authenticated mode */
0021 # define OSSL_HPKE_MODE_PSKAUTH           3 /* PSK+authenticated mode */
0022
0023 /*
0024  * Max for ikm, psk, pskid, info and exporter contexts.
0025  * RFC9180, section 7.2.1 RECOMMENDS 64 octets but we have test vectors from
0026  * Appendix A.6.1 with a 66 octet IKM so we'll allow that.
0027  */
0028 # define OSSL_HPKE_MAX_PARMLEN        66
0029 # define OSSL_HPKE_MIN_PSKLEN         32
0030 # define OSSL_HPKE_MAX_INFOLEN        1024
0031
0032 /*
0033  * The (16bit) HPKE algorithm ID IANA codepoints
0034  * If/when new IANA codepoints are added there are tables in
0035  * crypto/hpke/hpke_util.c that must also be updated.
0036  */
0037 # define OSSL_HPKE_KEM_ID_RESERVED         0x0000 /* not used */
0038 # define OSSL_HPKE_KEM_ID_P256             0x0010 /* NIST P-256 */
0039 # define OSSL_HPKE_KEM_ID_P384             0x0011 /* NIST P-384 */
0040 # define OSSL_HPKE_KEM_ID_P521             0x0012 /* NIST P-521 */
0041 # define OSSL_HPKE_KEM_ID_X25519           0x0020 /* Curve25519 */
0042 # define OSSL_HPKE_KEM_ID_X448             0x0021 /* Curve448 */
0043
0044 # define OSSL_HPKE_KDF_ID_RESERVED         0x0000 /* not used */
0045 # define OSSL_HPKE_KDF_ID_HKDF_SHA256      0x0001 /* HKDF-SHA256 */
0046 # define OSSL_HPKE_KDF_ID_HKDF_SHA384      0x0002 /* HKDF-SHA384 */
0047 # define OSSL_HPKE_KDF_ID_HKDF_SHA512      0x0003 /* HKDF-SHA512 */
0048
0049 # define OSSL_HPKE_AEAD_ID_RESERVED        0x0000 /* not used */
0050 # define OSSL_HPKE_AEAD_ID_AES_GCM_128     0x0001 /* AES-GCM-128 */
0051 # define OSSL_HPKE_AEAD_ID_AES_GCM_256     0x0002 /* AES-GCM-256 */
0052 # define OSSL_HPKE_AEAD_ID_CHACHA_POLY1305 0x0003 /* Chacha20-Poly1305 */
0053 # define OSSL_HPKE_AEAD_ID_EXPORTONLY      0xFFFF /* export-only fake ID */
0054
0055 /* strings for suite components */
0056 # define OSSL_HPKE_KEMSTR_P256        "P-256"              /* KEM id 0x10 */
0057 # define OSSL_HPKE_KEMSTR_P384        "P-384"              /* KEM id 0x11 */
0058 # define OSSL_HPKE_KEMSTR_P521        "P-521"              /* KEM id 0x12 */
0059 # define OSSL_HPKE_KEMSTR_X25519      "X25519"             /* KEM id 0x20 */
0060 # define OSSL_HPKE_KEMSTR_X448        "X448"               /* KEM id 0x21 */
0061 # define OSSL_HPKE_KDFSTR_256         "hkdf-sha256"        /* KDF id 1 */
0062 # define OSSL_HPKE_KDFSTR_384         "hkdf-sha384"        /* KDF id 2 */
0063 # define OSSL_HPKE_KDFSTR_512         "hkdf-sha512"        /* KDF id 3 */
0064 # define OSSL_HPKE_AEADSTR_AES128GCM  "aes-128-gcm"        /* AEAD id 1 */
0065 # define OSSL_HPKE_AEADSTR_AES256GCM  "aes-256-gcm"        /* AEAD id 2 */
0066 # define OSSL_HPKE_AEADSTR_CP         "chacha20-poly1305"  /* AEAD id 3 */
0067 # define OSSL_HPKE_AEADSTR_EXP        "exporter"           /* AEAD id 0xff */
0068
0069 /*
0070  * Roles for use in creating an OSSL_HPKE_CTX, most
0071  * important use of this is to control nonce reuse.
0072  */
0073 # define OSSL_HPKE_ROLE_SENDER 0
0074 # define OSSL_HPKE_ROLE_RECEIVER 1
0075
0076 # ifdef  __cplusplus
0077 extern "C" {
0078 # endif
0079
0080 typedef struct {
0081     uint16_t    kem_id; /* Key Encapsulation Method id */
0082     uint16_t    kdf_id; /* Key Derivation Function id */
0083     uint16_t    aead_id; /* AEAD alg id */
0084 } OSSL_HPKE_SUITE;
0085
0086 /**
0087  * Suite constants, use this like:
0088  *          OSSL_HPKE_SUITE myvar = OSSL_HPKE_SUITE_DEFAULT;
0089  */
0090 # ifndef OPENSSL_NO_ECX
0091 #  define OSSL_HPKE_SUITE_DEFAULT \
0092     {\
0093         OSSL_HPKE_KEM_ID_X25519, \
0094         OSSL_HPKE_KDF_ID_HKDF_SHA256, \
0095         OSSL_HPKE_AEAD_ID_AES_GCM_128 \
0096     }
0097 # else
0098 #  define OSSL_HPKE_SUITE_DEFAULT \
0099     {\
0100         OSSL_HPKE_KEM_ID_P256, \
0101         OSSL_HPKE_KDF_ID_HKDF_SHA256, \
0102         OSSL_HPKE_AEAD_ID_AES_GCM_128 \
0103     }
0104 #endif
0105
0106 typedef struct ossl_hpke_ctx_st OSSL_HPKE_CTX;
0107
0108 OSSL_HPKE_CTX *OSSL_HPKE_CTX_new(int mode, OSSL_HPKE_SUITE suite, int role,
0109                                  OSSL_LIB_CTX *libctx, const char *propq);
0110 void OSSL_HPKE_CTX_free(OSSL_HPKE_CTX *ctx);
0111
0112 int OSSL_HPKE_encap(OSSL_HPKE_CTX *ctx,
0113                     unsigned char *enc, size_t *enclen,
0114                     const unsigned char *pub, size_t publen,
0115                     const unsigned char *info, size_t infolen);
0116 int OSSL_HPKE_seal(OSSL_HPKE_CTX *ctx,
0117                    unsigned char *ct, size_t *ctlen,
0118                    const unsigned char *aad, size_t aadlen,
0119                    const unsigned char *pt, size_t ptlen);
0120
0121 int OSSL_HPKE_keygen(OSSL_HPKE_SUITE suite,
0122                      unsigned char *pub, size_t *publen, EVP_PKEY **priv,
0123                      const unsigned char *ikm, size_t ikmlen,
0124                      OSSL_LIB_CTX *libctx, const char *propq);
0125 int OSSL_HPKE_decap(OSSL_HPKE_CTX *ctx,
0126                     const unsigned char *enc, size_t enclen,
0127                     EVP_PKEY *recippriv,
0128                     const unsigned char *info, size_t infolen);
0129 int OSSL_HPKE_open(OSSL_HPKE_CTX *ctx,
0130                    unsigned char *pt, size_t *ptlen,
0131                    const unsigned char *aad, size_t aadlen,
0132                    const unsigned char *ct, size_t ctlen);
0133
0134 int OSSL_HPKE_export(OSSL_HPKE_CTX *ctx,
0135                      unsigned char *secret,
0136                      size_t secretlen,
0137                      const unsigned char *label,
0138                      size_t labellen);
0139
0140 int OSSL_HPKE_CTX_set1_authpriv(OSSL_HPKE_CTX *ctx, EVP_PKEY *priv);
0141 int OSSL_HPKE_CTX_set1_authpub(OSSL_HPKE_CTX *ctx,
0142                                const unsigned char *pub,
0143                                size_t publen);
0144 int OSSL_HPKE_CTX_set1_psk(OSSL_HPKE_CTX *ctx,
0145                            const char *pskid,
0146                            const unsigned char *psk, size_t psklen);
0147
0148 int OSSL_HPKE_CTX_set1_ikme(OSSL_HPKE_CTX *ctx,
0149                             const unsigned char *ikme, size_t ikmelen);
0150
0151 int OSSL_HPKE_CTX_set_seq(OSSL_HPKE_CTX *ctx, uint64_t seq);
0152 int OSSL_HPKE_CTX_get_seq(OSSL_HPKE_CTX *ctx, uint64_t *seq);
0153
0154 int OSSL_HPKE_suite_check(OSSL_HPKE_SUITE suite);
0155 int OSSL_HPKE_get_grease_value(const OSSL_HPKE_SUITE *suite_in,
0156                                OSSL_HPKE_SUITE *suite,
0157                                unsigned char *enc, size_t *enclen,
0158                                unsigned char *ct, size_t ctlen,
0159                                OSSL_LIB_CTX *libctx, const char *propq);
0160 int OSSL_HPKE_str2suite(const char *str, OSSL_HPKE_SUITE *suite);
0161 size_t OSSL_HPKE_get_ciphertext_size(OSSL_HPKE_SUITE suite, size_t clearlen);
0162 size_t OSSL_HPKE_get_public_encap_size(OSSL_HPKE_SUITE suite);
0163 size_t OSSL_HPKE_get_recommended_ikmelen(OSSL_HPKE_SUITE suite);
0164
0165 # ifdef  __cplusplus
0166 }
0167 # endif
0168
0169 #endif