Public Key Signing and Verification

Updated: August 7, 2017

SmartKey can create digital signatures and verify signatures using RSA or elliptic curve keypairs.

Prerequisites

Performing public key cryptography requires an SmartKey account, a group with an RSA or elliptic curve key, and an application configured in that group. See the SmartKey Developer’s Guide for more details.

Required Operations

The RSA or elliptic curve key must have the Sign operation enabled for creating signatures and the Verify operation enabled for verifying signatures. In addition, the key must be enabled.

Authorization and Configuration

You must first authenticate and optionally configure a default API client as described in Configure API Client and Client Authentication. Signing and verification requires authenticating as an app with an API key or a client certificate. (User accounts may not create signatures or verify them.)

Create a SignAndVerifyApi Client Object

Signatures and verification are performed using a SignAndVerifyApi object.

import com.fortanix.sdkms.v1.api.SignAndVerifyApi();

SignAndVerifyApi signatureApi = new SignAndVerifyApi();

Creating a Signature

Creating a signature requires a private key. (Verification can be performed with only a public key).

Create a Signature Request

The signature request object encodes the request parameters. The required parameters are the hash data to be signed, and the hash algorithm used to create the hash. For example, to create a signature request using the SHA-256 hash algorithm:

import com.fortanix.sdkms.v1.model.SignRequest;
import com.fortanix.sdkms.v1.model.DigestAlgorithm;

SignRequest signatureRequest = new SignRequest().hashAlg(DigestAlgorithm.SHA256).hash(<hash value as bytes[]>);

Note that command-line programs like sha1sum and sha256sum typcially output digests in hexadecimal format. These will need to be converted into binary format before they are used.

Make the Signature Call

The hash is signed with the sign() method of the SignAndVerifyApi object. sign() is called with the UUID of the key used to perform signature, and the signature request. The UUID of the key can be found in the key details page of the UI, or it can be retrieved by looking up keys with the API. The signature is returned as a byte arrray in the signature property of the SignResponse object returned by the sign() method.

import com.fortanix.sdkms.v1.model.SignResponse;

SignResponse signResponse = signatureApi.sign(<key UUID>, signatureRequest);
byte[] signature = Response.getSignature();

Verifying a Signature.

You will need a public key in order to verify a signature.

Create a Verify Request

The signature verification request object encodes the request parameters. The required parameters are the hash data that was signed, the hash algorithm used to produce that hash, and the signature. For example, to create a signature verification request using the SHA-256 hash algorithm:

import com.fortanix.sdkms.v1.model.VerifyRequest;
import com.fortanix.sdkms.v1.model.DigestAlgorithm;

VerifyRequest verifyRequest = new VerifyRequest().hashAlg(DigestAlgorithm.SHA256).hash(<hash value as bytes[]>).signature(<signature as bytes[]>);

Make the Verify Signature Call

The signature is verified with the verify() method of the SignAndVerifyApi object. verify() is called with the UUID of the key used to perform verification, and the verification request. The UUID of the key can be found in the key details page of the UI, or it can be retried by looking up keys with the API. The result property of the VerifyReponse object will be true if the signature was correctly verified, and false if the signature did not match.

import com.fortanix.sdkms.v1.model.VerifyResponse;

VerifyResponse verifyResponse = signatureApi.verify(<key UUID>, verifyRequest);
bool verified = verifyResponse.result;