Skip to main content

Key Manager Clients

This section describes commonly occurring issues related to command-line client usage and API client usage.

Most of the issues related to command-line client usage are caused by faulty configurations and certificate authentication. For more information about these topics, see the PrivX Key Manager Installation Manual.

Symptom: "400 Bad Request" error when using the command-line client​

  • If this error is displayed after all command-line client commands (excluding help commands), the issue may be caused by misconfigured client certificates on the Key Manager front end receiving the command-line client connections. To resolve this problem, ensure the following:

    • Ensure that the Key Manager front end is configured to support sufficiently long certificate chains: If you are using intermediate certificates, you must configure the Nginx web server to support longer certificate chains. This is done by specifying the ssl_verify_depth in the Nginx configuration file /etc/nginx/sites-available/sshmgr, similarly to the following:

      server {
          listen       443 ssl default_server;
          server_name  _;
          # Server certificate
          ssl_certificate      /etc/pki/tls/certs/ukmserver.crt;
          # Server private key
          ssl_certificate_key  /etc/pki/tls/private/ukmserver.key;
          # CA used for signing api client certificates
          ssl_client_certificate /etc/pki/tls/certs/ukmca.crt;
          ssl_verify_depth 5;
          ...
      }

      Save and close the file, then restart the Nginx service to apply the changes:

      # service nginx restart

      Test the client using any supported command (excluding help commands). If you still get the 400 Bad Request error, proceed to the following step.

    • Find the client-CA-certificate file. The location of the file is specified by the variable ssl_client_certificate in the Nginx configuration located at /etc/nginx/sites-available/sshmgr. By default, the client-CA-certificate file is located at /etc/pki/tls/certs/ukmca.crt on Red Hat and CentOS platforms. Ensure that the client-CA-certificate file contains the certificate chain of the CA that provided the client certificates. Note that if you are using different CAs for issuing the server certificate and the client certificates, then the client-CA-certificate file should contain a different certificate chain than the server-certificate file.

      Restart the nginx service to apply the changes. Once again, test the client using any supported command.

      For additional information about configuring server-side and client-side SSL authentication, refer to the PrivX Key Manager Installation Manual.

Symptom: "certificate verify failed" error when using the command-line client​

• The full error message looks similar to the following:

ERROR:ssh-mgr-client:: [Errno 1] _ssl.c:492:error:14090086:SSL
routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed ERROR
[Errno 1] _ssl.c:492: error:14090086:SSL
routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed

If this error is displayed after all command-line client commands (excluding help commands), the issue may be caused by the command-line client user account having the wrong certificates. To resolve this problem, ensure that the client certificates are configured correctly on the host where the command- line client is run.

For detailed instructions about setting up client certificates, see the command-line client installation instructions in the PrivX Key Manager Installation Manual.

Symptom: "/path/to/certificate is not readable" error when using the command-line client​

  • If this error is displayed after all command-line client commands (excluding help commands), the issue may be caused by faulty client-certificate configurations. To resolve this problem, ensure the following:

    • The required certificate files (client key, client certificate, and the certificate chain of the client- certificate CA) are owned by the user account that runs the command-line client. Also, the required certificate files must be readable for the owning user account.

    • The command-line client must be able to find the required certificate files. This can be accomplished by placing the required certificate files under ~/crt/ (where ~ is the path to the home directory of the owning user account). Alternatively, you can specify alternate locations by setting the following environment variables:

      • SSHMGR_CERT: Path of the client-certificate file.

      • SSHMGR_KEY: Path of the client-key file.

      • SSHMGR_CA: Path of the file containing the Key Manager Server root-CA certificate.

Symptom: API client commands fail due to invalid SSL certificates​

By default, the API client requires that the Key Manager front end it is connecting to provides valid SSL certificates. In situations where API client commands fail due to invalid certificates, you may solve the issue as follows:

  • If the Key Manager front end is set up with trusted certificates, make sure that the CA that issued the Key Manager front end certificate is trusted on the machine where you are using the API client. Please see the OS vendor documentation for instructions about configuring trusted CAs on your machine.

    Alternatively, you can try providing the CA certificate directly in the API client command, using the --ca-file-path option or the --ca-dir-path option (replace /path/to/ca.crt with the path to the CA-certificate file, replace /path/to/cadir with the path of the directory that contains the CA- certificate file):

    $ ssh-mgr-cli --ca-file-path /path/to/ca.crt <command>
    $ ssh-mgr-cli --ca-dir-path /path/to/cadir <command>

  • If the Key Manager front end uses self-signed certificates, you may allow connections using the -- insecure option:

    $ ssh-mgr-cli --insecure <command>

    You may also persistently disable certificate validation with the following command:

    $ ssh-mgr-cli client config request verify off
    note

    In production environments, we strongly recommend using trusted certificates for the Key Manager front end, in order to ensure the security of any data passed between the API client and the Key Manager front end.

Symptom: "403 Using external API not allowed" error when using an API client​

To connect to Key Manager using an user-agent, the connecting user must have the Connect through external API permission. Also ensure that the user's client is specified in the Settings→General→Frontend setting Allowed API clients.

You may give either full or partial name to satisfy this condition. For example, if the API client sends a User-Agent header that contains SomeCustomClient-0.1, you could add the word Custom to the list of Allowed API clients.

Symptom: error prevents running commands such as client login or client update using ssh-mgr-cli​

It is possible that the API definition file can not be refreshed. You may remove the existing definition file located in the following path:

/home/username/.config/ssh-mgr-cli/api_definitions/localhost-username/api_definition.json