jose 0.3.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 97b12e5771a9533cfe90cf343ad9829fea08959e
-  data.tar.gz: 36896efd3b895906a16ff8f751449fba9159dc3d
+  metadata.gz: 8804406a3e47d37b89da4315eb021d33d447ecf7
+  data.tar.gz: 9409c19e851ef2036b1fc843eeeaa3667c64ed40
 SHA512:
-  metadata.gz: dc6941ef61ef94954fe118082d564936fc59b13c53f6ab4b09dd7598355b4572b9dff093fe57e84febf842817c88e454b7d34c1551028ee687fbda36c439697c
-  data.tar.gz: 919c7f009f80b2e22e82083c60f93c39571800b3069d9d86372c7ca9b12d8cb6b18d3f0c322c2dc812fdeee411dd2d42e36956803cf2405d68ffe169514859fe
+  metadata.gz: ade14cfd65ca8cab5f24b5329448db0e0ee19d04fa71ec43fda67300197563c361c20f2229dba79f0b6b4b01cf9440482cae460324ce069fa782c66e3430b284
+  data.tar.gz: 391d322825bf7905f41800ae0ed77f7d29b0c27018ac06e65bcf3d04288fe579191a4278beac44e5a2f09e2e9350c22da4cab0189c126fef258888d4e1f53516

data/.travis.yml

@@ -3,6 +3,11 @@ language: ruby
 sudo: required
 dist: trusty
 
+env:
+  global:
+    - JOSE_CRYPTO_FALLBACK=true
+    - RUBYOPT="-W0"
+
 rvm:
   - 2.3.1
 

data/.yardopts

@@ -0,0 +1,4 @@
+--markup markdown
+-
+docs/*.md
+*.md

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.0.0 (2016-05-07)
+
+* Enhancements
+  * [Documentation!](http://www.rubydoc.info/gems/jose) Many thanks to [@soumyaray](https://github.com/soumyaray) for the motivation to improve documentation.
+  * Support for OpenSSH octet key pairs (for Ed25519).
+  * Better key management behavior associated with ECDH-ES algorithms.
+
 ## 0.3.1 (2016-05-05)
 
 * Fixes

data/README.md

@@ -1,6 +1,6 @@
 # JOSE
 
-[![Build Status](https://travis-ci.org/potatosalad/ruby-jose.png?branch=master)](https://travis-ci.org/potatosalad/ruby-jose) [![Gem](https://img.shields.io/gem/v/jose.svg?maxAge=2592000)](https://rubygems.org/gems/jose)
+[![Travis](https://img.shields.io/travis/potatosalad/ruby-jose.svg?maxAge=2592000)](https://travis-ci.org/potatosalad/ruby-jose) [![Gem](https://img.shields.io/gem/v/jose.svg?maxAge=2592000)](https://rubygems.org/gems/jose) [![Docs](https://img.shields.io/badge/yard-docs-blue.svg?maxAge=2592000)](http://www.rubydoc.info/gems/jose) [![Inline docs](http://inch-ci.org/github/potatosalad/ruby-jose.svg?branch=master&style=shields)](http://inch-ci.org/github/potatosalad/ruby-jose)
 
 JSON Object Signing and Encryption (JOSE) for Ruby.
 
@@ -24,7 +24,7 @@ Or install it yourself as:
 
 ## Usage
 
-Better documentation is in progress, but the [erlang-jose documentation](https://hexdocs.pm/jose/) can provide an idea of the functionality available in this gem.
+Better documentation is in progress, but here are a few resources to get started. First, a simple example of key generation and message signing:
 
 ```ruby
 # Let's use our secret key "symmetric key" for use with
@@ -44,6 +44,14 @@ verified, message, = jwk.verify(signed)
 # => [true, "test"]
 ```
 
+More details and examples:
+- [Getting Started](http://www.rubydoc.info/gems/jose/file/docs/GettingStarted.md)
+- [Key Generation](http://www.rubydoc.info/gems/jose/file/docs/KeyGeneration.md)
+- [Encryption Algorithms](http://www.rubydoc.info/gems/jose/file/docs/EncryptionAlgorithms.md)
+- [Signature Algorithms](http://www.rubydoc.info/gems/jose/file/docs/SignatureAlgorithms.md)
+
+Finally, the [erlang-jose documentation](https://hexdocs.pm/jose/) can provide more ideas of the functionality available in this gem.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -57,4 +65,3 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/potato
 ## License
 
 The gem is available as open source under the terms of the [MPL-2.0 License](http://opensource.org/licenses/MPL-2.0).
-

data/docs/EncryptionAlgorithms.md

@@ -0,0 +1,55 @@
+# @title Encryption Algorithms
+
+# Encryption Algorithms
+
+The basic parameters for a {JOSE::JWE JOSE::JWE} header are:
+
+- `"alg"` **(required)** - Key Management Algorithm used to encrypt or determine the value of the Content Encryption Key.
+- `"enc"` **(required)** - Encryption Algorithm used to perform authenticated encryption on the plain text using the Content Encryption Key.
+- `"zip"` *(optional)* - Compression Algorithm applied to the plaintext before encryption, if any.
+
+See [RFC 7516](https://tools.ietf.org/html/rfc7516#section-4.1) for more information about other header parameters.
+
+### `alg` Header Parameter
+
+Here are the supported options for the `alg` parameter, grouped by similar funcionality:
+
+- Single Asymmetric Public/Private Key Pair
+  - [`RSA1_5`](http://www.rubydoc.info/gems/jose/JOSE/JWE#RSA-group)
+  - [`RSA-OAEP`](http://www.rubydoc.info/gems/jose/JOSE/JWE#RSA-group)
+  - [`RSA-OAEP-256`](http://www.rubydoc.info/gems/jose/JOSE/JWE#RSA-group)
+- Two Asymmetric Public/Private Key Pairs with Key Agreement
+  - [`ECDH-ES`](http://www.rubydoc.info/gems/jose/JOSE/JWE#ECDH-ES-group)
+  - [`ECDH-ES+A128KW`](http://www.rubydoc.info/gems/jose/JOSE/JWE#ECDH-ES-group)
+  - [`ECDH-ES+A192KW`](http://www.rubydoc.info/gems/jose/JOSE/JWE#ECDH-ES-group)
+  - [`ECDH-ES+A256KW`](http://www.rubydoc.info/gems/jose/JOSE/JWE#ECDH-ES-group)
+- Symmetric Password Based Key Derivation
+  - [`PBES2-HS256+A128KW`](http://www.rubydoc.info/gems/jose/JOSE/JWE#PBES2-group)
+  - [`PBES2-HS384+A192KW`](http://www.rubydoc.info/gems/jose/JOSE/JWE#PBES2-group)
+  - [`PBES2-HS512+A256KW`](http://www.rubydoc.info/gems/jose/JOSE/JWE#PBES2-group)
+- Symmetric Key Wrap
+  - [`A128GCMKW`](http://www.rubydoc.info/gems/jose/JOSE/JWE#AESGCMKW-group)
+  - [`A192GCMKW`](http://www.rubydoc.info/gems/jose/JOSE/JWE#AESGCMKW-group)
+  - [`A256GCMKW`](http://www.rubydoc.info/gems/jose/JOSE/JWE#AESGCMKW-group)
+  - [`A128KW`](http://www.rubydoc.info/gems/jose/JOSE/JWE#AESKW-group)
+  - [`A192KW`](http://www.rubydoc.info/gems/jose/JOSE/JWE#AESKW-group)
+  - [`A256KW`](http://www.rubydoc.info/gems/jose/JOSE/JWE#AESKW-group)
+- Symmetric Direct Key (known to both sides)
+  - [`dir`](http://www.rubydoc.info/gems/jose/JOSE/JWE#direct-group)
+
+### `enc` Header Parameter
+
+Here are the options for the `enc` parameter:
+
+- [`A128CBC-HS256`](http://www.rubydoc.info/gems/jose/JOSE/JWE#AESCBC-group)
+- [`A192CBC-HS384`](http://www.rubydoc.info/gems/jose/JOSE/JWE#AESCBC-group)
+- [`A256CBC-HS512`](http://www.rubydoc.info/gems/jose/JOSE/JWE#AESCBC-group)
+- [`A128GCM`](http://www.rubydoc.info/gems/jose/JOSE/JWE#AESGCM-group)
+- [`A192GCM`](http://www.rubydoc.info/gems/jose/JOSE/JWE#AESGCM-group)
+- [`A256GCM`](http://www.rubydoc.info/gems/jose/JOSE/JWE#AESGCM-group)
+
+### `zip` Header Parameter
+
+Here are the options for the `zip` parameter:
+
+- [`DEF`](http://www.rubydoc.info/gems/jose/JOSE/JWE#DEF-group)

data/docs/GettingStarted.md

@@ -0,0 +1,137 @@
+# @title Getting Started
+
+# Getting Started
+
+JOSE stands for JSON Object Signing and Encryption which is a is a set of
+standards established by the [JOSE Working Group](https://datatracker.ietf.org/wg/jose).
+
+JOSE is split into 5 main components:
+
+  * {JOSE::JWA JOSE::JWA} - JSON Web Algorithms (JWA) {https://tools.ietf.org/html/rfc7518 RFC 7518}
+  * {JOSE::JWE JOSE::JWE} - JSON Web Encryption (JWE) {https://tools.ietf.org/html/rfc7516 RFC 7516}
+  * {JOSE::JWK JOSE::JWK} - JSON Web Key (JWK)        {https://tools.ietf.org/html/rfc7517 RFC 7517}
+  * {JOSE::JWS JOSE::JWS} - JSON Web Signature (JWS)  {https://tools.ietf.org/html/rfc7515 RFC 7515}
+  * {JOSE::JWT JOSE::JWT} - JSON Web Token (JWT)      {https://tools.ietf.org/html/rfc7519 RFC 7519}
+
+Additional specifications and drafts implemented:
+
+  * JSON Web Key (JWK) Thumbprint [RFC 7638](https://tools.ietf.org/html/rfc7638)
+  * JWS Unencoded Payload Option  [draft-ietf-jose-jws-signing-input-options-04](https://tools.ietf.org/html/draft-ietf-jose-jws-signing-input-options-04)
+
+## More Information
+
+  * {file:docs/KeyGeneration.md}
+  * {file:docs/EncryptionAlgorithms.md}
+  * {file:docs/SignatureAlgorithms.md}
+
+## Usage Examples
+
+The simplest combination might be `{"alg":"dir","enc":"A128GCM"}` which requires a 128-bit (or 16-byte) key that must be fully known by both parties.
+
+```ruby
+# Alice wants to send Bob an encrypted message.
+# Both Alice and Bob know about the 128-bit key "this is 16 bytes".
+
+# Alice encrypts the plain_text and sends cipher_text to Bob.
+plain_text  = "Hello, World!"
+jwk         = JOSE::JWK.from_oct("this is 16 bytes")
+cipher_text = jwk.block_encrypt(plain_text, {"alg" => "dir", "enc" => "A128GCM"}).compact
+# => "eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4R0NNIn0..oSOfVgfW5dPo4Mwx.x3N6TNI0pTYlBVHiSA.Uu_kROoBRWL0Hb0BH150Zg"
+
+# Bob decrypts the cipher_text using the shared secret key.
+cipher_text = "eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4R0NNIn0..oSOfVgfW5dPo4Mwx.x3N6TNI0pTYlBVHiSA.Uu_kROoBRWL0Hb0BH150Zg"
+jwk         = JOSE::JWK.from_oct("this is 16 bytes")
+plain_text, = jwk.block_decrypt(cipher_text)
+# => "Hello, World!"
+```
+
+A more complex combination might be `{"alg":"PBES2-HS256+A128KW","enc":"A128GCM","p2c":4096}` which uses a passphrase of any length and generates the Content Encryption Key of the correct length based on that passphrase. The `p2c` in the JSON specifies that 4096 rounds will be done which slows down any brute force attacks trying to determine the passphrase.
+
+```ruby
+# Alice wants to send Bob an encrypted message.
+# Both Alice and Bob know about the passphrase "alice and bob's secret".
+
+# Alice encrypts the plain_text and sends cipher_text to Bob.
+plain_text  = "Hello, World!"
+jwk         = JOSE::JWK.from_oct("alice and bob's secret")
+cipher_text = jwk.block_encrypt(plain_text, {"alg" => "PBES2-HS256+A128KW", "enc" => "A128GCM", "p2c" => 4096}).compact
+# => "eyJhbGciOiJQQkVTMi1IUzI1NitBMTI4S1ciLCJlbmMiOiJBMTI4R0NNIiwicDJjIjo0MDk2LCJwMnMiOiJfZEllWDFGX29zUSJ9.B8vGlGGJBNSeGiaOKFJq3MXqhvK5fihL.WUt7m0TldTqW4eNb.wyjPCvfglCovqEd7xw.qZFI-qEV9ACh142xs3MozA"
+
+# Bob decrypts the cipher_text using the shared passphrase.
+cipher_text = "eyJhbGciOiJQQkVTMi1IUzI1NitBMTI4S1ciLCJlbmMiOiJBMTI4R0NNIiwicDJjIjo0MDk2LCJwMnMiOiJfZEllWDFGX29zUSJ9.B8vGlGGJBNSeGiaOKFJq3MXqhvK5fihL.WUt7m0TldTqW4eNb.wyjPCvfglCovqEd7xw.qZFI-qEV9ACh142xs3MozA"
+jwk         = JOSE::JWK.from_oct("alice and bob's secret")
+plain_text, = jwk.block_decrypt(cipher_text)
+# => "Hello, World!"
+```
+
+An even more complex combination might be `{"alg":"ECDH-ES","enc":"A128GCM"}` which requires two sets of keypairs. The sender (in our case Alice) uses their secret key and the public key of the receiver (Bob) to compute a shared key. The public key of the sender is embedded in the resulting encrypted message which the receiver then uses with their own secret key to decrypt the message.
+
+```ruby
+# Let's setup the keys that will be used below (use JOSE::JWK.from_binary(...) to load the string version)
+## Alice
+alice_secret = JOSE::JWK.generate_key([:okp, :X25519])
+# => "{\"crv\":\"X25519\",\"d\":\"0Pygq6jZVuWM4lPIhmCCbxtLIsWVzfnK5aM65PC1iX0\",\"kty\":\"OKP\",\"x\":\"uZGRsHIG33ebtKoIBG2WL4_TC_GTZtluSFuOmEPCngc\"}"
+alice_public = alice_secret.to_public
+# => "{\"crv\":\"X25519\",\"kty\":\"OKP\",\"x\":\"uZGRsHIG33ebtKoIBG2WL4_TC_GTZtluSFuOmEPCngc\"}"
+## Bob
+bob_secret   = JOSE::JWK.generate_key([:okp, :X25519])
+# => "{\"crv\":\"X25519\",\"d\":\"CMVqzIl-pHk0vuAUxhsZccYSLHpJfhRYvz3rTu6R8kc\",\"kty\":\"OKP\",\"x\":\"U-ckTk7roeu-9peZjdhZUIm9yJHtBrrkBJojCpUz5Cs\"}"
+bob_public   = bob_secret.to_public
+# => "{\"crv\":\"X25519\",\"kty\":\"OKP\",\"x\":\"U-ckTk7roeu-9peZjdhZUIm9yJHtBrrkBJojCpUz5Cs\"}"
+
+# Alice wants to send Bob an encrypted message.
+# Bob first sends Alice his public key (bob_public above).
+
+# Alice loads Bob's public key and encrypts the plain_text using her secret key.
+# She then sends the resulting cipher_text to Bob.
+plain_text  = "Hello, World!"
+bob_public  = JOSE::JWK.from_binary("{\"crv\":\"X25519\",\"kty\":\"OKP\",\"x\":\"U-ckTk7roeu-9peZjdhZUIm9yJHtBrrkBJojCpUz5Cs\"}")
+cipher_text = bob_public.box_encrypt(plain_text, alice_secret).compact
+# => "eyJhbGciOiJFQ0RILUVTIiwiYXB1IjoiZTdwaGd3YU92NXVIVlFkOFJIRFRxcXpMYjZ6T0Nlb1oteXJLRTVmcTM2ayIsImFwdiI6IjY5U1Y3VWo0MWstMEhrcU1GOXVMaEk5Ty14TXZ0UlJ0bU0tbmxJV1RyV2MiLCJlbmMiOiJBMTI4R0NNIiwiZXBrIjp7ImNydiI6IlgyNTUxOSIsImt0eSI6Ik9LUCIsIngiOiJ1WkdSc0hJRzMzZWJ0S29JQkcyV0w0X1RDX0dUWnRsdVNGdU9tRVBDbmdjIn19..EeHOlLmlZocrf0Iz.O2kmN_-6m2YEWiR8XA.CTpSFJKy1GRLU3OoNj_AvA"
+
+# Bob decrypts the cipher_text using his secret key.
+cipher_text = "eyJhbGciOiJFQ0RILUVTIiwiYXB1IjoiZTdwaGd3YU92NXVIVlFkOFJIRFRxcXpMYjZ6T0Nlb1oteXJLRTVmcTM2ayIsImFwdiI6IjY5U1Y3VWo0MWstMEhrcU1GOXVMaEk5Ty14TXZ0UlJ0bU0tbmxJV1RyV2MiLCJlbmMiOiJBMTI4R0NNIiwiZXBrIjp7ImNydiI6IlgyNTUxOSIsImt0eSI6Ik9LUCIsIngiOiJ1WkdSc0hJRzMzZWJ0S29JQkcyV0w0X1RDX0dUWnRsdVNGdU9tRVBDbmdjIn19..EeHOlLmlZocrf0Iz.O2kmN_-6m2YEWiR8XA.CTpSFJKy1GRLU3OoNj_AvA"
+plain_text, = bob_secret.box_decrypt(cipher_text)
+# => "Hello, World!"
+```
+
+Here is an example of using X25519 and Ed25519 key pairs to encrypt and then sign a message.
+
+```ruby
+# Alice's Signing Key Pair
+alice_ed25519_secret = JOSE::JWS.generate_key({"alg" => "Ed25519"})
+# => "{\"alg\":\"Ed25519\",\"crv\":\"Ed25519\",\"d\":\"CNnP7HYI-plw66s8GWOJwFCWWCZO1udseqEiyGxJGyk\",\"kty\":\"OKP\",\"use\":\"sig\",\"x\":\"atNiugZnSNxjmd5TM4eXg-aszq7Xarmpsuxrt2yIkUc\"}"
+alice_ed25519_public = alice_ed25519_secret.to_public
+# => "{\"alg\":\"Ed25519\",\"crv\":\"Ed25519\",\"kty\":\"OKP\",\"use\":\"sig\",\"x\":\"atNiugZnSNxjmd5TM4eXg-aszq7Xarmpsuxrt2yIkUc\"}"
+
+# Bob's Key Agreement Key Pair
+bob_x25519_secret    = JOSE::JWK.generate_key([:okp, :X25519])
+# => "{\"crv\":\"X25519\",\"d\":\"CMVqzIl-pHk0vuAUxhsZccYSLHpJfhRYvz3rTu6R8kc\",\"kty\":\"OKP\",\"x\":\"U-ckTk7roeu-9peZjdhZUIm9yJHtBrrkBJojCpUz5Cs\"}"
+bob_x25519_public    = bob_x25519_secret.to_public
+# => "{\"crv\":\"X25519\",\"kty\":\"OKP\",\"x\":\"U-ckTk7roeu-9peZjdhZUIm9yJHtBrrkBJojCpUz5Cs\"}"
+
+# Alice wants to send Bob an encrypted message that has also been signed.
+# Alice provides Bob with her public signing key.
+# Bob provides Alice with his public key agreement key.
+# Alice does not specify her own key agreement key, which results in a new one being generated.
+plain_text                       = "Hello, World!"
+cipher_text, alice_x25519_secret = bob_x25519_public.box_encrypt(plain_text)
+cipher_text                      = cipher_text.compact
+# => ["eyJhbGciOiJFQ0RILUVTIiwiYXB1IjoiXy1leGtvYkpFQVpRWi01N1E2ZzRsMHNzbG0yT2I4TnRTeDlwcFFMZEJaNCIsImFwdiI6IjY5U1Y3VWo0MWstMEhrcU1GOXVMaEk5Ty14TXZ0UlJ0bU0tbmxJV1RyV2MiLCJlbmMiOiJBMTI4R0NNIiwiZXBrIjp7ImNydiI6IlgyNTUxOSIsImt0eSI6Ik9LUCIsIngiOiJQR3h4cXRXbnJ2Q0IwOVY0cVRoZEZpUUVweXp6ZVhEMVVJNjYyY0UxNHlrIn19..qcI2uruuJA7wZYda.-NhogJt2ofXlKSZMcQ.7Y9ZBHyPuuSj75u7zR7gpg",
+#  "{\"crv\":\"X25519\",\"d\":\"6Gu9vuKL_3YqjBrxLm2rcz3mkKNHMj5pkslVbL7XEVU\",\"kty\":\"OKP\",\"x\":\"PGxxqtWnrvCB09V4qThdFiQEpyzzeXD1UI662cE14yk\"}"]
+
+# Alice then signs the cipher_text using her Ed25519 secret key.
+signed_text = alice_ed25519_secret.sign(cipher_text).compact
+# => "eyJhbGciOiJFZDI1NTE5In0.ZXlKaGJHY2lPaUpGUTBSSUxVVlRJaXdpWVhCMUlqb2lYeTFsZUd0dllrcEZRVnBSV2kwMU4xRTJaelJzTUhOemJHMHlUMkk0VG5SVGVEbHdjRkZNWkVKYU5DSXNJbUZ3ZGlJNklqWTVVMVkzVldvME1Xc3RNRWhyY1UxR09YVk1hRWs1VHkxNFRYWjBVbEowYlUwdGJteEpWMVJ5VjJNaUxDSmxibU1pT2lKQk1USTRSME5OSWl3aVpYQnJJanA3SW1OeWRpSTZJbGd5TlRVeE9TSXNJbXQwZVNJNklrOUxVQ0lzSW5naU9pSlFSM2g0Y1hSWGJuSjJRMEl3T1ZZMGNWUm9aRVpwVVVWd2VYcDZaVmhFTVZWSk5qWXlZMFV4TkhsckluMTkuLnFjSTJ1cnV1SkE3d1pZZGEuLU5ob2dKdDJvZlhsS1NaTWNRLjdZOVpCSHlQdXVTajc1dTd6UjdncGc.AK5wm7g9UjZflK5Z-0K7SRu8gPiT-zJoz0HBGy1fI9tnpw9_iXReqmsV0Z8NEa34gj4SZbSGYI7KZxXzyZ-VBw"
+
+# Bob receives the signed_text and can immediately verify whether it's from Alice or not.
+verified, cipher_text, = alice_ed25519_public.verify(signed_text)
+if verified == true
+  # Bob can decrypt the cipher_text using his secret X25519 key.
+  plain_text, jwe = bob_x25519_secret.box_decrypt(cipher_text)
+  # => "Hello, World!"
+  # If Bob wanted to send a message back to Alice, he can use the embedded public key to do so:
+  jwe.alg.epk.box_encrypt("A message for Alice", bob_x25519_secret)
+  # At this point, however, we essentially have a partially functional SSL/TLS implementation.
+end
+```

data/docs/KeyGeneration.md

@@ -0,0 +1,263 @@
+# @title Key Generation
+
+# Key Generation
+
+There are four key generation methods described below for each key type:
+
+* Method 1: OpenSSL
+* Method 2: {JOSE::JWK.generate_key JOSE::JWK.generate_key}
+* Method 3: {JOSE::JWE.generate_key JOSE::JWE.generate_key}
+* Method 4: {JOSE::JWS.generate_key JOSE::JWS.generate_key}
+
+## EC
+
+The three curve types defined in the [JWA RFC 7518](https://tools.ietf.org/html/rfc7518#section-6.2.1.1) for the `EC` key type are:
+
+1. `"P-256"` (openssl curve `secp256r1`)
+2. `"P-384"` (openssl curve `secp384r1`)
+3. `"P-521"` (openssl curve `secp521r1`)
+
+### Method 1
+
+The basic formula for key generation is `openssl ecparam -name CURVE -genkey -noout -out FILE`, for example:
+
+```bash
+openssl ecparam -name secp256r1 -genkey -noout -out ec-secp256r1.pem
+openssl ecparam -name secp384r1 -genkey -noout -out ec-secp384r1.pem
+openssl ecparam -name secp521r1 -genkey -noout -out ec-secp521r1.pem
+```
+
+The PEM files can then be read using {JOSE::JWK.from_pem_file JOSE::JWK.from_pem_file}:
+
+```ruby
+jwk = JOSE::JWK.from_pem_file("ec-secp256r1.pem")
+```
+
+### Method 2
+
+The curve names are almost the same as the ones for OpenSSL.
+
+```ruby
+jwk = JOSE::JWK.generate_key([:ec, 'prime256v1'])
+jwk = JOSE::JWK.generate_key([:ec, 'secp384r1'])
+jwk = JOSE::JWK.generate_key([:ec, 'secp521r1'])
+
+# Alternative curve alias syntax:
+jwk = JOSE::JWK.generate_key([:ec, 'P-256'])
+jwk = JOSE::JWK.generate_key([:ec, 'P-384'])
+jwk = JOSE::JWK.generate_key([:ec, 'P-521'])
+```
+
+Keys may also be generated based on other keys.  The new key will use the same curve as the supplied key.
+
+```ruby
+old_jwk = JOSE::JWK.from_pem_file("ec-secp256r1.pem")
+new_jwk = JOSE::JWK.generate_key(old_jwk)
+```
+
+### Method 3
+
+If you have a JWE header with an `"epk"` field, a new key will be generated based on the same key type of the `"epk"`.  Otherwise, the `P-521` curve will be used.
+
+```ruby
+# Based on the "epk" field.
+epk = JOSE::JWK.generate_key([:ec, 'P-256'])
+jwe = JOSE::JWE.from_map({"alg" => "ECDH-ES", "enc" => "A128GCM", "epk" => epk.to_map})
+jwk = jwe.generate_key
+
+# Otherwise, defaults to "P-521".
+jwk = JOSE::JWE.generate_key({"alg" => "ECDH-ES", "enc" => "A128GCM"})
+```
+
+### Method 4
+
+If you have a JWS header with one of the ECDSA signature algorithms specified, a corresponding EC key will be generated with the correct curve for the signature type.
+
+```ruby
+jwk_ec256 = JOSE::JWS.generate_key({"alg" => "ES256"})
+jwk_ec384 = JOSE::JWS.generate_key({"alg" => "ES384"})
+jwk_ec521 = JOSE::JWS.generate_key({"alg" => "ES512"})
+```
+
+## oct
+
+This key type is simply an octet or byte sequence (see [RFC 7518 Section 6.4](https://tools.ietf.org/html/rfc7518#section-6.4)).
+
+### Method 1
+
+The basic formula for generating a random octet sequence is `openssl rand -out FILE BYTE_SIZE`, for example:
+
+```bash
+openssl rand -out oct-128-bit.bin 16
+```
+
+The binary file can then be read using {JOSE::JWK.from_oct_file JOSE::JWK.from_oct_file}:
+
+```ruby
+jwk = JOSE::JWK.from_oct_file("oct-128-bit.bin")
+```
+
+### Method 2
+
+Calling either of these functions with an integer will generate a random octet sequence.
+
+```ruby
+jwk = JOSE::JWK.generate_key([:oct, 16])
+```
+
+Keys may also be generated based on other keys.  The new key will use the same byte size as the supplied key.
+
+```ruby
+old_jwk = JOSE::JWK.from_oct_file("oct-128-bit.bin")
+new_jwk = JOSE::JWK.generate_key(old_jwk)
+```
+
+### Method 3
+
+If you have a JWE header with an `"alg"` field that requires a symmetric key, a new `oct` key will be generated based on the byte size required of `"alg"` and/or `"enc"`.
+
+```ruby
+jwk_oct16 = JOSE::JWE.generate_key({"alg" => "dir", "enc" => "A128GCM"})
+jwk_oct24 = JOSE::JWE.generate_key({"alg" => "dir", "enc" => "A192GCM"})
+jwk_oct32 = JOSE::JWE.generate_key({"alg" => "dir", "enc" => "A256GCM"})
+jwk_oct32 = JOSE::JWE.generate_key({"alg" => "dir", "enc" => "A128CBC-HS256"})
+jwk_oct48 = JOSE::JWE.generate_key({"alg" => "dir", "enc" => "A192CBC-HS384"})
+jwk_oct64 = JOSE::JWE.generate_key({"alg" => "dir", "enc" => "A256CBC-HS512"})
+```
+
+### Method 4
+
+If you have a JWS header with an `"alg"` field that requires a symmetric key, a new `oct` key will be generated based on the byte size recommended for `"alg".
+
+```ruby
+jwk_oct32 = JOSE::JWS.generate_key({"alg" => "HS256"})
+jwk_oct48 = JOSE::JWS.generate_key({"alg" => "HS384"})
+jwk_oct64 = JOSE::JWS.generate_key({"alg" => "HS512"})
+```
+
+## OKP
+
+This key type is an octet key pair with an associated curve (see [draft-ietf-jose-cfrg-curves](https://tools.ietf.org/html/draft-ietf-jose-cfrg-curves)).
+
+### Method 1
+
+*NOTE:* Only `Ed25519` is currently supported by `ssh-keygen`.
+
+The basic formula for generating a octet key pair is `ssh-keygen -t TYPE -f FILE`, for example:
+
+```bash
+ssh-keygen -t ed25519 -f ed25519
+```
+
+The private key file can then be read using {JOSE::JWK.from_openssh_key_file JOSE::JWK.from_openssh_key_file}:
+
+```ruby
+jwk = JOSE::JWK.from_openssh_key_file("ed25519")
+```
+
+### Method 2
+
+Calling either of these functions with a specified curve will generate an octet key pair.  You may also specify the secret portion of the key after the curve.
+
+```ruby
+# Curve25519
+jwk_Ed25519   = JOSE::JWK.generate_key([:okp, :Ed25519])
+jwk_Ed25519ph = JOSE::JWK.generate_key([:okp, :Ed25519ph])
+jwk_X25519    = JOSE::JWK.generate_key([:okp, :X25519])
+
+# Curve448
+jwk_Ed448   = JOSE::JWK.generate_key([:okp, :Ed448])
+jwk_Ed448ph = JOSE::JWK.generate_key([:okp, :Ed448ph])
+jwk_X448    = JOSE::JWK.generate_key([:okp, :X448])
+```
+
+Keys may also be generated based on other keys.  The new key will use the same curve as the supplied key.
+
+```ruby
+old_jwk = JOSE::JWK.from_openssh_key_file("ed25519")
+new_jwk = JOSE::JWK.generate_key(old_jwk)
+```
+
+### Method 3
+
+If you have a JWE header with an `"epk"` field, a new key will be generated based on the same key type of the `"epk"`.
+
+```ruby
+# Based on the "epk" field.
+epk = JOSE::JWK.generate_key([:okp, :X25519])
+jwe = JOSE::JWE.from_map({"alg" => "ECDH-ES", "enc" => "A128GCM", "epk" => epk.to_map})
+jwk = jwe.generate_key
+```
+
+### Method 4
+
+If you have a JWS header with one of the EdDSA signature algorithms specified, a corresponding OKP key will be generated with the correct curve for the signature type.
+
+```ruby
+jwk_Ed25519   = JOSE::JWS.generate_key({"alg" => "Ed25519"})
+jwk_Ed25519ph = JOSE::JWS.generate_key({"alg" => "Ed25519ph"})
+jwk_Ed448     = JOSE::JWS.generate_key({"alg" => "Ed448"})
+jwk_Ed448ph   = JOSE::JWS.generate_key({"alg" => "Ed448ph"})
+```
+
+## RSA
+
+Both two-prime and multi-prime RSA keys are supported by [RFC 7518 Section 6.3](https://tools.ietf.org/html/rfc7518#section-6.3), but currently only two-prime RSA keys can be generated by OpenSSL-based generators.  Ruby does not support multi-prime RSA at this time.
+
+### Method 1
+
+The basic formula for generating a RSA key is `openssl genrsa -out FILE BIT_SIZE`, for example:
+
+```bash
+openssl genrsa -out rsa-2048.pem 2048
+```
+
+The PEM file can then be read using {JOSE::JWK.from_pem_file JOSE::JWK.from_pem_file}:
+
+```ruby
+jwk = JOSE::JWK.from_pem_file("rsa-2048.pem")
+```
+
+### Method 2
+
+The modulus bit size is the only required argument.  Optionally, you may specify the public exponent as the second argument (default is `65537`).
+
+```ruby
+jwk = JOSE::JWK.generate_key([:rsa, 2048])
+
+# Alternative explicit syntax with public exponent:
+jwk = JOSE::JWK.generate_key([:rsa, 4096, 65537])
+```
+
+Keys may also be generated based on other keys.  The new key will use the same modulus size and public exponent as the supplied key.
+
+```ruby
+old_jwk = JOSE::JWK.from_pem_file("rsa-2048.pem")
+new_jwk = JOSE::JWK.generate_key(old_jwk)
+```
+
+### Method 3
+
+If you have a JWE header with an `"alg"` field that requires an asymmetric RSA key, a new `RSA` key will be generated. 2048-bit keys are generated in these cases.
+
+```ruby
+jwk_rsa1_5      = JOSE::JWE.generate_key({"alg" => "RSA1_5", "enc" => "A128GCM"})
+jwk_rsa_oaep    = JOSE::JWE.generate_key({"alg" => "RSA-OAEP", "enc" => "A128GCM"})
+jwk_rsa_oaep256 = JOSE::JWE.generate_key({"alg" => "RSA-OAEP-256", "enc" => "A128GCM"})
+```
+
+### Method 4
+
+If you have a JWS header with one of the RSA PKCS1 or PSS signature algorithms specified, a corresponding RSA key will be generated with a recommended modulus size based on the digest type.
+
+```ruby
+# RS256, RS384, RS512
+jwk_rsa2048 = JOSE::JWS.generate_key({"alg" => "RS256"})
+jwk_rsa3072 = JOSE::JWS.generate_key({"alg" => "RS384"})
+jwk_rsa4096 = JOSE::JWS.generate_key({"alg" => "RS512"})
+
+# PS256, PS384, PS512
+jwk_rsa2048 = JOSE::JWS.generate_key({"alg" => "PS256"})
+jwk_rsa3072 = JOSE::JWS.generate_key({"alg" => "PS384"})
+jwk_rsa4096 = JOSE::JWS.generate_key({"alg" => "PS512"})
+```