Added sign message, verify message, and purge key

Signed-off-by: Samuel Bailey <[email protected]>
parallaxsecond · Aug 28, 2020 · 1e1cd61 · 1e1cd61
1 parent 2709858
commit 1e1cd61
Show file tree

Hide file tree

Showing 14 changed files with 128 additions and 49 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -23,8 +23,8 @@ jobs:
           mkdir /tmp/go
           export GOPATH=/tmp/go
           go get github.com/bobertlo/vmd/cmd/vmdfmt
-    - name: Install markdown-link-check tool
-      run: npm install markdown-link-check
+    - name: Link Checker
+      uses: peter-evans/link-checker@v1
     - name: Check formatting
       run: |
           export PATH="$PATH:/tmp/go/bin:$(pwd)/node_modules/.bin"

diff --git a/ci/check_format.sh b/ci/check_format.sh
@@ -17,7 +17,6 @@ do
 	echo "Checking file \"$f\""
 	vmdfmt -cols 100 $f > $OUT_DIR/$(basename $f)
 	git diff --exit-code $f $OUT_DIR/$(basename $f)
-	markdown-link-check -q $f
 done
 
 rm -rf $OUT_DIR
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -22,9 +22,11 @@
       - [PsaGenerateKey](parsec_client/operations/psa_generate_key.md)
       - [PsaImportKey](parsec_client/operations/psa_import_key.md)
       - [PsaRawKeyAgreement](parsec_client/operations/psa_raw_key_agreement.md)
-      - [PsaSignHash](parsec_client/operations/psa_sign_hash.md)
       - [PSA Key Attributes](parsec_client/operations/psa_key_attributes.md)
       - [PSA Algorithm](parsec_client/operations/psa_algorithm.md)
+      - [PsaSignMessage](parsec_client/operations/psa_sign_message.md)
+      - [PsaVerifyMessage](parsec_client/operations/psa_verify_message.md)
+      - [PsaSignHash](parsec_client/operations/psa_sign_hash.md)
       - [PsaVerifyHash](parsec_client/operations/psa_verify_hash.md)
       - [PsaHashCompute](parsec_client/operations/psa_hash_compute.md)
       - [PsaHashCompare](parsec_client/operations/psa_hash_compare.md)

diff --git a/src/clients_api_coverage.md b/src/clients_api_coverage.md
@@ -32,6 +32,8 @@ will be added here for any other such coverage report.
 | Export public key  | ✅         |
 | Export key         | ✅         |
 | Destroy key        | ✅         |
+| Sign message       | ❌         |
+| Verify message     | ❌         |
 | Sign hash          | ✅         |
 | Verify hash        | ✅         |
 | Hash compute       | ✅         |
@@ -40,6 +42,8 @@ will be added here for any other such coverage report.
 | Asymmetric decrypt | ✅         |
 | Aead encrypt       | ✅         |
 | Aead decrypt       | ✅         |
+| Cipher encrypt     | ❌         |
+| Cipher decrypt     | ❌         |
 | RawKeyAgreement    | ✅         |
 
 ## Algorithm support
@@ -95,21 +99,21 @@ will be added here for any other such coverage report.
 | Algorithm    | Rust client |
 |--------------|-------------|
 | StreamCipher | ❌         |
-| Crt          | ❌         |
+| Ctr          | ❌         |
 | Cfb          | ❌         |
 | Ofb          | ❌         |
 | Xts          | ❌         |
-| EbcNoPadding | ❌         |
+| EcbNoPadding | ❌         |
 | CbcNoPadding | ❌         |
 | CbcPkcs7     | ❌         |
 
 ### MAC algorithms
 
-| Algorithm    | Rust client |
-|--------------|-------------|
-| Hmac | ❌         |
-| CbcMac          | ❌         |
-| Cmac          | ❌         |
+| Algorithm | Rust client |
+|-----------|-------------|
+| Hmac      | ❌         |
+| CbcMac    | ❌         |
+| Cmac      | ❌         |
 
 ### Raw key agreement algorithms
 

diff --git a/src/parsec_client/operations/README.md b/src/parsec_client/operations/README.md
@@ -53,6 +53,7 @@ Most of the documentation in this book directly come from the specification.
 - [PsaGenerateKey](psa_generate_key.md)
 - PsaCopyKey
 - [PsaDestroyKey](psa_destroy_key.md)
+- PsaPurgeKey
 - [PsaExportKey](psa_export_key.md)
 - [PsaExportPublicKey](psa_export_public_key.md)
 
@@ -125,8 +126,8 @@ Most of the documentation in this book directly come from the specification.
 
 ### Asymmetric Signature
 
-- PsaSignMessage
-- PsaVerifyMessage
+- [PsaSignMessage](psa_sign_message.md)
+- [PsaVerifyMessage](psa_verify_message.md)
 - [PsaSignHash](psa_sign_hash.md)
 - [PsaVerifyHash](psa_verify_hash.md)
 

diff --git a/src/parsec_client/operations/psa_cipher_decrypt.md b/src/parsec_client/operations/psa_cipher_decrypt.md
@@ -11,6 +11,7 @@ Decrypt a short message with a symmetric cipher. Opcode: 21 (`0x0015`)
 | `ciphertext` | Vector of bytes                               | IV followed by the ciphertext                              |
 
 - `key_name` must allow the [usage flag](psa_key_attributes.md#usageflags-type) `decrypt`.
+- `ciphertext` must be the IV followed by the ciphertext.
 
 ## Results
 
@@ -25,8 +26,7 @@ Decrypt a short message with a symmetric cipher. Opcode: 21 (`0x0015`)
 
 ## Description
 
-This function will decrypt a short message using the provided initialisation vector (IV). The input
-must be the IV followed by the ciphertext.
+This function will decrypt a short message using the provided initialisation vector (IV).
 
 ## Contract
 

diff --git a/src/parsec_client/operations/psa_cipher_encrypt.md b/src/parsec_client/operations/psa_cipher_encrypt.md
@@ -25,8 +25,7 @@ Encrypt a short message with a symmetric cipher. Opcode: 20 (`0x0014`)
 
 ## Description
 
-This function will encrypt a short message with a random initialisation vector (IV). The output is
-the IV followed by the ciphertext.
+This function will encrypt a short message with a random initialisation vector (IV).
 
 ## Contract
 

diff --git a/src/parsec_client/operations/psa_mac_compute.md b/src/parsec_client/operations/psa_mac_compute.md
@@ -4,11 +4,11 @@ Calculate the MAC of a message. Opcode: 22 (`0x0016`)
 
 ## Parameters
 
-| Name       | Type                                          | Description                              |
-|------------|-----------------------------------------------|------------------------------------------|
-| `key_name` | String                                        | Name of the key to use for the operation |
-| `alg`      | [`Cipher`](psa_algorithm.md#cipher-algorithm) | Mac algorithm to compute                 |
-| `input`    | Vector of bytes                               | Buffer containing the input message      |
+| Name       | Type                                    | Description                              |
+|------------|-----------------------------------------|------------------------------------------|
+| `key_name` | String                                  | Name of the key to use for the operation |
+| `alg`      | [`Mac`](psa_algorithm.md#mac-algorithm) | Mac algorithm to compute                 |
+| `input`    | Vector of bytes                         | Buffer containing the input message      |
 
 - `key_name` must allow the [usage flag](psa_key_attributes.md#usageflags-type) `sign_message`.
 

diff --git a/src/parsec_client/operations/psa_mac_verify.md b/src/parsec_client/operations/psa_mac_verify.md
@@ -1,15 +1,15 @@
-# PsaMacCompute
+# PsaMacVerify
 
-Calculate the MAC of a message. Opcode: 22 (`0x0016`)
+Calculate the MAC of a message and compare it to an expected value. Opcode: 23 (`0x0017`)
 
 ## Parameters
 
-| Name       | Type                                          | Description                              |
-|------------|-----------------------------------------------|------------------------------------------|
-| `key_name` | String                                        | Name of the key to use for the operation |
-| `alg`      | [`Cipher`](psa_algorithm.md#cipher-algorithm) | Mac algorithm to compute                 |
-| `input`    | Vector of bytes                               | Buffer containing the input message      |
-| `mac`      | Vector of bytes                               | Buffer containing the expected MAC value |
+| Name       | Type                                    | Description                              |
+|------------|-----------------------------------------|------------------------------------------|
+| `key_name` | String                                  | Name of the key to use for the operation |
+| `alg`      | [`Mac`](psa_algorithm.md#mac-algorithm) | Mac algorithm to compute                 |
+| `input`    | Vector of bytes                         | Buffer containing the input message      |
+| `mac`      | Vector of bytes                         | Buffer containing the expected MAC value |
 
 - `key_name` must allow the [usage flag](psa_key_attributes.md#usageflags-type) `verify_message`.
 

diff --git a/src/parsec_client/operations/psa_sign_hash.md b/src/parsec_client/operations/psa_sign_hash.md
@@ -37,7 +37,7 @@ such signature algorithm: Raw PKCS#1 v1.5 signature.
 **Note:** To perform a hash-and-sign algorithm, the hash must be calculated before passing it to
 this function. This could be done with the operation PsaHashCompute or with a multi-part hash
 operation. Those operations are not yet implemented. Alternatively, to hash and sign a message in a
-single call, you could use PsaSignMessage (not yet implemented).
+single call, you could use PsaSignMessage.
 
 ## Contract
 

diff --git a/src/parsec_client/operations/psa_sign_message.md b/src/parsec_client/operations/psa_sign_message.md
@@ -0,0 +1,36 @@
+# PsaSignMessage
+
+Sign a message with a private key. Opcode: 24 (`0x0018`)
+
+## Parameters
+
+| Name       | Type                                                                    | Description                                                                                                              |
+|------------|-------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
+| `key_name` | String                                                                  | Name of the key to use for the operation                                                                                 |
+| `alg`      | [`AsymmetricSignature`](psa_algorithm.md#asymmetricsignature-algorithm) | An asymmetric signature algorithm that separates the message and sign operations that is compatible with the type of key |
+| `message`  | Vector of bytes                                                         | The message to sign                                                                                                      |
+
+- `key_name` must be the name of an asymmetric key pair. The key must allow the [usage
+   flag](psa_key_attributes.md#usageflags-type) `sign_hash`.
+
+## Results
+
+| Name        | Type            | Description                     |
+|-------------|-----------------|---------------------------------|
+| `signature` | Vector of bytes | Buffer containing the signature |
+
+## Specific response status codes
+
+- `PsaErrorNotPermitted`: The key does not have the `sign_hash` flag, or it does not permit the
+   requested algorithm.
+
+## Description
+
+This function will sign a message with a private key. For hash-and-sign algorithms, this includes
+the hashing step.
+
+## Contract
+
+[Protobuf](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_sign_message.proto)
+
+*Copyright 2020 Contributors to the Parsec project.*
diff --git a/src/parsec_client/operations/psa_verify_hash.md b/src/parsec_client/operations/psa_verify_hash.md
@@ -38,7 +38,7 @@ such signature algorithm: Raw PKCS#1 v1.5 signature.
 **Note:** To perform a hash-and-sign algorithm, the hash must be calculated before passing it to
 this function. This could be done with the operation PsaHashCompute or with a multi-part hash
 operation. Those operations are not yet implemented. Alternatively, to hash and verify a message
-signature in a single call, you could use PsaVerifyMessage (not yet implemented).
+signature in a single call, you could use PsaVerifyMessage.
 
 ## Contract
 

diff --git a/src/parsec_client/operations/psa_verify_message.md b/src/parsec_client/operations/psa_verify_message.md
@@ -0,0 +1,35 @@
+# PsaVerifyMessage
+
+Verify the signature of a message using a public key. Opcode: 25 (`0x0019`)
+
+## Parameters
+
+| Name        | Type                                                                    | Description                                                                                                              |
+|-------------|-------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
+| `key_name`  | String                                                                  | Name of the key to use for the operation                                                                                 |
+| `alg`       | [`AsymmetricSignature`](psa_algorithm.md#asymmetricsignature-algorithm) | An asymmetric signature algorithm that separates the message and sign operations that is compatible with the type of key |
+| `message`   | Vector of bytes                                                         | The message whose signature is to be verified                                                                            |
+| `signature` | Vector of bytes                                                         | Buffer containing the signature to verify                                                                                |
+
+- `key_name` must be the name of a public key or an asymmetric key pair. The key must allow the
+   [usage flag](psa_key_attributes.md#usageflags-type) `verify_hash`.
+
+No values are returned by this operation. If `Success` is returned the signature is valid.
+
+## Specific response status codes
+
+- `PsaErrorNotPermitted`: The key does not have the `verify_hash` flag, or it does not permit the
+   requested algorithm.
+- `PsaErrorInvalidSignature`: The calculation was performed successfully, but the passed signature
+   is not a valid signature.
+
+## Description
+
+This function will verify the signature of a message with a public key, using a hash-and-sign
+verification algorithm.
+
+## Contract
+
+[Protobuf](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_verify_message.proto)
+
+*Copyright 2020 Contributors to the Parsec project.*
diff --git a/src/service_api_coverage.md b/src/service_api_coverage.md
@@ -33,16 +33,16 @@ in the future and will be organized by operation type.
 | `psa_destroy_key`        | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_destroy_key.proto)        |
 | `psa_hash_compute`       | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_hash_compute.proto)       |
 | `psa_hash_compare`       | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_hash_compare.proto)       |
-| `psa_mac_compute`        | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_mac_compute.proto)                                                                                                        |
-| `psa_mac_verify`         | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_mac_verify.proto)                                                                                                          |
-| `psa_cipher_encrypt`     | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_cipher_encrypt.proto)                                                                                                          |
-| `psa_cipher_decrypt`     | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_cipher_decrypt.proto)                                                                                                          |
+| `psa_mac_compute`        | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_mac_compute.proto)        |
+| `psa_mac_verify`         | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_mac_verify.proto)         |
+| `psa_cipher_encrypt`     | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_cipher_encrypt.proto)     |
+| `psa_cipher_decrypt`     | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_cipher_decrypt.proto)     |
 | `psa_aead_encrypt`       | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_aead_encrypt.proto)       |
 | `psa_aead_decrypt`       | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_aead_decrypt.proto)       |
 | `psa_asymmetric_encrypt` | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_asymmetric_encrypt.proto) |
 | `psa_asymmetric_decrypt` | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_asymmetric_decrypt.proto) |
-| `psa_sign_message`       | ❌                                                                                                          |
-| `psa_verify_message`     | ❌                                                                                                          |
+| `psa_sign_message`       | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_sign_message.proto)       |
+| `psa_verify_message`     | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_verify_message.proto)     |
 | `psa_sign_hash`          | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_sign_hash.proto)          |
 | `psa_verify_hash`        | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_verify_hash.proto)        |
 | `psa_raw_key_agreement`  | [✅](https://github.com/parallaxsecond/parsec-operations/blob/master/protobuf/psa_raw_key_agreement.proto)  |
@@ -66,6 +66,9 @@ option marked as supported is necessarily supported for all operations on which
 | Export public key  | ✅                  | ✅              | ✅              |
 | Export key         | ✅                  | ❌              | ❌              |
 | Destroy key        | ✅                  | ✅              | ✅              |
+| Purge key          | ❌                  | ❌              | ❌              |
+| Sign message       | ❌                  | ❌              | ❌              |
+| Verify message     | ❌                  | ❌              | ❌              |
 | Sign hash          | ✅                  | ✅              | ✅              |
 | Verify hash        | ✅                  | ✅              | ✅              |
 | Hash compute       | ✅                  | ❌              | ❌              |
@@ -74,10 +77,10 @@ option marked as supported is necessarily supported for all operations on which
 | Asymmetric decrypt | ✅                  | ❌              | ❌              |
 | AEAD encrypt       | ✅                  | ❌              | ❌              |
 | AEAD decrypt       | ✅                  | ❌              | ❌              |
-| Cipher encrypt       | ❌                  | ❌              | ❌              |
-| Cipher decrypt       | ❌                  | ❌              | ❌              |
-| MAC compute       | ❌                  | ❌              | ❌              |
-| MAC verify       | ❌                  | ❌              | ❌              |
+| Cipher encrypt     | ❌                  | ❌              | ❌              |
+| Cipher decrypt     | ❌                  | ❌              | ❌              |
+| MAC compute        | ❌                  | ❌              | ❌              |
+| MAC verify         | ❌                  | ❌              | ❌              |
 | Raw key agreement  | ✅                  | ❌              | ❌              |
 
 ### Algorithm support
@@ -133,21 +136,21 @@ option marked as supported is necessarily supported for all operations on which
 | Algorithm    | Mbed Crypto provider | PKCS 11 provider | TPM 2.0 provider |
 |--------------|----------------------|------------------|------------------|
 | StreamCipher | ❌                  | ❌              | ❌              |
-| Crt          | ❌                  | ❌              | ❌              |
+| Ctr          | ❌                  | ❌              | ❌              |
 | Cfb          | ❌                  | ❌              | ❌              |
 | Ofb          | ❌                  | ❌              | ❌              |
 | Xts          | ❌                  | ❌              | ❌              |
-| EbcNoPadding | ❌                  | ❌              | ❌              |
+| EcbNoPadding | ❌                  | ❌              | ❌              |
 | CbcNoPadding | ❌                  | ❌              | ❌              |
 | CbcPkcs7     | ❌                  | ❌              | ❌              |
 
 ### MAC algorithms
 
-| Algorithm    | Mbed Crypto provider | PKCS 11 provider | TPM 2.0 provider |
-|--------------|----------------------|------------------|------------------|
-| Hmac | ❌                  | ❌              | ❌              |
-| CbcMac          | ❌                  | ❌              | ❌              |
-| Cmac          | ❌                  | ❌              | ❌              |
+| Algorithm | Mbed Crypto provider | PKCS 11 provider | TPM 2.0 provider |
+|-----------|----------------------|------------------|------------------|
+| Hmac      | ❌                  | ❌              | ❌              |
+| CbcMac    | ❌                  | ❌              | ❌              |
+| Cmac      | ❌                  | ❌              | ❌              |
 
 #### Raw key agreement algorithms