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.
|
| SVaultGenTokenResponse | GenSVaultToken (UInt32 Op, DinamoApi.SVAULT_GEN_TOKEN TokenInfo, UInt32 Reserved) |
| | Faz a tokenização de um dado, gerando um token blob e seu respectivo token.
|
| |
| SVaultGenTokenResponse | GenSVaultToken (DinamoApi.SVAULT_GEN_TOKEN TokenInfo) |
| | Faz a tokenização de um dado, gerando um token blob e seu respectivo token.
|
| |
| SVaultGenTokenResponse | GenSVaultDigitToken (byte CKS, byte MaskFlags, string MK, string Secret) |
| | Faz a tokenização de dígitos, gerando um token blob e seu respectivo token.
|
| |
| SVaultGenTokenResponse | GenSVaultStringToken (byte MaskFlags, string MK, string Secret) |
| | Faz a tokenização de uma string UTF-8, gerando um token blob e seu respectivo token.
|
| |
| string | GetSVaultTokenBlobData (UInt32 Op, string MK, string Mask, byte[] TokenBlob) |
| | 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.
|
| |
| string | GetSVaultSecret (string MK, string Mask, byte[] TokenBlob) |
| | Recupera o secret um dado tokenizado utilizando um token blob. Esta API também permite a recuperação do secret mascarado.
|
| |
| string | GetSVaultToken (string MK, string Mask, byte[] TokenBlob) |
| | Recupera o token um dado tokenizado utilizando um token blob. Esta API também permite a recuperação do token mascarado.
|
| |
◆ GenSVaultToken() [1/2]
Faz a tokenização de um dado, gerando um token blob e seu respectivo token.
- Parâmetros
-
| Op | Tipo da operação. Deverá ser 0. |
| TokenInfo | Detalhes da operação de tokenização. |
| Reserved | Reservado para uso futuro (deve ser 0). |
- Retorna
- Token blob e token.
- Exceções
-
◆ GenSVaultToken() [2/2]
Faz a tokenização de um dado, gerando um token blob e seu respectivo token.
- Parâmetros
-
| TokenInfo | Detalhes da operação de tokenização. |
- Retorna
- Token blob e token.
- Exceções
-
◆ GenSVaultDigitToken()
Faz a tokenização de dígitos, gerando um token blob e seu respectivo token.
- Parâmetros
-
| CKS | Define o tipo de checksum para a geração de tokens. Pode ser uma das opções da tabela abaixo
| Valor | Operação |
| DinamoApi.D_SVAULT_CKS_NULL | Não faz geração de checksum. Apenas gera o token. |
| DinamoApi.D_SVAULT_CKS_CPF | Gera os 2 dígitos verificadores no padrão CPF (Cadastro de Pessoas Físicas) no token. O secret deverá conter apenas números e incluir os dígitos verificadores. |
| DinamoApi.D_SVAULT_CKS_CNPJ | Gera os 2 dígitos verificadores no padrão CNPJ (Cadastro Nacional da Pessoa Jurídica) no token. O secret deverá conter apenas números e incluir os dígitos verificadores. |
| DinamoApi.D_SVAULT_CKS_PAN | Gera um PAN (Primary Account Number) com o dígito verificador válido no token. O secret deverá ser completo e conter apenas números. |
| DinamoApi.D_SVAULT_CKS_IEL | Gera os 2 dígitos verificadores no padrão do número do título de eleitor no token. O secret deverá conter apenas números e incluir os dígitos verificadores. |
|
| MaskFlags | Opções de geração. Pode ser uma das opções da tabela abaixo
| Valor | Operação |
| 0 | Não utiliza máscaras para geração do token ou recuperação do secret. |
| DinamoApi.D_SVAULT_F_MASK_TOKEN | Utiliza máscaras para geração do token. A máscara poderá ser passada ao recupear o token ou secret. |
| DinamoApi.D_SVAULT_F_MASK_SECRET | Utiliza máscaras para geração do secret. A máscara poderá ser passada ao recupear o token ou secret. |
|
| MK | Nome da chave utilizada para a proteção do dados. |
| Secret | O secret que deverá ser uma string UTF-8 apenas com números. Deverá ter tamanho mínimo de DinamoApi.D_SVAULT_MIN_TL code points e máximo de DinamoApi.D_SVAULT_MAX_TL encoding units. |
- Retorna
- Token blob e token.
- Exceções
-
- Exemplos
- tokenization.cs.
◆ GenSVaultStringToken()
Faz a tokenização de uma string UTF-8, gerando um token blob e seu respectivo token.
- Parâmetros
-
| MaskFlags | Opções de geração. Pode ser uma das opções da tabela abaixo
| Valor | Operação |
| 0 | Não utiliza máscaras para geração do token ou recuperação do secret. |
| DinamoApi.D_SVAULT_F_MASK_TOKEN | Utiliza máscaras para geração do token. A máscara poderá ser passada ao recupear o token ou secret. |
| DinamoApi.D_SVAULT_F_MASK_SECRET | Utiliza máscaras para geração do secret. A máscara poderá ser passada ao recupear o token ou secret. |
|
| MK | Nome da chave utilizada para a proteção do dados. |
| Secret | O secret que deverá ser uma string UTF-8 apenas com números. Deverá ter tamanho mínimo de DinamoApi.D_SVAULT_MIN_TL code points e máximo de DinamoApi.D_SVAULT_MAX_TL encoding units. |
- Retorna
- Token blob e token.
- Exceções
-
- Exemplos
- tokenization.cs.
◆ GetSVaultTokenBlobData()
| string GetSVaultTokenBlobData |
( |
UInt32 | Op, |
|
|
string | MK, |
|
|
string | Mask, |
|
|
byte[] | TokenBlob ) |
|
inline |
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
-
| Op | Tipo da operação. Poderá ser uma das opções abaixo.
|
| MK | Nome da chave utilizada para a proteção do dados. |
| Mask | Padrão de máscara que será aplicado ao secret ou token, de acordo com o definido na geração do token blob em GenSVaultToken(). Buffer com tamanho máximo de DinamoApi.D_SVAULT_MAX_TL contendo a máscara. Pode ser string vazia "" 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 de GetSVaultTokenBlobData() para exemplos. |
| TokenBlob | Buffer de tamanho DinamoApi.D_SVAULT_TOKEN_BLOB_LEN, gerado pela API GenSVaultToken(), contendo o token blob. |
- Retorna
- Retorno de acordo com o definido em op.
- Exceções
-
Exemplos de uso de máscara. Neste exemplo utilizaremos um secret com valor "123456789". Utilizando a máscara "***" teremos o seguinte resultado.
Aplicando a máscara "9999" teremos o seguinte resultado.
Aplicando a máscara "***\0\0\0***" teremos o seguinte resultado.
◆ GetSVaultSecret()
| string GetSVaultSecret |
( |
string | MK, |
|
|
string | Mask, |
|
|
byte[] | TokenBlob ) |
|
inline |
Recupera o secret um dado tokenizado utilizando um token blob. Esta API também permite a recuperação do secret mascarado.
- Parâmetros
-
| MK | Nome da chave utilizada para a proteção do dados. |
| Mask | Padrão de máscara que será aplicado ao secret ou token, de acordo com o definido na geração do token blob em GenSVaultToken(). Buffer com tamanho máximo de DinamoApi.D_SVAULT_MAX_TL contendo a máscara. Pode ser string vazia "" 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 de GetSVaultTokenBlobData() para exemplos. |
| TokenBlob | Buffer de tamanho DinamoApi.D_SVAULT_TOKEN_BLOB_LEN, gerado pela API GenSVaultToken(), contendo o token blob. |
- Retorna
- secret
- Exceções
-
- Exemplos
- tokenization.cs.
◆ GetSVaultToken()
| string GetSVaultToken |
( |
string | MK, |
|
|
string | Mask, |
|
|
byte[] | TokenBlob ) |
|
inline |
Recupera o token um dado tokenizado utilizando um token blob. Esta API também permite a recuperação do token mascarado.
- Parâmetros
-
| MK | Nome da chave utilizada para a proteção do dados. |
| Mask | Padrão de máscara que será aplicado ao secret ou token, de acordo com o definido na geração do token blob em GenSVaultToken(). Buffer com tamanho máximo de DinamoApi.D_SVAULT_MAX_TL contendo a máscara. Pode ser string vazia "" 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 de GetSVaultTokenBlobData() para exemplos. |
| TokenBlob | Buffer de tamanho DinamoApi.D_SVAULT_TOKEN_BLOB_LEN, gerado pela API GenSVaultToken(), contendo o token blob. |
- Retorna
- token
- Exceções
-
