 |
Xentara v2.0.3
User Manual
|
|
Xentara v2.0.3
User Manual
|
The Xentara client certificate configuration file has the following format:
| $schema | An optional string value containing the URI of the JSON schema for Xentara client certificate configuration files. Xentara itself ignores this member, but some editors may use it to associate the model file with the correct JSON schema. The schema schould always point to https://docs.xentara.io/xentara/schema-xentara-client-certs.json. |
| rules | An optional JSON array containing the rules for checking client certificates. The format of the array is described below. |
| rootCertificates | An optional JSON array containing the root certificates of untrusted enterprise CAs. The format of the array is described under JSON Format for Issuer Root Certificates. |
A JSON schema file to validate client certificate configuration files is available here.
The JSON array containing the rules for checking client certificates has the following format:
Each JSON object in the array describes a single rule. The array can contain any combination of explicit rules and trust-based rules. The format for the corresponding JSON objects is described below.
The array can contain as many or as few entries as desired. If the array is empty, or if you omit rules parameter altogether, no rules will be defined, and authentication of remote clients via certificate-based authentication will not be possible.
JSON objects for explicit certificate rules only match a single certificate. The certificate can be specified either using a PEM encoded certificate file, or using the certificate fingerprint (aka thumbprint). The format of the two types of objects are as follows:
| certificatePath | A string value containing the path to the certificate file containing the client certificate. The certificate file is searched for as described under Certificate File Location. The certificate file must be a PEM encoded file containing the client certificate, as described in Certificate And Private Key File Structure. The rule will only match the first certificate in the file, which is usually the client certificate. This parameter cannot be used together with the fingerprint parameter. |
| fingerprint | A string value containing the SHA-256 or SHA-1 fingerprint (aka thumbprint) of the certificate. The format of the string is described under JSON Format for Binary Data. SHA-256 fingerprints must consist of 32 bytes of data totalling in 64 hexadecimal digits, and SHA-1 fingerprints must consist of 20 bytes of data totalling in 40 hexadecimal digits. This parameter cannot be used together with the certificatePath parameter. |
| roles | An optional JSON array containing the names of additional roles that should be assigned to clients whose certificate matches this rule. The role “Everyone” is assigned automatically to any authorized client, and should not appear in this array. If this array is empty, or of you do not specify this parameter, then clients will only be assigned the role “Everyone” through this this rule. |
The object must include either a certificatePath or a fingerprint member, but not both.
JSON objects for trust-based certificate rules contain the criteria used for matching a certificate. The object can also include additional roles to assign to matched certificates. The object has the following format:
| issuer | A string containing the distinguished name of the issuer that issued the certificate. This criterion is required. The name must be specified using first-to-last order. In this order, the first entry is ususally a country name (C) or domain component (DC), and the last entry is usually a common name (CN). |
| serialNumber | A string value containing the serial number of the certificate as a hexadecimal number. Since this is a JSON string value, the number must appear in quotes. The serial number can also be represented as binary data, as described under JSON Format for Binary Data. |
| SKI | A string value mathed against the subject key identifier (SKI) of the certificate. The format of the string is described under JSON Format for Binary Data. |
| subject | A string containing the full distinguished name of the subject the certificate was issued to. The name must be specified using first-to-last order. In this order, the first entry is ususally a country name (C) or domain component (DC), and the last entry is usually a common name (CN). |
| subjectPrefix | A string containing the beginning of the distinguished name of the subject the certificate was issued to. This criterion matches if the subject’s distinguished name begins with the given prefix. This criterion allows you, for example, to match the name of all subjects belonging to the same organizational unit (OU). The prefix must be specified using first-to-last order. In this order, the first entry is ususally a country name (C) or domain component (DC). |
| publicKeySHA256 | A string value containing the SHA-256 hash of the certificate’s public key. The format of the string is described under JSON Format for Binary Data. SHA-256 hashes must consist of 32 bytes of data totalling in 64 hexadecimal digits. |
| publicKeySHA1 | A string value containing the SHA-1 hash of the certificate’s public key. The format of the string is described under JSON Format for Binary Data. SHA-1 hashes must consist of 20 bytes of data totalling in 40 hexadecimal digits. |
| NTDSObjectSID | A string value containing the Active Directory (NTDS) object SID embedded into the certifivate’s ntdsCASecurityExt extension as described in the Microsoft knowledge base arcticle KB5014754. |
| roles | An optional JSON array containing the names of additional roles that should be assigned to clients whose certificate matches this rule. The role “Everyone” is assigned automatically to any authorized client, and should not appear in this array. If this array is empty, or of you do not specify this parameter, then clients will only be assigned the role “Everyone” through this this rule. |
See Trust-Based Certificate Rules for a more detailed description of the criteria.
The JSON array containing the root certificates of untrusted enterprise CAs contains a JSON object for each certification authority. The CAs are identified by their issuer property. Listing a certificate in this block is a more conservative alternative to installing it as a trusted root certificate in the operating system. Enterprise CAs whose root CA is already trusted should not appear in this array.
The array can contain as many or as few entries as desired. If the array is empty, or if you do not specify this parameter, only certificates issued by a trusted certification authority will be accepted.
The format of the individual JSON objects is as follows:
| issuer | A string containing the distinguished name of the issuer whose root certificate is contained in this block. The name must be specified using first-to-last order. In this order, the first entry is ususally a country name (C) or domain component (DC), and the last entry is usually a common name (CN). Note that this is the name of the certificate authority that actually issues the certificates, not the namne of the root CA. If the issuing CA is an intermediate CA, then this name should be the name of the intermediate CA, not the root CA. |
| certificatePath | A string value containing the path to the certificate file containing the root certificate for the issuer. The certificate file is searched for as described under Certificate File Location. It must be a PEM encoded file containing the root certificate, as described in Certificate And Private Key File Structure. The file must only contain a single certificate, files with multiple certificate blocks are not accepted. |