HPKE library and HPKE application

[hannestschofenig]

Description

This PR provides an initial version of the Hybrid Public Key Encryption (HPKE) librrary along with an example application. HPKE is used in TLS 1.3 with the ESNI extension (see https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni-13) but also by various other application domains, such as firmware encryption using the SUIT manifest or messaging services.

This implementation uses the PSA Crypto API.

Status

IN DEVELOPMENT

Requires Backporting

NO

Migrations

The HPKE library offers new APIs to utilize the features but there is no impact on existing code.

Building and using the HPKE Code

The example application demonstrates the use of HPKE encryption and decryption.

To encrypt and decrypt messages using this HPKE application the following steps are necessary.

(A) Encryption

A.1. Create a private key A.2. Convert the key into a format understood by the HPKE example application (which uses the PSA Crypto API) A.3. Invoke the HPKE example application

A.1. Create a private key

It is necessary to create a public/private key pair for use by the recipient (called pkR and skR in the HPKE spec). The command to generate a private key using the OpenSSL tools with ECC with the NIST P256r1. Then, put the private key in the skR.pem file (in a PEM encoding). Finally, generate a PEM version of the public key (pkR.pem) from the private key.

openssl ecparam -name prime256v1 -genkey -noout -out skR.pem openssl ec -in skR.pem -pubout -out pkR.pem

A.2. Convert key

We need to convert the key from the PEM format into the raw key format required by the example program. We use the key_writer utility to create two files, one for the public key and another one for the private key. The public key will be used for encryption by the sender and the private key by the recipient (obviously) for decryption. The key_writer program is a separate utility, which can be found here: https://github.com/hannestschofenig/key_writer

Once compiled, create pkR and skR using the following commands:

key_writer mode=public filename=pkR.pem output_mode=public output_file=pkR.bin output_format=bin key_writer mode=private filename=skR.pem output_mode=private output_file=skR.bin output_format=bin

A.3. Encrypt plaintext

Finally, we invoke the HPKE example application to encrypt data. The sender uses several command line arguments to pass the following information in, namely:

• Public key of the recipient (pkR)
• Plaintext
• Ciphersuite information
• Authentication mode

As a result, the following output is produced:

• Ciphertext
• Ephemeral public key (pkE)

Here are the commands:

echo "Hello World!" > hello.txt

hpke_app doing_enc=1 pkR_filename=pkR.bin input_filename=hello.txt pkE_filename=pkE.bin output_filename=ciphertext mode=base suite=0x10,1,1

Note: The parameter -c 0x10,1,1 refers to the following ciphersuite combination:

• KEM: P256
• KDF: HKDF-SHA256
• AEADs: AES-128-GCM

Normally, the sender would then transmit the ciphertext, and the pkE to the recipient. We assume that the authentication mode and the ciphersuite are known to both parties a priori or negotiated.

(B) Decryption

Now, we invoke the HPKE example application to decrypt the ciphertext. The recipient takes the input together with its private key (skR) and re-creates the plaintext as follows:

hpke_app doing_enc=0 skR_filename=skR.bin mode=base suite=0x10,1,1 pkE_filename=pkE.bin input_filename=ciphertext output_filename=plaintext

If everything was configured correctly, the recipient obtains the plaintext.

Todos

• [ ] Tests
• [ ] Documentation
• [ ] Alignment with Mbed TLS coding style
• [ ] Legacy Mbed TLS Crypto API support
• [ ] Use in TLS 1.3 ESNI extension

Steps to test or reproduce

Outline the steps to test or reproduce the PR here.

[ronald-cron-arm]

Thanks for your contribution. We will have to plan the review as it is a fair amount of work.

[tom-daubney-arm]

We are now converting older PRs to draft PRs where the following conditions are met: They have not been updated in the last 3 months, and they need more than non-trivial work to complete.