From 1068f4a2bfcc82aefc307fc2114f52e5ac9e61ee Mon Sep 17 00:00:00 2001
From: Gavin Andresen <gavinandresen@gmail.com>
Date: Fri, 19 Apr 2013 13:27:33 -0400
Subject: [PATCH] Fix use-after-free bug, and better error handling

---
 README.txt                                  |   25 +-
 TODO.txt                                    |   76 --
 c++/README.txt                              |   21 +
 c++/paymentrequest-create.cpp               |   34 +-
 c++/paymentrequest-dump.cpp                 |    2 +-
 php/demo_website/createpaymentrequest.php   |    7 +-
 php/demo_website/include/paymentrequest.php | 1227 ++++++++++++++++++-
 spec.rst                                    |  297 -----
 8 files changed, 1282 insertions(+), 407 deletions(-)
 delete mode 100644 TODO.txt
 create mode 100644 c++/README.txt
 mode change 120000 => 100644 php/demo_website/include/paymentrequest.php
 delete mode 100644 spec.rst

diff --git a/README.txt b/README.txt
index 3a58cd8..b50a549 100644
--- a/README.txt
+++ b/README.txt
@@ -1,25 +1,16 @@
 Code implementing a simple payment protocol for Bitcoin (PaymentRequest/etc).
 
-See https://gist.github.com/4120476
+See https://en.bitcoin.it/wiki/BIP_0070
 
-Dependencies:
-  OpenSSL (library and openssl command-line tool)
-  Google Protocol Buffers (library and protoc command-line compiler)
+Files here:
 
-Debian/Ubuntu:
-  apt-get install openssl protobuf
-OSX MacPorts:
-  port install openssl protobuf
+paymentrequest.proto : Google protocol buffer definition of messages
 
-To compile:
-  make
+Subdirectories here:
 
-The Makefile will create a "certificate authority in a box" in ca_in_a_box/ and
-compile command-line tools:
+c++ : command-line utilities for creating/validating PaymentRequests
 
-paymentrequest-create  # Prototype code: create a PaymentRequest message
-paymentrequest-verify  # Prototype code: verify a PaymentRequest message
+php : php code and a demo website for creating/validating PaymentRequests
 
-
-Example usage:
-  paymentrequest-create paytoaddress=1BTCorgHwCg6u2YSAWKgS17qUad6kHmtQW memo="Just Testing" amount=11.0 | paymentrequest-dump
+ca_in_a_box : "certificate authority in a box", used to generate
+  certificates and certificate chains for testing.
diff --git a/TODO.txt b/TODO.txt
deleted file mode 100644
index badb238..0000000
--- a/TODO.txt
+++ /dev/null
@@ -1,76 +0,0 @@
-Task list for implementing PaymentRequest/etc
-
-SERVER SIDE:
-
-DONE: 1. Create command-line, intended-to-run-on-a-web-server merchant tool
-  that creates PaymentRequest messages: paymentrequest-create
-
-Arguments:
-  --paytoaddress=BTC_ADDRESS
-  --amount=BTC (e.g. 1.0)
-  --certificates=path/to/certleaf.pem,path/to/certintermediate.pem
-  --privatekey=path/to/key.pem
-  --memo="message"
-  --expires=timestamp
-  --payment_url=URL
-  --out=path_to_file
-
---certificates is the certificate chain, farthest-from-root first.
---privatekey must be the key used by the first --certificate.
---out defaults to stdout
-
-See https://gist.github.com/4120476 for a description of the other arguments.
-
-DONE: 2. Create a command-line tools for debugging/testing:
-  "paymentrequest-dump"
-
-3. Create a testing website that generates -testnet PaymentRequests signed
-  by a valid certificate (allow user to choose paytoaddress/amount/etc).
-  DONE: https://bitcoincore.org/~gavin/createpaymentrequest.php
-
-4. Modify testing website so it will generate invalid PaymentRequests
-  Conditions:
-    Self-signed
-    Expired leaf certificate
-    Valid-certificates but expired PaymentRequest    
-    Invalid signature
-    ??? what else ???  UTF-8 tricks with the common name? (e.g. attacker^H^H^H^H^H^H^H^Hamazon.com )
-      Is that taken care of by the root CA ?
-
-5. Add to testing website to support a payment_url that generates PaymentACK messages:
-  DONE: Add an id number to generated PaymentRequests, add to PaymentRequest.merchant_data
-    and store them as they're generated
-  DONE: Handle Payment messages submitted to payment_url:
-    get id from merchant_data, lookup associated PaymentRequest
-
-
-CLIENT SIDE
-
-1. DONE/PULLED:  Rework Bitcoin-Qt bitcoin: URI handling to use QLocalSocket instead of the flaky
-   boost::interprocess mechanism.
-
-2. Teach Bitcoin-Qt to handle application/x-bitcoin-payment-request MIME type:
-  DONE Add protobuf library as dependency to .pro file, doc/build-*.txt, gitian dependencies, etc.
-  DONE Use system root certs, but allow overriding with own list.
-  DONE Display Send dialog with info from PaymentRequest
-    (displayed in Send tab)
-
-  DONE: Unit tests for valid/invalid certs
-
-3. Modify installers to:
-  register Bitcoin-Qt as x-bitcoin-payment-request handler
-  OSX: DONE
-  Windows
-  Linux  (??? just ppa ???)
-
- TEST: OSX/Linux/Windows
-   
-4. Teach Bitcoin-Qt the extended bitcoin: URI syntax:
-  DONE if request= given, fetch payment-request from URL
-
- TEST: OSX/Linux/Windows
-
-5. Teach Bitcoin-Qt to create and submit Payment messages when given
-  a PaymentRequest with a payment_url:
-  DONE Code to POST to a TLS-protected url (let user know if ERROR)
-  DONE Code to parse response and show PaymentACK.memo
diff --git a/c++/README.txt b/c++/README.txt
new file mode 100644
index 0000000..16bd6dc
--- /dev/null
+++ b/c++/README.txt
@@ -0,0 +1,21 @@
+Dependencies:
+  OpenSSL (library and openssl command-line tool)
+  Google Protocol Buffers (library and protoc command-line compiler)
+
+Debian/Ubuntu:
+  apt-get install openssl protobuf
+OSX MacPorts:
+  port install openssl protobuf
+
+To compile:
+  make
+
+The Makefile will create a "certificate authority in a box" in ../ca_in_a_box/ and
+compile command-line tools:
+
+paymentrequest-create  # Prototype code: create a PaymentRequest message
+paymentrequest-verify  # Prototype code: verify a PaymentRequest message
+
+
+Example usage:
+  paymentrequest-create paytoaddress=1BTCorgHwCg6u2YSAWKgS17qUad6kHmtQW memo="Just Testing" amount=11.0 | paymentrequest-dump
diff --git a/c++/paymentrequest-create.cpp b/c++/paymentrequest-create.cpp
index 0de27c0..5fdbc8c 100644
--- a/c++/paymentrequest-create.cpp
+++ b/c++/paymentrequest-create.cpp
@@ -37,7 +37,7 @@
 #include <openssl/x509_vfy.h>
 #include <openssl/evp.h>
 
-#include "paymentrequest.pb.h";
+#include "paymentrequest.pb.h"
 #include <google/protobuf/io/tokenizer.h>  // For string-to-uint64 conversion
 #include "util.h"
 
@@ -352,25 +352,28 @@ int main(int argc, char **argv) {
 
     // Certificate chain:
     X509Certificates certChain;
-    X509 *first_cert = NULL;
-    X509 *last_cert = NULL;
-    EVP_PKEY *pubkey = NULL;
     std::list<string> certFiles = split(params["certificates"], ",");
+    std::vector<X509*> certs;
     for (std::list<string>::iterator it = certFiles.begin(); it != certFiles.end(); it++) {
         X509 *cert = parse_pem_cert(load_file(*it));
-        certChain.add_certificate(x509_to_der(cert));
-        if (first_cert == NULL) {
-            first_cert = cert; // Don't free this yet, need pubkey to stay valid
-            pubkey = X509_get_pubkey(cert);
-        }
-        else {
-            X509_free(cert);
+        if (cert == NULL) {
+            fprintf(stderr, "Could not read %s\n", it->c_str());
+            continue;
         }
-        last_cert = cert;
+        certs.push_back(cert);
+        certChain.add_certificate(x509_to_der(cert));
+    }
+
+    if (certs.empty()) {
+        fprintf(stderr, "Could not load any certificates\n");
+        exit(1);
     }
 
+    // Public key is first certificate:
+    EVP_PKEY *pubkey = X509_get_pubkey(certs.front());
+
     // Fetch any missing intermediate certificates, if we can:
-    fetchParentCerts(certChain, last_cert);
+    fetchParentCerts(certChain, certs.back());
 
     string certChainBytes;
     certChain.SerializeToString(&certChainBytes);
@@ -410,7 +413,10 @@ int main(int argc, char **argv) {
     }
     EVP_MD_CTX_destroy(ctx);
     EVP_PKEY_free(pubkey);
-    X509_free(first_cert);
+    for (std::vector<X509*>::iterator it = certs.begin(); it != certs.end(); it++) {
+        X509_free(*it);
+    }
+    certs.clear();
 
     // We got here, so the signature is self-consistent.
     request.set_signature(signature, actual_signature_len);
diff --git a/c++/paymentrequest-dump.cpp b/c++/paymentrequest-dump.cpp
index 1c4864a..d20e400 100644
--- a/c++/paymentrequest-dump.cpp
+++ b/c++/paymentrequest-dump.cpp
@@ -15,7 +15,7 @@
 #include <openssl/x509.h>
 #include <openssl/x509_vfy.h>
 
-#include "paymentrequest.pb.h";
+#include "paymentrequest.pb.h"
 #include "util.h"
 
 using std::string;
diff --git a/php/demo_website/createpaymentrequest.php b/php/demo_website/createpaymentrequest.php
index bd4aec7..299819d 100755
--- a/php/demo_website/createpaymentrequest.php
+++ b/php/demo_website/createpaymentrequest.php
@@ -66,7 +66,7 @@ function createPaymentRequest($params)
         if (!empty($params[$field])) {
             $output = new \payments\Output();
             $r = address_to_script($params["address".$i]);
-            if ($r[0]) $testnet = true;
+            $testnet = $r[0];
             $output->setScript($r[1]);
 	    $output->setAmount($params["amount".$i]*1.0e8);
 	    $totalAmount += $params["amount".$i];
@@ -183,6 +183,11 @@ function createPaymentRequest($params)
 $validationData['amount3'] = array('type' => 'btcamount');
 
 if (isset($request['submit'])) {
+    // For debugging Tor connections: replace $CLIENT_IP
+    // in memo/ACK_message with client's IP address:
+    $request['memo'] = str_replace('$CLIENT_IP', $_SERVER['REMOTE_ADDR'], $request['memo']);
+    $request['ACK_message'] = str_replace('$CLIENT_IP', $_SERVER['REMOTE_ADDR'], $request['ACK_message']);
+
     $formErrors = validateForm($request, $validationData);
 
     if (count($formErrors) == 0) {
diff --git a/php/demo_website/include/paymentrequest.php b/php/demo_website/include/paymentrequest.php
deleted file mode 120000
index 64c7e5c..0000000
--- a/php/demo_website/include/paymentrequest.php
+++ /dev/null
@@ -1 +0,0 @@
-../../paymentrequest.php
\ No newline at end of file
diff --git a/php/demo_website/include/paymentrequest.php b/php/demo_website/include/paymentrequest.php
new file mode 100644
index 0000000..48f9780
--- /dev/null
+++ b/php/demo_website/include/paymentrequest.php
@@ -0,0 +1,1226 @@
+<?php
+// DO NOT EDIT! Generated by Protobuf-PHP protoc plugin 0.9.4
+// Source: paymentrequest.proto
+//   Date: 2013-04-17 18:43:15
+
+namespace payments {
+
+  class Output extends \DrSlump\Protobuf\Message {
+
+    /**  @var int */
+    public $amount = 0;
+    
+    /**  @var string */
+    public $script = null;
+    
+
+    /** @var \Closure[] */
+    protected static $__extensions = array();
+
+    public static function descriptor()
+    {
+      $descriptor = new \DrSlump\Protobuf\Descriptor(__CLASS__, 'payments.Output');
+
+      // OPTIONAL UINT64 amount = 1
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 1;
+      $f->name      = "amount";
+      $f->type      = \DrSlump\Protobuf::TYPE_UINT64;
+      $f->rule      = \DrSlump\Protobuf::RULE_OPTIONAL;
+      $f->default   = 0;
+      $descriptor->addField($f);
+
+      // REQUIRED BYTES script = 2
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 2;
+      $f->name      = "script";
+      $f->type      = \DrSlump\Protobuf::TYPE_BYTES;
+      $f->rule      = \DrSlump\Protobuf::RULE_REQUIRED;
+      $descriptor->addField($f);
+
+      foreach (self::$__extensions as $cb) {
+        $descriptor->addField($cb(), true);
+      }
+
+      return $descriptor;
+    }
+
+    /**
+     * Check if <amount> has a value
+     *
+     * @return boolean
+     */
+    public function hasAmount(){
+      return $this->_has(1);
+    }
+    
+    /**
+     * Clear <amount> value
+     *
+     * @return \payments\Output
+     */
+    public function clearAmount(){
+      return $this->_clear(1);
+    }
+    
+    /**
+     * Get <amount> value
+     *
+     * @return int
+     */
+    public function getAmount(){
+      return $this->_get(1);
+    }
+    
+    /**
+     * Set <amount> value
+     *
+     * @param int $value
+     * @return \payments\Output
+     */
+    public function setAmount( $value){
+      return $this->_set(1, $value);
+    }
+    
+    /**
+     * Check if <script> has a value
+     *
+     * @return boolean
+     */
+    public function hasScript(){
+      return $this->_has(2);
+    }
+    
+    /**
+     * Clear <script> value
+     *
+     * @return \payments\Output
+     */
+    public function clearScript(){
+      return $this->_clear(2);
+    }
+    
+    /**
+     * Get <script> value
+     *
+     * @return string
+     */
+    public function getScript(){
+      return $this->_get(2);
+    }
+    
+    /**
+     * Set <script> value
+     *
+     * @param string $value
+     * @return \payments\Output
+     */
+    public function setScript( $value){
+      return $this->_set(2, $value);
+    }
+  }
+}
+
+namespace payments {
+
+  class PaymentDetails extends \DrSlump\Protobuf\Message {
+
+    /**  @var string */
+    public $network = "main";
+    
+    /**  @var \payments\Output[]  */
+    public $outputs = array();
+    
+    /**  @var int */
+    public $time = null;
+    
+    /**  @var int */
+    public $expires = null;
+    
+    /**  @var string */
+    public $memo = null;
+    
+    /**  @var string */
+    public $payment_url = null;
+    
+    /**  @var string */
+    public $merchant_data = null;
+    
+
+    /** @var \Closure[] */
+    protected static $__extensions = array();
+
+    public static function descriptor()
+    {
+      $descriptor = new \DrSlump\Protobuf\Descriptor(__CLASS__, 'payments.PaymentDetails');
+
+      // OPTIONAL STRING network = 1
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 1;
+      $f->name      = "network";
+      $f->type      = \DrSlump\Protobuf::TYPE_STRING;
+      $f->rule      = \DrSlump\Protobuf::RULE_OPTIONAL;
+      $f->default   = "main";
+      $descriptor->addField($f);
+
+      // REPEATED MESSAGE outputs = 2
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 2;
+      $f->name      = "outputs";
+      $f->type      = \DrSlump\Protobuf::TYPE_MESSAGE;
+      $f->rule      = \DrSlump\Protobuf::RULE_REPEATED;
+      $f->reference = '\payments\Output';
+      $descriptor->addField($f);
+
+      // REQUIRED UINT64 time = 3
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 3;
+      $f->name      = "time";
+      $f->type      = \DrSlump\Protobuf::TYPE_UINT64;
+      $f->rule      = \DrSlump\Protobuf::RULE_REQUIRED;
+      $descriptor->addField($f);
+
+      // OPTIONAL UINT64 expires = 4
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 4;
+      $f->name      = "expires";
+      $f->type      = \DrSlump\Protobuf::TYPE_UINT64;
+      $f->rule      = \DrSlump\Protobuf::RULE_OPTIONAL;
+      $descriptor->addField($f);
+
+      // OPTIONAL STRING memo = 5
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 5;
+      $f->name      = "memo";
+      $f->type      = \DrSlump\Protobuf::TYPE_STRING;
+      $f->rule      = \DrSlump\Protobuf::RULE_OPTIONAL;
+      $descriptor->addField($f);
+
+      // OPTIONAL STRING payment_url = 6
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 6;
+      $f->name      = "payment_url";
+      $f->type      = \DrSlump\Protobuf::TYPE_STRING;
+      $f->rule      = \DrSlump\Protobuf::RULE_OPTIONAL;
+      $descriptor->addField($f);
+
+      // OPTIONAL BYTES merchant_data = 7
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 7;
+      $f->name      = "merchant_data";
+      $f->type      = \DrSlump\Protobuf::TYPE_BYTES;
+      $f->rule      = \DrSlump\Protobuf::RULE_OPTIONAL;
+      $descriptor->addField($f);
+
+      foreach (self::$__extensions as $cb) {
+        $descriptor->addField($cb(), true);
+      }
+
+      return $descriptor;
+    }
+
+    /**
+     * Check if <network> has a value
+     *
+     * @return boolean
+     */
+    public function hasNetwork(){
+      return $this->_has(1);
+    }
+    
+    /**
+     * Clear <network> value
+     *
+     * @return \payments\PaymentDetails
+     */
+    public function clearNetwork(){
+      return $this->_clear(1);
+    }
+    
+    /**
+     * Get <network> value
+     *
+     * @return string
+     */
+    public function getNetwork(){
+      return $this->_get(1);
+    }
+    
+    /**
+     * Set <network> value
+     *
+     * @param string $value
+     * @return \payments\PaymentDetails
+     */
+    public function setNetwork( $value){
+      return $this->_set(1, $value);
+    }
+    
+    /**
+     * Check if <outputs> has a value
+     *
+     * @return boolean
+     */
+    public function hasOutputs(){
+      return $this->_has(2);
+    }
+    
+    /**
+     * Clear <outputs> value
+     *
+     * @return \payments\PaymentDetails
+     */
+    public function clearOutputs(){
+      return $this->_clear(2);
+    }
+    
+    /**
+     * Get <outputs> value
+     *
+     * @param int $idx
+     * @return \payments\Output
+     */
+    public function getOutputs($idx = NULL){
+      return $this->_get(2, $idx);
+    }
+    
+    /**
+     * Set <outputs> value
+     *
+     * @param \payments\Output $value
+     * @return \payments\PaymentDetails
+     */
+    public function setOutputs(\payments\Output $value, $idx = NULL){
+      return $this->_set(2, $value, $idx);
+    }
+    
+    /**
+     * Get all elements of <outputs>
+     *
+     * @return \payments\Output[]
+     */
+    public function getOutputsList(){
+     return $this->_get(2);
+    }
+    
+    /**
+     * Add a new element to <outputs>
+     *
+     * @param \payments\Output $value
+     * @return \payments\PaymentDetails
+     */
+    public function addOutputs(\payments\Output $value){
+     return $this->_add(2, $value);
+    }
+    
+    /**
+     * Check if <time> has a value
+     *
+     * @return boolean
+     */
+    public function hasTime(){
+      return $this->_has(3);
+    }
+    
+    /**
+     * Clear <time> value
+     *
+     * @return \payments\PaymentDetails
+     */
+    public function clearTime(){
+      return $this->_clear(3);
+    }
+    
+    /**
+     * Get <time> value
+     *
+     * @return int
+     */
+    public function getTime(){
+      return $this->_get(3);
+    }
+    
+    /**
+     * Set <time> value
+     *
+     * @param int $value
+     * @return \payments\PaymentDetails
+     */
+    public function setTime( $value){
+      return $this->_set(3, $value);
+    }
+    
+    /**
+     * Check if <expires> has a value
+     *
+     * @return boolean
+     */
+    public function hasExpires(){
+      return $this->_has(4);
+    }
+    
+    /**
+     * Clear <expires> value
+     *
+     * @return \payments\PaymentDetails
+     */
+    public function clearExpires(){
+      return $this->_clear(4);
+    }
+    
+    /**
+     * Get <expires> value
+     *
+     * @return int
+     */
+    public function getExpires(){
+      return $this->_get(4);
+    }
+    
+    /**
+     * Set <expires> value
+     *
+     * @param int $value
+     * @return \payments\PaymentDetails
+     */
+    public function setExpires( $value){
+      return $this->_set(4, $value);
+    }
+    
+    /**
+     * Check if <memo> has a value
+     *
+     * @return boolean
+     */
+    public function hasMemo(){
+      return $this->_has(5);
+    }
+    
+    /**
+     * Clear <memo> value
+     *
+     * @return \payments\PaymentDetails
+     */
+    public function clearMemo(){
+      return $this->_clear(5);
+    }
+    
+    /**
+     * Get <memo> value
+     *
+     * @return string
+     */
+    public function getMemo(){
+      return $this->_get(5);
+    }
+    
+    /**
+     * Set <memo> value
+     *
+     * @param string $value
+     * @return \payments\PaymentDetails
+     */
+    public function setMemo( $value){
+      return $this->_set(5, $value);
+    }
+    
+    /**
+     * Check if <payment_url> has a value
+     *
+     * @return boolean
+     */
+    public function hasPaymentUrl(){
+      return $this->_has(6);
+    }
+    
+    /**
+     * Clear <payment_url> value
+     *
+     * @return \payments\PaymentDetails
+     */
+    public function clearPaymentUrl(){
+      return $this->_clear(6);
+    }
+    
+    /**
+     * Get <payment_url> value
+     *
+     * @return string
+     */
+    public function getPaymentUrl(){
+      return $this->_get(6);
+    }
+    
+    /**
+     * Set <payment_url> value
+     *
+     * @param string $value
+     * @return \payments\PaymentDetails
+     */
+    public function setPaymentUrl( $value){
+      return $this->_set(6, $value);
+    }
+    
+    /**
+     * Check if <merchant_data> has a value
+     *
+     * @return boolean
+     */
+    public function hasMerchantData(){
+      return $this->_has(7);
+    }
+    
+    /**
+     * Clear <merchant_data> value
+     *
+     * @return \payments\PaymentDetails
+     */
+    public function clearMerchantData(){
+      return $this->_clear(7);
+    }
+    
+    /**
+     * Get <merchant_data> value
+     *
+     * @return string
+     */
+    public function getMerchantData(){
+      return $this->_get(7);
+    }
+    
+    /**
+     * Set <merchant_data> value
+     *
+     * @param string $value
+     * @return \payments\PaymentDetails
+     */
+    public function setMerchantData( $value){
+      return $this->_set(7, $value);
+    }
+  }
+}
+
+namespace payments {
+
+  class PaymentRequest extends \DrSlump\Protobuf\Message {
+
+    /**  @var int */
+    public $payment_details_version = 1;
+    
+    /**  @var string */
+    public $pki_type = "none";
+    
+    /**  @var string */
+    public $pki_data = null;
+    
+    /**  @var string */
+    public $serialized_payment_details = null;
+    
+    /**  @var string */
+    public $signature = null;
+    
+
+    /** @var \Closure[] */
+    protected static $__extensions = array();
+
+    public static function descriptor()
+    {
+      $descriptor = new \DrSlump\Protobuf\Descriptor(__CLASS__, 'payments.PaymentRequest');
+
+      // OPTIONAL UINT32 payment_details_version = 1
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 1;
+      $f->name      = "payment_details_version";
+      $f->type      = \DrSlump\Protobuf::TYPE_UINT32;
+      $f->rule      = \DrSlump\Protobuf::RULE_OPTIONAL;
+      $f->default   = 1;
+      $descriptor->addField($f);
+
+      // OPTIONAL STRING pki_type = 2
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 2;
+      $f->name      = "pki_type";
+      $f->type      = \DrSlump\Protobuf::TYPE_STRING;
+      $f->rule      = \DrSlump\Protobuf::RULE_OPTIONAL;
+      $f->default   = "none";
+      $descriptor->addField($f);
+
+      // OPTIONAL BYTES pki_data = 3
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 3;
+      $f->name      = "pki_data";
+      $f->type      = \DrSlump\Protobuf::TYPE_BYTES;
+      $f->rule      = \DrSlump\Protobuf::RULE_OPTIONAL;
+      $descriptor->addField($f);
+
+      // REQUIRED BYTES serialized_payment_details = 4
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 4;
+      $f->name      = "serialized_payment_details";
+      $f->type      = \DrSlump\Protobuf::TYPE_BYTES;
+      $f->rule      = \DrSlump\Protobuf::RULE_REQUIRED;
+      $descriptor->addField($f);
+
+      // OPTIONAL BYTES signature = 5
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 5;
+      $f->name      = "signature";
+      $f->type      = \DrSlump\Protobuf::TYPE_BYTES;
+      $f->rule      = \DrSlump\Protobuf::RULE_OPTIONAL;
+      $descriptor->addField($f);
+
+      foreach (self::$__extensions as $cb) {
+        $descriptor->addField($cb(), true);
+      }
+
+      return $descriptor;
+    }
+
+    /**
+     * Check if <payment_details_version> has a value
+     *
+     * @return boolean
+     */
+    public function hasPaymentDetailsVersion(){
+      return $this->_has(1);
+    }
+    
+    /**
+     * Clear <payment_details_version> value
+     *
+     * @return \payments\PaymentRequest
+     */
+    public function clearPaymentDetailsVersion(){
+      return $this->_clear(1);
+    }
+    
+    /**
+     * Get <payment_details_version> value
+     *
+     * @return int
+     */
+    public function getPaymentDetailsVersion(){
+      return $this->_get(1);
+    }
+    
+    /**
+     * Set <payment_details_version> value
+     *
+     * @param int $value
+     * @return \payments\PaymentRequest
+     */
+    public function setPaymentDetailsVersion( $value){
+      return $this->_set(1, $value);
+    }
+    
+    /**
+     * Check if <pki_type> has a value
+     *
+     * @return boolean
+     */
+    public function hasPkiType(){
+      return $this->_has(2);
+    }
+    
+    /**
+     * Clear <pki_type> value
+     *
+     * @return \payments\PaymentRequest
+     */
+    public function clearPkiType(){
+      return $this->_clear(2);
+    }
+    
+    /**
+     * Get <pki_type> value
+     *
+     * @return string
+     */
+    public function getPkiType(){
+      return $this->_get(2);
+    }
+    
+    /**
+     * Set <pki_type> value
+     *
+     * @param string $value
+     * @return \payments\PaymentRequest
+     */
+    public function setPkiType( $value){
+      return $this->_set(2, $value);
+    }
+    
+    /**
+     * Check if <pki_data> has a value
+     *
+     * @return boolean
+     */
+    public function hasPkiData(){
+      return $this->_has(3);
+    }
+    
+    /**
+     * Clear <pki_data> value
+     *
+     * @return \payments\PaymentRequest
+     */
+    public function clearPkiData(){
+      return $this->_clear(3);
+    }
+    
+    /**
+     * Get <pki_data> value
+     *
+     * @return string
+     */
+    public function getPkiData(){
+      return $this->_get(3);
+    }
+    
+    /**
+     * Set <pki_data> value
+     *
+     * @param string $value
+     * @return \payments\PaymentRequest
+     */
+    public function setPkiData( $value){
+      return $this->_set(3, $value);
+    }
+    
+    /**
+     * Check if <serialized_payment_details> has a value
+     *
+     * @return boolean
+     */
+    public function hasSerializedPaymentDetails(){
+      return $this->_has(4);
+    }
+    
+    /**
+     * Clear <serialized_payment_details> value
+     *
+     * @return \payments\PaymentRequest
+     */
+    public function clearSerializedPaymentDetails(){
+      return $this->_clear(4);
+    }
+    
+    /**
+     * Get <serialized_payment_details> value
+     *
+     * @return string
+     */
+    public function getSerializedPaymentDetails(){
+      return $this->_get(4);
+    }
+    
+    /**
+     * Set <serialized_payment_details> value
+     *
+     * @param string $value
+     * @return \payments\PaymentRequest
+     */
+    public function setSerializedPaymentDetails( $value){
+      return $this->_set(4, $value);
+    }
+    
+    /**
+     * Check if <signature> has a value
+     *
+     * @return boolean
+     */
+    public function hasSignature(){
+      return $this->_has(5);
+    }
+    
+    /**
+     * Clear <signature> value
+     *
+     * @return \payments\PaymentRequest
+     */
+    public function clearSignature(){
+      return $this->_clear(5);
+    }
+    
+    /**
+     * Get <signature> value
+     *
+     * @return string
+     */
+    public function getSignature(){
+      return $this->_get(5);
+    }
+    
+    /**
+     * Set <signature> value
+     *
+     * @param string $value
+     * @return \payments\PaymentRequest
+     */
+    public function setSignature( $value){
+      return $this->_set(5, $value);
+    }
+  }
+}
+
+namespace payments {
+
+  class X509Certificates extends \DrSlump\Protobuf\Message {
+
+    /**  @var string[]  */
+    public $certificate = array();
+    
+
+    /** @var \Closure[] */
+    protected static $__extensions = array();
+
+    public static function descriptor()
+    {
+      $descriptor = new \DrSlump\Protobuf\Descriptor(__CLASS__, 'payments.X509Certificates');
+
+      // REPEATED BYTES certificate = 1
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 1;
+      $f->name      = "certificate";
+      $f->type      = \DrSlump\Protobuf::TYPE_BYTES;
+      $f->rule      = \DrSlump\Protobuf::RULE_REPEATED;
+      $descriptor->addField($f);
+
+      foreach (self::$__extensions as $cb) {
+        $descriptor->addField($cb(), true);
+      }
+
+      return $descriptor;
+    }
+
+    /**
+     * Check if <certificate> has a value
+     *
+     * @return boolean
+     */
+    public function hasCertificate(){
+      return $this->_has(1);
+    }
+    
+    /**
+     * Clear <certificate> value
+     *
+     * @return \payments\X509Certificates
+     */
+    public function clearCertificate(){
+      return $this->_clear(1);
+    }
+    
+    /**
+     * Get <certificate> value
+     *
+     * @param int $idx
+     * @return string
+     */
+    public function getCertificate($idx = NULL){
+      return $this->_get(1, $idx);
+    }
+    
+    /**
+     * Set <certificate> value
+     *
+     * @param string $value
+     * @return \payments\X509Certificates
+     */
+    public function setCertificate( $value, $idx = NULL){
+      return $this->_set(1, $value, $idx);
+    }
+    
+    /**
+     * Get all elements of <certificate>
+     *
+     * @return string[]
+     */
+    public function getCertificateList(){
+     return $this->_get(1);
+    }
+    
+    /**
+     * Add a new element to <certificate>
+     *
+     * @param string $value
+     * @return \payments\X509Certificates
+     */
+    public function addCertificate( $value){
+     return $this->_add(1, $value);
+    }
+  }
+}
+
+namespace payments {
+
+  class Payment extends \DrSlump\Protobuf\Message {
+
+    /**  @var string */
+    public $merchant_data = null;
+    
+    /**  @var string[]  */
+    public $transactions = array();
+    
+    /**  @var \payments\Output[]  */
+    public $refund_to = array();
+    
+    /**  @var string */
+    public $memo = null;
+    
+
+    /** @var \Closure[] */
+    protected static $__extensions = array();
+
+    public static function descriptor()
+    {
+      $descriptor = new \DrSlump\Protobuf\Descriptor(__CLASS__, 'payments.Payment');
+
+      // OPTIONAL BYTES merchant_data = 1
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 1;
+      $f->name      = "merchant_data";
+      $f->type      = \DrSlump\Protobuf::TYPE_BYTES;
+      $f->rule      = \DrSlump\Protobuf::RULE_OPTIONAL;
+      $descriptor->addField($f);
+
+      // REPEATED BYTES transactions = 2
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 2;
+      $f->name      = "transactions";
+      $f->type      = \DrSlump\Protobuf::TYPE_BYTES;
+      $f->rule      = \DrSlump\Protobuf::RULE_REPEATED;
+      $descriptor->addField($f);
+
+      // REPEATED MESSAGE refund_to = 3
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 3;
+      $f->name      = "refund_to";
+      $f->type      = \DrSlump\Protobuf::TYPE_MESSAGE;
+      $f->rule      = \DrSlump\Protobuf::RULE_REPEATED;
+      $f->reference = '\payments\Output';
+      $descriptor->addField($f);
+
+      // OPTIONAL STRING memo = 4
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 4;
+      $f->name      = "memo";
+      $f->type      = \DrSlump\Protobuf::TYPE_STRING;
+      $f->rule      = \DrSlump\Protobuf::RULE_OPTIONAL;
+      $descriptor->addField($f);
+
+      foreach (self::$__extensions as $cb) {
+        $descriptor->addField($cb(), true);
+      }
+
+      return $descriptor;
+    }
+
+    /**
+     * Check if <merchant_data> has a value
+     *
+     * @return boolean
+     */
+    public function hasMerchantData(){
+      return $this->_has(1);
+    }
+    
+    /**
+     * Clear <merchant_data> value
+     *
+     * @return \payments\Payment
+     */
+    public function clearMerchantData(){
+      return $this->_clear(1);
+    }
+    
+    /**
+     * Get <merchant_data> value
+     *
+     * @return string
+     */
+    public function getMerchantData(){
+      return $this->_get(1);
+    }
+    
+    /**
+     * Set <merchant_data> value
+     *
+     * @param string $value
+     * @return \payments\Payment
+     */
+    public function setMerchantData( $value){
+      return $this->_set(1, $value);
+    }
+    
+    /**
+     * Check if <transactions> has a value
+     *
+     * @return boolean
+     */
+    public function hasTransactions(){
+      return $this->_has(2);
+    }
+    
+    /**
+     * Clear <transactions> value
+     *
+     * @return \payments\Payment
+     */
+    public function clearTransactions(){
+      return $this->_clear(2);
+    }
+    
+    /**
+     * Get <transactions> value
+     *
+     * @param int $idx
+     * @return string
+     */
+    public function getTransactions($idx = NULL){
+      return $this->_get(2, $idx);
+    }
+    
+    /**
+     * Set <transactions> value
+     *
+     * @param string $value
+     * @return \payments\Payment
+     */
+    public function setTransactions( $value, $idx = NULL){
+      return $this->_set(2, $value, $idx);
+    }
+    
+    /**
+     * Get all elements of <transactions>
+     *
+     * @return string[]
+     */
+    public function getTransactionsList(){
+     return $this->_get(2);
+    }
+    
+    /**
+     * Add a new element to <transactions>
+     *
+     * @param string $value
+     * @return \payments\Payment
+     */
+    public function addTransactions( $value){
+     return $this->_add(2, $value);
+    }
+    
+    /**
+     * Check if <refund_to> has a value
+     *
+     * @return boolean
+     */
+    public function hasRefundTo(){
+      return $this->_has(3);
+    }
+    
+    /**
+     * Clear <refund_to> value
+     *
+     * @return \payments\Payment
+     */
+    public function clearRefundTo(){
+      return $this->_clear(3);
+    }
+    
+    /**
+     * Get <refund_to> value
+     *
+     * @param int $idx
+     * @return \payments\Output
+     */
+    public function getRefundTo($idx = NULL){
+      return $this->_get(3, $idx);
+    }
+    
+    /**
+     * Set <refund_to> value
+     *
+     * @param \payments\Output $value
+     * @return \payments\Payment
+     */
+    public function setRefundTo(\payments\Output $value, $idx = NULL){
+      return $this->_set(3, $value, $idx);
+    }
+    
+    /**
+     * Get all elements of <refund_to>
+     *
+     * @return \payments\Output[]
+     */
+    public function getRefundToList(){
+     return $this->_get(3);
+    }
+    
+    /**
+     * Add a new element to <refund_to>
+     *
+     * @param \payments\Output $value
+     * @return \payments\Payment
+     */
+    public function addRefundTo(\payments\Output $value){
+     return $this->_add(3, $value);
+    }
+    
+    /**
+     * Check if <memo> has a value
+     *
+     * @return boolean
+     */
+    public function hasMemo(){
+      return $this->_has(4);
+    }
+    
+    /**
+     * Clear <memo> value
+     *
+     * @return \payments\Payment
+     */
+    public function clearMemo(){
+      return $this->_clear(4);
+    }
+    
+    /**
+     * Get <memo> value
+     *
+     * @return string
+     */
+    public function getMemo(){
+      return $this->_get(4);
+    }
+    
+    /**
+     * Set <memo> value
+     *
+     * @param string $value
+     * @return \payments\Payment
+     */
+    public function setMemo( $value){
+      return $this->_set(4, $value);
+    }
+  }
+}
+
+namespace payments {
+
+  class PaymentACK extends \DrSlump\Protobuf\Message {
+
+    /**  @var \payments\Payment */
+    public $payment = null;
+    
+    /**  @var string */
+    public $memo = null;
+    
+
+    /** @var \Closure[] */
+    protected static $__extensions = array();
+
+    public static function descriptor()
+    {
+      $descriptor = new \DrSlump\Protobuf\Descriptor(__CLASS__, 'payments.PaymentACK');
+
+      // REQUIRED MESSAGE payment = 1
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 1;
+      $f->name      = "payment";
+      $f->type      = \DrSlump\Protobuf::TYPE_MESSAGE;
+      $f->rule      = \DrSlump\Protobuf::RULE_REQUIRED;
+      $f->reference = '\payments\Payment';
+      $descriptor->addField($f);
+
+      // OPTIONAL STRING memo = 2
+      $f = new \DrSlump\Protobuf\Field();
+      $f->number    = 2;
+      $f->name      = "memo";
+      $f->type      = \DrSlump\Protobuf::TYPE_STRING;
+      $f->rule      = \DrSlump\Protobuf::RULE_OPTIONAL;
+      $descriptor->addField($f);
+
+      foreach (self::$__extensions as $cb) {
+        $descriptor->addField($cb(), true);
+      }
+
+      return $descriptor;
+    }
+
+    /**
+     * Check if <payment> has a value
+     *
+     * @return boolean
+     */
+    public function hasPayment(){
+      return $this->_has(1);
+    }
+    
+    /**
+     * Clear <payment> value
+     *
+     * @return \payments\PaymentACK
+     */
+    public function clearPayment(){
+      return $this->_clear(1);
+    }
+    
+    /**
+     * Get <payment> value
+     *
+     * @return \payments\Payment
+     */
+    public function getPayment(){
+      return $this->_get(1);
+    }
+    
+    /**
+     * Set <payment> value
+     *
+     * @param \payments\Payment $value
+     * @return \payments\PaymentACK
+     */
+    public function setPayment(\payments\Payment $value){
+      return $this->_set(1, $value);
+    }
+    
+    /**
+     * Check if <memo> has a value
+     *
+     * @return boolean
+     */
+    public function hasMemo(){
+      return $this->_has(2);
+    }
+    
+    /**
+     * Clear <memo> value
+     *
+     * @return \payments\PaymentACK
+     */
+    public function clearMemo(){
+      return $this->_clear(2);
+    }
+    
+    /**
+     * Get <memo> value
+     *
+     * @return string
+     */
+    public function getMemo(){
+      return $this->_get(2);
+    }
+    
+    /**
+     * Set <memo> value
+     *
+     * @param string $value
+     * @return \payments\PaymentACK
+     */
+    public function setMemo( $value){
+      return $this->_set(2, $value);
+    }
+  }
+}
+
diff --git a/spec.rst b/spec.rst
deleted file mode 100644
index 767e4cb..0000000
--- a/spec.rst
+++ /dev/null
@@ -1,297 +0,0 @@
-Bitcoin Payment Messages
-========================
-
-This document proposes protocol buffer-based formats for a simple payment protocol between a customer's bitcoin client software and a merchant.
-
-Separate documents will propose an extension to the Bitcoin URI syntax and new MIME types to support them.
-
-Motivation
-==========
-
-The idea of a "payment protocol" to improve on Bitcoin addresses has been around for over a year. Users have been asking for some features in this proposal (like the ability to provide a refund address so overpayments or refunds can be returned to customers without the need to ask them for their address) for two or three years, and have started to work around shortcomings in the Bitcoin payment process with creative (but inefficient) uses of transactions.
-
-The key features of this proposal are:
-
-+ Requests for payment (PaymentRequests) are tied to authenticated identities using the only widely-deployed identity authentication system we have right now (X.509 certificates signed by root certificate authorities)
-+ PaymentRequests include a user-friendly description of what the payment is for
-+ Payments include information on where refunds should be sent
-+ At the end of the payment process, the customer has a PaymentRequest and bitcoin transaction that can be used as proof-of-payment if there is any dispute with the merchant.
-
-
-Specification
-=============
-
-PaymentDetails/PaymentRequest
----------------------
-
-An Output specifies where payment (or part of a payment) should be sent:
-
-::
-
-    message Output {
-	optional uint64 amount = 1 [default = 0];
-        optional bytes script = 2;
-    }
-
-amount: Number of satoshis (0.00000001 BTC) to be paid.
-
-script: a "TxOut" script where payment should be sent. This will normally be one of the standard Bitcoin transaction scripts (e.g. pubkey OP_CHECKSIG). This is optional to enable future extensions to this protocol that derive Outputs from a master public key and the PaymentRequest data itself.
-
-Payment requests are split into two messages to support future extensibility. The bulk of the information is contained in the PaymentDetails message. It is wrapped inside a PaymentRequest message, which may contain meta-information about the merchant and a digital signature.
-
-::
-
-    message PaymentDetails {
-        optional string network = 1 [default = "main"];
-        repeated Output outputs = 2;
-        required uint64 time = 3;
-        optional uint64 expires = 4;
-        optional string memo = 5;
-        optional string payment_url = 6;
-        optional bytes merchant_data = 7;
-    }        
-
-network: either "main" for payments on the production Bitcoin network, or "test" for payments on test network. If a client receives a PaymentRequest for a network it does not support it must reject the request.
-
-outputs: one or more outputs where Bitcoins are to be sent. If the sum of outputs.amount is zero, the customer will be asked how much to pay, and the bitcoin client may choose any or all of the Outputs (if there are more than one) for payment. If the sum of outputs.amount is non-zero, then the customer will be asked to pay the sum, and the payment shall be split among the Outputs with non-zero amounts (if there are more than one; Outputs with zero amounts shall be ignored). 
-
-time: Unix timestamp (seconds since 1-Jan-1970) when the PaymentRequest was created.
-
-expires: Unix timestamp after which the PaymentRequest should be considered invalid.
-
-memo: UTF-8 encoded, plain-text (no formatting) note that should be displayed to the customer, explaining what this PaymentRequest is for.
-
-payment_url: Secure (usually https) location where a Payment message (see below) may be sent to obtain a PaymentACK.
-
-merchant_data : Arbitrary data that may be used by the merchant to identify the PaymentRequest. May be omitted if the merchant does not need to associate Payments with PaymentRequest or if they associate each PaymentRequest with a separate payment address.
-
-A PaymentRequest is PaymentDetails cryptographically tied to a merchant's identity:
-
-::
-
-    message PaymentRequest {
-        optional uint32 payment_details_version = 1 [default = 1];
-        optional string pki_type = 2 [default = "none"];
-        optional bytes pki_data = 3;
-        required bytes serialized_payment_details = 4;
-        optional bytes signature = 5;
-    }
-
-payment_details_version: See below for a discussion of versioning/upgrading. 
-
-pki_type : public-key infrastructure (PKI) system being used to identify the merchant. All implementation should support "none", "x509+sha256" and "x509+sha1".
-
-pki_data: PKI-system data that identifies the merchant and can be used to create a digital signature. In the case of X.509 certificates, pki_data one or more X.509 certificates (see Certificates section below).
-
-serialized_payment_details: A protocol-buffer serialized PaymentDetails message.
-
-signature: digital signature over a hash of the protocol buffer serialized variation of the PaymentRequest message, where signature is a zero-byte array and fields are serialized in numerical order (all current protocol buffer implementations serialize fields in numerical order), using the public key in pki_data.
-
-When a Bitcoin client receives a PaymentRequest, it must authorize payment by doing the following:
-
-1. Validate the merchant's identity and signature using the PKI system (e.g. validate the X.509 certificates in pki_data up to a list of root certificate authorities, extract the public key from the first certificate, and validate the signature).
-2. Validate that the time on the customer's system is before PaymentDetails.expires
-3. Display the merchant's identity and ask the customer if they would like to submit payment (e.g. display the "Common Name" in the first X.509 certificate). In the case of pki_type = "none", it should be made obvious to the user that the identity of the payee has not been verified.
-
-**TODO**: develop best practices for warning the customer of the dangers of accepting unsigned PaymentRequests:  potential man-in-the-middle attacks if the request came over an insecure connection, and possibility that their trading partner will repudiate payment.
-
-Payment
--------
-
-::
-
-    message Payment {
-        optional bytes merchant_data = 1;
-        repeated bytes transactions = 2;
-        repeated Output refund_to = 3;
-        optional string memo = 4;
-    }
-
-merchant_data : copied from PaymentDetails.merchant_data. Merchants may use invoice numbers or any other data they require to match Payments to PaymentRequests.
-
-transactions : One or more valid, signed Bitcoin transactions that fully pay the PaymentRequest
-
-refund_to : One or more outputs where the merchant may return funds, if necessary.
-
-memo : UTF-8 encoded, plain-text note from the customer to the merchant.
-
-If the customer authorizes payment, then the Bitcoin client:
-
-1. Creates and signs one or more transactions that satisfy (pay in full) PaymentDetails.outputs
-2. Broadcast the transactions on the Bitcoin p2p network.
-3. If PaymentDetails.payment_url is specified, POST a Payment message to that URL. The Payment message is serialized and sent as the body of the POST request.
-4. If a PaymentACK is received in response to the Payment message, PaymentACK.memo should be displayed to the user.
-
-Errors communicating with the payment_url server should be communicated to the user.
-
-PaymentDetails.payment_url must be secure against man-in-the-middle attacks that might alter Payment.refund_to (if using HTTP, it must be TLS-protected).
-
-A merchant receiving a Payment will determine whether or not the transactions satisfy conditions of payment, and, if and only if they do, broadcast the transactions on the Bitcoin p2p network. It must return a PaymentACK with a message letting the customer know the status of their transaction.
-
-PaymentACK
----------------------
-
-::
-
-    message PaymentACK {
-        required Payment payment = 1;
-        optional string memo = 2;
-    }
-
-memo : UTF-8 encoded note that should be displayed to the customer giving the status of the transaction (e.g. "Payment of 1 BTC for eleven tribbles accepted for processing.")
-
-::
-
-Upon receiving a PaymentACK, a Bitcoin client should display the PaymentACK.memo to the customer.
-
-Once broadcast on the Bitcon p2p network, payments are like any other Bitcoin transaction and may be confirmed or not.
-
-A note on localization
-----------------------
-
-Merchants that support multiple languages should generate language-specific PaymentRequests, and either associate the language with the request or embed a language tag in the request's merchant_data. They should also generate a language-specific PaymentACK based on the original request.
-
-For example: A greek-speaking customer browsing the Greek version of a merchant's website clicks on a "Αγορά τώρα" link, which generates a PaymentRequest with merchant_data set to "lang=el&basketId=11252". The customer pays, their bitcoin client sends a Payment message, and the merchant's website responds with PaymentACK.message "σας ευχαριστούμε" .
-
-Certificates
-============
-
-The default PKI system is X.509 certificates (the same system used to authenticate web servers). The format of pki_data when pki_type is "x509+sha256" or "x509+sha1" is a protocol-buffer-encoded certificate chain [RFC5280]:
-
-::
-
-    message X509Certificates {
-        repeated bytes certificate = 1;
-    }
-
-If pki_type is "x509+sha256", then the Payment message is hashed using the SHA256 algorithm to produce the message digest that is signed. If pki_type is "x509+sha1", then the SHA1 algorithm is used.
-
-Each certificate is a DER [ITU.X690.1994] PKIX certificate value. The certificate containing the public key of the entity that digitally signed the PaymentRequest MUST be the first certificate. This MAY be followed by additional certificates, with each subsequent certificate being the one used to certify the previous one. The recipient MUST verify the certificate chain according to [RFC5280] and reject the PaymentRequest if any validation failure occurs.
-
-*Issue:* What should we say about root certificates and certificate management in general? Any requirements, or leave it up to each Bitcoin client to determine which root CA's are trustworthy, as happens with web browsers? Proposal: by default, use the system's list of root certificates, which should be kept up-to-date with system software updates. But allow technical or paranoid users to override with a list of their own.
-
-*Issue:* Specify a maximum certificate chain length, to avoid DoS or other potential attacks? What is the maximum chain length that reputable certificate issuing authorities use?  Proposal: maximum 50,000 bytes for the entire PaymentRequest message, which is plenty for any reasonable size certificate chain.
-
-*Potential extension:* add 'bytes ocsp_response' for an optional "stapled" OCSP reponse (http://en.wikipedia.org/wiki/OCSP_Stapling) to prove the merchant certificate hasn't been revoked.
-
-Extensibility / Upgrading
-=========================
-
-The protocol buffers serialization format is designed to be extensible. In particular, new, optional fields can be added to a message and will be ignored (but saved/re-transmitted) by old implementations.
-
-PaymentDetails messages may be extended with new optional fields and still be considered "version 1." Old implementations will be able to validate signatures against PaymentRequests containing the new fields, but (obviously) will not be able to display whatever information is contained in the new, optional fields to the user.
-
-If it becomes necessary at some point in the future for merchants to produce PaymentRequest messages that are accepted *only* by new implementations, they can do so by defining a new PaymentDetails message with version=2. Old implementations should let the user know that they need to upgrade their software when they get an up-version PaymentDetails message.
-
-Implementations that need to extend messages in this specification shall use tags starting at 1000, and shall update the wiki page at https://en.bitcoin.it/wiki/Payment_Request to avoid conflicts with other extensions.
-
-
-Use Cases
-=========
-
-Merchant Payment Service
-------------------------
-
-A merchant payment service (like Paysius or bit-pay.com) would use PaymentRequests and PaymentACKs as follows:
-
-1. Merchant pays for a certificate from a certificate authority, and then gives the payment service the certificate and their private key. This could be the same certificate and private key as is used for the merchant's web site, but best security practice would be to purchase a separate certificate for authenticating PaymentRequests. Very successful merchant payment services might act as intermediate certificate authorities, issuing certificates for their merchants.
-2. Customer goes through the checkout process on either the merchant's or payment service's web site.
-3. At the end of the checkout process, a PaymentRequest is generated and sent to the customer's Bitcoin client.
-4. Customer's Bitcoin client displays the PaymentRequest, showing that the payment is for the merchant.
-5. On customer approval, a Payment is sent to the payment service's paymentURI. The merchant is notified of the payment, and the customer receives a PaymentACK.
-6. The payment service broadcasts the Payment.transactions, and the customer's Bitcoin client show the transaction as it is confirmed. The merchant ships product to the customer when the transaction has N confirmations.
-
-Immediate-feedback Transactions
--------------------------------
-
-SatoshiDice (www.satoshidice.com) and similar very popular games use tiny transactions for customer/service communication. In particular, customers can add an extra output to their transactions to indicate where winnings should be sent. And they create tiny transactions as a way of telling customers that their bet was received, but lost.
-
-Assuming Bitcoin clients upgrade to support this proposal, a bet on SatoshiDice would proceed as follows:
-
-1. Customer clicks on a link on SatoshiDice.com and their Bitcoin client receives a PaymentRequest.
-2. Customer authorizes payment, and their Bitcoin client creates a Payment message and submits it directly to https://satoshidice.com/something
-3. The SatoshiDice web server checks to make sure the transaction is valid, broadcasts it, and determines whether the customer wins or loses. It returns a PaymentACK with either a "You win" or "You lost" memo.
-4. If the customer won, it broadcasts a transaction to pay them using Payment.refund_to
-5. Customer's Bitcoin client displays the win/lose memo, and if they won the winnings appear in their wallet when received over the p2p network.
-
-Using a Payment message to specify where winning should be sent instead of an extra send-to-self output makes the customer-to-merchant transactions about 30% smaller on average.  And using a PaymentACK message to let the customer know that they did not win avoids a blockchain transaction entirely.
-
-Multiperson Wallet
-------------------
-
-This use case starts with a multi-signature Bitcoin address or wallet, with keys held by two different people (Alice and Bob). Payments from that address/wallet must be authorized by both Alice and Bob, and both are running multi-signature-capable Bitcoin clients.
-
-Alice begins the payment process by getting a PaymentRequest from a merchant that needs to be paid. She authorizes payment and her Bitcoin client creates a Payment message with a partially-signed transaction, which is then sent to Bob any way that is convenient (email attachment, smoke signals...).
-
-Bob's Bitcoin client validates the PaymentRequest and asks Bob to authorize the transaction. He says OK, his Bitcoin client completes the transaction by providing his signature, submits the payment to the merchant, and then sends a message to Alice with the PaymentACK he received from the merchant, completing the payment process.
-
-
-Design Notes
-============
-
-Why X.509 Certificates?
------------------------
-
-This proposal uses X.509 certificates as the identity system for merchants because most of them will have already purchased a certificate to secure their website and will be familiar with the process of proving their identity to a certificate issuing authority.
-
-Implementing a better global PKI infrastructure is outside the scope of this proposal. If a better PKI infrastructure is adopted, the only change to this proposal would be to add a new pki_type and new formats for pki_data and signature with whatever that better infrastructure uses to identify entities.
-
-
-Why not JSON?
--------------
-
-PaymentRequest, Payment and PaymentACK messages could all be JSON-encoded. The Javascript Object Signing and Encryption (JOSE) working group at the IETF has a draft specification for signing JSON data that we could adopt and use.
-
-But the spec is non-trivial. Signing JSON data is troublesome, so JSON that needs to be signed must be base64-encoded into a string. And the standards committee identified one security-related issue that will require special JSON parsers for handling JSON-Web-Signed (JWS) data (duplicate keys must be rejected by the parser, which is more strict than the JSON spec requires). It is very likely some implementors would just use whatever JSON library was most convenient, either because they weren't aware of the potential problem or because they were lazy and couldn't see how an attacker might take advantage of the problem.
-
-
-Why not an existing electronic invoice standard?
-------------------------------------------------
-
-There are several existing standards for electronic invoices (EDIFACT, OAGIS, UBL, ISDOC). They are all over-designed for Bitcoin's purposes.
-
-However, it would be trivial to extend the PaymentRequest message to include more extensive invoice details encoded as specified by one of those standards (e.g. add a ubl_invoice string that is an XML-encoded UBL invoice).
-
-What about a merchant-pays-fee feature?
----------------------------------------
-
-It is desireable to allow a merchant to pay the cost of any Bitcoin network transaction processing fees, so if a customer is paying for a 1 BTC item they pay exactly 1 BTC.
-
-The consensus is to change the transaction selection code used by Bitcoin miners so that dependent transactions are considered as a group. Merchants or payment services with one or more unconfirmed zero-fee transaction from customers will periodically create a pay-to-self transaction with a large enough fee to get the transactions into a block.
-
-Checking for revoked certificates
----------------------------------
-
-The Online Certificate Checking Protocol (OCSP) is supposed to be a quick and easy way for applications to check for revoked certificates.
-
-In practice, it doesn't work very well. Certificate Authorities have no financial incentive to support a robust infrastructure that can handle millions of OCSP validation requests quickly.
-
-Ideally, Bitcoin clients would use OCSP to check certificate statuses every time they received or re-used a PaymentRequest. But if that results in long pauses or lots of false-positive rejections (because an OCSP endpoint is offline or overwhelmed, perhaps) then merchants and customers might revert to just using "never fails" Bitcoin addresses.
-
-Test Vectors
-============
-
-TODO: give base64-encoded data for PaymentDetails, PaymentRequest, root certificate(s), etc.
-
-
-References
-==========
-
-Public-Key Infrastructure (X.509) working group : http://datatracker.ietf.org/wg/pkix/charter/
-
-RFC 2560, X.509 Internet Public Key Infrastructure Online Certificate Status Protocol - OCSP : http://tools.ietf.org/html/rfc2560
-
-Protocol Buffers : https://developers.google.com/protocol-buffers/
-
-See Also
-========
-
-Javascript Object Signing and Encryption working group : http://datatracker.ietf.org/wg/jose/
-
-Wikipedia's page on Invoices: http://en.wikipedia.org/wiki/Invoice  especially the list of Electronic Invoice standards
-
-sipa's payment protocol proposal: https://gist.github.com/1237788
-
-ThomasV's "Signed Aliases" proposal : http://ecdsa.org/bitcoin_URIs.html
-
-Homomorphic Payment Addresses and the Pay-to-Contract Protocol : http://arxiv.org/abs/1212.3257