Update Use.md

doc/Use.md

@@ -6,114 +6,144 @@ How to use
 Each operation you will perform with this library uses objects.
 Before to start, you need to know object types provided by this library and the methods you can call.
 
+* [Signed JWT (JWS)](object/jws.md)
+* [Encrypted JWT (JWE)](object/jwe.md)
 * [The keys (JWK)](object/jwk.md)
 * [The key sets (JWKSet)](object/jwkset.md)
-* The Jose:
-    * [JWT](object/jwt.md)
-    * [JWS](object/jws.md)
-    * [JWE](object/jwe.md)
-* The instructions:
-    * [Signature instruction](object/signature_instruction.md)
-    * [Encryption instruction](object/encryption_instruction.md)
 
-# The operations
+To create these objects, this library provides factories.
 
-Depending on operations you want to perform, you have to initialize required components first.
+* [JWS Factory](factory/jws.md)
+* [JWE Factory](factory/jwe.md)
+* [JWK Factory](factory/jwe.md)
+
+Please note that there is no factory for the `JWKSet` object (a factory is useless as the object can be instatiate directly).
 
-## How To Sign
+# The operations
 
-### Create a JWS
+## How To Add A Signature?
 
-First, you must create a [signature instruction](object/signature_instruction.md) for each signature you want to create:
+To add a signature on a `JWS` object, you will need to create:
 
-```php
-use Jose\SignatureInstruction;
-
-$instruction1 = new SignatureInstruction();
-$instruction1->setProtectedHeader(['alg'=>'HS512'])
-    ->setKey($my_first_key);
-$instruction2 = new SignatureInstruction();
-$instruction2->setProtectedHeader(['alg'=>'ES384'])
-    ->setUnprotectedHeader('foo'=>'bar')
-    ->setKey($my_second_key);
-```
+* the `JWS` object itself,
+* a key (`JWK` object),
+* a `Signer` object with algorithm you want to use.
 
-Then, you can sign your input:
+Example
+-------
 
 ```php
-use Jose\JSONSerializationModes;
-$input = 'The input to sign';
-$instructions = [$instruction1, $instruction2];
-
-$output = $signer->sign($input, $instructions, JSONSerializationModes::JSON_COMPACT_SERIALIZATION);
+use Jose\Factory\JWSFactory;
+use Jose\Factory\KeyFactory;
+use Jose\Factory\SignerFactory;
+
+// We create our JWS object with claims
+$jws = JWSFactory::createJWS([
+   'iss' => 'https://my-authorization-server.com',
+   'aud' => 'https://your-resource-server.com',
+   'sub' => '0123456789',
+   'exp' => 1456789018,
+   'iat' => 1456780018,
+   'nbf' => 1456780018,
+]);
+
+// We load two keys
+$key1 = KeyFactory::createFromFile('/path/to/my/RSA/private.encrypted.key', 'Password');
+$key2 = KeyFactory::createFromValues([
+    'kty' => 'oct',
+    'k'   => 'AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow',
+]);
+
+// We create our Signer service and we declare the algorithms we want to use ('HS512' and 'RS512')
+$signer = SignerFactory::createSigner(['HS512', 'RS512']);
+
+// We add the first signature using our RSA key and algorithm RS512
+$jws = $signer->addSignature(
+   $jws,
+   $key1,
+   ['alg' => 'RS512']
+);
+
+// We add the second signature using our shared key and algorithm HS512
+$jws = $signer->addSignature(
+   $jws,
+   $key2,
+   ['alg' => 'HS512']
+);
+
+// Now our JWS object contains 2 signatures.
+// We can convert each signature into compact or flattened JSON.
+// We can convert the JWS into JSON with all signatures
+$jws->toCompactJSON(0); // We convert the first signature (#0) into compact JSON
+$jws->toCompactJSON(1); // We convert the second signature (#1) into flattened JSON
+$jws->toJSON(); // We convert all signatures into JSON
 ```
 
-### Output
-
-The supported serialization modes can be found in [the Compact Serialization mode page](OutputModes.md).
-
-The output depends on the output format you set and the number of instructions. It could be:
-
-| Output Mode \ Number of instruction |   1    |        2+        |
-|-------------------------------------|--------|------------------|
-| Compact JSON Serialization          | string | array of strings |
-| Flattened JSON Serialization        | string | array of strings |
-| JSON Serialization                  | string | string           |
+### Important note
 
+Please note that if a signature contains unprotected headers, it cannot be converted into Compact JSON Serialization mode.
 
 ### Detached payload
 
-In some cases, you will need to detached the payload. This library is able to perform this task for you.
+In some cases, you will need to detached the payload. This library supports `JWS` with detached payload.
+
+Example
+-------
 
 ```php
-$output = $signer->sign($input, $instructions, JSONSerializationModes::JSON_COMPACT_SERIALIZATION, true, $detached_payload);
+use Jose\Factory\JWSFactory;
+use Jose\Factory\KeyFactory;
+use Jose\Factory\SignerFactory;
+
+// We create our JWS object with claims
+// The method used is 'createJWSWithDetachedPayload'.
+// The second argument will contain the encoded payload
+$jws = JWSFactory::createJWSWithDetachedPayload(
+   [
+      'iss' => 'https://my-authorization-server.com',
+      'aud' => 'https://your-resource-server.com',
+      'sub' => '0123456789',
+      'exp' => 1456789018,
+      'iat' => 1456780018,
+      'nbf' => 1456780018,
+   ],
+   $encoded_payload
+);
+
+// We load two keys
+... See previous example
+
+// We add a signature using our RSA key and algorithm RS512
+// Please note that the method is now 'addSignatureWithDetachedPayload' and the third argument is the detached payload
+$jws = $signer->addSignatureWithDetachedPayload(
+   $jws,
+   $key1,
+   $detached_payload,
+   ['alg' => 'RS512']
+);
+
+);
+
+// Now our JWS object contain all signatures, but hte payload is empty.
+// As in the previous example, the signatures can be converted into JSON (including compact and flattened).
+// The payload will not be present.
 ```
 
-The fourth parameter is set to `true` to indicate that the payload is detached.
-The output now contains all signatures but no payload. The payload is set in the last parameter `$detached_payload`.
-Note that your payload is encoded in Base 64.
+## How To Add A Recipient (= encrypt)?
 
-## How To Encrypt
+**To be written**
 
-### Create a JWE
+### Additional Authenticated Data
 
-First, you must create an [encryption instruction](object/encryption_instruction.md) for each encryption you want to create:
+This library supports Additional Authenticated Data (AAD).
 
 ```php
-use Jose\EncryptionInstruction;
-
-$instruction1 = new EncryptionInstruction();
-$instruction1->setRecipientKey($first_recipient_public_key)
-    ->setUnprotectedHeader([
-        'alg' => 'RSA-OAEP-256',
-    ]);
-
-$instruction2 = new EncryptionInstruction();
-$instruction2>setRecipientKey($second_recipient_public_key)
-   ->setSenderKey($my_private_key)
-   ->setUnprotectedHeader([
-        'alg' => 'ECDH-ES',
-        'foo' => 'bar',
-   ]);
-```
-
-Then, you can encrypt your input:
 
-```php
-$input = 'The input to encrypt';
-$instructions = [$instruction1, $instruction2];
-$shared_protected_header = [
-    'enc' => 'A256CBC-HS512',
-    'zip' => 'DEF'
-];
-$shared_unprotected_header = [];
-
-$output = $encrypter->encrypt($input, $instructions, JSONSerializationModes::JSON_COMPACT_SERIALIZATION, $shared_protected_header, $shared_unprotected_header);
 ```
 
-#### Important note
+### Important note
 
-With this library, you can create encrypt an input using multiple instructions.
+With this library, you can create encrypt an input using multiple recipients.
 In this case, the Key Management Mode is determined according to the used algorithms.
 
 You cannot create multiple encryptions if the Key Management Mode are not compatible.
@@ -143,43 +173,19 @@ And a compatibility table between Key Management Modes:
 
 |        Key Management Mode      | Key Encryption | Key Wrapping | Direct Key Agreement | Key Agreement with Key Wrapping | Direct Encryption |
 |---------------------------------|----------------|--------------|----------------------|---------------------------------|-------------------|
-| Key Encryption                  |     YES        |     YES      |        NO            |            YES                  |       NO          |
-| Key Wrapping                    |     YES        |     YES      |        NO            |            YES                  |       NO          |
-| Direct Key Agreement            |     NO         |     NO       |        YES           |            NO                   |       NO          |
-| Key Agreement with Key Wrapping |     YES        |     YES      |        NO            |            YES                  |       NO          |
-| Direct Encryption               |     NO         |     NO       |        NO            |            NO                   |       YES         |
+| Key Encryption                  |     YES        |     YES      |        NO *          |            YES                  |       NO *      |
+| Key Wrapping                    |     YES        |     YES      |        NO *          |            YES                  |       NO *      |
+| Direct Key Agreement            |     NO *       |     NO *     |        YES           |            NO *                 |       NO          |
+| Key Agreement with Key Wrapping |     YES        |     YES      |        NO *          |            YES                  |       NO *      |
+| Direct Encryption               |     NO *       |     NO *     |        NO            |            NO *                 |       YES         |
 
-### Output
+*: Compatibility is possible only if the algorithm for the first recipient is a `Direct Key Agreement` or a `Direct Encryption` algorithm, otherwise it is not possible
 
-The supported serialization modes can be found in [the Compact Serialization mode page](OutputModes.md).
+### Important note
 
-The output depends on the output format you set and the number of instructions. It could be:
+Please note that if a recipient contains unprotected headers or the `JWE` contains unprotected shared headers, it cannot be converted into Compact JSON Serialization mode.
 
-| Output Mode \ Number of instruction |   1    |        2+        |
-|-------------------------------------|--------|------------------|
-| Compact JSON Serialization          | string | array of strings |
-| Flattened JSON Serialization        | string | array of strings |
-| JSON Serialization                  | string | string           |
-
-
-### Additional Authenticated Data
-
-This library supports Additional Authenticated Data (AAD).
-
-Note that this data is not available when using Compact JSON Serialization mode.
-
-```php
-$output = $encrypter->encrypt($input, $instructions, $shared_protected_header, $shared_unprotected_header, JSONSerializationModes::JSON_SERIALIZATION, 'foo,bar,baz');
-```
-
-## How To Load
-
-### Load a JWS or JWE
-
-```php
-$output = $loader->load($input);
-```
+## How To Load?
 
-### Verify a JWS
+**To be written**
 
-### Decrypt a JWE