CLI cookbook: replacing the HTTPS (HTTP secure) certificate

This topic explains how to replace the HTTPS (HTTP Secure) certificate used by the Delphix Virtualization Engine. There are two methods of replacing the certificate. The key difference between the two is whether Delphix or the user is providing the key pair (public and private key).

Delphix provided key pair

Use the following instructions to provide an HTTPS certificate chain for a key pair created by the Delphix Engine. Once the key pair is created users can download a Certificate Signing Request (CSR) to generate a signed certificate from the CA of their choice. This is done using the "create" operation in the "/service/tls/csr" API as seen below when using the CLI.

CODE

hostname.domainname> service tls csr
hostname.domainname service tls csr> create
hostname.domainname service tls csr create *> ls
Properties
   type: CertificateSigningRequestCreateParameters
   dname:
       type: X500DistinguishedNameComposite
       dname: (required)
  :
       type: EndEntityHttps
   forceReplace: false
   keyPair:
       type: RsaKeyPair
       keySize: 2048
       signatureAlgorithm: SHA256withRSA

The first key property is the dname. This will be used as the subject name of the CSR and resulting X.509 certificate unless it is changed when the certificate is signed. Delphix supports two different formats for dname:

a composite string
a list of fields

Use the composite string as follows:

CODE

hostname.domainname service tls csr create *> set dname.dname="CN=Delphix CA, O=Delphix, C=US"
hostname.domainname service tls csr create *> ls
Properties
   type: CertificateSigningRequestCreateParameters
   dname:
       type: X500DistinguishedNameComposite (*)
       dname: CN=Delphix CA, O=Delphix, C=US (*)

Use the list of field formats as follows:

CODE

hostname.domainname service tls csr create *> set dname.type=X500DistinguishedNameFields
hostname.domainname service tls csr create *> ls
Properties
   type: CertificateSigningRequestCreateParameters
   dname:
       type: X500DistinguishedNameFields (*)
       city: (unset)
       commonName: Delphix CA (*)
       country: US (*)
       organization: Delphix (*)
       organizationUnit: (unset)
       stateRegion: (unset)

The only required field is the commonName (CN).

The only currently supported type for endEntity is EndEntityHttps.

The next property is forceReplace. By default, this is false and means Delphix will not replace the active key pair and certificate with the newly generated keypair and self-signed certificate. If the user wants to replace the active key pair right away before the signed certificate has been created this can be set to true.

The final property keyPair impacts the generated key pair. When creating a new key pair the engine supports two algorithms:

RSA - The supported signature algorithms are SHA256withRSA, SHA384withRSA, and SHA512withRSA . The valid key sizes range from 2048 to 4096.
ECDSA - The supported signature algorithms are SHA256withECDSA, SHA384withECDSA, and SHA512withECDSA. The valid key sizes range from 256 to 571

Once the create operation has completed you can get the CSR in PEM format by selecting the CSR object and looking at the requestInPem property:

CODE

requestInPem: -----BEGIN CERTIFICATE REQUEST-----
MIIBezCB0gIBADAhMR8wHQYDVQQDExZiYmFrZXIuZGMyLmRlbHBoaXguY29tMIGn
MBAGByqGSM49AgEGBSuBBAAmA4GSAAQBU5WY9+GkCTFvbGHTNJDb/QM3t4YI/9S6
fhCJELx7SbJNti2n0l3mCePenyUuBY9m6BWvUQzlhawZG5YAJ9WdcM+IIPciiNsD
Xmw0eFH05z6yTLMnfBYYZKFbpu/dcK5V8WoltrIC7jTxg/k6jf/WeD+dmyIMQ0Z7
VmwnD6RsaAs7T5lajXkurwPfqQ5MnsmgADAKBggqhkjOPQQDAwOBlwAwgZMCSAGM
quqcnIAxIRDxQ+BzzSywNtozn5ihtfFxtTF/EW/ARBib2l9hq0pwHrIinnLvjW9u
avpAH1pkWHx1w0/O6W6DCZAPIIL3ugJHKsScJqsvaeZzVqJVfQt8g42cL9hKc7ic
HLhuAyMGQOXrEdLbOxtOH6SiExnyEv2Y9LHHYYgRafgGzOoA5tx+mrkr9J+zm8Y=
-----END CERTIFICATE REQUEST-----

Once the CSR has been signed and turned into an X.509 Certificate you can replace the certificate using the "service/tls/endEntityCertificate" API. To replace using the CSR method begin by setting the correct type of replace parameters as seen below:

CODE

hostname.domainname service tls endEntityCertificate> replace
hostname.domainname service tls endEntityCertificate replace *> set type=EndEntityCertificateReplaceChainParameters
hostname.domainname service tls endEntityCertificate replace *> ls
Properties
    type: EndEntityCertificateReplaceChainParameters
    chain:
        type: PemCertificateChain
        chain: (required)
    endEntity:
        type: EndEntityHttps

The "chain" property must contain a list of the entire trust chain from the newly generated end-entity certificate to the root CA.

The CLI might not always interpret newline characters in PEM certificates correctly. Therefore, it is highly recommended to find and replace all newlines ('\n') with an empty string ('') prior to pasting the PEM certificate into the CLI.

To do this in the CLI first run:

CODE

hostname.domainname service tls endEntityCertificate replace *> edit chain.chain
Then `add` and `set contents` to the PEM certificate for each certificate in the chain.
hostname.domainname service tls endEntityCertificate replace chain.chain *> add

When adding multiple certificates, use the command back after each add. After the final add, enter back and then commit.

The order in which the PEM certificates are added to the list does not matter.

Customer provided key pair

This section describes the steps to take if you are replacing the HTTPS with your own key pair and certificate.

To start, you need to add the key pair and full certificate chain as an entry in a file in JKS or PKCS #12 format.

Then, send a file upload request to the following endpoint:

CODE

hostname.domainname service tls endEntityCertificate requestKeyPairAndCertChainUpload *> ls
Properties
   type: CertificateUploadParameters
   alias: alias_in_keystore (*)
   keypass: (unset)
   keystoreType: JKS
   storepass: ******** (*)
hostname.domainname service tls endEntityCertificate requestKeyPairAndCertChainUpload *> commit 
   type: FileUploadResult
   token: 8f4361c5-019c-4fee-9306-b7c85e977cf4
   url: /resources/json/delphix/data/upload

The alias field is where the key pair and certificate is saved in your JKS or PKCS #12 store.

The keypass field is the password for the given alias’ key. If not set, it uses the keystore's password.

The storepass field is the keystore’s password.

Then, establish a session from the host with the keystore to the Delphix Engine. Choose the location of the cookies, and determine the API version (command example uses 1.9.2):

CODE

curl -c <path/to/cookies> -X POST --data '{ "type": "APISession", "version": { "type": "APIVersion", "major": 1, "minor": 9, "micro": 2 } }' -H "Content-Type: application/json" http://<delphix_engine_url>/resources/json/delphix/session

Login to the Delphix Engine using the established session as a domain or system admin:

CODE

curl -b <path/to/cookies> -c <path/to/cookies> -X POST --data '{ "type": "LoginRequest", "username": "sysadmin", "password": "sysadmin" }' -H "Content-Type: application/json" http://<delphix_engine_url>/resources/json/delphix/login

Send the file upload request with the location of your keystore and token from above:

CODE

curl -b <path/to/cookies> -X POST -F "file=@<path/to/keystore>" -F "token=8f4361c5-019c-4fee-9306-b7c85e977cf4" http://<delphix_engine_url>/resources/json/delphix/data/upload

You can now replace the HTTPS end-entity certificate with the keystore you have uploaded, identified by the token:

CODE

hostname.domainname service tls endEntityCertificate replace *> set type=EndEntityCertificateReplaceKeystoreParameters
hostname.domainname service tls endEntityCertificate replace *> set token=8f4361c5-019c-4fee-9306-b7c85e977cf4
hostname.domainname service tls endEntityCertificate replace *> ls
Properties
   type: EndEntityCertificateReplaceKeystoreParameters (*)
   endEntity:
       type: EndEntityHttps
   token: b0e889ff-847a-4d7d-bd17-c1292ddbb63e (*)
hostname.domainname service tls endEntityCertificate replace *> commit