Tenant Policy Configuration

General configuration fields

The following fields are general definitions for a tenant policy.

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

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

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.

Sample acme.policy.json contents

{
    "url": "acme",
    "version": "1.0.0",
    "description": "Acme Pilot",
    "status": "enabled",
    "certPolicyLevel": "3",
    "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
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
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
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

OCSP validation

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

Sub Policies

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

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
ignoreExpiredCertificate	no	Sets Debbie validator to take expired certificates as valid ones.	true	false
ignoreSigningTime	no	Sets Debbie validator to disable checks of the signature date.	true	false
signatureValidityWindow	no	Sets a validity window to check the signature date.	-5:30	not set
checkCoversWholeDocument	no	Sets Debbie validator to give an error message in case a signature does not cover a whole PDF document.	true	false
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",
    "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",
	        "ignoreExpiredCertificate": "false",
	        "ignoreSigningTime": "false",
	        "certPolicyLevel": "2",
	        "signatureValidityWindow": "-5:30",
	        "checkCoversWholeDocument": "true"
	    },
	    {
	        "url": "renew",
	        "certValidityWindow": "-30:30"
	    }
	] 
}