OpenSSH Certificate Extensions

[Damien Miller]

On Mon, 20 May 2019, Nickolas Klue wrote:

> Hello:
>
> I am working to implement certificate-based authentication for some
> internal applications. It would be very helpful to be able to pass
> information server-side by specifying some custom options via the
> Extensions of the signed certificate, allowing the authenticity of the
> options to be verified readily. However, I have not been able to find
> too much for specifying behaviors, etc. server-side in relation to
> custom certificate extensions in the documentation.
>
> Is there any extant documentation that goes into more depth than
> PROTOCOL.certkeys that anyone would be able to point me towards before
> I start digging into source? My digging for documentation has not been
> very fruitful as of yet.

There's not really any more documentation beyond the PROTOCOL.certkeys
file. Extensions are simply name=value pairs and unrecognised extensions
are, by design, simply ignored by the server (use a critical option if
you want an unrecognised option to cause auth to fail).

The ssh-keygen tool allows creating private extensions, e.g.

ssh-keygen -s /path/ca -I id -O extension:x at example.com=foo key.pub

I'd recommend you follow name at domain.org naming for any local extensions
that you define.

As for server behaviour, there is nothing in sshd that considers
extensions beyond those defined in the PROTOCOL.certkeys file. If you
want custom behaviour, you'll have to implement it yourself. There are a
few ways to do this:

The first is by implementing support for the extensions in sshd
directly. This isn't particularly hard, esp. since I refactored
the authentication options code in recent releases. Take a look at
auth-options.[ch] to see how the existing extensions are handed if you
want to go this path.

Another option is building your controls in a PAM module. OpenSSH >=
7.6 exposes the public keys/certs used for authentication via the PAM
environment, so it is possible to parse the key there and pull out your
local extensions. If you do this in a session module, you can do stuff
like custom ulimits, environment variables, etc.

Finally, if you just want to make authn/authz decisions on the
extensions then you can implementing auth-time processing of custom
extensions via ssh'd AuthorizedPrincipalsCommand. This can be passed the
key contents using the %k expansion and you pull out the extensions from
there and abort the authentication or add additional key restrictions
based on their contents.

> Thank you very much to anyone that is able to shine some light on this
> topic or outright tell me that I am wrong for contemplating it and
> why.

You're not wrong to contemplate it. I'm aware of a number of
large organisations that use custom certificate extensions to
perform various form of signalling. AFAIK most of them do the
AuthorizedPrincipalsCommand route.

-d