Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation and license text. #1663

Merged
merged 3 commits into from
Jan 19, 2024
Merged

Update documentation and license text. #1663

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8ac8f3f
Update documentation and license text.
ashman-p Jan 12, 2024
8f3ae22
Fix missing CR in calls to printf
ashman-p Jan 17, 2024
fefbdfc
Updates per review comments
ashman-p Jan 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions docs/algorithms/sig_stfl/lms.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# LMS

- **Algorithm type**: Digital signature scheme.
- **Main cryptographic assumption**: stateful hash-based signatures.
- **Principal submitters**: Scott Fluhrer.
- **Authors' website**: https://www.rfc-editor.org/info/rfc8554
- **Specification version**: None.
- **Primary Source**<a name="primary-source"></a>:
- **Source**: None
- **Implementation license (SPDX-Identifier)**: MIT


## Parameter set summary

| Parameter set | Security model | Claimed NIST Level | Public key size (bytes) | Secret key size (bytes) | Signature size (bytes) |
|:------------------------:|:-----------------|:---------------------|--------------------------:|--------------------------:|-------------------------:|
| LMS_SHA256_H5_W1 | | | 60 | 64 | 8688 |
| LMS_SHA256_H5_W2 | | | 60 | 64 | 4464 |
| LMS_SHA256_H5_W4 | | | 60 | 64 | 2352 |
| LMS_SHA256_H5_W8 | | | 60 | 64 | 1296 |
| LMS_SHA256_H10_W1 | | | 60 | 64 | 8848 |
| LMS_SHA256_H10_W2 | | | 60 | 64 | 4624 |
| LMS_SHA256_H10_W4 | | | 60 | 64 | 2512 |
| LMS_SHA256_H10_W8 | | | 60 | 64 | 1456 |
| LMS_SHA256_H15_W1 | | | 60 | 64 | 9008 |
| LMS_SHA256_H15_W2 | | | 60 | 64 | 4784 |
| LMS_SHA256_H15_W4 | | | 60 | 64 | 2672 |
| LMS_SHA256_H15_W8 | | | 60 | 64 | 1616 |
| LMS_SHA256_H20_W1 | | | 60 | 64 | 9168 |
| LMS_SHA256_H20_W2 | | | 60 | 64 | 4944 |
| LMS_SHA256_H20_W4 | | | 60 | 64 | 2832 |
| LMS_SHA256_H20_W8 | | | 60 | 64 | 1776 |
| LMS_SHA256_H25_W1 | | | 60 | 64 | 9328 |
| LMS_SHA256_H25_W2 | | | 60 | 64 | 5104 |
| LMS_SHA256_H25_W4 | | | 60 | 64 | 2992 |
| LMS_SHA256_H25_W8 | | | 60 | 64 | 1936 |
| LMS_SHA256_H5_W8_H5_W8 | | | 60 | 64 | 2644 |
| LMS_SHA256_H10_W4_H5_W8 | | | 60 | 64 | 2804 |
| LMS_SHA256_H10_W8_H5_W8 | | | 60 | 64 | 3860 |
| LMS_SHA256_H10_W2_H10_W2 | | | 60 | 64 | 9300 |
| LMS_SHA256_H10_W4_H10_W4 | | | 60 | 64 | 5076 |
| LMS_SHA256_H10_W8_H10_W8 | | | 60 | 64 | 2964 |
| LMS_SHA256_H15_W8_H5_W8 | | | 60 | 64 | 2964 |
| LMS_SHA256_H15_W8_H10_W8 | | | 60 | 64 | 3124 |
| LMS_SHA256_H15_W8_H15_W8 | | | 60 | 64 | 3284 |
| LMS_SHA256_H20_W8_H5_W8 | | | 60 | 64 | 3124 |
| LMS_SHA256_H20_W8_H10_W8 | | | 60 | 64 | 3284 |
| LMS_SHA256_H20_W8_H15_W8 | | | 60 | 64 | 3444 |
| LMS_SHA256_H20_W8_H20_W8 | | | 60 | 64 | 3604 |
214 changes: 214 additions & 0 deletions docs/algorithms/sig_stfl/lms.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,214 @@
name: LMS
type: stateful signature
principal-submitters:
- Scott Fluhrer
auxiliary-submitters:
SWilson4 marked this conversation as resolved.
Show resolved Hide resolved

crypto-assumption: stateful hash-based signatures
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably be more specific and write something like "second preimage resistance of SHA-256". However, since the security proofs for LMS all seem to rely on random oracle assumptions on SHA-256 or one of its components, I'm not quite sure what to put here. Ideas @dstebila?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated with "second preimage resistance of SHA-256"

website: https://www.rfc-editor.org/info/rfc8554
nist-round:
spec-version:
spdx-license-identifier:
primary-upstream:
source:
spdx-license-identifier: MIT
SWilson4 marked this conversation as resolved.
Show resolved Hide resolved
upstream-ancestors:
parameter-sets:
- name: LMS_SHA256_H5_W1
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 8688
- name: LMS_SHA256_H5_W2
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 4464
- name: LMS_SHA256_H5_W4
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 2352
- name: LMS_SHA256_H5_W8
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 1296
- name: LMS_SHA256_H10_W1
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 8848
- name: LMS_SHA256_H10_W2
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 4624
- name: LMS_SHA256_H10_W4
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 2512
- name: LMS_SHA256_H10_W8
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 1456
- name: LMS_SHA256_H15_W1
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 9008
- name: LMS_SHA256_H15_W2
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 4784
- name: LMS_SHA256_H15_W4
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 2672
- name: LMS_SHA256_H15_W8
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 1616
- name: LMS_SHA256_H20_W1
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 9168
- name: LMS_SHA256_H20_W2
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 4944
- name: LMS_SHA256_H20_W4
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 2832
- name: LMS_SHA256_H20_W8
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 1776
- name: LMS_SHA256_H25_W1
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 9328
- name: LMS_SHA256_H25_W2
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 5104
- name: LMS_SHA256_H25_W4
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 2992
- name: LMS_SHA256_H25_W8
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 1936
- name: LMS_SHA256_H5_W8_H5_W8
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 2644
- name: LMS_SHA256_H10_W4_H5_W8
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 2804
- name: LMS_SHA256_H10_W8_H5_W8
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 3860
- name: LMS_SHA256_H10_W2_H10_W2
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 9300
- name: LMS_SHA256_H10_W4_H10_W4
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 5076
- name: LMS_SHA256_H10_W8_H10_W8
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 2964
- name: LMS_SHA256_H15_W8_H5_W8
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 2964
- name: LMS_SHA256_H15_W8_H10_W8
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 3124
- name: LMS_SHA256_H15_W8_H15_W8
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 3284
- name: LMS_SHA256_H20_W8_H5_W8
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 3124
- name: LMS_SHA256_H20_W8_H10_W8
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 3284
- name: LMS_SHA256_H20_W8_H15_W8
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 3444
- name: LMS_SHA256_H20_W8_H20_W8
claimed-nist-level:
claimed-security:
length-public-key: 60
length-secret-key: 64
length-signature: 3604
27 changes: 27 additions & 0 deletions docs/algorithms/sig_stfl/sig_stfl.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good idea to add this file! Can you add a little bit of markdown formatting to it?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. Done.

Stateful Hash Based Signature
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Stateful Hash Based Signature
Stateful Hash Based Signatures


The security of hash based signatures (HBS) is based on the underlaying hash functions on which they are built.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The security of hash based signatures (HBS) is based on the underlaying hash functions on which they are built.
The security of hash based signatures (HBS) is based on the underlying hash functions on which they are built.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

NIST recommendation is that they are suitable for near term use to mitigate against attacks mounted by quantum computers.
While not a general purpose solution, they are useful means to authenticate boot or firmware images.

This package provides full support for a variety of variants for XMSS and LMS.
Key generation, signature generation, and signature verification.
Security of HBS also depends on the management of the state of the secret key. Secret keys can only used once to generate a signature.
Multiple signing with same key can reveal that key to an attacker.
Because of this, NIST recommends that key and signature aeration be done in hardware security modules.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Because of this, NIST recommends that key and signature aeration be done in hardware security modules.
Because of this, NIST recommends that key and signature iteration be done in hardware security modules.

I think (?)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed (generation)

Having said that, this library is fully functional for research purposes. Storage and management of the secret keys are left update applications using this feature.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Having said that, this library is fully functional for research purposes. Storage and management of the secret keys are left update applications using this feature.
Having said that, this library is fully functional for research purposes. Storage and management of the secret keys are left up to applications using this feature.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

Secret key storage is easily done when by supplying a callback function to the library.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Secret key storage is easily done when by supplying a callback function to the library.
Secret key storage is easily done by supplying a callback function to the library.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.



Key State Management:
Application writers have to supply callback functions to store and update secret keys.
After a sign operation the secret key index is advanced and stored. This ensures one-time use of the key.
Signing operations will fail without this callback set because the private key cannot be advance (to prevent reuse).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Signing operations will fail without this callback set because the private key cannot be advance (to prevent reuse).
Signing operations will fail without this callback set because the private key cannot be advanced (to prevent reuse).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.


Stateful keys can generate a finite number signatures. A counter tracks the limit when the key is created and is decremented after each signature is generated.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Stateful keys can generate a finite number signatures. A counter tracks the limit when the key is created and is decremented after each signature is generated.
Stateful keys can generate a finite number of signatures. A counter tracks the limit when the key is created and is decremented after each signature is generated.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

When the counter is down to 0, signature generations fails. Applications can query the remaining count via an API.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When the counter is down to 0, signature generations fails. Applications can query the remaining count via an API.
When the counter is down to 0, signature generation fails. Applications can query the remaining count via an API.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.


Multithreaded application will need to set lock and unlock callbacks for the library to use. This is needed to ensure that only one thread can access a given secret key
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Multithreaded application will need to set lock and unlock callbacks for the library to use. This is needed to ensure that only one thread can access a given secret key
Multithreaded applications will need to set lock and unlock callbacks for the library to use. This is needed to ensure that only one thread can access a given secret key

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

for signing and update operations.

44 changes: 44 additions & 0 deletions docs/algorithms/sig_stfl/xmss.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# XMSS

- **Algorithm type**: Digital signature scheme.
- **Main cryptographic assumption**: stateful hash-based signatures.
- **Principal submitters**: Joost Rijneveld, A. Huelsing, David Cooper, Bas Westerbaan.
- **Authors' website**: https://www.rfc-editor.org/info/rfc8391
- **Specification version**: None.
- **Primary Source**<a name="primary-source"></a>:
- **Source**: https://github.com/XMSS/xmss-reference
- **Implementation license (SPDX-Identifier)**: Apache-2.0 AND MIT


## Parameter set summary

| Parameter set | Security model | Claimed NIST Level | Public key size (bytes) | Secret key size (bytes) | Signature size (bytes) |
|:----------------------:|:-----------------|:---------------------|--------------------------:|--------------------------:|-------------------------:|
| XMSS-SHA2_10_256 | | | 64 | 1373 | 2500 |
| XMSS-SHA2_16_256 | | | 64 | 2093 | 2692 |
| XMSS-SHA2_20_256 | | | 64 | 2573 | 2820 |
| XMSS-SHAKE_10_256 | | | 64 | 1373 | 2500 |
| XMSS-SHAKE_16_256 | | | 64 | 2093 | 2692 |
| XMSS-SHAKE_20_256 | | | 64 | 2573 | 2820 |
| XMSS-SHA2_10_512 | | | 128 | 2653 | 9092 |
| XMSS-SHA2_16_512 | | | 128 | 4045 | 9476 |
| XMSS-SHA2_20_512 | | | 128 | 2653 | 9732 |
| XMSS-SHAKE_10_512 | | | 128 | 2653 | 9092 |
| XMSS-SHAKE_16_512 | | | 128 | 4045 | 9476 |
| XMSS-SHAKE_20_512 | | | 128 | 4973 | 9732 |
| XMSSMT-SHA2_20/2_256 | | | 64 | 5998 | 4963 |
| XMSSMT-SHA2_20/4_256 | | | 64 | 10938 | 9251 |
| XMSSMT-SHA2_40/2_256 | | | 64 | 9600 | 5605 |
| XMSSMT-SHA2_40/4_256 | | | 64 | 15252 | 9893 |
| XMSSMT-SHA2_40/8_256 | | | 64 | 24516 | 18469 |
| XMSSMT-SHA2_60/3_256 | | | 64 | 16629 | 8392 |
| XMSSMT-SHA2_60/6_256 | | | 64 | 24507 | 14824 |
| XMSSMT-SHA2_60/12_256 | | | 64 | 38095 | 27688 |
| XMSSMT-SHAKE_20/2_256 | | | 64 | 5998 | 4963 |
| XMSSMT-SHAKE_20/4_256 | | | 64 | 10938 | 9251 |
| XMSSMT-SHAKE_40/2_256 | | | 64 | 9600 | 5605 |
| XMSSMT-SHAKE_40/4_256 | | | 64 | 15252 | 9893 |
| XMSSMT-SHAKE_40/8_256 | | | 64 | 24516 | 18469 |
| XMSSMT-SHAKE_60/3_256 | | | 64 | 24516 | 8392 |
| XMSSMT-SHAKE_60/6_256 | | | 64 | 24507 | 14824 |
| XMSSMT-SHAKE_60/12_256 | | | 64 | 38095 | 27688 |
Loading
Loading