Generating Code Signing Key and CSR

A code signing certificate identifies an organization (your company), and connects it to a public key that will be used to verify your signature. The certificate is signed by a trusted Certificate Authority. CORE provides the following methods to generate a signing key and CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate for your organization based on this key:

• Use UCL
• Use OpenSSL
• Use Java

For working in a clientlessSystem that is using Unbound Java Security Provider without dependency on the UKC Client software. environment, see Using the Provider in Clientless Environment.

Use UCL

The following four steps must be repeated each time you create a certificate:

1. Generate a key-pair using one of the following:
   • ucl generate -t RSA
   • ucl generate -t ECC

Make sure that the key --purpose includes the signing capability.

2. Create a CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate signed by the key that was generated above.
   
• ucl csr
  

3. Deliver the CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate to CA and obtain the CA-signed certificate.
4. Import the CA-signed certificate:
   • ucl import

Use OpenSSL

The ucl csr contains standard certificate extensions (EXT). To add the missing extensions you may opt using OpenSSL and its -extfile filename option.

1. Run dy_openssl script to add Unbound OpenSSL library to the openssl.cnf file. See CORE OpenSSL Engine.
2. Use ucl export --obfuscated command to create a handle to the key for use by the OpenSSL commands (MyKey.pem). See Export Obfuscated Key.
3. Use OpenSSL to create the CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate using MyKey.pem.
openssl req -out MyCSR.pem -key MyKey.pem -new -subj "/CN=Me/OU=myOU/O=MyO"
4. Deliver the CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate to CA and obtain the CA-signed certificate.
5. Import the CA-signed certificate:
   • ucl import

Use Java

Use the Java keytool to achieve the following in the CORE:

• keytool -genkeypair - generate a key that signs the CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate.
• keytool -certreq - generate the CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate and sign it with the key.
• keytool -importcert - import the signed certificate.

Note
Java 9 (and above) discontinued the method to integrate Java Security Provider's JAR into Java Extensions. In the following examples we use the universal inline JAR-specification option applicable to the Java 8, 9, 10 and 11 releases. See Unbound Provider's Parameters.

Keytool to Create CSR

Note. Examples in this section assume:

• Access to the single partition (obsoletes the -providerarg parameter).
• The user is the default user (sets the -storepath to NULL).
• The environment is Java 11 on Ubuntu18 (impacts the -providerpath).

Step 1: Generate Key Pair

Note
Skip this step to use the self-signed key that already exist in the partition.

Generate an RSA key pair and store it in CORE:

keytool -genkeypair -keyalg RSA -keysize <size> -alias <key name> \
-dname <distinguished name to be used in the certificate's subject> \
-Unbound Provider's Parameters

For example (see Note regarding examples in this section): 

keytool -genkeypair -keyalg RSA -keysize 4096 -alias KT-RSA-1 -dname CN=Wiki \
-keystore NONE -storetype PKCS11 -providername UNBOUND \
-storepass NULL \
-providerclass com.unbound.provider.UBCryptoProvider \
-providerpath /usr/lib/ekm-java-9-provider-2.0.jar

Step 2: Generate CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate

Create a CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate and store it in the <Name of CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate File> file:

keytool -certreq -alias <Name of Key> -file <Name of CSR file> \
-Unbound Provider's Parameters

For example:

keytool -certreq -alias KT-RSA-1 -file certreq.txt \
-keystore NONE -storetype PKCS11 -providername UNBOUND \
-storepass NULL \
-providerclass com.unbound.provider.UBCryptoProvider \
-providerpath /usr/lib/ekm-java-9-provider-2.0.jar

Step 3: Obtain and Import CA-Signed Certificate

1. Deliver the CSRCertificate Signing Request - a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate to the CA and obtain a certificate in a file.
2. Import a certificate.

1. Import from a file.

keytool -importcert -alias <Name of the Key> -file <Name of the obtained cert file> \
-Unbound Provider's Parameters

For example (see Note regarding examples in this section): 

keytool -importcert -alias KT-RSA-4096-1 -file KT-RSA-4096-1.cer \

-keystore NONE -storetype PKCS11 -providername UNBOUND \

-storepass NULL \

-providerclass com.unbound.provider.UBCryptoProvider \

-providerpath /usr/lib64/ekm-java-provider-2.0.jar



The expected output is:

“Certificate was installed in keystore.”

Note
The message "Certificate was added to the keystore" indicates a failure to bind the signed certificate to the already existing private key. Use keytool -list to examine the partition.

2. Import from Keystore

Use the following syntax to import a a signing key and its certificate from another Java keystore. In this example we use JKSA Java KeyStore (JKS) is a repository of security certificates – either authorization certificates or public key certificates – plus corresponding private keys, used for instance in SSL encryption. keystore as the source.

keytool -importkeystore \
-srckeystore <KS.jks> -srcstoretype JKS -srcstorepass <KS_PWD> \
-srcalias <ALIAS_SRC> [-srckeypass <ALIAS_SRC_PWD>] \
-destalias <ALIAS_SRC> \
-Unbound Provider's Parameters


The following example imports a test1 key and certificate from JKSA Java KeyStore (JKS) is a repository of security certificates – either authorization certificates or public key certificates – plus corresponding private keys, used for instance in SSL encryption. to CORE:

keytool -importkeystore \
-srckeystore test.jks -srcstoretype JKS -srcstorepass SrcJksPassword \
-srcalias test1 destalias test1\
-keystore NONE -storetype PKCS11 -providername UNBOUND \
-storepass NULL \
-providerclass com.unbound.provider.UBCryptoProvider \
-providerpath /usr/lib64/ekm-java-provider-2.0.jar

Test the Setup of Unbound Provider

To test the Unbound Provider integration and parameters, use keytool -list:

keytool -list \
-Unbound Provider's Parameters

For example, in Java 11 environment:

Linux:

keytool -list
-keystore NONE -storetype PKCS11 -providername UNBOUND \
-storepass NULL \
-providerclass com.unbound.provider.UBCryptoProvider \
-providerpath /usr/lib/ekm-java-9-provider-2.0.jar

Windows:

keytool -list \
-keystore NONE -storetype PKCS11 -providername UNBOUND \
-storepass NULL \
-providerclass com.unbound.provider.UBCryptoProvider \
-providerpath "C:\Program Files\Dyadic\ekm-client\lib\ekm-java-9-provider-2.0.jar"

Unbound Provider's Parameters

In the following sections <UB-Provider-JAR> indicates the complete path to the CORE Java Provider JAR in your file system. See Unbound Java Provider JARs.

The following keytool parameters shall be used to specify Unbound Java Provider:

• -keystore NONE
• -storetype PKCS11
• -providername UNBOUND
• -storepass See The -storepass Options
• -providerclass com.unbound.provider.UBCryptoProvider
• -providerpath <UB-Provider-JAR>

The -storepass Options

Unbound uses the -storepass option to specify the user's credentials.

• Default user:
  •  -storepass NULL for the default password.
  • -storepass <the password>for non-default password.

    Make sure to escape all characters in the password that may be misinterpreted by your shell.

• Non-default user:
  • -storepass '{\"username\":\"<name>\", \"password\":\"<user's password>"}'
    • For example, a user whose credentials are [signer, Password1!] shall use the following:

    -storepass '{\"username\":\"signer\", \"password\":\"Password1\!\"}'

  • -storepass:file <file with credentials>.json
    • create a text file with JSON-formatted specification of the credentials

    {"username":"user's name", "password":"user's password"}.

    For example, create credentials.json file with the following line:
    
    {"username":"signer", "password":"Password1!"}.

  • -storepass:env <credentials environment variable>
    • For example:
    export CREDENTIALS= \'{\"username\":\"signer\", \"password\":\"Password1\!\"}'