View Source http_message_signatures (http_message_signatures v1.0.0-alpha.1)
Verify / Sign HTTP requests / responses using HTTP Message Signatures
RFC draft-ietf-httpbis-message-signatures-19 -https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures
Summary
Functions
Sign a HTTP request / response
Sign a HTTP request / response using JOSE JWS
Verify HTTP request / response signatures
Verify HTTP request / response signatures using JOSE JWS
Types
-type body() :: iolist() | binary().
-type component() ::
method | target_uri | authority | scheme | request_target | path | query | query_params |
status | request_response |
binary().
-type header() :: {Field :: [byte()], Value :: header_value()}.
-type header_value() :: binary() | iolist().
-type headers() :: [header()].
-type method() :: head | get | put | patch | post | trace | options | delete.
-type parameters() :: [{created, calendar:datetime()} | {expires, calendar:datetime()} | {nonce, binary()} | {alg, binary()} | {keyid, binary()} | {tag, binary()}].
-type sign_base_options() :: #{expires => calendar:datetime(), created => calendar:datetime(), nonce => binary(), alg => binary(), keyid := binary(), tag => binary(), components => [component()], key => binary()}.
-type sign_jws_options() :: #{expires => calendar:datetime(), created => calendar:datetime(), nonce => binary(), keyid := binary(), tag => binary(), components => [component()], key => binary()}.
-type sign_options() :: #{expires => calendar:datetime(), created => calendar:datetime(), nonce => binary(), alg := binary(), keyid := binary(), tag => binary(), components => [component()], key => binary(), signer := signer()}.
-type signer() :: fun((Data :: iolist() | binary()) -> binary()).
-type status() :: 100..599.
-type url() :: uri_string:uri_string().
-type verifier() :: verifier(term()).
-type verifier(Reason) :: fun((Data :: iolist() | binary(), Signature :: binary(), Parameters :: parameters()) -> ok | {error, Reason}).
-type verify_error_reason() ::
{parse_error, Type :: signature | input, Subject :: binary(), ErrorDescription :: binary()}.
-type verify_options() :: verify_options(term()).
-type verify_options(VerifierErrorReason) :: #{verifier := verifier(VerifierErrorReason)}.
Functions
-spec sign(Message, Options) -> Message when Message :: request() | response(), Options :: sign_options().
Sign a HTTP request / response
Example
Request = #{
method => get,
url => <<"https://example.com/path?queryString">>,
headers => [{"content-type", "text/plain"}]
},
SignedRequest = http_message_signatures:sign(
Request,
#{
components => [method, path, <<"content-type">>],
key => <<"sig1">>,
signer => fun(Data) ->
execute_signature(Data)
end
}
).-spec sign_jws(Message, Jwk, Options) -> Message when Message :: request() | response(), Jwk :: jose_jwk:key(), Options :: sign_jws_options().
Sign a HTTP request / response using JOSE JWS
Example
Request = #{
method => get,
url => <<"https://example.com/path?queryString">>,
headers => [{"content-type", "text/plain"}]
},
SignedRequest = http_message_signatures:sign_jws(
Request,
jose_jwk:from_pem_file("path-to-priv.pem"),
#{
components => [method, path, <<"content-type">>],
key => <<"sig1">>
}
).-spec verify(Message, Options) -> {ok, SignatureParameters} | {error, Reason} when Message :: request() | response(), Options :: verify_options(VerifierErrorReason), Reason :: VerifierErrorReason | verify_error_reason(), SignatureParameters :: #{KeyId := {[component()], parameters()}}, KeyId :: binary().
Verify HTTP request / response signatures
Example
SignedRequest = #{
%% Get the signed request from somewhere
},
{ok, #{<<"sig1">> := {Components, Parameters}} = http_message_signatures:verify(
SignedRequest,
#{
verifier => fun(Data, Signature, SignatureParameters) ->
case execute_signature_verification(Data) of
true -> ok;
false -> {error, invalid_signature}
end
end
}
).-spec verify_jws(Message, Jwk) -> {ok, SignatureParameters} | {error, Reason} when Message :: request() | response(), Jwk :: jose_jwk:key(), Reason :: signature_input_mismatch | invalid_signature | none_alg_used | verify_error_reason(), SignatureParameters :: #{KeyId := {[component()], parameters()}}, KeyId :: binary().
Verify HTTP request / response signatures using JOSE JWS
Example
SignedRequest = #{
%% Get the signed request from somewhere
},
{ok, #{<<"sig1">> := {Components, Parameters}} = http_message_signatures:verify_jws(
SignedRequest,
jose_jwk:from_pem_file("path-to-pub.pem")
).