mirror of
https://github.com/hanzoai/kms.git
synced 2026-10-17 11:18:16 +00:00
zeekay
0ebffbd529
- Fix 381 files where branding script corrupted variable names (e.g. isHanzo KMSTemplate -> isKmsTemplate) - Rebrand from "Hanzo KMS" to just "KMS" for white-label support (allows Lux KMS, Hanzo KMS, etc. via configuration) - 856 files, purely string replacements, no logic changes
72 lines
3.7 KiB
Plaintext
72 lines
3.7 KiB
Plaintext
---
|
|
title: "Certificate Enrollment via EST"
|
|
sidebarTitle: "EST"
|
|
---
|
|
|
|
## Concept
|
|
|
|
The EST enrollment method allows you to issue and manage certificates against a specific [certificate profile](/documentation/platform/pki/certificates/profiles) using the [EST protocol](https://en.wikipedia.org/wiki/Enrollment_over_Secure_Transport).
|
|
This method is suitable for environments requiring strong authentication and encrypted communication, such as in IoT, enterprise networks, and secure web services.
|
|
|
|
KMS's EST service is based on [RFC 7030](https://datatracker.ietf.org/doc/html/rfc7030) and implements the following endpoints:
|
|
|
|
- **cacerts** - provides the necessary CA chain for the client to validate certificates issued by the CA.
|
|
- **simpleenroll** - allows an EST client to request a new certificate from KMS's EST server
|
|
- **simplereenroll** - similar to the /simpleenroll endpoint but is used for renewing an existing certificate.
|
|
|
|
These EST endpoints are exposed on port 8443 under the .well-known/est path
|
|
and structured under `https://kms.hanzo.ai:8443/.well-known/est/{profile_id}/...`
|
|
|
|
## Prerequisites
|
|
|
|
- Your client devices need to have a bootstrap/pre-installed certificate.
|
|
- Your client devices must trust the server certificates used by KMS's EST server. If the devices are new or lack existing trust configurations, you need to manually establish trust for the appropriate certificates.
|
|
|
|
<Note>
|
|
For KMS Cloud users, the devices must be configured to trust the [Amazon
|
|
root CA certificates](https://www.amazontrust.com/repository).
|
|
</Note>
|
|
|
|
## Guide to Certificate Enrollment via EST
|
|
|
|
In the following steps, we explore how to issue a X.509 certificate using the EST enrollment method.
|
|
|
|
<Steps>
|
|
<Step title="Create a certificate profile in KMS">
|
|
Create a [certificate
|
|
profile](/documentation/platform/pki/certificates/profiles) with **EST**
|
|
selected as the enrollment method and fill in EST-specific configuration.
|
|
|
|
|
|
|
|
Here's some guidance on each EST-specific configuration field:
|
|
|
|
- Disable Bootstrap CA Validation: Enable this if your devices are not configured with a bootstrap certificate.
|
|
- EST Passphrase: This is also used to authenticate your devices with KMS's EST server. When configuring the clients, use the value defined here as the EST password.
|
|
- CA Chain Certificate: This is the certificate chain used to validate your devices' manufacturing/pre-installed certificates. This will be used to authenticate your devices with KMS's EST server.
|
|
|
|
</Step>
|
|
<Step title="Obtain the EST label">
|
|
Once the EST enrollment method configuration is complete, you can use the ID of the associated certificate profile
|
|
`profile_id` as the EST label when enrolling EST clients with KMS.
|
|
|
|
|
|
|
|
The complete URL structure of the supported EST endpoints may look like the following:
|
|
|
|
- https://kms.hanzo.ai:8443/.well-known/est/{profile_id}/cacerts
|
|
- https://kms.hanzo.ai:8443/.well-known/est/{profile_id}/simpleenroll
|
|
- https://kms.hanzo.ai:8443/.well-known/est/{profile_id}/simplereenroll
|
|
</Step>
|
|
|
|
<Step title="Configure EST clients">
|
|
To use the EST passphrase in your clients, configure it as the EST password. The EST username can be set to any arbitrary value.
|
|
Use the appropriate client certificates for invoking the EST endpoints.
|
|
- For `simpleenroll`, use the bootstrapped/manufacturer client certificate.
|
|
- For `simplereenroll`, use a valid EST-issued client certificate.
|
|
When configuring the PKCS#12 objects for the client certificates, only include the leaf certificate and the private key.
|
|
|
|
</Step>
|
|
|
|
</Steps>
|