ConfigDump Tool

ENTERPRISE

The EJBCA ConfigDump tool allows you to export and import configurations in a human-readable (YAML) format. Exporting the current state of your installation is useful for auditing purposes and comparing configuration changes made in EJBCA.

The import functionality allows you to import a full configuration or importing specific configuration objects, such as profiles, certification authorities (CAs), or any other previously exported items. Because the exported configuration is human-readable, you can edit fields directly before import. For example, it is possible to modify the subject DN of an end entity profile in the YAML file prior to importing it.

The following sections compare ConfigDump tool with the legacy Statedump configuration management tool and describe how to build, run, export, and import configurations using ConfigDump.

Comparison Between ConfigDump and Statedump

ConfigDump repleces the deprecated Statedump configuration management tool.

Statedump allows exporting and importing full EJBCA configurations on new instances in an XML format that is not human-readable, making it unsuitable for auditing or manual review. ConfigDump provides similar functionality using human-readable YAML format, allowing you to review and modify configuration exports.

The following provides a high-level comparison between ConfigDump and the legacy Statedump tool.

Functionality	ConfigDump	Statedump
Output format	YAML	XML
Can be easily edited
Export
Import
Ability to add comments to output files

Folder Structure and Output

Each EJBCA object is exported into its own file. Objects of different types are put in different folders.

The following displays an example of a directory structure created by ConfigDump:

Example Directory structure

TEXT

> tree
.
├── certification-authorities
│   ├── PrimeKey TestNet.yml
├── validators
│   ├── My CAA Validator.yml
│   ├── My RSA Key Validator.yml

The following displays an example output from ConfigDump:

Example ConfigDump output

TEXT

'Type': 'PARTITIONED_APPROVAL'
'Name': 'Partitioned approval profile test'
'Approval expiration period': '1d'
'Request expiration period': '2d'
'Max extension time': '3d'
'Allow self-approved request editing': !!bool 'true'
'Steps':
- 'Partitions':
  - 'Title': 'Partition 1'
    'Can approve':
    - 'Super Administrator'
    - 'RA Administrator 1'
    'Can view':
    - 'Super Administrator'
    - 'CA Administrator'
    - 'RA Administrator 1'
    - 'RA Administrator 2'
    - 'Supervisor'
    'Components':
    - 'Type': 'Text field'
      'Label': 'Text test'
      'Content': 'This is a multiline string.'
    - 'Type': 'Checkbox'
      'Label': 'Checkbox test'
      'Is checked?': !!bool 'true'
    - 'Type': 'Radio group'
      'Label': 'Radio test'
      'Selected choice': 'Blue'
      'Possible choices':
      - 'Green'
      - 'Blue'
      - 'Red'
  - 'Title': 'Partition 2'
    'Can approve':
    - 'Super Administrator'
    - 'RA Administrator 2'
    'Can view':
    - 'Anybody'
    'Administrator notification':
      'Sender': 'no-reply@admin.notification'
      'Recipients':
      - 'recipient1@admin.com'
      - 'recipient2.admin.com'
      'Subject': 'Admin notification subject'
      'Body': 'Admin notification body'
    'User notification':
      'Sender': 'no-reply@user.notification'
      'Subject': 'User notification subject'
      'Body': 'User notification body'
    'Components':
    - 'Type': 'Number'
      'Label': 'Integer test'
      'Value': !!int '42'
    - 'Type': 'Big number'
      'Label': 'Long test'
      'Value': !!int '9223372036854775807'

This YAML file example corresponds to a partitioned approval profile with one step and two partitions. Partition 1 contains a text field, a checkbox, and a radio group with three radio buttons. Partition 2 contains a user notification, an administrator notification, and two number fields.

Exportable Object Types

The following object types can be exported using ConfigDump:

acme-config
admin-preferences
admin-roles
approval-profiles
available-protocols
certificate-profiles
certification-authorities
cmp-config
crypto-tokens
ct-logs
custom-certificate-extensions
end-entity-profiles
est-config
extended-key-usage
internal-key-bindings
oauth-key-configuration
ocsp-configuration
peer-connectors
publishers
scep-config
services
trusted-oauth-providers
validators

Version Field

The version of the exported object is used to keep track of object compatibility. The version number is incremented when there's an incompatible change, for example if an objects field is changed in between EJBCA versions. Upon import the version of the YAML file is compared to the internal object version and a warning is given if it is incompatible.

Import and export requires /system_functionality/edit_systemconfiguration access rule permission. Import of available-protocols requires superadmin permission. For more information on permissions, see Roles and Access Rules.

Build ConfigDump

To build and run the ConfigDump tool from the command line, use the following build argument:

BASH

$ ant configdump

This creates a standalone JAR library deployed to dist/configdump/configdump.jar.

To run it, use the following command:

BASH

$ ./dist/configdump/configdump.sh

Export

The following lists sub-commands for the export command.

To see the full manual file for the export command, run:

BASH

$ ./dist/configdump/configdump.sh export --help

The export command produces a complete YAML-based export of an EJBCA installation, meant to be human-readable. Thus, ID references for objects will be replaced with their proper names. Certificates and end entity information will not be included in this export.

Mandatory Parameters

Switch	Description
-l (may be omitted if this value is added first)	The output directory where YAML files will be written. It will be created automatically if non-existent. Provide absolute path to the directory e.g. /home/user/configdumpresult etc. Any existing dump files will be overwritten.

Optional Parameters

Switch	Description
--exclude	Names of items/types to exclude in the export, separated by a semicolon. Type and name are separated by a colon, and wildcards "" are allowed. Both are case-insensitive. E.g. --exclude ":Example CA; cryptotoken:Example; systemconfiguration:" Supported types are: ACMECONFIG, CA, CRYPTOTOKEN, PUBLISHER, APPROVALPROFILE, CERTPROFILE, EEPROFILE, SERVICE, ROLE, KEYBINDING, ENDENTITY, SYSCONFIG, ADMINPREFS, CMPCONFIG, OCSPCONFIG, PEERCONNECTOR, PEERCONFIG, SCEPCONFIG, ESTCONFIG, VALIDATOR, CTLOG, EXTENDEDKEYUSAGE, CERTEXTENSION, AVAILABLEPROTOCOLS, EXTERNALACCOUNTBINDING, CACONFIG
--ignore-errors	Print a warning instead of aborting and throwing an exception on errors.
--ignore-warnings	No warnings will be printed in the CLI output.
--include	Names of items/types to include in the export. The syntax is identical to that of --exclude. For items of types that aren't listed, everything is included.
--include-external-cas	Enables export of external CAs (i.e. CAs where there's only a certificate and nothing else).
--export-cas-for-peer-import	Export CAs with certificate chain so that they can be conveniently imported in Peers i.e. RA/VA
--with-defaults	Also include fields having the default value.

An example usage of the include filter to only export CMP configuration to the directory dump would look like:

TEXT

./configdump.sh export --exclude "*:*" --include "CMPCONFIG:*" -l dump

Or exporting a specific EST Alias:

TEXT

./configdump.sh export --exclude "*:*" --include "ESTCONFIG:myAliasName*" -l dump

Export of Passwords and Secrets

Certain configuration items have passwords or secrets stored, which are usually encrypted in the database. An example is the CMP RA Mode authentication secret. Secrets like these are replaced with the string placeholder during export.

When constructing configuration dump files for import, search and replace secrets set with placeholder with the values to be used for import, or edit it afterward using the EJBCA UI or the CLI.

The following shows an example output for a SCEP Alias with Intune configuration containing Azure Application API Secret and Intune EJBCA Proxy Password.

YML

Object Type: SCEP Configuration
Version: 2
Name: Intune
Operational Mode: RA
Authenticate through Microsoft Intune: 'true'
RA CA Name: IntuneCA
RA Authentication Password: placeholder
Azure Application ID: IntuneID
Azure Application API Secret: placeholder
Intune Tenant: My tennant
Intune EJBCA Proxy Password: placeholder

When importing CMP aliases, if prompted for a CMP Authentication Module password:

Enter a password to set HMAC mode to Specify Secret in the imported alias.
Press Enter twice (without providing any password) to set the mode to CA Shared Secret.

Import

The import command reads from YAML export files of an EJBCA installation, or user-created YAML files that follow the same structure. ConfigDump supports creation and editing of objects but does not provide full CRUD functionality.

ConfigDump supports creation and editing of objects but does not provide full CRUD functionality.

To view the full manual file for the import command, run:

BASH

$ ./dist/configdump/configdump.sh import --help

Mandatory Parameters

Switch	Description
-l	The input directory to read dump YAML files from. Must point to the root directory of the YAML files. Specific sub-directories cannot be targeted directly.

Optional Parameters

Switch	Description
--ignore-errors	Print a warning instead of aborting and throwing an exception on errors.
--ignore-warnings	No warnings will be printed in the CLI output.
--initialize	Generate initial certificate for CAs on import. Also generate certificates for Remote Authentication or OCSP Responder key bindings key bindings when enrollment information is provided since 8.3.0.
--non-interactive	Set non-interactive mode. Mode must be one of: <continue> or <abort>
--overwrite	Don't prompt for overwrite. Mode must be one of: <update> or <skip>. When an object from the YAML file already exists in the database, this object should be skipped from import or be updated.
--resolve-reference	Don't prompt for reference problem. Mode must be one of: <default> or <skip>. When an object to be imported is referencing a missing object, this object should get a default value for the missing object or be skipped from import.
--expand-variables	Replace variable references in form ${CONFIGDUMP_VARIABLE_NAME} with values of matching environment variables. Keep CONFIGDUMP_ prefix for the variable.

Note that when importing (that is, editing) an initialized CA, modifications to the crypto token or key assignments should only be performed as part of an HSM migration. Using this method for key rotation is not recommended.

ConfigDump REST Interface

Import and export operations are also available through the EJBCA REST Interface.

To allow automation via the REST interface, superadmins can access the REST interface without enabling it beforehand. By enabling ConfigDump or other protocols, the superadmin can support further operations without access to the CLI or UI. To update the protocol and/or interface configuration, superadmins need to import the available-protocol object with overwrite parameter set to true.

Troubleshooting

If EJBCA is running as a different user than ConfigDump (which may happen whenever you log in as foo but EJBCA is running as e.g. wildfly) you may run into the following problem when exporting:

CODE

Exporting to directory: /home/foo/configdump
java.nio.file.AccessDeniedException: /home/foo/configdump
[....]

The solution is to create the folder manually with the proper group ownership, according to the following example:

CODE

mkdir ~/configdump
sudo chown foo:wildfly ~/configdump

ConfigDump Initialization

ConfigDump import allows initialization of certain EJBCA objects using the --initialize flag or equivalent REST query parameter. Initialization is especially helpful during automation and is available only on CA nodes.

Initialize CA

Creates CA certificate and CRL and activates it. This allows the imported CA to generate certificates in the future without any manual intervention.

Initialize Key Bindings

This allows multiple steps to be automated from a single ConfigDump import which greatly simplifies setup process of Remote Authentication or OCSP Responder key bindings. The Enrollment info section of the ConfigDump must be populated for the key binding.

EJBCA will:

Generate key pairs in the designated crypto token (if needed)
Enroll certificate for the key binding
Enable the key binding for remote peer connection or OCSP

Required attributes:

Enrollment info: Key Binding SubjectDN
Enrollment info: Signing CA SubjectDN
Enrollment info: Certificate profile
Enrollment info: End entity profile
Enrollment info: Key spec or curve

Example

The following shows an example where a remote authentication key binding is initialized and then used in a peer connection. The referenced cryptotoken (peer-key1) is pre-created and auto-activated. The key pair signKey002 may be created beforehand or generated automatically during import

Note that the peer-connector is also imported in the example to help demonstrate a use case while only the internal-key-bindings is required for the initialization functionality.

The result of this imported ConfigDump is an active key binding and a peer connection.

Key binding configdump

JS

{
  "peer-connectors": {
    "va-peer1": {
      "Object Type": "Peer Connector",
      "Version": 1,
      "Name": "va-peer1",
      "Peer Enabled": true,
      "URL": "https://172.17.2.47:8443/ejbca/peer/v1",
      "Long Hanging Connections Enabled": false,
      "Min Long Hanging Connections": 1,
      "Max Long Hanging Connections": 2,
      "Authentication Key Binding": "peer-key1"
    }
  },
  "internal-key-bindings": {
    "peer-key1": {
      "Object Type": "Internal Key Binding",
      "Version": 1,
      "Name": "peer-key1",
      "Type": "AuthenticationKeyBinding",
      "Status": "ACTIVE",
      "Crypto Token": "peer-token",
      "Key Pair Alias": "signKey002",
      "Next Key Pair Alias": null,
      "Signature Algorithm": "SHA256WithRSA",
      "Enrollment info: Key Binding SubjectDN": "CN=peer-key1",
      "Enrollment info: Signing CA SubjectDN": "CN=1CA2ruleThemALL",
      "Enrollment info: Certificate profile": "ENDUSER",
      "Enrollment info: End entity profile": "EMPTY",
	  "Enrollment info: Key spec or curve": "RSA2048",
      "Trusted certificates": {},
      "Signed on behalf of CAs": {},
      "Properties": {
        "Protocol and Cipher Suite": "TLSv1.2;TLS_DHE_RSA_WITH_AES_128_GCM_SHA256"
      }
    }
  }
}