include/openssl/hpke.h

   1 /*
   2  * Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
   3  *
   4  * Licensed under the OpenSSL license (the "License").  You may not use
   5  * this file except in compliance with the License.  You can obtain a copy
   6  * in the file LICENSE in the source distribution or at
   7  * https://www.openssl.org/source/license.html
   8  */
   9
  10 /* APIs and data structures for HPKE (RFC9180)  */
  11 #ifndef OSSL_HPKE_H
  12 # define OSSL_HPKE_H
  13 # pragma once
  14
  15 # include <openssl/types.h>
  16
  17 /* HPKE modes */
  18 # define OSSL_HPKE_MODE_BASE              0 /* Base mode  */
  19 # define OSSL_HPKE_MODE_PSK               1 /* Pre-shared key mode */
  20 # define OSSL_HPKE_MODE_AUTH              2 /* Authenticated mode */
  21 # define OSSL_HPKE_MODE_PSKAUTH           3 /* PSK+authenticated mode */
  22
  23 /*
  24  * Max for ikm, psk, pskid, info and exporter contexts.
  25  * RFC9180, section 7.2.1 RECOMMENDS 64 octets but we have test vectors from
  26  * Appendix A.6.1 with a 66 octet IKM so we'll allow that.
  27  */
  28 # define OSSL_HPKE_MAX_PARMLEN        66
  29 # define OSSL_HPKE_MAX_INFOLEN        1024
  30
  31 /*
  32  * The (16bit) HPKE algorithm ID IANA codepoints
  33  * If/when new IANA codepoints are added there are tables in
  34  * crypto/hpke/hpke_util.c that must also be updated.
  35  */
  36 # define OSSL_HPKE_KEM_ID_RESERVED         0x0000 /* not used */
  37 # define OSSL_HPKE_KEM_ID_P256             0x0010 /* NIST P-256 */
  38 # define OSSL_HPKE_KEM_ID_P384             0x0011 /* NIST P-384 */
  39 # define OSSL_HPKE_KEM_ID_P521             0x0012 /* NIST P-521 */
  40 # define OSSL_HPKE_KEM_ID_X25519           0x0020 /* Curve25519 */
  41 # define OSSL_HPKE_KEM_ID_X448             0x0021 /* Curve448 */
  42
  43 # define OSSL_HPKE_KDF_ID_RESERVED         0x0000 /* not used */
  44 # define OSSL_HPKE_KDF_ID_HKDF_SHA256      0x0001 /* HKDF-SHA256 */
  45 # define OSSL_HPKE_KDF_ID_HKDF_SHA384      0x0002 /* HKDF-SHA384 */
  46 # define OSSL_HPKE_KDF_ID_HKDF_SHA512      0x0003 /* HKDF-SHA512 */
  47
  48 # define OSSL_HPKE_AEAD_ID_RESERVED        0x0000 /* not used */
  49 # define OSSL_HPKE_AEAD_ID_AES_GCM_128     0x0001 /* AES-GCM-128 */
  50 # define OSSL_HPKE_AEAD_ID_AES_GCM_256     0x0002 /* AES-GCM-256 */
  51 # define OSSL_HPKE_AEAD_ID_CHACHA_POLY1305 0x0003 /* Chacha20-Poly1305 */
  52 # define OSSL_HPKE_AEAD_ID_EXPORTONLY      0xFFFF /* export-only fake ID */
  53
  54 /* strings for suite components */
  55 # define OSSL_HPKE_KEMSTR_P256        "P-256"              /* KEM id 0x10 */
  56 # define OSSL_HPKE_KEMSTR_P384        "P-384"              /* KEM id 0x11 */
  57 # define OSSL_HPKE_KEMSTR_P521        "P-521"              /* KEM id 0x12 */
  58 # define OSSL_HPKE_KEMSTR_X25519      "X25519"             /* KEM id 0x20 */
  59 # define OSSL_HPKE_KEMSTR_X448        "X448"               /* KEM id 0x21 */
  60 # define OSSL_HPKE_KDFSTR_256         "hkdf-sha256"        /* KDF id 1 */
  61 # define OSSL_HPKE_KDFSTR_384         "hkdf-sha384"        /* KDF id 2 */
  62 # define OSSL_HPKE_KDFSTR_512         "hkdf-sha512"        /* KDF id 3 */
  63 # define OSSL_HPKE_AEADSTR_AES128GCM  "aes-128-gcm"        /* AEAD id 1 */
  64 # define OSSL_HPKE_AEADSTR_AES256GCM  "aes-256-gcm"        /* AEAD id 2 */
  65 # define OSSL_HPKE_AEADSTR_CP         "chacha20-poly1305"  /* AEAD id 3 */
  66 # define OSSL_HPKE_AEADSTR_EXP        "exporter"           /* AEAD id 0xff */
  67
  68 /*
  69  * Roles for use in creating an OSSL_HPKE_CTX, most
  70  * important use of this is to control nonce re-use.
  71  */
  72 # define OSSL_HPKE_ROLE_SENDER 0
  73 # define OSSL_HPKE_ROLE_RECEIVER 1
  74
  75 typedef struct {
  76     uint16_t    kem_id; /* Key Encapsulation Method id */
  77     uint16_t    kdf_id; /* Key Derivation Function id */
  78     uint16_t    aead_id; /* AEAD alg id */
  79 } OSSL_HPKE_SUITE;
  80
  81 /**
  82  * Suite constants, use this like:
  83  *          OSSL_HPKE_SUITE myvar = OSSL_HPKE_SUITE_DEFAULT;
  84  */
  85 # ifndef OPENSSL_NO_ECX
  86 #  define OSSL_HPKE_SUITE_DEFAULT \
  87     {\
  88         OSSL_HPKE_KEM_ID_X25519, \
  89         OSSL_HPKE_KDF_ID_HKDF_SHA256, \
  90         OSSL_HPKE_AEAD_ID_AES_GCM_128 \
  91     }
  92 # else
  93 #  define OSSL_HPKE_SUITE_DEFAULT \
  94     {\
  95         OSSL_HPKE_KEM_ID_P256, \
  96         OSSL_HPKE_KDF_ID_HKDF_SHA256, \
  97         OSSL_HPKE_AEAD_ID_AES_GCM_128 \
  98     }
  99 #endif
 100
 101 typedef struct ossl_hpke_ctx_st OSSL_HPKE_CTX;
 102
 103 OSSL_HPKE_CTX *OSSL_HPKE_CTX_new(int mode, OSSL_HPKE_SUITE suite, int role,
 104                                  OSSL_LIB_CTX *libctx, const char *propq);
 105 void OSSL_HPKE_CTX_free(OSSL_HPKE_CTX *ctx);
 106
 107 int OSSL_HPKE_encap(OSSL_HPKE_CTX *ctx,
 108                     unsigned char *enc, size_t *enclen,
 109                     const unsigned char *pub, size_t publen,
 110                     const unsigned char *info, size_t infolen);
 111 int OSSL_HPKE_seal(OSSL_HPKE_CTX *ctx,
 112                    unsigned char *ct, size_t *ctlen,
 113                    const unsigned char *aad, size_t aadlen,
 114                    const unsigned char *pt, size_t ptlen);
 115
 116 int OSSL_HPKE_keygen(OSSL_HPKE_SUITE suite,
 117                      unsigned char *pub, size_t *publen, EVP_PKEY **priv,
 118                      const unsigned char *ikm, size_t ikmlen,
 119                      OSSL_LIB_CTX *libctx, const char *propq);
 120 int OSSL_HPKE_decap(OSSL_HPKE_CTX *ctx,
 121                     const unsigned char *enc, size_t enclen,
 122                     EVP_PKEY *recippriv,
 123                     const unsigned char *info, size_t infolen);
 124 int OSSL_HPKE_open(OSSL_HPKE_CTX *ctx,
 125                    unsigned char *pt, size_t *ptlen,
 126                    const unsigned char *aad, size_t aadlen,
 127                    const unsigned char *ct, size_t ctlen);
 128
 129 int OSSL_HPKE_export(OSSL_HPKE_CTX *ctx,
 130                      unsigned char *secret,
 131                      size_t secretlen,
 132                      const unsigned char *label,
 133                      size_t labellen);
 134
 135 int OSSL_HPKE_CTX_set1_authpriv(OSSL_HPKE_CTX *ctx, EVP_PKEY *priv);
 136 int OSSL_HPKE_CTX_set1_authpub(OSSL_HPKE_CTX *ctx,
 137                                const unsigned char *pub,
 138                                size_t publen);
 139 int OSSL_HPKE_CTX_set1_psk(OSSL_HPKE_CTX *ctx,
 140                            const char *pskid,
 141                            const unsigned char *psk, size_t psklen);
 142
 143 int OSSL_HPKE_CTX_set1_ikme(OSSL_HPKE_CTX *ctx,
 144                             const unsigned char *ikme, size_t ikmelen);
 145
 146 int OSSL_HPKE_CTX_set_seq(OSSL_HPKE_CTX *ctx, uint64_t seq);
 147 int OSSL_HPKE_CTX_get_seq(OSSL_HPKE_CTX *ctx, uint64_t *seq);
 148
 149 int OSSL_HPKE_suite_check(OSSL_HPKE_SUITE suite);
 150 int OSSL_HPKE_get_grease_value(const OSSL_HPKE_SUITE *suite_in,
 151                                OSSL_HPKE_SUITE *suite,
 152                                unsigned char *enc, size_t *enclen,
 153                                unsigned char *ct, size_t ctlen,
 154                                OSSL_LIB_CTX *libctx, const char *propq);
 155 int OSSL_HPKE_str2suite(const char *str, OSSL_HPKE_SUITE *suite);
 156 size_t OSSL_HPKE_get_ciphertext_size(OSSL_HPKE_SUITE suite, size_t clearlen);
 157 size_t OSSL_HPKE_get_public_encap_size(OSSL_HPKE_SUITE suite);
 158 size_t OSSL_HPKE_get_recommended_ikmelen(OSSL_HPKE_SUITE suite);
 159
 160 #endif