BankAPI

What is it?

BankAPI is a secure decentralized messaging system to send files/messages between banks and other types of financial institutions.

There is a reference implementation of the protocol which can be used off-the-shelf, which is production grade quality and is not only for testing and demonstration, although it fulfils those two roles as well.

The BankAPI protocol relies on OpenPGP (RFC 4880) + SHA512 + HTTPS. That's it, there is nothing more to it.

BankAPI is only a transmission protocol, and makes no assumptions of what kind of messages or file types banks will want to transfer.

Key exchange

Protocol design

The protocol imposes certain restrictions on the details and choices of algorithms used for generating the OpenPGP messages. The terminology used here conforms to the one specified in RFC2119. The details specific to OpenPGP are documented in RFC4880.

All OpenPGP messages MUST be symmetrically encrypted messages, where the session key is public-key encrypted. The session key packet MUST contain the Key ID of the key used to encrypt the message. All messages MUST contain a signature packet. Implementations MAY choose to generate one-pass signatures.
All parties MUST use a key length of at least 2048 bits for their RSA keys. Implementations SHOULD accept key sizes of 2048, 3072 and 4096 bits. Using 4096-bit keys is RECOMMENDED. DSA and Elgamal MUST NOT be used.
The cipher algorithm MUST be one of AES128, AES192 and AES256.
If the OpenPGP message is a compressed message, the compression algorithm MUST be ZIP or ZLIB.
The OpenPGP message MAY be integrity protected via the Modification Detection Code packet.
The literal data inside the OpenPGP message MUST be marked to contain binary data. If a text or UTF-8 message is received, an implementation MAY choose to accept the message. An implementation MUST NOT convert any canonical line endings to their local counterpart.
The signature packet and (if present) the one-pass signature packet MUST contain the Key ID of the key used to sign the message. Implementations SHOULD only sign a message using a single key. The hash algorithm used for signatures MUST be SHA-512.
The ASCII Armor, including Armor Headers, MUST be valid UTF-8.
The Armor Header "Comment", MUST be set to the message type.

System design

The system is built on top of PostgreSQL and uses its pgcrypto contrib module.

Messages are encrypted and signed using RSA public-key cryptography.

Each bank generates a RSA key-pair consisting of a public and a secret key.

The public keys and API URLs are exchanged between the banks.

The task of exchanging public keys and API URLs is preferrably done over the SWIFT network, by sending them in a normal MT999 SWIFT FIN-message. This allows banks to trust the validity of the public key and API URL, as the origin of SWIFT messages can be trusted.

Highlights

RSA-encryption
SHA512
JSON-RPC / HTTPS
Linux / PostgreSQL / Apache
Open source / MIT-license
Real-time request/response
Instant delivery receipt
Local archiving of files in PostgreSQL

Overview of the interface

To send a message, the sending bank encrypts and signs a message using Create_Message(), and calls Get_Message() to get the actual ciphertext content of the message. The ciphertext is then delivered to the receiving bank by calling its Receive_Message() API method, accessible at the API URL provided by the receiving bank. The API implementation must adhere to the JSON-RPC standard and accept HTTPS POST.

The Receive_Message() function returns a delivery receipt, which is a cryptographic proof of the fact that the sender was able to verify the signature contained within the message against the receiving bank's public key. This allows the sender to be certain that the message was delivered and decrypted successfully by the recipient.

The sending bank calls Decode_Delivery_Receipt() with the delivery receipt as input to verify its validity.

Database tables and columns

Banks

BankID : Unique identifier for the bank, preferrably the SWIFT BIC (PRIMARY KEY)
Protocol : API procotol, example "https"
Host : API host, Internet domain name, example "bank.com"
Port : API port, Internet network port, example 443
Path : API path, example "/api"
Datestamp : Date/time when added to the table

Files

FileID : SHA512 hash of the Plaintext (PRIMARY KEY)
Plaintext : The content of the file (UTF8)
Datestamp : Date/time when added to the table

Keys

MainKeyID : Signature key (PRIMARY KEY)
SubKeyID : Encryption key
PublicKeyring : Contains public keys
SecretKeyring : Contains secret keys (only set for your own bank, NULL for others)
BankID : The BankID which the keys belong to
Datestamp : Date/time when added to the table
PrimaryKey : Only set to TRUE for one row per BankID, other keys are still valid, but this key is used when creating new messages

Messages

MessageID : SHA512 hash of the Cipherdata (PRIMARY KEY)
FileID : The hash of the file send in the message
FromBankID : The bank who sent the message
ToBankID : The bank who received the message
Cipherdata : The encrypted and signed message
DeliveryReceipt : The encrypted and signed delivery receipt
Datestamp : The date/time when the message was created
Delivered : The date/time when the message was delivered

Database functions

Create_Message(Plaintext, FromBankID, ToBankID)

Create_Message() takes the plaintext context of a file as input and prepares an encrypted message signed by FromBankID which can be only decrypted by ToBankID. If the message already exists, the existing data is reused. An error is returned if the secret key of FromBankID or the public key of ToBankID can not be located in the database.

The return value is the message id of the message.

Get_Message(MessageID)

Given a message id as input, Get_Message() returns the ASCII armored PGP message. This data can then be HTTPS POSTed to the Receive_Message API method of ToBank.

Receive_Message(Ciphertext text)

Receive_Message() decrypts and verifies the signature of the input message. The message's details are written to the Messages table, and information about the file and its plaintext contents are written into the Files table. This function will raise an error if:

The secret key counterpart of the public key used to encrypt the message is not present in the table Keys.
The public key counterpart of the secret key used to sign the message is not present in the table Keys.
The message is corrupt or the signature can not be verified.

The return value is a delivery receipt, which should be then used as the contents of the response to the caller of the Receive_Message API method.

Decode_Delivery_Receipt(DeliveryReceipt text)

Decode_Delivery_Receipt() decrypts and verifies the given delivery receipt, where the keys involved and the plaintext should match a row in Messages. If so, the Message has been successfully delivered, and the Messages.DeliveryReceipt and Messages.Delivered columns are set.

Installing and building .deb packages for installation

The repository includes scripts for building debian/ubuntu packages for the bankapi and the required pgcrypto extensions (in PostgreSQL) in order to run the code.

If you are running a different version of PostgreSQL then 9.3 then replace the version in the commands below with the appropriate version. If you are running the default version in Debian you can omit the version extension of the packages names.

sudo apt-get -y build-dep postgresql-9.3
sudo apt-get -y install postgresql-server-dev-9.3 postgresql-9.3 apache2 python-psycopg2
make

This should produce two deb files, one for bankapi and one for the pgcrypto extension.

bankapi-1.0.deb

Package contains the command line tools for sending messages (/usr/bin/bankapi), SQL needed for creating the bankapi in postgres and installes a CGI as an endpoint for receving incoming communication messages.

The installation of the module installs and activates the CGI script. It will be available under http://localhost/bankapi .

The installation does not finish the installation of the database but leaves this as a manual task. Follow the following steps for a default database installation:

cd /usr/share/bankapi
sudo -u postgres createdb bankapi
sudo -u postgres psql --dbname=bankapi --single-transaction --no-psqlrc --file=install.sql
Make sure www-data user can connect to the bankapi database, this can for instance be done by adding the following line where appropriate in the active pg_hba.conf file: local bankapi www-data peer
To optionally install the test bank data: sudo -u postgres psql --dbname=bankapi --single-transaction --no-psqlrc --file=testdata/index.sql

postgresql-pgcrypto-openpgp-9.3.deb

This is an extension to the pgcrypto PostgreSQL extension. The extension only installs with the extended functions, all functions normally in pgcrypto is still accessed from the standard pgcrypto extension. The extension is called pgcrypto_openpgp.

thayub/bankapi