1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
.. _keymanager:
=================
Keymanager
=================
Keymanager is the Bitmask component that does key management, including generation,
discovery and validation. It is, esentially, a `nicknym`_ client that uses `Soledad`_
as its storage layer.
Keymanager handles the creation of a OpenPGP transparently in user's behalf. When
bootstrapping a new account, keymanager will generate a new key pair. The key
pair is stored encrypted inside soledad (and therefore able to be synced by
other replicas). After generating it, the public key is sent to the provider,
which will replace any prior keys for the same address in its database.
To discover keys for other users, the `nicknym`_ client in keymanager will query
the nicknym server associated with user's provider, and will process the keys
that the server returns. This query has the following form::
https://nicknym.test.bitmask.net:6425?address=user@example.com
And it's up to the the provider's service to determine the sources for the keys.
Keymanager currently implements all the levels defined in the `Transitional Key
Validation`_ spec, although the mechanisms for validation currently in place
only reach level 2 of what's contemplated in the spec.
.. _nicknym: https://leap.se/en/docs/design/nicknym
.. _Soledad: https://leap.se/en/docs/design/soledad
.. _'transitional key validation': https://leap.se/en/docs/design/transitional-key-validation
Sources of public keys
----------------------
Currently bitmask can discover new public keys from different sources:
* Keys attached to incoming emails. Simple *.asc* attachments with the keys will be
taken into account, like the ones produced by enigmail.
* OpenPGP header in incoming emails. The only field taken into account is the *url*
and it will only be used if it's an *https* address from the same domain as the
senders email address.
* When sending emails if the recipient key is not known bitmask will ask for the key
to it's nicknym provider. The nicknym provider will try to discover the key from
other nicknym providers. If provider discovery doesn't bring any results, will
fetch it from the sks key servers (this sks discovery is probably going to be
removed some time in the future as it provides too many unused keys).
Other methods are planned to be added in the future, like discovery from signatures in
emails or other kind of key servers.
Implementation: using Soledad documents
---------------------------------------
KeyManager uses two types of Soledad documents for the keyring:
* key document, that stores each gpg key.
* active document, that relates an address to its corresponding key.
Each key can have 0 or more active documents with a different email address
each:
::
.-------------. .-------------.
| foo@foo.com | | bar@bar.com |
'-------------' '-------------'
| |
| .-----------. |
| | | |
| | key | |
'----->| |<----'
| |
'-----------'
Fields in a key document:
* uids
* fingerprint
* key_data
* private. bool marking if the key is private or public
* length
* expiry_date
* refreshed_at
* version = 1
* type = "OpenPGPKey"
* tags = ["keymanager-key"]
Fields in an active document:
* address
* fingerprint
* private
* validation
* last_audited_at
* encr_used
* sign_used
* version = 1
* type = "OpenPGPKey-active"
* tags = ["keymanager-active"]
The meaning of validation, encr_used and sign_used is related to the `Transitional Key Validation`_
.. _Transitional Key Validation: https://leap.se/en/docs/design/transitional-key-validation
|
