Data tokenization and anonymization operations.
SVault
The SVault module APIs provide tokenization functionalities for anonymizing and pseudonymizing databases containing Personally Identifiable Information (PII). The tokenization process is based on the generation of random numbers by a FIPS SP800-90A DRBG ( NIST CAVP approval).
Architecture
The SVault Dinamo module tokenizes personally identifiable information (also called secret) by generating a random token and a blob token(secret and encrypted metadata).
The token blob can be stored and used for later retrieval of the secret, for pseudonymization operations. For anonymization operations, the token blob must be discarded and the secret cannot be recovered later.
The token generated replaces the secret in the original database and may have the blob token associated with it in cases of pseudonymization. The token can have its format (decimal, base62, etc.) and the ability to generate check digits (in the case of CPF, CNPJ, PAN, etc.) specified at the time of generation.
Sensitive data is protected using a symmetric key protected within the HSM.
Retrieving the secret using the token blob allows it to be retrieved in clear text or masked. Masking is done internally to the HSM, preventing the secret from being manipulated in clear text by the application.
---
title: Secrets coding flow
---
sequenceDiagram
autonumber
participant base as Database
participant app as Application
participant hsm as HSM
Note over hsm: key
app ->> hsm: secret
hsm ->> hsm: encrypt
hsm ->> app: token (pseudomized data)
token blob (encrypted secret)
app ->> base: token
token blob
Note over base: token
token blob
---
title: Blob token decoding flow
---
sequenceDiagram
autonumber
participant base as Database
participant app as Application
participant hsm as HSM
Note over base: token (pseudomized data)
token blob (encrypted secret)
Note over hsm: key
app ->> base: search token blob
base ->> app: token blob
app ->> hsm: token blob
hsm ->> hsm: decrypt
hsm ->> app: secret
- Attention
- The tokens are generated randomly and, naturally, there is the possibility of conflicting tokens being generated. Therefore, the application will have to deal with the collisions by requesting the generation of the token again in order to guarantee the storage of unique tokens.
|
| SVaultGenTokenResponse | GenSVaultToken (int op, SVaultGenTokenInfo tokenInfo, int reserved) throws TacException |
| | It tokenizes a piece of data, generating a token blob and its respective token.
|
| |
| SVaultGenTokenResponse | GenSVaultToken(SVaultGenTokenInfo tokenInfo ) throws TacException |
| | It tokenizes a piece of data, generating a token blob and its respective token.
|
| |
| SVaultGenTokenResponse | GenSVaultDigitToken (byte CKS, byte maskFlags, String MK, String secret) throws TacException |
| | It tokenizes digits, generating a token blob and its respective token.
|
| |
| SVaultGenTokenResponse | GenSVaultStringToken (byte maskFlags, String MK, String secret) throws TacException |
| | It tokenizes a UTF-8 string, generating a token blob and its respective token.
|
| |
| String | GetSVaultTokenBlobData (int op, String MK, String mask, byte[] tokenBlob) throws TacException |
| | Retrieves the secret or token of tokenized data using a token blob.
|
| |
| String | GetSVaultSecret (String MK, String mask, byte[] tokenBlob) throws TacException |
| | Retrieves the secret of tokenized data using a token blob.
|
| |
| String | GetSVaultToken (String MK, String mask, byte[] tokenBlob) throws TacException |
| | Retrieves the token of tokenized data using a token blob.
|
| |
◆ GenSVaultToken() [1/2]
It tokenizes a piece of data, generating a token blob and its respective token.
- Parameters
-
| op | Type of operation. Must be 0. |
| tokenInfo | Details of the tokenization operation |
| reserved | Reserved for future use (must be 0). |
- Return
- Exceptions
-
◆ GenSVaultToken() [2/2]
It tokenizes a piece of data, generating a token blob and its respective token.
- Parameters
-
| tokenInfo | Details of the tokenization operation |
- Return
- Exceptions
-
◆ GenSVaultDigitToken()
It tokenizes digits, generating a token blob and its respective token.
- Parameters
-
| CKS | Defines the type of checksum for the generation of tokens. It can be one of the options in the table below
| Value | Operation |
| TacNDJavaLib.D_SVAULT_CKS_NULL | It doesn't generate a checksum. It only generates the token. |
| TacNDJavaLib.D_SVAULT_CKS_CPF | Generates the 2 check digits in the CPF (Cadastro de Pessoas Físicas) standard on the token. The secret must contain only numbers and include the check digits. |
| TacNDJavaLib.D_SVAULT_CKS_CNPJ | Generates the 2 verification digits in the CNPJ (Cadastro Nacional da Pessoa Jurídica) standard on the token. The secret must contain only numbers and include the check digits. |
| TacNDJavaLib.D_SVAULT_CKS_PAN | Generates a PAN (Primary Account Number) with a valid check digit in the token. The secret must be complete and contain only numbers. |
| TacNDJavaLib.D_SVAULT_CKS_IEL | Generates the 2 check digits in the pattern of the voter registration number on the token. The secret must contain only numbers and include the check digits. |
|
| maskFlags | Generation options. It can be one of the options in the table below
| Value | Operation |
| 0 | It does not use masks for token generation or secret recovery. |
| TacNDJavaLib.D_SVAULT_F_MASK_TOKEN | It uses masks to generate the token. The mask can be passed when retrieving the token or secret. |
| TacNDJavaLib.D_SVAULT_F_MASK_SECRET | It uses masks to generate the secret. The mask can be passed when retrieving the token or secret. |
|
| MK | Name of the key used for data protection |
| secret | The secret must be a string with numbers only. It should have a minimum size of TacNDJavaLib.D_SVAULT_MIN_TL and a maximum size of TacNDJavaLib.D_SVAULT_MAX_TL. |
- Return
- Exceptions
-
◆ GenSVaultStringToken()
It tokenizes a UTF-8 string, generating a token blob and its respective token.
- Parameters
-
- Return
- Exceptions
-
◆ GetSVaultTokenBlobData()
| String GetSVaultTokenBlobData |
( |
int | op, |
|
|
String | MK, |
|
|
String | mask, |
|
|
byte[] | tokenBlob ) throws TacException |
Retrieves the secret or token of tokenized data using a token blob.
This API also allows the recovery of the masked secret or token.
- Parameters
-
| op | Type of operation. This can be one of the options below.
|
| MK | Name of the key used for data protection. |
| mask | Mask pattern that will be applied to the secret or token, according to the one defined when generating the token blob in GenSVaultToken(). Buffer with a minimum size of TacNDJavaLib.D_SVAULT_MIN_TL and a maximum of TacNDJavaLib.D_SVAULT_MIN_TL containing the mask. It can be an empty string "" so as not to use masking. The mask is a UTF-8 string containing the characters that will be applied to the data to mask it. Pass '\0' in the positions where you want the data to be displayed. See the notes for examples. |
| tokenBlob | Buffer of size TacNDJavaLib.D_SVAULT_TOKEN_BLOB_LEN, generated by the GenSVaultToken() API, containing the blob token. |
- Return
- Return as defined in op
- Exceptions
-
◆ GetSVaultSecret()
| String GetSVaultSecret |
( |
String | MK, |
|
|
String | mask, |
|
|
byte[] | tokenBlob ) throws TacException |
Retrieves the secret of tokenized data using a token blob.
This API also allows the masked secret to be recovered.
- Parameters
-
- Return
- secret
- Exceptions
-
◆ GetSVaultToken()
| String GetSVaultToken |
( |
String | MK, |
|
|
String | mask, |
|
|
byte[] | tokenBlob ) throws TacException |
Retrieves the token of tokenized data using a token blob.
This API also allows the masked token to be recovered.
- Parameters
-
- Return
- token
- Exceptions
-
