3 Managing Certificates
The RESTful API enables you to manage certificate signing requests (CSRs), system or trusted user certificates, and certificate authority (CA) certificates.
In the following table, request is the uuid of a CSR, and certificate is the uuid of a system or trusted user certificate or a CA certificate.
Table 3-1 Certificate Operations
| Request | Append to Path /api/setting/v{1|2} | Description |
|---|---|---|
|
GET |
/certificates/system/template |
Return a template CSR. |
|
POST |
/certificates/system |
Create a CSR. Upload a new system certificate. |
|
GET |
/certificates/system/request |
List the properties of the specified CSR. Return the CSR in PEM format. |
|
GET |
/certificates/system |
List the properties of all system certificates and requests. |
|
PUT |
/certificates/system |
Set the value of the default system certificate. |
|
GET |
/certificates/system/certificate |
List the properties of the specified system certificate. Return the certificate in PEM format. |
|
DELETE |
/certificates/system/certificate |
Destroy the specified system certificate. |
|
GET |
/certificates/trusted |
List the properties of all trusted certificates. |
|
POST |
/certificates/trusted |
Upload a new trusted certificate. |
|
GET |
/certificates/trusted/certificate |
List the properties of the specified trusted certificate. Return the certificate in PEM format. |
|
PUT |
/certificates/trusted/certificate |
Set the value of the |
|
DELETE |
/certificates/trusted/certificate |
Destroy the specified trusted certificate. |
List Certificates
The following request lists the properties of all system certificates on the
host and lists the value of the default property.
Example Request:
GET /api/setting/v2/certificates/system HTTP/1.1 Host: alice.example.com:215 Authorization: Basic Tm8gcGVla2luZyE= Accept: application/json
Example Result:
The first certificate in the following example is an automatically-generated conventional certificate (based on the domain or IP address). The second certificate is an automatically-generated certificate based on the Appliance Serial Number (ASN) UUID.
At the end of this result, the value of the default property
shows that the system default certificate is selected automatically.
HTTP/1.1 200 OK
Date: Sat, 08 May 2021 00:37:21 GMT
Content-Type: application/json; charset=utf-8
X-Zfssa-Api-Version: 2.0
X-Zfssa-Setting-Api: 2.0
Content-Length: 1975
{
"certificates": [
{
"uuid": "system-cert1-uuid",
"type": "cert",
"data": {
"subject": [
{
"countryName": "US"
},
{
"stateOrProvinceName": "CA"
},
{
"localityName": "Exampleton"
},
{
"organizationName": "Example Corp, Inc"
},
{
"commonName": "alice.example.com"
}
],
"issuer": [
{
"countryName": "US"
},
{
"stateOrProvinceName": "AK"
},
{
"localityName": "Trustville"
},
{
"organizationName": "Totally Trustworthy Certificates, Inc"
},
{
"commonName": "Most Trusted Certificate"
}
],
"serialNumber": "64",
"validity": {
"notBefore": "20210520T21:08:27",
"notAfter": "20220520T21:08:27"
},
"extensions": {
"basicConstraints": {
"value": [
{
"CA": false
}
]
},
"subjectKeyIdentifier": {
"value": "subjectKeyIdentifier"
},
"authorityKeyIdentifier": {
"value": [
{
"keyid": "authorityKeyIdentifier"
}
]
},
"subjectAltName": {
"value": [
{
"DNS": "alice.example.com"
},
{
"IP": "alice.example.com-ipaddr"
}
]
}
}
},
"sha1fingerprint": "sha1fingerprint",
"href": "/api/setting/v2/certificates/system/system-cert1-uuid"
},
{
"uuid": "system-cert2-uuid",
"type": "cert",
"asn": "8bf7f9bc-8b3a-4064-e59f-bf09e3dba275",
"data": {
"subject": [
{
"commonName": "8bf7f9bc-8b3a-4064-e59f-bf09e3dba275"
}
],
"issuer": [
{
"commonName": "8bf7f9bc-8b3a-4064-e59f-bf09e3dba275"
}
],
"serialNumber": "59:8A:73:7B:00:00:00:07",
"validity": {
"notBefore": "20060215T18:00:00",
"notAfter": "20380119T03:14:07"
},
"extensions": {
"nsComment": {
"value": "Automatically generated"
},
"subjectAltName": {
"critical": true,
"value": [
{
"DirName": "8bf7f9bc-8b3a-4064-e59f-bf09e3dba275"
}
]
}
}
},
"sha1fingerprint": "sha1fingerprint",
"href": "/api/setting/v2/certificates/system/system-cert2-uuid"
}
],
"default": "auto"
}The following request lists the properties of the specified trusted-cert1-uuid trusted certificate.
Example Request:
GET /api/setting/v2/certificates/trusted/trusted-cert1-uuid HTTP/1.1
Host: alice.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: application/jsonExample Result:
HTTP/1.1 200 OK
Date: Sat, 08 May 2021 00:37:57 GMT
Content-Length: 984
Content-Type: application/json; charset=utf-8
X-Zfssa-Setting-Api: 2.0
X-Zfssa-Api-Version: 2.0
{
"certificate": {
"uuid": "trusted-cert1-uuid",
"type": "cert_ca",
"data": {
"subject": [
{
"countryName": "US"
},
{
"stateOrProvinceName": "AK"
},
{
"localityName": "Trustville"
},
{
"organizationName": "Totally Trustworthy Certificates, Inc"
},
{
"commonName": "Most Trusted Certificate"
}
],
"issuer": [
{
"countryName": "US"
},
{
"stateOrProvinceName": "AK"
},
{
"localityName": "Trustville"
},
{
"organizationName": "Totally Trustworthy Certificates, Inc"
},
{
"commonName": "Most Trusted Certificate"
}
],
"serialNumber": "83:F7:79:02:5F:44:4D:60",
"validity": {
"notBefore": "20210316T17:28:37",
"notAfter": "20210415T17:28:37"
},
"extensions": {
"subjectKeyIdentifier": {
"value": "subjectKeyIdentifier"
},
"authorityKeyIdentifier": {
"value": [
{
"keyid": "authorityKeyIdentifier"
}
]
},
"basicConstraints": {
"value": [
{
"CA": true
}
]
}
}
},
"sha1fingerprint": "sha1fingerprint",
"services": [
"ldap",
"cloud"
],
"href": "/api/setting/v2/certificates/trusted/trusted-cert1-uuid"
}
}Return a Certificate in PEM Format
To return a certificate in PEM format, specify one of the following values in the Accept header:
application/pkix-cert application/x-x509-ca-cert application/x-x509-user-cert application/x-pem-file
Example Request:
GET /api/setting/v2/certificates/system/system-cert1-uuid HTTP/1.1
Host: alice.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: application/x-pem-fileExample Result:
HTTP/1.1 200 OK Date: Thu, 13 May 2021 06:29:33 GMT Content-Length: 1440 Content-Type: application/x-pem-file; charset=utf-8 X-Zfssa-Setting-Api: 2.0 X-Zfssa-Api-Version: 2.0 -----BEGIN CERTIFICATE----- MIID+TCCAuGgAwIBAgIIXKTieQAAAAIwDQYJKoZIhvcNAQELBQAwVjEgMB4GA1UE ... sUSSZgilvMJ4G8jtx6JSbG4DzDkvo8vq7GSika7h+hi5cbDiZdsOL9kDtBIqSAVN Z1gjaFpzgio6wRvaIA== -----END CERTIFICATE-----
Upload a Key or Certificate
When you receive the signed certificate from the CA, use the following command to upload the certificate. Specify one of the following values in the Content-Type header:
application/pkix-cert application/x-x509-ca-cert application/x-x509-user-cert application/x-pem-file
Example Request:
POST /api/setting/v2/certificates/system HTTP/1.1 Host: alice.example.com:215 Authorization: Basic Tm8gcGVla2luZyE= Content-Type: application/x-pem-file -----BEGIN CERTIFICATE----- MIIDdTCCAl2gAwIBAgICH5cwDQYJKoZIhvcNAQELBQAwazELMAkGA1UEBhMCdXMx ... cgfvd1NUEvSdlb2+cjRBd9uSdtLfv7H5BKTKEdOXikv9+f150MytMEo4ABt0pEyp /KwtRsdIxmzAjmNqfQPR6eAHVfQ/CGwh6Q== -----END CERTIFICATE-----
Example Result:
HTTP/1.1 200 OK Date: Tue, 11 May 2021 18:04:22 GMT Content-Type: application/json; charset=utf-8 X-Zfssa-Api-Version: 2.0 X-Zfssa-Setting-Api: 2.0 Location: /api/setting/v2/certificates/system/system-cert3-uuid Content-Length: 987 { "certificate": { "uuid": "system-cert3-uuid", "type": "cert", "data": { "subject": [ { "countryName": "US" }, { "stateOrProvinceName": "CA" }, { "localityName": "Exampleton" }, { "organizationName": "Example Corp, Inc" }, { "commonName": "alice.example.com" } ], "issuer": [ { "countryName": "US" }, { "stateOrProvinceName": "AK" }, { "localityName": "Trustville" }, { "organizationName": "Totally Trustworthy Certificates, Inc" }, { "commonName": "Most Trusted Certificate" } ], "serialNumber": "64", "validity": { "notBefore": "20210520T21:08:27", "notAfter": "20220520T21:08:27" }, "extensions": { "basicConstraints": { "value": [ { "CA": false } ] }, "subjectKeyIdentifier": { "value": "subjectKeyIdentifier" }, "authorityKeyIdentifier": { "value": [ { "keyid": "authorityKeyIdentifier" } ] }, "subjectAltName": { "value": [ { "DNS": "alice.example.com" }, { "IP": "alice.example.com-ipaddr" } ] } } }, "sha1fingerprint": "sha1fingerprint", "href": "/api/setting/v2/certificates/system/system-cert3-uuid" } }
Specify the Services for Which a Certificate Should Be Trusted
You cannot modify any properties of a system certificate or a CSR. Set the properties of a CSR before you post the CSR.
You can set the value of the services property of a trusted
certificate. The services property is the list of services for which
the certificate should be trusted.
The following example sets the services property of a
trusted certificate.
PUT /api/setting/v2/certificates/trusted/trusted-cert2-uuid HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: alice.example.com:215
Content-Type: application/json
{"certificate": { "services": ["ldap"] }}The following example sets multiple services for which the certificate should be trusted.
PUT /api/setting/v2/certificates/trusted/trusted-cert2-uuid HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: alice.example.com:215
Content-Type: application/json
{"certificate": {"services": [ "ldap", "cloud" ] }}Set the System Default Certificate
The following example assigns a default system certificate.
PUT /api/setting/v2/certificates/system HTTP/1.1
Authorization: Basic Tm8gcGVla2luZyE=
Host: alice.example.com:215
Accept: application/json
Content-Type: application/json
{ "default": "system-cert1-uuid" }Destroy a Certificate
The DELETE command destroys the specified certificate,
request, or key. If successful, HTTP status 204 (No Content) is returned.
DELETE /api/setting/v2/certificates/system/system-cert2-uuid HTTP/1.1Enable HTTP Strict Transport Security
HTTP Strict Transport Security (HSTS) allows only secure HTTPS connections, and not HTTP connections, for a specified period of time. Before using HSTS, familiarize yourself with HSTS prerequisites, understand browser behavior with HSTS enabled, and install a certificate signed by a certificate authority.
Note:
Failure to keep the certificate valid and appropriate could negate HSTS security advantages or could cause a browser to not connect with Oracle ZFS Storage Appliance.As shown in the following example, the default maximum length of time that HSTS will remain enabled is 63072000 seconds, or 2 years.
Example Request:
GET /api/setting/v2/security HTTP/1.1 Host: alice.example.com:215 Authorization: Basic Tm8gcGVla2luZyE= Accept: application/json
Example Result:
HTTP/1.1 200 OK
Date: Fri, 14 May 2021 19:22:27 GMT
Content-Type: application/json; charset=utf-8
X-Zfssa-Api-Version: 2.0
X-Zfssa-Setting-Api: 2.0
Content-Length: 109
{
"Security settings": {
"href": "/api/setting/v2/security",
"hsts_enable": false,
"hsts_max_age": 63072000
}
}To enable HSTS for this appliance, set the hsts_enable
property to true.
PUT /api/setting/v2/security HTTP/1.1
Host: alice.example.com:215
Content-Type: application/json
{"hsts_enable": true}