# Index

1. [When to use digital certificates?](#quando-integrar)
2. [How secure is it?](#seguranca)
3. [Using certificates with the Infosimples API](#integracao)
4. [Obtaining the encrypted certificate without coding](#gerar-sem-codigo)

## [When to use digital certificates?](#quando-integrar)
Some of the services accept PKCS12 digital certificates (largely known as **A1 certificates** in Brazil) as input parameters. The certificates are often used to authenticate users in some websites.

If you need to use an API that uses a certificate, please read the rest of this page.


## [How secure is it?](#seguranca)
This approach makes your integration significantly secure. Highlights:

- The communication between your application and the API takes place only over HTTPS (TLS-encrypted connection), promoting integrity (data cannot be modified during transmission) and ensuring data can only be read by your application and the API;
- The digital certificate and its password have to be encrypted with AES (256-bit key, GCM mode) before being transmitted over HTTPS, which adds another layer of security to the integration;
- The digital certificate and its password are decrypted in-memory by the API and are completely purged after being used;
- Infosimples never persists the digital certificate or its password, either raw or encrypted, in databases or other data storage structures;
- Infosimples only stores MD5 hashes of the digital certificate and its password in order to validate reception was successful.


## [Using certificates with the Infosimples API](#integracao)
To develop an integration with the APIs that use A1 PKCS12 digital certificates, you need to:

1. Read the certificate file as a binary (usually it is a file with the `.pfx` extension).
2. Convert the read file to `base64`
3. Encrypt the `base64` string using AES-256, according to the [encryption instructions](https://api.infosimples.com/consultas/docs/en/criptografia). The result string will be used in the parameters named `pkcs12_cert`.
4. Encrypt the certificate's password string using AES-256, according to the [encryption instructions](https://api.infosimples.com/consultas/docs/en/criptografia). The result string will be used in the parameters named `pkcs12_pass`.

The **encryption key** , used in the process above, is linked to your account and can be found in the [account settings](https://api.infosimples.com/administracao/conta#chave-criptografia).

The digital certificate parameters are:

| Parameter   | Description                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pkcs12_cert | Binary data of the digital certificate file (A1), encoded in Base64 and then encrypted according to the [encryption instructions](https://api.infosimples.com/consultas/docs/en/criptografia). |
| pkcs12_pass | The digital certificate's password, encrypted according to the [encryption instructions](https://api.infosimples.com/consultas/docs/en/criptografia).                                          |

You can test your certificates on the following free API [Infosimples / Certificado Digital (A1/A3)](https://api.infosimples.com/consultas/docs/en/infosimples/certificado).

### Code examples

> The code examples below are based on the [AesBridge](https://github.com/mervick/aes-bridge) project.

#### Encrypting `pkcs12_cert`

#### Python
```python
# Tested with: Python 3.10.19, Python 3.14.0
# pip install aes-bridge
import aes_bridge
import base64

cert_base64 = base64.b64encode(open('path/to/file', 'rb').read()).decode()
criptogram = aes_bridge.encrypt(cert_base64, 'ENCRYPTION_KEY').decode("ascii").replace("+", "-").replace("/", "_").replace("=", "")
```


#### Encrypting `pkcs12_pass`

#### Python
```python
# Tested with: Python 3.10.19, Python 3.14.0
# pip install aes-bridge
import aes_bridge

criptogram = aes_bridge.encrypt("CERTIFICATE_PASSWORD", "ENCRYPTION_KEY",).decode("ascii").replace("+", "-").replace("/", "_").replace("=", "")
```



## [Obtaining the encrypted certificate without coding](#gerar-sem-codigo)
Alternatively, you can use the tool in https://api.infosimples.com/consultas/docs/en/certificados.html to generate the cryptograms manually, without coding. Once generated, you can copy them to the fields `pkcs12_cert` and `pkcs12_pass` in the API.

Note that the files and data entered in the tool are not sent to Infosimples or anywhere else. The data is processed only inside your browser.


## We're here to help
Do you still need to figure something out? Reach us at [suporte@infosimples.com.br](mailto:suporte@infosimples.com.br) and our highly qualified support team will be happy to help.