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
.
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.
-
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" -
Allow-list the signing certificate in the VaultCode configuration.
vaultcode:
certificates:
whitelist:
- |
--BEGIN--
DEV 1 PEM HERE
--END--
- |
--BEGIN--
DEV 2 PEM HERE
--END-- -
Compile your code into a JAR.
-
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 -
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" -
Call VaultCode to run your JAR
curl "https://demo-vaultcode.securosys.com/api/v1/execute"
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 of JARs can be onboarded to allow different logic to be used.
Which Option to Use
You have four options:
- Use nothing.
- In this case VaultCode allows uploading any JAR.
- Allowlist only fingerprints.
- Allowlist only certificates.
- 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 |
|
|
Cons |
|
|