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 all commits
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
50 changes: 50 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,50 @@
# LMS

- **Algorithm type**: Digital signature scheme.
- **Main cryptographic assumption**: hash function second-preimage resistance.
- **Principal submitters**: Scott Fluhrer.
- **Auxiliary submitters**: C Martin, Maurice Hieronymus.
- **Authors' website**: https://www.rfc-editor.org/info/rfc8554
- **Specification version**: None.
- **Primary Source**<a name="primary-source"></a>:
- **Source**: https://github.com/cisco/hash-sigs
- **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 |
216 changes: 216 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,216 @@
name: LMS
type: stateful signature
principal-submitters:
- Scott Fluhrer
auxiliary-submitters:
SWilson4 marked this conversation as resolved.
Show resolved Hide resolved
- C Martin
- Maurice Hieronymus

crypto-assumption: hash function second-preimage resistance
website: https://www.rfc-editor.org/info/rfc8554
nist-round:
spec-version:
spdx-license-identifier:
primary-upstream:
source: https://github.com/cisco/hash-sigs
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
29 changes: 29 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,29 @@

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 Signatures**

The security of hash based signatures (HBS) is based on the underlying hash functions on which they are built.
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.

<ins>**General**</ins>

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 generation be done in hardware security modules.
Having said that, this library is fully functional for research purposes. Secret keys are incremented after each sign operation.
However, secure storage and lifecycle management of the secret keys are left to applications using this feature.
Secret key storage is easily done by supplying a callback function to the library. This callback is invoked to store the secret key.


<ins>**Key State Management**</ins>

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 advanced (to prevent reuse).

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.
When the counter is down to 0, signature generation fails. Applications can query the remaining count via an API.


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**: hash function second-preimage resistance.
- **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