Digipass S3 is now DigipassONE. This section is currently being updated to reflect our new name.

Installing the Crypto and Secrets plugins

  • Updated on Apr 21, 2026
  • Published on Mar 12, 2026
  • 6 minute(s) read
Prev Next

The following instructions are for customers who deploy Digipass S3 Software on Linux. They do not apply to customers who use the Digipass S3 Cloud Deployment Toolkit. If you are deploying Digipass S3 Software using the Digipass S3 Cloud Deployment Toolkit, please contact OneSpan Customer Support before continuing.

When you install the Crypto or the Secrets Plugin on a production Server, the steps to follow depend on whether you are implementing both. If you are implementing the Crypto Plugin only, then follow the steps in Installing Crypto Plugin Only. If you are implementing the Secrets Plugin only, then follow the steps in Installing Secrets Plugin Only. If you implemented both plugins, install them using the following instructions.

Installing both Crypto and Secrets plugin

Before installing the Digipass S3 Server, set up your external secrets manager with your operational database password along with its handle. You can choose to load any remaining passwords and their handles into your external secrets manager after installation.

Begin by completing Steps 1, 2 and 3 of Install the Digipass S3 Servers on Linux. If you plan to store any passwords in encrypted form in the Digipass S3 database, then also complete Step 4 of Install the Digipass S3 Servers on Linux.

Next, uncomment and update the properties below in nnl-install.properties.

Property

Expected Value

NNL_CRYPTO_PLUGIN_CLASS_NAME

The name of your class that implements the interface CryptoPlugin.

NNL_SECRETS_PLUGIN_CLASS_NAME

The name of your class that implements the interface SecretsPlugin.

NNL_EXT_DIR_PATHS

The directory paths to your Crypto plugin, Secrets plugin, and other required JAR files.

What you do next depends on if you plan to use a handle to retrieve the password or store the encrypted password in the database.

Use a handle to the external secrets manager

If you will not be storing any encrypted passwords in the database, i.e. you will always use a handle to the external secrets manager, then make the following changes to the nnl-install.properties file:

  • Comment out DB_ENCRYPTED_USER_PASSWD_ENV

  • Uncomment and configure DB_SECRET_HANDLE_ENV={handle}<The handle for the operational database password from the external secrets manager>

Note that "{handle}" is prefixed literally.

Store the encrypted password in the database

In certain circumstances you will install the Secrets plugin and continue to store an encrypted password in the database. In this case, make the following changes to the nnl-install.properties file:

  • Uncomment and configure DB_ENCRYPTED_USER_PASSWD_ENV

  • Comment out DB_SECRET_HANDLE_ENV

In either case:

After you have completed the configuration of the Secrets plugin, go to Step 6. Install the Server and its Components to run the installation script and then return here.

If you completed installation successfully, you see the following:

  • Inside the tomcat/bin/setenv.sh file:

CATALINA_OPTS="${CATALINA_OPTS}-Dnnl.crypto.plugin.class.name=<The name of your class that implements the interface CryptoPlugin>"

  • JARs from the paths specified in NNL_EXT_DIR_PATHS are copied into the web applications' lib directories. For example: tomcat/webapps/nnl/WEB-INF/lib/

  • Use the following nnl-mgmt.sh command to list the SYSTEM tenant's properties so you can verify the values. For details, see Properties Commands.

./nnl-mgmt.sh properties list -tenantid system

Verify the values for the properties listed below:

nnl.default.external.encryption.key.jce.provider.name=NokNokCryptoProvider
nnl.jce.providers=com.noknok.crypto.provider.NokNokCryptoProvider,org.bouncycastle.jce.provider.BouncyCastleProvider

  • Inside the tomcat/bin/setenv.sh file :

CATALINA_OPTS="${CATALINA_OPTS}-Dnnl.secrets.plugin.class.name=<The name of your class that implements the interface SecretsPlugin>"

  • The JARs from the paths specified in NNL_EXT_DIR_PATHS are copied into the correct server and web applications' lib directories. For example, for the Authentication Server, these libraries are in tomcat/webapps/nnl/WEB-INF/lib/.

  • The handle for the Operational database password in the external secrets manager is updated in the following files:

    • <TOMCAT_HOME>/bin/setenv.sh

    • <MFAS_HOME>/admin/conf/nnl-db.properties

    • <MFAS_HOME>/admin/conf/application.properties

Verify the installation by running the <NNL_HOME>/install/nnl-postinstall-checks.sh script. Examine the output to uncover any configuration issues.

After you verify the installation, perform the Post Installation tasks.

For the Crypto plugin, configure an alias for the encryption key for default and Admin tenants. If required, also configure an alias for the encryption key for other tenants. You can enter the aliases using the Admin Console or using the command line interface. See Rotate Encryption Keys.

Installing Crypto plugin only

Use the instructions below to install and configure just a Crypto plugin in the Digipass S3 Server. Do not use these instructions if you are planning on installing both the Crypto and the Secrets plugin.

Begin by completing Steps 1, 2, 3 and 4 of Install on Linux.

Next, update the Crypto plugin properties in nnl-install.properties

  • NNL_CRYPTO_PLUGIN_CLASS_NAME = <The name of your class that implements the interface CryptoPlugin>

  • NNL_EXT_DIR_PATHS = <The directory paths to your Crypto plugin and other required jar files>

You are now ready to install, go to Step 6. Install the Server and its Components to run the installation script and then return here.

If you completed installation successfully, you see the following

  • Inside the tomcat/bin/setenv.sh file :

CATALINA_OPTS="${CATALINA_OPTS} -Dnnl.crypto.plugin.class.name=<The name of your class that implements the interface CryptoPlugin>"

  • Jars from the paths specified in NNL_EXT_DIR_PATHS are copied into the web applications' lib directories. For example: tomcat/webapps/nnl/WEB-INF/lib/

  • The following properties are configured for the SYSTEM tenant:

    • nnl.default.external.encryption.key.jce.provider.name=NokNokCryptoProvider

    • nnl.jce.providers=com.noknok.crypto.provider.NokNokCryptoProvider,org.bouncycastle.jce.provider.BouncyCastleProvider

Verify the installation by running the <NNL_HOME>/install/nnl-postinstall-checks.sh script. Examine the output to uncover any configuration issues. After you verify the installation, perform the Post Installation tasks.

Configure an alias for the encryption key for default and Admin tenants. If required, also configure an alias for the encryption key for other tenants. You can enter the aliases using the Admin Console or using the command line interface.

If you are using the command line interface, enter the following commands and respond to the resulting prompts by entering your alias:

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

Installing Secrets plugin only

Before installing the Digipass S3 Server, set up your external secrets manager with your operational database password along with its handle. You can choose to load any remaining passwords and their handles into your external secrets manager after installation.

Use these instructions to install and configure the Secrets plugin alone. Do not use these instructions if you are going to deploy both the Secrets plugin and the Crypto plugin.

Begin by completing Steps 1, 2 and 3 of Install using Linux. If you plan to store any passwords in encrypted form in the Digipass S3 database, then also complete Step 4 of Installing the Digipass S3 Servers.

Next, uncomment and update the Secrets plugin properties in nnl-install.properties.

  • NNL_SECRETS_PLUGIN_CLASS_NAME=<The name of your class that implements the interface SecretsPlugin>

  • NNL_EXT_DIR_PATHS=<The directory paths to your Secrets plugin and other required jar files>

What you do next depends on if you plan to use a handle to retrieve the password or store the encrypted password in the database.

Use a handle to the external secrets manager

If you will not be storing any encrypted passwords in the database, i.e. you will always use a handle to the external secrets manager, then make the following changes to the nnl-install.properties file:

  • Comment out DB_ENCRYPTED_USER_PASSWD_ENV

  • Uncomment and configure DB_SECRET_HANDLE_ENV={handle}<The handle for the operational database password from the external secrets manager>

Note that "{handle}" is prefixed literally.

Store the encrypted password in the database

In certain circumstances you will install the Secrets plugin and continue to store an encrypted password in the database. In this case, make the following changes to the nnl-install.properties file:

  • Uncomment and configure DB_ENCRYPTED_USER_PASSWD_ENV

  • Comment out DB_SECRET_HANDLE_ENV

In either case:

After you have completed the configuration of the Secrets plugin, go to Step 6. Install the Server and its Components to run the installation script and then return here.

If you completed installation successfully, you see the following:

  • Inside the tomcat/bin/setenv.sh file:

CATALINA_OPTS="${CATALINA_OPTS}-Dnnl.secrets.plugin.class.name=<The name of your class that implements the interface SecretsPlugin>"

  • The jars from the paths specified in NNL_EXT_DIR_PATHS are copied into the web applications' lib directories. For example, for the authentication server these libraries will be in tomcat/webapps/nnl/WEB-INF/lib/

  • The handle for the operational database password in the external secrets manager is updated in the following files:

    • <TOMCAT_HOME>/bin/setenv.sh

    • <MFAS_HOME>/admin/conf/nnl-db.properties

    • <MFAS_HOME>/admin/conf/application.properties

Verify the installation by running the <NNL_HOME>/install/nnl-postinstall-checks.sh script. Examine the output to uncover any configuration issues. After you verify the installation, perform the Post Installation tasks.