mirror of
https://github.com/Infisical/infisical.git
synced 2026-01-09 15:38:03 -05:00
276 lines
14 KiB
Plaintext
276 lines
14 KiB
Plaintext
---
|
|
title: "Certificates"
|
|
sidebarTitle: "Certificates"
|
|
---
|
|
|
|
<Note>
|
|
PKI architecture is a complex topic and there are many ways to orchestrate
|
|
certificate management including renewal operations. For specific guidance and
|
|
access to enterprise features, we recommend reaching out to
|
|
sales@infisical.com to schedule a demo.
|
|
</Note>
|
|
|
|
## Concept
|
|
|
|
A certificate is the (X.509) leaf certificate issued for a certificate profile.
|
|
|
|
Once issued, a certificate is kept track of in the certificate inventory
|
|
where you can manage various aspects of its lifecycle including deployment to cloud key stores, server-side auto-renewal behavior, revocation, and more.
|
|
|
|
## Guide to Issuing Certificates
|
|
|
|
To [issue a certificate](/documentation/platform/pki/concepts/certificate-lifecycle#enrollment-request-%2F-issuance), you must first create a [certificate profile](/documentation/platform/pki/certificates/profiles) and a [certificate template](/documentation/platform/pki/certificates/templates) to go along with it.
|
|
|
|
- Self-Signed Certificates: To issue a [self-signed certificate](https://en.wikipedia.org/wiki/Self-signed_certificate), you must configure the certificate profile to use the `Self-Signed` issuer type. You can then use the [API enrollment method](/documentation/platform/pki/enrollment-methods/api) to request a self-signed certificate against it.
|
|
- CA-Issued Certificates: To issue a certificate from a certificate authority, you must configure the certificate profile to use the `Certificate Authority` issuer type and select the [issuing CA](/documentation/platform/pki/ca/overview) to use. You can then use one of the [enrollment methods](/documentation/platform/pki/enrollment-methods/overview) to request a certificate against it.
|
|
|
|
Refer to the documentation for each [enrollment method](/documentation/platform/pki/enrollment-methods/overview) to learn more about how to issue certificates using it.
|
|
|
|
## Guide to Renewing Certificates
|
|
|
|
To [renew a certificate](/documentation/platform/pki/concepts/certificate-lifecycle#renewal), you can either request a new certificate from a certificate profile or have the platform
|
|
automatically request a new one for you. Whether you pursue a client-driven or server-driven approach is totally dependent on the enrollment method configured on your certificate
|
|
profile as well as your infrastructure use-case.
|
|
|
|
### Client-Driven Certificate Renewal
|
|
|
|
Client-driven certificate renewal is when renewal is initiated client-side by the end-entity consuming the certificate.
|
|
This is the most common approach to certificate renewal and is suitable for most use-cases.
|
|
|
|
### Server-Driven Certificate Renewal
|
|
|
|
Server-driven certificate renewal is when renewal is initiated server-side by Infisical rather than by the end-entity consuming the certificate.
|
|
When a certificate considered for auto-renewal meets a specified _renewal days before expiration_ threshold, Infisical reaches out to the issuing CA bound to the [certificate profile](/documentation/platform/pki/certificates/profiles) of the expiring certificate
|
|
to request for a new one.
|
|
The resulting renewed certificate is stored in the platform and made available to be fetched back or pushed downstream to end-entities or external systems such as cloud key stores.
|
|
|
|
Note that server-driven certificate renewal is only available for certificates issued via the [API enrollment method](/documentation/platform/pki/enrollment-methods/api) where key pairs are generated server-side.
|
|
A certificate can be considered for auto-renewal at time of issuance if the **Enable Auto-Renewal By Default** option is selected on its [certificate profile](/documentation/platform/pki/certificates/profiles) or after issuance by toggling this option manually.
|
|
|
|
<Info>
|
|
For server-driven certificate renewal workflows, you can programmatically
|
|
fetch the latest active certificate bundle for a certificate profile using the
|
|
[Get Latest Active Certificate
|
|
Bundle](/api-reference/endpoints/certificate-profiles/get-latest-active-bundle)
|
|
API endpoint. This ensures you always retrieve the most current valid
|
|
certificate, including any that have been automatically renewed, making it
|
|
particularly useful for deployment pipelines and automation workflows where
|
|
you don't want to track individual serial numbers.
|
|
</Info>
|
|
|
|
The following examples demonstrate different approaches to certificate renewal:
|
|
|
|
- Using the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme), you may connect an ACME client like [certbot](https://certbot.eff.org/) to fetch back and renew certificates for [Apache](/documentation/platform/pki/integration-guides/apache-certbot), [Nginx](/documentation/platform/pki/integration-guides/nginx-certbot), or other server. The ACME client will pursue a client-driven approach and submit certificate requests upon certificate expiration for you, saving renewed certificates back to the server's configuration.
|
|
- Using the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme), you may use [cert-manager](https://cert-manager.io/) with Infisical to issue and renew certificates for Kubernetes workloads; cert-manager will pursue a client-driven approach and submit certificate requests upon certificate expiration for you, saving renewed certificates back to Kubernetes secrets.
|
|
- Using the [API enrollment method](/documentation/platform/pki/enrollment-methods/api), you may push and auto-renew certificates to AWS and Azure using [certificate syncs](/documentation/platform/pki/certificate-syncs/overview). Certificates issued over the API enrollment method, where key pairs are generated server-side, are also eligible for server-side auto-renewal; once renewed, certificates are automatically pushed back to their sync destination.
|
|
|
|
## Guide to Downloading Certificates
|
|
|
|
In the following steps, we explore different options for exporting already-issued certificates from Infisical in different formats for use in your applications and infrastructure.
|
|
|
|
### Download Latest Profile Certificate
|
|
|
|
You can download the latest certificate issued against a [certificate profile](/documentation/platform/pki/certificates/profiles) using the [latest certificate bundle](/api-reference/endpoints/certificate-profiles/get-latest-active-bundle) endpoint.
|
|
|
|
### Download Specific Certificate
|
|
|
|
To export a specific certificate, first navigate to your project's certificate inventory and locate the certificate you want to export. Click on the **Export Certificate** option from the certificate's action menu.
|
|
|
|
|
|
|
|
<Tabs>
|
|
<Tab title="PEM Format">
|
|
<Steps>
|
|
<Step title="Exporting in PEM Format">
|
|
In the export modal, choose **PEM** as the format and click **Export**.
|
|
|
|
|
|
|
|
The PEM export modal will display the certificate details including:
|
|
- **Serial Number**: The unique identifier for the certificate
|
|
- **Certificate Body**: The X.509 certificate in PEM format
|
|
- **Certificate Chain**: The intermediate and root CA certificates
|
|
- **Private Key**: The private key associated with the certificate (if available)
|
|
|
|
|
|
|
|
You can copy each component individually or use the **Copy All** button to copy the complete certificate bundle.
|
|
</Step>
|
|
<Step title="Using PEM Certificates">
|
|
PEM format certificates can be used directly with most web servers and applications:
|
|
|
|
- **Apache HTTP Server**: Configure SSL certificates in your virtual host
|
|
- **Nginx**: Use the certificate and private key files in your server configuration
|
|
- **Docker containers**: Mount certificate files for TLS-enabled applications
|
|
- **Load balancers**: Upload PEM certificates to AWS ALB, Azure Application Gateway, etc.
|
|
|
|
Example Nginx configuration:
|
|
```nginx
|
|
server {
|
|
listen 443 ssl;
|
|
server_name example.com;
|
|
|
|
ssl_certificate /path/to/certificate.pem;
|
|
ssl_certificate_key /path/to/private-key.pem;
|
|
}
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
</Tab>
|
|
<Tab title="PKCS12 Format">
|
|
<Steps>
|
|
<Step title="Exporting in PKCS12 Format">
|
|
In the export modal, choose **PKCS12** as the format and provide the required configuration:
|
|
|
|
|
|
|
|
- **Password**: A secure password to protect the PKCS12 keystore
|
|
- **Alias**: A friendly name for the certificate within the keystore
|
|
|
|
Click **Export** to generate and download the `.p12` file containing the certificate, certificate chain, and private key.
|
|
</Step>
|
|
<Step title="Using PKCS12 Certificates">
|
|
PKCS12 files (`.p12` extension) are binary keystore files that contain the certificate, certificate chain, and private key in a single encrypted file:
|
|
|
|
- **Java applications**: Import directly into Java KeyStore (JKS) or use with SSL/TLS
|
|
- **Windows IIS**: Import the PKCS12 file for web server SSL configuration
|
|
- **Browser certificates**: Install client certificates for authentication
|
|
- **Mobile applications**: Deploy certificates to iOS and Android applications
|
|
|
|
To verify the contents of a PKCS12 file:
|
|
```bash
|
|
openssl pkcs12 -in certificate.p12 -nokeys -clcerts
|
|
```
|
|
|
|
To extract the private key:
|
|
```bash
|
|
openssl pkcs12 -in certificate.p12 -nocerts -out private-key.pem
|
|
```
|
|
|
|
<Info>
|
|
If you need to convert the PKCS12 file to Java KeyStore (JKS) format for applications running on Java 8 or earlier, use the following keytool command:
|
|
|
|
```bash
|
|
keytool -importkeystore \
|
|
-srckeystore certificate.p12 \
|
|
-srcstoretype PKCS12 \
|
|
-srcstorepass <p12-password> \
|
|
-destkeystore certificate.jks \
|
|
-deststoretype JKS \
|
|
-deststorepass <jks-password>
|
|
```
|
|
|
|
Replace `<p12-password>` with the password you used when exporting the PKCS12 file, and `<jks-password>` with your desired JKS keystore password.
|
|
|
|
The resulting `.jks` file can then be used with Java applications that require JKS format keystores.
|
|
</Info>
|
|
</Step>
|
|
</Steps>
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
## Guide to Revoking Certificates
|
|
|
|
In the following steps, we explore how to revoke a X.509 certificate and obtain a Certificate Revocation List (CRL) for a CA.
|
|
|
|
<Tabs>
|
|
<Tab title="Infisical UI">
|
|
<Steps>
|
|
<Step title="Revoking a Certificate">
|
|
Assuming that you've issued a certificate under a CA, you can revoke it by
|
|
selecting the **Revoke Certificate** option for it and specifying the reason
|
|
for revocation.
|
|
|
|
|
|
|
|
|
|
|
|
</Step>
|
|
<Step title="Obtaining a CRL">
|
|
In order to check the revocation status of a certificate, you can check it
|
|
against the CRL of a CA by heading to its Issuing CA and downloading the CRL.
|
|
|
|
|
|
|
|
To verify a certificate against the
|
|
downloaded CRL with OpenSSL, you can use the following command:
|
|
|
|
```bash
|
|
openssl verify -crl_check -CAfile chain.pem -CRLfile crl.pem cert.pem
|
|
```
|
|
|
|
Note that you can also obtain the CRL from the certificate itself by
|
|
referencing the CRL distribution point extension on the certificate.
|
|
|
|
To check a certificate against the CRL distribution point specified within it with OpenSSL, you can use the following command:
|
|
|
|
```bash
|
|
openssl verify -verbose -crl_check -crl_download -CAfile chain.pem cert.pem
|
|
```
|
|
|
|
</Step>
|
|
</Steps>
|
|
</Tab>
|
|
<Tab title="API">
|
|
<Steps>
|
|
<Step title="Revoking a certificate">
|
|
Assuming that you've issued a certificate under a CA, you can revoke it by making an API request to the [Revoke Certificate](/api-reference/endpoints/certificates/revoke) API endpoint,
|
|
specifying the serial number of the certificate and the reason for revocation.
|
|
|
|
### Sample request
|
|
|
|
```bash Request
|
|
curl --location --request POST 'https://app.infisical.com/api/v1/pki/certificates/<cert-serial-number>/revoke' \
|
|
--header 'Authorization: Bearer <access-token>' \
|
|
--header 'Content-Type: application/json' \
|
|
--data-raw '{
|
|
"revocationReason": "UNSPECIFIED"
|
|
}'
|
|
```
|
|
|
|
### Sample response
|
|
|
|
```bash Response
|
|
{
|
|
message: "Successfully revoked certificate",
|
|
serialNumber: "...",
|
|
revokedAt: "..."
|
|
}
|
|
```
|
|
</Step>
|
|
<Step title="Obtaining a CRL">
|
|
In order to check the revocation status of a certificate, you can check it against the CRL of the issuing CA.
|
|
To obtain the CRLs of the CA, make an API request to the [List CRLs](/api-reference/endpoints/certificate-authorities/crl) API endpoint.
|
|
|
|
### Sample request
|
|
|
|
```bash Request
|
|
curl --location --request GET 'https://app.infisical.com/api/v1/pki/ca/<ca-id>/crls' \
|
|
--header 'Authorization: Bearer <access-token>'
|
|
```
|
|
|
|
### Sample response
|
|
|
|
```bash Response
|
|
[
|
|
{
|
|
id: "...",
|
|
crl: "..."
|
|
},
|
|
...
|
|
]
|
|
```
|
|
|
|
To verify a certificate against the CRL with OpenSSL, you can use the following command:
|
|
|
|
```bash
|
|
openssl verify -crl_check -CAfile chain.pem -CRLfile crl.pem cert.pem
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
</Tab>
|
|
</Tabs>
|