-
Notifications
You must be signed in to change notification settings - Fork 15
/
PROTOCOL.grl
96 lines (70 loc) · 2.86 KB
/
PROTOCOL.grl
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
# Grant Revocation List
## Purpose
This file allows to selectively revoke one or several grants from a
certificate without revoking all the grants or the certificate itself.
Note: Consider using an OpenSSH KRL if you want to revoke entire certificates
instead of individual grants - it is more efficient.
## Format
The hiba-chk is a short lived helper invoked by OpenSSH and will need to parse
the GRL file for every invocation. Therefore, the format has been optimized for
fast SSH certificate serial lookups.
The GRL starts with a header followed by two sections: serials list and grant
revocation maps. Each section starts with a uint64 that store the section size.
```
uint32 magic
uint32 version
uint32 min_version
uint64 timestamp
string comment
```
Where magic is defined as:
```
#define HIBA_GRL_MAGIC 0x4847524c
```
The subsequent section begins with a uint64 indicating the number of entries in
a sorted list of certificate serial numbers each of which is associated with an
offset. Entries in the list have a fixed size in order to allow quick lookups.
The offset is used to find the corresponding bitmap of revoked grants in the
next section.
```
uint64 serial
uint64 offset
```
The last section contains a list of bitmaps corresponding to serial entries from
the previous section. The offset of each bit in the map, for a given serial,
represents the position of a grant in the certificate. This means that the order
of grants in a certificate matters.
```
char[] bitmap
```
The size of each bitmap is variable, consisting of a char[] of length one or
more depending on the position of revoked grants in the certificate. The size of
a bitmap for a serial[i] can be calculated using the offsets for serial[i] and
serial[i+1].
```
size = serial[i+1].offset - serial[i].offset
```
When serial[i] is the final serial in the serials list section the grant
revocation map section size must be used to calculate the bitmap size instead of
the serial[i+1] offset.
```
size = revocation_map_size - serial[i].offset
```
Finally, the file also contains a trailer magic (same value as header magic).
## Grant Revocation Check
A grant is revoked for a given certificate only when all of the following
conditions are met.
1. The certificate serial is found in the serials list section.
2. The grant index from the certificate falls within the bounds of the relevant
revocation bitmap. See the GRL format documentation above for information on
calculating the size of a bitmap.
```
floor(grant_idx / 8) <= bitmap_size
```
3. The bit in the map corresponding to the grant index must equal 1.
## Usage
This file is read by hiba-chk and must be pushed by the host owner similarly to
the openssh KRL.
Note: It is the CA owner's responsibility to assess the trade off between the
need to push a GRL file periodically and the maximum allowed validity of HIBA
grants within a certificate.