age-plugin-hpke

Crates.ioage-plugin-hpke
lib.rsage-plugin-hpke
version0.1.2
sourcesrc
created_at2023-08-28 08:35:38.572564
updated_at2023-08-28 17:48:17.496824
descriptionHPKE plugin for age clients.
homepagehttps://github.com/thibmeu/age-plugin-hpke
repositoryhttps://github.com/thibmeu/age-plugin-hpke
max_upload_size
id956694
size92,850
Thibault (thibmeu)

documentation

README

age-plugin-hpke: HPKE plugin for age

Documentation License crates.io

age-plugin-hpke is a plugin for age. It provides an age Identity and Recipient consuming Hybrid Public Key Encrypted (HPKE) files.

HPKE is defined in RFC 9180, and age-plugin are defined by C2SP.

Tables of Content

Features

  • HPKE recipienties and identities
  • Post Quantum HPKE with Kyber Draft00
  • Plugin cli for age
  • Plugin library for age
  • Cross platform (Linux, Windows, macOS)

What's next

  • Agree on age format

Installation

Environment CLI Command
Cargo (Rust 1.67+) cargo install --git https://github.com/thibmeu/age-plugin-hpke

Read age installation instructions to install age.

Usage

You can use the --help option to get more details about the command and its options.

age-plugin-hpke [OPTIONS]

Generate recipient and identity

Create an identity using Kyber768.

age-plugin-hpke --generate --kem x25519-kyber768-draft00 --aead cha-cha20-poly1305 --associated-data "user@example.com" > my_id.key

For convenience, you can also create an associated recipient

cat my_id.key | grep 'recipient' | sed 's/.*\(age1.*\)/\1/' > my_id.key.pub

The recipient and identity size are going to vary based on the KEM. With Post-quantum, keys are large.

HPKE Encryption

Encrypt Hello age-plugin-hpke! string with your new key.

echo 'Hello age-plugin-hpke!' | age -a -R my_id.key.pub > data.age
age --decrypt -i my_id.key data.age
Hello age-plugin-hpke!

Security Considerations

This software has not been audited. Please use at your sole discretion. With this in mind, age-plugin-hpke security relies on the following:

FAQ

age format

Stanza

hpke <ASSOCIATED_DATA> <KEM> <AEAD>

All data within the stanza are base64 encoded with no pad.

Recipient

age1hpke1<KEM_ALG><AEAD_ALG><KDF_ALG><PUBLIC_KEY><ASSOCIATED_DATA>

Identity

AGE-PLUGIN-HPKE-<KEM_ALG><AEAD_ALG><KDF_ALG><PRIVATE_KEY><ASSOCIATED_DATA>

Why age for HPKE

Why not? At the time of writting, age is available on multiple platform, has a file format allowing for agility, and a decent tooling to integrate with.

IETF format with HPKE in COSE might offer an alternative path down the line.

Usage as a library

The underlying primitive used in the cli are exposed via a library. This includes the age stanza, recipient, and identity, as well as tools to generate an identity from scratch.

cargo add age-plugin-hpke

License

This project is under the MIT license.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be MIT licensed as above, without any additional terms or conditions.

Commit count: 19

cargo fmt