Key Management: Certificates
Catalog id: resource.kms.certificates
Public certificate material associated with a tenant's keys. A certificate reference is a tenant-scoped record saying "this public certificate belongs to that key in that provider". It never carries a private key, and registering one neither creates key material nor transfers lifecycle ownership away from the provider.
Audience: tenant administrator or an application developer integrating signing.
Guides: Keys and DID, Azure KMS and external keys.
Two sources, and which providers offer them
The source field decides where the public material comes from, and it is the field that determines
whether an operation works at all on your provider.
stored_public_material carries the certificate bytes in the request. This is the
bring-your-own-certificate case: an external CA issues a certificate for a key that stays in Azure or
AWS, and you hand EDK the public chain. EDK checks that the chain is ordered leaf to root with each
issuer directly above its subject, resolves the linked key through the provider, checks that the leaf
public key matches that key, and stores the chain in the tenant reference index. Because the material
arrives in the request, this needs no certificate API from the provider and works against any of them,
including AWS KMS.
The binding to the cloud key is re-checked on every read, not only at registration. A stored chain whose linked key has since been rotated in the backend is refused rather than served.
provider_native references a certificate object the provider already holds. EDK reads the leaf
through the provider on every request, so the provider has to expose a non-destructive certificate
read. The console offers this source only when the selected provider reports GET_CERTIFICATE, and
it does not infer support from the provider merely being AWS, Azure or software, nor from public-key
resolution or a general X.509 flag.
A provider read returns one certificate. No cloud KMS publishes the issuers above a leaf as public
data: Key Vault's GetCertificate returns the leaf cer, and the only Azure response that carries
more is the certificate's secret, which is a PKCS#12 blob containing the private key. EDK does not
read that, and it does not follow certificate AIA URLs either, since that would open an outbound
network path outside the provider API. So when a key_certificate_chain uses provider_native, the
leaf comes from the provider and the issuers above it come from the trusted certificates the tenant
has already registered, matched by issuer name. The leaf is re-read from Azure on every request and
checked against what was registered, so a certificate deleted or replaced in Key Vault is caught at
read time instead of being served from a stored copy. That check is strict: a renewed certificate is
a different certificate, and the read is refused until you register the new one. The chain above the
leaf is assembled fresh each time, so adding a trusted certificate takes effect without touching the
reference.
If no registered trusted certificate issues the leaf, the read fails rather than returning a
one-element chain. A truncated chain is worse than an error, because it fails later at whatever
verifier consumes the x5chain, far from the registration that caused it.
AWS KMS has no certificate object API at all: AWS Certificate Manager and AWS Private CA are separate
services, not KMS certificate stores. A certificate linked to an AWS KMS key therefore uses
stored_public_material, which is the bring-your-own-certificate path described below.
Which leaves this as the practical matrix:
| Software | AWS KMS | Azure Key Vault | |
|---|---|---|---|
stored_public_material registration | yes | yes | yes |
provider_native leaf | no | no | only where the certificate client is configured |
provider_native chain, completed from the trust store | no | no | only where the certificate client is configured |
| Register an existing key (BYOK) | no | yes | yes |
The last row runs the other way from the rest, and it is worth noting before designing around it.
Registering a reference to a key that already exists is a cloud capability: AWS and Azure both report
REGISTER_KEY_REFERENCE, and the software provider does not report it at all. Certificates go with
the software provider; existing-key registration does not.
Every explicitly registered certificate is externally_managed. That records a reference and leaves
the provider owning the object.
Registering and reading
- Admin Console
- Request
- Response
- Try it
Resources > Key Management > Certificates, then Register certificate. Pick the provider and the certificate kind, then the source the provider supports.
kind and source are independent choices. A key_certificate_chain is bound to a key and needs
linkedKeyAlias or linkedKeyKid; a trusted_certificate is a trust anchor and must not carry
either field.
For stored public material, supply the chain leaf to root as Base64 DER. The console accepts a PEM chain in the dialog and normalises it to Base64 DER before submitting; over REST, PEM text, concatenated unframed DER and private material are all rejected.
Choosing Key certificate chain as the kind reveals the linked key fields. One of Linked key alias or Linked key kid identifies the key the leaf must certify, and the dialog rejects a
submission that carries both or neither.
The public-key check is the part worth understanding. EDK converts the leaf certificate's public key and the linked provider key to canonical SubjectPublicKeyInfo and compares the bytes. A mismatch is rejected with a key identity error rather than stored, so a chain registered against the wrong key fails here instead of at the first signature a verifier checks.
The prerequisites are checked before any of that: the provider must already be configured, active and authorized for the tenant, and the linked key must be resolvable through that same provider.
- Admin Console
- Request
- Response
- Try it
The list covers the authenticated tenant's reference index only. It never enumerates a cloud provider's certificate inventory, which is why a certificate sitting in your vault does not appear here until someone registers it.
Filter with providerId, kind or source when the index grows past one screen.
Read one reference
GET/api/kms/v1/certificate-references/00000000-0000-4000-8000-000000000000200 OK- Admin Console
- Request
- Response
- Try it
The projection carries the reference id, alias, provider, optional provider certificate id, kind, source, control mode, origin, the linked key reference id and alias, and the public fingerprints.
It deliberately carries no certificate bytes, no tenant storage internals, no raw locators, no permits and no provider credentials. Use it to confirm the linkage; use the chain read below when you need the material itself.
- Admin Console
- Request
- Response
- Try it
For stored public material this comes from the reference index. For a provider-native reference the read delegates to the provider every time, so a certificate rotated in the vault shows up here without re-registering, while a revoked provider credential makes the read fail rather than serving a stale copy.
The certificates array is ordered leaf to root.
Delete a reference
DELETE/api/kms/v1/certificate-chains/customer-tenant-signing-chain204 No Content- Admin Console
- Request
- Response
- Try it
For an externally_managed reference, delete removes the EDK record and nothing else. The provider's
certificate is untouched, and repeating the delete, including after a restart, stays local and never
falls through to provider deletion.
Platform-managed certificates keep their existing provider-deletion behaviour. What decides is the reference's control mode, not whether it happens to hold certificate bytes.
Deleting a linked key reference does not cascade to certificate references. A certificate reference remains historical public verification metadata and keeps resolving its material according to its source.
Full schema: KMS API.
Certificate metadata on a key is not a certificate reference
A public JWK from a provider may carry x5c, x5t and x5t#S256. Those are public key metadata:
x5c entries are padded standard Base64 DER, and the two thumbprints are unpadded Base64url over the
DER.
Their presence does not create a certificate-management record, does not register anything, and does
not put a row in the list above. x5u is excluded because it is a remote locator, and a DID
verification method omits the provider kid while keeping the three certificate members.
What is stored
EDK keeps the provider id, the tenant-local alias, the optional provider certificate id, the source,
the lifecycle mode, the linked key reference, the fingerprints, and the public DER chain when the
source is stored_public_material. Typed provider leases enforce tenant authorization before any
provider inspection or certificate use.
Existing platform-managed certificate and key rows keep their provider-deletion behaviour through
migration. Migration does not guess which historical rows were externally provisioned, so a row
becomes externally_managed only through an explicit registration.
Related
Providers, Keys, Keys and DID guide, Azure KMS and external keys