Loading Your JAR Executables

To extend the security of your VaultCode, client developed JAR executables should be allow-listed, either via a code signing certificate or via JAR hash. Allowlisting JARs allows the HSM operator to restrict which JARs can be loaded to VaultCode. Allowlisting is done using the configuration options in the application.yml.

Operators can limit the maximum size of a JAR via the vaultcode.maxExecutableSize setting. VaultCode enforces that this setting is set to 500 MB or less.

Example Use Case

While developing locally, each developer can have their own JKS, that they do not share with other developers, similar to their own private keys. In CI/CD pipelines, the pipeline can have its own code signing certificate to build and deploy your JARs to a test environment.

Lastly, once you are in production, the certificate should be strictly protected and access to it should be limited and maintained. For example, only Release Managers have access to the signing certificate, that is stored inside an HSM. Alternatively, you could allowlist only fingerprints in production, to enforce explicit and intentional upgrade ceremonies.

Allowlist Code Signing Certificates

To streamline the development process while maintaining security, you can use code signing certificate. Multiple certificates can be onboarded to allow changes from different developers who each have their own certificate.

1. Create a code signing key pair per environment or developer.

   keytool -genkeypair \
      -alias "VaultCode Dev Signing Certificate" \
      -keyalg "RSA" \
      -keysize "4096" \
      -validity "365" \                          # Valid for 365 days
      -keystore "vaultcode_keystore.jks" \
      -storepass "strong_keystore_password" \
      -keypass "strong_private_key_password" \
      -dname "CN=Developer Name VaultCode, OU=IT, O=Company, L=Zurich, ST=Zurich, C=CH"

2. Allow-list the signing certificate in the VaultCode configuration.

   vaultcode:
      certificates:
         whitelist:
            - |
               --BEGIN--
               DEV 1 PEM HERE
               --END--
            - |
               --BEGIN--
               DEV 2 PEM HERE
               --END--

3. Compile your code into a JAR.

4. Sign your JAR.

   jarsigner \
      -keystore vaultcode_keystore.jks \         # Which keystore to use
      -storepass strong_keystore_password \      # Keystore password
      -keypass strong_private_key_password \     # Private key password
      -signedjar ./executable_signed.jar \       # Name of signed JAR
      ./executable_unsigned.jar \                # Name of JAR to be signed
      "VaultCode Dev Signing Certificate"        # Alias of key in keystore

5. Upload your JAR to VaultCode

   JAR=/path/to/signed_executable.jar
   curl "https://demo-vaultcode.securosys.com/api/v1/upload_execution_code" \
      --form "file=@${JAR};type=application/java-archive"

6. Call VaultCode to run your JAR

   curl "https://demo-vaultcode.securosys.com/api/v1/execute"

tip

Use the Primus Tools as a drop-in replacement for keytool and jarsigner. These allow you to use keys that are stored on an HSM instead of in a local file.

Allowlist Executable Hashes

The configuration file for VaultCode also allows the option vaultcode.fingerprint to allow-list executable JARs.

vaultcode:
  fingerprint: 
    - "e7fd9dec16945df11753dfcac5f2993bac870991868d2ea59ee957e7f3053ad3"
    - "3adb6f0729d4bae2bd15d442d713949e45928a716aa692c97690d180cc6a3349"

Multiple fingerprints can be listed to allow JARs to be swapped out dynamically. Note that at runtime, clients still need to call the /api/v1/upload_execution_code endpoint to upload (and thus change to) another JAR. The benefit is that SOs can allow-list all JARs once ahead of time.

Which Option to Use

You have four options:

1. Define nothing.
   • In this case VaultCode allows uploading any JAR.
2. Allowlist only fingerprints.
3. Allowlist only certificates.
4. Allowlist both fingerprints and certificates.

In cases 2, 3, 4: if multiple fingerprints and/or certificates are configured, as long as the uploaded JAR is allowed by at least one of them, the JAR is allowed.

Both approaches have benefits and downsides. Below is an overview of what to consider when deciding which option is best for your use case.

	Certificate	Fingerprint
Pros	More flexibility Faster development (possible CI/CD pipelines) Reduced SO interaction	More security Guarantees only the intended executables are allowed (4-eye principle)
Cons	If private key is compromised the wrong executable could be uploaded	Requires SO interaction for each new executable Cannot be integrated into CI/CD pipelines