forked from google/hiba
-
Notifications
You must be signed in to change notification settings - Fork 0
/
PROTOCOL.extensions
138 lines (105 loc) · 5.37 KB
/
PROTOCOL.extensions
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
132
133
134
135
136
137
138
# HIBA Extensions
## Type of extensions supported by HIBA
HIBA supports two kinds of extensions:
| Name | Target | Description |
| ---------- | ----------------- | ------------------------------------------- |
| identity | Host certificate | Defines the identity of host, used to match |
: : : grants at connection time. :
| grant | User certificate | Defines which identity this certificate |
: : : gives access to. :
## Overall format
Each extension is a list of key/value pairs and is following the openssh
serialized format. The extension content also contains a header that describes
the type, the version and a minimum supported version that allows backward
incompatible changes. The last field is a count of the number of key/value
pairs.
```
uint32 magic
uint32 type
uint32 vers
uint32 min_vers
uint32 npairs
```
Where magic is defined as:
```
#define HIBA_MAGIC 0x48494241
```
Where type is defined by the following:
```
#define HIBA_UNKNOWN_EXT 0
#define HIBA_IDENTITY_EXT 'i'
#define HIBA_GRANT_EXT 'g'
```
The current extension format version is 2, which supports negative constraint
matching. The extension format minimum version is still 1 when only positive
constraint matching is used (to maximize backward compatibility), but must
be increased to 2 whenever a negative matching constraint is added to a grant
(to avoid compromizing security with unexpected behavior when parsing newer
extensions on older HIBA binaries).
The rest of the data is a list of strings key1, value1, key2, value2, ...
There must be exactly one value per key.
The HIBA tools support the identity and grant extensions both in their raw
serialized form as well as in base64 encoding.
## Support for mutliple grants
For attaching multiple grants to a single certificate one MUST use one the
two following methods:
* comma separated list of base64 encoded grants (raw serialized extension only
supports one grant per certificates). This provides the simplest support for
shell scripts based management, or manual debugging.
* A magic multi grant header followed by a concatenation of raw serialized
extensions each starting with its size stored on 32 bits. This provides the
shortest representation, optimizing for the total certificate size.
The magic multi grant header is defined as:
```
#define HIBA_MULTI_EXTS 0x4d554c54
```
Followed by repeated grants:
```
uint32 size
string raw_extension
```
## Support for compression
Optionally, the value of the OpenSSH certificate extension can be compressed
using zlib in order to minimize the size of the resulting certificate. This
allows to accomodate for hardware security keys with limited storage size or
even embedded systems.
## Extensions ID
The HIBA extensions are identified by the following IDs:
* `[email protected]`: a host certificate can only have one
identity extension attached.
* `[email protected]`: a user certificate can have an arbitrary
number of grant extensions attached. Access will be granted if any grant
extension matches.
## Special extension keys
HIBA reserves five extension keys with a special meaning:
| Key | Description |
| --------- | -----------------------------------------------------------------|
| hostname | The hostname constraint used in a HIBA grant is directly checked |
: : against the hostname of the target host as returned by the :
: : gethostname() syscall, even if no host certificate is present on :
: : the target host. This allows a low-level last resort way to :
: : contact a host that has a corrupted host certificate or identity :
: : extension. :
| domain | The domain constraint used in a HIBA grant is checked against the|
: : corresponding HIBA identity, but this key is mandatory in both :
: : extensions. This allows preventing inadvertantly granting wide :
: : privileges when managing different domains using the same CA key :
| options | The list of SSH options to be applied to this SSH connection, as |
: : they would be listed in an authorized_users or authorized_keys :
: : file. :
| validity | The duration in seconds from the supporting certificate issued |
: : date. This means that a certificate can have unlimited validity, :
: : but some of the grants attached would be able to expire :
: : independently. :
| role | The target requested role to grant access to. This can be any |
: : role available on the target host. The special value @PRINCIPALS :
: : will be automatically expanded to the list of principals declared:
: : in the certificate. :
## Special key modifier
HIBA reserves the HIBA_NEGATIVE_MATCHING char used as the first character of a
key as a way to express a negative matching constraint. See
PROTOCOL.authorizations for more details on how negative matching is evaluated.
HIBA_NEGATIVE_MATCHING is defined as:
```
#define HIBA_NEGATIVE_MATCHING '!'
```