Exception Handling

The Primus JCE Provider throws RuntimeExceptions to indicate failures. All exceptions inherit from the com.securosys.primus.jce.PrimusProviderException base class. For a list of all known sub-classes, please see the Javadoc.

How to retry requests

The JCE Provider does not automatically retry failed requests to the HSM. Instead, it throws an exception, and lets the business application decide how to handle it. This is because the business application has more insight into the context of the HSM call.

Depending on the use case, the application may decide to retry a limited number of times, or to fail immediately. For example, PrimusAuthorizationExpiredException indicates that the SKA timeout has passed, and PrimusAuthorizationInsufficientException indicates that the SKA policy is not satisfied. In both cases, the application can collect new signed approvals and then retry the request.

Whenever the application retries a failed call, the JCE provider applies the same selection algorithm as for any fresh call. This includes selecting which HSM in a cluster to send the request to. Therefore, transient errors (such as an HSM being unavailable due to a firmware update) can often be fixed by immediately retrying a request, possibly with a backoff.