Skip to main content

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

  1. Sign in to DigiCert ONE.

  2. Navigate to DigiCert​​®​​ Software Trust Manager > Resources > Client tool repository.

  3. Select Linux.

  4. 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:

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

  2. Copy and paste the following text into the editor:

  3. Save the file as pkcs11properties.cfg.

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

User authentication

Software Trust Manager enforces multifactor authentication for security. To access keypairs, certificates, and sign code, you need to set up two types of credentials: an API token and an authentication certificate.

Create an API token

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

Follow these steps to generate an API token:

  1. Sign in to DigiCert ONE.

  2. Select the profile icon (top-right).

  3. Select Admin Profile.

  4. Scroll down to API Tokens.

  5. Select  Create API token.

    Nota

    The API token is only shown once, securely store the API key to use it later.

Create an authentication certificate

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

Follow these steps to create a client authentication certificate:

  1. Sign in to DigiCert ONE.

  2. Select the profile icon (top-right).

  3. Select Admin Profile.

  4. Scroll down to Authentication certificates.

  5. Select Create authentication certificate.

    Nota

    The client authentication certificate password shown after creating an client authentication certificate cannot be accessed again, download the certificate and securely store the password to use it later.

Integration with Oracle Cloud Infrastructure

Set certificate file in environment variables:

  1. Identify your downloaded client authentication certificate.

  2. Encode the file to base64. For encoding run command:

    base64 <file_name>

  3. In OCI add a new vault secret with:

    Name

    Value

    SM_CLIENT_CERT_FILE_B64

    Base64 encoded client authentication certificate.

  4. 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:

  1. Sign in to OCI Console.

  2. Navigate to Identity > Security & Vault.

  3. Click Create Vault.

To create the Master encryption key:

  1. Under Resources in the left navigation bar, select the appropriate Compartment from the dropdown menu.

  2. Select Master Encryption Keys from the left navigation bar.

  3. Select Create Key.

To create secrets:

  1. Under Resources in the left navigation bar, select Secrets.

  2. Click the Create Secret.

  3. 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:

  1. Sign in to DigiCert ONE.

  2. Select the Manager menu (top right) > Software Trust.

  3. Navigate to: Certificates > Certificate profiles.

  4. 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.

  5. Identify the Certificate profile ID field.

Nota

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://stage.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
Nesta secção: