Search the Community

Many organizations rely on X.509 public key infrastructure (PKI) certificates to protect their services and workloads. This standard supports a wide range of configurable fields and extensions, making it highly flexible and allowing for a high degree of customization. Many of these fields are relevant for a large number of use cases and are natively supported by HashiCorp Vault. However, due to the sheer number of fields defined in the X.509 standard, there were cases where a field was not implemented in Vault and could not be validated by Vault. To address these use cases, we have introduced support for Certificate Issuance External Policy Services (CIEPS) in Vault Enterprise 1.15. Issuing a PKI certificate Issuing a PKI certificate with Vault is simple. Once a certificate authority (CA) has been established and configured with a role, authenticated clients can submit certificate issuance or signing requests against that role. The role defines the allowed values in the certificate and compares the request against those values. If the values match, a certificate is issued or signed. If they do not match, the request is rejected. This workflow is suitable for all requests that include fields and extensions natively supported by Vault. In scenarios where customers require certificates to be issued with custom fields, Vault offers the option to use the sign-verbatim method, described in the next section. Challenges with sign-verbatim requests Issuing or signing a certificate with the sign-verbatim method allows the request to use arbitrary fields and extensions that are not supported with the role-based process outlined above. However, because Vault does not validate those custom fields, the use of sign-verbatim requires a different validation approach. HashiCorp Sentinel is a policy as code framework that allows the definition of fine-grained, logic-based policies. It can be used to provide additional validation for requests made to endpoints and entities in Vault. When defined for a particular endpoint, the Sentinel policy evaluates all requests to that endpoint and determines whether to allow or reject them based on the result of the policy check. With Sentinel, specific fields can be denied or required. When fields are defined as required in the Sentinel policy, the client has to know and specify all required fields in the request. Missing fields would lead to the request being denied, and resolving the issue requires clients to have knowledge of very specific PKI fields, which may not be easy to find. In addition, Sentinel operates on a deny/accept basis and lacks the ability to modify requests. Another possible approach when issuing or signing certificates verbatim would be to set up a validation service in front of Vault. With this approach, the client communicates with and authenticates to the validation service instead of directly to Vault. The validation service then validates incoming requests and forwards valid requests to the sign-verbatim endpoint. However, in order to do this, the validation service needs to authenticate to Vault, which introduces an additional authentication and authorization step. Clients who need to use this validation service and Vault for other use cases, such as role-based certificate request validation, would need to manage authentication information for both services. Similar to the Sentinel approach, a validation service running in front of Vault cannot modify certificate signing requests (CSR). Even if the request could be modified, it would happen outside of Vault which leaves the question of how those modifications could be audited. In addition, in order to remain compatible with Vault, the validation service would need to support the ACME protocol and any protocols that may be added to Vault in the future. Both approaches, sign-verbatim with Sentinel or with a validation service, are good for allowing and rejecting requests. However, they do not provide the ability to modify requests and lack auditability. As a result, the sign-verbatim solution is not user-friendly and is not popular among organizations that use Vault. Vault’s Certificate Issuance External Policy Service To address these challenges, we designed and implemented a new Vault Enterprise feature called CIEPS in HashiCorp Vault 1.15. CIEPS is part of the PKI secrets engine and offers a new mechanism that allows customers to use and validate any field specified in the x.509 standard. This enables a high degree of customizability to address less-common use cases. With CIEPS, customers can build a custom policy service that runs outside of Vault. In the service, custom issuance policies can be specified. A Vault operator can then configure the PKI secrets engine to refer to this custom policy service. This lets Vault handle communication with the service. When Vault receives a request that requires validation by the external policy service, it forwards the request to the custom policy service for validation and approval. The external policy service processes the request and, based on the defined policies, determines if the request should be approved or denied. When the request is approved, Vault updates select fields if necessary and then issues the certificate. If the request is denied, the policy service can specify a custom error message in its response to Vault. Vault includes the error message in its response to the original request, allowing a better user experience with customized error messages instead of generic, uninformative ones. Once everything has been set up, clients can authenticate to and request certificates from Vault. The interaction between Vault and the external policy service is not visible to the client. For the client, Vault's behavior remains unchanged and the certificate request workflow remains the same. The only difference is the API endpoint to which the request is sent in Vault. No additional authentication or authorization step is necessary. This lets the client interact only with Vault as the central platform, instead of having to target an additional service. The external policy service can also modify the original requests if necessary. Since it is directly integrated with Vault, all requests and responses are part of Vault’s audit logs, ensuring complete auditability of the issuance process. The benefits of using an external policy service with Vault include: Auditability: As Vault is handling the communication and requests to the service, all requests and responses between Vault and the external policy service are tracked in Vault’s audit logs. User experience: Clients interact only with Vault, the request workflow stays the same, and error messages are customizable. Certificate modification: The original request can be customized according to the defined policies. Flexibility: The external policy service uses a customer-defined external service for validation and is therefore more flexible than the role-based system. CIEPS in Vault PKI: Adding flexibility With CIEPS, organizations now have granular control and the ability to create flexible certificate structures that meet their PKI requirements, while having HashiCorp Vault validate and issue them. CIEPS allows for the use and validation of any field or extension specified in the x.509 standard, addressing use cases that are not supported natively and therefore were previously not possible in Vault. Additionally, the workflow for end users remains the same, ensuring a consistent user experience. Interested in learning more about the Certificate Issuance External Policy Service? Check out our hands-on tutorial, which includes an example service to get you started. To learn more about how HCP Vault and Vault Enterprise can help with your PKI requirements, contact HashiCorp sales. HashiCorp Vault PKI resources PKI design considerations: Read this technical guide on how to build modern PKI with HashiCorp Vault. What is public key infrastructure (PKI): See how PKI governs the provisioning of digital certificates to protect sensitive data, establish digital identities, and secure communications. What is ACME PKI? Learn about the ACME protocol for PKI, the common problems it solves, and why it should be part of your certificate management roadmap. PKI hosting: Cloud-based PKI vs. self managed: Discover the benefits and differences between hosting PKI workloads in the cloud versus on-premises. X.509 certificate management with Vault: A look at practical public key certificate management in HashiCorp Vault using dynamic secrets rotation. View the full article