Systemics - Ricardo - SOX Server

The Management of a SOX-conformant Server

The Issuer Infrastructure

The Issuer Infrastructure achieves the purpose of connecting up clients (WebFunds, et al) to a SOX-compliant server. It is a layer above SOX, and a part of the full Ricardo infrastructure.

There are the following elements in the Issuer Infrastructure:

The Contracts. With each contract, the operator of the servers provides extra details to point to the SOX Server Descriptor that describes the SOX Server that will manage this contract.

This additional information can be in the local file that accompanies the contract, or it can be in the [operator] section of the contract. See The digital financial instrument contract. The contracts are then loaded automagically into the client program (either supplied with the client or browsed with a ContractBrowser such as within WebFunds ).
The SOX Server Descriptor (SSD), below. This (Info format) file is the single starting point for each SOX Server, and specifies the addressing conventions.
The Ricardian Issuance Servers, as particular instances of SOX Servers. At the addresses specified within SSD, servers will decrypt, verify and pass on SOX requests to backends for completion.
The LaMassana accounts backend. This does the grunge work of managing value.

On a SOX-compliant server there exists an info file called the SOX Server Descriptor (SSD) that describes information to do with that server. The contents of the SSD are one-to-one with a given server (although the file containing the SSD may be duplicated at several URLs, and there may be several alternate addresses for each server). The SSD instantiates the concept of the SOX-compliant Server (such as a Ricardian Issuance Server).

The addresses may be domain names or IP numbers, if DNS problems are indicated. This avoids primary DNS server lockup delays, and in a sense, implements a local form of DNS.

The syntax and layout formats of the SSD is defined in the same way as the Ricardian Contract.

The [sox] section

server_name The short name used to indicate the SOX Server is just a hint for user software for display and filename purposes. Typically, user software stores its data in a directory of this name, or otherwise indexes into a database, allowing for multiple SOX Servers.

Note that the name is not guarunteed to be unique as it is impossible to stop spoofing. It provides a mechanism for avoiding errors. This may be replaced by some PK mechanism at some stage. (Don't use more than 31 characters until the Mac can handle it.) Was shortname.

server_url the precise net location of the server that will accept SOX instructions. This will include the port number.

For a server that has multiple ports, this can be duplicated using the += form:

        server_url+=http://ivanovich.com:8087/
        server_url+=http://ivanovich.ai:9010/
        server_url+=http://ivanovich.co.uk:9011/
        server_url+=http://ivanovich.za:9012/

server_file_url the location of files containing the SSD on the web (use a standard GET to acquire the file).

This self-referential url allows the SOX Server to change the location of the file from time to time. Clients can re-read the SSD, and check that this url has not changed.

This tag is also replicated in the same sense of the server_url, above.
protocol_version the SOX version that the server conforms to. This is synonymous with server_version and one of these should be deprecated. The Ricardo Issuer uses the former, Java clients expect the latter.
file_version is the version of this SSD. Similar to DNS, the SSD is manually incremented when there is a change.
server_cert is the current certificate that the server uses to sign its ephemeral certs.

This is an optional field. The presence here of the cert does not signify it is valid, see keys notes below.

The [application] section

Remaining sections are application specific and not defined by the SOX definition.

contracts_url is the url of the contracts directory. Where contracts are handled, these are located in a directory. Optional.
account_key Id of the SOX Server [account] key.

This key gives the account to make payments to. It exists for a SOX Server that requires you to send it value.

Accessed via the get key in SOX, not yet added.
hash_type Default hash type used to hash contracts, can be overridden in the local file for a given contract. For example, either MD5 or SHA.

Default is SHA. This might be used in order to signal a change to another hash, if the previous one becomes suspect.

This may be dropped in favour of a SOX indication.

The [misc] section

A Misc section has been added for random stuff.

history Traditionally, comment was added to the top of the file to document the history behind the name of the server. This is now optionally available in a variable for the client's pleasure.

Purposes of Keys

PGP keys have a userid field which for Ricardian Contract purposes includes a Ricardian key purpose tag. The tag is simply a word surrounded by [square] brackets.

The following intentional purposes for keys are defined. Appended numbers indicate minimum recommended key sizes, in bits.

[certification] is used to sign all other keys (it should also sign itself) by a legal contract issuer. This one should be confirmed *manually* by the user, allowing the rest to be confirmed automatically by software. 2048

Note that the [certification] key may itself signed by a super certification key, where the latter is kept off-line whilst the former is used to automatically roll-over keys. A future detail.

Deprecated. The certification key used to have a shorter form of [cert] tag in it.
[contract] is used to sign digital financial instrument contracts, such as currencies and bonds that are financially issued by a company or individual. The signer, as legal contract issuer, is making some statement about the value of the contract. 1024
[receipt] is used by an Ricardo Issuance Server to sign receipts indicating details of successful transfers between accounts. 512

Note that the [receipt] key was not used in SOX 2.0 (x.509) to SOX 2.1 (OpenPGP first versions).
[operator] is used by the operator of the SOX Server to sign [server] keys. The former is kept off-line, whilst the latter is available on-line inside the server and optionally the SSD. 2048.

The inclusion of this [operator] key in a Ricardian contract indicates which operator is contracted to provide the Issuance Server whilst permitting the operator to change [server] keys from time to time.
[server] is used as the working key by the SOX Server. On restart, this is the key it has available to authenticate any session setup work. 1024
[comms] is used as the (short-term) session key for generating single transactions with user software. 768

Note that the [comms] key is not currently used (SOX 2.1) as a key-exchange protocol (Diffie-Hellman) is used instead of a PGP public key.
[account] is used as the payee account for a shop. 512
[web] is used to sign the keys of others. This is a "I think it is what it says, but don't believe me" key, as distinct from any contractual position. That is, this is the key used to create a web of trust. It can be used to sign the keys of shops, or other legal contract issuers, for instance and it should in term be signed by the applicable [cert] key of the signer. 1024

The purpose is a lower case word surrounded by [square] brackets. It is stored in the user id.

The keys are used for differing purposes, allowing, for example, the [certification] key to be inefficient but strong, whilst the [comms] key can be efficient, and hence not as strong. To guard against a swapped key attack, user software should check that the purpose is correct.

Both the contract and the SOX protocol require a public key signing chain in order to authenticate dynamic actions initiated by a client such as WebFunds. The major purpose of this public key infrastructure (PKI) is to direct the authentication up a chain to a single key for each substantial question that might be asked.

SOX generally prescribes that the user id should also include the following substrings, currently only for human consumption:

Server name.
A version number. So as to work out which is the current key if there are many.
An email address. For admin purposes only.

Deprecated. This section does not relate to SOX 2 (which used x.509, whose keys had no purpose tag available).

Issuing a New Digital Financial Instrument

The digital financial instrument, more simply known as an item, can be managed by an issuer simply by honouring requests on a hash of a contract, and by injecting value into the item within the system.

As of the moment, there is no difficulty in any outside user creating their own currency. However, there is a lot of difficulty in them injecting value into the system. This is unlikely to remain so in the future, if only for marketing purposes. Currently, however, it is not a problem as there is no security implication in users creating a worthless currency.

Issuance of New Contracts

In the mounting of contracts, a phased approach is taken:

1. take the contract and conduct sanity checks on it to catch any errors that might have occurred. If an error is spotted, it is referred back to the Legal Issuer for correction and resigning. This phase is concerned with the technical format of the contract, not with its legal content. For example, misplaced or illegal characters that the software cannot read are checked for.

2. Place the contract within the domain of the server, and test that the various features are turned on and working. For example, balance sheet reporting is checked.

3. Await the notification for the mint account. A mint account is required for every contract, and this is created and controlled by the Legal Issuer (or more properly, his agent). Once the Legal Issuer designates which account is the Mint account, then that account is turned into a Mint, and the Legal Issuer can start to create and disburse value.

That is the end of the big steps, but bear in mind there is a lot of administrative detail behind those steps. There is much more information on issuance on the Ricardian Issuance Page.

Initiating the New Contract

To introduce the contract to the outside world, you will need your [contract] key, signed by the former (see above). Follow these steps

Copy one of the existing ones, and adjust the contents according to the contract specification .
Run infofile (a market/bin program) over the contents (not possible yet).
Sign it with the Issuers [contract] key, (see above) using the PGP command (or something similar):
```
	pgp -sta +clearsig=on file -u [contract]
    
```
Copy the signed contract file.asc into issue directory tree, where it can be browsed down by users, where file is the name (a TLA if international currency) for the currency.
If the market is to accept the new contract for trading purposes, then send a copy of the contract to it.

Injecting Value into the System

To manage the contract, you need to inject value into it in a controlled fashion. Follow these steps:

Create a new KHID on a secure machine. We will use this KHID as the Mint for the currency, so the KHID must be kept highly secure - the security of your entire system depends on it, along with access to the machine that runs the servers.

Register and create the KHID by using a Systemics tool such as WebFunds. At this stage, that's all you can do, as it has no value in it.
Here's the tricky part. Identify the KHID and run a special issuer management tool on it that permits it to go into debit:
```
        lam_modify -name MD5:1234567890abcdef -comd flags 2
    
```
rather than credit. This KHID will always operate on the negative side of the balance sheet from now on.
Now, simply export a payment out of the KHID using one of the Systemics tools. This payment can now be deposited into any KHID as a positive amount.

Take a moment to think about these steps. The total system is still at a net balance of zero. If you add up the amounts, it should all balance, and in fact, that is what has to happen always for the system to work.

In fact, if you run the special issuer management tool on your currency:

	lam_sheet -item MD5:abcdef1234567890

you will see that the net balance shown at the end is zero.

Annex 1: The PGP Key Ring Entry

A PGP Key Ring Entry is used as the unit of delivery for keys in the SOX key infrastructure. PGP (Pretty Good Privacy, as trademarked by PGP, Inc) is documented voluminously elsewhere. Only relevant sections are included here. See the file doc/pgformat.doc in your PGP documentation for more details.

The PGP Key Ring Entry, or Entry, consists of:

A PGP key certificate. For the purposes of this document, this will be a Public key, but Private keys are the same.
One or more user id fields. These are strings that label the certificate for human consumption. They can be used to describe the intended purpose of the key.
One of more signatures. Each signature is on the preceeding certificate and one of the user id fields.

Each signature includes a key id that refers to the Entry that was used to formally sign this key. See ....

Other defined terms are:

key id: is an 8 byte identifier for a key. It is normally printed as a 16 byte hex string.
key fingerprint: is the 16 byte identifier that uniquely identifies a given key. It is an MD5 hash of the public key. It is normally printed as a 32 byte hex string.