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 module Dinamo tokenizes personally identifiable information (also called secret) by generating a random token and a token blob(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.

Data tokenization and anonymization operations. More...

Functions
int AAP_API	DSVaultGenToken (HSESSIONCTX hSession, DWORD dwOp, BYTE pbInData, BYTE pbTokenBlob, DWORD pdwTokenBlobLen, char szToken, DWORD dwReserved)

int AAP_API	DSVaultGetData (HSESSIONCTX hSession, DWORD dwOp, const char szMK, const char szMask, BYTE pbTokenBlob, DWORD dwTokenBlobLen, char szData, DWORD *pdwDataLen, DWORD dwReserved)

Functions

◆ DSVaultGenToken()

int AAP_API DSVaultGenToken	(	HSESSIONCTX	hSession,
		DWORD	dwOp,
		BYTE *	pbInData,
		BYTE *	pbTokenBlob,
		DWORD *	pdwTokenBlobLen,
		char *	szToken,
		DWORD	dwReserved )

#include <dinamo.h>

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

Parameters

[in]	hSession	Context acquired through the DOpenSession() function. .
[in]	dwOp	Type of operation. Must be 0.
[in]	pbInData	Input data for token generation. The SVAULT_GEN_TOKEN structure must be used.
[out]	pbTokenBlob	Buffer that will contain the token blob. Passing a buffer size D_SVAULT_TOKEN_BLOB_LEN at the entrance. `pdwTokenBlobLen` will contain the size of the output buffer. O token blob protects the secret and its metadata. This buffer must be saved and used when calling DSVaultGetData() for later recovery of the secret or token.
[in,out]	pdwTokenBlobLen	Size of `pbTokenBlob`. The entry contains the total size of the buffer `pbTokenBlob` and the output will contain the size of the copied data in `pbTokenBlob`.
[out]	szToken	String of length D_SVAULT_MAX_TL + 1 that will contain the generated token. NULL can be passed to not retrieve the generated token. The token can be retrieved again using the DSVaultGetData() API.
[in]	dwReserved	Reserved for future use (must be 0).

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

See also: DSVaultGetData().

Examples: tokenization.c.

◆ DSVaultGetData()

int AAP_API DSVaultGetData	(	HSESSIONCTX	hSession,
		DWORD	dwOp,
		const char *	szMK,
		const char *	szMask,
		BYTE *	pbTokenBlob,
		DWORD	dwTokenBlobLen,
		char *	szData,
		DWORD *	pdwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

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

Parameters

[in] hSession Context acquired through the DOpenSession() function. .

[in]

dwOp

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

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

[in] szMK Name of the key used for data protection.

[in] szMask Mask pattern that will be applied to the secret or token, according to the one defined when generating the token blob in DSVaultGenToken(). Buffer with a minimum size of D_SVAULT_MIN_TL and a maximum of D_SVAULT_MAX_TL containing the mask. It can be NULL 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.

[in] pbTokenBlob Buffer of size D_SVAULT_TOKEN_BLOB_LEN, generated by the DSVaultGenToken() API, containing the token blob.

[in] dwTokenBlobLen Maximum size buffer of D_SVAULT_TOKEN_BLOB_LEN, generated by the DSVaultGenToken() API, containing the token blob.

[out] szData String that will contain the token or secret as specified in dwOp. You can use a size of D_SVAULT_MAX_TL + 1 to cover all current data.

[in,out] pdwDataLen String size szData. It should contain the size of szData and the return from the API will contain the total size of the copied data.

[in] dwReserved Reserved for future use (must be 0).

Return: 0 (ZERO) if the function is successful.
See the Return Codes section for other values.

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***"

See also: DSVaultGenToken().

Examples: tokenization.c.