All parties communicating through DAX need an Amido/DAX issued certificate to be able to talk and interact with the platform. This is true for both REST API calls and service bus connections. In both theses cases transport is encrypted using TLS and all messages are cryptographically signed.
To retreive a certificate from Amido/DAX a relationship must be formed in the term of a legal binding contract between the 3rd party and Amido. Upon signing this contract a certificate may be issued. This document describes that process and its usage in general terms.
Getting a certificate¶
Key pair generation¶
All parties need to create their own RSA private/public key pair. The private key must be stored in a safe manner and is the responsibility of the party to keep secret and safe. DAX and Amido normally has no knowledge of this key; it’s strictly private.
In case of Alliera all Alliera installations has its own private/public key pair generated upon installation and is stored in Alliera’s database using Microsoft strong encryption connected to the user account running Alliera. If the account password running Alliera is lost the key can never be recovered but needs to be regenerated. As stated above Amido normally has no record of this key and we will never ask for it.
Example key generation¶
By using the software openssl it’s possible to create your own private/public key pair.
openssl genrsa -out private.pem 2048
Note! If you’re using openssl version 3 or later you need to add a traditional flag like below:
openssl genrsa -traditional -out private.pem 2048
This will generate a 2048 bit RSA private key and store it in a file called
private.pem. It’s a simple text file and it will look something like this:
----BEGIN RSA PRIVATE KEY----- MIIEogIBAAKCAQEAwSlVS+zEyiIzthzyUCRyKiceRWf+dKp6Fd/GTxuBOnimXwuc bF+KFR8lSC5kXH5arxImRVJG6JT85NY2hxcGex0ZrHmVAQHSljywFoYFlhCdJiQr H2c5flAHubkgWni8QNwhWomQlpLpNwjQFGYUYn+FVM...... ... -----END RSA PRIVATE KEY-----
To extract your public key from your private key you need to run the following command:
openssl rsa -in private.pem -outform PEM -pubout -out public.pem
The output will be your public key and just as the privat key it is a simple textfile that looks like this:
-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwSlVS+zEyiIzthzyUCRy KiceRWf+dKp6Fd/GTxuBOnimXwucbF+KFR8lSC5kXH5arxImRVJG6JT85NY2hxcG ex0ZrHmVAQHSljywFoYFlhCdJiQrH2c5flAHubkgWni8QNwhWomQlpLpNwjQFGYU ... -----END PUBLIC KEY-----
Certificate Signing Request¶
To get a certificate from Amido/DAX a Certificate Signing Request need to be created and signed with the private key. The CSR is then sent to Amido for review and if it fulfills all technical and contractual obligations set a DAX certificate will be issued. This certificate is stored within DAX for future validation of all signed messages.
The issued certificate can be revoked by Amido at any time or upon request by the owning party if the key has been deemed compromised.
If the private key is lost, all communication with DAX will cease since DAX will not accept unsigned messages. The process of generating a new key pair, CSR and certificate must be restarted.
Example CSR generation¶
In order to create a CSR you need access to your private key as described above.
Copy the below content to the file
request.conf and update the values above the line with your provided values before saving.
# Your Partner ID as provided by Amido. PARTNERID=8bd953d6-52ee-4c8e-a953-217abd16fbd1 # Your Instance ID as provided by Amido. INSTANCEID=a2ff6de6-2ec6-4677-9913-942bfc1cd588 # Your country in two letter code. COUNTRY=SE # your city or company location. LOCALIZATION=Gothenburg # Your partner name/organization that you've configured or that was provided by Amido. PARTNERNAME=Partner Name # The name of the part of your partner's organization that will own the certificate. SECTION=IS/IT # ----------------------------------------------- # --- No modifications needed below this line --- # ----------------------------------------------- [ dn ] C = $COUNTRY L = $LOCALIZATION O = $PARTNERNAME OU = $SECTION CN = $INSTANCEID.instance.prod.dax.amido.io [ req ] distinguished_name = dn req_extensions = req_ext prompt = no [ req_ext ] subjectAltName = DNS:$INSTANCEID.instance.prod.dax.amido.io,DNS:$PARTNERID.partner.prod.dax.amido.io
With this configuration file you can create a valid CSR with the following command:
openssl req -new -config request.conf -key private.pem -out request.csr
A certificate signing request has now been created in PEM format in the file
request.csr. You can check the content of the request by issuing:
openssl req -text -noout -verify -in request.csr
It will look something like this:
verify OK Certificate Request: Data: Version: 1 (0x0) Subject: C = SE, L = Gothenburg, O = Partner Name, OU = IS/IT, CN = a2ff6de6-2ec6-4677-9913-942bfc1cd588.instance.prod.dax.amido.io Subject Public Key Info: Public Key Algorithm: rsaEncryption RSA Public-Key: (2048 bit) ... Requested Extensions: X509v3 Subject Alternative Name: DNS:a2ff6de6-2ec6-4677-9913-942bfc1cd588.instance.prod.dax.amido.io, DNS:8bd953d6-52ee-4c8e-a953-217abd16fbd1.partner.prod.dax.amido.io
If you check the actual content of the
request.csr file it looks like this:
-----BEGIN CERTIFICATE REQUEST----- MIIDBTCCAe0CAQAwfTELMAkGA1UEBhMCU0UxEzARBgNVBAcMCkdvdGhlbmJ1cmcx FzAVBgNVBAoMDjxQQVJUTkVSIE5BTUU+MQ4wDAYDVQQLDAVJUy1JVDEwMC4GA1UE ... dKLpGhQTJS575bXscg3BiKUQvPAjWKZPcBD6HKJ96Aqf0VxxYKxYuvlTRN+Bw4Qg De3DpfmILRuQw/Z+/iaz2HNQaz3LWwFC4H85fGbg2MmQ/JyzfnPYXqJ+ltNN85St TfXuZPwURQqQ -----END CERTIFICATE REQUEST-----
The contents of this file need to be provided to Amido Customer Success in order to get your certificate.
The private key is used to cryptographically sign all messages sent through the DAX platform. DAX will not accept a message that has not been signed and it will not accept a message that it can’t cryptographically verify through its own certificate store connected to the partner and instance sending the message.
All messages are also time stamped before signing to prohibit and detect replay attempts.
One might think that since all communication between a party and DAX is encrypted using SSL/TLS this is unnecessary but by signing the message we can prove and keep a record of who actually sent the message and we can verify and prove that it’s the original message sent and that it has not been tampered with or modified in any way, not even by ourselves.
The REST API is protected by a username and password. The username and password is used to request a security token from DAX which for a short time can be used in subsequent requests before it expires.
Together with this token the party’s private key must be used to sign the request. Signing the requests makes it possible for DAX to verify who the sender is and that the message has not been tampered with before processing.
In an Alliera-to-Alliera scenario there are three parties involved:
- Sending Alliera
- Receiving Alliera
All three parties has their own set of private/public keys in order to sign and verify messages going through the DAX platform.
An Alliera will never, ever, talk directly to any other entity but DAX. It’s not possible for anyone to circumvent DAX since a receiving Alliera will never accept a message not signed by DAX.
If the sending Alliera wants to send a message to the receiving Alliera this is the series of events taking place:
- The sending Alliera creates a message that it wants to send. It knows about the receiving Alliera just as a “remote entity” which it cannot communicate directly with but it needs to send the message through DAX.
- The sending Alliera signs the message and asks DAX to send it to the remote Alliera.
- DAX receives the message, verifies its origin in terms of cryptographically checking the signature. If the signature is valid it sends the message on for processing.
- The process handling the message checks DAX internal contracts to check that the sending Alliera and receiving Alliera are allowed to talk to each other. If not, the message is discarded immediately.
- DAX further checks the
operationof the message. Is it a query for information or a command to perform an action? All queries, commands and requests need to be specifically allowed by the receiving Alliera and all these operations are determined by the contract and its clauses. If no explicit clause is found that allows the operation, the message will be discarded. Also there might be limits in the contract determining the extent possible by the request/command.
- The message has been deemed correct and the contract is valid. DAX now repackages the message, signs it with DAX private key and sends it to the receiving Alliera.
- A permanent record, event, is created with the technical content of the request being handled. This event is recorded and kept by DAX.
- The receiving Alliera verifies the message and performs the operation requested.
- If the operation requires some kind of response, the response is created, signed and sent back to DAX from the receiving Alliera.
- DAX verifies the signature of the receiving Alliera’s response and discards the message if the signature fails verification.
- Another permanent record, event, is created with the technical contents of this response. This event is also recorded and kept by DAX.
- DAX repackages the response into a response back to the sending Alliera. The response is signed by DAX.
- The sending Alliera verifies the signature in the message from DAX, pairs it with its own requests and returns the response coming from the receiving Alliera.
Through this chain a correlation ID is created which links all of this data together. In essence a record is kept of the complete transaction from request to response and can be called up for review if needed.
If a 3rd party using the REST API wants to communicate with an Alliera, DAX follows the exact same order of events as described above. The request is verified in the same way and recorded in the same way.
Alliera will limit access¶
All operations performed by a 3rd party and/or other Alliera needs to be verified as described above. But also, the resources such as access groups, card owners and cards within Alliera that a remote party actually gains access to is determined by the Alliera owning the information. By default no information is available but must explicitly be given access by the operators of Alliera. This further limits any kind of data a remote party can gain access to beside the checks DAX does with regards to contracts and clauses.
For more reading¶
- Public Key Cryptography (PKC) - https://en.wikipedia.org/wiki/Public-key_cryptography
- PKI Bootcamp - https://www.youtube.com/playlist?list=PLDp2gaPHHZK-mnKi3Zy_-hRjqLHh5PaAv