EzSign can make use of any HSM that supports the PKCS#11 interface.  The steps to configure EzSign for use with an HSM are simple and are outlined below but before any confguration takes place, the following pre-requisites must be in place: 

  • The HSM must be networked, configured and the Security World must be loaded
  • The local HSM client software must be installed and the HSM must be enrolled
  • Any passwords (such as the operator cardset password) must be available

 To confirm that the server can see and communicate with the HSM run the enquiry command e.g. C:\nCipher\nfast\bin\enquiry.exe

This will output details about the HSM, cardsets and the status

 

EzSign Server Configuration

Edit the server.properties file and add a new channel as shown below:

channel.1.name=CHANNELNAME
channel.1.enabled=true
channel.1.tokenType=PKCS11
channel.1.token.password=
channel.1.token.pkcs11.library=C:/nCipher/nfast/toolkits/pkcs11/cknfast-64.dll
channel.1.token.pkcs11.slot=1
channel.1.signature.hash=SHA256
channel.1.signature.includeCerts=ALLEXCEPTROOT
channel.1.signature.includeContent=false
channel.1.signature.keyId=
channel.1.revocationChecker.type=NONE
channel.1.verify.nonRepudiationRequired=true
channel.1.verify.denyWeakHash=false
channel.1.verify.relaxAllCertExtensionChecks=true

The key points to note are:

The channel number (e.g. channel.1) increments for every channel, so if you have any previous channels configured (which you wish to retain) then the number should be incremented (e.g. if you had settings for channel.1 already, then these settings would all start channel.2)

The tokenType is PKCS11

The token.password value should be blank for now, as we will set this later

The value for token.pkcs11.library should be the PKCS#11 library.  You should reference the 32 or 64 bit versions depending on the host system

The value for token.pkcs11.slot depends on how your HSM has been setup.  Usually the module is at slot 0, and operator card sets at slot 1, 2...etc.  Usually slot 1 refers to the operator card set if only one has been created

Other options can be altered as required

 

Configure Passwords

Next start the EzSign Management utility (ezsign-manage.bat [properties file]).  Enter the master password and choose option 1.  Follow the prompts which require you to set the master password again, then the token password.  in this instance the token password will be the HSM password.  If an operator card set has been created this will be the passphrase associated with that cardset (set when the cardset is created)

The utility will prompt to save the updated file

This will result in the token.password setting being populated with the encrypted password

Exit the utility

 

Generate CSR

When ready to generate a CSR, start the Management utility and choose option 2 to Generate a CSR.  This will be the same process as when software CSRs are generated.  Note, that the token password will be the operator cardset password for the HSM

Once the CSR has been generated, send this to the CA and obtain the certificates as .cer files.  Obtain the entire chain (issued end-entity certificate plus any intermediates and the root).  Import via the Management utility using option 4

When the end-entity certificate has been imported you will be prompted whether you wish to set this as ths signing key.  Choose yes, and the properties file will be updated, populating the signature.keyId value

 

Run the Server

Assuming all steps were succesfull and the HSM is operational the server can now be started and signing operations should use the key generated on the HSM

 

 

Thales HSMs support Module protection as well as Operator Card protection

The latter involves creating an Operator Cardset and assigning a Passphrase to the cards.  Objects stored on the HSM are then protected by the Module as well as this Cardset and applications that wish to make use of these objects not only must have access to the HSM but must also supply the Operator Cardset Passphrase

Thus, access to objects such as private keys require the user to be logged on to the HSM, providing the Passphrase before access is granted

If Module only protection is used then objects are still stored protected by the module's internal master keys, but can be accessed by any application (that has access to the HSM) without the need to log on to the HSM with a passphrase

Within EzSign, the Operator Cardset Passphrase is provided as the Token Password.  This is encrypted by the Master Password.  The server may be started by supplying the Master Password but sensitive operations such as CSR generation and the import of certificates require that the Token password is also entered.  This prevents operational staff (responsible for managing the server) from also having the ability to perform sensitive operations.  Another team (e.g. Security) can own the Token/Operator Cardset password.  It is therefore, recommended that an Operator Cardset be created when using Thales HSMs

However, if other security controls are in place which restrict an application's access to an HSM and there is no need to restrict the operational user from performing sensitive operations, then Module-Only protection can be enabled as follows:

 

Edit the EzSign Server Configuration

The server properties file must be updated for the channel that wishes to make use of Module protection only.  The following property must be set:

    channel.N.token.useModuleProtection=true

Where 'N' is the channel number e.g.

    channel.1.token.useModuleProtection=true

 

The entry for the following property:

     channel.N.token.password

 

Can then be left empty and no Token password needs to be set via the Management Utility.  When generating CSRs or importing certificates via the Management Utility, when asked for the Token password, just hit return, as it is not required

 

 

Run the Server

The server can be started in the normal way but on starting the following warning will be output to the logs:

2017-09-14 10:06:26.085 [main] WARN  EzSignLog - Module protection is enabled.  This means that no password is required to access the keys on the Token/HSM.  Ensure that other sufficient security controls are in place to prevent unauthorised access

 

When a CSR is generated, the private key will not require a passphrase for access

 

 

Viewing Object's Protection Level

To verify what protection each object within the HSM is under, from the nFast bin directory, run the following command:

    nfkminfo -l

 

This will display all items (together with the label) sorted by protection e.g.:

Keys with module protection:
key_pkcs11_ua114f29785ea013fd5eca7e6cd7614c796bc24a06 `15e7f5e09ff2030'
key_pkcs11_ua1df56ecd5514769c92c361e2e3c799745bfd0b96 `nopassword'

...

Keys protected by cardsets:
key_pkcs11_uc725e1d27135c1b5dbb296f63be079fa827cf65fd-0317f899c8a6737e8506278850b57bf1b7b29e9e `OTP_SEED_SYM_KEY'
key_pkcs11_uc725e1d27135c1b5dbb296f63be079fa827cf65fd-49b37b070741ea08fccdafffcd3298e01306806e `15ab7ef2ff43176'

...

Before configuring EzSign with an HSM it is worth performing a quick check that everything is working as expected and all libraries and passwords are correct

The steps below outline some steps that can be taken to verify everything is ready to go

 

HSM Status

The nCipher HSMs provide several commands for verifying the setup is correct

These utilties are normally located at (On UNIX)

    /opt/nfast/bin

 

Or on windows:

    C:\Program Files (x86)\nCipher\nfast\bin

 

First run the enquiry command e.g. On Unix from a shell run:

    ./enquiry

 

On Windows, from a Command Prompt, run:

    enquiry.exe

 

The output will be split into several sections:

    Server:

    ...

    Module #1:

    ...

And if there is more than one module configured you will also see headings for these, e.g.:

  Module #2:

  ...

  etc.

 

The key things to note are that each of the module entries are showing:

  mode      operational

 

If there are no entries beneath the Server heading, first try starting the hardserver.  On Unix:

    /opt/nfast/sbin/init.d-ncipher start

 

On Windows, start the nFast Server service

 

HSM Test Tool

If all looks OK, download the Krestfield HSM Test tool from here:

 

Run the tool as follows:

From a UNIX shell:

    > ./hsmtest.sh


From a Windows Command Prompt:

    hsmtest.bat

 

    > Krestfield HSM Test Tool

 

    Enter PKCS#11 library path > /opt/nfast/toolkits/pkcs11/libcknfast-64.so    <-- Enter the full path to the PKCS#11 library

 

    PKCS#11 Token: Loading the PKCS#11 library: /opt/nfast/toolkits/pkcs11/libcknfast-64.so...

    PKCS#11 Token: Loaded PKCS#11 Driver /opt/nfast/toolkits/pkcs11/libcknfast-64.so OK

    HSM Driver loaded OK

 

    There are 2 slots:

 

    Slot: 0

      slotDescription:                                                                

      manufacturerID: nCipher Corp. Ltd              

      flags: CKF_TOKEN_PRESENT | CKF_HW_SLOT

      hardwareVersion: 0.00

      firmwareVersion: 0.00

 

    Slot: 1

      slotDescription: SFHSMTTOCS                                                     

      manufacturerID: nCipher Corp. Ltd              

      flags: CKF_TOKEN_PRESENT | CKF_REMOVABLE_DEVICE | CKF_HW_SLOT

      hardwareVersion: 0.00

      firmwareVersion: 0.00

 

    Select Slot > 1 <-- Enter the slot number - normally 1 if an operatore card set is in use

 

    PKCS#11 Token: Opening session...

    PKCS#11 Token: Opened session for slot 1 OK

    HSM Session Opened OK.  Session ID: 2251

 

    Enter HSM OCS Passphrase > <-- Enter the operator cardset password and press enter

 

    PKCS#11 Token: Password provided, attempting logon...

    PKCS#11 Token: Logged on to Token

 

    Logged in OK.  Configuration is good

 

This tool performs the same operations to connect to the HSM as EzSign.  Therefore, if you see this success message, translating the values entered above into the following properties: 

    channel.1.tokenType=This must be set to PKCS11
    channel.1.token.password=Set this as the operator password (as entered above) via the Management Utility
    channel.1.token.pkcs11.library=Set this to be the same path as entered above
    channel.1.token.pkcs11.slot=Set this to be the same number slot as entered above

e.g.

    channel.1.tokenType=PKCS11
    channel.1.token.password=Mt3WQvXz6fUy2yhpNC5ZBxCdPJWsy2Ol1QdLH3c1pogbHViP7oDeQA==
    channel.1.token.pkcs11.library=/opt/nfast/toolkits/pkcs11/libcknfast-64.so
    channel.1.token.pkcs11.slot=1

Should result in a successfull HSM setup

If you wish to extract the signer certificate from a PKCS#7/CMS formatted signature using C#, the following steps can be used:

 

Add a Reference

From your .NET project, add a reference to System.Security

 

Directives

Add the following using directives to your source file:

using System.Security.Cryptography.Pkcs;
using System.Security.Cryptography.X509Certificates;

 

Code

The following method will accept a base64 encoded signature and return the signer certificate

You will then be able to extract details from this certificate as required

 

public X509Certificate getSignerCert(String b64Signature)
{
    byte[] binarySignature = Convert.FromBase64String(b64Signature);

    SignedCms cms = new SignedCms();
    cms.Decode(binarySignature);

    SignerInfoCollection coll = cms.SignerInfos;

    // Normally there is just the one signer certificate, which this will return
    SignerInfoEnumerator siEnum = coll.GetEnumerator();
    if (siEnum.MoveNext())
    {
        X509Certificate signerCert = siEnum.Current.Certificate;
        return signerCert;
    }

    // If you are expecting more than one signer, then use the following
    // to extract the signer from each signature
    /*
    foreach (SignerInfo si in coll)
    {
        X509Certificate cert = si.Certificate;

        // Add cert to array and return the array
    }
    */

    throw new Exception("No signer certificate was found in the provided signature");
} 

 

Example

 

    String b64Signature = "MIAGCSqGSIb3D....MocqJA56a3n3vJUk=";
    X509Certificate signerCert = getSignerCert(b64Signature);
    String serialNum = signerCert.GetSerialNumberString();
    String subject = signerCert.Subject;

 

 

 

 

 

If you receive a Path Build Exception error this indicates that either the certificate path is not complete - in that a valid certificate path could not be found from the end-entity (signer) certificate to a trusted root certificate, or that there was another issue with one or more certificates in the path e.g. an expired certificate or a rule violation

 

Check the Logs

Where is the log file?

The EzSign log file should contain the actual reason for the failure. e.g.

  Path Build Exception: Path Build: Path building failed.  Could not find issuer for : CN=BANK001001, OU=Engineering, O=Krestfield Ltd, C=GB

This will give the reason for the path build failure 

 

 

Incomplete Paths

Errors such as the following:

  Path Build Exception: Path Build: Path building failed.  Could not find issuer for : CN=BANK001001, OU=Engineering, O=Krestfield Ltd, C=GB

Are caused because either the root certificate is not present in the channel or the signature itself does not contain the required intermediate certificates

To determine which, you may copy the Signature data sent, and paste into the Signature Toolkit tool.  This will display the certificates included in the signature which can then be analysed

You can install the root certificate (or any other certificates required, including the intermediate CA certificates) via the Management Utility, choosing the Import Certificate option

Once all the required certificates have been installed, restart EzSign and attempt the verification again

Note: This may not be an error condition at all.  The siganture being verified may have been signed by a rougue or spoofed certificate and EzSign is rejecting it for this reason

 

Rule Violation

Errors such as the following:

  Path Build Exception: The key size of the certificate CN=BANK001001, OU=Engineering, O=Krestfield Ltd, C=GB is 2048 bits.  This is less than the minimum key size of 4096 bits specified

Are due to the rules specified in the configuration, or within the custom path checker (if enabled)

In this specific case, the following property:

  channel.1.verify.minKeySize=4096

Requires that the certificate must have a key size of at least 4096 bits

The property can be relaxed (e.g. to 2048) but the rule may be in place for a specific security reason, in which case the signature has been rejected intentionally

Other settings that perform checks on the path and siganture are shown below:

  channel.1.verify.signedAttribsRequired=true
  channel.1.verify.denyWeakSignatureHash=false
  channel.1.verify.denyWeakCertificateHash=false
  channel.1.verify.relaxRootCertExtensionChecks=false
  channel.1.verify.relaxAllCertExtensionChecks=false
  channel.1.verify.nonRepudiationRequired=true
  channel.1.verify.caBasicConstraintsRequired=true
  channel.1.verify.minKeySize=2048
  channel.1.verify.maxKeySize=8192

 

Contact Us

Email: This email address is being protected from spambots. You need JavaScript enabled to view it.

Call: 020 8938 3616

Krestfield Limited, International House, 24 Holborn Viaduct, London, EC1A 2BN

Sales & Support

Should you need any help with any of Krestfield's products, or wish to make any suggestions, please contact us.

Sales: sales@krestfield.com

Support: support@krestfield.com

Latest News

PKCloud

Version 2.1.0 released

EzSign

Version 4.1.2 released

 

Our Mission

To create secure, highly available, easy to use products that are priced fairly

Please publish modules in offcanvas position.