From 047f60417358c01f01c3160737233464e2a31f0c Mon Sep 17 00:00:00 2001 From: Linus Nordberg Date: Fri, 29 Apr 2022 15:19:15 +0200 Subject: change 'verification_key' to 'public_key' Critically in the API: verification_key -> public_key Less critical in describing text, changing "verification key" and "verification public key" to "public key" all over. Issue: #40 --- doc/api.md | 18 +++++++++--------- doc/design.md | 18 +++++++++--------- 2 files changed, 18 insertions(+), 18 deletions(-) (limited to 'doc') diff --git a/doc/api.md b/doc/api.md index e1912e4..5a21814 100644 --- a/doc/api.md +++ b/doc/api.md @@ -123,7 +123,7 @@ The namespace field must be set to `tree_leaf:v0:@sigsum.org`, where `` is replaced with the shortest decimal ASCII representation of `shard_hint`. This ensures a _sigsum shard-specific tree leaf context_. -`key_hash` is a hash of the signer's public verification key using the same +`key_hash` is a hash of the signer's public key using the same format as Section 2.3.2. It is included in `tree_leaf` so that each leaf can be attributed to a signer. A hash, rather than the full public key, is used to motivate monitors and end-users to @@ -197,7 +197,7 @@ Output on success: - `root_hash`: `tree_head.root_hash`, hex-encoded. - `signature`: log signature for the above tree head, hex-encoded. - `cosignature`: witness signature for the above tree head, hex-encoded. -- `key_hash`: hashed witness verification key that can be used to verify the +- `key_hash`: hashed witness public key that can be used to verify the above cosignature. The key is encoded as defined in [RFC 8032, section 5.1.2](https://tools.ietf.org/html/rfc8032#section-5.1.2) before hashing. The resulting hash value is hex-encoded. @@ -293,7 +293,7 @@ Input: number. - `message`: the message used to compute `tree_leaf.statement.checksum`, hex-encoded. - `signature`: `tree_leaf.signature`, hex-encoded. -- `verification_key`: public verification key that can be used to verify the +- `public_key`: public key that can be used to verify the above signature. The key is encoded as defined in [RFC 8032, section 5.1.2](https://tools.ietf.org/html/rfc8032#section-5.1.2), then hex-encoded. - `domain_hint`: domain name indicating where `tree_leaf.key_hash` can be found @@ -304,7 +304,7 @@ Output on success: - None A submission will not be accepted if `signature` or `shard_hint` is invalid. -The retrieved key hash must also match the specified verification key. +The retrieved key hash must also match the specified public key. A submission may not be accepted if the second-level domain name has exceeded its rate limit. A rate limit should only be charged for the specified domain hint @@ -319,7 +319,7 @@ Example: $ echo "shard_hint=1633039200 message=315f5bdb76d078c43b8ac0064e4a0164612b1fce77c869345bfc94c75894edd3 signature=0b849ed46b71b550d47ae320a8a37401129d71888edcc387b6a604b2fe1579e25479adb0edd1769f9b525d44b843ac0b3527ea12b8d9574676464b2ec6077401 -verification_key=46a6aaceb6feee9cb50c258123e573cc5a8aa09e5e51d1a56cace9bfd7c5569c +public_key=46a6aaceb6feee9cb50c258123e573cc5a8aa09e5e51d1a56cace9bfd7c5569c domain_hint=_sigsum_v0.example.com" | curl --data-binary @- /add-leaf ``` @@ -335,7 +335,7 @@ POST /add-cosignature Input: - `cosignature`: witness signature over `tree_head`, hex-encoded. -- `key_hash`: hashed witness verification key that can be used to verify the +- `key_hash`: hashed witness public key that can be used to verify the above cosignature. The key is encoded as defined in [RFC 8032, section 5.1.2](https://tools.ietf.org/html/rfc8032#section-5.1.2) prior to hashing. The resulting hash value is hex-encoded. @@ -343,7 +343,7 @@ Output on success: - None `key_hash` can be used to identify which witness cosigned a tree head. A -key-hash, rather than the full verification key, is used to motivate monitors +key-hash, rather than the full public key, is used to motivate monitors and end-users to locate the appropriate key and make an explicit trust decision. Note that logs must be configured with relevant public keys for witnesses. @@ -362,7 +362,7 @@ on how one could produce it "byte-for-byte" using Python and ssh-keygen -Y. Ed25519 as signature scheme. SHA256 as hash function. ### 4.1 - Log -- **Public key**: public verification key that is used to verify tree head +- **Public key**: public key that is used to verify tree head signatures. - **Base URL**: Where the log can be reached over HTTP(S). It is the prefix to be used to construct a version 0 specific endpoint. @@ -372,5 +372,5 @@ Ed25519 as signature scheme. SHA256 as hash function. use the number of seconds since the UNIX epoch as a dynamic shard end. ### 4.2 - Witness -- **Public key**: public verification key that is used to verify tree head +- **Public key**: public key that is used to verify tree head cosignatures. diff --git a/doc/design.md b/doc/design.md index e0b3b68..b10c758 100644 --- a/doc/design.md +++ b/doc/design.md @@ -168,7 +168,7 @@ we give a brief primer below. A signer wants to make their key-usage transparent. Therefore, they sign a statement that sigsum logs accept. That statement encodes a checksum for some data. Minimal metadata must also be logged, such as the checksum's signature -and a hash of the public verification key. A hash of the public verification +and a hash of the public key. A hash of the public key is configured in DNS as a TXT record to help log operators combat spam. The signing party waits for their submission to be included in the log. When an @@ -195,7 +195,7 @@ are accepted. Once elapsed, the log can be shut down or be made read-only. - **checksum**: a cryptographic hash that commits to some data. - **signature**: a digital signature that is computed by a signer for the selected shard hint and checksum. -- **key_hash**: a cryptographic hash of the signer's verification key that can +- **key_hash**: a cryptographic hash of the signer's public key that can be used to verify the signature. Any additional metadata that is use-case specific can be stored as part of the @@ -203,7 +203,7 @@ data that a checksum represents. Where data is located is use-case specific. Note that a key hash is logged rather than the public key itself. This reduces the likelihood that an untrusted key is discovered and used by mistake. In -other words, end-users and monitors must locate signer verification keys +other words, end-users and monitors must locate signer public keys independently of logs, and trust them explicitly. ### 3.2 - Usage pattern @@ -220,9 +220,9 @@ incorporates the shard hint. The exact signing format is compatible with `ssh-keygen -Y sign` when using Ed25519 and SHA256. The signer also has to do a one-time DNS setup. As outlined below, logs will -check that _some domain_ is aware of the signer's verification key. This is +check that _some domain_ is aware of the signer's public key. This is part of a defense mechanism that helps log operators to deal with log spam. -Once present in DNS, a verification key can be used in subsequent log requests. +Once present in DNS, a public key can be used in subsequent log requests. #### 3.2.2 - Submit request Sigsum logs implement an HTTP(S) API. Input and output is human-readable and @@ -230,11 +230,11 @@ use a simple ASCII format. A more complex parser like JSON is not needed since the data structures being exchanged are primitive enough. The signer submits their shard hint, message, signature, public -verification key and domain hint as ASCII key-value pairs. The log uses the +key and domain hint as ASCII key-value pairs. The log uses the submitted message to compute the signer's checksum. The log also verifies -that the public verification key is present in DNS, and uses it to check that +that the public key is present in DNS, and uses it to check that the signature is valid for the resulting checksum and shard hint. The public -verification key is then hashed to construct the Merkle tree leaf as described +key is then hashed to construct the Merkle tree leaf as described in Section 3.1. A sigsum log will @@ -278,7 +278,7 @@ reproduce a logged checksum. **Metadata:** the shard hint to use as signing context, the resulting signature over checksum, -and the verification key hash used in the log request. Note that the +and the public key hash used in the log request. Note that the combination of data and metadata can be used to reconstruct the logged leaf. **Proof:** -- cgit v1.2.3