The External Command Certificate Validator allows validating issuance based on other certificate values after the certificate (or eventual pre-certificate) has been generated but not issued, stored and published.

Validator Types

External Command Certificate Validator

The External Command Certificate Validator allows calling an external script for the generated certificate. The exit code of the external call determines if the validation has failed. This can be used not only to validate certificate criteria, but also to call other external commands or scripts. The user running EJBCA's application server requires the OS file system permissions to do so.

To be able to view and edit the External Script Validator, access to external scripts must be enabled by activating Enable External Script Access under System Configuration>External Scripts. For more information, see External Scripts.

The first token of the External command field must be the external command or script called, followed by its arguments, all separated by spaces. The certificate is stored as a temporary file on the EJBCA server, and its full path is used as first argument. All subsequent arguments are shifted to the right. If the placeholder %cert% is used as an argument at any position, the certificate is not stored on the EJBCA server file system. Instead the placeholder is removed, and the PEM encoded certificate is fed to the external command or script via STDIN.

The platform for MS Windows and Unix/Linux is auto-detected and the default shell command and shell options are set:

MS Windows: cmd.exe /C
Unix/Linux: /bin/sh -c

The following displays examples of external commands for Unix/Linux platforms:

$ /usr/local/opt/script.sh -param1 -param2
$ /usr/local/opt/script.sh -param1 -param2 %cert%
$ openssl x509 -text -noout -in %cert%    

Script Whitelisting

An administrator can restrict which scrips can be executed for security reasons, by configuring a whitelist on the System Configuration External scripts tab. The whitelist should contain a list of paths to all scripts allowed to be executed by the External Command Certificate Validator. If the whitelist is enabled by an administrator, any execution of scripts not explicitly listed on the whitelist is prevented by EJBCA.

If the External Scripts Whitelist has been enabled by an administrator and a Validator tries to execute a command which is not on the whitelist, the "Validator was not applicable" action is carried out.

The whitelist is formatted according to the following: Each line contains the full path of the whitelisted script. Lines beginning with the character # are treated as comments. The whitelist can contain any number of scripts. An empty (enabled) whitelist will effectively block execution of all external scripts.

The following displays an example of a syntactically valid whitelist:

# -----------------------------------------------------------------------
# This is an example, this configuration does not necessarily make sense
# -----------------------------------------------------------------------
/bin/echo
# X.509 Certificate Linter by Amazon 
# https://github.com/awslabs/certlint
/opt/certlint/certlint
/opt/certlint/cablint
# X.509 Certificate Linter based on CA/B Forum Baseline Requirements and RFC 5280 
# https://github.com/zmap/zlint
/opt/scripts/zLint.sh
#/opt/scripts/IAmDisabled.sh

This whitelist allows the three scripts /opt/certlint/certlint, /opt/certlint/cablint, and /opt/scripts/zLint.sh to be executed. There is no restriction on the parameters which can be given as input to these scripts. Any input validation should be done in the script itself.

Example certificate lint

You can use the External Command Certificate Validator to run a lint check on issued certificates, and abort issuance if certificates don't pass the tests.

Preparations:

First, to enable external scripts, select Admin Web>System Configuration>External Scripts:
- For Enable External Script Access, select Activate
- In Configure Scripts Whitelist, select Use the whitelist below and specify a full path. For example /opt/bin/zlint.sh.
To add an External Command Certificate Validator, go to Navigators:
- In Validator Type, select External Command Certificate Validator.
- In Full pathname of script, add the full path to the script ending with %cert%. For example /opt/bin/zlint.sh %cert%.
- Ensure that at least the options Fail on script error code and Log error out are selected.
To enable the validator for the CA, go to Certificate Authorities, click Edit and select the Validator for the CA.

Issue a certificate using a server certificate Certificate Profile. You can see the Validator being triggered in the server.log. To test failures, set Key Usage to Key certificate sign in the Certificate Profile used to issue the end entity certificate. This option is not allowed in the CAB Forum Baseline Requirements. For more information, see Key Usage in Certificate Profile Fields.

ZLint

ZLint is a X.509 certificate linter that can be downloaded and built from the ZLint homepage.

You must wrap zlint in a zlint.sh script to allow the script to return a 0 exit code on success, and 1 as exit code on failure.

Place the zlint.sh script in the same location as ZLint:

#!/bin/sh
mydir="$(dirname "$(realpath "$0")")"
OUTPUT=`$mydir/zlint -pretty <&0|grep -1 error`
#echo Output:\"$OUTPUT\"
if [ -z "$OUTPUT" ]; then
  echo "No error in zlint"
  exit 0
else
  echo "Error in zlint"
  echo $OUTPUT >&2
  exit 1
fi

Test by issuing certificate both with and without the Key Usage option set to Key certificate sign and view the log output in the server.log and the security audit log.