Expand description
libes
library of encryption schemes is a collection of ECIES variants.
The goal of this is library is to become a one-stop shop for everything ECIES.
For project details like ECIES variant flowcharts, explanations, license, and release tracks please see the README.md on GitHub.
⚠️ Alpha Release Track - Not Production Ready ⚠️
During alpha development, versions 0.1.Z, there is no guarantee of backwards compatibility and the API can change at any time. If you decide to use this library at this time, make sure that you always use the latest version, and be prepared to update your usage of the library often.
The mechanics of libes
Internally, libes is built up using generics. This allows the library to add support for algorithms with only a couple lines of code per algorithm to glue the dependency providing that algorithm with the private trait system. Then all the procedures are automatically & appropriately implemented with the help of generics & constraints. This significantly reduces the risk for human error, and ensures that the behavior is uniform between all supported algorithms.
Externally, this is abstracted for the user with the struct Ecies<K, E, A> where:
K
is an Elliptic Curve algorithm from keyE
is an Encryption algorithm from encA
is an Authentication algorithm from auth
Ecies<K, E, A> can be instantiated using the associated function new(recipient_public_key), and then the method encrypt(plaintext) will become available to use for encryption. The instantiated struct can be safely reused to encrypt multiple messages for the same recipient. The struct also has an associated function decrypt(recipient_secret_key, ciphertext) for decryption.
The library user is responsible for choosing K
& E
that are compatible with A
,
otherwise encryption and/or decryption functionality will not be available on the struct.
Compatibility can be determined by checking whether K
& E
implement:
- EciesMacEncryptionSupport/EciesMacDecryptionSupport if
A
is of variantECIES-MAC
e.g. HmacSha256 - EciesAeadEncryptionSupport/EciesAeadDecryptionSupport if
A
is Aead - EciesSynEncryptionSupport/EciesSynDecryptionSupport if
A
is Syn
Short usage guide
- We decide that we want to use the
ECIES-AEAD
variant - We need to choose an Elliptic Curve algorithm from key and an Encryption algorithm from enc that are compatible with
ECIES-AEAD
- Both key::X25519 and enc::XChaCha20Poly1305 implement EciesAeadEncryptionSupport and EciesAeadDecryptionSupport, so we can choose to use those algorithms
- We will use auth::Aead to mark that it is our Authentication algorithm of choice
- We enable the corresponding features for the libes dependency to compile our chosen functionality
[dependencies.libes] version = "*" # For the Alpha Release Track, always use the latest version features = ["ECIES-AEAD", "x25519", "XChaCha20-Poly1305"]
Code example
Receiver
// Create an alias for Ecies with our chosen algorithms
type MyEcies = Ecies<key::X25519, enc::XChaCha20Poly1305, auth::Aead>;
// Generate an appropriate elliptic key pair
let secret_key = x25519_dalek::StaticSecret::new(rand_core::OsRng);
let public_key = x25519_dalek::PublicKey::from(&secret_key);
// Convert public_key to bytes
let public_key_bytes = public_key.to_bytes().to_vec();
// Send public_key_bytes to the message sender
~~~ Network ~~~
Sender
// Create an alias for Ecies with our chosen algorithms
type MyEcies = Ecies<key::X25519, enc::XChaCha20Poly1305, auth::Aead>;
// Instantiate Ecies using the received public_key_bytes
let encryptor = MyEcies::try_new(public_key_bytes)?;
// Encrypt the message
let message = b"Hello Alice, this is Bob.";
let encrypted_message = encryptor.encrypt(message)?;
// Send encrypted_message to the message recipient
~~~ Network ~~~
Receiver
// Create an alias for Ecies with our chosen algorithms
type MyEcies = Ecies<key::X25519, enc::XChaCha20Poly1305, auth::Aead>;
// Decrypt the message
let decrypted_message = MyEcies::decrypt(secret_key, &encrypted_message)?;
Algorithm support
Matrix entries are of form Encryption & Decryption
or Encryption
/Decryption
Support icon legend
- 🚀 Completed
- 🏗️ Development
- 📅 Planned
- 🤔 Planning
- 🚫 Can/Will not implement
Elliptic Curve Support Matrix
Algorithm/ECIES Variant | ECIES-MAC | ECIES-AEAD | ECIES-SYN |
---|---|---|---|
x25519 | 🚀 | 🚀 | 🚀 |
ed25519 | 🏗️️ | 🏗️ | 🏗️ |
K-256 / secp256k1 | 📅 | 📅 | 📅 |
P-256 / secp256r1 | 📅 | 📅 | 📅 |
P-384 / secp384r1 | 🤔 | 🤔 | 🤔 |
P-521 / secp521r1 | 🤔 | 🤔 | 🤔 |
Encryption Support Matrix
Algorithm/ECIES Variant | ECIES-MAC | ECIES-AEAD | ECIES-SYN |
---|---|---|---|
ChaCha20-Poly1305 | 🚫1/🚫2 | 🚫1/🚫2 | 🚫1/🚫2 |
XChaCha20-Poly1305 | 🚀 | 🚀 | 🚀 |
AES-GCM | 📅 | 📅 | 📅 |
Authentication Support Matrix
Algorithm/ECIES Variant | ECIES-MAC |
---|---|
HMAC-SHA256 | 🚀 |
HMAC-SHA512 | 🤔 |
Modules
libes
libes
libes
Structs
ECIES
instance