Key and certificate generation

To generate a certificate and private key for your server:

  1. Set P4SSLDIR to a valid directory in a secure location. The directory specified by P4SSLDIR must be secure: owned by the same userid as the one generating the key pair, and it must not be readable by any other user.
  2. Optionally, create a file named config.txt in your P4SSLDIR directory before running p4d -Gc, and format the file as follows:

    # C: Country Name - 2 letter code (default: US)
    C =
    
    # ST: State or Province Name - full name (default: CA)
    ST =
    
    # L: Locality or City Name (default: Alameda)
    L =
    
    # O: Organization or Company Name (default: Helix Autogen Cert)
    O =
    
    # OU = Organization Unit - division or unit
    OU =
    
    # CN: Common Name (usually the DNS name of the server)
    # (default: the current server's DNS name)
    CN =
    
    # EX: number of days from today for certificate expiration
    # (default: 730, that is, 2 years)
    EX =
    
    # UNITS: unit multiplier for expiration (defaults to "days")
    # Valid values: "secs", "mins", "hours"
    UNITS =
  3. Generate the certificate and key pair with the following command:

    p4d -Gc

    If P4SSLDIR (and optionally, config.txt) has been correctly configured, and if no existing private key or certificate is found, two files, named privatekey.txt and certificate.txt, are created in P4SSLDIR.

    If a config.txt file is not present, the following default values are assumed, and a certificate is created that expires in 730 days (two years, excluding leap years).

    C=US
    ST=CA
    L=Alameda
    O=Helix Autogen Cert
    OU=
    CN=the-DNS-name-of-your-server
    EX=730
    UNITS=days
  4. Generate a fingerprint for your server’s key and certificate pair.

    p4d -Gf

    This command displays the fingerprint of the server’s public key, and then exits.

    Fingerprint: CA:BE:5B:77:14:1B:2E:97:F0:5F:31:6E:33:6F:0E:1A:E9:DA:EF:E2

    Record your server’s fingerprint for your own records and communicate it to your users via an out-of-band communications channel.

    If a Helix server application reports a different fingerprint (and you have not recently installed a new certificate and key pair), your users should consider such changes as evidence of a potential man-in-the-middle threat.

Note

Because Helix server can use self-signed certificates, you may also use third-party tools such as OpenSSL or PuTTY to generate the key pairs, or supply your own key pair. The p4d -Gf command accepts user-supplied credentials.

If you are supplying your own key, your privatekey.txt and certificate.txt files in P4SSLDIR must be PEM-encoded, with the private key file stripped of passphrase protection.

Whether you supply your own key and certificate pair or generate one with p4d -Gc, it is imperative that these files are stored in a secure location that is readable only by the p4d binary.