105 lines
3.9 KiB
Markdown
105 lines
3.9 KiB
Markdown
# JAVA-SPIFFE Helper
|
|
|
|
The JAVA-SPIFFE Helper is a simple utility for fetching X.509 SVID certificates from the SPIFFE Workload API,
|
|
and storing the Private Key and the chain of certificates in a Java KeyStore in disk, and the trusted bundles (CAs)
|
|
in a separated TrustStore in disk.
|
|
|
|
The Helper automatically gets the SVID updates and stores them in the KeyStore and TrustStore.
|
|
|
|
## Usage
|
|
|
|
On Linux:
|
|
|
|
`java -jar java-spiffe-helper-0.8.13-linux-x86_64.jar`
|
|
|
|
On Mac OS:
|
|
|
|
`java -jar java-spiffe-helper-0.8.13-osx-x86_64.jar`
|
|
|
|
You can run the utility with the `-c` or `--config` option to specify the path to the configuration file. By default, it
|
|
will look for a configuration file named `conf/java-spiffe-helper.properties` in the current working directory.
|
|
|
|
## Config file
|
|
|
|
```
|
|
keyStorePath = /tmp/keystore.p12
|
|
keyStorePass = example123
|
|
keyPass = pass123
|
|
|
|
trustStorePath = /tmp/truststore.p12
|
|
trustStorePass = otherpass123
|
|
|
|
keyStoreType = pkcs12
|
|
|
|
keyAlias = spiffe
|
|
|
|
spiffeSocketPath = unix:/tmp/agent.sock
|
|
```
|
|
|
|
### Configuration Properties
|
|
|
|
| Configuration | Description | Default value |
|
|
|--------------------|-------------------------------------------------------------------------------|-------------------------------------------------------|
|
|
| `keyStorePath` | Path to the Java KeyStore File for storing the Private Key and chain of certs | none |
|
|
| `keyStorePass` | Password to protect the Java KeyStore File | none |
|
|
| `keyPass` | Password to protect the Private Key entry in the KeyStore | none |
|
|
| `trustStorePath` | Path to the Java TrustStore File for storing the trusted bundles | none |
|
|
| `trustStorePass` | Password to protect the Java TrustStore File | none |
|
|
| `keyStoreType` | Java KeyStore Type. (`pkcs12` and `jks` are supported). Case insensitive. | pkcs12 |
|
|
| `keyAlias` | Alias for the Private Key entry | spiffe |
|
|
| `spiffeSocketPath` | Path the Workload API | Read from the system variable: SPIFFE_ENDPOINT_SOCKET |
|
|
|
|
KeyStore and TrustStore **must** be in separate files. If `keyStorePath` and `trustStorePath` points to the same file,
|
|
an error is shown.
|
|
If the store files do not exist, they are created.
|
|
|
|
The default and **recommended KeyStore Type** is `PKCS12`. The same type is used for both KeyStore and TrustStore.
|
|
|
|
It is **strongly recommended** to set restrictive file permissions for KeyStore file, since it stores a private key:
|
|
|
|
`chmod 600 keystore_file_name`
|
|
|
|
Make sure the process running the JAVA-SPIFFE Helper has _write_ permission on the KeyStores files.
|
|
|
|
### Debug
|
|
|
|
To check that the certs are being stored in the KeyStore:
|
|
|
|
`keytool -list -v -keystore keystore.path -storepass example123`
|
|
|
|
The output should be a `Private Key Entry`:
|
|
|
|
```
|
|
Keystore type: PKCS12
|
|
Keystore provider: SUN
|
|
|
|
Your keystore contains 1 entry
|
|
|
|
Alias name: spiffe
|
|
Creation date: Jun 2, 2020
|
|
Entry type: PrivateKeyEntry
|
|
|
|
Owner: O=SPIFFE, C=US
|
|
Issuer: O=SPIFFE, C=US
|
|
...
|
|
```
|
|
|
|
In the case of the TrustStore, it should display a `trustedCertEntry`:
|
|
|
|
```
|
|
Keystore type: PKCS12
|
|
Keystore provider: SUN
|
|
|
|
Your keystore contains 1 entry
|
|
|
|
Alias name: example.org.0
|
|
Creation date: Jun 2, 2020
|
|
Entry type: trustedCertEntry
|
|
|
|
Owner: O=SPIFFE, C=US
|
|
Issuer: O=SPIFFE, C=US
|
|
...
|
|
```
|
|
|
|
The aliases for the trusted certs are generated using the Trust Domain of the SPIFFE ID in the SAN URI, and adding a
|
|
correlative number suffix. |