[gnutls-devel] GnuTLS | Expose HPKE through abstract key API (#1506)

[Read-only notification of GnuTLS library development activities]

Daiki Ueno created an issue: https://gitlab.com/gnutls/gnutls/-/issues/1506



!1749 tries to port Nettle's work in progress HPKE implementation for ECH. As HPKE is general purpose mechanism and useful outside of ECH, it would make sense to expose it from the GnuTLS API, possibly in the absract key API.

The following is the design drafted by @npocs some time ago, with a slight modification:

### New API functions

```c
/* gnutls_privkey_encap:
 * @priv: an initialized (and generated) private key
 * @peer: the public key of the peer side
 * @mode: the hpke mode to be used, can be: base, auth, psk, auth_psk
 * @handle: the handle for cipher functions
 * @key: (out): the calculated shared key
 *
 * Performs HPKE encapsulation.  Note that gnutls_aead_cipher_init() must be called before this operation.
 * 
 * Returns: 0 on success, negative error code otherwise
 */
int gnutls_privkey_encap (gnutls_privkey_t priv, gnutls_pubkey_t peer,  gnutls_hpke_mode_t mode,
                          gnutls_aead_cipher_hd_t *handle, gnutls_datum_t *key);

/* gnutls_privkey_decap:
 * @priv: an initialized (and generated) private key
 * @peer: the public key of the peer side
 * @mode: the hpke mode to be used, can be: base, auth, psk, auth_psk
 * @handle: the handle for cipher functions
 * @key: (out): the calculated shared key
 *
 * Performs HPKE decapsulation.  Note that gnutls_aead_cipher_init() must be called before this operation.
 * 
 * Returns: 0 on success, negative error code otherwise
 */
int gnutls_privkey_decap (gnutls_privkey_t priv, gnutls_pubkey_t peer, gnutls_hpke_mode_t mode,
                          gnutls_cipher_hd_t *handle, gnutls_datum_t *key);
```

For seal/open `gnutls_aead_cipher_encrypt/decrypt` can be freely used instead of creating these new ones.

Notes:
- The KEM context does not need to be saved to a structure, as the user can use it directly with the functions.
- The HPKE mode only affects the public key part of the scheme.

### Example usage

Sender:

```c
gnutls_aead_cipher_hd_t handle = NULL;
gnutls_datum_t key;
gnutls_hpke_mode mode = GNUTLS_HPKE_MODE_BASE;
gnutls_privkey_t priv = NULL;
int ret;

ret = gnutls_privkey_init(&priv);
ret = gnutls_privkey_generate2(priv, GNUTLS_PK_ECDH_X25519, ...);

/* this creates the shared key and stores it in `key` */
ret = gnutls_privkey_encap(priv, peer, mode, handle, &key);

ret = gnutls_aead_cipher_init(&handle, GNUTLS_CIPHER_AES_128_GCM, &key);
ret = gnutls_aead_cipher_encrypt(handle, …);

/* doing other stuff */

/* cleanup */
...
```

Receiver:

```c
gnutls_aead_cipher_hd_t handle = NULL;
gnutls_datum_t key;
gnutls_hpke_mode mode = GNUTLS_HPKE_MODE_BASE;
gnutls_privkey_t priv = NULL;
int ret;

ret = gnutls_privkey_init(&priv);
ret = gnutls_privkey_import_x509(priv, ...);

/* this creates the shared key and stores it in `key` */
ret = gnutls_privkey_decap(priv, peer, mode, handle, &key);

ret = gnutls_aead_cipher_init(&handle, GNUTLS_CIPHER_AES_128_GCM, &key);
ret = gnutls_aead_cipher_decrypt(handle, …);

/* doing other stuff */

/* cleanup */
...
```

-- 
Reply to this email directly or view it on GitLab: https://gitlab.com/gnutls/gnutls/-/issues/1506
You're receiving this email because of your account on gitlab.com.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.gnupg.org/pipermail/gnutls-devel/attachments/20231010/ac1ae02f/attachment-0001.html>