> For the complete documentation index, see [llms.txt](https://ftcoders.first-tech.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ftcoders.first-tech.com/landing-page/modulo-rsa/referencia-da-api-rsa.md).
# Referência da API — RSA
Esta seção descreve os dois endpoints expostos pelo módulo PayShield RSA: `Import` e `Export`. Eles são utilizados sequencialmente para garantir a transferência segura de chaves simétricas .
## Exportar chave sob chave pública RSA
> Traduz uma chave DES, AES ou HMAC de criptografia sob o LMK para criptografia sob uma chave pública RSA.\
> Retorna a chave exportada (criptografada sob a chave pública) em \`retValue\` em formato Hex.\
> \
> Suporta dois modos de padding:\
> \- \*\*PKCS#1 v1.5\*\* (\`padModeId: 1\`): método clássico, não requer \`mgfHashFunction\`\
> \- \*\*OAEP\*\* (\`padModeId: 2\`): método moderno, requer \`mgfHashFunction\`\
> \
> Atualmente apenas \`keyBlockType: 3\` (Unformatted Key Data Block) é suportado.
```json
{"openapi":"3.0.3","info":{"title":"PayShield RSA API","version":"4.1.32"},"tags":[{"name":"RSA","description":"Operações de exportação e importação de chaves RSA/ECC"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"ExportKeyInput":{"type":"object","required":["client_id","keyId","padModeId","publicKey","keyBlockType"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave a ser exportada no banco de dados"},"padModeId":{"type":"integer","enum":[1,2],"description":"Identificador do modo de padding usado na criptografia:\n- `1`: PKCS#1 v1.5 (EME-PKCS1-v1_5)\n- `2`: PKCS#1 v2.2 OAEP (EME-OAEP-ENCODE) — requer `mgfHashFunction`\n"},"mgfHashFunction":{"type":"integer","enum":[1,5,6,7,8],"nullable":true,"description":"Identificador da função hash MGF — obrigatório apenas quando `padModeId: 2` (OAEP):\n- `1`: SHA-1\n- `5`: SHA-224\n- `6`: SHA-256\n- `7`: SHA-384\n- `8`: SHA-512\n"},"publicKey":{"type":"string","description":"Chave pública RSA em formato Key Block Thales (Hex).\nGerada pelo endpoint `Import` deste mesmo serviço.\n"},"keyBlockType":{"type":"integer","enum":[3],"description":"Tipo do Key Data Block:\n- `3`: Unformatted Key Data Block (único valor suportado atualmente)\n"}}},"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retValue":{"type":"string","description":"Valor de retorno — chave exportada/importada em Hex"},"retDescription":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro (Export):\n- `01`: Falha na verificação do MAC\n- `02`: Falha na verificação do check value\n- `03`: Tipo de chave privada inválido / Tipo de codificação de chave pública inválido\n- `04`: Flag de chave privada inválido / Chave pública não conforme com as regras de codificação\n- `05`: Tipo de chave DES/AES inválido\n- `06`: Identificador de criptografia inválido\n- `07`: Identificador de modo de padding inválido\n- `08`: Erro no Key Block HMAC\n- `10`: Erro de paridade na chave DES\n- `34`: Valor de identificador hash HMAC inválido\n- `47`: Algoritmo não licenciado\n- `50`: Chave pública não conforme com as regras de codificação\n- `68`: Comando desabilitado\n- `76`: Erro no comprimento do Key Data Block\n- `81`: Tipo de Key Data Block inválido\n- `83`: Erro no formato do Key Block\n- `84`: Erro no check value do Key Block\n- `85`: Função MGF OAEP inválida\n- `86`: Função hash MGF OAEP inválida\n- `87`: Erro no parâmetro OAEP\n- `88`: Erro OAEP\n- `D3`: Erro na chave / Critérios de equivalência PCI HSM V3 não atendidos\n- `D4`: Chave pública ECC inválida\n"},"retValid":{"type":"boolean"},"retValue":{"type":"string"},"retDescription":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldRsa/Export":{"post":{"tags":["RSA"],"summary":"Exportar chave sob chave pública RSA","description":"Traduz uma chave DES, AES ou HMAC de criptografia sob o LMK para criptografia sob uma chave pública RSA.\nRetorna a chave exportada (criptografada sob a chave pública) em `retValue` em formato Hex.\n\nSuporta dois modos de padding:\n- **PKCS#1 v1.5** (`padModeId: 1`): método clássico, não requer `mgfHashFunction`\n- **OAEP** (`padModeId: 2`): método moderno, requer `mgfHashFunction`\n\nAtualmente apenas `keyBlockType: 3` (Unformatted Key Data Block) é suportado.\n","operationId":"exportKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportKeyInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnSingle"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
***
## Importar chave pública RSA/ECC
> Importa uma chave pública RSA ou ECC gerando um MAC sobre ela.\
> Retorna a chave pública importada com o MAC gerado em \`retValue\` (formato Key Block Thales).\
> \
> O campo \`publicKey\` deve ser a chave pública em formato DER encoded ASN.1 em Hex.\
> O \`publicKeyEncoding\` define o formato de codificação da chave.
```json
{"openapi":"3.0.3","info":{"title":"PayShield RSA API","version":"4.1.32"},"tags":[{"name":"RSA","description":"Operações de exportação e importação de chaves RSA/ECC"}],"servers":[{"url":"https://apivin.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"ImportPublicKeyInput":{"type":"object","required":["client_id","publicKeyEncoding","publicKey"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"publicKeyEncoding":{"type":"integer","enum":[1,2,3],"description":"Regras de codificação da chave pública:\n- `1`: DER encoded ASN.1 RSA Public Key (INTEGER com representação unsigned)\n- `2`: DER encoded ASN.1 RSA Public Key (INTEGER com representação 2's complement)\n- `3`: DER encoded ASN.1 ECC X9.62 format uncompressed key\n"},"publicKey":{"type":"string","description":"Chave pública RSA ou ECC em formato DER encoded ASN.1 em Hex.\nPara RSA: SubjectPublicKeyInfo ou RSAPublicKey.\nPara ECC: X9.62 uncompressed point format.\n"}}},"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retValue":{"type":"string","description":"Valor de retorno — chave exportada/importada em Hex"},"retDescription":{"type":"string","description":"Descrição do resultado"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro (Export):\n- `01`: Falha na verificação do MAC\n- `02`: Falha na verificação do check value\n- `03`: Tipo de chave privada inválido / Tipo de codificação de chave pública inválido\n- `04`: Flag de chave privada inválido / Chave pública não conforme com as regras de codificação\n- `05`: Tipo de chave DES/AES inválido\n- `06`: Identificador de criptografia inválido\n- `07`: Identificador de modo de padding inválido\n- `08`: Erro no Key Block HMAC\n- `10`: Erro de paridade na chave DES\n- `34`: Valor de identificador hash HMAC inválido\n- `47`: Algoritmo não licenciado\n- `50`: Chave pública não conforme com as regras de codificação\n- `68`: Comando desabilitado\n- `76`: Erro no comprimento do Key Data Block\n- `81`: Tipo de Key Data Block inválido\n- `83`: Erro no formato do Key Block\n- `84`: Erro no check value do Key Block\n- `85`: Função MGF OAEP inválida\n- `86`: Função hash MGF OAEP inválida\n- `87`: Erro no parâmetro OAEP\n- `88`: Erro OAEP\n- `D3`: Erro na chave / Critérios de equivalência PCI HSM V3 não atendidos\n- `D4`: Chave pública ECC inválida\n"},"retValid":{"type":"boolean"},"retValue":{"type":"string"},"retDescription":{"type":"string","description":"Descrição do erro"}}}}},"paths":{"/v4/PayShieldRsa/Import":{"post":{"tags":["RSA"],"summary":"Importar chave pública RSA/ECC","description":"Importa uma chave pública RSA ou ECC gerando um MAC sobre ela.\nRetorna a chave pública importada com o MAC gerado em `retValue` (formato Key Block Thales).\n\nO campo `publicKey` deve ser a chave pública em formato DER encoded ASN.1 em Hex.\nO `publicKeyEncoding` define o formato de codificação da chave.\n","operationId":"importKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportPublicKeyInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnSingle"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
***
## The ExportKeyInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield RSA API","version":"4.1.32"},"components":{"schemas":{"ExportKeyInput":{"type":"object","required":["client_id","keyId","padModeId","publicKey","keyBlockType"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave a ser exportada no banco de dados"},"padModeId":{"type":"integer","enum":[1,2],"description":"Identificador do modo de padding usado na criptografia:\n- `1`: PKCS#1 v1.5 (EME-PKCS1-v1_5)\n- `2`: PKCS#1 v2.2 OAEP (EME-OAEP-ENCODE) — requer `mgfHashFunction`\n"},"mgfHashFunction":{"type":"integer","enum":[1,5,6,7,8],"nullable":true,"description":"Identificador da função hash MGF — obrigatório apenas quando `padModeId: 2` (OAEP):\n- `1`: SHA-1\n- `5`: SHA-224\n- `6`: SHA-256\n- `7`: SHA-384\n- `8`: SHA-512\n"},"publicKey":{"type":"string","description":"Chave pública RSA em formato Key Block Thales (Hex).\nGerada pelo endpoint `Import` deste mesmo serviço.\n"},"keyBlockType":{"type":"integer","enum":[3],"description":"Tipo do Key Data Block:\n- `3`: Unformatted Key Data Block (único valor suportado atualmente)\n"}}}}}}
```
## The ImportPublicKeyInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield RSA API","version":"4.1.32"},"components":{"schemas":{"ImportPublicKeyInput":{"type":"object","required":["client_id","publicKeyEncoding","publicKey"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"publicKeyEncoding":{"type":"integer","enum":[1,2,3],"description":"Regras de codificação da chave pública:\n- `1`: DER encoded ASN.1 RSA Public Key (INTEGER com representação unsigned)\n- `2`: DER encoded ASN.1 RSA Public Key (INTEGER com representação 2's complement)\n- `3`: DER encoded ASN.1 ECC X9.62 format uncompressed key\n"},"publicKey":{"type":"string","description":"Chave pública RSA ou ECC em formato DER encoded ASN.1 em Hex.\nPara RSA: SubjectPublicKeyInfo ou RSAPublicKey.\nPara ECC: X9.62 uncompressed point format.\n"}}}}}}
```
## The ReturnSingle object
```json
{"openapi":"3.0.3","info":{"title":"PayShield RSA API","version":"4.1.32"},"components":{"schemas":{"ReturnSingle":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de retorno. 0 = sucesso, outros valores indicam erro"},"retValid":{"type":"boolean","description":"Indica se a operação foi bem-sucedida"},"retValue":{"type":"string","description":"Valor de retorno — chave exportada/importada em Hex"},"retDescription":{"type":"string","description":"Descrição do resultado"}}}}}}
```
## The ReturnError object
```json
{"openapi":"3.0.3","info":{"title":"PayShield RSA API","version":"4.1.32"},"components":{"schemas":{"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Código de erro (Export):\n- `01`: Falha na verificação do MAC\n- `02`: Falha na verificação do check value\n- `03`: Tipo de chave privada inválido / Tipo de codificação de chave pública inválido\n- `04`: Flag de chave privada inválido / Chave pública não conforme com as regras de codificação\n- `05`: Tipo de chave DES/AES inválido\n- `06`: Identificador de criptografia inválido\n- `07`: Identificador de modo de padding inválido\n- `08`: Erro no Key Block HMAC\n- `10`: Erro de paridade na chave DES\n- `34`: Valor de identificador hash HMAC inválido\n- `47`: Algoritmo não licenciado\n- `50`: Chave pública não conforme com as regras de codificação\n- `68`: Comando desabilitado\n- `76`: Erro no comprimento do Key Data Block\n- `81`: Tipo de Key Data Block inválido\n- `83`: Erro no formato do Key Block\n- `84`: Erro no check value do Key Block\n- `85`: Função MGF OAEP inválida\n- `86`: Função hash MGF OAEP inválida\n- `87`: Erro no parâmetro OAEP\n- `88`: Erro OAEP\n- `D3`: Erro na chave / Critérios de equivalência PCI HSM V3 não atendidos\n- `D4`: Chave pública ECC inválida\n"},"retValid":{"type":"boolean"},"retValue":{"type":"string"},"retDescription":{"type":"string","description":"Descrição do erro"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://ftcoders.first-tech.com/landing-page/modulo-rsa/referencia-da-api-rsa.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.