synced/infisical
1
0
Fork 0
mirror of https://github.com/Infisical/infisical.git synced 2025-04-17 19:37:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add examples for ca cert ops via api call

Browse Source
This commit is contained in:
Tuan Dang
2024-06-13 14:00:53 -07:00
parent 8686b4abd3
commit 90dae62158
2 changed files with 244 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
docs/documentation/platform/pki/certificates.mdx
View File

@ -37,7 +37,10 @@ The typical workflow for managing certificates consists of the following steps:
## Guide to Issuing Certificates
In the following steps, we explore how to issue a X.509 certificate under a CA using the Infisical UI.
In the following steps, we explore how to issue a X.509 certificate under a CA.
<Tabs>
<Tab title="Infisical UI">
<Steps>
<Step title="Creating a certificate">
@ -52,6 +55,7 @@ In the following steps, we explore how to issue a X.509 certificate under a CA u
Here's some guidance on each field:
- Issuing CA: The CA under which to issue the certificate.
- Friendly Name: A friendly name for the certificate; this is only for display and defaults to the common name of the certificate if left empty.
- Common Name (CN): The (common) name of the certificate.
- TTL: The lifetime of the certificate in seconds.
- Valid Until: The date until which the certificate is valid in the date time string format specified [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format). For example, the following formats would be valid: `YYYY`, `YYYY-MM`, `YYYY-MM-DD`, `YYYY-MM-DDTHH:mm:ss.sssZ`.
@ -68,16 +72,51 @@ In the following steps, we explore how to issue a X.509 certificate under a CA u
</Note>
</Step>
</Steps>
</Tab>
<Tab title="API">
To create a certificate, make an API request to the [Create Certificate](/api-reference/endpoints/certificate-authorities/sign-intermediate) API endpoint,
specifying the issuing CA.
### Sample request
```bash Request
curl --location --request POST 'https://app.infisical.com/api/v1/pki/ca/<ca-id>/issue-certificate' \
--header 'Content-Type: application/json' \
--data-raw '{
"commonName": "My Certificate",
}'
```
### Sample response
```bash Response
{
certificate: "...",
certificateChain: "...",
issuingCaCertificate: "...",
privateKey: "...",
serialNumber: "..."
}
```
<Note>
Make sure to store the `privateKey` as it is only returned once here at the time of certificate issuance. The `certificate` and `certificateChain` will remain accessible and can be retrieved at any time.
</Note>
</Tab>
</Tabs>
## Guide to Revoking Certificates
In the following steps, we explore how to revoke a X.509 certificate under a CA and obtain a Certificate Revocation List (CRL) for a CA using the Infisical UI.
In the following steps, we explore how to revoke a X.509 certificate under a CA 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. Image 1 Image 2
for revocation.
![pki revoke certificate](/images/platform/pki/cert-revoke.png)
@ -102,6 +141,63 @@ openssl verify -crl_check -CAfile chain.pem -CRLfile crl.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/certificate-authorities/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 CRL of the CA, make an API request to the [Get CRL](/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>/crl' \
--header 'Authorization: Bearer <access-token>'
```
### Sample response
```bash Response
{
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>
## FAQ

146
docs/documentation/platform/pki/private-ca.mdx
View File

@ -39,8 +39,10 @@ A typical workflow for setting up a Private CA hierarchy consists of the followi
## Guide
In the following steps, we explore how to create a simple Private CA hierarchy
consisting of a root CA and an intermediate CA using the Infisical UI.
consisting of a root CA and an intermediate CA.
<Tabs>
<Tab title="Infisical UI">
<Steps>
<Step title="Creating a root CA">
To create a root CA, head to your Project > Internal PKI > Certificate Authorities and press **Create CA**.
@ -56,6 +58,7 @@ consisting of a root CA and an intermediate CA using the Infisical UI.
- Valid Until: The date until which the CA is valid in the date time string format specified [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format). For example, the following formats would be valid: `YYYY`, `YYYY-MM`, `YYYY-MM-DD`, `YYYY-MM-DDTHH:mm:ss.sssZ`.
- Path Length: The maximum number of intermediate CAs that can be chained to this CA. A path of `-1` implies no limit; a path of `0` implies no intermediate CAs can be chained.
- Key Algorithm: The type of public key algorithm and size, in bits, of the key pair that the CA creates when it issues a certificate. Supported key algorithms are `RSA 2048`, `RSA 4096`, `ECDSA P-256`, and `ECDSA P-384` with the default being `RSA 2048`.
- Friendly Name: A friendly name for the CA; this is only for display and defaults to the subject of the CA if left empty.
- Organization (O): The organization name.
- Country (C): The country code.
- State or Province Name: The state or province.
@ -95,6 +98,147 @@ consisting of a root CA and an intermediate CA using the Infisical UI.
</Step>
</Steps>
</Tab>
<Tab title="API">
<Steps>
<Step title="Creating a root CA">
To create a root CA, make an API request to the [Create CA](/api-reference/endpoints/certificate-authorities/create) API endpoint, specifying the `type` as `root`.
### Sample request
```bash Request
curl --location --request POST 'https://app.infisical.com/api/v1/pki/ca' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"projectSlug": "<your-project-slug>",
"type": "root",
"commonName": "My Root CA"
}'
```
### Sample response
```bash Response
{
ca: {
id: "<root-ca-id>",
type: "root",
commonName: "My Root CA",
...
}
}
```
By default, Infisical creates a root CA with the `RSA_2048` key algorithm, validity period of 10 years, with no restrictions on path length;
you may override these defaults by specifying your own options when making the API request.
</Step>
<Step title="Creating an intermediate CA">
2.1. To create an intermediate CA, make an API request to the [Create CA](/api-reference/endpoints/certificate-authorities/create) API endpoint, specifying the `type` as `intermediate`.
### Sample request
```bash Request
curl --location --request POST 'https://app.infisical.com/api/v1/pki/ca' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"projectSlug": "<your-project-slug>",
"type": "intermediate",
"commonName": "My Intermediate CA"
}'
```
### Sample response
```bash Response
{
ca: {
id: "<intermediate-ca-id>",
type: "intermediate",
commonName: "My Intermediate CA",
...
}
}
```
2.2. Next, get a certificate signing request from the intermediate CA by making an API request to the [Get CSR](/api-reference/endpoints/certificate-authorities/csr) API endpoint.
### Sample request
```bash Request
curl --location --request GET 'https://app.infisical.com/api/v1/pki/ca/<intermediate-ca-id>/csr' \
--header 'Authorization: Bearer <access-token>' \
--data-raw ''
```
### Sample response
```bash Response
{
csr: "..."
}
```
2.3. Next, create an intermediate certificate by making an API request to the [Sign Intermediate](/api-reference/endpoints/certificate-authorities/sign-intermediate) API endpoint
containing the CSR from step 2.2, referencing the root CA created in step 1.
### Sample request
```bash Request
curl --location --request POST 'https://app.infisical.com/api/v1/pki/ca/<root-ca-id>/sign-intermediate' \
--header 'Content-Type: application/json' \
--data-raw '{
"csr": "<csr>",
"notAfter": "2029-06-12"
}'
```
### Sample response
```bash Response
{
certificate: "...",
certificateChain: "...",
issuingCaCertificate: "...",
serialNumber: "...",
}
```
<Note>
The `notAfter` value must be within the validity period of the root CA that is if the root CA is valid until `2029-06-12`, the intermediate CA must be valid until a date before `2029-06-12`.
</Note>
2.4. Finally, import the intermediate certificate and certificate chain from step 2.3 back to the intermediate CA by making an API request to the [Import Certificate](/api-reference/endpoints/certificate-authorities/import-cert) API endpoint.
### Sample request
```bash Request
curl --location --request POST 'https://app.infisical.com/api/v1/pki/ca/<intermediate-ca-id>/import-certificate' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"certificate": "<certificate>",
"certificateChain": "<certificate-chain>"
}'
```
### Sample response
```bash Response
{
message: "Successfully imported certificate to CA",
caId: "..."
}
```
Great! You’ve successfully created a Private CA hierarchy with a root CA and an intermediate CA. Now check out the Certificates page to learn more about how to issue X.509 certificates using the intermediate CA.
</Step>
</Steps>
</Tab>
</Tabs>
## FAQ