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.
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:
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:
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:
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:
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:
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 that the PEM certificates are added to the list does not matter.
Finally, once the certificate chain has been successfully replaced you will need to restart the Delphix Engine.
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:
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.
3. 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):
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
4. Login to the Delphix Engine using the established session as a domain or system admin:
curl -b <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
5. Send the file upload request with the location of your keystore and token from above:
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
6. You can now replace the HTTPS end-entity certificate with the keystore you have uploaded, identified by the token:
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
7. Once the key pair and certificate chain has been successfully replaced you will need to restart the Delphix Engine for the changes to take effect.