system-certificate¶

Manage system certificates. Supported operations:

list certificates
show certificate content
configure Let's Encrypt
configure self-signed certificate
set default certificate

read¶

Input¶

It takes a mandatory action argument.

list¶

List all available certificates.

Example:

{
  "action": "list"
}

info¶

To retrieve a certificate, pass the name parameter to the read helper.

Example:

{
  "action": "info",
  "name":"/etc/pki/tls/certs/NSRV.crt"
}

Output¶

list¶

Internally, the helper calls /usr/libexec/nethserver/cert-list. Output current pki configuration and the list of existing certificates.

If some pki properties are empty, system defaults will be used to fill the returned object.

Example:

{
  "status": "",
  "configuration": {
    "pki": {
      "props": {
        "LetsEncryptMail": "",
        "SubjectAltName": "",
        "KeyFile": "",
        "CrtFile": "",
        "State": "",
        "EmailAddress": "",
        "ChainFile": "",
        "Organization": "",
        "CertificateDuration": "3650",
        "Locality": "",
        "LetsEncryptDomains": "",
        "CommonName": "",
        "LetsEncryptRenewDays": "30",
        "LetsEncrypt": "disabled",
        "CountryCode": "",
        "OrganizationalUnitName": ""
      },
      "name": "pki",
      "type": "configuration"
    },
    "certificates": [
      {
        "cn": "NethServer, O=Example Org, ST=SomeState, OU=Main",
        "file": "/etc/pki/tls/certs/NSRV.crt",
        "issuer": "NethServer, O=Example Org, ST=SomeState, OU=Main",
        "default": 1,
        "key": "/etc/pki/tls/private/NSRV.key",
        "chain": "",
        "expiration_t": 1795129200,
        "expired": 0
      }
    ]
  }
}

info¶

Internally, the helper calls /usr/libexec/nethserver/pki-info.

Output is base64 encoded:

{
  "certificate": "Q2Vyd .... "
}

validate¶

Constraints¶

Validate 3 different actions:

lets-encrypt
upload
self-signed

The action must be specified inside the JSON action field.

Example:

{
  "action": "upload",
  ...
}

Constraints for self-signed:

CountryCode: empty or 2 letters
State, Locality, Organization, OrganizationalUnitName, CommonName: valid x509 fields
EmailAddress: empty or valid mail address
SubjectAltName: comma-separated list of FQDNs

Constraints for lets-encrypt:

LetsEncryptMail: empty or valid mail address
LetsEncryptDomains: comma-separated list of FQDNs
LetsEncryptRenewDays: and integer greater than 10 and lower than 90
Check all Let's Encrypt conditions are met

Constraints for upload:

certificate: valid x509 certificate
chain: valid x509 certificate
key: valid key for running tlspolicy

Input¶

self-signed¶

action must be set to self-signed
pki record in json format

Example:

{
  "props": {
    "SubjectAltName": "t1.test.net,t2.test.net",
    "State": "myState",
    "EmailAddress": "",
    "Organization": "My company",
    "CertificateDuration": "3650",
    "Locality": "",
    "CommonName": "",
    "CountryCode": "it",
    "OrganizationalUnitName": ""
  },
  "action": "self-signed"
}

Invocation example:

echo '{"props":{"SubjectAltName":"t1.test.net,t2.test.net","State":"myState","EmailAddress":"","Organization":"My company","CertificateDuration":"3650","Locality":"","CommonName":"","CountryCode":"it","OrganizationalUnitName":"myoffice"},"action":"self-signed"}' | ./update

lets-encrypt¶

Manfatory fields:

action must be set to lets-encrypt
LetsEncryptMail
LetsEncryptDomains
LetsEncryptRenewDays

Example:

{
  "props": {
    "LetsEncryptMail": "",
    "LetsEncryptDomains": "test.local.net",
    "LetsEncryptRenewDays": "30",
  },
  "action": "lets-encrypt"
}

Warning: the UI shouldn't change the LetsEncrypt field.

upload¶

Format:

action must be set to upload
name is mandatory and set the name for the uploaded certs
certificate, key and chain must contain base64 encoded data
the chain field can be empty

{
  "action": "upload",
  "files": {
    "name": "mycert",
    "certificate": "...",
    "key": "...",
    "chain": "..."
  }
}

update¶

Available actions:

self-signed
lets-encrypt
upload
set-default

self-signed¶

Same input from validate.

lets-encrypt¶

Same input from validate.

upload¶

Same input from validate.

set-default¶

Mandatory fields: CrtFile, KeyFile and ChainFile. The ChainFile field can be empty.

Input example:

{
  "action": "set-default",
  "props": {
    "KeyFile": "/etc/pki/tls/private/NSRV.key",
    "CrtFile": "/etc/pki/tls/certs/NSRV.crt",
    "ChainFile": ""
  }
}