System Functionality

This is a multi-step process. First, the client (VSC) needs to be logged in to a Jabber server (an OFS) which reveals via discovery (or "disco") that it possesses the required plugin for system access. The "Voucher Safe Client" tab will not appear in the client unless this is the case.

Next, the user selects from among the VPs supported by that OFS (unless there is only one, in which case this step is skipped). The user also enters an identifying name or "handle" for the safe being created.

The OFS then queries the VP on the client's behalf, and obtains the key algorithm and key length which the VP supports. This is sent back to the client, which proceeds to generate the key pair as specified.

Having generated the key pair, the client sends the OFS the public key and the entered safe name. The OFS forwards these to the VP, which appends a base name and unique sequence number to the client's safe name to produce the VS number (which resembles an email address, e.g. foo-123@voucher-safe.org). It then generates a certificate for the public key provided, signs it with its own private key, and uploads it to the PKS, indexed by the VS#.

The VP also tells the SDS to create two folders for the new safe: one which will store vouchers and tokens belonging to the safe, and another which will be used to store pending payment and receipt records. The SDS returns the randomized index hashes and the two generated capabilities (read cap and read-write cap in Tahoe parlance) to the VP.

The VP then constructs an XML block for the client which contains:

• The assigned voucher safe number (VS#)
• The hash index (dirname) for the voucher/token folder on the SDS
• The hash index (dirname) for the payment/receipt folder on the SDS
• The read cap for the voucher/token folder
• The read cap for the payment/receipt folder
• The read-write cap of the voucher/token folder, encrypted using the VP's public key
• The read-write cap of the payment/receipt folder

This block is then encrypted using the client's public key, and sent back to the client via the OFS, along with the inet address of the PKS, and the VS's new signed certificate. The OFS appends the length of the PINs used by that VP, and the text of five security questions whose answers will be used for lost safe recovery.

It should be noted that the OFS is incapable of viewing the new safe's private data, and that the client itself will have read-write access to its payment/receipt folder, but only read access to its voucher/token folder.

The client decrypts the VP's block using its private key. It also obtains the VP's public key from the PKS, and uses it to validate the signature on its own certificate. It then prompts the user for the following information:

• A PIN (of the indicated length)
• A long-phrase of 8-15 alphanumeric characters
• A pass-phrase of 8-24 characters
• The answers to the five recovery questions

The client validates the user's input and constructs an XML data block for the VP, encrypted using the VP's public key, which contains:

• The VS# (as an echo)
• A secret details blob, encrypted using 3DES with the pass-phrase as key, containing:
  • The VP's id (the userid of its public key)
  • The signed public key certificate
  • The private key
  • The voucher/token folder hash index
  • The voucher/token folder read cap
  • The voucher/token folder encrypted read-write cap
  • The payment/receipt folder index hash
  • The payment/receipt folder read-write cap
• A hash key index for the long-phrase record, hash(VS#+PIN)
• The long-phrase
• A recovery details blob, encrypted using 3DES with the hash of the VS# and the concatenated answers to the five recovery questions as key, containing:
  • The VS#
  • The VP's id
  • The PIN
  • The long-phrase
  • The pass-phrase
• The recovery index storage hash, hash(hash(VS#+5 recovery answers) )
• The login secrets storage hash, hash(hash(VS#+PIN)+long-phrase))

Note that the OFS cannot read any of this, while the VP cannot read the secret details or recovery blobs. The VP then creates three more records on the SDS, as follows:

• A login details blob, mapping the secret details to the login secrets hash
• A recovery details blob, mapping the recovery details to the recovery index hash
• A long-phrase blob, mapping the long-phrase hash key to a record 3DES-encrypted with the hash key, and containing the following:
  • The long-phrase
  • The associated login details read cap (as set by the SDS)

Long-phrase blobs are stored in a global SDS folder, for which the VP has the read-write cap and all OFSen have the read cap. Login secrets are stored in unique folders, with read caps recorded in the long-phrase blob (i.e. they cannot be modified). Recovery details go in a global table, hash collisions being rendered impossible by the uniqueness of VS numbers.

All of this complexity is, fortunately, hidden from the client, but it allows the system login protocol to work as described in the next section.

Once a VS is logged in and has access to its secrets, it can then perform operations with the vouchers and tokens in its safe. These operations include: Validation, Split, Merge, Payment (to another VS), Token Purchase, and Reclamation (of an outbound payment which was never picked up by its payee before it expired).

These operations all require that the VSC supply the VP with a "Voucher Request." A VoucherRequest object always contains:

• An action, one of validate|merge|split
• An input list of vouchers
• An output list of values, such as a payment amount and a change amount
• The VS# making the request
• The VS's voucher/token folder hash index on the SDS
• The VS's encrypted read-write cap for its voucher/token folder
• The VS's private key signature on the above
• Some number of payment tokens, based on the cost of the operation.

Note that the XML details element (which contains everything except the action and the payment) is always encrypted with the VP's public key before sending, so that only the VP can interpret it.

Depending upon the operation, additional data may be included, such as a payee VS#, baggage field names and values, or the like. This additional data is typically provided in a separately encrypted and signed XML block which precedes the VoucherRequest in order to give it a context.

The general principles are that:

1. The VSC cannot make any changes to its SDS folder without involving the VP.
2. The VP utilizes the folder index and decrypts the cap (using its private key) for piecemeal use only, and then forgets about it as soon as the operation is completed.
3. Third party notification (e.g. of a payee) occurs via an encrypted notification placed on the DHT for that party's attention.
4. All outstanding notifications have a TTL (time to live, one week by default) on the DHT.

Next we'll look at the process of making a payment, in the following section.

The payment form in the VSC asks for an amount and a payee VS#. There is also a handy calculator tool for computing the amount of the underlying asset (gold in the demo system) valued in various national currencies on a drop-down list. Feeds for metals prices are easy to find. If something else were used as the backing asset, current market prices would need to be obtainable in real time for the calculator to be useful.

The VSC fetches the payee safe's public key off of the PKS. It is not possible to make a payment to a VS that does not exist, nor to one that has been closed, because the PKS will return a failure in either case.

The form also permits entry of key/value pairs, intended to communicate to the payee what the payment is for (such as an order number) or who sent it. In future, this "baggage field" table will be able to be pre-populated via a message sent by a website which accepts P2P vouchers as a payment option. All user entries will be encrypted using the retrieved public key of the payee. Therefore the VP will be unable to view this information, merely passing it along to the payee as a blob contained within the payment notification which it posts for the payee on the DHT.

Lastly, the client form allows the payer to specify 1-7 integral days as the time limit for the payee to pick up their voucher payment. After this time (known as the "TTL" or time to live) elapses, the payee will no longer be allowed to pick up the payment and it will become eligible to be reclaimed by the payer.

The VSC checks that one or more vouchers have been selected in the safe's voucher pane, sufficient in value to cover the amount of the payment. It also checks that the required number of tokens is available (12, in the demo system). Provided these conditions are met, the client then constructs a VoucherRequest XML object and a payDetails object, containing everything the VP needs to perform the transaction, and then signs the whole with its private key and encrypts it using the VP's public key. The request is then sent to the VP via the OFS.

The VP decrypts the client's message block and validates the VSC's signature on the VoucherRequest. (It cannot validate the signature on the baggage details encrypted to the payee's key, obviously; that is left as an exercise for the payee.) One of the elements of the payer's VoucherRequest is the hash index (dirname) and read-write capability for the payer VS's voucher/token folder on the SDS. The cap is always encrypted using the VP's public key, so the VP now decrypts that field separately to obtain the clear cap. This gives the VP the temporary ability to manipulate the contents of the payer's safe. It should be noted however that the VP does not possess the corresponding folder dirname and cap for the payee's folder.

The VP then performs the following steps in order:

1. It fetches the public keys for both the payer and payee off of the PKS. Failure, even if the reason is a connectivity loss to the PKS, aborts the payment with an error.
2. It lists the vouchers in the payer's safe, and checks that the filenames match. That is, it verifies that the filename which is associated with each decrypted voucher in the VoucherRequest actually appears in the payee's safe. While vouchers on the SDS are encrypted, and therefore the VP cannot validate that the contents are the same as the decrypted vouchers presented in the request, since filenames are randomly generated by the SDS, it would be astronomically difficult to counterfeit a valid filename. A malicious VSC could swap one filename for another, but since the vouchers spent will have their serial numbers retired, and the filenames specified will be deleted, any such substitution would only result in a loss of value to the user. Verification failure aborts the payment with an error.
3. The VP next verifies that all tokens offered as payment bear valid signatures, and actually appear in the payer's SDS folder. Tokens are not stored encrypted; therefore the serial numbers of the actual tokens can be confirmed. Verification failure aborts the payment with an error.
4. The VP tests the vouchers supplied for sufficiency against the amount of the payment. It then transmits to the Issuer the amounts and serial numbers of the vouchers being spent, asking for two replacement vouchers of equal total value. The first will be used for the payee and equals the amount of the payment. The second is for the payer and represents any difference. (Note that if the payment voucher(s) exactly equal the payment amount, the change voucher may be obviated.) The Issuer validates the amounts and serial numbers of the vouchers against its list of outstanding unexpired vouchers in circulation. If they are found, it retires them and issues the new vouchers with fresh serial numbers and transmits them back to the VP. Inability to access the Issuer, or an error reply from it, aborts the payment with an error. Note that once this step is completed, the transaction can only go forward. It cannot go backward, because the original vouchers no longer exist.
5. The VP's next step is to delete the spent vouchers, by filename, from the payer's SDS folder. If this operation fails owing to a sudden loss of connectivity to the SDS, then the message will be queued in a disk-backed hard queue for processing as soon as the SDS is again available. (This means that even if the VP itself should go down before delivery occurs, there will be no loss of data.)
6. The VP creates an incoming payment notification message for the payee. This contains the payee's new voucher and the opaque blob from the payer. The record is encrypted with the payee's public key and placed on the DHT at the payee's hash (i.e. SHA1(payee VS#) ). If the DHT is currently unavailable, the message is hard queued for transmission when connectivity is restored.
7. The payer's change voucher (if any) is then inserted into their safe on the SDS. Again, insertion failures will be hard queued.
8. The expended tokens are then deleted from the payer's SDS folder. Those owed to the OFS are paid over (copied) into a special token accumulation safe, to which the VP has the index hash and cap. (The OFS will redeem them for a voucher later after enough of them have accumulated.) Those owed to the VP itself are simply de-circulated, i.e. removed from the VP's list of circulating tokens and added to its list of withdrawn tokens.
9. A payment confirmation record is then prepared for the payer. This record reiterates the payee, amount, and TTL of the payment, and includes the payer's signed change voucher and the serial number of the voucher issued to the payer (but not the signed voucher itself). The VP creates a temporary record in its own database in which the same serial number is stored, together with the payment's expiration time and a hash: SHA256(payer VS#:payee VS#:amount units asset). Both the payer and the payee will have enough information to successfully reconstruct this hash. But the VP logs or retains no other record of the transaction, and anyone who gained access to the VP's database would therefore find nothing of interest. The confirmation record is encrypted with the payer's public key and placed on the DHT, again subject to hard queuing if necessary.
10. Lastly, the VP sends a reply to the VSC via the OFS. This simply indicates the success or failure of the operation, and contains an additional boolean field indicating whether any of the above manipulations involving the SDS or DHT needed to be queued. (The client is expected to warn the user if a reply arrives with this flag set, since viewable data may not yet reflect the completion of the payment.) The payment confirmation record is placed on the DHT in preference to returning it in this reply, because it is not possible to guarantee delivery of the reply. If for example the client lost its internet connection immediately after clicking the Submit button, the reply could be dropped, possibly without detection. In such a case, if the payee never picked up their payment the payer would likewise lack the information (the serial number of the issued voucher) required to recover it, and the value would be permanently lost in limbo.

In due course, the payee logs into their VS. They check their Activity on the DHT and discover and download the new incoming payment notification. Decrypting this with the private key, the VSC displays the details of the payment, including any private "baggage" details from the payer, whose signature is also verified. The user then processes the payment, which triggers the performance of the following steps by the payee VSC:

• It picks up the payment from the VP, via the OFS. This message basically amounts to a Validation of the incoming voucher, but also includes the computed hash of the transaction details which the VP has stored in its database. The payee must produce not only the serial number, but the VP-signed voucher itself bearing that number, in order to pick up the payment. This operation causes a new equivalent voucher to be issued and placed in the payee's safe, at which point the voucher serial number (which the payee also received in their confirmation) is no longer valid. The VP also deletes the pending transaction record from its database. If the payment TTL as set by the payer has expired, the VP will reject the pickup operation.
• Next it generates a receipt for the payer, recapitulating all the transaction details, and signs it with the payee's private key. This record is then encrypted using the payer's public key and placed on the DHT (at a cost of one token paid by the payee).
• Lastly, it marks the record "read" on the DHT so that it will not be retrieved again. The record is not deleted until its TTL has elapsed, but records bearing an index hash (known only to the particular VS) will not be retrieved subsequently.

The payer retrieves their confirmation off the DHT, probably almost immediately. Processing this message causes their change voucher to be displayed in their voucher pane, their spent tokens to be removed from their tokens pane, and a pending payment record to be inserted on the SDS in their payments/receipts folder. (Recall that each VS always has both the read and read-write caps for this folder in its login secrets.) This record can be used, after the TTL has expired, to recover the payment if the payee has not picked it up before then.

If the payee does pick up their payment, as above, then in due course the payer will discover a receipt from the payee on the DHT. Decrypting and processing this results in a receipt which can be read, and if the user wishes stored in their payments/receipt folder at a cost of one token. (Or, it may be discarded at the user's option.) Receipts constitute a payment history for the safe, and records stored may be purged by the user at any later date. All receipts are stored only in encrypted form. Processing a receipt causes the corresponding pending payment record to be deleted.

Should the payee fail to pick up the payment within the designated TTL, the payer will see, when browsing their pending payments folder, that a particular payment has expired. (It's a good idea to check to be certain that all incoming receipts have been processed first, before making this assumption.) Reclaiming an expired payment generates a VoucherRequest message to the VP, which includes the transaction details hash and the serial number of the payee's voucher.

The VP will check to see if an outstanding payment with this hash and voucher serial number is found within its database. If the payee previously picked up the payment, it will not exist. (Note that this situation is possible if the payer had not logged into their safe for at least 7 days, and thus missed ever seeing their receipt before it expired off the DHT.) If it does exist, and the TTL has expired, then the hash is validated, and if it matches the reversion of the payment is permitted. In this case the payee voucher is retired and a new one for the same amount is obtained from the Issuer, and placed into the payer's safe. There is no token charge for this operation. The VP then purges the outstanding payment record.

Thus the loop is closed and a P2P voucher payment has been effected!

It is not possible to change the keys or login details of a voucher safe. However, periodically or if they have reason to believe that their safe may have been compromised, a user can close their safe and transfer all value stored in it to a new safe. There is a 25 token fee for this operation.

If the user's safe is empty (i.e. contains no vouchers and less than 25 tokens), then it may simply be closed. Closing a safe causes the VP to revoke its public key certificate and add its serial number to the certificate revocation list (CRL) on the PKS. A user may still log into a closed safe and view and delete stored receipts, but a closed safe cannot receive a voucher, or a receipt. For this reason, a safe cannot be closed while it still has an unprocessed record on the DHT. It is also highly recommended, but not required, that any pending payments not yet picked up by their payees be resolved before closing a safe.

If the VS is non-empty (i.e contains at least one voucher of any size, and/or more than 25 tokens), then the user will be led through the process of opening a successor safe. When that is completed, the user will be taken to a closure agreement page explaining what is about to occur, and requiring the user's acceptance. This agreement will be signed with the safe's private key.

Upon submission, the OFS forwards the encrypted closure request to the VP, which will convert all vouchers in the old safe into a single new voucher of equivalent value which is then inserted into the new safe. This is the only case where the VP actually has the index hashes and read-write caps for two safes available to it at the same time. Excess tokens are likewise moved from the old safe to the new. The old safe then has its key repudiated, after which it cannot receive or send payments.