Key Exchange
Signed Request
All information exchange between APIs must use the HTTPS protocol and an asymmetric signature. Our signature implementation model is based on the one used by Amazon, with the main difference being the use of asymmetric keys that add a non-repudiation layer to the communication.
All our APIs only accept HTTPS requests using TLS 2.0
All communication with QI is signed, both requests and responses, meaning there is a parameter in the messages that guarantees their authenticity. To perform such signature, QI uses a standard with asymmetric keys, therefore there are two different keys, one for signing (private key) and one for reading (public key). The signatures follow the JWT standard and the ECDSASHA512 encryption algorithm (We STRONGLY recommend exploring the website https://jwt.io/, where you can validate JWTs and discover libraries to handle these tokens in basically any modern programming language).
The use of this combination of technologies aims to create a secure communication channel that ensures the sent messages could only come from a source that possesses the private key to sign them. For this reason, the public-private key pair needs to be created independently by each party and the private key must be kept secret, not being disclosed to any third party or interested party, not even QI.
Key pair generation (public and private)
- Unix
- Mac OS
- Windows
To generate your private key on a Unix computer, run in your terminal or command line:
$ ssh-keygen -t ecdsa -b 521 -m PEM -f jwtECDSASHA512.key
And from this private key, generate your public key.
$ openssl ec -in jwtECDSASHA512.key -pubout -outform PEM -out jwtECDSASHA512.key.pub
To generate your private key on a Mac OS computer, run in your terminal:
openssl ecparam -name secp521r1 -genkey -noout -out ec512-private.pem
And from this private key, generate your public key.
openssl ec -in ec512-private.pem -pubout -out ec512-public.pem
To generate your key pair (private and public) on a Windows computer, you will need the ssh-keygen and openssl tools in PowerShell or GitBash.
Run the command below to create your private key file (jwtECDSASHA512.key).
ssh-keygen -t ecdsa -b 521 -m PEM -f jwtECDSASHA512.key
And from this private key, generate your public key (jwtECDSASHA512.key.pub).
openssl ec -in jwtECDSASHA512.key -pubout -outform PEM -out jwtECDSASHA512.key.pub
To view the key in notepad:
notepad jwtECDSASHA512.key.pub
To view the key in the terminal:
cat jwtECDSASHA512.key.pub
If you add an encryption password to your private key and want to view it, you will need to decrypt it with the command below and your password:
openssl ec -in jwtECDSASHA512.key -out chave_descriptografada.pem
Generating QI Tech's public and integration keys
As part of request and response signing, you need to provide us with your public key and we will return a public key to you, so message reading can be done on both ends of the communication. Additionally, we provide a unique UUID-type key that represents your API integration within our system.
To receive both keys, log in to the QI Tech platform in the sandbox environment. Click on "My profile", located in the bottom left corner of the menu, then go to the Integration tab located at the top of the page. Insert your public key in the first field (Client public key) and click the "SAVE KEY" button. Once this is done, QI Tech's public and integration keys will be available in the 'Integration Key' and 'QI Tech Public Key' fields.
If necessary, you can check and change your key after the first integration through the same path "My Profile" > "Integration" by repeating the process above.
Never share your private key, it is for your exclusive use and sharing it instead of the public key compromises the security of your requests. Additionally, do not share your QI Tech public keys and integration key as they are your means of communication with our APIs.