Scripts for signing using PKCS11 library on Oracle Cloud Infrastructure

Set up Software Trust Manager, client tools, and integrate them with OCI for automation into a CI/CD pipeline.

Prerequisites

Linux operating system
Oracle Cloud Infrastructure DevOps project
JDK installed on the agent
DigiCert® Software Trust Manager credentials
DigiCert® Software Trust Manager client tools

Client tools

DigiCert® Software Trust Manager clients can be downloaded in a package.

Download Client tools

Sign in to DigiCert ONE.
Navigate to DigiCert® Software Trust Manager > Resources > Client tool repository.
Select Linux.
Click the download icon next to DigiCert® Software Trust Manager clients.

Create PKCS11 configuration file

To create a configuration file with the path to this shared library:

Open an integrated development environment (IDE) or plain text editor.

Copy and paste the following text into the editor:

Save the file as pkcs11properties.cfg.
Move the pkcs11properties.cfg file to the same location as the PKCS11 library.

User authentication

Software Trust enforces multi-factor authentication for security purposes. To access keypairs, certificates, and sign code, you need to set up two types of credentials: An API key and an authentication certificate.

Create an API key

The API key is an authentication method used to verify you as a user and your permissions assigned in DigiCert ONE. The API key provides the first factor authentication.

In DigiCert ONE, select the profile () icon, and then select Admin Profile.
Under API keys, select Create API key.
For Name, enter a descriptive name for the key.
For End date (optional), enter the date when the key should expire.
Select Create. The API key appears this one time and can't be accessed again. Securely store the API key for future use.

Create an authentication certificate

The client authentication certificate is an authentication method used to verify you as a user and your permissions assigned in DigiCert ONE. The client authentication certificate provides the second factor authentication.

In DigiCert ONE, select the profile () icon, and then select Admin Profile.
Under Client authentication certificates, select Create client authentication certificate.
For Nickname, enter a descriptive name for the key.
For End date, enter the date when the certificate should expire.
Select the desired Encryption and Signature hash algorithm.
Select Generate certificate. The password appears this one time and can't be accessed again. Download the certificate and securely store the password for future use.

Integration with Oracle Cloud Infrastructure

Set certificate file in environment variables:

Identify your downloaded client authentication certificate.
Encode the file to base64. For encoding run command:
```
base64 <file_name>
```
In OCI add a new vault secret with:
Name
Value
SM_CLIENT_CERT_FILE_B64
Base64 encoded client authentication certificate.

Name	Value
SM_CLIENT_CERT_FILE_B64	Base64 encoded client authentication certificate.

Setup certificate file for signing using the following commands:

  - type: Command
    timeoutInSeconds: 600
    name: "Certificate-Setup"
    command: |
      touch Certificate_pkcs12.p12
      echo "$SM_CLIENT_CERT_FILE_B64" > CERT_FILE.p12.b64
      base64 -d CERT_FILE.p12.b64 > Certificate_pkcs12.p12

Environment variables setup for OCI

The OCI client tools require you to create an OCI Vault, Master encryption key, secrets to connect with Software Trust Manager. To integrate Software Trust Manager environment variables with OCI:

To create the OCI Vault:

Sign in to OCI Console.
Navigate to Identity > Security & Vault.
Click Create Vault.

To create the Master encryption key:

Under Resources in the left navigation bar, select the appropriate Compartment from the dropdown menu.
Select Master Encryption Keys from the left navigation bar.
Select Create Key.

To create secrets:

Under Resources in the left navigation bar, select Secrets.
Click the Create Secret.

Add the following Software Trust Manager environment variables as secrets:

Variable	Description
SM_API_KEY	Provide your API token.
SM_CLIENT_CERT_FILE_B64	The base64 encoded text of certificate downloaded from client authentication certificate setup.
SM_CLIENT_CERT_PASSWORD	Provide your client certificate password.
SM_HOST	Provide your host environment.

Command to set environment variables:

env:
  vaultVariables:
    SM_HOST: ocid1.vaultsecret.oc1.iad.amaaaaaakc372dqaxe63v35kwhhcimfcoude5d4sbd2eaozuve555jhk4fwa
    SM_API_KEY: ocid1.vaultsecret.oc1.iad.amaaaaaakc372dqam7iepkmla7rrbg4o3uw6oj4ps5rn5yhrxjsnpiotq24a
    SM_CLIENT_CERT_PASSWORD: ocid1.vaultsecret.oc1.iad.amaaaaaakc372dqaudtlk2feyn55aqni2lli2qvygorke7tjj2z5oax32thq
    SM_CLIENT_CERT_FILE_BASE: ocid1.vaultsecret.oc1.iad.amaaaaaakc372dqan3tzwy46r4w2bulu7enizirgiw2mhp43jgxqrtlejqca
  variables:
    SM_CLIENT_CERT_FILE: /workspace/STM_Repo/Certificate_pkcs12.p12

Create certificate and keypair

You can create a test or production certificate. Certificate creation requires you to provide the certificate profile ID.

To retrieve the certificate profile ID:

Sign in to DigiCert ONE.
Select the Manager menu (top right) > Software Trust.
Navigate to: Certificates > Certificate profiles.
Click on the certificate profile alias that you want to use to generate the certificate with.
Note: The profile category must match the type of certificate you want to create.
Identify the Certificate profile ID field.

Anmerkung

You are required to provide an alias for the keypair and certificate in the steps below, these inputs must be unique, meaning the aliases cannot already exist in your Software Trust Manager account.

Create test keypair and certificate

To generate a RSA test keypair with certificate using OCI pipeline:

- type: Command
  timeoutInSeconds: 600
  name: "Generate Test Keypair"
  command: |
    smctl keypair generate rsa <Keypair Name> --cert-alias=<Certificate Name> --cert-profile-id=<Certificate Profile ID> --generate-cert=true --key-type=TEST

Create production keypair with certificate

To generate an RSA production keypair with a given certificate using the OCI pipeline:

- type: Command
  timeoutInSeconds: 600
  name: "Generate Production Keypair"
  command: |
    smctl keypair generate rsa <Keypair Name> --cert-alias=<Certificate Name> --cert-profile-id=<Certificate Profile ID> --generate-cert=true --key-type=PRODUCTION

Sign

Use one of the following script integrations to sign:

Jarsigner

To sign and verify signature with Jarsigner provide:

Path to the .jar file to be signed
Output path for the signed.jar file
Keypair alias or certificate alias that should be used to sign

- type: Command
  timeoutInSeconds: 600
  name: "Signing using jarsigner"
  command: |
    jarsigner -keystore NONE -storepass NONE -storetype PKCS11 -sigalg SHA256withRSA -providerClass sun.security.pkcs11.SunPKCS11 -providerArg pkcs11properties.cfg -signedjar <Path to output signed .jar> <Path to the .jar to be Signed> <Keypair alias or Certificate alias > -tsa http://timestamp.digicert.com    
    jarsigner -verify <Path to Signed .jar>

Jsign

To sign with Jsign provide:

.jar file to be signed
Keypair alias that should be used to sign

- type: Command
  timeoutInSeconds: 600
  name: "Signing using Jsign"
  command: |
    jsign --keystore pkcs11properties.cfg --storepass NONE --storetype PKCS11 --alias <keypair alias> <unsigned
file>

Sample pipeline

version: 0.1
component: build
timeoutInSeconds: 6000
runAs: root
shell: bash
steps:
  - type: Command
    timeoutInSeconds: 600
    name: "Certificate-Setup"
    command: |
      touch Certificate_pkcs12.p12
      echo "$SM_CLIENT_CERT_FILE_BASE" > CERT_FILE.p12.b64
      base64 -d CERT_FILE.p12.b64 > Certificate_pkcs12.p12

  - type: Command
    timeoutInSeconds: 600
    name: "Setup the client tools"
    command: |
      cd ${OCI_PRIMARY_SOURCE_DIR}
      curl -X GET https://one.digicert.com/signingmanager/api-ui/v1/releases/smtools-linux-x64.zip/download -H "x-api-key:$SM_API_KEY" -o smtools-linux-x64.zip
      unzip smtools-linux-x64.zip
      cp pkcs11properties.cfg smtools-linux-x64/pkcs11properties.cfg
      cd smtools-linux-x64
      chmod +x pkcs11properties.cfg
      chmod +x smctl
      chmod +x smpkcs11.so

  - type: Command
    timeoutInSeconds: 600
    name: "Signing using jarsigner"
    command: |
      cd ${OCI_PRIMARY_SOURCE_DIR}/smtools-linux-x64/
      jarsigner -keystore NONE -storepass NONE -storetype PKCS11 -sigalg SHA256withRSA -providerClass sun.security.pkcs11.SunPKCS11 -providerArg pkcs11properties.cfg -signedjar ../SIGNED.jar ../UNSIGNED.jar sign_clicktosign -tsa http://timestamp.digicert.com
      jarsigner -verify ../SIGNED.jar -certs -verbose

  - type: Command
    timeoutInSeconds: 600
    name: "Signing using Jsign"
    command: |
      curl -fSslL https://github.com/ebourg/jsign/releases/download/3.1/jsign_3.1_all.deb -o jsign_3.1_all.deb
      ar x jsign_3.1_all.deb
      tar -xf data.tar.gz
      cd usr/share/jsign/
      chmod +x jsign.sh
      chmod +x jsign-3.1.jar
      mkdir /usr/share/jsign
      cp jsign.sh /usr/share/jsign/
      cp jsign-3.1.jar /usr/share/jsign/
      mv jsign.sh /usr/bin/jsign
      cd ${OCI_PRIMARY_SOURCE_DIR}/smtools-linux-x64/
      jsign --keystore pkcs11properties.cfg --storepass NONE --storetype PKCS11 --alias sign_clicktosign ../UNSIGNED1.msi

env:
  vaultVariables:
    SM_HOST: ocid1.vaultsecret.oc1.iad.amaaaaaakc372dqaxe63v35kwhhcimfcoude5d4sbd2eaozuve555jhk4fwa
    SM_API_KEY: ocid1.vaultsecret.oc1.iad.amaaaaaakc372dqam7iepkmla7rrbg4o3uw6oj4ps5rn5yhrxjsnpiotq24a
    SM_CLIENT_CERT_PASSWORD: ocid1.vaultsecret.oc1.iad.amaaaaaakc372dqaudtlk2feyn55aqni2lli2qvygorke7tjj2z5oax32thq
    SM_CLIENT_CERT_FILE_BASE: ocid1.vaultsecret.oc1.iad.amaaaaaakc372dqan3tzwy46r4w2bulu7enizirgiw2mhp43jgxqrtlejqca
  variables:
    SM_CLIENT_CERT_FILE: /workspace/STM_Repo/Certificate_pkcs12.p12

In diesem Abschnitt: