This module exposes a RESTful API for performing cryptographic signing of messages.
Cryptographic signing is carried out against a remote instance, which requires mutual TLS authentication to secure the communications. This requires using private and public keys to secure the communications between this instance and the remote signing instance.
The current version and release history of the Jpo-security-svcs: Jpo-security-svcs Release Notes
The following table depicts the RESTful API exposed by the jpo-security-svcs module:
| Verb | path | Content Type | Functionality | Request Body Format | Response Body Format |
|---|---|---|---|---|---|
| POST | /sign | application/json | signs data provided in the body of the request | {"message":"Base64 encoded unsigned data"} | {"result": "Base64 Encoded Signed Data"} |
Send a POST request to localhost:8090/sign with a body of the form:
{
"message": "<hex encoded data>"
}
Expected output:
{
"result": "<hex encoded data + signature>"
}
- Install Docker
- Set up a directory to contain your own JKS file.
- Set up a subdirectory in the above directory called "caCerts" to contain any CA certificates (one per file) from the remote system that need to be installed in the Java truststore on boot.
- Copy the sample.env file to a new '.env' file and populate with your settings. See Configuration for more information.
- Build & run the application using
docker compose up --build -d - To spin down the container, run
docker compose down
- Install Maven
- Install Java
- Configure the properties file as needed (see Configuration)
- Package the application using
mvn clean install - Run the application using
java -jar target/jpo-security-svcs-0.0.1-SNAPSHOT.jar
In ./src/main/resources/application.properties you'll find the following properties which can be defined whether on the command line or by environment variable. To define the property on the command line, insert -- to the front of the Property name, for example, --server.port=8091:
| Property | Meaning | Default Value | Environment Variable Substitute |
|---|---|---|---|
| server.port | The port number to which this service will be listening. | 8090 | SERVER_PORT |
| sec.cryptoServiceBaseUri | Cryptographic service endpoint URI excluding path. For example, http://<ip>:<port> OR http://server.dns.name including the port number, if any. |
- | SEC_CRYPTO_SERVICE_BASE_URI |
| sec.cryptoServiceEndpointSignPath | The REST endpoint path of the external service. | /tmc/signtim | SEC_CRYPTO_SERVICE_ENDPOINT_SIGN_PATH |
| sec.useCertificates | Whether to use certificates or not. | true | SEC_USE_CERTIFICATES |
| sec.keyStorePath | The path to the keystore file. | /home/cert.jks | SEC_KEY_STORE_PATH |
| sec.keyStorePassword | The password for the keystore file. | password | SEC_KEY_STORE_PASSWORD |
For enhanced security, MTLS is used to communicate with a remote signing system. This requires properly configured certificates from the remote system to properly perform - work with your remote signing authority to obtain necessary certificates.
Certificates can be in several different formats, including the widely used PEM format. Because this is a Java application, the signing certificates must be in the Java Keystore format to be used. The following commands using OpenSSL and the Java keytool will convert a PEM file to a Java Keystore file.
- Convert the PEM file to a PKCS12 file:
openssl pkcs12 -export -in <cert.pem> -inkey <key.pem> -out <certificate.p12> -name <alias>
- Convert the PKCS12 file to a Java Keystore file:
keytool -importkeystore -srckeystore <certificate.p12> -srcstoretype pkcs12 -destkeystore <cert.jks>
If your remote signing authority is using their own certificates as a CA, you may need to import those certificates into your Java truststore to allow the handshake to go through. Note that when running the dockerized application, these CA certificates are to be one certificate per file (chain certificates are not supported).
If running in VS Code, a launch.json has been included to allow for ease of debugging. A .env file can be created using the sample.env file as a starting point. Once this settings file is in place, simply click the green arrow in the debug tab to run the application. At this point all breakpoints will function as expected.
To run the unit tests, reopen the project in the provided dev container and run the following command:
mvn test
A script has been provided to test the endpoint. To use this script, run the following command:
./hit_endpoint.sh <data to sign>
This script will send a POST request to the endpoint with the provided data to sign. The output will be the signed data returned from the endpoint. See Usage for more information on the expected input and output.