Key and certificate management

When configured to accept SSL connections, all server processes (p4d, p4p, p4broker), require a valid certificate and key pair on startup. These files are stored in the directory specified by the P4SSLDIR environment variable. For an SSL-enabled server process to start, the following additional conditions must be met:

  • P4SSLDIR must be set to a valid directory.
  • The P4SSLDIR directory must be owned by the same userid as the one running the Helix Server, proxy, or broker process. The P4SSLDIR directory must not be readable by any other user. On UNIX, for example, the directory’s permissions must be set to 0700 (drwx------) or 0500 (dr-x------).

  • Two files, named privatekey.txt and certificate.txt, must exist in P4SSLDIR.

    These files correspond to the PEM-encoded private key and certificate used for the SSL connection. They must be owned by the userid that runs the Helix Server, proxy, and broker process, and must also have their permissions set such as to make them unreadable by other users. On UNIX, for example, the files' permissions must be set to 0600 (-rw-------) or 0400 (-r--------).

    You can supply your own private key and certificate, or you can use p4d -Gc to generate a self-signed key and certificate pair.

  • To generate a fingerprint from your server’s private key and certificate, run p4d -Gf . (P4SSLDIR must be configured with the correct file names and permissions, and the current date must be valid for the certificate.)

    After you have communicated this fingerprint to your end users, your end users can then compare the fingerprint the server offers with the fingerprint you have provided. If the two fingerprints match, users can use p4 trust to add the fingerprint to their P4TRUST files.

Tip

If you have a certificate chain, you can append any intermediary certificates into the certificate.txt file. For more information, see SSL connections that do not require P4TRUST in Helix Core Command-Line (P4) Reference.

Troubleshooting certificate validation errors

You can test at the P4 command line whether the SSL handshake succeeds. The SSL handshake includes certificate validation.

To allow connection use the 'p4 trust' command

If you see something that resembles:

$ p4 -p ssl:maria:2222 users
The authenticity of '10.1.10.1:2222' can't be established,
...
To allow connection use the 'p4 trust' command.

  1. Make sure that your client is at release 2021.2 or later, so that chain certification is supported. The P4V visual client requires release 2021.4 or later.

  2. Use p4 trust if the certificate is self-signed. To determine whether a self-signed certificate is involved, capture ssl=4 trace output (see Command Tracing), and examine the Common Name (CN) values. If the "CN=" value of "subject" and "issuer" are the same, the certificate is self-signed.

Certificate chain failed validation

If you see something that resembles:

$ p4 -p ssl:maria:2222 users
The authenticity of '10.1.10.1:2222' can't be established,
...
To allow connection use the 'p4 trust' command.
Certificate chain failed validation.
... unable to get local issuer certificate, depth=1 CN = maria Root CA Intermediate issuer= CN = maria Root CA
...

Import the missing certificate into your trusted OS store. In this example, import "maria Root CA". See the Support Knowledgebase article, Trusted Certificates and Importing Certificates.

Certificate's subject doesn't match P4PORT

$ p4 -p ssl:maria:2222 users
The authenticity of '10.1.10.1:2222' can't be established,
...
To allow connection use the 'p4 trust' command.
...
Certificate's subject (maria.company.com) doesn't match P4PORT (maria).

  1. Alter your P4PORT by using the certificate subject's CN in the certificate for the P4PORT's host value. For example, p4 -p ssl:maria.company.com:2222

  2. Obtain a new server certificate with a Subject Alternate name that includes "maria"

  3. Use p4 trust.