PrivX Authorizer issues access certificates using its own CA, which is self-signed by default. For production deployments we recommend replacing the Authorizer CA with one signed by a trusted certificate authority.

📘

Note

The following procedures use ​<key_id>, ​<cert_id>​​ and <ag> to substitute for PrivX-CA-key ID, the Authorizer-certificate ID, and the access-group ID/name respectively. Be careful not to mix them up.

Preferred method

Generate a Certificate-Signing Request (CSR)

Gain root terminal access to a PrivX server and generate a CSR for the access group:

/opt/privx/bin/cert-tool -command create -access-group <ag> \
	-csr -csrout privx-im-ca.csr

Replace <ag> with the access group's name or ID. If the access group has multiple CA keys, you will be prompted to select one. You can also use the -latest option to automatically select the CA key with the latest certificate expiration date.

This writes the CSR to the file ​privx-im-ca.csr​​ in your current working directory.

Sign the CSR with a trusted CA

Request a trusted CA to sign the CSR with the following constraints:

• ​​keyUsage​ must include: ​Digital Signature, Key Agreement, Certificate Sign, CRL Sign​​

• ​​basicConstraints​ must be: ​CA:TRUE, pathlen:0​​

Optionally the CA may attach name constraints. See X.509 Certificate Name Constraints for more information.

After the trusted CA provides you with the signed certificate, you may verify its constraints with:

openssl x509 -text -noout -in privx-im-ca.crt

Replace ​privx-im-ca.crt with the path to the signed certificate.

Replace the unsigned certificate

Run cert-tool again to replace the certificate.

/opt/privx/bin/cert-tool -command replace -nv -access-group <ag> -in privx-im-ca.crt

Replace <ag> with the access group's name or ID and privx-im-ca.crt with the filepath to the signed certificate. The command will find the matching CA key and ask for confirmation.

On all PrivX servers, restart the PrivX services to apply the changes:

systemctl restart privx

Subsequent certificates issued by PrivX are signed using the new trusted Authorizer CA certificate.

Manual method

The manual method involves more steps but can also be used for signing certificates other than authorizer certificates.

Resolve the CA key ID

Find the CA key for which to generate a CSR. Keys can be listed with the following command:

/opt/privx/bin/keyvault-tool -nv list-asymmetric

Take note that the default access group's initially created CA key may be stored in the filesystem-based keyvault as "PrivX CA Key". To list keys in the filesystem-based keyvault, omit the -nv flag.

Generate a Certificate-Signing Request (CSR)

Get the old certificate's subject field with the following command:

/opt/privx/bin/cert-tool -command list -short | grep <key_id> | cut -f3

Generate a CSR for the private key.

/opt/privx/bin/cert-tool -command create -type authorizer-ca \
	-subject <subject> -nv -key <key_id> -csr -csrout privx-im-ca.csr

Replace <key_id> with the CA key ID and <subject> with the output of the previous command. If replacing a certificate other than an authorizer certificate, change the -type option accordingly.

This creates the CSR in the file privx-im-ca.csr in your current working directory.

Sign the CSR with a trusted CA

Follow the instructions from the Preferred Method for this step.

Replace the unsigned certificate

Resolve the ID of the old certificate to be replaced. You can use the following command:

/opt/privx/bin/cert-tool -command list -short | grep <key_id> | cut -f4

Replace <key_id> with the CA key ID from the first step of this guide.

To replace the old certificate with the signed one, run the following command:

/opt/privx/bin/cert-tool -command replace -type authorizer-ca -nv \
   -id <cert_id> -in privx-im-ca.crt

Replace <cert_id> with the output of the previous command and change -type if necessary. Also omit -nv, if you omitted it previously in this guide.

cert-tool will verify that the new certificate is derived from the correct CA key. If this verification fails, the command will show a warning and ask for confirmation. In this case, decline and confirm that you have completed all the steps properly.

Finally, restart PrivX to apply the changes.

systemctl restart privx