Skip to main content

Introduction

The Axway Validation Authority (VA) Server is an Online Certificate Status Protocol (OCSP) server for distribution of certificate revocation information for certificates issued by any certification authority (CA). The VA Server provides integrity and validity for online transactions by validating, in real-time, digital certificates issued by a CA. The Entrust nshield Hardware Security Module (HSM) integrates with the Axway VA responder server through the nshield PKCS #11 cryptographic API to securely generate and store the OCSP response signing keys. The following image shows such an integration:

architecture

Requirements

The Axway VA installation requires either Microsoft Windows Server or Red Hat Enterprise Linux as the base operating system. Conceptually, a CentOS platform will work the same way. You can get the installation package for Windows or Linux from Axway Support.

The Axway Validation Authority Administrators Guide recommends the following hardware specification for installing a production Axway VA responder server.

Component Minimum Requirement

Processor

3.0 GHz, quad core/CPU

Memory

16 GB

Hard Disk

500 GB

Network Adapter

1

System components required for installation:

Component Version

Red Hat Enterprise Linux

7.x

Microsoft Windows Server

2012 R2, 2016, or 2019

Firewall

Linux firewalld or Windows Firewall

Before starting this integration, familiarize yourself with:

  • The documentation for the nshield Connect HSM.

  • The documentation and configuration process for Axway VA.

Before you start to use nshield products:

  • For creating a Security World, define who within the organization act as custodians of the administrator card set (ACS).

  • Obtain enough blank smart cards to create the ACS. Six cards are delivered with the nshield Connect HSM.

  • Define the Security World parameters. For details of the security implications of the choices, see the nshield Security Manual .

Licensing

Configuring Axway VA requires importing a license text file into the Axway VA administration web UI. You must have this license file when you configure Axway VA.

Product configurations

Entrust tested nshield HSM integration with Axway VA in the following configurations:

Axway VA nshield Hardware nshield HSM Firmware Security World Software FIPS

5.2

Connect XC

12.50.11

12.80.4

140-2 level 3

5.2

Connect XC

12.72.1

12.80.4

140-2 level 3

Supported nshield functionality

Feature Support

Key Generation

Yes

Key Management

Yes

Key Import

No

Key Recovery

Yes

FIPS 140-2 Level 3 mode support

Yes

Common Criteria mode support

N/A

1-of-N Operator Card Set

Yes

K-of-N Operator Card Set

Yes

Softcards

Yes

Module-only keys

Yes

Load Sharing

Yes

Failover

Yes

Procedures

An overview of the integration procedures is as follows:

Install and configure the nshield HSM

This guide does not cover the basic installation and configuration of the nshield HSM or the nshield Security World client software. For instructions, see the Installation Guide for your HSM.

Important
When you are creating the Operator Card Set (OCS) or Softcards for the Security World, the passphrases must match the VA server password that will be set in the initial VA server configuration process. The VA server password must be at least 8 characters in length and include one uppercase letter, one lowercase letter, one number, and one special character. The same is true of the OCS/Softcard passphrase.

  1. Add the following lines to the cknfastrc configuration file of the Security World. The file is in the %NFAST_HOME% directory, which is C:\Program Files\nCipher\nfast on Windows and /opt/nfast on Linux.

    • Module protection: 

      CKNFAST_OVERRIDE_SECURITY_ASSURANCES=none
CKNFAST_FAKE_ACCELERATOR_LOGIN=1

    • Softcard protection: 

      CKNFAST_OVERRIDE_SECURITY_ASSURANCES=none
CKNFAST_LOADSHARING=1
CKNFAST_NO_ACCELERATOR_SLOTS=1

    • OCS protection with a K/N quorum where K=1: 

      CKNFAST_OVERRIDE_SECURITY_ASSURANCES=none
CKNFAST_LOADSHARING=1
CKNFAST_NO_ACCELERATOR_SLOTS=1

    • OCS protection with a K/N quorum where K>1: 

      CKNFAST_OVERRIDE_SECURITY_ASSURANCES=none
CKNFAST_LOADSHARING=1
CKNFAST_NO_ACCELERATOR_SLOTS=1
NFAST_NFKM_TOKENSFILE=C:\ProgramData\nCipher\nfast-nfkm-tokensfile

    On Windows, C:\ProgramData\nCipher\nfast-nfkm-tokensfile is an example location for creating the preload file. On Linux, an example location is NFAST_NFKM_TOKENSFILE=/opt/nfast/kmdata/nfast-nfkm-tokensfile . You can change it to another location as required.

  2. Optionally, enable PKCS #11 debugging by adding the following lines to cknfastrc : 

    CKNFAST_DEBUG=10
CKNFAST_DEBUGFILE=C:\ProgramData\nCipher\Log Files\pkcs11.log

    On Windows, C:\ProgramData\nCipher\Log Files\pkcs11.log is an example location for the log file. On Linux, an example is CKNFAST_DEBUGFILE=/opt/nfast/log/pkcs11.log .

Select the key protection method

If more than one key protection mechanism is available (for example: OCS and Softcard; OCS and module protection; or two Softcards), you must modify the C:\ProgramData\nCipher\Key Management Data\local directory on Windows to contain the minimum required key protection mechanism files. On Linux, this directory is /opt/nfast/kmdata/local . That is, if you are using a certain key protection method, make sure that only the files pertaining to that specific method are present in the local directory.

If you are using module protection, remove all OCS and Softcard files from local . Make sure that an ACS card is inserted into an available slot of the HSM. The ACS card can provide FIPS-authorization in place of the OCS card for this application (which will not work since the associated OCS card file must be removed).

If you are using Softcard protection:

  • Remove all OCS files from local .

  • Make sure that an ACS card is inserted into an available slot of the HSM to provide FIPS-authorization.

If you are using OCS protection:

  • Remove all Softcard files from local .

  • Insert the OCS quorum to provide FIPS-authorization.

For either OCS or Softcard protection:

  • Make sure you have only the Softcard or OCS card files for the token used to protect the OCSP signing key. That is, do not have multiple Softcard files or multiple OCS card file sets.

For more information about the environment variables used in cknfastrc , see:

  • The nshield Cryptographic API Guide .

  • The PKCS #11 library environment variables section of the User Guide for the HSM.

Initial VA server setup and configuration

Axway VA consists of:

  • A VA Host Server acting as either a Repeater or Responder operating on Windows Server or Red Hat Enterprise Linux.

  • A web-based Administration Server that provides centralized management of the validation processing components.

Client applications can query the VA Server utilizing open standard protocols including the Online Certificate Status Protocol (OCSP) or the Server-based Certificate Validation Protocol (SCVP), allowing clients to delegate the entire certificate validation operation including path construction and intermediate CA validation to the VA Server.

This section describes how to set up and configure a Responder. Before setting up the Axway VA Server (Responder), you must:

  • Obtain a Responder product license from Axway and make it available on the host platform.

  • Obtain a root certificate from a CA and make it available in on the host platform.

  • Obtain an associated Certificate Revocation List (CRL) for the CA and make it available on the host platform.

To install the Axway VA (Responder) server:

  1. Before installing Axway VA, install the nshield Security World software. This is especially important for Linux installation, so that you can select nfast as the group to run the VA server.

  2. See the Axway VA Administrators Guide for steps on installing the server on Windows and Linux.

  3. After installing Axway VA, browse to the Axway VA Web Administration and log in using the credentials specified during installation.

    If you are using OCS protected keys with a K/N quorum where K>1, use preload to load the OCS K/N quorum. Enter the OCS passphrase when prompted. 

    % preload -m<module-number> -c <ocs-cardset-name> -f <path-to-nfkm-tokensfile> pause

  4. Select the Enter License tab.

  5. Paste the license certificate from Axway into the license text box and select Submit License .

  6. On the Axway Validation Authority License page, confirm the license details and select Next Step .

  7. On the Import Configuration File page, select Skip .

  8. On the Install Custom Extensions page, select NO , then select Submit .

  9. On the Server Password page, enter and confirm the new VA server password.

    The password must match the OCS or Softcard passphrase and is required to have at least:

    • 8 characters in length

    • one alphabetic character

    • one digit

    • one special character

    • one upper case character

    • one lower case character

      Note
      		If your server password already matches the OCS or Softcard passphrase and meets these minimum requirements, you may skip this step. Select Create/Import Key Pair to go to the next step.

  10. Select Submit when finished.

  11. On the SUCCESS! page, select Next Step .

  12. On the Key Type Selection page, under Mandatory , select Default OCSP/SCVP Response Signing and select Submit Key Type .

  13. On the Key Generation/Import Mechanism: Default OCSP/SCVP Response Signing page, select Hardware Key Generation/Import using nCipher .

    If that is not an option, select the following:

    • Hardware Key Generation/Import on custom PKCS11 provider

    • Vendor : Entrust

    • PKCS#11 Library Path :

      • Windows: C:\Program Files\nCipher\nfast\toolkits\pkcs11\cknfast.dll

      • Linux: /opt/nfast/toolkits/pkcs11/libcknfast.so

  14. Select Submit Key Generation Technique .

  15. Select Generate new private key .

  16. Select Submit Key Generation or Import .

  17. On the Generate Hardware key and Certificate: Default OCSP/SCVP Response Signing page:

    1. Under PKCS11 Token Information :

      • For User PIN , enter the VA server password, which is also the OCS or Softcard passphrase. If you are using module protection, enter the VA server password.

      • For Friendly Key Name , enter a name to identify the key.

      • For Key Expiration in days , enter 0 for non-expiring keys or enter another number for the key lifetime.

      • For Slot ID , select either -1 or the decimal number representing the PKCS11 slot. Do not select Auto Sense .

        If you are using module protection (loadsharing is disabled in cknfastrc ), this decimal number will begin with 4929711 .

        If you are using OCS or Softcard (loadsharing enabled in cknfastrc ), this decimal number will begin with 7614066 .

      • For Key Algorithm , select RSA .

      • For Key Length , select 2048 .

      • For Hash Algorithm , select SHA256 (or any other algorithm except SHA1 ).

    2. Under Certificate Information :

      • For Type , select Self-signed Certificate .

        Alternatively, select Certificate Request if you want to have an external CA sign the certificate.

      • For Certificate Validity (days) , enter the certificate validity period (default = 365 days).

      • Select Simple DN Entry and enter the certificate parameters (country, city, and so on).

    3. Under Certificate Options , select Key Use: Sign/Signature Verification .

      Leave all other options clear.

  18. Review the PKCS11 token and certificate parameters and select Submit when finished.

  19. If the key and certificate were successfully generated, a SUCCESS! message appears, followed by Self signed certificate for Default OCSP/SCVP Response Signing was created successfully. Click here to view certificate information .

    If there is an error and you enabled PKCS#11 debugging in cknfastrc , check the contents of the debug file at the path specified to troubleshoot key generation.

    To generate a private key for OCSP responses, the following files are created:

    • OCSP_RESP_SIGN_<DateTimeStamp>_GMT.crt (Self-signed OCSP Responder certificate)

    • OCSP_RESP_SIGN_<DateTimeStamp>_GMT.req (PKCS#10 request)

    • vacs<DateTimeStamp>

    These files are located as follows:

    • Windows: C:\ProgramData\Axway\VA\entserv\.vacsbak

    • Linux: /var/lib/va-01/entserv/.vacsbak

  20. Open a command prompt and run the following command to verify the key is listed under the key protection method you intended: 

    % nfkminfo -l
Keys protected by cardsets:
  key_pkcs11_ucf581378f4a81d3ba312fcd19859247049bf18161-53ec9f29251f88e948217499c4736daf16027193 `<Friendly Key Name> RSAPrv'

  21. Back on the VA server web UI, select Click here to view certificate information .

    A dialog appears and displays the OCSP response signing certificate that was generated.

  22. Select Next Step .

    The generated certificate is used to digitally sign OCSP and SCVP responses from the Validation Authority server. OCSP requests are essentially queries to the VA server asking for the status of a certificate (good, revoked, or unknown) for a specific Certificate Authority.

    The private key used to sign the responses from the VA server is stored and protected within the HSM.

    The next step is to configure CA certificates for which the VA server will provide OCSP responses.

  23. On the Manage Certificate Store page:

    1. Under Mandatory Stores , select CA Certificates [OCSP Protocol] .

    2. Select Submit .

  24. On the Certificate Import Method page:

    1. Select Local File .

    2. Select Submit Certificate Import Method .

  25. On the Import Certificate File page:

    1. Select Choose File and select the root CA certificate for which you want the VA server to provide OCSP responses.

    2. Select Submit Certificate File .

  26. On the Select Certificates page:

    1. Confirm the details for the imported CA certificate.

    2. Select Submit Certificates if the displayed information is correct.

  27. On the Configure VA Certificate Store page:

    1. Make sure the root CA certificate is listed.

    2. Select Add to add more root CA certificates (repeat above process) or select Next Step to continue.

  28. On the Configure CRL Imports page:

    1. Select the appropriate method for retrieving a CRL associated with the CA.

    2. Select Add CRL Source .

      Note
      		Integration testing was done using an HTTPS CRL source. The next few steps reflect this selection.

  29. On the Configure CRL Import (HTTP/FTP/FILE) page:

    • Under CRL Source :

      • Set Protocol to the appropriate protocol for retrieving the CRL source information. For this guide, HTTPS was used.

      • CRL Source URL : Enter the URL for the CRL source. See the Axway Validation Authority Administrators Guide for the appropriate syntax for the selected protocol.

      • CRL Encoding : Select the appropriate encoding from the dropdown.

      • Configure other parameters as needed.

    • Leave the Import Schedule and Connection Settings to their defaults and select Add Source .

  30. Return to the Configure CRL Imports page and repeat the steps above to add additional CRL sources.

  31. Select Next Step to continue.

  32. On the Configure Server URLs page, enter the following:

    • For Hostname , enter the hostname or IP address set during installation.

    • For Port , select 80 .

    • Select Add and then Submit .

    Note
    		This is the URL and port the VA server will listen on for OCSP requests/queries.

  33. On the SUCCESS! page, select Next Step .

  34. On the VA Responder Server Configuration Parameters page:

    1. Configure as appropriate for your environment. See the Axway Validation Authority Administrators Guide .

    2. Select Submit Configuration Parameters .

  35. On the SUCCESS! page, select Next Step .

  36. On the Server Start/Stop page:

    1. Enter the VA server password, which is also the OCS or Softcard passphrase.

    2. Select Start Server .

  37. The server status changes from OFF to ON . The VA responder server is now operational.

  38. Confirm the Responder is importing CRLs from the configured CRL URL address by accessing the server log to view publisher-specific events. You can view CRLs published on the Responder by navigating to CRLs > CRLs & OCSP Databases .

Perform basic integration tests

The following sections will test the Axway VA nshield HSM integration.

Verify OCSP response signing key

To verify the OCSP signing key was generated on the HSM, run the following commands. Replace <pkcs11-key-hash> with the hash at the end of the key_pkcs11_<pkcs11-key-hash> file that is generated in the local directory. For example: 

% nfkminfo -l
Keys protected by cardsets:
  key_pkcs11_<pkcs11-key-hash> `OCSKeyOCSPCert RSAPrv'

% nfkmverify -v -m<module-number> pkcs11 <pkcs11-key-hash>
** [Security world] **
Ciphersuite: DLf3072s256mAEScSP800131Ar1
...
    ---

** [Application key pkcs11 <pkcs11-key-hash>] **
[Named `OCSKeyOCSPCert RSAPrv']
Useable by HOST applications
Cardset protected: 1/2 PERSISTENT [0s `axwayva_ocs']
Cardset hash f581378f4a81d3ba312fcd19859247049bf18161
(Currently in Module #1 Slot #2: Card #2)
...
    Verification successful, confirm details above.  1 key verified.

Verify OCSP signing certificate

To verify the OCSP signing certificate that is presented to clients, use either the vatest tool provided by Axway or the curl and openssl tools if they are on your system.

  • To use Axway’s vatest tool:

    • For Windows: 

      % C:\Program Files\axway\va\tools\vatest getconfig -url http://127.0.0.1:80

    • For Linux: 

      % /opt/axway/va/tools/vatest getconfig -url http://127.0.0.1:80
OCSP Host: <Server-hostname-or-IP>
OCSP Port: 80
OCSP Certificates: ocspcerts.pem

  • To use curl and openssl : 

    % curl "http://127.0.0.1:80/getvaconfig?mirroring" | openssl x509 -out ocspcerts.pem

Running either command generates a certificate file ocspcerts.pem in the directory from which the command was run.

Open the ocspcerts.pem file to see the OCSP signing certificate in Base64 format.

Test OCSP server functionality

To test the VA server’s OCSP response capability to requests on the status of various certificates:

  1. Open a command prompt.

  2. Use the openssl OCSP client to make a request to the VA server for the status of a certificate. For example: 

    % openssl ocsp -text -host 127.0.0.1:80 -issuer "<full-path-to-root-CA-cert>" -VAfile "C:\ProgramData\Axway\VA\entserv\.vacsbak\OCSP_RESP_SIGN_*_GMT.crt" -serial <cert-serial-number>

    In this example:

    • Replace <full-path-to-root-CA-cert> with the path to the root CA certificate.

    • Replace <cert-serial-number> with the serial number of the certificate whose status you want to check.

An example response for a valid certificate that is not on the CRL: 

OCSP Response Data:
OCSP Response Status: successful (0x0)
Response Type: Basic OCSP Response
Version: 1 (0x0)
...
Responses:
...
Serial Number: 099F
Cert Status: good
This Update: Jul 20 15:07:56 2021 GMT
Next Update: Aug  4 02:26:08 2021 GMT
...
Response verify OK
0x099F: good
This Update: Jul 20 15:07:56 2021 GMT
Next Update: Aug  4 02:26:08 2021 GMT

An example response for a revoked certificate that is on the CRL: 

OCSP Response Data:
OCSP Response Status: successful (0x0)
Response Type: Basic OCSP Response
Version: 1 (0x0)
...
Responses:
...
Serial Number: 026F
Cert Status: revoked
Revocation Time: Jun 15 14:38:52 2017 GMT
This Update: Jul 20 15:07:56 2021 GMT
Next Update: Aug  4 02:16:22 2021 GMT
...
Response verify OK
    0x026F: revoked
    This Update: Jul 20 15:07:56 2021 GMT
    Next Update: Aug  4 02:16:22 2021 GMT
    Revocation Time: Jun 15 14:38:52 2017 GMT
RESOURCES
RELATED PRODUCTS