Table of Contents

maxLevel	2
indent	circle

Debbie is a tool used to validate certificates and signatures. Its REST interface allows an easy way to obtain a JSON response that indicates if a certificate is valid, and if it comply the validation policy.

Its services can be configured to respond over an HTTP or HTTPS protocol.

Debbie run over any JVM 1.8, and can be configured to run as a service on Windows or Linux OS.

Currently a new Docker distribution is available.

Connectivity

To perform the validation of the status of the certificates, and depending on the elements and policies that are configured, Debbie requires access to the services provided by the Certifying Authority.

These services are usually accessible through HTTP, both for the publication of the List of Revoked Certificates (CRL) and for OCSP (Online Certificate Status Protocol) services. It is convenient that you consider this need.

Service & Policy

Debbie responds to the requests in each of the URLs defined in its configuration files. Each defined policy must have its own unique URL, and there cannot be a defined URL within another.

At least one policy must be defined so that the service can be started.

CertiSur, to perform tests of the service, makes available the following URL where the service can be accessed:

https://homo-debbie.certisur.com:4443/<tenant>

Related Product

Alison SDK js

Alison SDK allows developer to integrate Alison Desktop in its pages in a easier way. Go to the Alison SDK documentation.

Alison Desktop

You can obtain current version of Alison Desktop from ACME Alison Wizard site.

For developers, go to the Alison Desktop documentation.

Distribution

Debbie is released in two different ways:

- A docker container,

- A .zip file to be installed as a service on Windows or Linux

To obtain a ZIP distribution, please contact CertiSur team at support@certisur.com.

CertiSur will share with you the .zip file in case you decide to use this option. But if you prefer the docker alternative, follow the below instructions:

Download Docker image

In order to download the images, user must be registered in the aforesaid platform. Contact CertiSur to request access, and inform the Docker Hub profile to grant access to the docker image.

Step 1- Login using a Docker Hub account

Code Block

language	bash
theme	DJango
title	Login Docker Hub

# docker login -u <docker hub account>
Password:
WARNING! Your password will be stored unencrypted in /root/.docker/config.json.
Configure a credential helper to remove this warning. See https://docs.docker.com/engine/reference/commandline/login/#credentials-store
Login Succeeded

Info

title	Inform your docker hub account

You have to inform your docker hub account in order to authorize to download the package. Send an email to support@certisur.com.

Note

title	Security warning

It is possible to save the user’s credentials so as to login safely following the steps on this link(https://docs.docker.com/engine/reference/commandline/login/#credentials-store).

Step 2- Pulling image from Docker

Code Block

language	bash
theme	DJango
title	Downloading image

# docker pull certisursa/debbie:latest

latest: Pulling from certisursa/debbie
a02a4930cb5d: Pull complete
b5ffff9dbcda: Pull complete
...
7e5f58de12ac: Pull complete
Digest: sha256:332ee89371399b7c6235465beb00fbd2071868fecee33fc14d04b87ba99b265d
Status: Downloaded newer image for certisursa/debbie:latest
docker.io/certisursa/debbie:latest

Step 3- Run debbie docker image

Code Block

language	bash
theme	DJango
title	Run Alison Wizard

# docker run -d \
-it \
-p <external_port>:8080 \
-v  <debbie_config_folder>:/app/config/ debbie

Info

title	Alison Wizard default configuration

Debbie docker image includes an ACME tenant inside. You must overwrite that definition to include your own company or project tenants.

Step 4- Configure docker image

It is necessary to overwrite the directory where configuration of the tenants are located. Follow volume configuration explained below.

Volumes

Following volumes must be mounted on the Docker image to overwrite variables of each defined tenant.

Source (host)	Path (container)	Description
/home/opera/docker/debbie/tenants	/app/config	configuration files
/home/opera/docker/debbie/log	/app/log	log files

Configuration

Debbie configuration file has 2 main objects into it:

server: defines communication and conectivity.
debbie: defines policies

Server Object

The server object defines the properties necessary to run the embedded Web server. By default the debbie.json file provided is setup to run the Web server on the following URL: "http://localhost:8080/".

Field	Required	Description	Default/Example
license	yes	License key provided by CertiSur.	20180814032223:dW5pdm.............RA==
ip	yes	Web server IP address	127.0.0.1
port	yes	Web server port number.	8080
protocol	yes	Web server protocol.	http
minThreadPool	yes	Minimum number of Web server threads.	10
maxThreadPool	yes	Maximum number of Web server threads.	30
timeout	yes	Internal Web server timeout.	5000

Code Block

language	text
theme	Eclipse
title	Server configuration

{
  "server": {
    "license": "20180814032223:dW5pdmVyc2FsPVo.............RA==",
    "ip": "127.0.0.1",
    "port": 8080,
    "protocol": "http",
    "minThreadPool": 10,
    "maxThreadPool": 30,
    "timeout": 5000
  }
}

For those environments where an SSL proxy / balancer is not available, an SSL certificate can be configured using the ssl object key in the server object definition. For more details of this feature check the user manual.

Code Block

language	text
title	SSL Configuration example

{
  "server": {
    ...
    "ssl": {
      "keyStoreFile": "ssl/keystore",
      "keyStorePassword": "OBF:1vny1zlp2x9e6vmw1vn61x8g1zau2vn4",
      "keyManagerPassword": "OBF:1u3u4wmn4z5s1z7a5wnl1u2g"
    },
    ...
  }
}

If you use a proxy server to download the CRLs or obtain OCSP responses, the proxy object key must be added in the server object definition.

Code Block

language	text
title	Sample Proxy Access configuration

{
  "server": {
    ...
    "proxy": {
      "server": "proxy.internal.local",
      "port": 3128
    },
    ...
  }
}

Debbie Objects

debbie object defines the properties necessary to run the validation service.

Field	Required	Description	Default
cacheDir	yes	Path where offline CRL files are stored when a download script is used.	cache/
policyDir	yes	Path where the validation policies are stored.	policies/
urlMaxRedirects	yes	Number of URL redirects supported to access CRL distribution points and OCSP responders.	1
crlConnectionTimeout	yes	CRL distribution point connection timeout. (msec)	2000
crlReadTimeout	yes	CRL distribution point read timeout. (msec)	5000
ocspConnectionTimeout	yes	OCSP responder connection timeout. (msec)	2000
ocspReadTimeout	yes	OCSP responder read timeout. (msec)	5000

Code Block

language	text
title	Sample configuration

{
  "debbie": {
    "cacheDir": "cache/",
    "policyDir": "policies/",
    "urlMaxRedirects": 1,
    "crlConnectionTimeout": 2000,
    "crlReadTimeout": 5000,
    "ocspConnectionTimeout": 2000,
    "ocspReadTimeout": 5000
  }
}

According to this configuration, the validation service is available at "http://localhost:8080". The policy configuration files can be found in "config/policies/".

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.

Note

title	Case sensitive

All policy configuration field values are case sensitive.

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.	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 is 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.

Code Block

language	text
title	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. 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)

CRL validation related fields

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 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 related fields

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 certiticate. 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

Logging

Logger names are assembled from the name of the URL where the service is published. Every "." found in the **"url"** field is replaced by "\_".

A special logger is defined for the system itself, it is called "debbieLog". Each tenant has 2 potentials loggers: <tenant>Log and <tenant>Audit. The latter only generates validation outputs, both successful and failed.

Note

title	case sensitive

All log configuration field values are case sensitive.

Each tenant can define its own logger file. Modify the following template to create your own log file. Replace <tenant> by your tenant name.

Code Block

language	text
title	Tenant Logger Template

# ---------------------------------------------------------
# <tenant>
# ---------------------------------------------------------
# Logger del servicio <tenant> (Auditoria)
log4j.logger.<tenant>Audit=INFO, <tenant>Appender
log4j.additivity.<tenant>Audit=false

# <tenant> Appender
log4j.appender.<tenant>Appender=org.apache.log4j.rolling.RollingFileAppender
log4j.appender.<tenant>Appender.rollingPolicy=org.apache.log4j.rolling.FixedWindowRollingPolicy
log4j.appender.<tenant>Appender.rollingPolicy.maxIndex=0
log4j.appender.<tenant>Appender.rollingPolicy.maxIndex=12
log4j.appender.<tenant>Appender.triggeringPolicy=org.apache.log4j.rolling.SizeBasedTriggeringPolicy
log4j.appender.<tenant>Appender.triggeringPolicy.MaxFileSize=10240000
log4j.appender.<tenant>Appender.rollingPolicy.FileNamePattern=${app.log.dir}/<tenant>-audit-%i.log.gz
log4j.appender.<tenant>Appender.rollingPolicy.ActiveFileName=${app.log.dir}/<tenant>-audit.log
log4j.appender.<tenant>Appender.layout=org.apache.log4j.PatternLayout
log4j.appender.<tenant>Appender.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} %-5p [%t]: %m%n

# ---------------------------------------------------------
# Logger del servicio <tenant> (Sistema)
log4j.logger.<tenant>Log=INFO, <tenant>Appender1
log4j.additivity.<tenant>Audit=false
# <tenant> Appender
log4j.appender.<tenant>Appender1=org.apache.log4j.rolling.RollingFileAppender
log4j.appender.<tenant>Appender1.rollingPolicy=org.apache.log4j.rolling.FixedWindowRollingPolicy
log4j.appender.<tenant>Appender1.rollingPolicy.minIndex=0
log4j.appender.<tenant>Appender1.rollingPolicy.maxIndex=12
log4j.appender.<tenant>Appender1.triggeringPolicy=org.apache.log4j.rolling.SizeBasedTriggeringPolicy
log4j.appender.<tenant>Appender1.triggeringPolicy.MaxFileSize=10240000
log4j.appender.<tenant>Appender1.rollingPolicy.FileNamePattern=${app.log.dir}/<tenant>-system-%i.log.gz
log4j.appender.<tenant>Appender1.rollingPolicy.ActiveFileName=${app.log.dir}/<tenant>-system.log
log4j.appender.<tenant>Appender1.layout=org.apache.log4j.PatternLayout
log4j.appender.<tenant>Appender1.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} %-5p [%t]: %m%n

Following is the content of the debbielog.properties configuration file included in with the validation service distribution.

Code Block

language	text
title	debbie-log.properties example

# Logger default
log4j.rootLogger=INFO

# ---------------------------------------------------------
# System Logger
log4j.logger.debbieLog=INFO, debbieAppender
log4j.additivity.debbieLog=false
# Debbie Appender
log4j.appender.debbieAppender=org.apache.log4j.FileAppender
log4j.appender.debbieAppender.file=${app.log.dir}/debbie-system.log
log4j.appender.debbieAppender.file.MaxFileSize=10MB
log4j.appender.debbieAppender.file.MaxBackupIndex=10
log4j.appender.debbieAppender.layout=org.apache.log4j.PatternLayout
log4j.appender.debbieAppender.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} %-5p [%t]: %m%n

# ---------------------------------------------------------
# ACME
# ---------------------------------------------------------
# ACME service Logger (Audit)
log4j.logger.acmeAudit=INFO, acmeAppender
log4j.additivity.acmeAudit=false

# ACME Appender
log4j.appender.acmeAppender=org.apache.log4j.rolling.RollingFileAppender
log4j.appender.acmeAppender.rollingPolicy=org.apache.log4j.rolling.FixedWindowRollingPolicy
log4j.appender.acmeAppender.rollingPolicy.maxIndex=0
log4j.appender.acmeAppender.rollingPolicy.maxIndex=12
log4j.appender.acmeAppender.triggeringPolicy=org.apache.log4j.rolling.SizeBasedTriggeringPolicy
log4j.appender.acmeAppender.triggeringPolicy.MaxFileSize=10240000
log4j.appender.acmeAppender.rollingPolicy.FileNamePattern=${app.log.dir}/acme-audit-%i.log.gz
log4j.appender.acmeAppender.rollingPolicy.ActiveFileName=${app.log.dir}/acme-audit.log
log4j.appender.acmeAppender.layout=org.apache.log4j.PatternLayout
log4j.appender.acmeAppender.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} %-5p [%t]: %m%n

# ---------------------------------------------------------
# ACME service Logger (System)
log4j.logger.acmeLog=INFO, acmeAppender1
log4j.additivity.acmeAudit=false

# ACME Appender
log4j.appender.acmeAppender1=org.apache.log4j.rolling.RollingFileAppender
log4j.appender.acmeAppender1.rollingPolicy=org.apache.log4j.rolling.FixedWindowRollingPolicy
log4j.appender.acmeAppender1.rollingPolicy.minIndex=0
log4j.appender.acmeAppender1.rollingPolicy.maxIndex=12
log4j.appender.acmeAppender1.triggeringPolicy=org.apache.log4j.rolling.SizeBasedTriggeringPolicy
log4j.appender.acmeAppender1.triggeringPolicy.MaxFileSize=10240000
log4j.appender.acmeAppender1.rollingPolicy.FileNamePattern=${app.log.dir}/acme-system-%i.log.gz
log4j.appender.acmeAppender1.rollingPolicy.ActiveFileName=${app.log.dir}/acme-system.log
log4j.appender.acmeAppender1.layout=org.apache.log4j.PatternLayout
log4j.appender.acmeAppender1.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} %-5p [%t]: %m%n

License

Depending on the kind of distribution used, you must request a extended license and install it.

Before request the new license, check that the following configuration is correcto.

Code Block

language	text
title	Configutation file

# IP where debbie listen
server.ip=<IP>

# Server port
server.port=8002

Run the following command:

Code Block

language	bash
theme	DJango
title	Request License Windows

c:> genlicense-win.bat

Code Block

language	bash
theme	DJango
title	Request License Windows

# genlicense-linux.sh

Send the request code regerated to support@certisur.com with the following aditional information:

Company Name
Contact name
eMail
Server Name (used to identify the request. It won't affect the license if you change this value in the future).
Environment (Develop/QA/Production)

You'll receive an email with the license, and included it into the configuration file like:

Code Block

language	text
title	License

server.license=20190601014449:GeIdlvYetkRld5CjlcDfzK9/KjuonNKIanpJ9xLShXRf434343rfFfsdfv444x+Fa3Xmezu3Acg3dTqcYKZtUqMWWCygtzleivcH9iHsbGbT3TkiMQvZWruhroVg46j9IlHTmPPx234luNTv943b3ZP2kEaU00mwAkyKnr9UHl44c=

Restart Debbie and check into the log file that the new license is working.

Version	Old Version 12	New Version 13
Changes made by	Armando Carratala	Armando Carratala
Saved on	Nov 22, 2019	Nov 23, 2019

Versions Compared

Key

Connectivity

Service & Policy

Related Product

Alison SDK js

Alison Desktop

Distribution

Download Docker image

Step 1- Login using a Docker Hub account

Step 2- Pulling image from Docker

Step 3- Run debbie docker image

Step 4- Configure docker image

Volumes

Configuration

Server Object

Debbie Objects

Debbie Policy Configuration

Trust Anchors

CRL validation related fields

OCSP validation related fields

Logging

License

Content Comparison

Versions Compared

Key

Connectivity

Service & Policy

Related Product

Alison SDK js

Alison Desktop

Distribution

Download Docker image

Step 1- Login using a Docker Hub account

Step 2- Pulling image from Docker

Step 3- Run debbie docker image

Step 4- Configure docker image

Volumes

Configuration

Server Object

Debbie Objects

Debbie Policy Configuration

Trust Anchors

CRL validation related fields

OCSP validation related fields

Logging

License