Sign extensions

Each extension uploaded to a Dynatrace environment must be signed so that Dynatrace can verify the authenticity and integrity of the extension.

Two ways to sign and build your extension are described below:

Use Dynatrace CLI

The Dynatrace CLI (dt-cli) is a command-line utility that assists you in developing, signing, and building extensions for the Dynatrace Extensions 2.0 framework.

It enables you to:

For details, see dt-cli on GitHub.

Prerequisites

Prerequisites for using the Dynatrace CLI to sign and build your extension:

To sign and build your extension using Dynatrace CLI, complete the following steps:

Install Dynatrace CLI

Generate certificates

Add root certificate to the Dynatrace credential vault

Build and sign the extension

Upload the extension package to your Dynatrace environment

Upload root certificate to hosts

Install Dynatrace CLI

1pip install dt-cli

Generate certificates

This command generates your root and developer certificates. Go to the my-sample-extension parent directory and run the following commands:

1mkdir secrets
2cd secrets
3dt extension genca --no-ca-passphrase
4dt extension generate-developer-pem -o developer.pem --ca-crt ca.pem --ca-key ca.key --name 'JDoe'

The command generates the following files:

Example successful output:

1>_ mkdir secrets
2>_ cd secrets
3>_ dt extension genca --no-ca-passphrase
4Generating CA...
5Wrote CA private key: ./ca.key
6Wrote CA certificate: ./ca.pem
7>_ dt extension generate-developer-pem -o developer.pem --ca-crt ca.pem --ca-key ca.key --name 'JDoe'
8Loading CA private key ca.key
9Loading CA certificate ca.pem
10Generating developer certificate...
11Wrote developer private key: developer.pem
12Wrote developer certificate: developer.pem

Please bear in mind that this workflow should only be used for demonstration / PoC purposes. We recommend following the security best practices such as having the root and developer certificates managed by different entities as opposed to storing them in the same directory.

Add root certificate to the Dynatrace credential vault

Build and sign the extension

In the my-sample-extension parent directory, run the following command:

1dt extension assemble

This will create extension.zip - a package, ready for signing.

To sign, run the following command:

1dt extension sign --key secrets/developer.pem

This command builds your extension package, which contains only the extension.zip archive and the extension.zip.sig signature file.

1bundle.zip
2|    extension.zip
3|    extension.zip.sig

Example successful output:

1>_ dt ext assemble
2Building extension.zip from src
3Adding file: src/alerts/palo-alto_temperature_max.json as alerts/palo-alto_temperature_max.json
4Adding file: src/alerts/palo-alto_fan_speed.json as alerts/palo-alto_fan_speed.json
5Adding file: src/extension.yaml as extension.yaml
6Adding file: src/dashboards/palo-alto-generic-default.json as dashboards/palo-alto-generic-default.json
7Wrote extension.zip file
8>_ dt ext sign --key secrets/developer.pem

Upload the extension package to your Dynatrace environment

In the my-sample-extension parent directory, run the following command:

1dt extension upload bundle.zip

This command uploads the extension package to your Dynatrace environment, from which it's distributed to the OneAgent or ActiveGate hosts.

For more information, see Manage Extensions 2.0 lifecycle.

Upload root certificate to hosts

Upload root certificate to hosts running your extensions. For more information, see Upload your root certificate below.

Use OpenSSL

To sign your extension manually, use OpenSSL. For Windows, you need to download and install an OpenSSL binary of your choice. We tested the procedure with OpenSSL 1.1.1k.

Create the root key and certificate

Add your root certificate to the Dynatrace credential vault

Create a developer certificate

Sign your extension

Verify signature

Create extension package

Create the root key and certificate

Your company should issue developer certificates from a company-wide root certificate. When developers sign their extensions with their own developer certificates, Dynatrace will be able to verify the extension authenticity against your root certificate stored in the Dynatrace credential vault and on the hosts where extensions are executed.

Run the following commands to generate your organization's root certificate. Do not set the password. Password-protected certificates are not supported by Dynatrace.

1openssl genrsa -out root.key 2048
2openssl req -new -key root.key -out root.csr

When generating the root certificate, you need to explicitly define the certificate extension by pointing the -extfile property to the ca.txt file. The file should contain the following data:

1basicConstraints=critical, CA:true, pathlen:0
2subjectKeyIdentifier    = hash
3authorityKeyIdentifier  = keyid:always
4keyUsage                = keyCertSign

1openssl x509 -req -days 10000 -in root.csr -signkey root.key -out root.pem -extfile ca.txt

This generates your root.pem root certificate.

Note that you can also use an existing root certificate to generate developer certificates. Dynatrace accepts only PFX, P12, and PEM formats, so you may need to convert the existing certificate to one of the allowed formats. Refer to the OpenSSL documentation for conversion instructions.

Add your root certificate to the Dynatrace credential vault

Create a developer certificate

To create your developer certificate, you need to create a developer certificate signing request and then issue the certificate.

Create a developer certificate signing request

Run the following commands to generate the certificate signing request (CSR) to the root CA:

1openssl genrsa -out developer.key 2048

1openssl req -new -key developer.key -out developer.csr

When filling in the fields for the Distinguished Name (DN), make sure that at least one of the fields is different than the DN you defined for the root certificate.

The result is the developer.csr CSR that you'll use to issue the developer certificate from the root certificate.

Issue a developer certificate

Run the following commands to generate the developer certificate:

1openssl req -new -key developer.key -out developer.csr

When generating the developer certificate, you need to explicitly define the certificate extension by pointing the -extfile property to the developer.txt file. The file should contain the following data:

1subjectKeyIdentifier    = hash
2authorityKeyIdentifier  = keyid:always
3keyUsage                = digitalSignature

1openssl x509 -req -days 10000 -in developer.csr -CA root.pem -CAkey root.key -CAcreateserial -out developer.pem -extfile developer.txt

The result is the developer.pem certificate file that you'll use for signing your extensions.

Sign your extension

With the developer certificate in place, use the following command to sign your extension. Make sure that your extension.zip file is in the directory from which you run the command.

1openssl cms -sign -signer developer.pem -inkey developer.key -binary -in extension.zip -outform PEM -out extension.zip.sig

The result is an extension.zip.sig signature file.

Verify signature

Use the following command to verify the extension.zip.sig signature file against the root.pem root certificate:

The output should contain the phrase Verification successful.

Create extension package

For the final step, create an extension package containing only the extension.zip archive and the extension.zip.sig signature file.

1bundle.zip
2|    extension.zip
3|    extension.zip.sig

You can now upload the extension package to your Dynatrace environment. For more information, see Manage Extensions 2.0 lifecycle.

Upload your root certificate

Each host running your extension, whether OneAgent or ActiveGate, needs to have the root certificate saved in a dedicated directory. This extra step is required to enhance the security of the Extensions 2.0 framework.

By doing this:

Remote extensions

Upload your root certificate to each ActiveGate host within the ActiveGate group selected for running your extensions

Save the root.pem certificate file in the following location:

Local extensions

Upload your root certificate to each OneAgent host or each OneAgent host within the host group selected for running your extensions.

Save the root.pem certificate file in the following location: