Descrição detalhada

Operações de tokenização e anonimização de dados.

SVault

As APIs do módulo SVault disponibilizam funcionalidades de tokenização para anonimização e pseudonimização de base de dados que contém informações de identificação pessoal (Personally Identifiable Information – PII). O processo de tokenização é baseado na geração de números randômicos por um DRBG FIPS SP800-90A (homologação NIST CAVP).

Arquitetura

O módulo SVault Dinamo faz a tokenização de uma informação de identificação pessoal (também chamada de secret) gerando um token randômico e um token blob (secret e metadados encriptados).

O token blob pode ser armazenado e utilizado para posterior recuperação do secret, para operações de pseudonimização. Para operações de anonimização o token blob deve ser descartado, não permitindo a recuperação posterior do secret.

O token gerado substitui o secret na base de dados original e pode ter o token blob associado, nos casos de pseudonimização. O token pode ter seu formato (decimal, base62 etc.) e habilitação de geração de dígitos verificadores (no caso de CPF, CNPJ, PAN etc.) especificados no momento da geração.

A proteção dos dados sigilosos é feita utilizando uma chave simétrica protegida dentro do HSM.

A recuperação do secret utilizando o token blob permite que ele seja recuperado em texto claro ou mascarado. O mascaramento é feito internamente ao HSM, evitando que o secret seja manipulado em texto claro pela aplicação.

--- title: Fluxo de codificação de segredos --- sequenceDiagram autonumber participant base as Base de dados participant app as Aplicação participant hsm as HSM Note over hsm: chave app ->> hsm: segredo hsm ->> hsm: codifica hsm ->> app: token (dado pseudomizado)
token blob (segredo encriptado) app ->> base: token
token blob Note over base: token
token blob

--- title: Fluxo de decodificação de tokens blobs --- sequenceDiagram autonumber participant base as Base de dados participant app as Aplicação participant hsm as HSM Note over base: token (dado pseudomizado)
token blob (segredo encriptado) Note over hsm: chave app ->> base: busca token blob base ->> app: token blob app ->> hsm: token blob hsm ->> hsm: decodifica hsm ->> app: segredo

Atenção: Os tokens são gerados de forma randômica e, naturalmente, há a possibilidade de geração de tokens conflitantes. Desta forma, a aplicação deverá fazer o tratamento das colisões, solicitando novamente a geração do token para garantir o armazenamento de tokens únicos.

Operações de tokenização e anonimização de dados. Mais...

Funções
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)

Funções

◆ DSVaultGenToken()

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

#include <dinamo.h>

Faz a tokenização de um dado, gerando um token blob e seu respectivo token.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession(). .
[in]	dwOp	Tipo da operação. Deverá ser 0.
[in]	pbInData	Dados de entrada para a geração do token. Deverá ser utilizada a estrutura SVAULT_GEN_TOKEN.
[out]	pbTokenBlob	Buffer que conterá o token blob. Passar um buffer de tamanho D_SVAULT_TOKEN_BLOB_LEN na entrada. `pdwTokenBlobLen` conterá o tamanho do buffer de saída. O token blob protege o secret e seus metadados. Este buffer deverá ser guardado e utilizado na chamada à DSVaultGetData() para posterior recuperação do secret ou token.
[in,out]	pdwTokenBlobLen	Tamanho de `pbTokenBlob`. Na entrada conterá o tamanho total do buffer `pbTokenBlob` e na saída conterá o tamanho dos dados copiados em `pbTokenBlob`.
[out]	szToken	String de tamanho D_SVAULT_MAX_TL + 1 que conterá o token gerado. Pode ser passado NULL para não recuperar o token gerado. O token poderá ser recuperado novamente utilizando a API DSVaultGetData().
[in]	dwReserved	Reservado para uso futuro (deve ser 0).

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Veja também: DSVaultGetData().

Exemplos: 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>

Recupera o secret ou token um dado tokenizado utilizando um token blob. Esta API também permite a recuperação do secret ou token mascarados.

Parâmetros

[in] hSession Contexto adquirido através da função DOpenSession(). .

[in]

dwOp

Tipo da operação. Poderá ser uma das opções abaixo.

Valor	Significado
D_SVAULT_GET_OP_SECRET	Recupera o secret.
D_SVAULT_GET_OP_TOKEN	Recupera o token.

[in] szMK Nome da chave utilizada para a proteção do dados.

[in] szMask Padrão de máscara que será aplicado ao secret ou token, de acordo com o definido na geração do token blob em DSVaultGenToken(). Buffer com tamanho mínimo de D_SVAULT_MIN_TL e máximo de D_SVAULT_MAX_TL contendo a máscara. Pode ser NULL para não utilizar mascaramento. A máscara é uma string UTF-8 que contém os caracteres que serão aplicados sobre os dados fazendo o mascaramento do mesmo. Passe '\0' nas posições onde queira que o dado seja apresentado. Veja as observações para exemplos.

[in] pbTokenBlob Buffer de tamanho D_SVAULT_TOKEN_BLOB_LEN, gerado pela API DSVaultGenToken(), contendo o token blob.

[in] dwTokenBlobLen Buffer de tamanho máximo de D_SVAULT_TOKEN_BLOB_LEN, gerado pela API DSVaultGenToken(), contendo o token blob.

[out] szData String que conterá o token ou o secret de acordo com o especificado em dwOp. Pode-se utilizar um tamanho de D_SVAULT_MAX_TL + 1 para cobrir todos os cados atuais.

[in,out] pdwDataLen Tamanho da string szData. Deverá conter o tamanho de szData e no retorno da API conterá o tamanho total dos dados copiados.

[in] dwReserved Reservado para uso futuro (deve ser 0).

Retorna: 0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações: Exemplos de uso de máscara. Neste exemplo utilizaremos um secret com valor "123456789".

Utilizando a máscara "***" teremos o seguinte resultado.

"***456789"

Aplicando a máscara "9999" teremos o seguinte resultado.

"999956789"

Aplicando a máscara "***\0\0\0***" teremos o seguinte resultado.

"***456***"

Veja também: DSVaultGenToken().

Exemplos: tokenization.c.