Install and configure the WSOP server

This section describes the steps needed to setup a WSOP server.

Create the WSOP server

This guide used Virtual Machine running in VMware vSphere. The VM had the following spec:

  • 4 CPUs

  • 16 GB RAM

  • 100 GB Disk Space

  • Red Hat 8 installed.

Once the VM is up and running, login as root to the server.

Open up port 18001 on the firewall. This port is used so clients can talk to the WSOP server.

% sudo firewall-cmd --permanent --add-port=18001/tcp
% sudo firewall-cmd --reload

Install Security World Software

  1. Install the Entrust Security World software in accordance with its accompanying documentation.

  2. Create or edit the cknfastrc file located in the NFAST_HOME directory, and set the following PKCS#11 environment variables:

    • Including soft card key protection, and HSM load sharing:

      CKNFAST_LOADSHARING=1

      For more information, study the PKCS#11 library environment variables in the User Guide for your HSM.

  3. Create or load the Security World, or nShield Connect (if being used).

    If you are using RA for the ACS cards, you must do so through a registered client. Ensure the Security World data is copied to the NFAST_KMDATA/local folder, and is loaded onto each nShield Connect used in the configuration.

  4. Check the Security World on your various components as follows:

    The Security World must be shown as Initialized and Usable.

    1. Use the Entrust nfkminfo utility to check the Security World and configuration. In each case, the Security World must be shown as Initialized and Usable.

    2. nShield Connect: Front panel: MENU > Security World mgmt. > Display World Info.

      For further details, see the User Guide for your HSM.

  5. Prepare protection method.

    If your Security World does not already contain the required protection method, then proceed as follows:

    1. The integration requires the use of Softcard protection.

      This will be created in the Oracle database server, when the WSOP client software is installed and configured.

    2. If you are using a FIPS 140 Level 3 world environment, then you also need an OCS card set (1/N) to provide FIPS authorization. If a suitable OCS card set is not already available in the Security World, then create an OCS card set for this purpose.

Install MongoDB

The WSOP server uses MongoDB as its database. The instructions below are for a RedHat Linux 8 server.

  1. Create an /etc/yum.repos.d/mongodb-enterprise-7.0.repo file.

    The file should contain the following content to install MongoDB enterprise directly using yum.

    [mongodb-enterprise-7.0]
    name=MongoDB Enterprise Repository
    baseurl=https://repo.mongodb.com/yum/redhat/$releasever/mongodb-enterprise/7.0/$basearch/
    gpgcheck=1
    enabled=1
    gpgkey=https://www.mongodb.org/static/pgp/server-7.0.asc
  2. Install the MongoDB Enterprise packages

    % sudo yum install -y mongodb-enterprise

Install the Entrust nShield WSOP Software

  1. Download the Entrust nShield WSOP tar file and transfer to the server.

  2. Place the file in a folder

  3. In a terminal, create a temporary directory to unpack the WSOP tar file.

    % sudo mkdir ~/wsop_install
  4. Extract the WSOP tar to the temporary directory created above.

    % cd ~/wsop_install
    % sudo tar -xzf ~ /Downloads/wsop-p11-3.3.0-697-4bfd3ef.tar.gz
  5. Change to the root directory. Then extract the following files from the unpacked WSOP tar.

    % cd /
    % sudo tar zxvf ~/wsop_install/corecrypto.tar.gz
    % sudo tar zxvf ~/wsop_install/wsop-common.tar.gz
    % sudo tar zxvf ~/wsop_install/dbmt.tar.gz
  6. Install the Entrust nShield WSOP management tool.

    Execute the following to install the WSOP management tool:

    % cd /opt/nfast/webservices/dbmt-2.2.0/
    % sudo ./install.sh

Import or Create certificates.

Certificates are used to authenticate clients with Entrust nShield WSOP. In addition, Entrust nShield WSOP uses certificates to authenticate with the MongoDB database. Customer of Entrust nShield work out their own security requirements. For the purpose of this integration a Tiny certificate authority will be created.

The following certificates and keys are needed:

  • CA Key.

  • Root CA.

  • Certificate for the MongoDB database server.

  • Certificate for the Entrust nShield WSOP server.

  • Certificate for Entrust nShield WSOP client.

Become a Tiny certificate authority.

  1. Create the certificate directory.

    % sudo mkdir -p /opt/nfast/webservices/corecrypto/tls/db
    % cd /opt/nfast/webservices/corecrypto/tls/db
  2. Generate the private key.

    % sudo openssl genrsa -aes256 -out myCA.key 2048
    
    Generating RSA private key, 2048 bit long modulus (2 primes)
    ........+++++
    ..............+++++
    e is 65537 (0x010001)
    Enter pass phrase for myCA.key:
    Verifying - Enter pass phrase for myCA.key:
  3. Generate the root certificate.

    % sudo openssl req -x509 -new -nodes -key myCA.key -sha256 -days 1825 -out myCA.pem
    
    Enter pass phrase for myCA.key:
    You are about to be asked to enter information that will be incorporated
    into your certificate request.
    What you are about to enter is what is called a Distinguished Name or a DN.
    There are quite a few fields but you can leave some blank
    For some fields there will be a default value,
    If you enter '.', the field will be left blank.
    -----
    Country Name (2 letter code) [XX]:US
    State or Province Name (full name) []:FL
    Locality Name (eg, city) [Default City]:Sunrise
    Organization Name (eg, company) [Default Company Ltd]:Entrust
    Organizational Unit Name (eg, section) []:nShield
    Common Name (eg, your name or your server's hostname) []:myca
    Email Address []:test@myca.com

    Now you should have two files:

    • The CA Key: myCA.key

    • The CA root certificate: myCA.pem

Create the certificate for the MongoDB database server.

  1. Go to the certificate directory

    % cd /opt/nfast/webservices/corecrypto/tls/db
  2. Create an extension file for signing the certs.

    Create /opt/nfast/webservices/corecrypto/tls/db/sign_db_server.ext.

    IP is the IP address of the server running the MongoDB database server.

    basicConstraints=CA:FALSE
    keyUsage = digitalSignature
    subjectAltName = @alt_names
    
    [alt_names]
    IP = xxx.xxx.xxx.xxx
    DNS.1 = localhost
    DNS.2 = wsopserver-redhat-8
  3. Create a key for the MongoDB database.

    % sudo openssl genrsa -out db_server.key 2048
    
    Generating RSA private key, 2048 bit long modulus (2 primes)
    ................+++++
    ....+++++
    e is 65537 (0x010001)
  4. Create a certificate request for the MongoDB database.

    % sudo openssl req -new -key db_server.key -out db_server.csr
    
    You are about to be asked to enter information that will be incorporated
    into your certificate request.
    What you are about to enter is what is called a Distinguished Name or a DN.
    There are quite a few fields but you can leave some blank
    For some fields there will be a default value,
    If you enter '.', the field will be left blank.
    -----
    Country Name (2 letter code) [XX]:US
    State or Province Name (full name) []:FL
    Locality Name (eg, city) [Default City]:Sunrise
    Organization Name (eg, company) [Default Company Ltd]:Entrust
    Organizational Unit Name (eg, section) []:nShield
    Common Name (eg, your name or your server's hostname) []:wsopserver-redhat-8
    Email Address []:test@entrust.com
    
    Please enter the following 'extra' attributes
    to be sent with your certificate request
    A challenge password []:ncipher
    An optional company name []:Entrust
  5. Sign the certificate request for the MongoDB database server.

    % sudo openssl x509 -req -in db_server.csr -CA myCA.pem -CAkey myCA.key -CAcreateserial -out db_server.crt -days 825 -sha256 -extfile sign_db_server.ext
    
    Signature ok
    subject=C = US, ST = FL, L = Sunrise, O = Entrust, OU = nShield, CN = wsopserver-redhat-8, emailAddress = test@entrust.com
    Getting CA Private Key
    Enter pass phrase for myCA.key:
  6. Create a pem file containing the key and certificate for the MongoDB database server.

    % sudo cat db_server.key > /tmp/db_server.pem
    % sudo cat db_server.crt >> /tmp/db_server.pem
    % mv /tmp/db_server.pem .
  7. Copy the database root certificate and .pem file to a location accessible by the MongoDB database.

    % sudo mkdir /etc/ssl/mongodb/
    % sudo cp myCA.pem db_server.pem /etc/ssl/mongodb/
    % sudo chown -R mongod:mongod /etc/ssl/mongodb

Create the certificate for the Entrust nShield WSOP server.

The Entrust nShield WSOP server is a client of the MongoDB database.

  1. Go to the certificate directory.

    % cd /opt/nfast/webservices/corecrypto/tls/db
  2. Create an extension file for signing the certs.

    Create /opt/nfast/webservices/corecrypto/tls/db/sign_wsop_server.ext.

    IP is the IP address of the server running the Entrust nShield WSOP server.

    basicConstraints=CA:FALSE
    keyUsage = digitalSignature
    extendedKeyUsage = clientAuth, serverAuth
    subjectAltName = @alt_names
    
    [alt_names]
    IP = xxx.xxx.xxx.xxx
    DNS.1 = localhost
    DNS.2 = wsopserver-redhat-8
  3. Create a key for Entrust nShield WSOP server.

    % sudo openssl genrsa -out wsop_server.key 2048
    
    Generating RSA private key, 2048 bit long modulus (2 primes)
    ....................+++++
    .....+++++
    e is 65537 (0x010001)
  4. Create a certificate request for the Entrust nShield WSOP server.

    % sudo openssl req -new -key wsop_server.key -out wsop_server.csr
    
    You are about to be asked to enter information that will be incorporated
    into your certificate request.
    What you are about to enter is what is called a Distinguished Name or a DN.
    There are quite a few fields but you can leave some blank
    For some fields there will be a default value,
    If you enter '.', the field will be left blank.
    -----
    Country Name (2 letter code) [XX]:US
    State or Province Name (full name) []:FL
    Locality Name (eg, city) [Default City]:Sunrise
    Organization Name (eg, company) [Default Company Ltd]:Entrust
    Organizational Unit Name (eg, section) []:nShield
    Common Name (eg, your name or your server's hostname) []:wsopserver-redhat-8
    Email Address []:test@entrust.com
    
    Please enter the following 'extra' attributes
    to be sent with your certificate request
    A challenge password []:ncipher
    An optional company name []:Entrust
  5. Sign the certificate request for the Entrust nShield WSOP server.

    % sudo openssl x509 -req -in wsop_server.csr -CA myCA.pem -CAkey myCA.key -CAcreateserial -out wsop_server.crt -days 825 -sha256 -extfile sign_wsop_server.ext
    
    Signature ok
    subject=C = US, ST = FL, L = Sunrise, O = Entrust, OU = nShield, CN = wsopserver-redhat-7\088, emailAddress = test@entrust.com
    Getting CA Private Key
    Enter pass phrase for myCA.key:
  6. Create a pem file containing the key and certificate for the Entrust nShield WSOP server.

    % sudo cat wsop_server.key > /tmp/wsop_server.pem
    % sudo cat wsop_server.crt >> /tmp/wsop_server.pem
    % sudo mv /tmp/wsop_server.pem .

Create the certificate for Entrust nShield WSOP client

  1. Create the client certificate directory.

    % sudo mkdir -p /opt/nfast/webservices/corecrypto/tls/external
  2. Change directory to the certificate directory.

    % cd /opt/nfast/webservices/corecrypto/tls/external
  3. Create an extension file /opt/nfast/webservices/corecrypto/tls/external/sign_wsop_client.ext for signing the certs.

    IP is the IP address of the server running the Entrust nShield WSOP server.

    basicConstraints = CA:FALSE
    keyUsage = digitalSignature
    extendedKeyUsage = clientAuth
    subjectAltName = @alt_names
    
    [alt_names]
    IP.1 = xxx.xxx.xxx.xxx
    DNS.1 = localhost
    DNS.2 = wsopserver-redhat-8
  4. Create a key for the client of Entrust nShield WSOP server.

    % sudo openssl genrsa -out wsop_client.key 2048
    
    Generating RSA private key, 2048 bit long modulus (2 primes)
    ...............................................+++++
    ..................................................................................................+++++
    e is 65537 (0x010001)
  5. Create a certificate request for the Entrust nShield WSOP client.

    Set the hostname to the name of the client machine connecting to the Entrust nShield WSOP server.

    % sudo openssl req -new -key wsop_client.key -out wsop_client.csr
    
    You are about to be asked to enter information that will be incorporated
    into your certificate request.
    What you are about to enter is what is called a Distinguished Name or a DN.
    There are quite a few fields but you can leave some blank
    For some fields there will be a default value,
    If you enter '.', the field will be left blank.
    -----
    Country Name (2 letter code) [XX]:US
    State or Province Name (full name) []:FL
    Locality Name (eg, city) [Default City]:Sunrise
    Organization Name (eg, company) [Default Company Ltd]:Oracle
    Organizational Unit Name (eg, section) []:TDE
    Common Name (eg, your name or your server's hostname) []:otde-wsop-redhat-9
    Email Address []:test@oracle.com
    
    Please enter the following 'extra' attributes
    to be sent with your certificate request
    A challenge password []:ncipher
    An optional company name []:Oracle
  6. Sign the certificate request for the Entrust nShield WSOP client.

    % sudo openssl x509 -req -in wsop_client.csr -CA /opt/nfast/webservices/corecrypto/tls/db/myCA.pem \
           -CAkey /opt/nfast/webservices/corecrypto/tls/db/myCA.key \
           -CAcreateserial -sha256 -days 1826 -out wsop_client.crt \
           -extfile sign_wsop_client.ext
    
    Signature ok
    subject=C = US, ST = FL, L = Sunrise, O = Oracle, OU = TDE, CN = otde-wsop-redhat-8\089, emailAddress = test@oracle.com
    Getting CA Private Key
    Enter pass phrase for /opt/nfast/webservices/corecrypto/tls/db/myCA.key:
  7. Create a pem file containing the key and certificate for the Entrust nShield WSOP client.

    % sudo cat wsop_client.key > /tmp/wsop_client.pem
    % sudo cat wsop_client.crt >> /tmp/wsop_client.pem
    % sudo mv /tmp/wsop_client.pem .

Configure MongoDB

Now let’s configure MongoDB so it can be used by WSOP.

  1. Save the default /etc/mongod.conf by creating a copy.

    % sudo cp /etc/mongod.conf /etc/mongod.conf.example
  2. Edit /etc/mongod.conf with the applicable parameters.

    The resulting /etc/mongod.conf is:

    # mongod.conf
    
    # for documentation of all options, see:
    #   http://docs.mongodb.org/manual/reference/configuration-options/
    
    # where to write logging data.
    systemLog:
      destination: file
      logAppend: true
      path: /var/log/mongodb/mongod.log
    
    # Where and how to store data.
    storage:
      dbPath: /var/lib/mongo
    
    # how the process runs
    processManagement:
      fork: true  # fork and run in background
      pidFilePath: /var/run/mongodb/mongod.pid  # location of pidfile
      timeZoneInfo: /usr/share/zoneinfo
    
    # network interfaces
    net:
      port: 27017
      bindIp: 0.0.0.0  # Enter 0.0.0.0,:: to bind to all IPv4 and IPv6 addresses or, alternatively, use the net.bindIpAll setting.
      tls:
        mode: requireTLS
        certificateKeyFile: /etc/ssl/mongodb/db_server.pem
        CAFile: /etc/ssl/mongodb/myCA.pem
    
    security:
      clusterAuthMode: x509
    
    #operationProfiling:
    
    replication:
      replSetName: rs1
    
    #sharding:
    
    # Enterprise-Only Options
    
    #auditLog:
  3. Open a separate terminal window and initiate the replication set.

    Open a new terminal window in the WSOP server and do the following:

    1. Kill the mongod process:

      % sudo pkill mongod
    2. Start MongoDB in the following manner:

      % sudo mongod --replSet rs1 --dbpath /var/lib/mongo --bind_ip 0.0.0.0
  4. Back in the previous window, launch the MongoDB shell.

    % mongosh
    
    Current Mongosh Log ID: 664cf54837141997c3a26a12
    Connecting to:          mongodb://127.0.0.1:27017/?directConnection=true&serverSelectionTimeoutMS=2000&appName=mongosh+2.2.6
    Using MongoDB:          7.0.9
    Using Mongosh:          2.2.6
    
    For mongosh info see: https://docs.mongodb.com/mongodb-shell/
    
    
    To help improve our products, anonymous usage data is collected and sent to MongoDB periodically (https://www.mongodb.com/legal/privacy-policy).
    You can opt-out by running the disableTelemetry() command.
    
    ------
       The server generated these startup warnings when booting
       2024-05-21T15:25:01.616-04:00: Access control is not enabled for the database. Read and write access to data and configuration is unrestricted
       2024-05-21T15:25:01.616-04:00: You are running this process as the root user, which is not recommended
       2024-05-21T15:25:01.617-04:00: /sys/kernel/mm/transparent_hugepage/enabled is 'always'. We suggest setting it to 'never' in this binary version
       2024-05-21T15:25:01.617-04:00: Soft rlimits for open file descriptors too low
    
    Enterprise test>
  5. Run rs.initiate().

    Enterprise test> rs.initiate()
    
    {
      info2: 'no configuration specified. Using a default configuration for the set',
      me: 'wsopserver-redhat-8:27017',
      ok: 1
    }
    Enterprise rs1 [direct: other] test>
  6. Switch to admin.

    Enterprise rs1 [direct: other] test> use admin
    
    switched to db admin
  7. Copy-paste the following to create users as needed and exit.

    db.createUser(
        {
    	user: "mAdmin",
    	pwd: "admin",
    	roles: [ { role: "userAdminAnyDatabase", db: "admin" },
    	         { role: "dbAdminAnyDatabase", db: "admin" },
    		 { role: "readWriteAnyDatabase", db: "admin" } ]
        }
    )

    The output is as following:

    db.createUser(
    ...     {
    ...         user: "mAdmin",
    ...         pwd: "admin",
    ...         roles: [ { role: "userAdminAnyDatabase", db: "admin" },
    ...                  { role: "dbAdminAnyDatabase", db: "admin" },
    ...                  { role: "readWriteAnyDatabase", db: "admin" } ]
    ...     }
    ... )
    {
      ok: 1,
      '$clusterTime': {
        clusterTime: Timestamp({ t: 1716319876, i: 4 }),
        signature: {
          hash: Binary.createFromBase64('AAAAAAAAAAAAAAAAAAAAAAAAAAA=', 0),
          keyId: Long('0')
        }
      },
      operationTime: Timestamp({ t: 1716319876, i: 4 })
    }
    Enterprise rs1 [direct: primary] admin> exit
  8. Kill the mongod process.

    1. Check for the mongod processes that are running.

      % ps -aux | grep mongod
      
      root      260503  0.0  0.2 138432  8300 pts/2    S+   15:25   0:00 sudo mongod --replSet rs1 --dbpath /var/lib/mongo --bind_ip 0.0.0.0
      root      260505  1.2  5.3 3067544 202004 pts/2  SLl+ 15:25   0:06 mongod --replSet rs1 --dbpath /var/lib/mongo --bind_ip 0.0.0.0
      root      262202  0.0  0.0  12144  1192 pts/1    S+   15:33   0:00 grep --color=auto mongod
    2. Now kill mongod

      % sudo pkill mongod
  9. Afterwards, close the separate terminal window opened above.

  10. Change ownership of the following folder and files as follows.

    % sudo chown -R mongod:mongod /var/lib/mongo
    % sudo chown -R mongod:mongod /var/lib/mongo/WiredTiger.turtle
    % sudo chown -R mongod:mongod /var/lib/mongo/journal/
  11. Create a /data/db/ directory.

    % sudo mkdir -p /data/db/
    % sudo chown -R mongod:mongod /data/db/
  12. Start the mongod process.

    % sudo service mongod start
  13. Enable mongod so it starts after a reboot.

    % sudo systemctl enable mongod
  14. Check the status of the mongod service.

    % sudo service mongod status
    
    Redirecting to /bin/systemctl status mongod.service
    ● mongod.service - MongoDB Database Server
       Loaded: loaded (/usr/lib/systemd/system/mongod.service; enabled; vendor preset: disabled)
       Active: active (running) since Tue 2024-05-21 15:39:03 EDT; 36s ago
         Docs: https://docs.mongodb.org/manual
     Main PID: 263321 (mongod)
       Memory: 191.6M
       CGroup: /system.slice/mongod.service
               └─263321 /usr/bin/mongod -f /etc/mongod.conf
    
    May 21 15:39:03 wsopserver-redhat-8 systemd[1]: Started MongoDB Database Server.
    May 21 15:39:03 wsopserver-redhat-8 mongod[263321]: {"t":{"$date":"2024-05-21T19:39:03.390Z"},"s":"I",  "c":"CONTROL",  "id":7484500, "ctx":"main","msg":"Environment variable MONGOD…k\" to false"}
    Hint: Some lines were ellipsized, use -l to show in full.

Configure the Entrust nShield WSOP server

  1. Create the configuration file.

    Copy the example file into /opt/nfast/webservices/corecrypto/conf/config.yaml.

    % sudo cp /opt/nfast/webservices/corecrypto/conf/config.yaml.example /opt/nfast/webservices/corecrypto/conf/config.yaml
  2. Run the following command to display the hknso of the HSM installed. Copy it to the clipboard.

    % nfkminfo | grep hknso
    
    hknso 0adead5baac6c31d69dd964e00309829601fcd05
  3. Edit /opt/nfast/webservices/corecrypto/conf/config.yaml.

    Change the applicable parameters. These include the hknso above. The parameter allow_unauthenticated_clients was set to true for the purpose of the integration.

    The resulting /opt/nfast/webservices/corecrypto/conf/config.yaml is:

    # Server Authentication TLS (corecrypto server) Options
    external_tls:
        # Host for corecrypto to listen on
        host: 0.0.0.0
    
        # Port for corecrypto to listen on
        port: 18001
    
        # TLS Certificate
        cert_file: /opt/nfast/webservices/corecrypto/tls/db/wsop_server.pem
    
        # Appname:Ident of the key used to protect the TLS private key
        # key_appname_ident: appname:ident
    
        # Exclude TLS private key from queries
        # exclude_tls_key: true
    
        # TLS private key file - note only required if not using HSM protection
        key_file: /opt/nfast/webservices/corecrypto/tls/db/wsop_server.key
    
        # TLS CA Certificate for Mutual Authentication
        ca_certificate_file: /opt/nfast/webservices/corecrypto/tls/db/myCA.pem
    
        # Enable TLS Client Authentication
        # Warning: we suggest not disabling client_auth_enabled as this will allow unauthenticated client requests
        client_auth_enabled: true
    
        # API Gateway
        # This flag is set to true when webservices are expected to work behind an API Gateway
        api_gateway: false
    
        # Headers
        # This option is only used when webservices work behind an API Gateway
        # By default webservices will look into Authorization headers passed by the gateway to identify its clients by
        # issuer and subject.
        # If Authorization headers are not provided, then webservices will identify a clients' issuer and subject values
        # from the request headers defined in issuer_header and subject_header config fields
        # headers:
        #     issuer_header:
        #     subject_header:
    
        # Directory where to look for the CRL files, these need to have extension .crl or.pem to be loaded
        crl_directory: /opt/nfast/webservices/corecrypto/tls/external/crls
    
        # Interval at which to poll the CRL directory for changes to CRL files
        crl_poll_interval: 1m
    
        # Preferred Cipher Suites for external clients.
        # The full list of supported cipher suites can be found in the nShield Web Services Option Pack User Guide
        # The default provided in this file is a list of recommended cipher suites.
        cipher_suites:
            - ECDHE-ECDSA-AES128-GCM-SHA256
            - ECDHE-RSA-AES128-GCM-SHA256
            - ECDHE-ECDSA-AES256-GCM-SHA384
            - ECDHE-RSA-AES256-GCM-SHA384
            - ECDHE-ECDSA-CHACHA20-POLY1305
            - ECDHE-RSA-CHACHA20-POLY1305
    
    logging:
        # The loglevel
        # Valid values: Trace, Debug, Info, Warning, Error
        loglevel: Warning
    
        # Logging to console (stdout or stderr)
        console:
            # The console level output
            # Valid values: stderr, stdout, discard or empty
            output: discard
    
        # Logging to a file
        file:
            # Enable logging to a file
            enabled: true
    
            # The absolute path of the file that logs should be written to
            filepath: /opt/nfast/log/corecrypto.log
    
        # Logging to syslog
        syslog:
            # Enable logging to a configured syslog server
            enabled: false
    
            # The networking protocol to be used to send logs to syslog
            # Optional - if syslog is enabled but network is not configured, the local syslog daemon will be used
            # Valid values: udp
            network: udp
    
            # The IP/Hostname of the machine hosting syslog and the port to access syslog on in the format hostname:port
            # Optional - if syslog is enabled but host is not configured, the local syslog daemon will be used.
            # Valid values: localhost, and IPv4 addresses in the format x.x.x.x where x is a value between 0 and 255
            host: localhost:514
    
    # Health Check Options
    health:
        # Interval in seconds between estate health check
        # Estate means the modules which belong of the security world
        estate_check_interval: 5s
    
        # Period in seconds after which the estate health check will timeout
        estate_check_timeout: 4s
    
        # Interval in seconds between each security world check
        # Its value is a multiple of the estate_check_interval value
        # Note: each time a security world check takes place, an estate
        # health check also takes place
        sworld_check_interval: 300s
    
        # Interval in seconds between each database health check
        database_check_interval: 5s
    
        # Period in seconds after which a database health check will timeout
        database_check_timeout: 30s
    
        # Allow unauthenticated clients to probe the health check endpoint.
        # Only applicable when tls.client_auth_enabled is true
        allow_unauthenticated_clients: true
    
        # Extend health check status to include whether the service can acquire FIPS-authentication
        include_fips_ready_check: false
    
    # World
    world:
        # Hash of the security world Officer
        # It needs to match the world in the database and needs to be set before starting corecrypto.
        hknso: 0adead5baac6c31d69dd964e00309829601fcd05
    
    # Concurrent Request Limiter Options
    # Too many concurrent requests can lead to a denial of service
    concurrent_request_limiter:
        # Maximum number of concurrent requests that the server supports
        outstanding_requests_limit: 500
        # Maximum number of concurrent requests for generating or importing RSA keys
        rsa_key_requests_limit: 10
        # Maximum number of concurrent requests for generating or importing ECDSA keys
        ecdsa_key_requests_limit: 30
    
    # Caching Options
    cache:
        # Period of inactivity in minutes after which a key manager will be closed
        # Only applicable when tls.client_auth_enabled is true
        # Setting of 0 is used to disable closing an inactive key manager.
        key_manager_inactivity: 1440m
    
        # Capacity of the key cache. When the number of keys in the cache reaches this
        # capacity, then the keys are evicted based on a least recently used (LRU) policy.
        # Minimum value 100
        key_cache_capacity: 30000
    
        # Period of time for which a key stays in the cache before it is evicted
        # Minimum value 1m
        key_TTL_period: 60m
    
        # Capacity of the group cache: when the number of groups in the cache reaches the
        # capacity, then the groups are evicted based on least recently used (LRU) policy
        # Minimum value 100
        group_cache_capacity: 20000
    
        # Time to live value for a group in the cache
        # Minimum value 1m
        group_TTL_period: 120m
    
        # Maximum number of protection domains which are stored in the corecrypto cache
        # Minimum value 100
        max_number_of_active_protection_domains: 10000
    
        # Time to live value for protection domains in the cache
        # Minimum value 1m
        domain_TTL_period: 720m
    
    # Database Options
    database:
        # List of database hosts
        hosts:
            - localhost:27017
    
        # The loglevel of the database driver component
        # Valid values: Trace, Debug, Info, Warning, Error
        loglevel: Info
    
        # Time before a database request should fail
        timeout: 5s
    
        # Maximum returned keys when listing, large queries can hurt the service.
        # This limit affects the list keys endpoint.
        # If you wish to retrieve more than the maximum limit then you may make multiple API
        # requests and combine the results within your application using the offset and limit.
        # listkeys_max_limit: 300000
    
        # Name of the database
        db_name: nshield-corecrypto
    
        # Webservices Corecrypto Segregation (WCS) Options
        # The segregation database must be defined in order
        # to enable WCS. When enabled, corecrypto objects
        # will be segregated based on the mappings defined in the collection.
        # If the segregation database is not defined,
        # WCS is disabled.
        #
        # segregations_db_name: segregation_db
        # segregations_collection_name: segregations
    
        # Authentication method with database. Valid values: [none, pwd, tls]
        # none - no authentication
        # pwd  - username and password authentication using mongodb SCRAM
        # tls  - x509 authentication
        auth_type: tls
    
        # If 'auth_type' is pwd, 'auth_username_file' and 'auth_password_file'
        # options define the location of a secure file containing the username
        # and passphrase to use for authentication.
        # 'auth_source' is a database-type specific identifier for what to authenticate
        # against. For mongodb this is the name of the authentication database.
        #
        # auth_username_file: /opt/nfast/webservices/corecrypto/pwd-auth/config-username-auth
        # auth_password_file: /opt/nfast/webservices/corecrypto/pwd-auth/config-password-auth
        # auth_source: userdb
    
        # Transport Layer Security. Default is false.
        disable_tls: false
    
        # Path to the mongoDB TLS certificate
        db_ca_file: /opt/nfast/webservices/corecrypto/tls/db/myCA.pem
    
        # Path to the corecrypto client certificate (used when Mutual Authentication is enabled)
        db_cert_file: /opt/nfast/webservices/corecrypto/tls/db/wsop_server.pem
    
        # Path to the corecrypto client private key (used when Mutual Authentication is enabled)
        db_key_file: /opt/nfast/webservices/corecrypto/tls/db/wsop_server.key
    
        # Type of database. Supported values: mongodb
        db: mongodb
    
        # Disable this option when WSOP is running with keySafe5 instance.
        is_WSOP_standalone: true
    
        mongodb:
            # Name of the Replication Set
            replica_set: rs1
    
            # Timeout for connection to the database server
            connect_timeout: 5s
            # Timeout for selecting a connection from the pool
            selection_timeout: 5s
            # Timeout waiting for read/write in the socket
            socket_timeout: 5s
    
            # Minimum and maximum connections to use in mongodb's connection pool
            min_pool_size: 1
            max_pool_size: 100
    
    #group options
    group:
        # Allow all group deletions.
        # Disable this option to prevent the deletion of the reserved groups belonging
        # to either the Module Protection or Well-Known Key Protection domains.
        # A reserved group is defined as any public segregated group which has the same name as
        # the protection domain it belongs to.
        allow_all_group_deletions: true
  4. Configure the Entrust nShield WSOP management tool.

    1. Create the configuration file.

      Copy the example file into /opt/nfast/webservices/dbmt-2.2.0/config.yaml.

      % sudo cp /opt/nfast/webservices/dbmt-2.2.0/config_example.yaml /opt/nfast/webservices/dbmt-2.2.0/config.yaml
    2. Edit /opt/nfast/webservices/dbmt-2.2.0/config.yaml.

      Use the applicable parameters.

      The resulting /opt/nfast/webservices/dbmt-2.2.0/config.yaml is:

      # Database hostname (ip address)
      db_host : localhost
      # Database port number
      db_port : 27017
      
      # Name of the database
      db_name: nshield-corecrypto
      
      # Database Management System. Valid values: [mongodb]
      db: mongodb
      
      mongodb:
        # Transport Layer Security. Default is enabled
        # disable_tls: false
      
        #
        # Authentication method with database. Valid values: [none, pwd, tls]
        auth_type: tls
      
        #
        # If 'auth_type' is pwd, 'auth_pwd_file' defines the location of a secure file
        # containing the username and passphrase to use for authentication.
        # 'auth_source' is a database-type specific identifier for what to authenticate
        # against. For mongodb this is the name of the authentication database.
        #
        # auth_username_file: config-username-auth
        # auth_password_file: config-password-auth
        # auth_source: userdb
      
        #
        # Certificate Authority files to use for TLS
        db_ca_file: /opt/nfast/webservices/corecrypto/tls/db/myCA.pem
        db_cert_file: /opt/nfast/webservices/corecrypto/tls/db/wsop_server.pem
        db_key_file: /opt/nfast/webservices/corecrypto/tls/db/wsop_server.key
      
        #
        # Webservices Corecrypto Segregation (WCS) Options
        # The segregation database and collection must be defined in order
        # to enable WCS. When enabled, corecrypto objects
        # will be segregated based on the mappings defined in the collection.
        # If the segregation database and collection are not defined,
        # WCS is disabled.
        #
        # segregations_db_name: segregation_db
        # segregations_collection_name: segregations

Start the Entrust nShield WSOP service

  1. Initialize the database.

    % sudo /opt/nfast/python3/bin/dbmt db-init --config /opt/nfast/webservices/dbmt-2.2.0/config.yaml
    
    Starting initialisation of the database...
    Establishing connection to hardserver
    TLS enabled
    X509 Authentication enabled
    Establishing mongo connection to: localhost:27017
    Creating database with name: nshield-corecrypto
    Setting indices on collections: nshield-corecrypto
    Adding to database: Security World: Security World identifier: 57f6ab61-5547-4ed3-a249-4a9c1710c167
    Migrating the module certificates
    Migrating "module_BD10-03E0-D947" module file
    Adding to database: module certificates: esn: BD10-03E0-D947, hkml: 1dd6a3890c4ec65010466ee3ba5eaef3d6a61777
    Migrating cardsets
    Migrating cards
    getting protection domain by uuid
    Adding to database: domain: name: Module Protection type: Module id: 5ee26b95-7e90-53c3-ae75-2e5ddea011bc
    Adding to database: group_id: 5ee26b95-7e90-53c3-ae75-2e5ddea011bc name: Module Protection domain_id: 5ee26b95-7e90-53c3-ae75-2e5ddea011bc domain_type Module
    getting protection domain by uuid
    Adding to database: domain: name: Well-Known Key Protection type: WellKnown id: 2bd40730-85b1-5deb-8417-fb78a7735743
    Adding to database: group_id: 2bd40730-85b1-5deb-8417-fb78a7735743 name: Well-Known Key Protection domain_id: 2bd40730-85b1-5deb-8417-fb78a7735743 domain_type WellKnown
    Initialisation of the database completed.
    Finished
    This command can also be used to load new content from /opt/nfast/kmdata/local into the database.
  2. Install the corecrypto service.

    % sudo /opt/nfast/webservices/sbin/install
    
    -- Running install fragment corecrypto
    Creating wsopd group.
    Checking for user 'wsopd'
    Creating wsopd user.
    useradd: warning: the home directory already exists.
    Not copying any file from skel directory into it.
    Checking user 'wsopd' is in correct group 'wsopd'
    users created correctly
    Installing startup scripts for 'corecrypto'.
    Enabling the systemd service unit
    Adding and enabling a systemd unit
    Created symlink /etc/systemd/system/multi-user.target.wants/nc_corecrypto.service → /etc/systemd/system/nc_corecrypto.service.
    Note: Forwarding request to 'systemctl enable nc_corecrypto.service'.
    Starting nCipher 'corecrypto' server process.
    Job for nc_corecrypto.service failed because the control process exited with error code.
    See "systemctl status nc_corecrypto.service" and "journalctl -xe" for details.
    ● nc_corecrypto.service - nFast corecrypto
       Loaded: loaded (/etc/systemd/system/nc_corecrypto.service; enabled; vendor preset: disabled)
       Active: failed (Result: exit-code) since Tue 2024-05-21 16:02:03 EDT; 30ms ago
         Docs: https://nshielddocs.entrust.com/
      Process: 295512 ExecStopPost=/bin/chgrp $WSOPD_GROUP corecrypto.log (code=exited, status=0/SUCCESS)
      Process: 295510 ExecStopPost=/bin/chown $WSOPD_USER corecrypto.log (code=exited, status=0/SUCCESS)
      Process: 295508 ExecStopPost=/bin/bash -c echo corecrypto quit results: $SERVICE_RESULT $EXIT_CODE $EXIT_STATUS >> corecrypto.log (code=exited, status=0/SUCCESS)
      Process: 295506 ExecStopPost=/bin/bash -c echo "'corecrypto' shut down" >>corecrypto.log (code=exited, status=0/SUCCESS)
      Process: 295503 ExecStopPost=/bin/bash -c date >>corecrypto.log (code=exited, status=0/SUCCESS)
      Process: 295501 ExecStopPost=/bin/rm -f corecrypto.pid (code=exited, status=0/SUCCESS)
      Process: 295352 ExecStartPost=/bin/bash -c if [ -f "/opt/nfast/scripts/startup/wait-for-corecrypto" ]; then exec "/opt/nfast/scripts/startup/wait-for-corecrypto"; fi (code=exited, status=1/FAILURE)
      Process: 295351 ExecStart=/bin/bash -c if [ -f /etc/nfast.conf ]; then . /etc/nfast.conf; fi; exec "/opt/nfast/sbin/crypto"  >>corecrypto.log 2>>corecrypto.log (code=exited, status=1/FAILURE)
      Process: 295349 ExecStartPre=/bin/bash -c if [ -f /etc/nfast.conf ]; then owrite=$(stat -c%A /etc/nfast.conf | awk '{print substr($0,length-1,1)}'); if [ "$owrite" != "-" ]; then echo "/etc/nfast.conf can be written to by non-root users" >> corecrypto.log; exi\
    t 1; fi; fi (code=exited, status=0/SUCCESS)
      Process: 295347 ExecStartPre=/bin/bash -c if [ -f /etc/nfast.conf ]; then owner=$(stat -c%u:%g /etc/nfast.conf); if [ "$owner" != "0:0" ]; then echo "/etc/nfast.conf is not fully owned by root" >> corecrypto.log; exit 1; fi; fi (code=exited, status=0/SUCCESS)
      Process: 295345 ExecStartPre=/bin/chgrp $WSOPD_GROUP corecrypto.log (code=exited, status=0/SUCCESS)
      Process: 295343 ExecStartPre=/bin/chown $WSOPD_USER corecrypto.log (code=exited, status=0/SUCCESS)
      Process: 295341 ExecStartPre=/bin/touch corecrypto.log (code=exited, status=0/SUCCESS)
      Process: 295339 ExecStartPre=/bin/chgrp $WSOPD_GROUP corecrypto.pid (code=exited, status=0/SUCCESS)
      Process: 295337 ExecStartPre=/bin/chown $WSOPD_USER corecrypto.pid (code=exited, status=0/SUCCESS)
      Process: 295335 ExecStartPre=/bin/touch corecrypto.pid (code=exited, status=0/SUCCESS)
     Main PID: 295351 (code=exited, status=1/FAILURE)
    
    May 21 16:01:58 wsopserver-redhat-8 systemd[1]: Starting nFast corecrypto...
    May 21 16:01:58 wsopserver-redhat-8 systemd[1]: nc_corecrypto.service: Main process exited, code=exited, status=1/FAILURE
    May 21 16:02:03 wsopserver-redhat-8 bash[295352]: waiting for 'corecrypto'
    May 21 16:02:03 wsopserver-redhat-8 bash[295352]: 'corecrypto' did not start; see /opt/nfast/log/corecrypto.log.
    May 21 16:02:03 wsopserver-redhat-8 systemd[1]: nc_corecrypto.service: Control process exited, code=exited status=1
    May 21 16:02:03 wsopserver-redhat-8 systemd[1]: nc_corecrypto.service: Failed with result 'exit-code'.
    May 21 16:02:03 wsopserver-redhat-8 systemd[1]: Failed to start nFast corecrypto.
    2024-05-21 16:01:58.416 [INFO] [DBADAPTER] [295351] TLS CA key loaded
    2024-05-21 16:01:58.416 [ERROR] [DBADAPTER] [295351] TLS configuration failed: open /opt/nfast/webservices/corecrypto/tls/db/wsop_server.key: permission denied
    2024-05-21 16:01:58.416 [FATAL] [WSOP] [295351] [server] NewWSOPServer: cannot initialise database invalid adapter configuration
    Tue May 21 16:02:03 EDT 2024
    'corecrypto' shut down
    corecrypto quit results: exit-code exited
  3. Change the ownership of the following folders as follows:

    % sudo chown -R root:wsopd /opt/nfast/webservices/corecrypto/tls
    % sudo chmod -R 750 /opt/nfast/webservices/corecrypto/tls
  4. Make sure hostname is visible via DNS or by using the /etc/hosts file.

    Edit /etc/hosts and add the hostname to it.

    xxx.xxx.xxx.xxx wsopserver-redhat-8
  5. Restart corecrypto to take in the changes.

    1. Stop the service.

      % sudo /opt/nfast/scripts/init.d/corecrypto stop
    2. Start the service.

      % sudo /opt/nfast/scripts/init.d/corecrypto start
  6. Verify connection to the Entrust nShield WSOP service.

    % curl -k 'https://xxx.xxx.xxx.xxx:18001/health' | jq
    
    
      % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                     Dload  Upload   Total   Spent    Left  Speed
    100    52  100    52    0     0   4333      0 --:--:-- --:--:-- --:--:--  4333
    {
      "releaseId": "1.5.0",
      "status": "pass",
      "version": "1"
    }
  7. Verify the secure connection.

    % sudo curl -X GET \
      --cacert /opt/nfast/webservices/corecrypto/tls/db/myCA.pem \
      --cert /opt/nfast/webservices/corecrypto/tls/external/wsop_client.pem \
      --key /opt/nfast/webservices/corecrypto/tls/external/wsop_client.key \
      --header 'Content-Type: application/json' \
      --header 'Accept: application/json' 'https://xxx.xxx.xxx.xxx:18001/health' | jq
    
      % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                     Dload  Upload   Total   Spent    Left  Speed
    100    52  100    52    0     0   5200      0 --:--:-- --:--:-- --:--:--  5200
    {
      "releaseId": "1.5.0",
      "status": "pass",
      "version": "1"
    }
  8. Check the version

    % /opt/nfast/sbin/crypto --version
    
    crypto, 2.3.0-714-5306bc4