Generating app signature and verification certificate using OpenSSL

Install OpenSSL

Installation steps for OpenSSL depend on the operating system.

MacOS

On MacOS, the simplest way is to use Brew:

brew install openssl@3

Windows

On Windows, OpenSSL is part of Git for Windows installation. If you don’t have Git on your machine, you can use this link to install it: Download for Windows. With Git installed, you can use:

C:\Program Files\Git\usr\bin\openssl.exe

Linux

To install OpenSSL on Ubuntu or Debian, use the following command:

$ sudo apt install openssl

For CentOS or RHEL, use the following command:

$ sudo yum install openssl

Create a signing key and certificate

1. Create a private signing key

This key will be used later to sign an app (or apps). Run the following command:

openssl genpkey -algorithm ed25519 -out app-signing.key

This will create a private key and store it in the app-signing.key file. This key is generated using the Edwards-curve Digital Signature Algorithm (EdDSA) which is a requirement of Atlassian’s products.

2. Create a certificate matching the key

This involves creating a Certificate Signing Request file (CSR) and generating a certificate from a previously created CSR.

1. Create a configuration file

To create a Certificate Signing Request, start with the creation of a text file with the required configuration. Create a text file named app-signing.cfg with the following content:

[req]
distinguished_name = req_distinguished_name
x509_extensions = v3_ca
prompt = no
default_bits = 4096

[req_distinguished_name]
C = US
ST = California
L = San Francisco
O = Organization Name
OU = IT Department
CN = Best App Inc

[v3_ca]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints = critical, CA:true
keyUsage = critical, digitalSignature
extendedKeyUsage = critical, codeSigning

2. Adjust [req_distinguished_name] 

Adjust [req_distinguished_name] as, in this example:

• C stands for Country. It's represented by a two-letter country code, such as “US” for the United States.
• ST stands for State or Province. In this example, it's “California”.
• L stands for Locality or City. Here, it's “San Francisco”.
• O is the Organization Name. Here, it’s “Organization Name” as a placeholder.
• OU is the Organizational Unit Name. This is often used to specify a department, such as “IT Department”.
• CN is the Common Name. For app signing certificate purposes, we recommend providing here a vendor’s company name or, as an alternative, using the vendor’s website address is also a good option.

3. Generate CSR

Having the app signing file, use it to generate CSR with the following command:

openssl req -new -out app-signing.csr -key app-signing.key -config app-signing.cfg 

4. Create verification certificate

Now you can reuse the same config for creation of the verification certificate named in our example app-signing.crt:

openssl x509 -req -days 700 -in app-signing.csr -signkey app-signing.key -out app-signing.crt -extensions v3_ca -extfile app-signing.cfg

5. Verify the created certificate

To verify the created certificate, run this command:

openssl x509 -noout -text -in app-signing.crt 

Notice that our certificate is a self-signed certificate with the following attributes:

• not a Certificate Authority (CA), which means our certificate can't be used to create new certificates.
• extended key usage: code signing

Store your app-signing.key and app-signing.crt files, as one will be used for generating application signatures, other should be installed in the product’s certificate trust folder to allow verification of the installed application signature.

Generate app signature

Now let’s assume the application for signing is stored in a file named application.jar. To generate a signature of this application using a previously generated key, run:

openssl pkeyutl -sign -inkey app-signing.key -rawin -in application.jar -out application.sbin

This will create a binary signature in application.sbin. To convert it to base64 format, use this command:

% openssl base64 -in application.sbin > application.pem