<commit_before>.. _bank:

Bank
====

A bank is the consumer facing organisation that holds a users bank accounts. All banks must provide the `Standard Bank API`_ and declare the endpoint that their API is found at. Typically these will be banks that you recognise and trust; Anyone is able to setup a bank but only financially regulated ones are endorsed by the network itself. The ability for anyone to setup a bank is primarily for testing and innovation uses.

Setting up a bank
-----------------

In order to become a bank on the network, at a minimum, you need a domain name that you can prove is yours. Contact information is obtained via WHOIS which can then be edited later. An implementation of the bank creation process can be found at https://en.opentrans.fr/bank.create

Internally the join process works like this:

1. A company that wishes to join the network as a bank firstly provides their website domain name, for example “bank.opentrans.fr” and a public key through the `entity.create API`.
2. The receiving root node must now trust that the requesting user has access to the given domain. The response here is compatible with the `ACME protocol`_; essentially, the user is challenged to prove ownership by either creating a DNS record or by serving a special piece of text over HTTP/S.
3. The user then fulfils the challenge by creating the file or DNS entry. Also compatible with the ACME protocol, the user then informs Root that the challenge is complete. Root then validates it by e.g. performing a DNS lookup or loading the webpage.
4. Provided the validation is successful, the receiving root node looks up the domain name to obtain the registrant information such as the company name and country, then creates the entity.

At this point the entity is **not certified**. These banks may join the network for testing purposes, however consumers will be clearly notified that the bank they are using is not regulated.

Signing your DNS
----------------

It's very easy to forge DNS records. In order to prevent your DNS from being either hacked and changed or records being changed in-flight by untrusted proxies, it's highly recommended to provide a signature in your DNS. To do this, add a TXT record at your endpoint with the following:

opentx sig:{base64 encoded signature}

The data to sign is as follows:

1. Get all your IP and IPV6 address records
2. Treat the addresses as strings 'as-is' on the records
3. Sort alphabetically
4. JSON stringify the set with no spaces or tabs. The result looks like this (with complete IPs):

'["178.232..","178.233..","2a03:b0c0:.."]' // Sign this string with your private entity key.

Anyone wishing to verify the signature can perform the same steps as above and use your public entity key.

A Javascript implementation is available at https://txroot.opentrans.fr/v1/dev. Pop open the console, load your private key with loadKey("hex_key") or generate one for testing with generateKey(), then call signIPs("your.domain.com").

Editing Contact Details
-----------------------

Contact details are obtained from WHOIS as they are assumed to be correct for most trustworthy banks. However, if a banks details change or are otherwise not correct, the information can be updated through the `entity.update API`.
Banks **must** make sure this information matches the information held by the financial regulator if they wish to become certified.

Becoming certified
------------------

In order to become fully certified, a bank must pass basic security testing and prove that it is regulated by a financial regulator (for example, the FCA in the United Kingdom).

Internally the certification process works like this:

1. A registered entity (see setting up above) provides the name of their regulator from a known list and an ID. This is sent to the `entity.certify API` and signed with the entities private key.
2. The receiving root checks the security properties of the website itself, essentially performing a small security audit:

- Does the website use HTTPS? If not, it's rejected.
- Does the website handle connections on HTTP at all? If it does, warn about a security hole.
- If it does handle HTTP connections, is it a redirect? If it's not a redirect, i.e. the site works as normal over HTTP, reject.
- Does it use HSTS? If not, strongly recommend HSTS registration.

3. Provided it was not rejected, the root node looks up the website on the financial regulator to see if it really is a regulated entity. Note that the matching compares as much information as possible, so a bank must ensure that it's contact details are correct (see above).
4. If a valid match is found, the entity is successfully marked as certified.
<commit_msg>Update index.rst<commit_after>.. _bank:

Bank
====

A bank is the consumer facing organisation that holds a users bank accounts. All banks must provide the `Standard Bank API`_ and declare the endpoint that their API is found at. Typically these will be banks that you recognise and trust; Anyone is able to setup a bank but only financially regulated ones are endorsed by the network itself. The ability for anyone to setup a bank is primarily for testing and innovation uses.

Setting up a bank
-----------------

In order to become a bank on the network, at a minimum, you need a domain name that you can prove is yours. Contact information is obtained via WHOIS which can then be edited later. A simple UI for the bank creation process can be found at https://txroot.opentrans.fr/ui#screen=entity.create

Internally the join process works like this:

1. A company that wishes to join the network as a bank firstly provides their website domain name, for example “bank.opentrans.fr” and a public key through the `entity.create API`.
2. The receiving root node must now trust that the requesting user has access to the given domain. The response here is compatible with the `ACME protocol`_; essentially, the user is challenged to prove ownership by either creating a DNS record or by serving a special piece of text over HTTP/S.
3. The user then fulfils the challenge by creating the file or DNS entry. Also compatible with the ACME protocol, the user then informs Root that the challenge is complete. Root then validates it by e.g. performing a DNS lookup or loading the webpage.
4. Provided the validation is successful, the receiving root node looks up the domain name to obtain the registrant information such as the company name and country, then creates the entity.

At this point the entity is **not certified**. These banks may join the network for testing purposes, however consumers will be clearly notified that the bank they are using is not regulated.

Signing your DNS
----------------

It's very easy to forge DNS records. In order to prevent your DNS from being either hacked and changed or records being changed in-flight by untrusted proxies, it's highly recommended to provide a signature in your DNS. To do this, add a TXT record at your endpoint with the following:

opentx sig:{base64 encoded signature}

The data to sign is as follows:

1. Get all your IP and IPV6 address records
2. Treat the addresses as strings 'as-is' on the records
3. Sort alphabetically
4. JSON stringify the set with no spaces or tabs. The result looks like this (with complete IPs):

'["178.232..","178.233..","2a03:b0c0:.."]' // Sign this string with your private entity key.

Anyone wishing to verify the signature can perform the same steps as above and use your public entity key.

A Javascript implementation is available at https://txroot.opentrans.fr/v1/dev. Pop open the console, load your private key with loadKey("hex_key") or generate one for testing with generateKey(), then call signIPs("your.domain.com").

Editing Contact Details
-----------------------

Contact details are obtained from WHOIS as they are assumed to be correct for most trustworthy banks. However, if a banks details change or are otherwise not correct, the information can be updated through the `entity.update API`.
Banks **must** make sure this information matches the information held by the financial regulator if they wish to become certified.

Becoming certified
------------------

In order to become fully certified, a bank must pass basic security testing and prove that it is regulated by a financial regulator (for example, the FCA in the United Kingdom).

Internally the certification process works like this:

1. A registered entity (see setting up above) provides the name of their regulator from a known list and an ID. This is sent to the `entity.certify API` and signed with the entities private key.
2. The receiving root checks the security properties of the website itself, essentially performing a small security audit:

- Does the website use HTTPS? If not, it's rejected.
- Does the website handle connections on HTTP at all? If it does, warn about a security hole.
- If it does handle HTTP connections, is it a redirect? If it's not a redirect, i.e. the site works as normal over HTTP, reject.
- Does it use HSTS? If not, strongly recommend HSTS registration.

3. Provided it was not rejected, the root node looks up the website on the financial regulator to see if it really is a regulated entity. Note that the matching compares as much information as possible, so a bank must ensure that it's contact details are correct (see above).
4. If a valid match is found, the entity is successfully marked as certified.

{'fraction_non_alphanumeric': 0.058181432810512926, 'fraction_numerical': 0.006994489190334888, 'mean_word_length': 3.9408376963350786, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2088999', 'n_tokens_mistral': 2275, 'n_tokens_neox': 2163, 'n_words': 1516}