Implementing the Crypto Plugin

Nok Nok Server components provide a programmatic interface in Java for you to develop a plugin that supports the use of an external cryptographic service provider. The following operations are supported through the Crypto plugin:

• Encryption and decryption of:

  • Server data in UAF/FIDO2 protocol messages

  • Data required for FIDO out-of-band operations

• Digital signature generation and validation of JWT data used in the following:

  • Session token

  • EMV 3DS blob

  • Transaction confirmation token

Creating a Crypto Plugin

A Crypto plugin must implement the following Java interface:

package com.noknok.crypto.sdk;
/**
 * Implement this interface to perform cryptographic operations - sign,
 * encrypt and decrypt  
 *
 * The implementation class name should be provided as Java system property
 * nnl.crypto.plugin.class.name.
 *
 * Each server component (Auth Server, API Server etc.) creates a single
 * instance of the implementation using the no-argument constructor at
 * startup. All the methods in this interface may be called from multiple
 * threads. They should throw exceptions for any failures.
 */
interface CryptoPlugin {
    /**
     * Sign the data and return the result.
     *
     * @param context context for the request
     * @param alias identifies the key
     * @param algorithm name of algorithm as defined by Java
     * @param params optional parameters
     **/
    public byte[] sign(CryptoContext context, String alias, String algorithm, 
        AlgorithmParameterSpec params, byte[] data);
    /**
     * Encrypt the data and return the result.
     *
     * @param context context for the request
     * @param alias identifies the key
     * @param algorithm name of algorithm as defined by Java
     * @param params optional algorithm parameters
     */
    public byte[] encrypt(CryptoContext context, String alias, 
        String algorithm, AlgorithmParameterSpec params, byte[] data);
    /**
     * Decrypt the data and return the result.
     *
     * @param context context for the request
     * @param alias identifies the key
     * @param algorithm name of algorithm as defined by Java
     * @param params optional algorithm parameters
     */
public byte[] decrypt(CryptoContext context, String alias, String algorithm,
     AlgorithmParameterSpec params, byte[] data);
}
/**
 * Provides the context for cryptographic operation.
 */
public static class CryptoContext {
    /**
     * Returns the name of the context. Possible names are
     * "serverDataCipher" and "jwtGenerate".
     * 
     * @return the name
     */
    public String getName();
    /**
     * Returns the id of the tenant
     * 
     * @return the tenant ID
     */
    public String getTenantId();
    public CryptoContext(String name, String tenantId) {
    this.name = name;
        this.tenantId = tenantId;
    }
}

Building and Deploying the Crypto Plugin

Use the instructions below to build your Crypto plugin.

1. Make sure you have access to a Nok Nok Server installation for development and testing purposes.

2. Build your CryptoPlugin class with a dependency on nnlcrypto-9.3.0.xxx.jar found under the <NNL_HOME>/admin/lib/thirdparty folder.

3. Package the CryptoPlugin implementation in a jar file.

Configuring the Nok Nok Server with the Crypto Plugin

Step 1. Copy the CryptoPlugin implementation jar file, along with its third party dependencies, into the Nok Nok web applications' lib directories listed below.

• tomcat/webapps/nnl/WEB-INF/lib/

• tomcat/webapps/nnlgateway/WEB-INF/lib/

• tomcat/webapps/nnlfedapp/WEB-INF/lib/

• tomcat/webapps/nnlauthsvc/WEB-INF/lib/

• tomcat/webapps/gwtutorial/WEB-INF/lib/

Step 2. Provide the name of the class that implements the interface CryptoPlugin as a Java system property nnl.crypto.plugin.class.name. Enter the name of the class inside the <TOMCAT_HOME>/bin/setenv.sh file:

CATALINA_OPTS="${CATALINA_OPTS} -Dnnl.crypto.plugin.class.name=com.mycompany.CryptoPlugin"

Step 3. Using nnl-mgmt.sh, assign the values shown below to nnl.jce.providers and nnl.default.external.encryption.key.jce.provider.name. These are SYSTEM tenant properties.

./nnl-mgmt.sh properties set -name "nnl.jce.providers" -value  "com.noknok.crypto.provider.NokNokCryptoProvider,org.bouncycastle.jce.provider.BouncyCastleProvider" -tenantid SYSTEM
./nnl-mgmt.sh properties set -name "nnl.default.external.encryption.key.jce.provider.name" -value "NokNokCryptoProvider" -tenantid SYSTEM

Step 4. Using nnl-mgmt.sh as shown below, configure the alias to be the encryption key for your tenant.

./nnl-mgmt.sh key add -tenantid default -autogenerate no

Step 5. Configure the Nok Nok API Server's JWT Processor plugin. See the tables for the generate and validate fields in JWT Configuration Object Fields.

1. Set the jwks_keystore.provider field in jwt_config to "NokNokCryptoProvider".

2. Set the jwks_keystore.type field in jwt_config to "NokNokKeyStore".

3. Set the jwks_keystore.keys in jwt_config.This is a stringified JSON array containing references to keys. Each key reference defines "kid" (the key alias), "kty" (the key type/algorithm) and optionally "x5c" (certificate chain) attributes. Supported values for "kty" are "RSA", "EC" and "oct". The "x5c" attribute is required for "RSA" and "EC" key references. Below are examples of defining key references for each type:

[
  {
    "kid": "<key_alias_1>",
    "kty": "RSA",
    "x5c": [
      "<base64_cert1_of_key_1>",
      "<base64_cert2_of_key_1>"
    ]
  },
  {
    "kid": "<key_alias_2>",
    "kty": "EC",
    "x5c": [
      "<base64_cert1_of_key_2>",
      "<base64_cert2_of_key_2>"
    ]
  },
  {
    "kid": "<key_alias_3>",
    "kty": "oct"
  }
]

Step 6. Restart Tomcat and verify that registration and authentication works.

See Installing the Crypto and Secrets Plugin for details on how to install your Crypto plugin in a Nok Nok Server for production purposes.