Skip to content

Commit 1b6238d

Browse files
curiecryptcuriecrypt
committed
functionality and roadmap
1 parent 1d3b5c9 commit 1b6238d

File tree

1 file changed

+113
-94
lines changed

1 file changed

+113
-94
lines changed

‎docs/leios-design/README.md‎

Lines changed: 113 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -618,7 +618,7 @@ Corresponding types with instances of `EncCBOR` and `DecCBOR` must be provided i
618618
>
619619
> Work in progress. Content is created based on [impact analysis](../ImpactAnalysis.md), [Leios crypto project board](https://github.com/orgs/IntersectMBO/projects/75), and [CIP](https://github.com/cardano-scaling/CIPs/blob/leios/CIP-0164/README.md).
620620
>
621-
> TODO: Write: risks and mitigations, roadmap. Complete: implementation plan.
621+
> TODO: Contribution from crypto team.
622622
623623
In Leios, EBs are compactly certified for inclusion in RBs.
624624
Certification is achieved through a voting mechanism in which committee members cast votes referencing specific EBs, and these votes are then aggregated into compact certificates.
@@ -713,111 +713,130 @@ This section presents the implementation plan for extending `cardano-base` with
713713
The requirements are organized into two main categories: **core functionality**, which defines the essential BLS operations needed, and **performance and quality**, which ensures the implementation meets the expected efficiency, reliability, and maintainability standards.
714714
715715
#### Core functionality
716-
**BLS types**
717-
- The `BLS12_381.Internal` module in `cardano-base` already provides a comprehensive set of types designed for safe interaction with the linked C functions from the `blst` library.
718-
- As part of the integration effort, it is necessary to evaluate which additional types should be introduced beyond those already defined, ensuring full support for the BLS functionality required by Leios.
719-
720-
**Key generation**
721-
- Secure key generation must ensure strong randomness and resilience against side-channel attacks. To achieve this, an integration with the `blst` library through a FFI is required. This involves adding the necessary foreign function imports to the `BLS12_381.Internal` module and implementing the corresponding `SecretKey` type to enable safe and efficient handling of secret keys within the Haskell environment.
722-
- The `blst` library exposes a key-generation function [`blst_keygen`](https://github.com/supranational/blst/blob/e7f90de551e8df682f3cc99067d204d8b90d27ad/bindings/blst.h#L330)
723-
```C
724-
void blst_keygen(blst_scalar *out_SK, const byte *IKM, size_t IKM_len, const byte *info DEFNULL, size_t info_len DEFNULL);
725-
```
726-
which derives a secret key from input keying material (IKM) and optional `info`. To use this safely in `cardano-base`, we need to clarify the security guarantees of this construction: what qualifies as a cryptographically secure IKM (length, entropy, generation source) and how `info` should be used (additional entropy vs. domain/context bytes). In parallel, we should examine how `cardano-base` currently sources seeds for other schemes in the `DSIGN` class, review the `blst` keygen C implementation to assess robustness and side-channel posture, align our requirements with the IETF BLS draft’s guidance on key generation (see the “KeyGen” section in the CFRG draft), and determine whether `info` is treated as entropy input or merely contextual/domain-separation data; documenting these findings will let us standardize secure IKM generation and `info` usage for BLS within `cardano-base`.
727-
728-
**Proof-of-Possession**
729-
- The `blst` C library does not provide a direct interface for generating a proof of possession ($PoP$).
730-
- This functionality must be implemented manually in `cardano-base`, leveraging the existing `blst` bindings to construct a $PoP$ from the available primitives.
731-
732-
**Public key derivation**
733-
- Implement deterministic derivation of the public key ($pk$) from the corresponding secret key ($sk$) for the selected BLS variant.
734-
- This requires adding a FFI binding to the `blst` library to enable secure and efficient key derivation within `cardano-base`.
735-
```C
736-
void blst_sk_to_pk_in_g1(blst_p1 *out_pk, const blst_scalar *SK);
737-
void blst_sk_to_pk_in_g2(blst_p2 *out_pk, const blst_scalar *SK);
738-
```
739-
740-
**Signature**
741-
- Implement signature generation and verification APIs that are variant-agnostic and support domain separation, with DST supplied by the caller. This functionality requires integrating with the `blst` library through FFI bindings, using the following functions:
742-
```C
743-
void blst_sign_pk_in_g1(blst_p2 *out_sig, const blst_p2 *hash, const blst_scalar *SK);
744-
void blst_sign_pk_in_g2(blst_p1 *out_sig, const blst_p1 *hash, const blst_scalar *SK);
745-
```
746-
For single-signature verification, correctness can be established through a standard pairing check between the signature, message hash, and public key. See [this](https://www.ietf.org/archive/id/draft-irtf-cfrg-bls-signature-05.html#name-verify).
747-
748-
**Aggregation**
749-
750-
The core cryptographic feature of Leios EB certificates is the ability to aggregate signatures from persistent voters. By combining multiple signatures into a single compact representation, we achieve significant space efficiency within EB blocks. This aggregation also enables more efficient verification, as a single pairing check can replace many individual ones—saving numerous expensive pairing operations while requiring only a few lightweight point additions in $G_1$ or $G_2$.
751-
752-
To support this functionality, several helper functions should be implemented:
753-
- A function to aggregate multiple public keys into a single aggregated key.
754-
- A function to aggregate multiple signatures into a single aggregated signature.
755-
- A function that, given a message and multiple $(pk, sig)$ pairs over that message, performs batch verification.
756-
757-
The first two functions are particularly useful for building an accumulator that locally tallies Leios votes and aggregates them in advance for block production. The third provides a one-shot approach for efficient verification. Since the optimal aggregation strategy depends on when and how votes are combined, all three functions should be implemented to support flexible and efficient use within Leios.
758-
759-
**Batch verification**
760-
- Implement a batch verification API to efficiently verify multiple $(pk, msg, sig)$ tuples.
761-
- This requires adding FFI bindings to the `blst` library.
762-
- The underlying C functions can be composed to load multiple $(pk, msg, sig)$ combinations into a single pairing context for verification.
763-
- When many of the messages are identical, it becomes more efficient to merge them beforehand.
764-
- It is advisable to use a key-value data structure where each $msg$ serves as the key, and the corresponding values are the multiple $(pk, sig)$ pairs that can be aggregated using the existing aggregation functions.
765-
766-
**DSIGN integration**
767-
768-
...
769-
770-
**Serialization**
771-
772-
...
773-
774-
**Conformance vectors**
775-
776-
...
716+
- **BLS types**
717+
- The `BLS12_381.Internal` module in `cardano-base` already provides a comprehensive set of types designed for safe interaction with the linked C functions from the `blst` library.
718+
- As part of the integration effort, it is necessary to evaluate which additional types should be introduced beyond those already defined, ensuring full support for the BLS functionality required by Leios.
719+
720+
- **Key generation**
721+
- Secure key generation must ensure strong randomness and resilience against side-channel attacks. To achieve this, an integration with the `blst` library through a FFI is required. This involves adding the necessary foreign function imports to the `BLS12_381.Internal` module and implementing the corresponding `SecretKey` type to enable safe and efficient handling of secret keys within the Haskell environment.
722+
- The `blst` library exposes a key-generation function [`blst_keygen`](https://github.com/supranational/blst/blob/e7f90de551e8df682f3cc99067d204d8b90d27ad/bindings/blst.h#L330)
723+
```C
724+
void blst_keygen(blst_scalar *out_SK, const byte *IKM, size_t IKM_len, const byte *info DEFNULL, size_t info_len DEFNULL);
725+
```
726+
which derives a secret key from input keying material (IKM) and optional `info`. To use this safely in `cardano-base`, we need to clarify the security guarantees of this construction: what qualifies as a cryptographically secure IKM (length, entropy, generation source) and how `info` should be used (additional entropy vs. domain/context bytes). In parallel, we should examine how `cardano-base` currently sources seeds for other schemes in the `DSIGN` class, review the `blst` keygen C implementation to assess robustness and side-channel posture, align our requirements with the IETF BLS draft’s guidance on key generation (see the “KeyGen” section in the CFRG draft), and determine whether `info` is treated as entropy input or merely contextual/domain-separation data; documenting these findings will let us standardize secure IKM generation and `info` usage for BLS within `cardano-base`.
727+
728+
- **Proof-of-Possession**
729+
- The `blst` C library does not provide a direct interface for generating a proof of possession ($PoP$).
730+
- This functionality must be implemented manually in `cardano-base`, leveraging the existing `blst` bindings to construct a $PoP$ from the available primitives.
731+
732+
- **Public key derivation**
733+
- Implement deterministic derivation of the public key ($pk$) from the corresponding secret key ($sk$) for the selected BLS variant.
734+
- This requires adding a FFI binding to the `blst` library to enable secure and efficient key derivation within `cardano-base`.
735+
```C
736+
void blst_sk_to_pk_in_g1(blst_p1 *out_pk, const blst_scalar *SK);
737+
void blst_sk_to_pk_in_g2(blst_p2 *out_pk, const blst_scalar *SK);
738+
```
739+
740+
- **Signature**
741+
- Implement signature generation and verification APIs that are variant-agnostic and support domain separation, with DST supplied by the caller. This functionality requires integrating with the `blst` library through FFI bindings, using the following functions:
742+
```C
743+
void blst_sign_pk_in_g1(blst_p2 *out_sig, const blst_p2 *hash, const blst_scalar *SK);
744+
void blst_sign_pk_in_g2(blst_p1 *out_sig, const blst_p1 *hash, const blst_scalar *SK);
745+
```
746+
For single-signature verification, correctness can be established through a standard pairing check between the signature, message hash, and public key. See [this](https://www.ietf.org/archive/id/draft-irtf-cfrg-bls-signature-05.html#name-verify).
747+
748+
- **Aggregation**
749+
750+
The core cryptographic feature of Leios EB certificates is the ability to aggregate signatures from persistent voters. By combining multiple signatures into a single compact representation, we achieve significant space efficiency within EB blocks. This aggregation also enables more efficient verification, as a single pairing check can replace many individual ones—saving numerous expensive pairing operations while requiring only a few lightweight point additions in $G_1$ or $G_2$.
751+
752+
To support this functionality, several helper functions should be implemented:
753+
- A function to aggregate multiple public keys into a single aggregated key.
754+
- A function to aggregate multiple signatures into a single aggregated signature.
755+
- A function that, given a message and multiple $(pk, sig)$ pairs over that message, performs batch verification.
756+
757+
The first two functions are particularly useful for building an accumulator that locally tallies Leios votes and aggregates them in advance for block production. The third provides a one-shot approach for efficient verification. Since the optimal aggregation strategy depends on when and how votes are combined, all three functions should be implemented to support flexible and efficient use within Leios.
758+
759+
- **Batch verification**
760+
- Implement a batch verification API to efficiently verify multiple $(pk, msg, sig)$ tuples.
761+
- This requires adding FFI bindings to the `blst` library.
762+
- The underlying C functions can be composed to load multiple $(pk, msg, sig)$ combinations into a single pairing context for verification.
763+
- When many of the messages are identical, it becomes more efficient to merge them beforehand.
764+
- It is advisable to use a key-value data structure where each $msg$ serves as the key, and the corresponding values are the multiple $(pk, sig)$ pairs that can be aggregated using the existing aggregation functions.
765+
766+
- **DSIGN integration**
767+
- Integrate the internal BLS signature implementation into the `DSIGN` class.
768+
- Once completed, the `cardano-base` module `BLS12_381.Internal` will expose a comprehensive set of utility functions for setting up and managing the BLS signature scheme—similar to how `DSIGN.Ed25519` provides utilities for Ed25519 signatures.
769+
- End users will not interact directly with this low-level API but will instead use the higher-level `DSIGN` class interface.
770+
- As part of this integration, a new `DSIGN` instance must be defined for BLS signatures, specifying the minimal required functions and their corresponding type signatures.
771+
772+
- **Serialization**
773+
- Implement deterministic serialization by providing `ToCBOR` and `FromCBOR` instances, as well as raw byte encodings for keys and signatures.
774+
- Enforce strict validation through length, subgroup membership, and infinity checks.
775+
- Ensure canonical compressed encodings following the Zcash standard for BLS points.
776+
777+
- **Conformance vectors**
778+
- Add conformance tests using test vectors from the initial Rust implementation to ensure cross-impl compatibility.
777779
778780
#### Performance and quality
779-
**Performance benchmarks**
780-
781-
...
781+
- **Performance benchmarks**
782+
- Benchmark single-verify, aggregate-verify, and batch-verify; report the impact of batching vs individual verification.
782783
783-
**Rust parity**
784+
- **Rust parity**
785+
- Compare performance against the Rust implementation; document gaps and ensure functional parity on vectors.
784786
785-
...
787+
- **Determinism portability**
788+
- Deterministic results across platforms/architectures; outputs independent of CPU feature detection.
786789
787-
**Determinism portability**
788-
789-
...
790-
791-
**Documentation**
792-
793-
...
790+
- **Documentation**
791+
- Document the outward facing API in cardano-base and provide example usages. Additionally add a section on do's and don'ts with regards to security of this scheme outside the context of Leios.
794792
795793
#### Other utilities
796-
**Registration**
797-
798-
...
799-
800-
**Fa sortition**
801-
802-
...
803-
804-
**Local sortition**
805-
806-
...
794+
- Registration: See [this](https://github.com/input-output-hk/ouroboros-leios/blob/d5f1a9bc940e69f406c3e25c0d7d9aa58cf701f8/crypto-benchmarks.rs/Specification.md#key-registration)
795+
- Sortition: See [this](https://github.com/input-output-hk/ouroboros-leios/blob/d5f1a9bc940e69f406c3e25c0d7d9aa58cf701f8/crypto-benchmarks.rs/Specification.md#sortition)
807796
808-
**Implementation notes**
809-
810-
...
797+
#### Implementation notes
798+
- The $PoP$ verification is likely performed at the certificate level; therefore, the API described above should not handle it directly.
799+
- The existing `BLS12_381` code already abstracts over both $G_1$ and $G_2$ curves, and this abstraction should be preserved.
800+
- The `blst` library provides optimized verification for multiple messages, signatures, and public keys using a combined pairing check.
801+
- While this functionality could offer performance benefits, it remains uncertain whether it will be necessary for linear Leios, where such batch verification may not provide a meaningful speedup.
811802
812803
### Potential Risks and Mitigations
813-
...
804+
805+
> [!WARNING]
806+
>
807+
> TODO: Contribution from crypto team.
814808
815809
### Roadmap
816-
- Delivery cycle 1
817-
- Delivery cycle 2
818-
- Delivery cycle 3
819-
- Delivery cycle 4
820-
- ...
810+
811+
> [!WARNING]
812+
>
813+
> TODO: Contribution from crypto team.
814+
815+
This roadmap outlines the planned tasks and milestones for integrating BLS functionality into `cardano-base` to support the Leios protocol.
816+
The implementation is divided into three delivery cycles, progressing from foundational FFI bindings to high-level integration and code audit.
817+
818+
#### Core Bindings and Setup
819+
<!-- Delivery cycle 1 -->
820+
*Establish the foundational Haskell ↔ C interoperability layer for BLS operations.*
821+
- Create Haskell ↔ C Bindings for the following functionalities:
822+
- Key generation,
823+
- Public key derivation,
824+
- Signature generation and verification.
825+
- Create Haskell Function for Proof-of-Possession functionality using existing `blst` primitives.
826+
827+
#### Extended Functionality and Security Review
828+
<!-- Delivery cycle 2 -->
829+
*Build higher-level cryptographic utilities, perform security validation, and finalize BLS type definitions.*
830+
- Define and Add New Types: Identify and introduce any missing types needed for safe and ergonomic BLS operations.
831+
- Create Haskell ↔ C Binding for batch verification support for efficient validation of multiple $(pk, msg, sig)$ triples.
832+
- Create Haskell Function for aggregation logic for multiple signatures and public keys to enable compact certificates.
833+
- Check Security of key generation function of the C implementation and assess its adherence to the IETF BLS standard for secure IKM handling.
834+
835+
#### Integration and Quality Assurance
836+
<!-- Delivery cycle 3 -->
837+
*Integrate BLS signatures into the `DSIGN` class and complete final review.*
838+
- Add Internal BLS Signature to `DSIGN` Class
839+
- Audit the Code
821840
822841
## Performance & Tracing (P&T)
823842

0 commit comments

Comments
 (0)