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.

Finding Feature Information

Your software release may not support all the features documented in this module. For the latest caveats and feature information, see Bug Search Tool and the release notes for your platform and software release. To find information about the features documented in this module, and to see a list of the releases in which each feature is supported, see the feature information table.

Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/​go/​cfn. An account on Cisco.com is not required.

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 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 IOS secure shell (SSH) server side.

  • IOS SSH server supports only the x509v3-ssh-rsa algorithm based certificate for server and user authentication on the IOS SSH server side.

Information About X.509v3 Certificates for SSH 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 IOS 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 IOS 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 IOS SSH server end.

How to Configure X.509v3 Certificates for SSH Authentication

Configuring IOS SSH Server to Use Digital Certificates for Sever Authentication

SUMMARY STEPS

    1.    enable

    2.    configure terminal

    3.    ip ssh server algorithm hostkey {x509v3-ssh-rsa [ssh-rsa] | ssh-rsa [x509v3-ssh-rsa]}

    4.    ip ssh server certificate profile

    5.    server

    6.    trustpoint sign PKI-trustpoint-name

    7.    ocsp-response include

    8.    end


DETAILED STEPS
     Command or ActionPurpose
    Step 1 enable


    Example: 
    Device> enable
     

    Enables privileged EXEC mode.

    • Enter your password if prompted.

     
    Step 2 configure terminal


    Example: 
    Device# configure terminal
     

    Enters global configuration mode.

     
    Step 3 ip ssh server algorithm hostkey {x509v3-ssh-rsa [ssh-rsa] | ssh-rsa [x509v3-ssh-rsa]}


    Example: 
    Device(config)# ip ssh server algorithm hostkey x509v3-ssh-rsa
     

    Defines the order of host key algorithms. Only the configured algorithm is negotiated with the secure shell (SSH) client.

    Note   
    The IOS SSH server must have at least one configured host key algorithm:

    • ssh-rsa – public key based authentication

    • x509v3-ssh-rsa – certificate-based authentication

     
    Step 4 ip ssh server certificate profile


    Example: 
    Device(config)# ip ssh server certificate profile
     

    Configures server certificate profile and user certificate profile and enters SSH certificate profile configuration mode.

     
    Step 5 server


    Example: 
    Device(ssh-server-cert-profile)# server
     

    Configures server certificate profile and enters SSH server certificate profile server configuration mode.

     
    Step 6 trustpoint sign PKI-trustpoint-name


    Example: 
    Device(ssh-server-cert-profile-server)# trustpoint sign trust1
     

    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: 
    Device(ssh-server-cert-profile-server)# ocsp-response include
     

    (Optional) Sends the Online Certificate Status Protocol (OCSP) response or OCSP stapling along with the server certificate.

    Note   

    By default the “no” form of this command is configured and no OCSP response is sent along with the server certificate.

     
    Step 8 end


    Example: 
    Device(ssh-server-cert-profile-server)# end
     

    Exits SSH server certificate profile server configuration mode and enters privileged EXEC mode.

     

    Configuring IOS SSH Server to Verify User's Digital Certificate for User Authentication

    SUMMARY STEPS

      1.    enable

      2.    configure terminal

      3.    ip ssh server algorithm authentication {publickey | keyboard | password}

      4.    ip ssh server algorithm publickey {x509v3-ssh-rsa [ssh-rsa] | ssh-rsa [x509v3-ssh-rsa]}

      5.    ip ssh server certificate profile

      6.    user

      7.    trustpoint verify PKI-trustpoint-name

      8.    ocsp-response required

      9.    end


    DETAILED STEPS
       Command or ActionPurpose
      Step 1 enable


      Example: 
      Device> enable
       

      Enables privileged EXEC mode.

      • Enter your password if prompted.

       
      Step 2 configure terminal


      Example: 
      Device# configure terminal
       

      Enters global configuration mode.

       
      Step 3 ip ssh server algorithm authentication {publickey | keyboard | password}


      Example: 
      Device(config)# ip ssh server algorithm authentication publickey
       

      Defines the order of user authentication algorithms. Only the configured algorithm is negotiated with the secure shell (SSH) client.

      Note   

      The IOS SSH server must have at least one configured user authentication algorithm.

      Note   

      To use the certificate method for user authentication, the publickey keyword must be configured.

      Note   

      The ip ssh server algorithm authentication command replaces the ip ssh server authenticate user command.

       
      Step 4 ip ssh server algorithm publickey {x509v3-ssh-rsa [ssh-rsa] | ssh-rsa [x509v3-ssh-rsa]}


      Example: 
      Device(config)# ip ssh server algorithm publickey x509v3-ssh-rsa
       

      Defines the order of public key algorithms. Only the configured algorithm is accepted by the SSH client for user authentication.

      Note   
      The IOS SSH client must have at least one configured public key algorithm:

      • ssh-rsa – public-key-based authentication

      • x509v3-ssh-rsa – certificate-based authentication

       
      Step 5 ip ssh server certificate profile


      Example: 
      Device(config)# ip ssh server certificate profile
       

      Configures server certificate profile and user certificate profile and enters SSH certificate profile configuration mode.

       
      Step 6 user


      Example: 
      Device(ssh-server-cert-profile)# user
       

      Configures user certificate profile and enters SSH server certificate profile user configuration mode.

       
      Step 7 trustpoint verify PKI-trustpoint-name


      Example: 
      Device(ssh-server-cert-profile-user)# trustpoint verify trust2
       

      Configures the public key infrastructure (PKI) trustpoint that is used to verify the incoming user certificate.

      Note   

      Configure multiple trustpoints by executing the same command multiple times. A maximum of 10 trustpoints can be configured.

       
      Step 8 ocsp-response required


      Example: 
      Device(ssh-server-cert-profile-user)# ocsp-response required
       

      (Optional) Mandates the presence of the Online Certificate Status Protocol (OCSP) response with the incoming user certificate.

      Note   

      By default the “no” form of this command is configured and the user certificate is accepted without an OCSP response.

       
      Step 9 end


      Example: 
      Device(ssh-server-cert-profile-user)# end
       

      Exits SSH server certificate profile user configuration mode and enters privileged EXEC mode.

       

      Verifying Configuration for Server and User Authentication Using Digital Certificates

      SUMMARY STEPS

        1.    enable

        2.    show ip ssh


      DETAILED STEPS
        Step 1   enable

        Enables privileged EXEC mode.

        • Enter your password if prompted.



        Example: 
        Device> enable
        Step 2   show ip ssh

        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.



        Example: 
        Device# show ip ssh

SSH Enabled - version 1.99
Authentication methods:publickey,keyboard-interactive,password
Authentication Publickey Algorithms:x509v3-ssh-rsa,ssh-rsa
Hostkey Algorithms:x509v3-ssh-rsa,ssh-rsa
Authentication timeout: 120 secs; Authentication retries: 3
Minimum expected Diffie Hellman key size : 1024 bits

        Configuration Examples for X.509v3 Certificates for SSH Authentication

        Example: Configuring IOS SSH Server to Use Digital Certificates for Sever 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)# exit

        Example: Configuring IOS 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

        Additional References for X.509v3 Certificates for SSH Authentication

        Related Documents

        Related Topic

        Document Title

        Cisco IOS commands

        Cisco IOS Master Command List, All Releases

        Security commands

        SSH authentication

        “Secure Shell-Configuring User Authentication Methods” chapter in Secure Shell Configuration Guide

        Public key infrastructure (PKI) trustpoint

        “Configuring and Managing a Cisco IOS Certificate Server for PKI Deployment” chapter in Public Key Infrastructure Configuration Guide

        Technical Assistance

        Description

        Link

        The Cisco Support website provides extensive online resources, including documentation and tools for troubleshooting and resolving technical issues with Cisco products and technologies.

        To receive security and technical information about your products, you can subscribe to various services, such as the Product Alert Tool (accessed from Field Notices), the Cisco Technical Services Newsletter, and Really Simple Syndication (RSS) Feeds.

        Access to most tools on the Cisco Support website requires a Cisco.com user ID and password.

        http:/​/​www.cisco.com/​cisco/​web/​support/​index.html

        Feature Information for X.509v3 Certificates for SSH Authentication

        The following table provides release information about the feature or features described in this module. This table lists only the software release that introduced support for a given feature in a given software release train. Unless noted otherwise, subsequent releases of that software release train also support that feature.

        Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to www.cisco.com/​go/​cfn. An account on Cisco.com is not required.
        Table 1 Feature Information for X.509v3 Certificates for SSH Authentication

        Feature Name

        Releases

        Feature Information

        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.

        The following commands were introduced or modified: ip ssh server algorithm hostkey, ip ssh server algorithm authentication, and ip ssh server certificate profile.