Command Line Interfaces

The following EJBCA Command Line Interfaces (CLI) are available:

  • EJBCA Client Toolbox: Set of tools built as a stand-alone package, which can be put on any machine and run independently of EJBCA. Includes a Web Service Interface.

  • EJBCA Validation/Conformance Tool: Allows running tests on issued certificates or OCSP responses to see that they match the configured criteria.

  • Local Command Line Interface (EJBCA CLI): The Local CLI can be run directly on the CA machine and contains many functions that can be used in scripts, or come to rescue when your Admin certificate has expired, or you have accidentally revoked your Admin privileges for the Admin GUI.

  • Local Database CLI: Accessing a database, export and import, copy, verify audit log and OCSP monitoring.

  • CAA Lookup Tool: Providing additional verification, fallback and troubleshooting for the built-in CAA Validator.

  • P11Ng CLI: PKCS#11 tool used for interaction with the p11-ng provider. Supports key generation, key authorization (Utimaco CP5 specific) and so on.

  • ConfigDump Tool: A powerful tool used to export a complete EJBCA installation into human-readable YAML files.

Local Command Line Interface (EJBCA CLI)

The Local CLI can be run directly on the CA machine and contains many functions that can be used in scripts, or come to rescue when your Admin certificate has expired, or you have accidentally revoked your Admin privileges for the Admin GUI.

EJBCA has command line interfaces to both the CA and RA, as well as some other operations.

To list available commands, run the CLI using for example:

$ bin/ejbca.sh
$ bin/ejbca.sh ca
$ bin/ejbca.sh ra

To list available options for a specific command, run the command without any options, for example:

$ bin/ejbca.sh ra addendentity

To access usage information for certain commands that do not take parameters, provide the -? option.

Note that when providing files as input to the CLI it is advisable to use full path names as the working directory may not be what you think.

Return Codes

The local CLI uses the following return codes to facilitate scripting:

  • 0 - Normal exit.

  • 1 - Functional failure, command was entered correctly but failed for some other reason.

  • 2 - Authentication failure.

  • 3 - CLI failure, command failed due to incorrect parameter use.

Local CLI Authentication

By default, the CLI authenticates using a standard user defined in ejbca.properties. Disabling this user on the server will lead to all CLI operations demanding authentication in the form of the following flags appended to the argument list:

-u <username> -p

which will cause the console to prompt for the password. If instead the password should be included in the command line (such as) from a script, it can be specified using the following flags:

-u <username> --clipassword=<password>

You can also specify that the password is provided as the first line in a file, which can be useful for scripting. It can be specified prepending 'file:' to the password:

-u <username> --clipassword=file:<filename>

Where filename is a file, for example /tmp/pwd.txt, containing the password as a single line.

An example CLI command to list CAs can look like:

$ bin/ejbca.sh ca listcas -u ejbca --clipassword=file:/tmp/pwd.txt

Command line users are authenticated from the existing list of End Entities and are granted the same rights. You can find the default CLI user in the Super Administrator Role listed under Administrator Roles after a default install or upgrade. You can add new CLI users by adding an end entity and adding a member to a Role using the CLI:Username authentication token.

Deleting this user or revoking all its privileges makes it impossible to use the CLI for any operation that requires administrator rights including renewing the Super Administrator certificate. Make sure to renew the administrator certificates using the Admin Web before they expire!

Change the Password for the Default CLI User

The default username and password used for the CLI defined in the ejbca.properties is the following:

#------------------- CLI settings -------------
ejbca.cli.defaultusername=ejbca
ejbca.cli.defaultpassword=ejbca

When there is a requirement to change this password to comply with security policy requirements, use the following command to change the password:

$ bin/ejbca.sh ra setpwd ejbca <NEW PASSWORD>

Where NEW PASSWORD is the new password that will be used with CLI commands.

PowerShell does shell expansion with no quotes or double quotes, and the $ can cause problems unless escaped with a tick ( ` ), for example: `$

Disable the Command Line Interface

You can disable the command line interface to prevent a user running operations that require authorization. Go to System Functions>System Configuration and clear the option Enable Command Line Interface Access to disable performing operations requiring authorization from the command line interface.

The Enable Command Line Interface Access option, in contrast to disabling the CLI users privileges in Administrator Roles, allows switching having the CLI enabled or disabled as long as you have access to the Admin GUI.

Disabling Enable Command Line Interface Access makes it impossible to use the CLI for any operation that requires administrator rights, including renewing the Super Administrator certificate. Make sure to renew the administrator certificates using the Admin Web before they expire!

After changing this property, you may need to select Clear All Caches or run the following CLI command: 

    
$ bin/ejbca.sh clearcache -all

Local Database CLI

ENTERPRISE This is an EJBCA Enterprise feature.

You can build and run the local database CLI using the commands:

$ ant ejbca-db-cli
$ cd dist/ejbca-db-cli
$ ./run.sh

The CLI contains commands for directly accessing a database, export, import, copy, verify audit log and OCSP monitoring. Run the command to get a description about all available commands.

To verify database protection, make sure that you have conf/databaseprotection.properties configured. If you are using database protection for your CA, you can use the same file.

For verification, you can also use a verification token, without the private key, so you can do verification on another host from the CA. The file conf/databaseprotection.properties.sample provide example configuration and documentation for the various options.

You can also use the DB tool to create databaseprotection in case you started off not enabling it, and want to enable it later.

  • Shut down EJBCA

  • Configure databaseprotection.properties and build ejbca-db-cli (so the propereties file is included in dist/ejbca-db-cli/conf)

  • Export the database with db-cli

  • Drop the database

  • Import the database with db-cli

CAA Lookup Tool

ENTERPRISE This is an EJBCA Enterprise feature.

Full support is provided for CAs through the built-in CAA Validator. To provide additional verification, fallback and troubleshooting, a command line tool is provided, using the same underlying code to perform CAA requests from the command line. To build this tool and find out how it works, perform the following actions:

$ ant ejbca-caa-cli
$ java -jar
$ java -jar dist/caa-cli/caa-cli.jar --help