libes

library of encryption scheme(s) is a collection of ECIES variants.

The goal of this is library is to become a one-stop shop for everything ECIES.

For code documentation, usage explanations, and examples please see Docs.rs.

Why use libes?

The rust cryptography ecosystem is swarming with crates, with varying degrees of quality and documentation. I have taken it onto myself to navigate this, and I want to share my findings with those who are trying to make sense of it like me.

In doing this I commit myself to:

Maintaining a curated selection of relevant crates
- Verifying that dependencies have not made mistakes in their implementations
- Using dependencies with good performance and a high quality of code and documentation
Providing a uniform and predictable API
- Using shared constructors in the API to guarantee uniformity
- Guaranteeing long-term support for all major releases
- Striving for a high degree of clarity and detail in the documentation
Keeping the library up to date & vulnerability-free
- Automatically updating dependencies and testing code
- Prioritizing issues & feedback on implementations

libes
- Why use libes?
Table of Contents
FAQ
About
Algorithm support
License
Contributing

FAQ

TBD

About

What is ECIES?

ECIES stands for Elliptic Curve Integrated Encryption Scheme. It is a type of cryptographic procedure which allows encrypting data for a specific recipient given only the data to be encrypted and the recipients public key, everything else is derived from the input or generated with a CSPRNG (Cryptographically Secure Pseudo-Random Number Generator).

Wikipedia
Crypto++
Practical Cryptography for Developers

ECIES Variants

Cryptographic algorithms have evolved over time, and thus have grown into two distinct ECIES variants as of writing.

Originally, ECIES relied on a key exchange operation, an encryption operation, and a separate MAC operation.

A MAC (Message Authentication Code) is necessary to provide Authenticity on top of Confidentiality. By exploiting vulnerabilities and/or compromised parameters, encrypted data could potentially be manipulated to produce a desired output, other than what the sender intended. A MAC can be used separately from the encrypted data to verify that such manipulation did not take place.

More recently adopted encryption algorithms like AES-GCM and ChaCha20-Poly1305 are AEAD (Authenticated Encryption with Additional Data) algorithms which in addition to a ciphertext, also produce an Authentication Tag which serves the same purpose that a MAC does in this case, but is integrated in the encryption algorithm itself.

The library and documentation will refer to these two variants as:

ECIES-MAC (Encryption with MAC)
ECIES-AEAD (AEAD Encryption instead of MAC)

Iterating further on ECIES-AEAD, it could be further integrated by synthesizing the IV/Nonce rather than generating it randomly. This would eliminate the need to store & transmit the Nonce, as well as reduce the overhead by one or two dozen bytes. Because there is already random data in the ephemeral key, the risk of deriving the same encryption key twice is minimal, and thus it should be safe to do so. This third variant will be referred to as ECIES-SYN.

DISCLAIMER: ECIES-SYN is my own idea, which I will only implement for algorithms that I have done extensive research on to ensure that it is cryptographically secure to do so. Regardless, I am not a cryptography researcher and I can not give a guarantee that issues will not arise in the future. If ECIES-SYN turns out to be useful/popular and resources allow, I will make sure that it receives a security audit.

ECIES-MAC Flowchart

Flowchart color coding:

Red: Encryption
Green: Elliptic Curve
Blue: Authentication

graph TB
    subgraph Input
        RK(Recipient's Public Key)
        MSG(Plaintext)
    end
    
    subgraph Generate
        CSPRNG(CSPRNG)
        EK_PUB(Ephemeral Public Key)
        EK_PRI(Ephemeral Private Key)
        IV(IV/Nonce)
    end
    
    subgraph Derive
        DER_FN("Derive Shared Secret</br>(e.g. with ECDH -> HKDF-SHA256)</br><- and split ->")
        DER_ENC_KEY("Derived Encryption Key")
        DER_MAC_KEY("Derived MAC Key")
    end
    
    subgraph Process
        ENC_FN("Encrypt</br>(e.g. with AES-CBC)")
        MAC_FN("MAC</br>(e.g. with HMAC-SHA256)")
    end
    
    subgraph Output
        ENC_OUT(Ciphertext)
        IV_OUT(IV/Nonce)
        EK_OUT(Ephemeral Public Key)
        MAC_OUT(MAC)
    end

    CSPRNG --> IV & EK_PRI
    EK_PRI --> EK_PUB
    EK_PUB --> EK_OUT & MAC_FN
    IV --> IV_OUT & MAC_FN & ENC_FN
    RK --> DER_FN
    EK_PRI --> DER_FN
    DER_FN --> DER_ENC_KEY & DER_MAC_KEY
    DER_ENC_KEY --> ENC_FN
    DER_MAC_KEY --> MAC_FN
    MSG --> ENC_FN
    ENC_FN --> MAC_FN & ENC_OUT
    MAC_FN --> MAC_OUT
    EK_PUB --> |Encapsulation| DER_FN
    
    %% Elliptic Curve Key link colorization
    linkStyle 2 stroke:#98fb98,stroke-width:2px;
    linkStyle 3 stroke:#98fb98,stroke-width:2px;
    linkStyle 8 stroke:#98fb98,stroke-width:2px;
    linkStyle 9 stroke:#98fb98,stroke-width:2px;
    linkStyle 18 stroke:#98fb98,stroke-width:2px;
    
    %% Authentication link colorization
    linkStyle 4 stroke:#0096ff,stroke-width:2px;
    linkStyle 6 stroke:#0096ff,stroke-width:2px;
    linkStyle 11 stroke:#0096ff,stroke-width:2px;
    linkStyle 13 stroke:#0096ff,stroke-width:2px;
    linkStyle 15 stroke:#0096ff,stroke-width:2px;
    linkStyle 17 stroke:#0096ff,stroke-width:2px;
    
    %% Encryption link colorization
    linkStyle 7 stroke:#f88379,stroke-width:2px;
    linkStyle 10 stroke:#f88379,stroke-width:2px;
    linkStyle 12 stroke:#f88379,stroke-width:2px;
    linkStyle 14 stroke:#f88379,stroke-width:2px;
    linkStyle 16 stroke:#f88379,stroke-width:2px;

ECIES-AEAD Flowchart

Flowchart color coding:

Red: Encryption
Green: Elliptic Curve
Blue: IV/Nonce

graph TB
    subgraph Input
        RK(Recipient's Public Key)
        MSG(Plaintext)
    end
    
    subgraph Generate
        CSPRNG(CSPRNG)
        EK_PUB(Ephemeral Public Key)
        EK_PRI(Ephemeral Private Key)
        IV(IV/Nonce)
    end
    
    subgraph Derive
        DER_FN("Derive Shared Secret</br>(e.g. with ECDH -> HKDF-SHA256)")
        DER_ENC_KEY("Derived Encryption Key")
    end
    
    subgraph Process
        ENC_FN("Encrypt using AEAD</br>(e.g. with AES-GCM)")
    end
    
    subgraph Output
        ENC_OUT(Ciphertext)
        IV_OUT(IV/Nonce)
        EK_OUT(Ephemeral Public Key)
    end
    
    CSPRNG --> EK_PRI & IV
    EK_PRI --> EK_PUB
    EK_PUB --> EK_OUT
    RK --> DER_FN
    EK_PRI --> DER_FN
    DER_FN --> DER_ENC_KEY
    DER_ENC_KEY --> ENC_FN
    MSG --> ENC_FN
    ENC_FN --> ENC_OUT
    IV --> ENC_FN & IV_OUT
    EK_PUB --> |Encapsulation| DER_FN
    
    %% Elliptic Curve Key link colorization
    linkStyle 2 stroke:#98fb98,stroke-width:2px;
    linkStyle 3 stroke:#98fb98,stroke-width:2px;
    linkStyle 4 stroke:#98fb98,stroke-width:2px;
    linkStyle 5 stroke:#98fb98,stroke-width:2px;
    linkStyle 12 stroke:#98fb98,stroke-width:2px;
    
    %% Nonce link colorization
    linkStyle 10 stroke:#0096ff,stroke-width:2px;
    linkStyle 11 stroke:#0096ff,stroke-width:2px;
    
    %% Encryption link colorization
    linkStyle 6 stroke:#f88379,stroke-width:2px;
    linkStyle 7 stroke:#f88379,stroke-width:2px;
    linkStyle 8 stroke:#f88379,stroke-width:2px;
    linkStyle 9 stroke:#f88379,stroke-width:2px;

ECIES-SYN Flowchart

Flowchart color coding:

Red: Encryption
Green: Elliptic Curve
Blue: IV/Nonce

graph TB
    subgraph Input
        RK(Recipient's Public Key)
        MSG(Plaintext)
    end
    
    subgraph Generate
        CSPRNG(CSPRNG)
        EK_PUB(Ephemeral Public Key)
        EK_PRI(Ephemeral Private Key)
    end
    
    subgraph Derive
        DER_FN("Derive Shared Secret</br>(e.g. with ECDH -> HKDF-SHA256)</br><- and split ->")
        DER_IV("Derived IV/Nonce")
        DER_ENC_KEY("Derived Encryption Key")
    end
    
    subgraph Process
        ENC_FN("Encrypt using AEAD</br>(e.g. with AES-GCM)")
    end
    
    subgraph Output
        ENC_OUT(Ciphertext</br>with Authentication Tag)
        EK_OUT(Ephemeral Public Key)
    end
    
    CSPRNG --> EK_PRI
    EK_PRI --> EK_PUB
    EK_PUB --> EK_OUT
    RK --> DER_FN
    EK_PRI --> DER_FN
    DER_FN --> DER_ENC_KEY & DER_IV
    DER_IV --> ENC_FN
    DER_ENC_KEY --> ENC_FN
    MSG --> ENC_FN
    ENC_FN --> ENC_OUT
    EK_PUB --> |Encapsulation| DER_FN
    
    %% Elliptic Curve Key link colorization
    linkStyle 1 stroke:#98fb98,stroke-width:2px;
    linkStyle 2 stroke:#98fb98,stroke-width:2px;
    linkStyle 3 stroke:#98fb98,stroke-width:2px;
    linkStyle 4 stroke:#98fb98,stroke-width:2px;
    linkStyle 11 stroke:#98fb98,stroke-width:2px;
    
    %% Nonce link colorization
    linkStyle 5 stroke:#0096ff,stroke-width:2px;
    linkStyle 8 stroke:#0096ff,stroke-width:2px;
    
    %% Encryption link colorization
    linkStyle 6 stroke:#f88379,stroke-width:2px;
    linkStyle 7 stroke:#f88379,stroke-width:2px;
    linkStyle 9 stroke:#f88379,stroke-width:2px;
    linkStyle 10 stroke:#f88379,stroke-width:2px;

SemVer

This library respects SemVer, and guarantees decryption backwards compatibility.

This means that data encrypted using library version X.Y.Z can be decrypted using any superseding library version as long as X is the same.

For example, data encrypted using version 0.5.7 can be decrypted using version 0.5.7 or 0.11.1, but not using versions 1.2.3, 0.5.6, or 0.4.10.

Effort will be made to keep X, the major version, decryption backwards compatible as well, but no guarantee is given.

Release Tracks

v0.1.Z: alpha - initial strcuture
v0.(2+).Z: beta - adding algorithms
v1.0.0-pre.W: pre-production - refactoring & memory zeroing implementation
v1.0.0: initial production - potentially backwards-incompatible refactoring
V1.(1+).Z: production - wasm support & more

Conditional Compilation

All algorithm combinations are gated behind features, to reduce how much is being compiled. Features are named exactly like the algorithm names in the support matrices (if there are alternative names like P-521 and secp521r1 then they are aliases, so you can enable either). This library uses traits to implement appropriate functionality on valid user-defined variants.

NOTE: No ECIES variants are available without activating any features, at minimum one of each feature categories must be activated:

Elliptic Curve (e.g. x25519)
Encryption (e.g. AES-GCM)
Authentication (e.g. ECIES-AEAD or HMAC-SHA256)

NOTE: For a ECIES combination to be valid the Elliptic Curve, Encryption, and Authentication algorithms must all support the same ECIES variant.

To use ECIES-MAC, all three chosen algorithms need a "🚀" in their respective ECIES-MAC columns
To use ECIES-AEAD or ECIES-SYN both first two algorithms need a "🚀" in the variant column

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	🚫¹/🚫²	🚫¹/🚫²	🚫¹/🚫²
XChaCha20-Poly1305	🚀	🚀	🚀
AES-GCM	📅	📅	📅

Authentication Support Matrix

Algorithm/ECIES Variant	ECIES-MAC
HMAC-SHA256	🚀
HMAC-SHA512	🤔

License

Licensed under either of:

at your option.

Contributing

All contributions are very appreciated. If you spot a mistake or a vulnerability in this crate or any of its dependencies please open an issue. Currently, there is no template for issues or pull requests, but please try to include enough information to be able to determine what to do without having to ask too many follow-up questions.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

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. ↩ ↩² ↩³ ↩⁴
Will not encourage using potentially weak encryption ¹ by implementing decryption for it ↩ ↩² ↩³

libes
Release 0.9.1

Release 0.9.1

0.9.1

0.9.0

0.5.1

0.5.0

0.4.1

0.4.0

0.3.1

0.3.0

0.2.0

0.2.0-pre.0

Documentation

libes

Why use libes?

Table of Contents

FAQ

About

What is ECIES?

ECIES Variants

ECIES-MAC Flowchart

ECIES-AEAD Flowchart

ECIES-SYN Flowchart

SemVer

Release Tracks

Conditional Compilation

Algorithm support

Support icon legend

Elliptic Curve Support Matrix

Encryption Support Matrix

Authentication Support Matrix

License

Contributing

Stats

Development practices

Releases

Maintainers

Contributors

libes Release 0.9.1

Release 0.9.1 Toggle Dropdown 0.9.1 0.9.0 0.5.1 0.5.0 0.4.1 0.4.0 0.3.1 0.3.0 0.2.0 0.2.0-pre.0

Documentation

libes

Why use libes?

Table of Contents

FAQ

About

What is ECIES?

ECIES Variants

ECIES-MAC Flowchart

ECIES-AEAD Flowchart

ECIES-SYN Flowchart

SemVer

Release Tracks

Conditional Compilation

Algorithm support

Support icon legend

Elliptic Curve Support Matrix

Encryption Support Matrix

Authentication Support Matrix

License

Contributing

Footnotes

Stats

Development practices

Releases

Maintainers

Contributors

libes
Release 0.9.1

Release 0.9.1

0.9.1

0.9.0

0.5.1

0.5.0

0.4.1

0.4.0

0.3.1

0.3.0

0.2.0

0.2.0-pre.0