Azure key vault: Merge certificate

Question

I'm trying to understand the merge API of Azure Key vault. What is the use case of it? https://learn.microsoft.com/en-us/rest/api/keyvault/mergecertificate/mergecertificate

The doc says

The MergeCertificate operation performs the merging of a certificate or certificate chain with a key pair currently available in the service. 

One use case I understand here is to create CSR in key vault, get it signed by your CA and then merge it to the CSR in key vault to complete the certificate creation.

But what do we mean by merging a certificate chain? Does it mean the certificate chain that was used to sign the CSR?

Answer 1

Yes, merging the chain means that the whole chain, which starts with the certificate that is generated for CSR.

So, to have a local test using OpenSSL 1.1.1

1. Generate CA

openssl req -new -newkey rsa:2048 -nodes -out ca.csr -keyout ca.key -extensions v3_ca
openssl x509 -signkey ca.key -days 365 -req -in ca.csr -set_serial 01 -out ca.crt

2. Generate Intermediate CA

openssl req -new -newkey rsa:2048 -nodes -out inter.csr -keyout inter.key -addext basicConstraints=CA:TRUE
openssl x509 -CA ca.crt -CAkey ca.key -days 365 -req -in inter.csr -set_serial 02 -out inter.crt

3. Generate request using Azure KeyVault and download CSR to test.csr file. Assuming using keyvault test-kv and certificate with name test.

4. Sign the request using intermediate CA

openssl x509 -CA inter.crt -CAkey inter.key -days 365 -req -in test.csr -set_serial 03 -out test.crt

5. Bundle certificate together with intermediate and CA to PEM format (just concatenate those text files in proper order)

cat test.crt inter.crt ca.crt > test-chain.pem

6. Merge the certificate chain in Azure KeyVault

az keyvault certificate  pending merge --vault-name test-kv --name test --file test-chain.pem

---

Additional note about formats:
The certificate content type can be set to either PKCS12 or PEM upon creation in Azure KeyVault. As result merged certificate is exported/downloaded

• using PFX format for certificate created with PKCS12 content type
• using PEM format for certificate created with PEM content type

The format of the chain bundle for merging, however, does not depend on that content type. It only depends on the method that is used to perform the merge:

• az cli supports PEM format (with either single certificate or entire chain) and crt (which contains only one certificate, without the chain),
• Azure Portal UI allows to upload PEM, P7B and crt. But only merging P7B allows to preserve the chain. In case of merging PEM only the first certificate specified in PEM bundle is used (the others are ignored)
• Azure KeyVault REST api uses an array of base64-encoded certificates for representing a chain (https://learn.microsoft.com/en-us/azure/key-vault/certificates/create-certificate-scenarios#merge-when-a-pending-request-is-created---manual-certificate-creation)

The following command can be used to create a P7B file containing the chain:

openssl crl2pkcs7 -nocrl -certfile test.crt -out test.p7b -certfile inter.crt -certfile ca.crt

When certificate that was merged together with the chain is downloaded in PEM, it contains the whole chain already. When certificate is downloaded in PFX, to extract individual certificates the following command can be used to convert to PEM, containing only certificates (omitting the private key):

openssl pkcs12 -in downloaded-cert.pfx -nokeys -nodes -out chain.pem

Then chain.pem can be opened with text editor and individual certificates can be extracted to separate crt files