Skip to main content

Java Code Signing

Java applications that interact with the Pi Soft kS through the Java TEAgent (which is within the TEAdmin.jar) can be signed and the use of only signed code enforced.  Code signing is offered to prevent the development of an application or other code using the Pi Soft Java SDK that duplicates the functionality of trusted code but actually subverts the Pi Soft functionality, such as by copying authentication credentials or keys to a text file.  To prevent the introduction of subversive code, Java archive files are signed and the signatures stored within the kS.  When signed code is required only connections from code whose signatures are verified by the kS are allowed.

When the requirement for the kS to interact only with signed code is enforced this requirement is extended to the kS Manager and other Pi Soft Java applications as well.  A CA chain file and the signing certificate are included in packages which install the kS Manager.  For Linux these are eruces-ks-version.rpm and eruces-ls-mgr-version.tar.gz.  Within Windows, this chain file is included whenever the kS Manager is selected when using the Autorun, the kS installer, or setup-manager.exe. The section below titled Pi Soft Distributed Jar Files describes how to ensure the Pi Soft Java applications' remain usable by the kS.

The requirements to keep in mind when developing in Java with the intention of requiring that code be signed are below:

  • Code that calls Java TEAgent (in TEAdmin.jar) must be signed.
  • The signing certificate should be registered and verified by the kS.
  • TEAgent will get its caller class at runtime.
  • TEAgent will get its calling deployment package (signed jar) name from its caller class.
  • TEAgent will verify both the signature and the signing certificate.
  • TEAgent builds an in-memory cache to speed up the caller verification.
  • The kS has functionalities that can verify the signing certificate

Sequence​

Signing​

  1. Create a jar file of all code that calls the Pi Soft Java TEAgent.
  2. Sign the jar file with a private key.
  3. Export the signing certificate and its certificate chain (if any) for registration.

Registration​

  1. Import the root CA and intermediate CAs.
  2. Register the signing certificate with kS.

Signed Code Enforcement Process​

  • Signed code calls TEAgentConnection open.
  • TEAgentConnection finishes the authentication to the kS.
  • TEAgentConnection asks if enforcement is turned on by checking the kS policy.
  • TEAgentConnection gets its caller class through CallerUtil.
  • TEAgentConnection gets its caller jar name.
  • JarVerifier opens the jar, and verifies the jar is signed.
  • TEAgentConnection send certificate verification request to the kS.
  • The kS first checks the persisted repository to see if the certificate exists (and whether signature matches the saved version if per version enforcement is required).
  • CodeSignManagementModule will ask CertStore to verify the signing certificate.
  • If all the checks are fine, the connection is returned to caller.
  • If verification passed, the jar name will be put to the JVM signed code in-memory LRUcache. The cache is used to speed up verification upon next calls during the JVM life cycle.

Pi Soft Distributed Jar Files​

Pi Soft includes Java archive files in the installation packages.  These include TEManager, EFEClient, LogReporter, etc. and are pre-signed using Verisign certificates. The signing certificate and CA chain file are distributed during the kS Manager installation.  You must provide your own certificate when signing your code since a private key is required.

The CA chain file, verisign-code-signing.pem and the signing certificate, verisign-code-signing.cer are located in the kS Manager directory or folder and are not imported by default.  Follow the instructions below for adding the CA to the kS and registering TEManager-version.jar before you enable code signing.  Alternatively, you can sign the Pi Soft jars using your own certificate without use the included chain file.  Multiple signers are supported.

Usage​

Signing Java Code​

Please refer to http://docs.oracle.com/javase/tutorial/security/sigcert/index.html  and http://docs.oracle.com/javase/tutorial/deployment/jar/signing.html ((link last checked 22 July 2014)

Using the keytool and jarsigner from the JDK:

  • Create a key store.  The public/private key will be created at the same time.
    keytool -genkey -alias [private key entry name] -keyalg RSA -keystore agent.jks -keysize 2048
  • Generate the certificate signing request (CSR).
    keytool -certreq -alias [private key entry name] -keystore agent.jks -file agentsigner.csr
  • Get the signing certificate and certificate chain files from the CA.
  • **Import the certificate chain.  (This is optional since we only use this key store for signing.)**keytool -import  -file [root cert or chain]  -keystore agent.jks -alias [alias of the root or chain certificate]
  • Import the Signing certificate to replace the self-signed one.
    keytool -import  -file [signing cert name] -keystore agent.jks -alias [private key entry name]
  • Sign the jar.
    jarsigner -keystore agent.jks -signedjar [name of the signed jar] [name of the un-signed jar] [private key entry name]
Suite B High deployments require EC

A kS configured at Suite B High refuses RSA CSRs — generate an EC key instead (e.g. keytool -genkeypair -keyalg EC -groupname secp384r1 ...) before creating the CSR. The RSA example above applies to non-Suite-B deployments only.

Adding the CA (Or Chain) to the kS​

CAs can be imported into the kS in one of two ways.  You can use the tecert command line interface utility (included in the kS and dS installation packages) or you can use the Certificate Settings panel in the kS Manager.  Additional information about tecert can be found in the kS Guides.

  • **Using tecert:**tecert importca admin password chain_file [server [port]]
    Note: chain_file is in pkcs7 (PEM) format.
  • Using kS Manager:
    Go to the Certificate Authority tab on the Certificate Settings panel. 
    Right click and select Add CA to import the Certificate Authority certificate information or Import Certificate Chain to import the chain file for the CA.

Registering Signed Code​

The command line interface utility, manageSC, registers signed code.  The signing certificate must be in X509 format.  Signed code can be registered so that the digest is enforced or not.  When enforcement of the code digest is set to true, any changes to the jar requires that the jar be re-registered.  If it enforcement of the code digest is set to false, as long as the jar name remains the same, a changed jar does not need to be registered.  Usage of manageSC can also be found in the kS documentation.

  • Using manageSC
    manageSC –register [name of the signed jar] [signing certificate file name] [code digest enforcement true or false]
    Notes: 
    signing certificate must be X509 format
    code digest enforcement:
    true:  Enforces code digest. (If you change/update your code after registration, the changed code has to be re-registered.)  The kS policy must be set to Strict.
    false: Does not enforce code digest.  (As long as the code is signed and the jar name stays the same, you do not need to re-register changed code.)
    Example: manageSC --register signed.jar signing.cer false

Implementing Code Signing​

To enable code signing for Java applications, use the Policy panel in the kS Manager. Select the Strict or Enabledradio button. Strict enforcement requires individual registration of signed jars along with the certificate used to sign them (with or without digest enforcement).  Enabled permits self-registration of signed jars, provided the CA or Chain has been imported.

List Signed Code​

ManageSC can be used to retrieve a list of signed code.  The first column is an ID which can then be reference when a jar should be unregistered.  The second column is the jar file name.  The third column is the Boolean value of code digest enforcement.  0 is false, that is the digest is not enforced.  1 is true, that is the digest is enforced and all changes to a jar require re-registration.

  • manageSC –l
    Sample Output:

        id                  signed_code_name                        is_digest_on

        14001            s_teadmin.jar                                0

Unregistering Signed Code​

Remove Signed Code by removing the registration.

  • manageSC --remove id | [name of the signed jar] [signing certificate file name]
    Examples: 
    manageSC –re  14001
    manageSC –re s_teadmin.jar signing.cer

Updating Signed Code​

If the contents of a jar change and the code digest is enforced, the jar must be un-registered and then registered again.