.. highlight:: bash .. index:: Crypto Tasks .. _crypto_tasks: Crypto Management Commands ========================== .. _deployCrypto: ``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 :ref:`listCrypto`. This command creates a small JSON object on DataPower that contains audit info. Same info is also captured in the :ref:`audit file `. Attributes/Options ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 88 :header-rows: 1 * - 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 :ref:`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 ^^^^^^^^ .. code-block:: bash # 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: ``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 :ref:`passwordAliasTask` 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 ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 88 :header-rows: 1 * - 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 :ref:`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 ^^^^^^^^ .. code-block:: bash # 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.