# 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.9-linux-x86_64.jar`

On Mac OS:

`java -jar java-spiffe-helper-0.8.9-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.