ssh-keygen supports signing of keys to produce certificates that
may be used for user or host authentication. Certificates consist
of a public key, some identity information, zero or more principal
(user or host) names and a set of options that are signed by a
Certification Authority (CA) key. Clients or servers may then
trust only the CA key and verify its signature on a certificate
rather than trusting many user/host keys. Note that OpenSSH
certificates are a different, and much simpler, format to the X.509
certificates used in ssl(8).
ssh-keygen supports two types of certificates: user and host. User
certificates authenticate users to servers, whereas host
certificates authenticate server hosts to users. To generate a
user certificate:
$ ssh-keygen -s /path/to/ca_key -I key_id
/path/to/user_key.pub
The resultant certificate will be placed in
/path/to/user_key-cert.pub. A host certificate requires the -h
option:
$ ssh-keygen -s /path/to/ca_key -I key_id -h
/path/to/host_key.pub
The host certificate will be output to /path/to/host_key-cert.pub.
It is possible to sign using a CA key stored in a PKCS#11 token by
providing the token library using -D and identifying the CA key by
providing its public half as an argument to -s:
$ ssh-keygen -s ca_key.pub -D libpkcs11.so -I key_id
user_key.pub
Similarly, it is possible for the CA key to be hosted in a
ssh-agent(1). This is indicated by the -U flag and, again, the CA
key must be identified by its public half.
$ ssh-keygen -Us ca_key.pub -I key_id user_key.pub
In all cases, key_id is a "key identifier" that is logged by the
server when the certificate is used for authentication.
Certificates may be limited to be valid for a set of principal
(user/host) names. By default, generated certificates are valid
for all users or hosts. To generate a certificate for a specified
set of principals:
$ ssh-keygen -s ca_key -I key_id -n user1,user2 user_key.pub
$ ssh-keygen -s ca_key -I key_id -h -n host.domain
host_key.pub
Additional limitations on the validity and use of user certificates
may be specified through certificate options. A certificate option
may disable features of the SSH session, may be valid only when
presented from particular source addresses or may force the use of
a specific command.
The options that are valid for user certificates are:
clear Clear all enabled permissions. This is useful for clearing
the default set of permissions so permissions may be added
individually.
critical:name[=contents]
extension:name[=contents]
Includes an arbitrary certificate critical option or
extension. The specified name should include a domain
suffix, e.g. 'name@example.com'. If contents is specified
then it is included as the contents of the extension/option
encoded as a string, otherwise the extension/option is
created with no contents (usually indicating a flag).
Extensions may be ignored by a client or server that does
not recognise them, whereas unknown critical options will
cause the certificate to be refused.
force-command=command
Forces the execution of command instead of any shell or
command specified by the user when the certificate is used
for authentication.
no-agent-forwarding
Disable ssh-agent(1) forwarding (permitted by default).
no-port-forwarding
Disable port forwarding (permitted by default).
no-pty Disable PTY allocation (permitted by default).
no-user-rc
Disable execution of ~/.ssh/rc by sshd(8) (permitted by
default).
no-x11-forwarding
Disable X11 forwarding (permitted by default).
permit-agent-forwarding
Allows ssh-agent(1) forwarding.
permit-port-forwarding
Allows port forwarding.
permit-pty
Allows PTY allocation.
permit-user-rc
Allows execution of ~/.ssh/rc by sshd(8).
permit-X11-forwarding
Allows X11 forwarding.
no-touch-required
Do not require signatures made using this key include
demonstration of user presence (e.g. by having the user
touch the authenticator). This option only makes sense for
the FIDO authenticator algorithms ecdsa-sk and ed25519-sk.
source-address=address_list
Restrict the source addresses from which the certificate is
considered valid. The address_list is a comma-separated
list of one or more address/netmask pairs in CIDR format.
verify-required
Require signatures made using this key indicate that the
user was first verified. This option only makes sense for
the FIDO authenticator algorithms ecdsa-sk and ed25519-sk.
Currently PIN authentication is the only supported
verification method, but other methods may be supported in
the future.
At present, no standard options are valid for host keys.
Finally, certificates may be defined with a validity lifetime. The
-V option allows specification of certificate start and end times.
A certificate that is presented at a time outside this range will
not be considered valid. By default, certificates are valid from
the UNIX Epoch to the distant future.
For certificates to be used for user or host authentication, the CA
public key must be trusted by sshd(8) or ssh(1). Please refer to
those manual pages for details.
