Merge pull request #3 from scrogson/merge_rsa

generate_rsa

Author: scrogson

README.md

@@ -7,50 +7,46 @@
 ## Features
 
 In its current state, this library only supports signing JWTs using the `RS512`
-algo with a DER encoded RSA private key.
+algo with a DER or PEM encoded RSA private key.
 
 ## Installation
 
 ```elixir
 def deps do
   [
-    {:no_way_jose, "~> 0.1.0"}
+    {:no_way_jose, "~> 0.2.0"}
   ]
 end
 ```
 
 ## Generating a key
 
-In order to sign a JWT an RSA private key must be provided. The key must be DER
-encoded.
+In order to sign a JWT an RSA private key must be provided.
 
-### Generate an RSA public/private key pair
+### In code
 
-```
-ssh-keygen -m PEM -t rsa -b 4096 -f private.pem
-# Don't add passphrase
-```
+NoWayJose allows generating an RSA private key directly in code by specifying
+the number of bits and an encoding format (PEM or DER):
 
-### Convert the PEM to DER
-
-```
-openssl rsa -in private.pem -outform DER -out private.der
+```elixir
+# PEM encoded RSA private key
+NoWayJose.generate_rsa(4096, :pem)
 ```
 
-Optionally, you can extract the DER data from a PEM encoded private key in code
-using the following:
-
 ```elixir
-{:ok, key} = File.read("private.pem")
-[{:RSAPrivateKey, der, _}] = :public_key.pem_decode(key)
+# DER encoded RSA private key
+NoWayJose.generate_rsa(4096, :der)
 ```
 
 ## Basic usage
 
 ```elixir
-# Get the private signing key
+# Read a private signing key from a file
 {:ok, key} = File.read("private.der")
 
+# Or generate a new one in code
+key = NoWayJose.generate_rsa(4096, :der)
+
 # Build your claims
 claims = %{
   "exp" => 1571065163,
@@ -66,7 +62,7 @@ claims = %{
 }
 
 # Sign the claims into a JWT
-{:ok, token} = NoWayJose.sign(claims, key)
+{:ok, token} = NoWayJose.sign(claims, alg: :rs512, format: :der, key: key)
 ```
 
 ## Documentation

lib/no_way_jose.ex

@@ -4,24 +4,45 @@ defmodule NoWayJose do
   a signing key.
   """
 
+  require Logger
+
   @typedoc """
   A map containing the claims to be encoded. Map keys must be strings.
   """
   @type claims :: %{binary() => term()}
 
   @typedoc """
-  DER encoded RSA private key.
+  Algorithm used in JWT signing.
+  """
+  @type alg :: :rs512
 
-  ## Generating a key
+  @typedoc """
+  The format of the provided key.
+  """
+  @type key_format :: :der | :pem
 
-      ssh-keygen -m PEM -t rsa -b 4096 -f private.pem
+  @typedoc """
+  Key Identifier – Acts as an alias for the key
+  """
+  @type kid :: nil | binary()
+
+  @type signing_option ::
+          {:alg, alg()}
+          | {:format, key_format()}
+          | {:key, key()}
+          | {:kid, kid()}
 
-  Make sure not to set a passphrase.
+  @type signing_options :: [signing_option()]
+
+  @typedoc """
+  RSA private key.
 
+  The key can be either DER or PEM encoded.
 
-  ## Convert the PEM to DER
+  ## Generating a key
 
-      openssl rsa -in private.pem -outform DER -out private.der
+      der = NoWayJose.generate_rsa(4096, :der)
+      pem = NoWayJose.generate_rsa(4096, :pem)
 
   Optionally, you can extract the DER data from a PEM encoded private key in code
   using the following:
@@ -41,9 +62,9 @@ defmodule NoWayJose do
 
   Returns a JWT on success and raises an error on error.
   """
-  @spec sign!(claims(), key()) :: token() | no_return()
-  def sign!(claims, key) do
-    case sign(claims, key) do
+  @spec sign!(claims(), key() | signing_options()) :: token() | no_return()
+  def sign!(claims, opts) do
+    case sign(claims, opts) do
       {:ok, token} -> token
       {:error, error} -> raise error
     end
@@ -74,8 +95,51 @@ defmodule NoWayJose do
       # Sign the claims into a JWT
       {:ok, token} = NoWayJose.sign(claims, key)
   """
-  @spec sign(claims(), key()) :: {:ok, token()} | {:error, term()}
-  def sign(claims, key) do
-    NoWayJose.Native.sign(claims, key)
+  @spec sign(claims(), signing_options()) :: {:ok, token()} | {:error, term()}
+  def sign(claims, key) when is_binary(key) do
+    Logger.warn(
+      "Passing a binary key to sign/2 is deprecated. Please pass a list of signing options."
+    )
+
+    opts = [alg: :rs512, format: :der, key: key]
+    NoWayJose.Native.sign(claims, struct(NoWayJose.Signer, opts))
+  end
+
+  @doc """
+  Generates a signed JWT from the given claims and signing options.
+
+  ## Example
+
+      # Get the private signing key
+      {:ok, key} = File.read("private.pem")
+
+      # Build your claims
+      claims = %{
+        "exp" => 1571065163,
+        "iat" => 1571061563,
+        "iss" => "example.com",
+        "jti" => "a3a31258-2450-490b-86ed-2b8e67f91e20",
+        "nbf" => 1571061563,
+        "scopes" => [
+          "posts.r+w",
+          "comments.r+w"
+        ],
+        "sub" => "4d3796ca-19e0-40e6-97fe-060c0b7e3ce3"
+      }
+
+      # Sign the claims into a JWT
+      {:ok, token} = NoWayJose.sign(claims, alg: :rs512, key: key, format: :pem, kid: "1")
+  """
+  @spec sign(claims(), signing_options()) :: {:ok, token()} | {:error, term()}
+  def sign(claims, opts) when is_list(opts) do
+    NoWayJose.Native.sign(claims, struct(NoWayJose.Signer, opts))
+  end
+
+  @doc """
+  Generates an RSA private key based on the given bit size and format.
+  """
+  @spec generate_rsa(integer(), key_format()) :: binary()
+  def(generate_rsa(bits, format)) do
+    NoWayJose.Native.generate_rsa(bits, format)
   end
 end

lib/no_way_jose/native.ex

@@ -7,5 +7,7 @@ defmodule NoWayJose.Native do
 
   def sign(_claims, _signer), do: nif_error()
 
+  def generate_rsa(_bits, _output), do: nif_error()
+
   defp nif_error, do: :erlang.nif_error(:nif_not_loaded)
 end

lib/no_way_jose/signer.ex

@@ -0,0 +1,15 @@
+defmodule NoWayJose.Signer do
+  @moduledoc false
+
+  defstruct alg: :rs512,
+            key: nil,
+            format: :der,
+            kid: nil
+
+  @type t :: %__MODULE__{
+          alg: NoWayJose.alg(),
+          key: NoWayJose.key(),
+          format: NoWayJose.key_format(),
+          kid: NoWayJose.kid()
+        }
+end

mix.exs

@@ -5,7 +5,7 @@ defmodule NoWayJose.MixProject do
   Rust NIF for signing JWTs
   """
 
-  @version "0.1.0"
+  @version "0.2.0"
 
   def project do
     [
@@ -20,20 +20,20 @@ defmodule NoWayJose.MixProject do
           "https://github.com/scrogson/no-way-jose/blob/v#{@version}/%{path}#L%{line}"
       ],
       elixir: "~> 1.8",
-      elixirc_paths: elixirc_paths(Mix.env()),
       name: "NoWayJose",
       package: [
         exclude_patterns: [
           ~r/\W\.DS_Store$/,
-          ~r/target/,
-          ~r/nowayjose_testutils/
+          ~r/target/
         ],
         files: ["lib", "native", "mix.exs", "README.md", "LICENSE"],
         licenses: ["Apache-2.0"],
         links: %{"GitHub" => "https://github.com/scrogson/no-way-jose"},
         maintainers: ["Sonny Scroggin"]
       ],
-      rustler_crates: rustler_crates(Mix.env()),
+      rustler_crates: [
+        nowayjose: []
+      ],
       start_permanent: Mix.env() == :prod,
       version: @version
     ]
@@ -54,20 +54,4 @@ defmodule NoWayJose.MixProject do
       {:jason, "~> 1.0", only: [:dev, :test]}
     ]
   end
-
-  defp elixirc_paths(:test), do: ["lib", "test/support"]
-  defp elixirc_paths(_), do: ["lib"]
-
-  defp rustler_crates(:test) do
-    [
-      nowayjose: [],
-      nowayjose_testutils: []
-    ]
-  end
-
-  defp rustler_crates(_) do
-    [
-      nowayjose: []
-    ]
-  end
 end