Announcing HIBA: Host Identity Based Authorization for SSH

How do you manage SSH access to a fleet of hosts? While OpenSSH provides many methods from a simple password to the use of certificates, each of these on its own still presents challenges.

Let's start by clarifying the difference between Authentication and Authorization. The former is a way to prove you are the entity you claim to be. This is usually achieved by providing the secret password associated with your account or by signing a challenge proving you own the private key corresponding to a public key. Authorization is a way to decide whether an entity is allowed or not to access a resource—usually performed after Authentication happens.

Request ⇒ AuthenticateAuthorize ⇒ Result

Authorization with OpenSSH is typically done using one of the following:
  • The principal knows the password of the target role account on the host.
  • The principal's public key is present in the authorized_keys of the target role account on the host.
  • The principal's username is present in the authorized_users of the target role account on the host.
Transposing this into a real life example: the bouncer of the Foo bar asks for your ID and checks if the photo matches your face (authentication), then decides, based on whether your name is on the guest list, if you are allowed in or not (authorization).

All these methods require accessing the target host in order to update authorizations (the guest list) by either updating the password, or adding/removing authorized_(keys|users).

Note: OpenSSH's use of certificates provides an extra layer of authorization by requiring a Certificate Authority (CA) to trust the incoming public key. Short lived certificates provide a flexible on/off switch for globally authorizing an entity access to the targeted hosts, but they still don't solve the problem of per hosts authorization policies.

Introducing Hiba image
Introducing HIBA

HIBA is a layer on top of OpenSSH that aims at solving this problem:
  • Centralized policy for controlling per host authorization.
  • Hermetic authorization mechanism making it suitable for deep embedded applications or emergency situations.
Going back to our previous nightclub example: the certificate is your ID, and the signed challenge is your photo/face matching. HIBA would be the bouncer, except its decision is not based on a guest list, but rather on you presenting a valid access ticket.

HIBA achieves this by relying on OpenSSH and the certificate infrastructure.
  • Authorization decisions are made centrally by the CA.
  • Authorization is stored as a certificate extension signed by the CA.
  • Hosts trust the CA thanks to TrustedUserCAKeys sshd configuration option.
  • Hosts enforce the authorization policy presented with the certificate by relying on HIBA via the AuthorizedPrincipalsCommand sshd configuration option.

In more details

HIBA defines two extensions to SSH certificates:
  • The HIBA identity, attached to host certificates, lists properties defining this host. They will be used as criteria for granting access.
  • The HIBA grant, attached to user certificates, lists constraints that a host must match for access to be granted.
On the host side, the hiba-chk helper is responsible for decoding extensions from both the host and user certificates and deciding whether or not to grant access.

On the CA side, the HIBA policy defines a set of grants and a list of users allowed to request them. Users can now ask the CA for HIBA grants to be attached to their certificates. The CA will confirm eligibility based on the policy and sign the certificate after adding the requested HIBA grants.

The HIBA extension scheme is flexible by nature, and any type of constraint can be assigned to grants as long as they are also defined in the identity. The exact specifications can be found in the PROTOCOL.authorizations file. HIBA only defines a handful of reserved constraints that are described in the PROTOCOL.extensions file.

The HIBA source code implements hiba-chk for processing authorizations as well as a library (libhiba) and a CLI (hiba-gen) for generating HIBA extensions. It also provides a simple shell based CA implementation

Practical example

Hosts identities

Host identities example


Grants example

In this example:
  • A user with an Employee SEA grant can access any hosts located in Seattle.
  • A user with the Guests grant can access hosts everywhere, but only if they are Dance floor, while Celebrities can access both VIP lounge and Dance floor hosts.
  • The owner grant gives unrestricted access to any hosts.
By Tristan Lelong – Site Reliability Enthusiast, Technical Infrastructure