Link Search Menu Expand Document

Google KMS Configuration


This document gives a brief overview of the installation and setup steps required to support Google Cloud KMS from EzSign


Pre-Requisites

You must have a Google Cloud account and created a project

You must have created a key ring from the Security Cryptographic Keys section in Google Cloud

Note that it is recommended that a dedicated key ring be assigned to EzSign as it will be creating and deleting keys within this key ring

A service account is required. In order to perform PKI operations the account must have the following permissions:

  • Cloud KMS Admin

  • Cloud KMS CryptoKey Signer

  • Cloud KMS CryptoKey Public Key Viewer

If you also wish to perform symmetric operations, it must also have the following permission:

  • Cloud KMS CryptoKey Encryptor/Decryptor

It is recommended that a dedicated service account is created for EzSign. This service account should first be created with minimum global privileges e.g. Public Key Viewer and then the additional privileges (Signer, Admin etc.) configure on the specific key ring

The service account must have a key pair and you must have downloaded the JSON file containing the keys. This file is required to authenticate to the service from EzSign


Configuration


Navigate to ./ezsign-vX.Y.X/EzSignServer/config and edit googlekms.properties

Update the following properties:

keyStoreDir

This is where EzSign stores its key components. When using an HSM of any kind, these components only ever contain references to keys stored on the HSMs

By default it is set to a relative path ../keystores which means if you run the commands from the ./bin directory this will get picked up ok. But if you call any jars directly then you must set this to the full path. This can point to [Install Dir]/EzSignServer/config/keystores or you can choose an alternative location. The account running the software must have write permissions on this folder and it must already exist

e.g.

keyStoreDir=/opt/ezsign/EzSignV4.1.0/EzSignServer/keystores

channel.1.token.googleKms

Set the following properties to the values that are configured in your Google Cloud Console

channel.1.token.googleKms.project=cloudproject1
channel.1.token.googleKms.location=europe-west2
channel.1.token.googleKms.keyRing=default
channel.1.token.googleKms.credentialFile=/home/ezs-user/ezsign/google.json

Where:

channel.1.token.googleKms.project is project ID of the project in the Google Cloud console. E.g.

img

channel.1.token.googleKms.location should be set to the location of your existing key ring e.g. this is europe-west2 for the ezsign key ring shown below:

img

channel.1.token.googleKms.keyRing is just the name of the key ring (ezsign in the example above)

channel.1.token.googleKms.credentialFile is the filename (including the full path) to the JSON file as downloaded when you created the service account. You are able to generate a new JSON file by going to the IAM section in the Google Cloud Console, choose Service Accounts and select the service account that has been configured for access to the key ring

img

Click ADD KEY under the Keys section and select Create new key. Select JSON as the type and click Create. Then save the produced .json file

Note that the json file contains the private key and is sensitive. Anyone who has access to this file may access your keys. Therefore, protect access to this file

log.level

This is set to 4 by default which is the maximum (debug level) amount of logging. EzSign itself does not log profusely but the Google KMS components do. Once you are happy that everything is working as expected you may wish to reduce this to 3 (or lower)

Importing Existing Keys

Navigate to ezsign-v4.1.0\EzSignServer\bin and edit envs.sh

set the JAVA_HOME parameter to the location of java you are using

Save envs.sh then run

./ezsign-manage.sh ../config/googlekms.properties

Krestfield EzSign Management
----------------------------

The master password is required to manage the server

Enter password:

Type password and press Enter

Note: This master password encrypts the channel password that is configured in this setting:

channel.1.token.password

It is not stored and will be required to be entered if you start the server or call the java directly

Token passwords are used to encrypt local copies of keys. However, in the case of Google KMS no actual keys are stored. The only information that EzSign stores are the key references (i.e. project name, location, key ring name and key name). For a production environment it is recommended to change these passwords. See the installation guide for a description of channel and master passwords and how to change them

From the options displayed, select

4. Import Existing HSM Keys

At the Channels section, enter 1 to choose the Google Kms channel and press Enter

For the Token Password enter password and press Enter

Importing objects from the HSM…

Objects imported from the HSM OK

If you see this message it indicates that the keys (or rather, references to them) have been imported from the Google KMS into EzSign. To verify, check the keyStores folder configured above. There should now be a sub-directory called GoogleKms (or whatever you have called the channel) which will contain new files with extensions of .priv and .pub e.g.

-rw-rw-r– 1 ec2-user ezs-user 204 Jul 1 08:12 17305b484ff8593.priv

-rw-rw-r– 1 ec2-user ezs-user 204 Jul 1 08:12 17305b484ff8593.pub

-rw-rw-r– 1 ec2-user ezs-user 184 Jul 1 08:12 bass1.priv

-rw-rw-r– 1 ec2-user ezs-user 184 Jul 1 08:12 bass1.pub

Note that if there are no objects shown, this can be for several reasons. Including:

· You may be pointing to the wrong key ring (which does not have any existing objects)

o Check the value set for: channel.1.token.googleKms.keyRing

· The credentials in the json file are not correct

o Check that channel.1.token.googleKms.credentialFile contains the full path and the file contents are correct. Create a new key and download a new json file if not

· Existing keys are disabled or destroyed

o From the console if you click on a key its state will be shown. This must show ENABLED

· Existing key versions are not 1

o If you have versions that are not set to 1, you can add the following property:

channel.1.token.googleKms.keyImportVersion

to the configuration, specifying the version of the keys you wish to import e.g.

channel.1.token.googleKms.keyImportVersion=2

Then re-run the import process

Checking the logs at ./EzSignServer/logs/ezsign.log will help identify which of these issues have occurred

Once imported you need to obtain any certificates you have been issued that would have been generated from CSRs (Certificate Signing Requests) created using these keys. Also obtain any intermediate and root certificates e.g. you may have files such as: signercert1.cer, intermediate.cer, root.cer

For each of these certificates, perform the following:

  1. From the Management menu, select option 3. Import Certificate
  2. Select the Google Kms channel
  3. Enter the full path to the certificate e.g. /opt/ezsign/certs/root.cer and press Enter

If EzSign discovers that a certificate matches one of the keys previously imported, you will be asked if you wish to set this as the default signing certificate. Choosing ‘y’ will result in the properties file being updated to configure this. See the example output below:

Channels

-——-

  1. GoogleKms

Select Channel Number: 1

Path to certificate: /home/ezs-user/certs/google1.cer

Certificate imported successfully

Do you wish to set this as the default signing certificate? (y/n): y

A backup of the original has been saved to ../config/googlekms.properties.2020.07.01.08.39

Ready to update properties file ../config/googlekms.properties with the new passwords

Proceed? (y/n): y

The properties file ../config/googlekms.properties has been updated successfully.

Ensure that all certificates in the path are imported (you cannot generate signatures if the full path is not imported). Verify this by selecting option 6. Display Certificates and confirming that Current Signing Certificates shows the certificates you expect to sign with

Making Calls from your Java Application

Normally, EzSign is run as a server application called via the Krestfield Client API or a REST API. This is the simplest option and enables local configuration that does not need to be connected to or managed by your application

However, if you choose to call the java directly, from your java application, add a reference to the following jar:

[EzSign Installation Dir]/EzSignV4.1.0/EzSignServer/lib/ezsign-4.1.0.jar

In your application, set the following imports:

import com.krestfield.ezsign.KEzSign;
import com.krestfield.ezsign.KEzSignException;
import com.krestfield.ezsign.KSigningException;

and the following is an example showing the use of the KEzSign class for signing:

**try ** { // You can also load the properties in to a java.util.Properties object and

// pass this in place of the filename

String propertiesFile = “/EzSignV4.1.0/EzSignServer/config/googlekms.properties”;

 
    // The password here is the master password.  If you change this in the 
    // configuration you must also change it here
    KEzSign ezSign = new KEzSign(propertiesFile, "password", 1);
    String channelName = "GoogleKms";
    // hashedData is a SHA-256 hash of the original data
    // You can provide the raw data (and let EzSign hash it for you) but in production
    // it is more efficient to hash the data first
    byte[] hashedData = {0x55, 0xb5 ... 0x9d}; // 32 bytes required
    // The data returned in sig will be a PKCS7 formatted signature
    byte[] sig = ezSign.signData("1", channelName, hashedData, true);
}
catch (KEzSignException e)
{
    e.printStackTrace();
}
catch (KSigningException e)
{
    e.printStackTrace();
}