| 1 |
Verify Signature Tutorial |
| 2 |
========================= |
| 3 |
|
| 4 |
Objective |
| 5 |
--------- |
| 6 |
|
| 7 |
In this tutorial, you will verify a signature against a list of allowed signing keys. |
| 8 |
You will see the distinction between merely checking a signature, as shown in the |
| 9 |
[Check Signature Tutorial](check_signature.md), and verifying a signature, as demonstrated |
| 10 |
in this tutorial. |
| 11 |
|
| 12 |
|
| 13 |
Prerequisites |
| 14 |
------------- |
| 15 |
|
| 16 |
You need to install the `sshsig` Python package. |
| 17 |
A popular way to do this is by running: |
| 18 |
|
| 19 |
``` |
| 20 |
pip install sshsig |
| 21 |
``` |
| 22 |
|
| 23 |
This tutorial involves executing lines of Python code within a Python interpreter. |
| 24 |
A popular way to run the Python interpreter is to run: |
| 25 |
``` |
| 26 |
python3 |
| 27 |
``` |
| 28 |
in the command line. |
| 29 |
|
| 30 |
|
| 31 |
Steps |
| 32 |
----- |
| 33 |
|
| 34 |
### 1. Get the message and plain-text encoded signature |
| 35 |
|
| 36 |
To verify (or check) a signature, we need the message that was signed and its corresponding signature. |
| 37 |
|
| 38 |
```python |
| 39 |
message = """\ |
| 40 |
tree 8d602ce92adf2a598552736e97f07e5b8ab2b0a8 |
| 41 |
parent 06b3e55161aae343d23453f7443904512599a513 |
| 42 |
author Castedo Ellerman <[email protected]> 1736017937 -0500 |
| 43 |
committer Castedo Ellerman <[email protected]> 1736017937 -0500 |
| 44 |
|
| 45 |
add py.typed marker |
| 46 |
""" |
| 47 |
``` |
| 48 |
|
| 49 |
This message is from a Git commit, as demonstrated in the |
| 50 |
[Check a Git Commit how-to guide](../howto/check_commit.md) |
| 51 |
using the `raw_without_sig()` function from |
| 52 |
[`dulwich`](https://pypi.org/project/dulwich/). |
| 53 |
This Git commit includes an identity in the form of a personal name |
| 54 |
and email address. |
| 55 |
|
| 56 |
|
| 57 |
```python |
| 58 |
signature = """\ |
| 59 |
-----BEGIN SSH SIGNATURE----- |
| 60 |
U1NIU0lHAAAAAQAAADMAAAALc3NoLWVkMjU1MTkAAAAghB1C63jrmh3eWRXJVbrTfw9wP/ |
| 61 |
BIZf/aKPdFxBlMCq0AAAADZ2l0AAAAAAAAAAZzaGE1MTIAAABTAAAAC3NzaC1lZDI1NTE5 |
| 62 |
AAAAQMroG89bt34Civt2ftnKSDj/qpskASeCBHUfc8KQCUl1LAq4gAy4xQ1orAtiEaj5EM |
| 63 |
yMvtlcxbEImHo4KtbOewA= |
| 64 |
-----END SSH SIGNATURE----- |
| 65 |
""" |
| 66 |
``` |
| 67 |
|
| 68 |
|
| 69 |
### 2. Get and check the signing public key |
| 70 |
|
| 71 |
We get the public key from the signature and check that it was used to sign the |
| 72 |
message. |
| 73 |
|
| 74 |
```python |
| 75 |
import sshsig |
| 76 |
pub_key = sshsig.check_signature(message, signature) |
| 77 |
print(pub_key) |
| 78 |
``` |
| 79 |
|
| 80 |
Although `check_signature` confirms that the public key was used to sign the message, |
| 81 |
it does not validate whether the person identified by name and email |
| 82 |
address in the commit is the same person who holds the signing key and used it to |
| 83 |
sign the message. |
| 84 |
|
| 85 |
|
| 86 |
### 3. An allowed signers file |
| 87 |
|
| 88 |
One of many possible forms of additional verification is to |
| 89 |
only accept signatures that are performed with a signing key listed in |
| 90 |
an _allow list_ of acceptable public keys. |
| 91 |
|
| 92 |
The utility [ssh-keygen](https://en.wikipedia.org/wiki/Ssh-keygen) uses |
| 93 |
an "allowed signers" file as an allow list for signature verification. |
| 94 |
Git uses this utility to verify commits with SSH signatures. |
| 95 |
|
| 96 |
The `sshsig.allowed_signers` module supports a limited sub-format of the `ssh-keygen` allowed |
| 97 |
signers file format. This sub-format only supports lines starting with |
| 98 |
`* namespaces="git"` preceding public keys in OpenSSH format. |
| 99 |
|
| 100 |
Below, we create such a file: |
| 101 |
|
| 102 |
```python |
| 103 |
import io |
| 104 |
file = io.StringIO(f"""\ |
| 105 |
* namespaces="git" {pub_key} |
| 106 |
* namespaces="git" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMlKQFTcI28lrqcq8goeL2p1cxdHhm4/reBgjKDp1Ise |
| 107 |
""") |
| 108 |
``` |
| 109 |
|
| 110 |
|
| 111 |
### 4. Load an allow list |
| 112 |
|
| 113 |
Next, we get an allow list of public keys by loading the example file. |
| 114 |
|
| 115 |
```python |
| 116 |
from sshsig.allowed_signers import load_allowed_signers_file, for_git_allowed_keys |
| 117 |
allow_list = for_git_allowed_keys(load_allowed_signers_file(file)) |
| 118 |
print(*allow_list, sep="\n") |
| 119 |
``` |
| 120 |
|
| 121 |
Note that in this example, we've included the public key found in the signature. |
| 122 |
|
| 123 |
|
| 124 |
### 5. Verify the key in the allow list |
| 125 |
|
| 126 |
Checking whether the returned public key is in the returned allow list is |
| 127 |
a trivial one-liner. |
| 128 |
|
| 129 |
```python |
| 130 |
pub_key in allow_list |
| 131 |
``` |
| 132 |
|
| 133 |
Alternatively, one can use the trivial helper function `verify` to call |
| 134 |
`check_signature` and verify whether the returned public key is in the allow list. |
| 135 |
|
| 136 |
```python |
| 137 |
pub_key = sshsig.verify(message, signature, allow_list) |
| 138 |
``` |