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 Core 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 Core Server, proxy, and broker process, and must also have their permissions set 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.

Communicate this fingerprint to your end users so they can 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.

Certificates from a Certificate Authority

If you have a server certificate issued by a trusted certificate authority (CA),

Put the server certificate and any intermediary certificates into the certificate.txt file.
Make sure that the server certificate is first, before any intermediary certificates.
Make sure each following intermediate certificate directly certifies the one preceding it.

The root certificate does not need to be included.

Trusted certificates do not require the P4TRUST mechanism. To learn more, see SSL connections that do not require P4TRUST in the Helix Core Command-Line (P4) Reference.

Wildcard certificates and certificates with the Subject Alternative Name field

Any client application using the Helix Core C/C++ API supports wildcard certificates and the subject alternative name field for certificate validation. This includes not only applications like the P4V Visual Client, but also any p4 product that is acting as a client, such as the p4 command-line client, P4Broker, P4PHP scripts, and a replica or edge P4D.

The wildcard specification must be in the certificate's Subject's Common Name (CN) field. Only one wildcard is supported and it must be in the left-most label. For example,

*.mycompany.com

The Subject Alternative Name (SAN) field is also checked for matching the hostname of P4PORT.

DNS and IP for SAN values are supported, but a wildcard DNS value is not supported.

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.

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.
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
...

The second CN in the message is the missing certificate. In this example, maria Root CA is missing.

If the missing certificate is an intermediate certificate, verify whether your certificate.txt contains all the intermediate certificates. For more detail on intermediates within the certificate.txt file, see Certificates from a Certificate Authority.

If the missing certificate is the root certificate, import the missing certificate into your trusted OS store. In this example, import the maria Root CA certificate. To learn more, see Trusted Certificates and Importing Certificates in the Perforce Knowledge Base.

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).

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
Obtain a new server certificate with a Subject Alternate name that includes "maria"
Use p4 trust.