Detailed description

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.

Functions
SVaultGenTokenResponse	GenSVaultToken (UInt32 Op, DinamoApi.SVAULT_GEN_TOKEN TokenInfo, UInt32 Reserved)
	It tokenizes a piece of data, generating a token blob and its respective token.

SVaultGenTokenResponse	GenSVaultToken (DinamoApi.SVAULT_GEN_TOKEN TokenInfo)
	It tokenizes a piece of data, generating a token blob and its respective token.

SVaultGenTokenResponse	GenSVaultDigitToken (byte CKS, byte MaskFlags, string MK, string Secret)
	It tokenizes digits, generating a token blob and its respective token.

SVaultGenTokenResponse	GenSVaultStringToken (byte MaskFlags, string MK, string Secret)
	It tokenizes a UTF-8 string, generating a token blob and its respective token.

string	GetSVaultTokenBlobData (UInt32 Op, string MK, string Mask, byte[] TokenBlob)
	Retrieves the secret or token of tokenized data using a token blob. This API also allows the recovery of masked secret or token.

string	GetSVaultSecret (string MK, string Mask, byte[] TokenBlob)
	Retrieves the secret of tokenized data using a token blob. This API also allows the retrieval of the masked secret.

string	GetSVaultToken (string MK, string Mask, byte[] TokenBlob)
	Retrieves the token of tokenized data using a token blob. This API also allows masked tokens to be retrieved.

Functions

◆ GenSVaultToken() [1/2]

SVaultGenTokenResponse GenSVaultToken	(	UInt32	Op,
		DinamoApi::SVAULT_GEN_TOKEN	TokenInfo,
		UInt32	Reserved
	)

inline

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: Token blob and token.

Exceptions

DinamoException Throws exception in case of error.

◆ GenSVaultToken() [2/2]

SVaultGenTokenResponse GenSVaultToken ( DinamoApi::SVAULT_GEN_TOKEN TokenInfo )

inline

It tokenizes a piece of data, generating a token blob and its respective token.

Parameters

TokenInfo Details of the tokenization operation.

Return: Token blob and token.

Exceptions

DinamoException Throws exception in case of error.

◆ GenSVaultDigitToken()

SVaultGenTokenResponse GenSVaultDigitToken	(	byte	CKS,
		byte	MaskFlags,
		string	MK,
		string	Secret
	)

inline

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
DinamoApi.D_SVAULT_CKS_NULL	It doesn't generate a checksum. It only generates the token.
DinamoApi.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.
DinamoApi.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.
DinamoApi.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.
DinamoApi.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.
DinamoApi.D_SVAULT_F_MASK_TOKEN	It uses masks to generate the token. The mask can be passed when recovering the token or secret.
DinamoApi.D_SVAULT_F_MASK_SECRET	It uses masks to generate the secret. The mask can be passed when recovering the token or secret.

MK Name of the key used for data protection.

Secret The secret must be a UTF-8 string with numbers only. It must have a minimum length of DinamoApi.D_SVAULT_MIN_TL code points and a maximum of DinamoApi.D_SVAULT_MAX_TL encoding units.

Return: Token blob and token.

Exceptions

DinamoException Throws exception in case of error.

Examples: tokenization.cs.

◆ GenSVaultStringToken()

SVaultGenTokenResponse GenSVaultStringToken	(	byte	MaskFlags,
		string	MK,
		string	Secret
	)

inline

It tokenizes a UTF-8 string, generating a token blob and its respective token.

Parameters

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.
DinamoApi.D_SVAULT_F_MASK_TOKEN	It uses masks to generate the token. The mask can be passed when recovering the token or secret.
DinamoApi.D_SVAULT_F_MASK_SECRET	It uses masks to generate the secret. The mask can be passed when recovering the token or secret.

MK Name of the key used for data protection.

Secret The secret must be a UTF-8 string with numbers only. It must have a minimum length of DinamoApi.D_SVAULT_MIN_TL code points and a maximum of DinamoApi.D_SVAULT_MAX_TL encoding units.

Return: Token blob and token.

Exceptions

DinamoException Throws exception in case of error.

Examples: tokenization.cs.

◆ GetSVaultTokenBlobData()

string GetSVaultTokenBlobData	(	UInt32	Op,
		string	MK,
		string	Mask,
		byte[]	TokenBlob
	)

inline

Retrieves the secret or token of tokenized data using a token blob. This API also allows the recovery of masked secret or token.

Parameters

Op

Type of operation. This can be one of the options below.

Value	Meaning
DinamoApi.D_SVAULT_GET_OP_SECRET	Get the secret back.
DinamoApi.D_SVAULT_GET_OP_TOKEN	Recover the token.

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 maximum size of DinamoApi.D_SVAULT_MAX_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 on GetSVaultTokenBlobData() for examples.

TokenBlob Buffer of size DinamoApi.D_SVAULT_TOKEN_BLOB_LEN, generated by the GenSVaultToken() API, containing the blob token.

Return: Return as defined in op.

Exceptions

DinamoException Throws exception in case of error.

Notes

Examples of mask use. In this example we will use a secret with the value "123456789". Using the mask "***" will give us the following result.

"***456789"

Applying the "9999" mask will give us the following result.

"999956789"

Applying the "***\0\0\0***" mask will give the following result.

"***456***"

◆ GetSVaultSecret()

string GetSVaultSecret	(	string	MK,
		string	Mask,
		byte[]	TokenBlob
	)

inline

Retrieves the secret of tokenized data using a token blob. This API also allows the recovery of the masked secret.

Parameters

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 maximum size of DinamoApi.D_SVAULT_MAX_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 on GetSVaultTokenBlobData() for examples.
TokenBlob	Buffer of size DinamoApi.D_SVAULT_TOKEN_BLOB_LEN, generated by the GenSVaultToken() API, containing the blob token.

Return: secret

Exceptions

DinamoException Throws exception in case of error.

Examples: tokenization.cs.

◆ GetSVaultToken()

string GetSVaultToken	(	string	MK,
		string	Mask,
		byte[]	TokenBlob
	)

inline

Retrieves the token of tokenized data using a token blob. This API also allows masked tokens to be retrieved.

Parameters

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 maximum size of DinamoApi.D_SVAULT_MAX_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 on GetSVaultTokenBlobData() for examples.
TokenBlob	Buffer of size DinamoApi.D_SVAULT_TOKEN_BLOB_LEN, generated by the GenSVaultToken() API, containing the blob token.

Return: token

Exceptions

DinamoException Throws exception in case of error.