deployCrypto

This command allows you to deploy X.509 certificates and private keys from multiple sources/formats to DataPower.

The command supports files in PEM and DER formats as well as keystores/truststores in all possible formats. The use of PKSC12 format is recommended for keystores.

In case of standalone files, the command automatically determines if it’s a cert or a private key. If a file or a keystore entry is protected by a password, the corresponding password alias will be created on DataPower.

The command copies keys/certs to DataPower and create the appropriate crypto objects. The names are derived either from file names or from the labels (aliases) in the keystore, except for issuers/CAs in which case the OU is used to generate the name.

The command automatically creates Crypto Identity Credential objects if it detects a cert-key keypair deployed from a keystore.

The command can also deploy certificates directly from endpoints.

The command automatically deploys the issuer’s chain of the certificate if found. It can also download the issuer from the certificate’s AIA extension if exists (all certs issued by the known CAs will have that extension).

All certificates and their issuers are de-duplicated, in other words, if the same cert of a CA is included multiple times (e.g., from different files or keystores or keystore labels), the cert will only be deployed once. The combination of the serial number and the issuer record is used as a unique identifier for each cert.

All changes to crypto objects are audited directly on the device and can be inspected using listCrypto. This command creates a small JSON object on DataPower that contains audit info. Same info is also captured in the audit file.

Attributes/Options

Name	Description
dir	The local directory which is the base for includes or excludes.
includes	Comma- or space-separated list of files that will be included into deployment (in Ant pattern format). You can mix and match files in different formats, including PEM, JKS, etc. E.g. **/*.pem **/*.jks Defaults to *.pem *.crt *.cer
excludes	Comma- or space-separated list of patterns of files that will be excluded from deployment. Defaults to ‘none’ (no files, except default Ant excludes, are excluded when omitted.)
file	Absolute path to the file to deploy. You must specify either file adn/or the file pattern using dir and includes.
toDir	The target directory for certificates on the device in the target domain. Defaults to cert:/
endpoint Alias: ep	A TLS Endpoint to deploy the certificate from. Format: host:port, e.g., my.backend.com:443. Port 443 is the default.
certs	Deploy certs from all found crypto files, including keystores. Defaults to “true”. If set to “false”, only keys will be deployed.
keys	Deploy keys from all found crypto files, including keystores. Defaults to “true”. If set to “false”, only certs will be deployed. Note that keys are usually password-protected. You must supply passwords for all keys you want to deploy in the format described below.
passwords	Comma-delimited list of passwords in the format name:password. Each password can be encrypted. name could be the name of a file for stand-alone files (e.g., .pem) or an alias/name in a keystore. You don’t need to specify extensions for files. You can use glob patterns instead of an explicit name, e.g., *:chageit. If a key or a cert is password protected and no matching password was provided, a warning will be issued and the key/cert will not be included into the deployment.
identCred	Automatically create Crypto Identity Credential object for the key/certificate pair from a keystore. Defaults to ‘true’.
issuers	Deploy all CAs and intermediate issuers certificate (certificate chain). The object/file name for each issuer will be derived from it’s OU or CN record. Each issuer/CA cert is deployed only once even if there only If there are multiple file with the same issuer/CA found. Issuers can downloaded from an endpoint (if the endpoint was used), can be provided in a file/keystore or it can be downloaded from the AIA extension’s URL of the end-entity certificate. Defaults to “true”.
fromAIA	Pull the issuer from the issuer’s URL of the certificate’s AIA extension and deploys it. Default is ‘false’. If set to ‘true’, the tool will attempt to use the AIA extension if issuer of the certificate was not provided by other means (e.g., as part of the cert chain in a pem file, a keystore or an endpoint).
ksNames Alias: names	Comma-delimited list of regular expression patterns defining what names (labels) from a keystore to pick. Only certificates/keys with matching names will be deployed. Applies only to certs/keys from keystores.
subjects	Comma-delimited list of regular expression patterns defining what certs to pick based on their CN or alternative subjects names. The tool attempts to match CN of the subject or any alternative name from the “Subject Alternative Name” extension. Only certificates with either the CN or at least one alternative name match will be deployed.
domainPatterns CLI alias: domains	Comma-delimited list of regular expression patterns defining what domains to deploy to. To deploy the same set of crypto objects to all domains use .* Defaults to the current domain. The current domain is specified using the dpDomain property or domain attribute of the task.
assertObjectsUp	Validate that the deployed crypto objects are in the ‘up’ state after the deployment. Defaults to ‘true’.
ignoreExpiration	Set the ‘Ignore certificate expiration’ configuration parameter for certificates. By default, DataPower will fail the import of expired certificates. If set to ‘true’, certificate expiration will be ignored. Defaults to ‘false’.

Examples

# Deploy certs and keys from various stand-alone files
dpbuddy deployCrypto -dir crypto_files -includes "*.pem *.cer *.key *.pkcs8" -excludes "myarch.pem" -passwords "self_signed:changeit"
# Deploy certs and keys from the keystore that match the names
dpbuddy deployCrypto -file crypto_files/test_keystore.jks -ksNames "local-app, keypair-1" -passwords "test_keystore:changeit,keypair-1:changeit"
# you can also specify passwords (or any other value) in dpbuddy.conf
dpbuddy deployCrypto -file crypto_files/test_keystore.jks -ksNames "local-app, keypair-1" -passwords "\${crypto.passwd}"
# Deploy the cert from the file without the issuer chain and download its issuer cert from the AIA URL
dpbuddy deployCrypto -dir crypto_files -includes "myarch.pem" -fromAIA
# Deploy directly from an endpoint (including the issuers)
dpbuddy deployCrypto -endpoint myarch.com
# Deploy only the certs (and their issuers) that have myarch.com in CN or in alternative names
dpbuddy deployCrypto -subjects myarch.com -dir crypto_files -includes "*.pem test_keystore.*" -passwords "test_keystore:ENC{+MmRqtwXqYFpbpk9r3NTfrxMXR9m21xT}" -keys false