PROTOCOL.grl

# 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 contains a sorted list of certificate serial numbers
associated with an offset. Each entry has 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.