From ef58e15547ee171a716eaa768374e2e7e2f7d397 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 25 Oct 2017 20:17:21 +0100 Subject: Introduce cowboy_req:sock/1 and cowboy_req:cert/1 To obtain the local socket ip/port and the client TLS certificate, respectively. --- doc/src/manual/cowboy_req.asciidoc | 11 ++++- doc/src/manual/cowboy_req.cert.asciidoc | 71 +++++++++++++++++++++++++++++++++ doc/src/manual/cowboy_req.peer.asciidoc | 10 +++-- doc/src/manual/cowboy_req.sock.asciidoc | 51 +++++++++++++++++++++++ 4 files changed, 137 insertions(+), 6 deletions(-) create mode 100644 doc/src/manual/cowboy_req.cert.asciidoc create mode 100644 doc/src/manual/cowboy_req.sock.asciidoc (limited to 'doc') diff --git a/doc/src/manual/cowboy_req.asciidoc b/doc/src/manual/cowboy_req.asciidoc index 7f026c3..b038764 100644 --- a/doc/src/manual/cowboy_req.asciidoc +++ b/doc/src/manual/cowboy_req.asciidoc @@ -29,6 +29,12 @@ and to read the body once. == Exports +Connection: + +* link:man:cowboy_req:peer(3)[cowboy_req:peer(3)] - Peer address and port +* link:man:cowboy_req:sock(3)[cowboy_req:sock(3)] - Socket address and port +* link:man:cowboy_req:cert(3)[cowboy_req:cert(3)] - Client TLS certificate + Raw request: * link:man:cowboy_req:method(3)[cowboy_req:method(3)] - HTTP method @@ -41,7 +47,6 @@ Raw request: * link:man:cowboy_req:uri(3)[cowboy_req:uri(3)] - Reconstructed URI * link:man:cowboy_req:header(3)[cowboy_req:header(3)] - HTTP header * link:man:cowboy_req:headers(3)[cowboy_req:headers(3)] - HTTP headers -* link:man:cowboy_req:peer(3)[cowboy_req:peer(3)] - Peer address and port Processed request: @@ -129,7 +134,9 @@ req() :: #{ path := binary(), %% case sensitive qs := binary(), %% case sensitive headers := cowboy:http_headers(), - peer := {inet:ip_address(), inet:port_number()} + peer := {inet:ip_address(), inet:port_number()}, + sock := {inet:ip_address(), inet:port_number()}, + cert := binary() | undefined } ---- diff --git a/doc/src/manual/cowboy_req.cert.asciidoc b/doc/src/manual/cowboy_req.cert.asciidoc new file mode 100644 index 0000000..c398f60 --- /dev/null +++ b/doc/src/manual/cowboy_req.cert.asciidoc @@ -0,0 +1,71 @@ += cowboy_req:cert(3) + +== Name + +cowboy_req:cert - Client TLS certificate + +== Description + +[source,erlang] +---- +cert(Req :: cowboy_req:req()) -> binary() | undefined +---- + +Return the peer's TLS certificate. + +Using the default configuration this function will always return +`undefined`. You need to explicitly configure Cowboy to request +the client certificate. To do this you need to set the `verify` +transport option to `verify_peer`: + +[source,erlang] +---- +{ok, _} = cowboy:start_tls(example, [ + {port, 8443}, + {cert, "path/to/cert.pem"}, + {verify, verify_peer} +], #{ + env => #{dispatch => Dispatch} +}). +---- + +You may also want to customize the `verify_fun` function. Please +consult the `ssl` application's manual for more details. + +TCP connections do not allow a certificate and this function +will therefore always return `undefined`. + +The certificate can also be obtained using pattern matching: + +[source,erlang] +---- +#{cert := Cert} = Req. +---- + +== Arguments + +Req:: + +The Req object. + +== Return value + +The client TLS certificate. + +== Changelog + +* *2.0*: Function introduced. + +== Examples + +.Get the client TLS certificate. +[source,erlang] +---- +Cert = cowboy_req:cert(Req). +---- + +== See also + +link:man:cowboy_req(3)[cowboy_req(3)], +link:man:cowboy_req:peer(3)[cowboy_req:peer(3)], +link:man:cowboy_req:sock(3)[cowboy_req:sock(3)] diff --git a/doc/src/manual/cowboy_req.peer.asciidoc b/doc/src/manual/cowboy_req.peer.asciidoc index a091aa2..0f134b3 100644 --- a/doc/src/manual/cowboy_req.peer.asciidoc +++ b/doc/src/manual/cowboy_req.peer.asciidoc @@ -8,14 +8,14 @@ cowboy_req:peer - Peer address and port [source,erlang] ---- -peer(Req :: cowboy_req:req()) -> Peer +peer(Req :: cowboy_req:req()) -> Info -Peer :: {inet:ip_address(), inet:port_number()} +Info :: {inet:ip_address(), inet:port_number()} ---- Return the peer's IP address and port number. -The peer can also be obtained using pattern matching: +The peer information can also be obtained using pattern matching: [source,erlang] ---- @@ -56,4 +56,6 @@ way of determining the source of an HTTP request. == See also -link:man:cowboy_req(3)[cowboy_req(3)] +link:man:cowboy_req(3)[cowboy_req(3)], +link:man:cowboy_req:sock(3)[cowboy_req:sock(3)], +link:man:cowboy_req:cert(3)[cowboy_req:cert(3)] diff --git a/doc/src/manual/cowboy_req.sock.asciidoc b/doc/src/manual/cowboy_req.sock.asciidoc new file mode 100644 index 0000000..c5e7fa7 --- /dev/null +++ b/doc/src/manual/cowboy_req.sock.asciidoc @@ -0,0 +1,51 @@ += cowboy_req:sock(3) + +== Name + +cowboy_req:sock - Socket address and port + +== Description + +[source,erlang] +---- +sock(Req :: cowboy_req:req()) -> Info + +Info :: {inet:ip_address(), inet:port_number()} +---- + +Return the socket's IP address and port number. + +The socket information can also be obtained using pattern matching: + +[source,erlang] +---- +#{sock := {IP, Port}} = Req. +---- + +== Arguments + +Req:: + +The Req object. + +== Return value + +The socket's local IP address and port number. + +== Changelog + +* *2.0*: Function introduced. + +== Examples + +.Get the socket's IP address and port number. +[source,erlang] +---- +{IP, Port} = cowboy_req:sock(Req). +---- + +== See also + +link:man:cowboy_req(3)[cowboy_req(3)], +link:man:cowboy_req:peer(3)[cowboy_req:peer(3)], +link:man:cowboy_req:cert(3)[cowboy_req:cert(3)] -- cgit v1.2.3