Crate libes

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 key
• E is an Encryption algorithm from enc
• A 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 variant ECIES-MAC e.g. HmacSha256
• EciesAeadEncryptionSupport/EciesAeadDecryptionSupport if A is Aead
• EciesSynEncryptionSupport/EciesSynDecryptionSupport if A is Syn

Short usage guide

1. We decide that we want to use the ECIES-AEAD variant
2. We need to choose an Elliptic Curve algorithm from key and an Encryption algorithm from enc that are compatible with ECIES-AEAD
3. Both key::X25519 and enc::XChaCha20Poly1305 implement EciesAeadEncryptionSupport and EciesAeadDecryptionSupport, so we can choose to use those algorithms
4. We will use auth::Aead to mark that it is our Authentication algorithm of choice
5. 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	🤔

---

1. ChaCha20 uses a 96-bit nonce, which when generated using a random function has an unsatisfactory risk of collision. XChaCha20 uses a 192-bit nonce where that is no longer an issue. ↩

2. Will not encourage using potentially weak encryption ¹ by implementing decryption for it ↩

Modules

auth

Markers for Authentication algorithms supported by libes

enc

Markers for Encryption algorithms supported by libes

key

Markers for Elliptic Curve algorithms supported by libes

markers

Support marker traits

Structs

Ecies

Generic ECIES instance

Enums

EciesError

KeyError