Debbie: Policy Configuration

Every Debbie policy configuration file has two to well-defined sections that must be configured in order to validate an End User Certificate for a given tenant.

1 General configuration fields
2 Trust Anchors
3 CRL validation
4 OCSP validation
5 Sub Policies
6 Sample Policy File

Case sensitive

All policy configuration field values are case sensitive.

General configuration fields

The following fields are general definitions for a tenant policy.

Field	Required	Description	Example

Field	Required	Description	Example
url	yes	URL where the policy validation service for a tenant is available. If several policies have the same URL in the policy configuration file, only the first one found will work. For example, the policy will be accessible on "/acme".	acme
version	yes	Policy configuration version.	1.0.0
description	yes	Policy configuration description.	Acme Pilot
status	yes	Indicates if this policy is enabled. This field allows to have several definitions but only keep one of them active. Possible values are enabled or disabled.	enabled
encoding	no	This field is used to select the character set used by the signed text, especially when it has been generated on a Web page that can be browser dependent. The possible values are all those Character Sets that can be defined in every platform. If none is indicated, "UTF-8" is taken as default.	ISO-8859-1
certPolicyLevel	yes	Sets the signature's certificate validation level. See Policy Level table below for more details.	1
validationTimeLevel	no	Sets the signature's validation time level. See Validation Time Level table below for more details. By default is set to "1".	1

The following table represents the possible values for the certPolicyLevel field.

Level	Value	Description

Level	Value	Description
0	NONE	There is no evaluation of the signing certificate. Any certificate is accepted.
1	TRUSTED	There is no evaluation of the signing certificate, ocspEnabled and crlEnabled must be false on the trust anchors.
2	CRL	The signer's validation result is evaluated only by CRL, ocspEnabled must be false and crlEnabled must be true on the trust anchors.
3	OCSP then CRL	The signer's validation result is evaluated by OCSP, if this fails is validated by CRL, ocspEnabled and crlEnabled must be true on the trust anchors. If this option is active, and any of the certificates are validated through CRL, then the final result of the validation will be WARNING.
4	OCSP	The signer's validation result is evaluated only by OCSP, ocspEnabled must be true and crlEnabled must be false on the trust anchors. If this option is active, and any of the certificates cannot be validated by OCSP, then the final result of the validation will be ERROR.

The following table represents the possible values for the validationTimeLevel field.

Level	Value	Description

Level	Value	Description
0	VALIDATE at SIGN_TIME with EXPIRED CERTIFICATE	There is no restriction of the signature signing time. Any signing time is accepted. Signatures with expired certificates are considered valid.
1	VALIDATE at SIGN_TIME	There is no restriction of the signature signing time.Any signing time source is accepted. The signing time must be into the validity period of the certificate.
2	VALIDATE at TSASIGNINGTIME	A TSA signing time is required for all signatures. There is no evaluation of the timestamp signing certificates.
3	VALIDATE at TRUSTED TSASIGNINGTIME	A TSA signing time is required for all signatures. The timestamp signing certificates are evaluated within the defined trust anchors.

Sample acme.policy.json contents

{
    "url": "acme",
    "version": "1.0.0",
    "description": "Acme Pilot",
    "status": "enabled",
    "certPolicyLevel": "3",
    "validationTimeLevel": "2",
    "trust": [
       ...
    ] 
}

Trust Anchors

A trust anchor represents the list of trusted Certificate Authorities needed to validate an End-User certificate. The following are the possible fields that can be used to define a trust anchor for a given Certificate Authority.

Field	Description	Example

Field	Description	Example
caCert	Certificate file for the Certification Authority in DER format.	config/certstore/CA.root.ClassB.G1.cer
certFilter	Details a specific filter defined on this policy. It can be by any field of the Subject or Issuer. The example restricts the policy to accept exclusively End-User Certificates where the O (Organization) field included in the Subject field contains the text: “Acme Inc”.	filters=subject.rfc2254:(O=Acme Inc)

Sample "tenant.policy.json" trust anchors definitions

{
    ...
    "trust": [
        {
            "caCert": "config/certstore/CertiSur.root.ClassB.G1.pilot.509.cer"
        },
        {
            "caCert": "config/certstore/CertiSur.shared.ClassB.G1.pilot.509.cer",
            "certFilter": "filters=subject.rfc2254:(O=Acme Inc)"            
        }
    ]
}

CRL validation

Field	Description	Example

Field	Description	Example
crlEnabled	CRL validation for the certificates issued by caCert is enabled. Possible values are true or false.	true
crlURL	See crlURL table below for more details.	http://pki-crl.symauth.com/ca_4..3/LatestCRL.crl

The following table represents the possible values for the "crlURL" field.

CRL Field	Description	Example

CRL Field	Description	Example
URL	If Internet access is available from the server where Debbie is installed, it is advisable to configure this field with the CRL URL. Debbie will download it every time it is needed or if the previously downloaded CRL has expired.	http://pki-crl.symauth.com/ca\_45a68..3/LatestCRL.crl
file URI	If there is no Internet access from the server where Debbie is installed, the CRL can be downloaded from another server and copied to the location cacheDir defined on Debbie configuration file. The downloaded CRL must be referenced with this variable.	file://http\_\_\_pki-crl\_symauth\_com\_ca\_45..d3\_LatestCRL\_crl
crlTimeout	Overwrite the expiration date of the CRL by a shorter value. If this value is different than 0, the next CRL will be downloaded at (CurrentCRL.ThisUpdate + crlTimeout) when crlTimeout is a positive value in seconds. 1hs = 3600, 6hs = 21600,	21600
caPurgesCRL	Number of retention days in which an expired certificate is kept in the CRL by the CA. After that It is not possible to determine the revocation status for an expired certificate. If your CA does not purge the CRL you MUST set this to -1. By default is set to 30 days.	30

Sample "tenant.policy.json" sub policies definitions

{
        ...
        {
            "caCert": "config/certstore/CertiSurClase3ACServiciosG1.prod.cer",
            "crlEnabled": "true",
            "caPurgesCRL": "false",
            "crlURL": "http://crl.certisur.net/C3/CertiSurClase3ACServiciosG1/latest.crl",
            "crlTimeout": "0"
        }
}

OCSP validation

Field	Description	Example

Field	Description	Example
ocspEnabled	OCSP validation for the certificates issued by caCert is enabled. Possible values are true or false.	true
ocspURL	OCSP Responder URL.	http://pki-ocsp.digicert.com
ocspCert	OCSP Responder signing certificate. This is necessary to verify the OCSP Response.	config/certstore/Sant..OCSP_responder.prod.509
testUserCert	End-User certificate to validate with the OCSP Responder. This is used to check if the OCSP Responder is available.	config/certstore/San..test_user.prod.509
caPurgesCRL	Number of retention days in which an expired certificate is kept in the CRL by the CA. After that It is not possible to determine the revocation status for an expired certificate. If your CA does not purge the CRL you MUST set this to -1. By default is set to 30 days.	30

Sub Policies

A sub policy represents a set of modifiers that applies to a specific end-entity trust anchor.

Field	Required	Description	Example	Default

Field	Required	Description	Example	Default
url	yes	URL where the sub policy validation service for a tenant is available. If several sub-policies have the same URL in the policy configuration file, only the first one found will work. For example, the sub policy will be accessible on "/acme/renew".	renew
certPolicyLevel	no	Overrides the signature's certificate validation level. See Policy Level table below for more details.	1	Parent policy value
certValidityWindow	no	Sets a validity window to check the certificate expiration date. This allows taking an expired certificate as valid if it is in that window.	-30:30	not set

Sample "tenant.policy.json" sub policies definitions

{
    ...
	"subpolicy": [
	    {
	        "url": "padessignature",
	        "ignoreExpiredCertificate": "true",
	        "ignoreSigningTime": "true",
	        "certPolicyLevel": "2",
	        "signatureValidityWindow": "-5:30",
	        "checkCoversWholeDocument": "true"
	    },
	    {
	        "url": "renew",
	        "certValidityWindow": "-30:30"
	    }
	] 
}

Sample Policy File

Following is the content of the "acme.policy.json" demo configuration file included in with the validation service distribution.

Sample Debbie policy configuration file

{
    "url": "acme",
    "version": "3.0.0",
    "description": "Acme Pilot",
    "status": "enabled",
    "certPolicyLevel": "0",
    "validationTimeLevel": "1",
    "trust": [
        {
            "caCert": "config/certstore/CertiSur.root.ClassB.G1.pilot.509.cer"
        },
        {
            "caCert": "config/certstore/CertiSur.shared.ClassB.G1.pilot.509.cer",
            "certFilter": "filters=subject.rfc2254:(O=Acme Inc)"            
        }
    ],
	"subpolicy": [
	    {
	        "url": "padessignature",
	        "certPolicyLevel": "2"
	    },
	    {
	        "url": "renew",
	        "certValidityWindow": "-30:30"
	    }
	] 
}