Debian Codegraph @

docs/tutorial/verify_signature.md

raw
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 ```