Doc: Sample code and README for v10 release

README.md

@@ -4,22 +4,17 @@
 [![Documentation Status](https://readthedocs.org/projects/http-signatures-php/badge/?version=latest)](https://http-signatures-php.readthedocs.io/en/latest/?badge=latest)
 
 PHP implementation of [Singing HTTP Messages][draft10] draft specification;
-allowing cryptographic signing and verifying of [PSR-7 messages][psr7].
-
-<!-- See also:
-
-* https://github.com/99designs/http-signatures-guzzlehttp
-* https://github.com/99designs/http-signatures-ruby
--->
-
+allowing cryptographic signing and verifying of HTTP messages using PHP
+[PSR-7][psr7] interfaces.
 
 ## Features
 
-- Sign HTTP Messages according to [Signing HTTP Message draft IETF RFC version 10][draft10]
+- Full compliance with [Signing HTTP Message draft IETF RFC version 10][draft10]
 - Sign & verify messages using HMACs
-- Sign & verify messages with RSA private/public keys
+- Sign & verify messages with RSA, Elliptic Curve and DSA private/public keys
 - Add a ``Digest`` header, or automatically add the header while signing in a single operation
 - Verify a ``Digest`` header while verifying the signature
+- Compatible with common PSR-7 libraries
 
 Complete documentation for this library can be found at 
 [Read The Docs](https://http-signatures-php.readthedocs.io/en/latest/)
@@ -34,18 +29,17 @@ Add [liamdennehy/http-signatures-php][package] to your [``composer.json``][compo
 * The ``signWithDigest`` function witll add a ``Digest`` header and digitally
   sign the message in a new ``Signature`` header.
 
-Using an PSR-7 request ``$message`` ready to send:
+Using an PSR-7 request ``$message`` ready to send (assuming it has a ``Date``
+header):
 
 ```php
-  use HttpSignatures\Context;
-
-  $context = new HttpSignatures\Context([
-    'keys' => ['mykey' => file_get_contents('/path/to/privatekeyfile')],
-    'algorithm' => 'rsa-sha256',
+  $signingContext = new \HttpSignatures\Context([
+    'keys' => ['myKeyId' => file_get_contents('/path/to/secret-key')],
+    'algorithm' => 'hmac-sha256',
     'headers' => ['(request-target)', 'Date'],
   ]);
 
-  $context->signer()->signWithDigest($message);
+  $signingContext->signer()->signWithDigest($message);
 ```
 
 ## Contributing

doc/source/index.rst

@@ -14,6 +14,9 @@ PHP implementation of `Signing HTTP Messages
 allowing cryptographic signing and verifying of 
 `PHP PSR-7 messages <http://www.php-fig.org/psr/psr-7/>`_.
 
+Version 10.x of this library implements all features of requirements of
+version 10 of the RFC.
+
 
 .. Indices and tables
   ==================

doc/source/quickstart.rst

@@ -41,13 +41,12 @@ This type of signature uses a secret key known to you and the verifier.
 
 .. code-block:: php
 
-  $context = new \HttpSignatures\Context([
-    'keys' => ['key12' => 'your-secret-here'],
+  $signingContext = new \HttpSignatures\Context([
+    'keys' => ['key12' => file_get_contents('/path/to/secret-key')],
     'algorithm' => 'hmac-sha256',
-    'headers' => ['(request-target)', 'Content-Type'],
+    'headers' => ['(request-target)', 'Date'],
   ]);
 
-
 Private Key Context (RSA)
 ---------------------------
 
@@ -59,10 +58,10 @@ The key file is assumed to be an unencrypted private key in PEM format.
 
 .. code-block:: php
 
-  $context = new \HttpSignatures\Context([
-    'keys' => ['key12' => file_get_contents('/path/to/privatekeyfile')],
+  $signingContext = new \HttpSignatures\Context([
+    'keys' => ['key12' => file_get_contents('/path/to/privatekey.pem')],
     'algorithm' => 'rsa-sha256',
-    'headers' => ['(request-target)', 'Date', 'Accept']
+    'headers' => ['(request-target)', 'Date']
   ]);
 
 Signing the Message:
@@ -72,7 +71,7 @@ With your PSR-7 compliant message in ``$message``:
 
 .. code-block:: php
 
-  $context->signer()->sign($message);
+  $signingContext->signer()->sign($message);
 
 Now ``$message`` contains the ``Signature`` header:
 
@@ -85,8 +84,9 @@ There is a similar function to add the ``Authorization: Signature`` header:
 
 .. code-block:: php
 
-  $context->signer()->sign($message);
-  print $message->->getHeader('Authorization')[0];
+  $signingContext->signer()->authorize($message);
+ 
+  print $message->getHeader('Authorization')[0];
   // Signature keyId="key12",algorithm="<yourAlgorithm>",headers="...",signature="..."
 
 Adding a Digest header while signing
@@ -97,8 +97,9 @@ payload (body) of the message in addition to the request-target and headers:
 
 .. code-block:: php
 
-  $context->signer()->signWithDigest($message);
-  $message->headers->get('digest');
+  $signingContext->signer()->signWithDigest($message);
+  
+  $message->headers->getHeader('Digest')[0];
   // SHA-256=<base64SHA256Digest>
 
 Verifying a Signed Message