noamik/yubihsm-java

A java library used to interact with the YubiHsm

JAVA YubiHSM

Java-yubihsm is a java library used to interact with a YubiHSM 2 device

Compilation

To compile from source, run

$ ./gradlew build

This will automatically run all tests after compilation. To compile without running tests, run

$ ./gradlew build -x test -x integrationTest

Tests

There are three test sets in this library, one for unit tests, one for integration tests and one for the device options test.

Unit Tests

To run all unit tests, run:

$ gradle clean test

To run one unit test, run

$ gradle test -Dtest.single=<TEST NAME>

Integrations Tests

The integration tests assume that the YubiHSM contains the default authentication key, which is an authentication key with Object ID 1, password password and alla capabilities and delegated capabilities. Most tests will reset the device before it starts.

The integration tests also assume that the YubiHSM is accessible via the URL defined in the environment variable DEFAULT_CONNECTOR_URL

To run all integration tests, run

$ gradle clean integrationTest

To run one integration test, run

$ gradle integrationTest -DintegrationTest.single=<TEST NAME>

Running all integration tests can take 10-15 minutes

Device Options Test

The device options test changes the audit log settings on the device. When run with the other tests, it will cause the log to fill quickly and all tests failing because of it. That is why this test is run in its own test set.

To run the device options test, run

$ gradle clean optionsTest

Or

$ gradle optionsTest -DoptionsTest.single=OptionsTest

Release Guide

Releasing is done into maven central (Sonatype).

Before making the release, make sure that the .gradle/gradle.properties contains the right credentials and profile ID as the values to the properties ossrhUsername, ossrhPassword and ossrhProfileId. These are the credentials to log into Sonatype

1. Update the version number in build.gradle file and push the change. If the release is a release candidate, the version number should be in the format X.Y.Z-RC[U], where:

   • X: Major version

   • Y: Minor version

   • Z: Build version

   • U: The number of the release candidate if there are more than one release candidate

2. Tag the release on git. Run git tag to list the current tags. To tag, for example, release 1.0.0, run:

   $ git tag -s 1.0.0 -m "(tag: 1.0.0) libyubihsm"
   $ git push --tags

3. Check one more last time that all tests pass on Travis

4. Build and sign the release packages

   $ ./gradlew jar
   $ ./gradlew packageSources
   $ ./gradlew packageJavadoc
   $ ./gradlew signArchives -x integrationTest -x test -x optionsTest

5. Upload the project to maven central by running the command bellow. To check that the upload worked, log into Sonatype and go to Staging Repositories. The uploaded files should be found in the bundle at the bottom of the list.

   $./gradlew uploadArchives -x integrationTest -x test -x optionsTest

6. Close the bundle and release the library by running:

   $ ./gradlew closeAndReleaseRepository

If this command fails, try to close and then release from Sonatype. Log in there and go to Staging Repositories. Mark the bundle containing the newly uploaded files and click the Close button at the top of the list. If every thing goes well, mark the same bundle and click the Release button at the top of the list. The bundle should now disappear from the staging repositories view.

To verify that the library was released properly, go to Repositories and click Releases on the upper frame. In the lower frame, go to Browse Storage and expand com/yubico/java-yubihsm. The new release should be listed there.

The command ./gradlew closeAndReleaseRepository can also be divided into two commands:

$ ./gradlew closeRepository
$ ./gradlew releaseRepository