ExHmac

HMAC Authentication

Installation

Add ExHmac to your list of dependencies in mix.exs:

def deps do
  [{:exhmac, ">= 1.0.0"}]
end

run mix deps.get.

Example

This Example Project is the basis for ExHmac, help you use well.

Download via Gitee or Github.

Once downloaded, Two Things Todo:

mix deps.get
mix test

# confirm gc configs which are expected, run following commands.
# use test.exs to run
MIX_ENV=test iex -S mix
# use dev.exs to run
iex -S mix

Usage

Quick Start

Here’s a commented example.

# Use ExHmac like this in Your Project.
iex> defmodule YourProject do
...>   # inject hmac functions to current scope via use ExHmac.
...>   use ExHmac, precision: :millisecond
...>
...>   @access_key "exhmac_key"
...>   @secret_key "exhmac_secret"
...>
...>   # use gen_timestamp/0, gen_nonce/0 to make params.
...>   def make_params(name) do
...>     [name: name, timestamp: gen_timestamp(), nonce: gen_nonce()]
...>   end
...>
...>   # make signature with access_key & secret_key using sign/3.
...>   def make_signature(params) do
...>     sign(params, @access_key, @secret_key)
...>   end
...>
...>   # use sign/3 & check_hmac/3 to make resp with hmac
...>   def start_request(name) do
...>     # simulate request, prepare params
...>     params = make_params(name)
...>     signature = make_signature(params)
...>     _req_params = [signature: signature] ++ params
...>
...>     # simulate response data
...>     resp_params = [result: 0, timestamp: gen_timestamp(), nonce: gen_nonce()]
...>     signature = sign(resp_params, @access_key, @secret_key)
...>     resp_params = [signature: signature] ++ resp_params
...>     check_hmac(resp_params, @access_key, @secret_key)
...>   end
...> end
...>
iex> # start request & get check response result
...> YourProject.start_request("ljy")
:ok

Check via decorator (Recommended)

Doc is cheap, Show you the Code. Download Example.

Check via defhmac macro (Recommended)

Doc is cheap, Show you the Code. Download Example

Customize Hmac

Support Hash Algs

• :sha & :hmac_sha
• :sha512 & :hmac_sha512
• :sha384 & :hmac_sha384
• :sha256 & :hmac_sha256
• :sha224 & :hmac_sha224
• :sha3_512 & :hmac_sha3_512
• :sha3_384 & :hmac_sha3_384
• :sha3_256 & :hmac_sha3_256
• :sha3_224 & :hmac_sha3_224
• :blake2b & :hmac_blake2b
• :blake2s & :hmac_blake2s
• :md5 & :hmac_md5

Hooks

• pre_hook/1, before check hmac, give you origin args with keyword.
• post_hook/1, after check hmac, this output is final.

These hokks only effect decorator & defhmac.

Callbacks

• get_access_key/1, get/evaluate access key from input args.
• get_secret_key/1, required, you must provide secret.
• check_nonce/4, If you want to use Redis getset command to check nonce, then implements it.
• make_sign_string/3, change sign string rule.
• encode_hash_result/1, defaults to encode hex string.
• fmt_resp/1, format resp to your own format, like: %{result: 0, error_msg: "some error"}.
• gc_log_callback/1, defaults to in-memory cache with gc, collect count up to max will invoke it.

more detail, please Download Example.

Available Configs

as ExHmac opts

use ExHmac,
  # once in-memory cache crash, will lose 2 following configs.
  # you should set them again in config.exs.
  precision: :millisecond,
  nonce_freezing_secs: 60,
  # normal configs
  hash_alg: :hmac_sha512,
  warn: false,
  nonce_len: 20,
  timestamp_offset_secs: 900

the following configs in config.exs

# set them again for exactly gc running.
config :exhmac, :precision, :millisecond
config :exhmac, :nonce_freezing_secs, 60
# normal configs
config :exhmac, :disable_noncer, false # disable local in-memory cache
config :exhmac, :gc_interval_milli, 20_000
config :exhmac, :gc_warn_count, 10
config :exhmac, :gc_log_callback, &MyHmac.gc_log/1

NOTICE: precision & nonce_freezing_secs set 2 places, once you don't want to use default values.

Contributing

Contributions to ExHmac are very welcome!

Bug reports, documentation, spelling corrections... all of those (and probably more) are much appreciated contributions!