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 - recommended
- Use OpenSSL - manual procedure
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:
- Build and sign extensions from source
- Generate development certificates for extension signing
- Generate CA certificates for development
For details, see dt-cli on GitHub.
Prerequisites
Prerequisites for using the Dynatrace CLI to sign and build your extension:
-
Python 3.8 or 3.9
-
Access to pip package installer for Python
-
Save your
extension.yaml
file and your assets in thesrc
directory using the following structure:my-sample-extension/ └── src/ ├── extension.yaml dashboards/ └── dashboard.json alerts/ └── alert.json
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
pip 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:
mkdir secrets
cd secrets
dt extension genca --no-ca-passphrase
dt extension generate-developer-pem -o developer.pem --ca-crt ca.pem --ca-key ca.key --name 'JDoe'
The command generates the following files:
developer.pem
- Your developer certificate & keyca.pem
- Your root certificateca.key
- Your root key
Example successful output:
>_ mkdir secrets
>_ cd secrets
>_ dt extension genca --no-ca-passphrase
Generating CA...
Wrote CA private key: ./ca.key
Wrote CA certificate: ./ca.pem
>_ dt extension generate-developer-pem -o developer.pem --ca-crt ca.pem --ca-key ca.key --name 'JDoe'
Loading CA private key ca.key
Loading CA certificate ca.pem
Generating developer certificate...
Wrote developer private key: developer.pem
Wrote 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
- From the navigation menu, select Manage > Credential vault.
- Select Add new credential.
- For Credential type, select Public Certificate.
- Add a meaningful Credential name.
- Upload the Root certificate file.
- Select Save.
Build and sign the extension
In the my-sample-extension
parent directory, run the following command:
dt extension assemble
This will create extension.zip
- a package, ready for signing.
To sign, run the following command:
dt 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.
bundle.zip
| extension.zip
| extension.zip.sig
Example successful output:
>_ dt ext assemble
Building extension.zip from src
Adding file: src/alerts/palo-alto_temperature_max.json as alerts/palo-alto_temperature_max.json
Adding file: src/alerts/palo-alto_fan_speed.json as alerts/palo-alto_fan_speed.json
Adding file: src/extension.yaml as extension.yaml
Adding file: src/dashboards/palo-alto-generic-default.json as dashboards/palo-alto-generic-default.json
Wrote extension.zip file
>_ 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:
dt 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.
openssl genrsa -out root.key 2048
openssl 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:
basicConstraints=critical, CA:true, pathlen:0
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always
keyUsage = keyCertSign
openssl 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
- From the navigation menu, select Manage > Credential vault.
- Select Add new credential.
- For Credential type, select Public Certificate.
- Add a meaningful Credential name.
- Upload the Root certificate file.
- Select Save.
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:
openssl genrsa -out developer.key 2048
openssl 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:
openssl 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:
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always
keyUsage = digitalSignature
openssl 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.
openssl 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:
openssl cms -verify -CAfile root.pem -in extension.zip.sig -binary -content extension.zip -inform PEM -out /dev/null
openssl cms -verify -CAfile root.pem -in extension.zip.sig -binary -content extension.zip -inform PEM -out NUL
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.
bundle.zip
| extension.zip
| 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:
- You verify the authenticity of distributed extensions
- You prevent potential malicious extension distribution by an intruder who could take control of your environment
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:
- Linux:
<CONFIG>/remotepluginmodule/agent/conf/certificates/
(default:/var/lib/dynatrace/remotepluginmodule/agent/conf/certificates/
) - Windows:
%PROGRAMDATA%\dynatrace\remotepluginmodule\agent\conf\certificates
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:
- Linux:
/var/lib/dynatrace/oneagent/agent/config/certificates
- Windows:
%PROGRAMDATA%\dynatrace\oneagent\agent\config\certificates