Powered by Redocly

TLS CA Roles

Different TLS CA roles can have different restrictions on the certificates that are generated from a CA. For example, one role may be allowed to only issue short lived (short TTL) client certificates, whereas another role may be allowed to issue server certificates for a given domain.

Create a new tls ca role

Roles allow for tighter control over which certificates a user or approle is allowed to issue, both in terms of certificate type as well as certificate properties such as TTL

It is recommended that restricted roles are used to limit the exposure. A user or app role should only be given access to a specific role that has been tightly locked down to only allow issuing of certificates with the properties needed for the specific use case. This to limit the chance of unwanted certificates being generated.

SecurityaccessToken
Request
path Parameters
tls-ca-name
required
string <name>

name of tls-ca

query Parameters
validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Request Body schema:
name
string <name>
cert-key-type
string <cipher-key-type>
Default: "ecdsa"
  • ecdsa: Elliptic Curve Digital Signature Algorithm
  • rsa: Rivest-Shamir-Adleman public-key cryptosystem

Key type of generated certificate.

cert-key-curve
string <cipher-key-curve>
Default: "secp256r1"
  • secp256r1
  • secp384r1
  • secp521r1 Elliptic curve ciphers.

Valid when: ../cert-key-type = 'ecdsa'

Curve of generated certificate, if the cert-key-type is ecdsa.

cert-key-size
integer <uint32>
Default: 2048

Valid when: ../cert-key-type = 'rsa'

Size of the certificate key, if the cert-key-type is RSA.

allowed-hosts
Array of strings
allowed-domains
Array of strings

List of allowed domains when issuing certificates from this role. Adding a * to the list allows all domains.

ttl
string <duration>

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

Default TTL of generated certificates.

max-ttl
string <duration>

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

Max allowed TTL of generated certificates.

digest
string <digest-type>
Default: "sha256"
  • sha1
  • sha224
  • sha256
  • sha384
  • sha512 Digest types, sha1 should be avoided.
allow-bare-domains
boolean
Default: false

Allow certificates to be issued with CN or DNS name equal to one of the domains listed in allowed domains, ie if example.com is listed in allowed-domains allow a certificate with CN example.com to be issued.

allow-subdomains
boolean
Default: false

Allow CN or DNS name that are a subdomain to the domains listed in allowed-domains.

allow-any-name
boolean
Default: false

Allow any CN or alt-name. Equivalent to adding * to allowed-domains.

allow-ip-sans
boolean
Default: false

Allow IP addresses in Subject Alt Names.

server-ext-usage
boolean
Default: true

Adds the ServerAuth flag to Extended Key Usage attribute of the generated certificates.

client-ext-usage
boolean
Default: true

Adds the ClientAuth flag to Extended Key Usage attribute of the generated certificates.

code-signing-ext-usage
boolean
Default: false

Adds the CodeSigning flag to Extended Key Usage attribute of the generated certificates.

full-authority-key-identifier
boolean

Include key authority serial and name, in addition to key.

allow-ca-certs
boolean
Default: false

Allow role to issue ca certificates.

allow-client-certs
boolean
Default: false

Allow role to issue client certificates.

allow-server-certs
boolean

Allow role to issue server certificates.

to (object) or sites (object) or deployments (object)
Responses
201

Created

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

409

Conflict (instance exists)

503

Service Unavailable (strongbox sealed)

post/v1/config/strongbox/tls/ca/{tls-ca-name}/roles
Request samples 
name: cert-signer
cert-key-type: ecdsa
allowed-hosts:
  - www.acme.com
allowed-domains:
  - avassa.net
ttl: 1y
max-ttl: 1y355d
digest: sha256
allow-bare-domains: true
allow-subdomains: true
allow-any-name: true
allow-ip-sans: true
server-ext-usage: true
client-ext-usage: true
code-signing-ext-usage: false
full-authority-key-identifier: false
allow-ca-certs: false
allow-client-certs: false
allow-server-certs: true
distribute:
  to: inherit

Retrieve the configuration of all tls ca roles

Roles allow for tighter control over which certificates a user or approle is allowed to issue, both in terms of certificate type as well as certificate properties such as TTL

It is recommended that restricted roles are used to limit the exposure. A user or app role should only be given access to a specific role that has been tightly locked down to only allow issuing of certificates with the properties needed for the specific use case. This to limit the chance of unwanted certificates being generated.

SecurityaccessToken
Request
path Parameters
tls-ca-name
required
string <name>

name of tls-ca

query Parameters
fields
string

Retrieve only requested fields from the resource

See section fields

validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
keys
string <enumeration>

Retrieve only the keys for the list

Value: "true"
count
string <enumeration>

Retrieve only the number of elements in the list

Value: "true"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

get/v1/config/strongbox/tls/ca/{tls-ca-name}/roles
Response samples 
- name: cert-signer
  cert-key-type: ecdsa
  allowed-hosts:
    - www.acme.com
  allowed-domains:
    - avassa.net
  ttl: 1y
  max-ttl: 1y355d
  digest: sha256
  allow-bare-domains: true
  allow-subdomains: true
  allow-any-name: true
  allow-ip-sans: true
  server-ext-usage: true
  client-ext-usage: true
  code-signing-ext-usage: false
  full-authority-key-identifier: false
  allow-ca-certs: false
  allow-client-certs: false
  allow-server-certs: true
  distribute:
    to: inherit

Update a tls ca role

Roles allow for tighter control over which certificates a user or approle is allowed to issue, both in terms of certificate type as well as certificate properties such as TTL

It is recommended that restricted roles are used to limit the exposure. A user or app role should only be given access to a specific role that has been tightly locked down to only allow issuing of certificates with the properties needed for the specific use case. This to limit the chance of unwanted certificates being generated.

SecurityaccessToken
Request
path Parameters
tls-ca-name
required
string <name>

name of tls-ca

tls-ca-role-name
required
string <name>

name of tls-ca-role

query Parameters
validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Request Body schema:
name
string <name>
cert-key-type
string <cipher-key-type>
Default: "ecdsa"
  • ecdsa: Elliptic Curve Digital Signature Algorithm
  • rsa: Rivest-Shamir-Adleman public-key cryptosystem

Key type of generated certificate.

cert-key-curve
string <cipher-key-curve>
Default: "secp256r1"
  • secp256r1
  • secp384r1
  • secp521r1 Elliptic curve ciphers.

Valid when: ../cert-key-type = 'ecdsa'

Curve of generated certificate, if the cert-key-type is ecdsa.

cert-key-size
integer <uint32>
Default: 2048

Valid when: ../cert-key-type = 'rsa'

Size of the certificate key, if the cert-key-type is RSA.

allowed-hosts
Array of strings
allowed-domains
Array of strings

List of allowed domains when issuing certificates from this role. Adding a * to the list allows all domains.

ttl
string <duration>

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

Default TTL of generated certificates.

max-ttl
string <duration>

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

Max allowed TTL of generated certificates.

digest
string <digest-type>
Default: "sha256"
  • sha1
  • sha224
  • sha256
  • sha384
  • sha512 Digest types, sha1 should be avoided.
allow-bare-domains
boolean
Default: false

Allow certificates to be issued with CN or DNS name equal to one of the domains listed in allowed domains, ie if example.com is listed in allowed-domains allow a certificate with CN example.com to be issued.

allow-subdomains
boolean
Default: false

Allow CN or DNS name that are a subdomain to the domains listed in allowed-domains.

allow-any-name
boolean
Default: false

Allow any CN or alt-name. Equivalent to adding * to allowed-domains.

allow-ip-sans
boolean
Default: false

Allow IP addresses in Subject Alt Names.

server-ext-usage
boolean
Default: true

Adds the ServerAuth flag to Extended Key Usage attribute of the generated certificates.

client-ext-usage
boolean
Default: true

Adds the ClientAuth flag to Extended Key Usage attribute of the generated certificates.

code-signing-ext-usage
boolean
Default: false

Adds the CodeSigning flag to Extended Key Usage attribute of the generated certificates.

full-authority-key-identifier
boolean

Include key authority serial and name, in addition to key.

allow-ca-certs
boolean
Default: false

Allow role to issue ca certificates.

allow-client-certs
boolean
Default: false

Allow role to issue client certificates.

allow-server-certs
boolean

Allow role to issue server certificates.

to (object) or sites (object) or deployments (object)
Responses
204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

patch/v1/config/strongbox/tls/ca/{tls-ca-name}/roles/{tls-ca-role-name}
Request samples 
name: cert-signer
cert-key-type: ecdsa
allowed-hosts:
  - www.acme.com
allowed-domains:
  - avassa.net
ttl: 1y
max-ttl: 1y355d
digest: sha256
allow-bare-domains: true
allow-subdomains: true
allow-any-name: true
allow-ip-sans: true
server-ext-usage: true
client-ext-usage: true
code-signing-ext-usage: false
full-authority-key-identifier: false
allow-ca-certs: false
allow-client-certs: false
allow-server-certs: true
distribute:
  to: inherit

Delete a tls ca role

Roles allow for tighter control over which certificates a user or approle is allowed to issue, both in terms of certificate type as well as certificate properties such as TTL

It is recommended that restricted roles are used to limit the exposure. A user or app role should only be given access to a specific role that has been tightly locked down to only allow issuing of certificates with the properties needed for the specific use case. This to limit the chance of unwanted certificates being generated.

SecurityaccessToken
Request
path Parameters
tls-ca-name
required
string <name>

name of tls-ca

tls-ca-role-name
required
string <name>

name of tls-ca-role

query Parameters
validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Responses
204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

delete/v1/config/strongbox/tls/ca/{tls-ca-name}/roles/{tls-ca-role-name}

Replace or create a new tls ca role

Roles allow for tighter control over which certificates a user or approle is allowed to issue, both in terms of certificate type as well as certificate properties such as TTL

It is recommended that restricted roles are used to limit the exposure. A user or app role should only be given access to a specific role that has been tightly locked down to only allow issuing of certificates with the properties needed for the specific use case. This to limit the chance of unwanted certificates being generated.

SecurityaccessToken
Request
path Parameters
tls-ca-name
required
string <name>

name of tls-ca

tls-ca-role-name
required
string <name>

name of tls-ca-role

query Parameters
validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Request Body schema:
name
string <name>
cert-key-type
string <cipher-key-type>
Default: "ecdsa"
  • ecdsa: Elliptic Curve Digital Signature Algorithm
  • rsa: Rivest-Shamir-Adleman public-key cryptosystem

Key type of generated certificate.

cert-key-curve
string <cipher-key-curve>
Default: "secp256r1"
  • secp256r1
  • secp384r1
  • secp521r1 Elliptic curve ciphers.

Valid when: ../cert-key-type = 'ecdsa'

Curve of generated certificate, if the cert-key-type is ecdsa.

cert-key-size
integer <uint32>
Default: 2048

Valid when: ../cert-key-type = 'rsa'

Size of the certificate key, if the cert-key-type is RSA.

allowed-hosts
Array of strings
allowed-domains
Array of strings

List of allowed domains when issuing certificates from this role. Adding a * to the list allows all domains.

ttl
string <duration>

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

Default TTL of generated certificates.

max-ttl
string <duration>

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

Max allowed TTL of generated certificates.

digest
string <digest-type>
Default: "sha256"
  • sha1
  • sha224
  • sha256
  • sha384
  • sha512 Digest types, sha1 should be avoided.
allow-bare-domains
boolean
Default: false

Allow certificates to be issued with CN or DNS name equal to one of the domains listed in allowed domains, ie if example.com is listed in allowed-domains allow a certificate with CN example.com to be issued.

allow-subdomains
boolean
Default: false

Allow CN or DNS name that are a subdomain to the domains listed in allowed-domains.

allow-any-name
boolean
Default: false

Allow any CN or alt-name. Equivalent to adding * to allowed-domains.

allow-ip-sans
boolean
Default: false

Allow IP addresses in Subject Alt Names.

server-ext-usage
boolean
Default: true

Adds the ServerAuth flag to Extended Key Usage attribute of the generated certificates.

client-ext-usage
boolean
Default: true

Adds the ClientAuth flag to Extended Key Usage attribute of the generated certificates.

code-signing-ext-usage
boolean
Default: false

Adds the CodeSigning flag to Extended Key Usage attribute of the generated certificates.

full-authority-key-identifier
boolean

Include key authority serial and name, in addition to key.

allow-ca-certs
boolean
Default: false

Allow role to issue ca certificates.

allow-client-certs
boolean
Default: false

Allow role to issue client certificates.

allow-server-certs
boolean

Allow role to issue server certificates.

to (object) or sites (object) or deployments (object)
Responses
201

Created

204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

put/v1/config/strongbox/tls/ca/{tls-ca-name}/roles/{tls-ca-role-name}
Request samples 
name: cert-signer
cert-key-type: ecdsa
allowed-hosts:
  - www.acme.com
allowed-domains:
  - avassa.net
ttl: 1y
max-ttl: 1y355d
digest: sha256
allow-bare-domains: true
allow-subdomains: true
allow-any-name: true
allow-ip-sans: true
server-ext-usage: true
client-ext-usage: true
code-signing-ext-usage: false
full-authority-key-identifier: false
allow-ca-certs: false
allow-client-certs: false
allow-server-certs: true
distribute:
  to: inherit

Retrieve the configuration of a tls ca role

Roles allow for tighter control over which certificates a user or approle is allowed to issue, both in terms of certificate type as well as certificate properties such as TTL

It is recommended that restricted roles are used to limit the exposure. A user or app role should only be given access to a specific role that has been tightly locked down to only allow issuing of certificates with the properties needed for the specific use case. This to limit the chance of unwanted certificates being generated.

SecurityaccessToken
Request
path Parameters
tls-ca-name
required
string <name>

name of tls-ca

tls-ca-role-name
required
string <name>

name of tls-ca-role

query Parameters
fields
string

Retrieve only requested fields from the resource

See section fields

validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

get/v1/config/strongbox/tls/ca/{tls-ca-name}/roles/{tls-ca-role-name}
Response samples 
name: cert-signer
cert-key-type: ecdsa
allowed-hosts:
  - www.acme.com
allowed-domains:
  - avassa.net
ttl: 1y
max-ttl: 1y355d
digest: sha256
allow-bare-domains: true
allow-subdomains: true
allow-any-name: true
allow-ip-sans: true
server-ext-usage: true
client-ext-usage: true
code-signing-ext-usage: false
full-authority-key-identifier: false
allow-ca-certs: false
allow-client-certs: false
allow-server-certs: true
distribute:
  to: inherit

Retrieve the state of all tls ca roles

Roles allow for tighter control over which certificates a user or approle is allowed to issue, both in terms of certificate type as well as certificate properties such as TTL

It is recommended that restricted roles are used to limit the exposure. A user or app role should only be given access to a specific role that has been tightly locked down to only allow issuing of certificates with the properties needed for the specific use case. This to limit the chance of unwanted certificates being generated.

SecurityaccessToken
Request
path Parameters
tls-ca-name
required
string <name>

name of tls-ca

query Parameters
fields
string

Retrieve only requested fields from the resource

See section fields

site
string

Send the request to the specfifed site

content
string <enumeration>

Filter descendant nodes in the response

Enum: "config" "nonconfig"
keys
string <enumeration>

Retrieve only the keys for the list

Value: "true"
count
string <enumeration>

Retrieve only the number of elements in the list

Value: "true"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

get/v1/state/strongbox/tls/ca/{tls-ca-name}/roles
Response samples 
- name: cert-signer
  cert-key-type: ecdsa
  allowed-hosts:
    - www.acme.com
  allowed-domains:
    - avassa.net
  ttl: 1y
  max-ttl: 1y355d
  digest: sha256
  allow-bare-domains: true
  allow-subdomains: true
  allow-any-name: true
  allow-ip-sans: true
  server-ext-usage: true
  client-ext-usage: true
  code-signing-ext-usage: false
  full-authority-key-identifier: false
  allow-ca-certs: false
  allow-client-certs: false
  allow-server-certs: true
  distribute:
    to: inherit
  distribution-status:
    to: none

Retrieve the state of a tls ca role

Roles allow for tighter control over which certificates a user or approle is allowed to issue, both in terms of certificate type as well as certificate properties such as TTL

It is recommended that restricted roles are used to limit the exposure. A user or app role should only be given access to a specific role that has been tightly locked down to only allow issuing of certificates with the properties needed for the specific use case. This to limit the chance of unwanted certificates being generated.

SecurityaccessToken
Request
path Parameters
tls-ca-name
required
string <name>

name of tls-ca

tls-ca-role-name
required
string <name>

name of tls-ca-role

query Parameters
fields
string

Retrieve only requested fields from the resource

See section fields

site
string

Send the request to the specfifed site

content
string <enumeration>

Filter descendant nodes in the response

Enum: "config" "nonconfig"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

get/v1/state/strongbox/tls/ca/{tls-ca-name}/roles/{tls-ca-role-name}
Response samples 
name: cert-signer
cert-key-type: ecdsa
allowed-hosts:
  - www.acme.com
allowed-domains:
  - avassa.net
ttl: 1y
max-ttl: 1y355d
digest: sha256
allow-bare-domains: true
allow-subdomains: true
allow-any-name: true
allow-ip-sans: true
server-ext-usage: true
client-ext-usage: true
code-signing-ext-usage: false
full-authority-key-identifier: false
allow-ca-certs: false
allow-client-certs: false
allow-server-certs: true
distribute:
  to: inherit
distribution-status:
  to: none

Invoke the check-ca operation

SecurityaccessToken
Request
path Parameters
tls-ca-name
required
string <name>

name of tls-ca

tls-ca-role-name
required
string <name>

name of tls-ca-role

Request Body schema:
offset
string <duration>
Default: "0s"

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

Time offset for testing.

Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/tls/ca/{tls-ca-name}/roles/{tls-ca-role-name}/check-ca
Request samples 
offset: 0s
Response samples 
renewed: true
activated: false
latest-expires-in: 128d
active-expires-in: 54d

Invoke the get-ca-cert operation

SecurityaccessToken
Request
path Parameters
tls-ca-name
required
string <name>

name of tls-ca

tls-ca-role-name
required
string <name>

name of tls-ca-role

Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/tls/ca/{tls-ca-name}/roles/{tls-ca-role-name}/get-ca-cert
Response samples 
cert: |
  -----BEGIN CERTIFICATE-----
  MIICHjCCAcSgAwIBAgITAKs1oS0ybeAUntauysqFuBeQlDAKBggqhkjOPQQDAjBl
  MRowGAYDVQQDExFBdmFzc2EgQVBJIHJvb3QgMjESMBAGA1UEBxMJU3RvY2tob2xt
  MQswCQYDVQQGEwJTRTEPMA0GA1UEChMGQXZhc3NhMRUwEwYDVQQLEwxkaXN0cmli
  dXRpb24wIhgPMjAyMTEyMjMyMzIwMTNaGA8yMDI3MDUxMTEwMDgxM1owZTEaMBgG
  A1UEAxMRQXZhc3NhIEFQSSByb290IDIxEjAQBgNVBAcTCVN0b2NraG9sbTELMAkG
  A1UEBhMCU0UxDzANBgNVBAoTBkF2YXNzYTEVMBMGA1UECxMMZGlzdHJpYnV0aW9u
  MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEzSauslxXPReRGQFzPKPamVN8KPiP
  h+6PQaTXa5EN0cYukD+VU8Guu9r+k7BBF0t6+kzxJ4v84uGqcS11BrbOPaNPME0w
  DgYDVR0PAQH/BAQDAgGGMBIGA1UdEwEB/wQIMAYBAf8CAQEwJwYDVR0fBCAwHjAc
  oBqgGIYWaHR0cDovL2NybC5hdmFzc2EubmV0LzAKBggqhkjOPQQDAgNIADBFAiEA
  1zOd7AGv/56MOFYAUa9WqJSBwBwncUkUdRcoMHNw5zoCIGeIgBFg5qxGU4SxwwWV
  ZQYSJpKqUCz7uo9HvItC3A7S
  -----END CERTIFICATE-----
  -----BEGIN CERTIFICATE-----
  MIICGDCCAb+gAwIBAgISMeZQ4HpjHhrLayS5JedHqb5vMAoGCCqGSM49BAMCMGMx
  GDAWBgNVBAMTD0F2YXNzYSBBUEkgcm9vdDESMBAGA1UEBxMJU3RvY2tob2xtMQsw
  CQYDVQQGEwJTRTEPMA0GA1UEChMGQXZhc3NhMRUwEwYDVQQLEwxkaXN0cmlidXRp
  b24wIhgPMjAyMTEyMzEwNjMxMTdaGA8yMDI1MDUxMTEwMDcxN1owYzEYMBYGA1UE
  AxMPQXZhc3NhIEFQSSByb290MRIwEAYDVQQHEwlTdG9ja2hvbG0xCzAJBgNVBAYT
  AlNFMQ8wDQYDVQQKEwZBdmFzc2ExFTATBgNVBAsTDGRpc3RyaWJ1dGlvbjBZMBMG
  ByqGSM49AgEGCCqGSM49AwEHA0IABCMdQb+jMkUsk2ZcuvpvsN5teiV5ia/Gsfgx
  GgQ4qDmBRFxNrfuj34uD8QCTImxijm5zJHaIwYIxQLJ9fi+SJiyjTzBNMA4GA1Ud
  DwEB/wQEAwIBhjASBgNVHRMBAf8ECDAGAQH/AgEBMCcGA1UdHwQgMB4wHKAaoBiG
  Fmh0dHA6Ly9jcmwuYXZhc3NhLm5ldC8wCgYIKoZIzj0EAwIDRwAwRAIgXHevBN00
  3omcAE1ryOvL8NbzpsRFjoAR2SVVj3HT454CIHR7hEVtX/FZ+Qdy7kzz3kArX2H/
  2l/pX1YONDXlyvHM
  -----END CERTIFICATE-----

Invoke the issue-cert operation

SecurityaccessToken
Request
path Parameters
tls-ca-name
required
string <name>

name of tls-ca

tls-ca-role-name
required
string <name>

name of tls-ca-role

Request Body schema:
version
integer <uint32>

CA certificate version to use when issuing certificate. If not specified, the current active version will be used.

ttl
string <duration>

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

Time the certificate should be valid, starting from the time when the certificate is issued.

truncate-ttl
boolean
Default: false

Automatically limit the TTL to the lifetime of the CA certificate. If this is set to 'false' then an error will be generated if a certificate is requested that has a TTL that is longer then the lifetime of the CA certificate.

host
string

Name of client or server, used as CN (common name) and SAN (subject alt name) in issued certificate.

public-key
string

If a public-key is provided the cert will be based on that key instead of generating a new key-pair. This is preferred since the private key does not have to be transported. If CSRs (certificate signing requests) are used, then the private keys are embedded in that.

cert-type
string <enumeration>
Default: "client"
  • ca
  • client
  • server

Sets default attributes associated with certificate use.

pathlen-constraint
integer <uint32>

Valid when: ../cert-type = 'ca'

The issued certificate will have the basic constraint pathLen set to this value. It is used to limit the length of a trust chain originating from the issued certificate.

Array of objects

Configure additional certificate alternate name extensions for the issued certificate.

server-ext-usage
boolean

Adds the ServerAuth flag to Extended Key Usage attribute of the generated certificates.

client-ext-usage
boolean

Adds the ClientAuth flag to Extended Key Usage attribute of the generated certificates.

code-signing-ext-usage
boolean

Adds the CodeSigning flag to Extended Key Usage attribute of the generated certificates.

full-authority-key-identifier
boolean

Include key authority serial and name, in addition to key.

serial-prefix
string <hex-string> ^([0-9a-fA-F]{2}(:[0-9a-fA-F]{2})*)?$

The certificate serial, a 144 bit number, can optionally have a fixed prefix (up to 80 bits), the rest will be a random number consisting of a minimum of 64 bits.

Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/tls/ca/{tls-ca-name}/roles/{tls-ca-role-name}/issue-cert
Request samples 
version: 1
ttl: 15d
truncate-ttl: false
host: tio.avassa.net
public-key: |
  -----BEGIN PUBLIC KEY-----
  MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAprsthcrQ/Ug6leQQAjna
  QmLN1QDvjPs2wB6BXfwsW+KnMKCAQmv2eKpE2ZmpHoHxyz4JYhFm5vRCbl5AjM+1
  m3MvPAEP6LkDKK1blOpOinv21WW1rjC6kC2TEEI54gDMW0XBZqIYJUD7gP02zpNe
  jsZTELRrD8w55HIAe38doEg+TqEgYo4CIKM/ivh8SXi1alI3N7Gi8K8oKXh8azhY
  u9FHVig13HSym9E5zreF32CKSiQMS4cyyH1DXAQg/v9X6uBtga1HD33SYeXTNaga
  1L6Gn9AcCeBwmcmImTeA49NedAqoLMFZSZlR3C3bsspN0rtWyroO00QpyFqpHMYx
  GQIDAQAB
  -----END PUBLIC KEY-----
cert-type: server
alt-name:
  - type: DNSName
    value: foo
  - type: DNSName
    value: bar
server-ext-usage: true
client-ext-usage: true
code-signing-ext-usage: true
full-authority-key-identifier: false
serial-prefix: fe:ed:ba:be
Response samples 
cert: |
  -----BEGIN CERTIFICATE-----
  MIIDUDCCAvagAwIBAgITAKYom2ar3MFwt//DipR5NywBdjAKBggqhkjOPQQDAjBa
  MQ8wDQYDVQQDEwZBdmFzc2ExEjAQBgNVBAcTCVN0b2NraG9sbTELMAkGA1UEBhMC
  U0UxDzANBgNVBAoTBkF2YXNzYTEVMBMGA1UECxMMZGlzdHJpYnV0aW9uMCIYDzIw
  MjIwMTEyMDYyMTQ4WhgPMjAyMjAxMjcwOTU3NDhaMGIxFzAVBgNVBAMTDnRpby5h
  dmFzc2EubmV0MRIwEAYDVQQHEwlTdG9ja2hvbG0xCzAJBgNVBAYTAlNFMQ8wDQYD
  VQQKEwZBdmFzc2ExFTATBgNVBAsTDGRpc3RyaWJ1dGlvbjCCASIwDQYJKoZIhvcN
  AQEBBQADggEPADCCAQoCggEBAKa7LYXK0P1IOpXkEAI52kJizdUA74z7NsAegV38
  LFvipzCggEJr9niqRNmZqR6B8cs+CWIRZub0Qm5eQIzPtZtzLzwBD+i5AyitW5Tq
  Top79tVlta4wupAtkxBCOeIAzFtFwWaiGCVA+4D9Ns6TXo7GUxC0aw/MOeRyAHt/
  HaBIPk6hIGKOAiCjP4r4fEl4tWpSNzexovCvKCl4fGs4WLvRR1YoNdx0spvROc63
  hd9gikokDEuHMsh9Q1wEIP7/V+rgbYGtRw990mHl0zWoGtS+hp/QHAngcJnJiJk3
  gOPTXnQKqCzBWUmZUdwt27LKTdK7Vsq6DtNEKchaqRzGMRkCAwEAAaOBwzCBwDB+
  BgNVHSMEdzB1oV6kXDBaMQ8wDQYDVQQDEwZBdmFzc2ExEjAQBgNVBAcTCVN0b2Nr
  aG9sbTELMAkGA1UEBhMCU0UxDzANBgNVBAoTBkF2YXNzYTEVMBMGA1UECxMMZGlz
  dHJpYnV0aW9ughMAp0MSfyaImp0XtPO3uqCnMRITMCMGA1UdEQQcMBqCDnRpby5h
  dmFzc2EubmV0ggNmb2+CA2JhcjALBgNVHQ8EBAMCA4gwDAYDVR0TAQH/BAIwADAK
  BggqhkjOPQQDAgNIADBFAiAssZp0WV7ejre85Zh4LJZQiTVWEObLXRwifAHQoiqi
  iwIhAOga9thMhWISM1FFgSTeNUtUe9jziVdPfSYQpInAcg3V
  -----END CERTIFICATE-----
private-key: |
  -----BEGIN EC PRIVATE KEY-----
  MHcCAQEEIOXuM9bGiQDY9UwAY/8RgJqV+5vq8XIURRKkrAWNQuhvoAoGCCqGSM49
  AwEHoUQDQgAENBCgxypqoxzHtxQjqVueMP/MrfboR7C0ix/58VYrEmiOjcWjfyrh
  5mHkSHhOuWG9Y9kBQEit0HGZqFdwtvofOg==
  -----END EC PRIVATE KEY-----
serial: a6:28:9b:66:ab:dc:c1:70:b7:ff:c3:8a:94:79:37:2c:01:76
created: 2022-01-25T09:57:48.000000Z
expires: 2022-01-27T09:57:48.000000Z
version: 1
ca-cert: |
  -----BEGIN CERTIFICATE-----
  MIIDUDCCAvagAwIBAgITAKYom2ar3MFwt//DipR5NywBdjAKBggqhkjOPQQDAjBa
  MQ8wDQYDVQQDEwZBdmFzc2ExEjAQBgNVBAcTCVN0b2NraG9sbTELMAkGA1UEBhMC
  U0UxDzANBgNVBAoTBkF2YXNzYTEVMBMGA1UECxMMZGlzdHJpYnV0aW9uMCIYDzIw
  MjIwMTEyMDYyMTQ4WhgPMjAyMjAxMjcwOTU3NDhaMGIxFzAVBgNVBAMTDnRpby5h
  dmFzc2EubmV0MRIwEAYDVQQHEwlTdG9ja2hvbG0xCzAJBgNVBAYTAlNFMQ8wDQYD
  VQQKEwZBdmFzc2ExFTATBgNVBAsTDGRpc3RyaWJ1dGlvbjCCASIwDQYJKoZIhvcN
  AQEBBQADggEPADCCAQoCggEBAKa7LYXK0P1IOpXkEAI52kJizdUA74z7NsAegV38
  LFvipzCggEJr9niqRNmZqR6B8cs+CWIRZub0Qm5eQIzPtZtzLzwBD+i5AyitW5Tq
  Top79tVlta4wupAtkxBCOeIAzFtFwWaiGCVA+4D9Ns6TXo7GUxC0aw/MOeRyAHt/
  HaBIPk6hIGKOAiCjP4r4fEl4tWpSNzexovCvKCl4fGs4WLvRR1YoNdx0spvROc63
  hd9gikokDEuHMsh9Q1wEIP7/V+rgbYGtRw990mHl0zWoGtS+hp/QHAngcJnJiJk3
  gOPTXnQKqCzBWUmZUdwt27LKTdK7Vsq6DtNEKchaqRzGMRkCAwEAAaOBwzCBwDB+
  BgNVHSMEdzB1oV6kXDBaMQ8wDQYDVQQDEwZBdmFzc2ExEjAQBgNVBAcTCVN0b2Nr
  aG9sbTELMAkGA1UEBhMCU0UxDzANBgNVBAoTBkF2YXNzYTEVMBMGA1UECxMMZGlz
  dHJpYnV0aW9ughMAp0MSfyaImp0XtPO3uqCnMRITMCMGA1UdEQQcMBqCDnRpby5h
  dmFzc2EubmV0ggNmb2+CA2JhcjALBgNVHQ8EBAMCA4gwDAYDVR0TAQH/BAIwADAK
  BggqhkjOPQQDAgNIADBFAiAssZp0WV7ejre85Zh4LJZQiTVWEObLXRwifAHQoiqi
  iwIhAOga9thMhWISM1FFgSTeNUtUe9jziVdPfSYQpInAcg3V
  -----END CERTIFICATE-----

Invoke the renew-cert operation

Renews a certificate if needed. The action first verifies that the certificate given as argument is signed by the CA, then examines the expiration time. If the refresh threshold has been reached then a new certificate is generated, together with a new public key.

SecurityaccessToken
Request
path Parameters
tls-ca-name
required
string <name>

name of tls-ca

tls-ca-role-name
required
string <name>

name of tls-ca-role

Request Body schema:
version
integer <uint32>

CA certificate version to use when issuing certificate. If not specified, the current active version will be used.

cert
required
string

If a public-key is provided the cert will be based on that key instead of generating a new key-pair. This is preferred since the private key does not have to be transported. If CSRs (certificate signing requests) are used, then the private keys are embedded in that.

threshold
required
string <duration>

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

Threshold for renewing the certificate. If the cert is valid for longer than the threshold, then it is not renewed.

ttl
string <duration>

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

If a new certificate is generated, use this ttl.

force
boolean

Force renew even if the certificate expiration time has not reached the threshold.

Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/tls/ca/{tls-ca-name}/roles/{tls-ca-role-name}/renew-cert
Request samples 
version: 1
cert: |
  -----BEGIN CERTIFICATE-----
  MIICizCCAjGgAwIBAgITANNt94hZ1dY/yf1V21FDUK6xVzAKBggqhkjOPQQDAjBg
  MRUwEwYDVQQDEwxpbnRlcm1lZGlhdGUxEjAQBgNVBAcTCVN0b2NraG9sbTELMAkG
  A1UEBhMCU0UxDzANBgNVBAoTBkF2YXNzYTEVMBMGA1UECxMMZGlzdHJpYnV0aW9u
  MCIYDzIwMjIwMTEyMDU1MzIxWhgPMjAyMjAxMjcwOTI5MjFaMGIxFzAVBgNVBAMT
  DnRpby5hdmFzc2EubmV0MRIwEAYDVQQHEwlTdG9ja2hvbG0xCzAJBgNVBAYTAlNF
  MQ8wDQYDVQQKEwZBdmFzc2ExFTATBgNVBAsTDGRpc3RyaWJ1dGlvbjBZMBMGByqG
  SM49AgEGCCqGSM49AwEHA0IABP12drrHCZgUNGKY4+AirpP8Srjtuf2wUYLyOELu
  5w+Q4bPBUOBnT0VQ7MJEGH1CS4TdBDZMmc/sC8iS6zqGjaujgcMwgcAwfgYDVR0j
  BHcwdaFepFwwWjEPMA0GA1UEAxMGQXZhc3NhMRIwEAYDVQQHEwlTdG9ja2hvbG0x
  CzAJBgNVBAYTAlNFMQ8wDQYDVQQKEwZBdmFzc2ExFTATBgNVBAsTDGRpc3RyaWJ1
  dGlvboITAN7Ag9ldW5mmpYKFnCWuYLZqaDAjBgNVHREEHDAagg50aW8uYXZhc3Nh
  Lm5ldIIDZm9vggNiYXIwCwYDVR0PBAQDAgOIMAwGA1UdEwEB/wQCMAAwCgYIKoZI
  zj0EAwIDSAAwRQIhAPAEa0/l9oOmLfRVKjDVFFcw81q91diNmERB3bOWc6X8AiB5
  jYenpXwkbchHtu3etE0/3FzLSVTN453CDVU6gIAtJw==
  -----END CERTIFICATE-----
threshold: 15d
ttl: 15d
force: true
Response samples 
cert: |
  -----BEGIN CERTIFICATE-----
  MIICizCCAjGgAwIBAgITAOlTFCbPxuMxTI7XY0XnZxm6xDAKBggqhkjOPQQDAjBg
  MRUwEwYDVQQDEwxpbnRlcm1lZGlhdGUxEjAQBgNVBAcTCVN0b2NraG9sbTELMAkG
  A1UEBhMCU0UxDzANBgNVBAoTBkF2YXNzYTEVMBMGA1UECxMMZGlzdHJpYnV0aW9u
  MCIYDzIwMjIwMTEyMDU1MzIxWhgPMjAyMjAxMjcwOTI5MjFaMGIxFzAVBgNVBAMT
  DnRpby5hdmFzc2EubmV0MRIwEAYDVQQHEwlTdG9ja2hvbG0xCzAJBgNVBAYTAlNF
  MQ8wDQYDVQQKEwZBdmFzc2ExFTATBgNVBAsTDGRpc3RyaWJ1dGlvbjBZMBMGByqG
  SM49AgEGCCqGSM49AwEHA0IABJxqeVJyPzB1TIpL6//bWCrrrrk9D3JkGBv4DHEk
  eBoXgDfV8n8Ni5m5PtazeJE+91WX0yhRCGZVRyohpzbx8+qjgcMwgcAwfgYDVR0j
  BHcwdaFepFwwWjEPMA0GA1UEAxMGQXZhc3NhMRIwEAYDVQQHEwlTdG9ja2hvbG0x
  CzAJBgNVBAYTAlNFMQ8wDQYDVQQKEwZBdmFzc2ExFTATBgNVBAsTDGRpc3RyaWJ1
  dGlvboITAN7Ag9ldW5mmpYKFnCWuYLZqaDAjBgNVHREEHDAagg50aW8uYXZhc3Nh
  Lm5ldIIDZm9vggNiYXIwCwYDVR0PBAQDAgOIMAwGA1UdEwEB/wQCMAAwCgYIKoZI
  zj0EAwIDSAAwRQIgWgpHPxZ5Y/U1a2jlMqyojqy0ux5T9a15gc1BXmj3MegCIQD8
  Lxclz6XhhIsMoOpBTX45gFMJmhDOisflmcsCumup9A==
  -----END CERTIFICATE-----
private-key: |
  -----BEGIN EC PRIVATE KEY-----
  MHcCAQEEIA69qgOw6+y/6aDASXFWtK17P98TvTlKcWZ3H5IZKDF4oAoGCCqGSM49
  AwEHoUQDQgAEnGp5UnI/MHVMikvr/9tYKuuuuT0PcmQYG/gMcSR4GheAN9Xyfw2L
  mbk+1rN4kT73VZfTKFEIZlVHKiGnNvHz6g==
  -----END EC PRIVATE KEY-----
serial: e9:53:14:26:cf:c6:e3:31:4c:8e:d7:63:45:e7:67:19:ba:c4
expires: 2022-01-27T09:29:21.000000Z

Invoke the revoke-cert operation

SecurityaccessToken
Request
path Parameters
tls-ca-name
required
string <name>

name of tls-ca

tls-ca-role-name
required
string <name>

name of tls-ca-role

Request Body schema:
version
integer <uint32>

CA certificate version to use when revoking certificate. If not specified, the current active version will be used.

serial
required
string <hex-string> ^([0-9a-fA-F]{2}(:[0-9a-fA-F]{2})*)?$
revoke-time
string <date-time>
reason
string <revoke-reason-type>
Default: "unspecified"
  • unspecified
  • keyCompromise
  • cACompromise
  • affiliationChanged
  • superseded
  • cessationOfOperation
  • certificateHold
  • privilegeWithdrawn
  • aAcompromise Reason for revoking a certificate.
Responses
204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/tls/ca/{tls-ca-name}/roles/{tls-ca-role-name}/revoke-cert
Request samples 
version: 1
serial: 02:59:cd:ba:9a:c3:7b:81:ad:d4:8b:be:35:f1:e3:10:a1:fa
revoke-time: 2023-01-12T09:27:23.000000Z
reason: keyCompromise

Invoke the rotate-ca operation

SecurityaccessToken
Request
path Parameters
tls-ca-name
required
string <name>

name of tls-ca

tls-ca-role-name
required
string <name>

name of tls-ca-role

Request Body schema:
ttl
string <duration>

A duration in years, days, hours, minutes and seconds.

Format is [<digits>y][<digits>d][<digits>m][<digits>s].

Examples: 1y2d5h, 5h or 10m30s

TTL of new certificate. It will default to the TTL of the old certificate.

Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/strongbox/tls/ca/{tls-ca-name}/roles/{tls-ca-role-name}/rotate-ca
Request samples 
ttl: 1y
Response samples 
ca-cert: |
  -----BEGIN CERTIFICATE-----
  MIICHTCCAcOgAwIBAgISWNECRJYLYnewT+3Ujk574sRJMAoGCCqGSM49BAMCMGUx
  GjAYBgNVBAMTEUF2YXNzYSBBUEkgcm9vdCAyMRIwEAYDVQQHEwlTdG9ja2hvbG0x
  CzAJBgNVBAYTAlNFMQ8wDQYDVQQKEwZBdmFzc2ExFTATBgNVBAsTDGRpc3RyaWJ1
  dGlvbjAiGA8yMDIyMDEwODE4NDk1NFoYDzIwMjMwMTEyMTAyNTU0WjBlMRowGAYD
  VQQDExFBdmFzc2EgQVBJIHJvb3QgMjESMBAGA1UEBxMJU3RvY2tob2xtMQswCQYD
  VQQGEwJTRTEPMA0GA1UEChMGQXZhc3NhMRUwEwYDVQQLEwxkaXN0cmlidXRpb24w
  WTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASvGeQvFMppCCzWIuoC9aLlPa+LMFec
  pPcRKkPxNKnFgfxxQkj8BxHFK983DkQPRN8DqLTnVu9PlbHF9vafoCZEo08wTTAO
  BgNVHQ8BAf8EBAMCAYYwEgYDVR0TAQH/BAgwBgEB/wIBATAnBgNVHR8EIDAeMByg
  GqAYhhZodHRwOi8vY3JsLmF2YXNzYS5uZXQvMAoGCCqGSM49BAMCA0gAMEUCIQCn
  rmajChgRM8BwDUr205011d/ra3spqDQqz+z32DjZEwIgNJp+7hOxQxUwejpDamRW
  BcbypHLoQkU/SCFeASg47vs=
  -----END CERTIFICATE-----
expires: 2023-01-12T10:25:54.000000Z
version: 2
➔ Next to TLS CAs