Update jwkset.md

ghola · Oct 10, 2016 · 7ceb406 · 7ceb406
1 parent 5d95059
commit 7ceb406
Showing 1 changed file with 111 additions and 5 deletions.
diff --git a/doc/object/jwkset.md b/doc/object/jwkset.md
@@ -147,7 +147,7 @@ The method `createFromX5U` supports the same arguments as the method `createFrom
 ## Create a Key Set with Random keys
 
 You may need to create and store a key set with random keys.
-This library provides an easy way to create such key set by using the `createStorableKeySet`
+This library provides an easy way to create such key set by using the `createStorableKeySet` method.
 
 ```php
 use Jose\Factory\JWKFactory;
@@ -164,18 +164,124 @@ $rotatable_key_set = JWKFactory::createStorableKeySet(
 );
 ```
 
+### Random Key Configurations
+
+The random keys created with that JWKSet are all of the same type. The configuration of those keys depends on their type and is similar to the configuration of [a random key](https://github.com/Spomky-Labs/jose/blob/master/doc/object/jwk.md#create-a-random-key).
+The main difference is that you do not have to define a `kid` as it is automatically generated.
+
+Additional paramters are accepted and are set for all key within the key set.
+
+#### Create a Random `oct` Key Set
+
+The following example will create `oct` keys.
+The key size is 256 bits (`'size' => 256`) and that key will be used with the `HS256` algorithm for signature/verification only.
+
+```php
+use Jose\Factory\JWKFactory;
+
+$jwk = JWKFactory::createStorableKeySet(
+    '/path/to/the/storage/file.keyset', // The file which will contain the key set
+    [
+        'kty'  => 'oct',
+        'size' => 256,
+        'alg'  => 'HS256',
+        'use'  => 'sig',
+        'foo'  => 'bar',
+    ],
+    3,                      // Number of keys in that key set
+);
+```
+
+#### Create a Random `RSA` Key Set
+
+The following example will create `RSA` keys.
+The key size is 4096 bits and that key will be used with the `RSA-OAEP` algorithm for encryption/decryption only.
+
+```php
+use Jose\Factory\JWKFactory;
+
+$jwk = JWKFactory::createStorableKeySet(
+    '/path/to/the/storage/file.keyset', // The file which will contain the key set
+    [
+        'kty'  => 'RSA',
+        'size' => 4096,
+        'alg'  => 'RSA-OAEP',
+        'use'  => 'enc',
+    ],
+    3,                      // Number of keys in that key set
+);
+```
+
+#### Create a Random `EC` Key Set
+
+The following example will create `EC` keys.
+The key uses the `P-521` curve and will be used with the `ES512` algorithm for signature/verification only.
+
+```php
+use Jose\Factory\JWKFactory;
+
+$jwk = JWKFactory::createStorableKeySet(
+    '/path/to/the/storage/file.keyset', // The file which will contain the key set
+    [
+        'kty' => 'EC',
+        'crv' => 'P-521',
+        'alg' => 'ES512',
+        'use' => 'sig',
+    ],
+    3,                      // Number of keys in that key set
+);
+```
+
+#### Create a Random `OKP` Key Set
+
+The following example will create `OKP` keys.
+The key uses the `X25519` curve and will be used with the `ECDH-ES` algorithm for encryption/decryption only.
+
+```php
+use Jose\Factory\JWKFactory;
+
+$jwk = JWKFactory::createStorableKeySet(
+    '/path/to/the/storage/file.keyset', // The file which will contain the key set
+    [
+        'kty' => 'OKP',
+        'crv' => 'X25519',
+        'alg' => 'ECDH-ES',
+        'use' => 'enc',
+    ],
+    3,                      // Number of keys in that key set
+);
+```
+
+#### Create a Random `None` Key Set
+
+This configuration is absolutely useless as it is not relevant to use 3 "random" `none` keys.
+However this configuration is possible.
+
+```php
+use Jose\Factory\JWKFactory;
+
+$jwk = JWKFactory::createStorableKeySet(
+    '/path/to/the/storage/file.keyset', // The file which will contain the key set
+    [
+        'kty' => 'none',
+    ],
+    3,                      // Number of keys in that key set
+);
+```
+
 ## Create a Rotatable Key Set
 
 Some applications may require a key set with keys that are updated after a period of time.
 To continue to validate JWS or decrypt JWE, the old keys should be able for another period of time.
 
 That is the purpose of the Rotatable Key Set.
+This kind of key set is configured exactly like a random key set.
+
+Those JWKSets implement the `Jose\Object\RotatableInterface` and the method `rotate`.
 
-You have to define which type of key you want to have (only one type per JWKSet allowed), how many keys in the key set and a period of time.
-Keys are automatically created and rotation is performed after the period of time.
+You can manipulate that key set as any other key sets, however you cannot add or remove keys.
 
-You can manipulate that key set as any other key sets, however we recommend you to never add or remove keys. All changes will be erased we keys are rotated.
-We also recommend you to use the first key of that key set to perform your signature/encryption operations.
+We recommend you to use the first key of that key set to perform your signature/encryption operations.
 
 Except when the key set is created, all keys will be available at least during `number of key * period of time`.