[system-administrators-guide/22] Updates to OpenSSH certificates
stephenw
stephenw at fedoraproject.org
Tue Jun 9 20:21:36 UTC 2015
commit 3239ce3361b01bc789fc645b906c3873e03c1b27
Author: Stephen Wadeley <swadeley at redhat.com>
Date: Thu Jun 4 00:40:39 2015 +0200
Updates to OpenSSH certificates
Thanks to Jakub Jelen for his review.
en-US/OpenSSH.xml | 301 +++++++++++++++++++++++++++--------------------------
1 files changed, 152 insertions(+), 149 deletions(-)
---
diff --git a/en-US/OpenSSH.xml b/en-US/OpenSSH.xml
index 8f1a971..8fdef69 100644
--- a/en-US/OpenSSH.xml
+++ b/en-US/OpenSSH.xml
@@ -913,8 +913,8 @@ Two types of certificates are required, host certificates and user certificates.
It is recommended to create and store CA keys in a safe place just as with any other private key. In these examples the <systemitem class="username">root</systemitem> user will be used. In a real production environment using an offline computer with an administrative user account is recommended. For guidance on key lengths see <ulink url="http://csrc.nist.gov/publications/nistpubs/800-131A/sp800-131A.pdf"><citetitle pubwork="book">NIST Special Publication 800-131A</citetitle></ulink>.
</para>
</important>
-<procedure id="proc-Generating_an_SSH_CA_Certificate">
-<title>Generating an SSH CA Certificate</title>
+<procedure id="proc-Generating_SSH_CA_Certificate_Signing-Keys">
+<title>Generating SSH CA Certificate Signing Keys</title>
<step>
<para>
On the server designated to be the CA, generate two keys for use in signing certificates. These are the keys that all other hosts need to trust. Choose suitable names, for example <filename>ca_user_key</filename> and <filename>ca_host_key</filename>. To generate the user certificate signing key, enter the following command as <systemitem class="username">root</systemitem>:
@@ -977,15 +977,15 @@ dr-xr-x---. 3 root root 4096 May 8 08:34 ..
</step>
<step>
<para>
-Create the CA server's own host certificate by signing the server's host public key together with an identification string such as the host name, the CA server's <firstterm>fully qualified domain name</firstterm> (<acronym>FQDN)</acronym>, and a validity period. The command takes the following form:
-<synopsis>ssh-keygen -s ~/.ssh/ca_host_key -I <replaceable>certificate_ID</replaceable> -h -Z <replaceable>host_name.example.com.</replaceable> -V <replaceable>-start:+end</replaceable> ~/.ssh/ssh_host_rsa.pub</synopsis>
+Create the CA server's own host certificate by signing the server's host public key together with an identification string such as the host name, the CA server's <firstterm>fully qualified domain name</firstterm> (<acronym>FQDN</acronym>) but without the trailing <literal>.</literal>, and a validity period. The command takes the following form:
+<synopsis>ssh-keygen -s ~/.ssh/ca_host_key -I <replaceable>certificate_ID</replaceable> -h -Z <replaceable>host_name.example.com</replaceable> -V <replaceable>-start:+end</replaceable> /etc/ssh/ssh_host_rsa.pub</synopsis>
The <option>-Z</option> option restricts this certificate to a specific host within the domain. The <option>-V</option> option is for adding a validity period; this is highly recommend. Where the validity period is intended to be one year, fifty two weeks, consider the need for time to change the certificates and any holiday periods around the time of certificate expiry.
</para>
<para>
For example:
-<screen>~]# <command>ssh-keygen -s ~/.ssh/ca_host_key -I <replaceable>host_name</replaceable> -h -Z host_name.example.com. -V -1w:+54w5d ~/.ssh/ssh_host_rsa.pub</command>
+<screen>~]# <command>ssh-keygen -s ~/.ssh/ca_host_key -I host_name -h -Z host_name.example.com -V -1w:+54w5d /etc/ssh/ssh_host_rsa.pub</command>
Enter passphrase:
-Signed host key /root/.ssh/ssh_host_rsa-cert.pub: id "<replaceable>host_name</replaceable>" serial 0 for host_name.example.com. valid from 2015-05-15T13:52:29 to 2016-06-08T13:52:29</screen>
+Signed host key /root/.ssh/ssh_host_rsa-cert.pub: id "host_name" serial 0 for host_name.example.com valid from 2015-05-15T13:52:29 to 2016-06-08T13:52:29</screen>
</para>
</step>
</procedure>
@@ -1010,28 +1010,52 @@ ca_user_key.pub 100% 420 0.4KB/s 00
</para>
<para>
-CA keys can be marked as trusted in the <filename>~/.ssh/authorized_keys</filename> file or by means of the <command>TrustedUserCAKeys</command> directive in the <filename>/etc/ssh/sshd_config</filename> file for user authentication, or in the <filename>/etc/ssh/known_hosts</filename> or <filename>~/.ssh/ssh_known_hosts</filename> file for host authentication.
+For remote user authentication, CA keys can be marked as trusted per-user in the <filename>~/.ssh/authorized_keys</filename> file using the <command>cert-authority</command> directive or for global use by means of the <command>TrustedUserCAKeys</command> directive in the <filename>/etc/ssh/sshd_config</filename> file. For remote host authentication, CA keys can be marked as trusted globally in the <filename>/etc/ssh/known_hosts</filename> file or per-user in the <filename>~/.ssh/ssh_known_hosts</filename> file.
</para>
+
+ <procedure id="proc-Trusting_the_User_Signing_Key">
+ <title>Trusting the User Signing Key</title>
+<step>
<para>
-To configure a host to permit logging in by a remote user listed in a certificate's list of principals, edit the <filename>/etc/ssh/sshd_config</filename> file as follows:
+For user certificates which have one or more principles listed, and where the setting is to have global effect, edit the <filename>/etc/ssh/sshd_config</filename> file as follows:
<synopsis>TrustedUserCAKeys /etc/ssh/ca_user_key.pub</synopsis>
Restart <systemitem class="daemon">sshd</systemitem> to make the changes take effect:
<screen>~]# <command>service sshd restart</command></screen>
</para>
+ </step>
+ </procedure>
+
<para>
-To configure a host to permit logging in to any user account from any remote user with a certificate, add the key to the <filename>/etc/ssh/ssh_known_hosts</filename> file using the <command>cert-authority</command> directive. For example:
-<screen># A CA key, accepted for any host in *.example.com
+ To avoid being presented with the warning about an unknown host, a user's system must trust the CA's public key that was used to sign the host certificates. In this example that is <literal>ca_host_key.pub</literal>.</para>
+
+<procedure id="proc-Trusting_the_Host_Signing_Key">
+<title>Trusting the Host Signing Key</title>
+<step>
+<para>
+ Extract the contents of the public key used to sign the host certificate. For example, on the CA:
+ <screen><command>cat ~/.ssh/ca_host_key.pub</command>
+ssh-rsa <replaceable>AAAAB5Wm.</replaceable>== root at ca-server.example.com</screen>
+</para>
+</step>
+<step>
+<para>
+To configure client systems to trust servers' signed host certificates, add the contents of the <literal>ca_host_key.pub</literal> into the global <filename>known_hosts</filename> file. This will automatically check a server's host advertised certificate against the CA public key for all users every time a new machine is connected to in the domain <literal>*.example.com</literal>. Login as <systemitem class="username">root</systemitem> and configure the <filename>/etc/ssh/ssh_known_hosts</filename> file, as follows:
+<screen>~]# <command>vi /etc/ssh/ssh_known_hosts</command>
+# A CA key, accepted for any host in *.example.com
@cert-authority *.example.com ssh-rsa <replaceable>AAAAB5Wm.</replaceable></screen>
- The <filename>sshd(8)</filename> manual page has more examples.
+Where <computeroutput>ssh-rsa <replaceable>AAAAB5Wm.</replaceable></computeroutput> is the contents of <literal>ca_host_key.pub</literal>. The above configures the system to trust the CA servers host public key. This enables global authentication of the certificates presented by hosts to remote users.
</para>
+</step>
+
+</procedure>
- <para>
- To avoid being presented with the warning about an unknown host, user's systems must be configured to trust the CA's public key that was used to sign the host certificates. In this example that is <literal>ca_host_key.pub</literal>.
-</para>
</section>
<section id="sec-Signing_SSH_Certificates">
-<title>Signing SSH Certificates</title>
+<title>Creating SSH Certificates</title>
+<para>
+A certifcate is a signed public key. The user's and host's public keys must be copied to the CA server for signing by the CA server's private key.
+</para>
<important>
<para>
@@ -1049,6 +1073,88 @@ drwxrwxrwx. 2 admin admin 4096 May 22 16:17 .
drwx------. 3 admin admin 4096 May 22 16:17 ..</screen>
</para>
+<section id="sec-Creating_SSH_Certificates_to_Authenticate_Hosts">
+<title>Creating SSH Certificates to Authenticate Hosts</title>
+<para>
+The command to sign a host certificate has the following format:
+ <synopsis>ssh-keygen -s ca_host_key -I <replaceable>host_name</replaceable> -h ssh_host_rsa_key.pub</synopsis>
+The host certificate will named <filename>ssh_host_rsa_key-cert.pub</filename>.
+</para>
+
+<procedure id="proc-Generating_a_Host_Certificate">
+<title>Generating a Host Certificate</title>
+
+<para>
+ To authenticate a host to a user, a public key must be generated on the host, passed to the CA server, signed by the CA, and then passed back to be stored on the host to present to a user attempting to log into the host.
+</para>
+<step>
+<para>
+Host keys are generated automatically on the system. To list them enter the following command:
+ <screen>~]# <command>ls -l /etc/ssh/ssh_host*</command>
+-rw-------. 1 root root 668 May 6 14:38 /etc/ssh/ssh_host_dsa_key
+-rw-r--r--. 1 root root 590 May 6 14:38 /etc/ssh/ssh_host_dsa_key.pub
+-rw-------. 1 root root 963 May 6 14:38 /etc/ssh/ssh_host_key
+-rw-r--r--. 1 root root 627 May 6 14:38 /etc/ssh/ssh_host_key.pub
+-rw-------. 1 root root 1679 May 6 14:38 /etc/ssh/ssh_host_rsa_key
+-rw-r--r--. 1 root root 382 May 6 14:38 /etc/ssh/ssh_host_rsa_key.pub</screen>
+</para>
+</step>
+<step>
+ <para>
+ Copy the chosen public key to the server designated as the CA. For example, from the host:
+ <screen>~]# <command>scp /etc/ssh/ssh_host_rsa_key.pub admin at ca-server.example.com:~/keys/ssh_host_rsa_key.pub</command>
+The authenticity of host 'ca-server.example.com (10.34.74.58)' can't be established.
+RSA key fingerprint is b0:e5:ea:b8:75:e2:f0:b1:fe:5b:07:39:7f:58:64:d9.
+Are you sure you want to continue connecting (yes/no)? yes
+Warning: Permanently added 'ca-server.example.com,10.34.74.58' (RSA) to the list of known hosts.
+admin at ca-server.example.com's password:
+ssh_host_rsa_key.pub 100% 382 0.4KB/s 00:00</screen>
+ </para>
+ <para>
+ Alternately, from the CA:
+ <screen>~]$ <command>scp root at host_name.example.com:/etc/ssh/ssh_host_rsa_key.pub ~/keys/ssh_host_rsa_key.pub</command></screen>
+ </para>
+
+</step>
+<step>
+<para>
+ On the CA server, sign the host's public key. For example, as <systemitem class="username">root</systemitem>:
+ <screen>~]# <command>ssh-keygen -s ~/.ssh/ca_host_key -I host_name -h -Z host_name.example.com -V -1d:+54w /home/admin/keys/ssh_host_rsa_key.pub</command>
+Enter passphrase:
+Signed host key /home/admin/keys/ssh_host_rsa_key-cert.pub: id "host_name" serial 0 for host_name.example.com valid from 2015-05-26T12:21:54 to 2016-06-08T12:21:54</screen>
+ Where <replaceable>host_name</replaceable> is the host name of the system requiring the certificate.
+</para>
+</step>
+<step>
+ <para>
+ Copy the certificate to the host. For example, from the CA:
+ <screen>~]# <command>scp /home/admin/keys/ssh_host_rsa_key-cert.pub root at host_name.example.com:/etc/ssh/</command>
+root at host_name.example.com's password:
+ssh_host_rsa_key-cert.pub 100% 1384 1.5KB/s 00:00</screen>
+ </para>
+</step>
+<step>
+ <para>
+Configure the host to present the certificate to a user's system when a user initiates the login process. As <systemitem class="username">root</systemitem>, edit the <filename>/etc/ssh/sshd_config</filename> file as follows:
+ <synopsis>HostCertificate /etc/ssh/ssh_host_rsa_key-cert.pub</synopsis>
+ </para>
+</step>
+<step>
+ <para>
+ Restart <systemitem class="daemon">sshd</systemitem> to make the changes take effect:
+ <screen>~]# <command>service sshd restart</command></screen>
+ </para>
+</step>
+
+<step>
+ <para>
+ On user's systems. remove keys belonging to hosts from the <filename>~/.ssh/known_hosts</filename> file if the user has previously logged into the host configured above. When a user logs into the host they should no longer be presented with the warning about the hosts authenticity.</para>
+</step>
+</procedure>
+
+ <para>
+ To test the host certificate, on a client system, ensure the client has set up the global <filename>/etc/ssh/known_hosts</filename> file, as described in <xref linkend="proc-Trusting_the_Host_Signing_Key"/>, and that the server's public key is not in the <filename>~/.ssh/known_hosts</filename> file. Then attempt to log into the server over SSH as a remote user. You should not see a warning about the authenticity of the host. If required, add the <option>-v</option> option to the SSH command to see logging information.</para>
+
</section>
<section id="sec-Creating_SSH_Certificates_for_Authenticating_Users">
@@ -1059,18 +1165,25 @@ To sign a user's certificate, use a command in the following format:
The resulting certificate will be named <filename>id_rsa-cert.pub</filename>.
</para>
<para>
- The default behavior of OpenSSH is that a certificate must include the user's name in order to be accepted for authentication. There are two alternatives:
+ The default behavior of OpenSSH is that a user is allowed to log in as a remote user if one of the principals specified in the certificate matches the remote user's name. This can be adjusted in the following ways:
<itemizedlist>
<listitem>
<para>
- Add the user's names to the certificate during the signing process using the <option>-Z</option>:
+ Add more user's names to the certificate during the signing process using the <option>-Z</option> option:
<synopsis>-Z "name1[,name2,...]"</synopsis>
- and add the public key of the CA in the <filename>~/.ssh/authorized_keys</filename> file.
+</para>
+</listitem>
+<listitem>
+<para>
+ On the user's system, add the public key of the CA in the <filename>~/.ssh/authorized_keys</filename> file using the <command>cert-authority</command> directive and list the principals names as follows:
+<screen>~]# <command>vi ~/.ssh/authorized_keys</command>
+# A CA key, accepted for any host in *.example.com
+ at cert-authority principals="name1,name2" *.example.com ssh-rsa <replaceable>AAAAB5Wm.</replaceable></screen>
</para>
</listitem>
<listitem>
<para>
- Add the principles names in a per-user file. In the <filename>/etc/ssh/sshd_config</filename> file, specify the file using the <command>AuthorizedPrincipalsFile</command> directive, and specify the CA's public key using the <command>TrustedCAKeys</command> directive.
+ On the server, create an <literal>AuthorizedPrincipalsFile</literal> file, either per user or glabally, and add the principles' names to the file for those users allowed to log in. Then in the <filename>/etc/ssh/sshd_config</filename> file, specify the file using the <command>AuthorizedPrincipalsFile</command> directive.
</para>
</listitem>
</itemizedlist>
@@ -1128,12 +1241,9 @@ Where <replaceable>protocol</replaceable> is the part of the file name indicatin
<para>
Copy the chosen public key to the server designated as the CA. For example:
<screen>~]$ <command>scp ~/.ssh/id_rsa.pub admin at ca-server.example.com:~/keys/</command>
-The authenticity of host 'ca-server.example.com (10.34.74.58)' can't be established.
-RSA key fingerprint is b0:e5:ea:b8:75:e2:f0:b1:fe:5b:07:39:7f:58:64:d9.
-Are you sure you want to continue connecting (yes/no)? yes
-Warning: Permanently added 'ca-server.example.com,10.34.74.58' (RSA) to the list of known hosts.
admin at ca-server.example.com's password:
id_rsa.pub 100% 421 0.4KB/s 00:00</screen>
+If you have configured the client system to trust the host signing key as described in <xref linkend="proc-Trusting_the_Host_Signing_Key"/> then you should not see a warning about the authenticity of the remote host.
</para>
</step>
<step>
@@ -1141,7 +1251,7 @@ id_rsa.pub 100% 421 0.4KB/s 00:00</scree
On the CA server, sign the user's public key. For example, as <systemitem class="username">root</systemitem>:
<screen>~]# <command>ssh-keygen -s ~/.ssh/ca_user_key -I user1 -Z user1 -V -1d:+54w /home/admin/keys/id_rsa.pub</command>
Enter passphrase:
-Signed user key /home/admin/keys/id_rsa-cert.pub: id "user1" serial 0 for host_name.example.com. valid from 2015-05-21T16:43:17 to 2016-06-03T16:43:17</screen>
+Signed user key /home/admin/keys/id_rsa-cert.pub: id "user1" serial 0 for host_name.example.com valid from 2015-05-21T16:43:17 to 2016-06-03T16:43:17</screen>
</para>
</step>
<step>
@@ -1155,9 +1265,10 @@ id_rsa-cert.pub 100% 1498 1.5KB/s 00:00</scree
<step>
<para>
- If using the standard file names and location then no further configuration is required as the SSH daemon will search for user certificates ending in <literal>-cert.pub</literal> and use them automatically if it finds them. Note that the default location and file names for for SSH version 2 keys are: <filename>~/.ssh/id_dsa</filename>, <filename>~/.ssh/id_ecdsa</filename> and <filename>~/.ssh/id_rsa</filename> as explained in the <filename>ssh_config(5)</filename> manual page. If you use these locations and naming conventions then there is no need for editing the configuration files to enable <systemitem class="daemon">sshd</systemitem> to present the certificate. They will be used automatically when logging in to a remote system. There is also no need to restart <systemitem class="daemon">sshd</systemitem> in this case and you can skip to step 6.</para>
+ If using the standard file names and location then no further configuration is required as the SSH daemon will search for user certificates ending in <literal>-cert.pub</literal> and use them automatically if it finds them. Note that the default location and file names for for SSH version 2 keys are: <filename>~/.ssh/id_dsa</filename>, <filename>~/.ssh/id_ecdsa</filename> and <filename>~/.ssh/id_rsa</filename> as explained in the <filename>ssh_config(5)</filename> manual page. If you use these locations and naming conventions then there is no need for editing the configuration files to enable <systemitem class="daemon">sshd</systemitem> to present the certificate. They will be used automatically when logging in to a remote system. In this is the case then skip to step 6.</para>
+
<para>
- If required to use a non-default directory or file naming convention, then as <systemitem class="username">root</systemitem>, add the following line to the <filename>/etc/ssh/sshd_config</filename> or <filename>~/.ssh/config</filename> files:
+ If required to use a non-default directory or file naming convention, then as <systemitem class="username">root</systemitem>, add the following line to the <filename>/etc/ssh/ssh_config</filename> or <filename>~/.ssh/config</filename> files:
<screen>IdentityFile <replaceable>~/path/key_file</replaceable></screen>
Note that this must be the private key name, do not had <literal>.pub</literal> or <literal>-cert.pub</literal>.
Ensure the file permission are correct. For example:
@@ -1179,125 +1290,21 @@ id_rsa-cert.pub 100% 1498 1.5KB/s 00:00</scree
</section>
-<section id="sec-Creating_SSH_Certificates_to_Authenticate_Hosts">
-<title>Creating SSH Certificates to Authenticate Hosts</title>
-<para>
-The command to sign a host certificate has the following format:
- <synopsis>ssh-keygen -s ca_host_key -I <replaceable>host_name</replaceable> -h ssh_host_rsa_key.pub</synopsis>
-The host certificate will named <filename>ssh_host_rsa_key-cert.pub</filename>.
-</para>
-
-<procedure id="proc-Generating_a_Host_Certificate">
-<title>Generating a Host Certificate</title>
-
-<para>
- To authenticate a host to a user, a public key must be generated on the host, passed to the CA server, signed by the CA, and then passed back to be stored on the host to present to a user attempting to log into the host.
-</para>
-<step>
-<para>
-Host keys are generated automatically on the system. To list them enter the following command:
- <screen>~]# <command>ls -l /etc/ssh/ssh_host*</command>-rw-------. 1 root root 668 May 6 14:38 /etc/ssh/ssh_host_dsa_key
--rw-r--r--. 1 root root 590 May 6 14:38 /etc/ssh/ssh_host_dsa_key.pub
--rw-------. 1 root root 963 May 6 14:38 /etc/ssh/ssh_host_key
--rw-r--r--. 1 root root 627 May 6 14:38 /etc/ssh/ssh_host_key.pub
--rw-------. 1 root root 1679 May 6 14:38 /etc/ssh/ssh_host_rsa_key
--rw-r--r--. 1 root root 382 May 6 14:38 /etc/ssh/ssh_host_rsa_key.pub</screen>
-</para>
-</step>
-<step>
- <para>
- Copy the chosen public key to the server designated as the CA. For example, from the host:
- <screen>~]# <command>scp /etc/ssh/ssh_host_rsa_key.pub admin at ca-server.example.com:~/keys/ssh_host_rsa_key.pub</command>
-The authenticity of host 'ca-server.example.com (10.34.74.58)' can't be established.
-RSA key fingerprint is b0:e5:ea:b8:75:e2:f0:b1:fe:5b:07:39:7f:58:64:d9.
-Are you sure you want to continue connecting (yes/no)? yes
-Warning: Permanently added 'ca-server.example.com,10.34.74.58' (RSA) to the list of known hosts.
-admin at ca-server.example.com's password:
-ssh_host_rsa_key.pub 100% 382 0.4KB/s 00:00</screen>
- </para>
- <para>
- Alternately, from the CA:
- <screen>~]$ <command>scp root at host_name.example.com:/etc/ssh/ssh_host_rsa_key.pub ~/keys/ssh_host_rsa_key.pub</command></screen>
- </para>
-
-</step>
-<step>
-<para>
- On the CA server, sign the host's public key. For example, as <systemitem class="username">root</systemitem>:
- <screen>~]# <command>ssh-keygen -s ~/.ssh/ca_host_key -I host_name -h -Z host_name.example.com. -V -1d:+54w /home/admin/keys/ssh_host_rsa_key.pub</command>
-Enter passphrase:
-Signed host key /home/admin/keys/ssh_host_rsa_key-cert.pub: id "host_name" serial 0 for host_name.example.com. valid from 2015-05-26T12:21:54 to 2016-06-08T12:21:54</screen>
- Where <replaceable>host_name</replaceable> is the host name of the system requiring the certificate.
-</para>
-</step>
-<step>
- <para>
- Copy the certificate to the host. For example, from the CA:
- <screen>~]# <command>scp /home/admin/keys/ssh_host_rsa_key-cert.pub root at host_name.example.com:/etc/ssh/</command>
-root at host_name.example.com's password:
-ssh_host_rsa_key-cert.pub 100% 1384 1.5KB/s 00:00</screen>
- </para>
-</step>
-<step>
- <para>
-Configure the host to present the certificate to a user's system when a user initiates the login process. As <systemitem class="username">root</systemitem>, edit the <filename>/etc/ssh/sshd_config</filename> file as follows:
- <synopsis>HostCertificate /etc/ssh/ssh_host_rsa_key-cert.pub</synopsis>
- </para>
-</step>
-<step>
- <para>
- Restart <systemitem class="daemon">sshd</systemitem> to make the changes take effect:
- <screen>~]# <command>service sshd restart</command></screen>
- </para>
-</step>
-
-<step>
-<para>
- Extract the contents of the public key. For example, on the CA:
- <screen><command>cat ~/.ssh/ca_host_key.pub</command>
-ssh-rsa <replaceable>AAAAB5Wm.</replaceable>== root at ca-server.example.com</screen>
-</para>
-<para>
-To configure the users' systems to enable authentication of hosts certificates for all users on the system, login as <systemitem class="username">root</systemitem> and configure the <filename>/etc/ssh/ssh_known_hosts</filename> file, creating it if it does not yet exist, as follows:
-<screen># A CA key, accepted for any host in *.example.com
- at cert-authority *.example.com ssh-rsa <replaceable>AAAAB5Wm.</replaceable></screen>
- The above configures the system to trust the CA servers host public key. This enables global authentication of the certificates presented by remote hosts to users.
- </para>
-
- <para>
- For host certificates that do not include host identifying information, or for certificates that are <emphasis role="bold">not</emphasis> for global use, place the contents of the host certificate signing key file in the user's <filename>~/.ssh/known_hosts</filename> file. Create the file if it does not yet exist.
- Edit the <filename>~/.ssh/known_hosts</filename> file to include a line as follows:
-<screen># A CA key, accepted for any host in *.example.com
- at cert-authority *.example.com ssh-rsa <replaceable>AAAAB5Wm.</replaceable></screen>
- The <filename>sshd(8)</filename> manual page has more examples.
-</para>
-</step>
-<step>
- <para>
- Remove keys belonging to hosts from the <filename>~/.ssh/known_hosts</filename> file if the user has previously logged into the host configured above. When a user logs into the host they should no longer be presented with the warning about the hosts authenticity.</para>
-</step>
-<step>
- <para>
- To test the host certificate, ensure the server's public key is not in the <filename>~/.ssh/known_hosts</filename> file and then attempt to log into the server over SSH as a remote user. You should not see a warning about the authenticity of the host. If required, add the <option>-v</option> option to the SSH command to see logging information.</para>
-</step>
-
-</procedure>
-
</section>
<section id="sec-SSH_Certificate_PKCS_11_Token">
<title>Signing an SSH Certificate Using a PKCS#11 Token</title>
<para>
It is possible to sign a host key using a CA key stored in a PKCS#11 token by providing the token library using the <option>-D</option> and identifying the CA key by providing its public half as an argument to the <option>-s</option> option:
- <synopsis>ssh-keygen -s ca_key.pub -D libpkcs11.so -I <replaceable>certificate_ID</replaceable> host_key.pub</synopsis>
+ <synopsis>ssh-keygen -s ca_host_key.pub -D libpkcs11.so -I <replaceable>certificate_ID</replaceable> host_key.pub</synopsis>
In all cases, <replaceable>certificate_ID</replaceable> is a <quote>key identifier</quote> that is logged by the server when the certificate is used for authentication.
</para>
<para>
Certificates may be configured to be valid only for a set of users or host names, the principals. By default, generated certificates are valid for all users or hosts. To generate a certificate for a specified set of principals, use a comma separated list with the <option>-Z</option> option as follows:</para>
-<screen>ssh-keygen -s ca_user_key -I <replaceable>certificate_ID</replaceable> -Z <replaceable>user1,user2</replaceable> id_rsa.pub</screen>
+<screen>ssh-keygen -s ca_user_key.pub -D libpkcs11.so -I <replaceable>certificate_ID</replaceable> -Z <replaceable>user1,user2</replaceable> id_rsa.pub</screen>
<para>
and for hosts:
-<screen>ssh-keygen -s ca_host_key -I <replaceable>certificate_ID</replaceable> -h -Z host.domain ssh_host_rsa_key.pub</screen>
+<screen>ssh-keygen -s ca_host_key.pub -D libpkcs11.so -I <replaceable>certificate_ID</replaceable> -h -Z host.domain ssh_host_rsa_key.pub</screen>
</para>
<para>
Additional limitations on the validity and use of user certificates may be specified through certificate options.
@@ -1331,31 +1338,26 @@ To view a certificate, use the <option>-L</option> to list the contents. For exa
user1
Critical Options: (none)
Extensions:
- permit-X11-forwarding UNKNOWN OPTION (len 0)
- permit-agent-forwarding UNKNOWN OPTION (len 0)
- permit-port-forwarding UNKNOWN OPTION (len 0)
- permit-pty UNKNOWN OPTION (len 0)
- permit-user-rc UNKNOWN OPTION (len 0)</screen>
+ permit-X11-forwarding
+ permit-agent-forwarding
+ permit-port-forwarding
+ permit-pty
+ permit-user-rc</screen>
</para>
<para>
To vew a host certificate:
<screen>~]# <command>ssh-keygen -L -f /etc/ssh/ssh_host_rsa_key-cert.pub</command>
/etc/ssh/ssh_host_rsa_key-cert.pub:
- Type: ssh-rsa-cert-v01 at openssh.com user certificate
+ Type: ssh-rsa-cert-v01 at openssh.com host certificate
Public key: RSA-CERT 1d:71:61:50:05:9b:ec:64:34:27:a5:cc:67:24:03:23
Signing CA: RSA e4:d5:d1:4f:6b:fd:a2:e3:4e:5a:73:52:91:0b:b7:7a
Key ID: "host_name"
Serial: 0
- Valid: from 2015-05-26T12:21:54 to 2016-06-08T12:21:54
+ Valid: from 2015-05-26T17:19:01 to 2016-06-08T17:19:01
Principals:
- host_name.example.com.
+ host_name.example.com
Critical Options: (none)
- Extensions:
- permit-X11-forwarding UNKNOWN OPTION (len 0)
- permit-agent-forwarding UNKNOWN OPTION (len 0)
- permit-port-forwarding UNKNOWN OPTION (len 0)
- permit-pty UNKNOWN OPTION (len 0)
- permit-user-rc UNKNOWN OPTION (len 0)</screen>
+ Extensions: (none)</screen>
</para>
</section>
@@ -1363,11 +1365,12 @@ To view a certificate, use the <option>-L</option> to list the contents. For exa
<title>Revoking an SSH CA Certificate</title>
<para>
- If a certificate is stolen, it should be revoked. Although OpenSSH does not provide a mechanism to distribute the revocation list it is still easier to create the revocation list and distribute it by other means then to change the CAN and all host and user certificates previously created and distributed.
+ If a certificate is stolen, it should be revoked. Although OpenSSH does not provide a mechanism to distribute the revocation list it is still easier to create the revocation list and distribute it by other means then to change the CA keys and all host and user certificates previously created and distributed.
</para>
<para>
Keys can be revoked by adding them to the <filename>revoked_keys</filename> file and specifying the file name in the <filename>sshd_config</filename> file as follows:
<synopsis>RevokedKeys /etc/ssh/revoked_keys</synopsis>
+Note that if this file is not readable, then public key authentication will be refused for all users.
</para>
<para>
A new key revocation list can be generated as follows:
@@ -1381,7 +1384,7 @@ where <replaceable>integer</replaceable> is the line number.
<synopsis>ssh-keygen -Qf /etc/ssh/revoked_keys ~/.ssh/id_rsa.pub</synopsis>
</para>
<para>
- Where the <command>@cert-authority</command> directive has been used, certificates can be revoke by changing the directive to <command>@revoke</command>.
+ A user can revoke a CA certificate by changing the <command>cert-authority</command> directive to <command>revoke</command> in the <filename>known_hosts</filename> file.
</para>
</section>
More information about the docs-commits
mailing list