Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

Tasks

Upgrade the Vault Schema

search

Please Note:

Upgrade the Vault Schema

This section describes how to upgrade an existing SFNT_KEY_TABLE and token vault. The installation program enables you to upgrade token vaults created in previous versions, such as 5.3, 5.5, 5.5.1, 6.2.x, or 6.6.x. The upgrade program alters the sfnt_key_table for your database and then offers you the option of converting your token vaults. This section also explains how the sfnt_key_table and token vaults are changed during the upgrade and provides an example of the upgrade portion of the installation script.

This section covers the following topics:

Note

Your permission is required for all table structure changes. The installation program prompts before updating sfnt_key_table and you must trigger the upgrade for each token vault.

Upgrading the SFNT_KEY_TABLE

There is one sfnt_key_table per database/schema, so this upgrade occurs only once per database/schema. Before the upgrade, a sfnt_key_table created in version 5.5.1 has the following structure:

ENCKEYHMACKEYTABLENAME
encKey1macKey1TOKEN_VAULT_1
encKey2macKey2TOKEN_VAULT_2
encKey3macKey3TOKEN_VAULT_3

The sfnt_key_table adds the TOKENVAULTNAME and KEYROTATIONDATE columns. An upgraded version of the table shown above would look like this:

ENCKEYHMACKEYTABLENAMETOKENVAULTNAMEKEYROTATIONDATE
encKey1macKey1TOKEN_VAULT_1TV$TOKEN_VAULT_1
encKey2macKey2TOKEN_VAULT_2TV$TOKEN_VAULT_2
encKey3macKey3TOKEN_VAULT_3TV$TOKEN_VAULT_3

Notice that the values in the TOKENVAULTNAME column append TV$ to the TABLENAME values. The TV$ is removed when the token vault itself is upgraded.

The KEYROTATIONDATE column enables the CT-V to track when key rotations occur, and to continue rotations if they are interrupted. For more information on key rotations, see Rotating and Re-Keying the Token Vault.

Upgrading a Token Vault

You must upgrade each token vault individually. Before upgrading, ensure to take the old version of CT-V instance offline and all access to the token vault must be stopped; otherwise, the incoming data will be lost. After upgrade, you can resume the CT-V operations.

Note

It is recommended to upgrade the Token Vault schema before using the Tokenization APIs.

Before the upgrade, a token vault created in lower version, for example, 8.4.0 has the following structure. (A few columns have been abridged to make the text readable.)

After upgrading, the table shown above would look like this:

Note

When upgrading CT-V to the latest version, ensure to use the latest version of jars provided in the /SafeNetTokenization/Tokenization/lib/ext directory.

Sample Upgrade Script

The following sample is an excerpt of upgrade for SQL Server.

To use any existing Token Vault, it is recommended to upgrade the Token Vault schema before using the Tokenization APIs.
Do you want to continue with upgrade of Token Vault Schema? [Yes|No] Y
Enter the database username: sa
Enter the database password:
Executing TVMSQLServer 5.3.0 to 5.5.0 Upgrader
==> 5.5.0: SCHEMA VERSION 6.5.0.000 APPEARS TO BE UP TO DATE.
Executing TVMSQLServer 5.5.0 to 5.5.1 Upgrader
==> 5.5.1: SCHEMA VERSION 6.5.0.000 APPEARS TO BE UP TO DATE.
Executing TVMSQLServer 5.5.1 to 6.3.0 Upgrader
==> 6.3.0: SCHEMA VERSION 6.5.0.000 APPEARS TO BE UP TO DATE.
Executing TVMSQLServer 6.3.0 to 6.5.0 Upgrader
==> 6.5.0: SCHEMA VERSION 6.5.0.000 APPEARS TO BE UP TO DATE.
Executing TVMSQLServer 6.5.0 to 8.1.0 Upgrader
Executing: SELECT DISTINCT table_name FROM information_schema.columns isc, sfnt_key_table skt
WHERE isc.table_name = skt.tokenvaultname AND
isc.table_name NOT IN (
select isc_sub.table_name    FROM information_schema.columns isc_sub
WHERE    isc_sub.column_name = 'lastaccessdate' )
ORDER BY 1
==> 6.5.0: SCHEMA VERSION 8.1.0.000 APPEARS TO BE UP TO DATE.
Executing TVMSQLServer 8.1.0 to 8.3.0 Upgrader
Executing: SELECT DISTINCT table_name FROM information_schema.columns isc, sfnt_key_table skt
WHERE isc.table_name = skt.tokenvaultname AND isc.column_name = 'tokenproperty' ORDER BY 1
Executing: SELECT DISTINCT table_name FROM information_schema.columns isc, sfnt_key_table skt
WHERE isc.table_name = skt.tokenvaultname AND
isc.table_name NOT IN (
select isc_sub.table_name    FROM information_schema.columns isc_sub
WHERE    isc_sub.column_name = 'tokenproperty' )
ORDER BY 1
==> 8.1.0: SCHEMA VERSION 8.3.0.000 APPEARS TO BE UP TO DATE.
Executing TVMSQLServer 8.3.0 to 8.4.0 Upgrader
==> 8.3.0: SCHEMA VERSION 8.4.0.000 APPEARS TO BE UP TO DATE.
Executing TVMSQLServer 8.4.0 to 8.4.2 Upgrader
Executing: SELECT DISTINCT table_name FROM information_schema.columns isc, sfnt_key_table skt
WHERE isc.table_name = skt.tokenvaultname AND isc.column_name = 'customtokenproperty' ORDER BY 1
Executing: SELECT DISTINCT table_name FROM information_schema.columns isc, sfnt_key_table skt
WHERE isc.table_name = skt.tokenvaultname AND
isc.table_name NOT IN (
select isc_sub.table_name    FROM information_schema.columns isc_sub
WHERE    isc_sub.column_name = 'customtokenproperty' )
ORDER BY 1
==> 8.4.0: SCHEMA VERSION 8.4.2.000 APPEARS TO BE UP TO DATE.
Executing TVMSQLServer 8.4.2 to 8.4.3 Upgrader
==> 8.4.2: SCHEMA VERSION 8.4.3.000 APPEARS TO BE UP TO DATE.
Executing TVMSQLServer 8.4.3 to 8.5.0 Upgrader
==> 8.4.3: SCHEMA VERSION 8.5.0.000 APPEARS TO BE UP TO DATE.
Executing TVMSQLServer 8.5.0 to 8.6.0 Upgrader
==> 8.5.0: SCHEMA VERSION 8.6.0.000 APPEARS TO BE UP TO DATE.
Executing TVMSQLServer 8.6.0 to 8.7.0 Upgrader
==> 8.6.0: SCHEMA VERSION 8.7.0.000 APPEARS TO BE UP TO DATE.
Executing TVMSQLServer 8.7.0 to 8.10.1 Upgrader
==> 8.7.0: SCHEMA VERSION 8.10.1.000 APPEARS TO BE UP TO DATE.
Executing TVMSQLServer 8.10.1 to 8.10.2 Upgrader
Executing: SELECT DISTINCT table_name FROM information_schema.columns isc, sfnt_key_table skt
WHERE isc.table_name = skt.tokenvaultname AND isc.column_name = 'tokenproperty' ORDER BY 1
Executing :  ALTER TABLE [TMV_2] ALTER COLUMN tokenproperty nvarchar(16) NULL
Executing:  SELECT name FROM SYS.DEFAULT_CONSTRAINTS where name like 'DF__TMV_2[__]%'
Executing :  ALTER TABLE [TMV_3] ALTER COLUMN tokenproperty nvarchar(16) NULL
Executing:  SELECT name FROM SYS.DEFAULT_CONSTRAINTS where name like 'DF__TMV_3[__]%'
==> 8.10.1: SCHEMA VERSION 8.10.2.000 APPEARS TO BE UP TO DATE.
Executing TVMSQLServer 8.10.2 to 8.12.4 Upgrader
==> 8.10.2: SCHEMA VERSION 8.12.4.000 APPEARS TO BE UP TO DATE.

The following sample is an excerpt of upgrade for MySQL. 

To use any existing Token Vault, it is recommended to upgrade the Token Vault schema before using the Tokenization APIs.
Do you want to continue with upgrade of Token Vault Schema? [Yes|No] Yes
Enter the database username: sa
Enter the database password:
Tue Mar 02 13:46:56 IST 2021 WARN: Establishing SSL connection without server's identity verification is not recommended. According to MySQL 5.5.45+, 5.6.26+ and 5.7.6+ requirements SSL connection must be established by default if explicit option isn't set. For compliance with existing applications not using SSL the verifyServerCertificate property is set to 'false'. You need either to explicitly disable SSL by setting useSSL=false, or set useSSL=true and provide truststore for server certificate verification.
Tue Mar 02 13:46:57 IST 2021 WARN: Establishing SSL connection without server's identity verification is not recommended. According to MySQL 5.5.45+, 5.6.26+ and 5.7.6+ requirements SSL connection must be established by default if explicit option isn't set. For compliance with existing applications not using SSL the verifyServerCertificate property is set to 'false'. You need either to explicitly disable SSL by setting useSSL=false, or set useSSL=true and provide truststore for server certificate verification.
Checking the records if duplicate macvalue is present in the vault or not....
Executing: SELECT DISTINCT table_name FROM information_schema.columns isc, sfnt_key_table skt
WHERE isc.table_name = skt.tokenvaultname AND (isc.column_name = 'macvalue' OR isc.column_name = 'customdata') and isc.table_schema ='test_upgrader2'
ORDER BY 1
Executing: select count(*) from test_upgrader2.tmv_1 group by macvalue having count(*) > 1
Executing: select count(*) from test_upgrader2.tmv_11 group by macvalue having count(*) > 1
Executing: select count(*) from test_upgrader2.tmv_12 group by macvalue having count(*) > 1
Executing: select count(*) from test_upgrader2.tmv_13 group by macvalue having count(*) > 1
==> 6.3.0: SCHEMA VERSION 6.5.0.000 APPEARS TO BE UP TO DATE.
==> 6.5.0: SCHEMA VERSION 6.5.0.000 APPEARS TO BE UP TO DATE.
Executing: TVMMySQL Upgrader
==> 6.6.0: SCHEMA VERSION 6.6.0.000 APPEARS TO BE UP TO DATE.
TVMMySQL Upgrader 6.6.0 to 8.1.0
Executing: SELECT DISTINCT table_name FROM information_schema.columns isc, sfnt_key_table skt
WHERE isc.table_name = skt.tokenvaultname AND
isc.table_name NOT IN (
select isc_sub.table_name    FROM information_schema.columns isc_sub
WHERE    isc_sub.column_name = 'lastaccessdate' and isc_sub.table_schema ='test_upgrader2')
ORDER BY 1
TVMMySQL Upgrader 8.1.0 to 8.3.0
Executing: SELECT DISTINCT table_name FROM information_schema.columns isc, sfnt_key_table skt
WHERE isc.table_name = skt.tokenvaultname AND isc.column_name = 'tokenproperty' and isc.table_schema ='test_upgrader2'
ORDER BY 1
Executing: SELECT DISTINCT table_name FROM information_schema.columns isc, sfnt_key_table skt
WHERE isc.table_name = skt.tokenvaultname AND
isc.table_name NOT IN (
select isc_sub.table_name    FROM information_schema.columns isc_sub
WHERE    isc_sub.column_name = 'tokenproperty' and isc_sub.table_schema ='test_upgrader2' )
ORDER BY 1
==> 8.1.0: SCHEMA VERSION 8.3.0.000 APPEARS TO BE UP TO DATE.
Executing: TVMMySQL 8.3.0 to 8.4.0 Upgrader
==> 8.3.0: SCHEMA VERSION 8.4.0.000 APPEARS TO BE UP TO DATE.
TVMMySQL 8.4.0 to 8.4.2 Upgrader
Executing: SELECT DISTINCT table_name FROM information_schema.columns isc, sfnt_key_table skt
WHERE isc.table_name = skt.tokenvaultname AND isc.column_name = 'customtokenproperty' and isc.table_schema ='test_upgrader2'
ORDER BY 1
Executing: SELECT DISTINCT table_name FROM information_schema.columns isc, sfnt_key_table skt
WHERE isc.table_name = skt.tokenvaultname AND
isc.table_name NOT IN (
select isc_sub.table_name    FROM information_schema.columns isc_sub
WHERE    isc_sub.column_name = 'customtokenproperty' and isc_sub.table_schema ='test_upgrader2' )
ORDER BY 1
==> 8.4.0: SCHEMA VERSION 8.4.2.000 APPEARS TO BE UP TO DATE.
Executing: TVMMySQL 8.4.2 to 8.4.3 Upgrader
==> 8.4.2: SCHEMA VERSION 8.4.3.000 APPEARS TO BE UP TO DATE.
Executing: TVMMySQL 8.4.3 to 8.5.0 Upgrader
==> 8.4.3: SCHEMA VERSION 8.5.0.000 APPEARS TO BE UP TO DATE.
Executing: TVMMySQL 8.5.0 to 8.6.0 Upgrader
==> 8.5.0: SCHEMA VERSION 8.6.0.000 APPEARS TO BE UP TO DATE.
Executing: TVMMySQL 8.6.0 to 8.7.0 Upgrader
==> 8.6.0: SCHEMA VERSION 8.7.0.000 APPEARS TO BE UP TO DATE.
Executing: TVMMySQL 8.7.0 to 8.10.1 Upgrader
==> 8.7.0: SCHEMA VERSION 8.10.1.000 APPEARS TO BE UP TO DATE.
TVMMySQL 8.10.1 to 8.10.2 Upgrader
Executing: SELECT DISTINCT table_name FROM information_schema.columns isc, sfnt_key_table skt
WHERE isc.table_name = skt.tokenvaultname AND isc.column_name = 'tokenproperty' and isc.table_schema ='test_upgrader2'
ORDER BY 1
Executing :  ALTER TABLE tmv_1 MODIFY COLUMN tokenproperty nvarchar(16) null
Executing:  ALTER TABLE tmv_1 ALTER COLUMN tokenproperty DROP DEFAULT
Executing :  ALTER TABLE tmv_11 MODIFY COLUMN tokenproperty nvarchar(16) null
Executing:  ALTER TABLE tmv_11 ALTER COLUMN tokenproperty DROP DEFAULT
Executing :  ALTER TABLE tmv_12 MODIFY COLUMN tokenproperty nvarchar(16) null
Executing:  ALTER TABLE tmv_12 ALTER COLUMN tokenproperty DROP DEFAULT
Executing :  ALTER TABLE tmv_13 MODIFY COLUMN tokenproperty nvarchar(16) null
Executing:  ALTER TABLE tmv_13 ALTER COLUMN tokenproperty DROP DEFAULT
==> 8.10.1: SCHEMA VERSION 8.10.2.000 APPEARS TO BE UP TO DATE.
Executing: TVMMySQL 8.10.2 to 8.12.2 Upgrader
==> 8.10.2: SCHEMA VERSION 8.12.2.000 APPEARS TO BE UP TO DATE.
TVMMySQL 8.12.2 to 8.12.4 Upgrader
Executing: SELECT DISTINCT table_name FROM information_schema.columns isc, sfnt_key_table skt
WHERE isc.table_name = skt.tokenvaultname AND (isc.column_name = 'macvalue' OR isc.column_name = 'customdata') and isc.table_schema ='test_upgrader2'
ORDER BY 1
Executing: SELECT DISTINCT INDEX_NAME FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA ='test_upgrader2' AND INDEX_NAME ='tmv_1_mcval'
Executing: SELECT DISTINCT INDEX_NAME FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA ='test_upgrader2' AND INDEX_NAME ='tmv_1_crtdate'
Executing: SELECT DISTINCT INDEX_NAME FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA ='test_upgrader2' AND INDEX_NAME ='tmv_1_mc'
Executing: SELECT DISTINCT INDEX_NAME FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA ='test_upgrader2' AND INDEX_NAME ='tmv_1_cdate'
Executing: SELECT CHARACTER_MAXIMUM_LENGTH FROM information_schema.columns where table_schema ='test_upgrader2' and table_name='tmv_1' and column_name='customdata'
Press Enter, to keep the existing size (20000) of customdata column else provide the new size of customdata column of vault :
Executing:  ALTER TABLE tmv_1 MODIFY COLUMN customdata NVARCHAR(20000)
Executing: SELECT DISTINCT INDEX_NAME FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA ='test_upgrader2' AND INDEX_NAME ='tmv_11_mcval'
Executing: SELECT DISTINCT INDEX_NAME FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA ='test_upgrader2' AND INDEX_NAME ='tmv_11_crtdate'
Executing: SELECT DISTINCT INDEX_NAME FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA ='test_upgrader2' AND INDEX_NAME ='tmv_11_mc'
Executing: SELECT DISTINCT INDEX_NAME FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA ='test_upgrader2' AND INDEX_NAME ='tmv_11_cdate'
Executing: SELECT CHARACTER_MAXIMUM_LENGTH FROM information_schema.columns where table_schema ='test_upgrader2' and table_name='tmv_11' and column_name='customdata'
Press Enter, to keep the existing size (20000) of customdata column else provide the new size of customdata column of vault :
Executing:  ALTER TABLE tmv_11 MODIFY COLUMN customdata NVARCHAR(20000)
Executing: SELECT DISTINCT INDEX_NAME FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA ='test_upgrader2' AND INDEX_NAME ='tmv_12_mcval'
Executing: SELECT DISTINCT INDEX_NAME FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA ='test_upgrader2' AND INDEX_NAME ='tmv_12_crtdate'
Executing: SELECT DISTINCT INDEX_NAME FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA ='test_upgrader2' AND INDEX_NAME ='tmv_12_mc'
Executing: SELECT DISTINCT INDEX_NAME FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA ='test_upgrader2' AND INDEX_NAME ='tmv_12_cdate'
Executing: SELECT CHARACTER_MAXIMUM_LENGTH FROM information_schema.columns where table_schema ='test_upgrader2' and table_name='tmv_12' and column_name='customdata'
Press Enter, to keep the existing size (10000) of customdata column else provide the new size of customdata column of vault :
Executing:  ALTER TABLE tmv_12 MODIFY COLUMN customdata NVARCHAR(10000)
Executing: SELECT DISTINCT INDEX_NAME FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA ='test_upgrader2' AND INDEX_NAME ='tmv_13_mcval'
Executing: CREATE UNIQUE INDEX TMV_13_mcval ON tmv_13(macvalue)
Executing: SELECT DISTINCT INDEX_NAME FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA ='test_upgrader2' AND INDEX_NAME ='tmv_13_crtdate'
Executing: CREATE INDEX TMV_13_crtdate ON tmv_13(creationdate)
Executing: SELECT DISTINCT INDEX_NAME FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA ='test_upgrader2' AND INDEX_NAME ='tmv_13_mc'
Executing: DROP INDEX TMV_13_mc ON tmv_13
Executing: SELECT DISTINCT INDEX_NAME FROM INFORMATION_SCHEMA.STATISTICS WHERE TABLE_SCHEMA ='test_upgrader2' AND INDEX_NAME ='tmv_13_cdate'
Executing: DROP INDEX TMV_13_cdate ON tmv_13
Executing: SELECT CHARACTER_MAXIMUM_LENGTH FROM information_schema.columns where table_schema ='test_upgrader2' and table_name='tmv_13' and column_name='customdata'
Press Enter, to keep the existing size (255) of customdata column else provide the new size of customdata column of vault :
Executing:  ALTER TABLE tmv_13 MODIFY COLUMN customdata NVARCHAR(255)

Note

For MySQL, if the token vault contains duplicate macvalues then the upgrade will be terminated with the following message:

Vault Schema upgrade is not successful: Cannot upgrade the schema as same plaintext with different custom data is not supported. Please restore the old version libraries from the backup and remove the new version libraries from the CT-V installed directory manually !!!

On this page