X.509v3 Certificates for SSH Authentication
The X.509v3 Certificates for SSH Authentication feature uses the X.509v3 digital certificates in server and user authentication at the secure shell (SSH) server side.
This module describes how to configure server and user certificate profiles for a digital certificate.
Prerequisites for X.509v3 Certificates for SSH Authentication
-
The X.509v3 Certificates for SSH Authentication feature introduces the ip ssh server algorithm authentication command to replace the ip ssh server authenticate user command. If you use the ip ssh server authenticate user command, the following deprecation message is displayed.
Warning: SSH command accepted but this CLI will be deprecated soon. Please move to new CLI “ip ssh server algorithm authentication”. Please configure “default ip ssh server authenticate user” to make the CLI ineffective.
Use the default ip ssh server authenticate user command to remove the ip ssh server authenticate user command from effect. The IOS secure shell (SSH) server then starts using the ip ssh server algorithm authentication command.
Restrictions for X.509v3 Certificates for SSH Authentication
-
The X.509v3 Certificates for SSH Authentication feature implementation is applicable only on the Cisco IOS XE secure shell (SSH) server side.
-
The SSH server supports only the x509v3-ssh-rsa algorithm-based certificate for server and user authentication.
Information About X.509v3 Certificates for SSH Authentication
The following section provides information about digital certificates, and server and user authentication.
Digital Certificates
The validity of the authentication depends upon the strength of the linkage between the public signing key and the identity of the signer. Digital certificates in the X.509v3 format (RFC5280) are used to provide identity management. A chain of signatures by a trusted root certification authority and its intermediate certificate authorities binds a given public signing key to a given digital identity.
Public key infrastructure (PKI) trustpoint helps manage the digital certificates. The association between the certificate and the trustpoint helps track the certificate. The trustpoint contains information about the certificate authority (CA), different identity parameters, and the digital certificate. Multiple trustpoints can be created to associate with different certificates.
Server and User Authentication using X.509v3
For server authentication, the Cisco IOS XE secure shell (SSH) server sends its own certificate to the SSH client for verification. This server certificate is associated with the trustpoint configured in the server certificate profile (ssh-server-cert-profile-server configuration mode).
For user authentication, the SSH client sends the user's certificate to the SSH server for verification. The SSH server validates the incoming user certificate using public key infrastructure (PKI) trustpoints configured in the server certificate profile (ssh-server-cert-profile-user configuration mode).
By default, certificate-based authentication is enabled for server and user at the SSH server end.
How to Configure X.509v3 Certificates for SSH Authentication
The following section provides information about how to configure X.509v3 Certificates for SSH Authentication.
Configuring the SSH Server to Use Digital Certificates for Server Authentication
To configure the SSH server to use digital certificates for server authentication, perform this procedure:
Procedure
Command or Action | Purpose | |||
---|---|---|---|---|
Step 1 |
enable Example:
|
Enables privileged EXEC mode. Enter your password, if prompted. |
||
Step 2 |
configure terminal Example:
|
Enters global configuration mode. |
||
Step 3 |
ip ssh server algorithm hostkey {x509v3-ssh-rsa [ssh-rsa] | ssh-rsa [x509v3-ssh-rsa]} Example:
|
Defines the order of host key algorithms. Only the configured algorithm is negotiated with the secure shell (SSH) client.
|
||
Step 4 |
ip ssh server certificate profile Example:
|
Configures server certificate profile and user certificate profile and enters SSH certificate profile configuration mode. |
||
Step 5 |
server Example:
|
Configures server certificate profile and enters SSH server certificate profile server configuration mode. |
||
Step 6 |
trustpoint sign PKI-trustpoint-name Example:
|
Attaches the public key infrastructure (PKI) trustpoint to the server certificate profile. The SSH server uses the certificate associated with this PKI trustpoint for server authentication. |
||
Step 7 |
ocsp-response include Example:
|
(Optional) Sends the Online Certificate Status Protocol (OCSP) response or OCSP stapling along with the server certificate.
|
||
Step 8 |
end Example:
|
Exits SSH server certificate profile server configuration mode and returns to privileged EXEC mode. |
Configuring the SSH Server to Verify Digital Certificates for User Authentication
To configure the SSH Server to use digital certificates for user authentication, perform this procedure:
Procedure
Command or Action | Purpose | |||
---|---|---|---|---|
Step 1 |
enable Example:
|
Enables privileged EXEC mode. Enter your password, if prompted. |
||
Step 2 |
configure terminal Example:
|
Enters global configuration mode. |
||
Step 3 |
ip ssh server algorithm authentication {publickey | keyboard | password} Example:
|
Defines the order of user authentication algorithms. Only the configured algorithm is negotiated with the secure shell (SSH) client.
|
||
Step 4 |
ip ssh server algorithm publickey {x509v3-ssh-rsa [ssh-rsa] | ssh-rsa [x509v3-ssh-rsa]} Example:
|
Defines the order of public key algorithms. Only the configured algorithm is accepted by the SSH client for user authentication.
|
||
Step 5 |
ip ssh server certificate profile Example:
|
Configures server certificate profile and user certificate profile and enters SSH certificate profile configuration mode. |
||
Step 6 |
user Example:
|
Configures user certificate profile and enters SSH server certificate profile user configuration mode. |
||
Step 7 |
trustpoint verify PKI-trustpoint-name Example:
|
Configures the public key infrastructure (PKI) trustpoint that is used to verify the incoming user certificate.
|
||
Step 8 |
ocsp-response required Example:
|
(Optional) Mandates the presence of the Online Certificate Status Protocol (OCSP) response with the incoming user certificate.
|
||
Step 9 |
end Example:
|
Exits SSH server certificate profile user configuration mode and returns to privileged EXEC mode. |
Configuring Trustpoint Authentication and Creating Device Certificate
To configure trustpoint authentication and create device certificate, perform this procedure:
![]() Note |
We recommend that you use a new RSA keypair name for the newly configured PKI certificate. If you want to reuse an existing RSA keypair name (that is associated with an old certificate) for a new PKI certificate, do either of the following:
|
Procedure
Command or Action | Purpose | |||
---|---|---|---|---|
Step 1 |
enable Example:
|
Enables privileged EXEC mode. Enter your password, if prompted. |
||
Step 2 |
configure terminal Example:
|
Enters global configuration mode. |
||
Step 3 |
crypto pki trustpoint name Example:
|
Declares the trustpoint and a given name and enters ca-trustpoint configuration mode. |
||
Step 4 |
enrollment url url Example:
|
Specifies the URL of the CA on which your device should send certificate requests. |
||
Step 5 |
revocation-check none Example:
|
Specifies that certificate checking is ignored. |
||
Step 6 |
rsakeypair key-label [key-size [encryption-key-size]] Example:
|
(Optional) Specifies which key pair to associate with the certificate. A key pair with the key-label argument will be generated during enrollment if it does not already exist or if the auto-enroll regenerate command was issued. Specify the key-size argument for generating the key, and specify the encryption-key-size argument to request separate encryption, signature keys, and certificates. The key-size argument range is from 512 to 4096. The key-size and encryption-key-size must be the same size. Length of less than 2048 is not recommended.
|
||
Step 7 |
exit Example:
|
Exits ca-trustpoint configuration mode and returns to global configuration mode. |
||
Step 8 |
crypto pki authenticate name Example:
|
Retrieves the CA certificate and authenticates it. Check the certificate fingerprint if prompted.
|
||
Step 9 |
crypto pki enroll name Example:
|
Certificate request is sent to the certificate server and the server issues the ID or device certificate. You are prompted for enrollment information, such as whether to include the device FQDN and IP address in the certificate request. |
||
Step 10 |
show crypto pki certificates Example:
|
(Optional) Displays information about your certificates, including any rollover certificates. |
What to do next
For more information on how to install the certificate using other enrollment options, see Deploying RSA Keys Within a PKI.
Verifying Configuration for Server and User Authentication Using Digital Certificates
To verify configuration for server and user Authentication using digital certificates, perform this procedure:
Procedure
Command or Action | Purpose | |
---|---|---|
Step 1 |
enable Example:
|
Enables privileged EXEC mode. Enter your password, if prompted. |
Step 2 |
show ip ssh Example:
|
Displays the currently configured authentication methods. To confirm the use of certificate-based authentication, ensure that the x509v3-ssh-rsa algorithm is the configured host key algorithm. |
Configuration Examples for X.509v3 Certificates for SSH Authentication
The following section provides examples for user and server authentication using digital certificates.
Example: Configuring the SSH Server to Use Digital Certificates for Server Authentication
This example shows how to configure the SSH Server to use digital certificates for server authentication.
Device> enable
Device# configure terminal
Device(config)# ip ssh server algorithm hostkey x509v3-ssh-rsa
Device(config)# ip ssh server certificate profile
Device(ssh-server-cert-profile)# server
Device(ssh-server-cert-profile-server)# trustpoint sign trust1
Device(ssh-server-cert-profile-server)# end
Example: Configuring the SSH Server to Verify Digital Certificates for User Authentication
This example shows how to configure the SSH server to verify user's digital certificate for user authentication.
Device> enable
Device# configure terminal
Device(config)# ip ssh server algorithm authentication publickey
Device(config)# ip ssh server algorithm publickey x509v3-ssh-rsa
Device(config)# ip ssh server certificate profile
Device(ssh-server-cert-profile)# user
Device(ssh-server-cert-profile-user)# trustpoint verify trust2
Device(ssh-server-cert-profile-user)# end
Feature History for X.509v3 Certificates for SSH Authentication
This table provides release and related information for the features explained in this module.
These features are available in all the releases subsequent to the one they were introduced in, unless noted otherwise.
Release |
Feature |
Feature Information |
---|---|---|
Cisco IOS XE Gibraltar 16.11.1 |
X.509v3 Certificates for SSH Authentication |
The X.509v3 Certificates for SSH Authentication feature uses the X.509v3 digital certificates in server and user authentication at the SSH server side. |
Use the Cisco Feature Navigator to find information about platform and software image support. To access Cisco Feature Navigator, go to http://www.cisco.com/go/cfn.