Guides
API Reference

Authentication mTLS

Suggest Edits

mTLS is an extension of the TLS (Transport Layer Security) protocol, widely used to ensure secure communications over the internet. While traditional TLS authenticates only the server, allowing the client to verify the server's identity, mTLS takes it a step further by requiring both the client and server to mutually authenticate each other. This is achieved through the exchange of digital certificates during the TLS handshake.

Advantages

  1. Enhanced Security: mTLS provides an additional layer of security by ensuring that both parties in a communication are authenticated.
  2. Mutual Trust: In environments where mutual trust is crucial, such as financial transactions or communications between critical systems, mTLS helps establish a higher level of assurance.

Minimum Requirements

mTLS can be easily integrated into your communication with Fitbank's APIs by following the instructions in this guide and meeting the minimum required conditions:

  1. Have a valid and static IP address: All requests from your institution must originate from an IP address that has been previously provided and registered during your integration process.
  2. Use the endpoint “https://apiv3.fitbank.com.br”: During the integration process, you must choose whether to use mTLS as an additional authentication method. If you opt for mTLS, you should exclusively use this new endpoint.
  3. Create a client certificate and send us the certification chain: To assist you in this task, we have prepared a tutorial that can be requested from your support agent during the integration process (Tutorial: Creating a PKI Infrastructure with a Self-Signed CA Using OpenSSL).

Tutorial:


Creating a PKI Infrastructure with your own CA Using OpenSSL

This tutorial describes how to create a Public Key Infrastructure (PKI) with a self-signed Certificate Authority (CA) and how to generate a client certificate for use with mTLS. We will use OpenSSL, a powerful command-line tool for encryption and certificate management.

Step 1: Initial Setup

Before starting, make sure you have OpenSSL installed. On Linux-based systems, you can install OpenSSL with:

sudo apt-get install openssl

Step 2: Configure the CA Directory

Create a directory for the CA and subdirectories to store certificates, keys, and other required files.

`mkdir -p ~/myCA/{certs,crl,newcerts,private}
chmod 700 ~/myCA/private
touch ~/myCA/index.txt
echo 1000 > ~/myCA/serial`

Step 3: Create the OpenSSL Configuration File

Create a configuration file for the CA (~/myCA/openssl.cnf). Here is a basic example:

[ ca ]  
default_ca = CA_default

[ CA_default ]  
dir = ~/myCA  
certs = $dir/certs  
crl_dir = $dir/crl  
new_certs_dir = $dir/newcerts  
database = $dir/index.txt  
serial = $dir/serial  
RANDFILE = $dir/private/.rand  
private_key = $dir/private/ca.key.pem  
certificate = $dir/certs/ca.cert.pem  
crlnumber = $dir/crlnumber  
crl = $dir/crl.pem  
crl_extensions = crl_ext  
default_crl_days = 30  
default_md = sha256  
name_opt = ca_default  
cert_opt = ca_default  
default_days = 375  
preserve = no  
policy = policy_strict

[ policy_strict ]  
countryName = match  
stateOrProvinceName = match  
organizationName = match  
organizationalUnitName = optional  
commonName = supplied  
emailAddress = optional

[ req ]  
default_bits = 2048  
distinguished_name = req_distinguished_name  
string_mask = utf8only

[ req_distinguished_name ]  
countryName = Country Name (2 letter code)  
stateOrProvinceName = State or Province Name  
localityName = Locality Name  
0.organizationName = Organization Name  
commonName = Common Name  
emailAddress = Email Address

[ v3_ca ]  
subjectKeyIdentifier = hash  
authorityKeyIdentifier = keyid:always,issuer  
basicConstraints = critical, CA:true  
keyUsage = critical, digitalSignature, cRLSign, keyCertSign

[ v3_req ]  
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

[ usr_cert ]  
basicConstraints = CA:FALSE  
nsCertType = client, email  
nsComment = "OpenSSL Generated Client Certificate"  
subjectKeyIdentifier = hash  
authorityKeyIdentifier = keyid,issuer  
keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment  
extendedKeyUsage = clientAuth, emailProtection

Replace the values in the [req_distinguished_name] section with values that identify your institution.

Step 4: Generate the CA Private Key and Certificate

  1. Generate the CA private key:
openssl genrsa -aes256 -out ~/myCA/private/ca.key.pem 4096  
chmod 400 ~/myCA/private/ca.key.pem  
openssl genrsa -aes256 -out ~/myCA/private/ca.key.pem 4096

chmod 400 ~/myCA/private/ca.key.pem

  1. Generate the CA certificate:
openssl req -config ~/myCA/openssl.cnf -key ~/myCA/private/ca.key.pem -new -x509 -days 7300 -sha256 -extensions v3_ca -out ~/myCA/certs/ca.cert.pem  
chmod 444 ~/myCA/certs/ca.cert.pem

Step 5: Generate a Client Key and Certificate

  1. Generate the client’s private key:
openssl genrsa -out ~/myCA/private/client.key.pem 2048  
chmod 400 ~/myCA/private/client.key.pem

❗️

Attention:

The client's private key and certificate password must not be sent to FITBANK under any circumstances


  1. Generate the client's CSR (Certificate Signing Request):
openssl req -config ~/myCA/openssl.cnf -key ~/myCA/private/client.key.pem -new –  
sha256 -out ~/myCA/client.csr.pem

  1. Sign the CSR with the CA to create the client's certificate:
openssl ca -config ~/myCA/openssl.cnf -extensions usr_cert -days 375 -notext -md sha256 -in ~/myCA/client.csr.pem -out ~/myCA/certs/client.cert.pem  
chmod 444 ~/myCA/certs/client.cert.pem

Step 6: Verify the Certificates

Verify the CA certificate:

openssl x509 -noout -text -in ~/myCA/certs/ca.cert.pem

Step 7: Create a Client File in PKCS#12 Format (.pfx)

To simplify the import of the certificate and private key into various applications and devices, you can create a PKCS#12 (.pfx) file.


  1. Create the PKCS#12 (.pfx) file:
openssl pkcs12 -export -out ~/myCA/certs/client.pfx -inkey ~/myCA/private/client.key.pem
-in ~/myCA/certs/client.cert.pem -certfile ~/myCA/certs/ca.cert.pem

Simple certificates, stored in .pem or .crt files, like the one generated in step 5, are usually accompanied by separate private key files (.key). Although these files can be protected by file system permissions, they do not offer built-in encryption and password protection like .pfx files.
A .pfx file combines the digital certificate and the private key into a single file. This simplifies the management and secure distribution of these critical components, reducing the likelihood of accidental loss or separation of the private key and certificate. Additionally, .pfx files are protected by strong encryption. When you create a .pfx file, you can set a password that protects the file's contents. This adds an extra layer of security, as even if the file is intercepted, it cannot be accessed without the correct password."

Step 8: Send the CA's PUBLIC certificate to FITBANK's trust store

For use with mTLS, it is necessary to export the certificate chain (CA and intermediates, if any) so that the client can present this chain to the server during the mTLS handshake process. Since this is a private CA, the institution must send the CA's public certificate to us via the email provided during the integration process.

How to proceed with making the call using mTLS?

The way to make the call will vary depending on the system or programming language chosen to perform the requests. In this sense, it is advisable to first execute the call using Postman to ensure that the solution is working as expected, and then "translate" it to the chosen platform.

❗️

Attention

Fitbank's endpoints only accept connections with TLS 1.2; other connections will be rejected. The client's application must establish only TLS 1.2 connections.


Conclusion

You have successfully created a PKI infrastructure with your own CA and generated a client certificate for use with mTLS. This process ensures that both sides of the communication (client and server) can mutually authenticate, increasing the security of transactions and communications.
Now, you can use these certificates in your mTLS configurations for mutual authentication, protecting your APIs from unauthorized access and ensuring the integrity of communications.

Updated 4 days ago