Debian Codegraph @

src/spki/README

raw
1 LIBSPKI
2
3 Libspki is a library and a set of tools for handling Simple Public Key
4 Infrastructure certificates and other objects.
5
6
7 OVERVIEW
8
9 This section gives an overview of the SPKI model of authorization.
10
11
12 Owners and ACLSs
13
14 The owner of a resource writes Access Control Lists (ACLs) specifying
15 who can access the resource. User's are identified by their public
16 key. A user will contact the server controlling the resource, and
17 provide a certificate chain and some proof of knowledge of a his or
18 her private key. The server checks the signatures, and then matches
19 the certificate chain, the requested access, and the owners ACL, to
20 make an access decision.
21
22
23 The root of authorization
24
25 The owner can write one ACL for each user that should have access to
26 the resource, or a single ACL giving full access to one of her own
27 keys. She can then use that key to sign certificates that delegate
28 some or all of her rights to other users.
29
30 There's no need for a trusted third party, because all valid
31 certificate chains will be rooted at a key listed in the owner's ACL.
32
33
34 Delegation
35
36 Delegation is a central issue in SPKI. Any user that has access rights
37 to some resource, via the owner's ACL and a certificate chain, and
38 which has the delegation flag set in her certificate, can sign new
39 certificates delegating some or all of her rights further. When
40 delegating, giving somebody a new certifon a new certificate, one will
41 usually provide a complete certificate chain, i.e. the chain that
42 gives oneself the right to use and delegate the right, extended with
43 the newly signed certificate.
44
45
46 LIMITATIONS OF LIBSPKI
47
48 Libspki doesn't yet implement all aspects of SPKI. In particular, it
49 doesn't yet implement SPKI names, online validity checks, and the
50 "range" type in tag expressions.
51
52
53 STORAGE
54
55 The information that SPKI users and applications need is organized as
56 follows. ACL:s are stored anywhere the software controling a resource
57 finds it convenient. The rest of the information is stored in a
58 directory, for users it would be located in files ad directories under
59 ~/.spki.
60
61 ~/.spki/keys/foo
62
63 A private key. Should contain the public information in
64 cleartext, and the private information in cleartext or encrypted
65 by a password.
66
67 ~/.spki/keys/foo.pub
68
69 The corresponding public key. Redundant, but may be useful.
70
71 ~/.spki/sha1-keys/{xxxx...} --> ../keys/foo
72
73 A symlink from the public-key hash to the corresponding key file.
74
75 ~/.spki/certificates
76
77 A big file containing all the user's certificate chains. To find
78 a relevant certificate, one has to read the file and filter out
79 interesting certificates, usually by looking at the SPKI tags.
80
81 ~/.spki/log/delegations
82
83 A log file containing information about all the user's own
84 delegations. Not strictly necessary, but it seems desirable to
85 keep a log of created certificates. The log file can be rotated
86 if it gets large.
87
88
89 TOOLS
90
91 Plain signatures can be created and verified with
92
93 spki-make-signature PRIVATE-KEY-FILE <message
94
95 and verified with
96
97 spki-check-signature {SIGNATURE} < data
98
99 where `{SIGNATURE}' is the transport encoded spki signature.
100 Certificates are created with
101
102 spki-delegate --issuer={ISSUER} --subject={SUBJECT} \
103 --tag={RESOURCE} --chain={CERTIFICATE} \
104 [--key-file=PRIVATE] [--propagate] \
105 [--no-signature]
106
107 where --subject specifies an spki principal (currently a public key or
108 hash), --tag specifies the resource to which access is delegated. If
109 --chain is used, a certificate chain is created by adding the
110 certificate at the end of the given certificate chain, otherwise, if
111 --issuer is given, a certificate chain with a single certificate is
112 created. --key-file specifies the private key to use (by default, it
113 is looked up in ~/.spki/sha1-keys). --propgate creates a delegation
114 that can be delegated further.
115
116 FIXME: Change terminology, we could talk of the source of the
117 delegation (--issuer or --chain).
118
119
120