Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 Server Administration Documentation | 2025.2

# 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/TLS-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 P4 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 P4 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.

- (Optional) Test whether your end user can connect by running the commands at Permissions on the public and private keys.

Communicate the 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),

1. Put the server certificate and any intermediary certificates into the `certificate.txt` file.

2. Make sure that the server certificate is first, before any intermediary certificates.

3. 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/TLS connections that do not require P4TRUST in the P4 CLI Reference.

### Wildcard certificates and certificates with the Subject Alternative Name field

Any client application using the P4 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, P4 Broker, P4 API for PHP 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/TLS handshake succeeds. The SSL/TLS handshake includes certificate validation.

### Permissions on the public and private keys

To verify that the permissions are correctly set on the public and private keys:

1. `chmod 700 P4SSLDIR` or `chmod 500 SSLDIR`

2. `cd P4SSLDIR`

3. `chmod 600 CERT-FILE`

4. `chmod 600 PRIVATE-KEY`

5. Restart the server.

6. Test connectivity with these two commands:

       p4 -p ssl:P4PORT trust -fy

       p4 -p ssl:P4PORT info

### To allow connection use the 'p4 trust' command

If you run a command similar to:

     p4 -p ssl:maria:2222 users

and the output is similar to:

    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. P4V 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 run a command similar to:

    p4 -p ssl:maria:2222 users

and the output is similar to:

Copy

    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

If you run a command similar to:

     p4 -p ssl:maria:2222 users

and the output is similar to:

Copy

    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.

Your search for returned results