PROTOCOL.extensions

# 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:

* `identity@hibassh.dev`: a host certificate can only have one
  identity extension attached.
* `grant@hibassh.dev`: 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 '!'
```