Crypto Management Commands

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 the file for stand-alone files (e.g., .pem) or the 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’. Defaults to “true”.

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

listCrypto

This command downloads certificates, keys and password aliases from DataPower or certificates from TLS endpoints.

It prints certificate/key information to the console and also generates a more detailed report in Excel format.

You can specify what columns to print by using various *Col options of this command. The Excel report always contains all columns.

The command can also check certificates’ validity and compliance with policies and best practices. For example, it can flag sef-signed certificates, certificates with weak keys or certificates issued by Certificate Authorities that are not approved within an organization.

The command also checks a certificate’s expiration, verifies its signature and checks the certificate’s revocation status using OCSP.

It also checks expiration of password aliases if they were deployed using passwordAlias with the expiresIn value provided.

You can put listCrypto on a schedule to periodically check certificates’ “health” and compliance. failOnCheckFailure option can be used to create alerts in case if a check fails.

The same certificate (same public key, issuer, serial number) can be encountered multiple times during the scan. E.g. a certificated can be deployed to multiple domains or appliances, or a duplicate can be pulled from a TLS endpoint. listCrypto always groups certificates based on their issuer/serial, so you can see if the same certificate is used in multiple locations.

By default, the command does not show issuers’ certificates (CAs and intermediate issuers), even though it downloads them from DataPower or from endpoints. The issuers’ certs are used for verifying certificate’s signature. You can use -issuers options if you need to see issuers’ certificates as part of the report.

The command will automatically download the issuer’s cert using the information in the AIA extension if needed.

Attributes/Options

Name	Description
domainPatterns alias: domains	Comma-delimited list of regular expression patterns defining what domains to apply the command to. Use ‘.*’ for all domains except the default. Use ‘.*,default’ to include the default.
excel	Produce report in Excel format in addition to printing to the console/standard out. Defaults to false
reportOutput	Path to the generated report file in Excel format or to a directory where the CSV files will be saved. Defaults to ./crypto_reports/cryptoReport
listKeys alias: keys	Include information about private keys. The actual keys are not collected and not displayed. Defaults to true
listPasswordAliases CLI alias: pa	Include information about password aliases, such as the object name, audit info, password expiration. The actual passwords are not collected and not displayed. Defaults to true
listCerts CLI alias: certs	Include information about X.509 certificates. Defaults to true
listIssuers CLI alias: issuers	Include certificates from CAs and intermediate issuers. Defaults to false
endpoints alias: ep	Endpoints to collect certificates from, in addition to DataPower. Format: list of comma-delimited host:port, e.g., my.backend.com,192.168.1.12:9443. Port 443 is the default.
runChecks	Validate certificates and keys according to the configured checks in crypto.conf. Defaults to false
failOnCheckFailure alias: fail	Fail this command if one of the checks defined in crypto.conf failed. The command will return a failure status. Defaults to false
auditCol	Show ‘Changed On’ and ‘Changed By’ columns. Defaults to true
issuerCol	Show the ‘issuer’ column. Defaults to true
serialCol	Show the serial number of the certificate. Defaults to false
usage	Print usage of all found crypto objects in the format Type:Name, Type:Name. Each Type:Name is the parent of the previous object, so it represent an object reference graph. Defaults to false

Examples

# List certificates, keys, password aliases, checks are not performed
dpbuddy listCrypto
# Display certs only, run policy checks defined in crypto.conf. Suppress the issuers columns to save space.
dpbuddy listCrypto -keys false -pa false -runChecks -issuerCol false
# Certs only, run policy checks defined in crypto.conf and fail if any of the checks failed
dpbuddy listCrypto -keys false -pa false -runChecks -failOnCheckFailure
# Generate excel report; Display the serial number of the certificates
dpbuddy listCrypto -runChecks -issuerCol false -serial -excel
# print usage of all found crypto objects
dpbuddy listCrypto -usage

Sample output:

Domain          Object Name    File                     Subject CN           Alt Names                           Exp in Days Key Alg  Issuer                              Serial                                Changed On Changed By
dpbuddy-samples revoked_chain  cert:/revoked_chain.pem  revoked.badssl.com   revoked.badssl.com,www.revoked.bads         473 RSA-2048 DigiCert SHA2 Secure Server CA      4578095623763233818958520798617405692 6/20/20    aananiev
dpbuddy-samples myarch_chain   cert:/myarch_chain.pem   myarch.com           myarch.com,www.myarch.com                   493 RSA-2048 Go Daddy Secure Certificate Authori 11510493113533735686                  6/20/20    aananiev
dpbuddy-samples myarch         cert:/myarch.pem         myarch.com           myarch.com,www.myarch.com                   493 RSA-2048 Go Daddy Secure Certificate Authori 11510493113533735686                  6/20/20    aananiev
dpbuddy-samples myarch.com_443 cert:/myarch.com_443.pem myarch.com           myarch.com,www.myarch.com                   493 RSA-2048 Go Daddy Secure Certificate Authori 11510493113533735686                  6/20/20    aananiev
https://myarch.com:443                                  myarch.com           myarch.com,www.myarch.com                   493 RSA-2048 Go Daddy Secure Certificate Authori 11510493113533735686
dpbuddy-samples local-app      cert:/local-app.pem      local-app            local-app                                   326 RSA-2048 Local CA                            1589417790                            6/20/20    aananiev
dpbuddy-samples local_app      cert:/local_app.pem      local-app.com                                                    266 RSA-2048 local CA                            1584288750                            6/20/20    aananiev
dpbuddy-samples self_signed    cert:/self_signed.pem    localhost                                                       -523 RSA-2048 localhost                           9699314724490867386                   6/20/20    aananiev
dpbuddy-samples keypair-1      cert:/keypair-1.pem      test-key-1                                                      -278 RSA-2048 test-key-1                          1537189500                            6/20/20    aananiev

Please see this post with more examples of crypto reports.