.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Net::Duo 3pm" .TH Net::Duo 3pm "2015-08-16" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Net::Duo \- API for Duo multifactor authentication service .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& my $duo = Net::Duo\->new({ key_file => \*(Aq/path/to/keys.json\*(Aq }); \& my $reply = $duo\->call_json(\*(AqGET\*(Aq, \*(Aq/auth/v2/check\*(Aq); .Ve .SH "REQUIREMENTS" .IX Header "REQUIREMENTS" Perl 5.14 or later and the modules HTTP::Request and HTTP::Response (part of HTTP::Message), \s-1JSON, LWP \s0(also known as libwww-perl), Perl6::Slurp, and URI::Escape (part of \s-1URI\s0), all of which are available from \s-1CPAN.\s0 .SH "DESCRIPTION" .IX Header "DESCRIPTION" Net::Duo provides an object-oriented Perl interface for generic calls to one of the the Duo Security \s-1REST\s0 APIs. This module is intended primarily for use as a base class for more specialized Perl modules implementing the specific Duo APIs, but it can also be used directly to make generic \s-1API\s0 calls. .PP On failure, all methods throw a Net::Duo::Exception object. This can be interpolated into a string for a simple error message, or inspected with method calls for more details. This is also true of all methods in all objects in the Net::Duo namespace. .SH "CLASS METHODS" .IX Header "CLASS METHODS" .IP "new(\s-1ARGS\s0)" 4 .IX Item "new(ARGS)" Create a new Net::Duo object. This should be used for all subsequent \s-1API\s0 calls. \s-1ARGS\s0 should be a hash reference with one or more of the following keys: .RS 4 .IP "api_hostname" 4 .IX Item "api_hostname" The \s-1API\s0 hostname returned by Duo when the \s-1API\s0 integration was created. .Sp This key is required if \f(CW\*(C`key_file\*(C'\fR is not set. .IP "integration_key" 4 .IX Item "integration_key" The integration key returned by Duo when the \s-1API\s0 integration was created. This is effectively the public \*(L"username\*(R" for this integration. .Sp This key is required if \f(CW\*(C`key_file\*(C'\fR is not set. .IP "key_file" 4 .IX Item "key_file" The path to a file in \s-1JSON\s0 format that contains the key and hostname data for a Duo integration. This file should contain one \s-1JSON\s0 object with keys \&\f(CW\*(C`integration_key\*(C'\fR, \f(CW\*(C`secret_key\*(C'\fR, and \f(CW\*(C`api_hostname\*(C'\fR. These are the three data values that are returned when one creates a new Duo \s-1API\s0 integration. .Sp Be aware that the \f(CW\*(C`secret_key\*(C'\fR value in this file is security-sensitive information equivalent to a password. Anyone in possession of that key has complete control of all data and actions to which the integration has access. .Sp Either this key or all of \f(CW\*(C`integration_key\*(C'\fR, \f(CW\*(C`secret_key\*(C'\fR, and \&\f(CW\*(C`api_hostname\*(C'\fR must be provided. If both this key and some of those keys are provided, their values will override the values retrieved from the \f(CW\*(C`key_file\*(C'\fR file. .IP "secret_key" 4 .IX Item "secret_key" The secret key returned by Duo when the \s-1API\s0 integration was created. This is security-sensitive information equivalent to a password. Anyone in possession of that key has complete control of all data and actions to which the integration has access. Do not hard-code this into programs; instead, read it from a file with appropriate permissions or retrieve it via some other secure mechanism. .Sp This key is required if \f(CW\*(C`key_file\*(C'\fR is not set. .IP "user_agent" 4 .IX Item "user_agent" The user agent to use for all requests. This should be a Perl object that supports the same \s-1API\s0 as LWP::UserAgent. .Sp Normally, the caller will not provide this key, in which case Net::Duo will create an LWP::UserAgent object internally to use to make Duo \s-1API\s0 calls. This argument is provided primarily so that the user agent can be overridden for unit testing. .RE .RS 4 .RE .SH "INSTANCE METHODS" .IX Header "INSTANCE METHODS" .IP "call(\s-1METHOD,\s0 PATH[, \s-1ARGS\s0])" 4 .IX Item "call(METHOD, PATH[, ARGS])" Make a generic Duo \s-1API\s0 call, with no assumptions about the response. .Sp This is a low-level escape hatch to make any Duo \s-1API\s0 call that this module does not know about, regardless of what format in which it returns its results. The caller will have to provide all of the details (\s-1HTTP\s0 method, \&\s-1URL\s0 path, and all arguments as a reference to a hash of key/value pairs). The \s-1URL\s0 path must start with a slash. .Sp The return value is the resulting HTTP::Response object from the web \s-1API\s0 call. No error checking will be performed. The caller is responsible for examining the HTTP::Response object for any problems, including internal or \s-1HTTP\s0 errors. .Sp Most Duo \s-1API\s0 calls return structured \s-1JSON\s0 and follow a standard pattern for indicating errors. For those calls, use \fIcall_json()\fR instead of this method. \fIcall()\fR is needed only for the small handful of \s-1API\s0 calls that do not return \s-1JSON\s0 in that format, such as the Auth \s-1API \s0\f(CW\*(C`/logo\*(C'\fR endpoint. .IP "call_json(\s-1METHOD,\s0 PATH[, \s-1ARGS\s0])" 4 .IX Item "call_json(METHOD, PATH[, ARGS])" Make a generic Duo \s-1API\s0 call that returns a \s-1JSON\s0 response. .Sp This is the escape hatch to use to make any Duo \s-1API\s0 call that this module does not know about. The caller will have to provide all of the details (\s-1HTTP\s0 method, \s-1URL\s0 path, and all arguments as a reference to a hash of key/value pairs). The \s-1URL\s0 path must start with a slash. .Sp The return value will be only the value of the response key from the returned \s-1JSON. \s0 This method still handles checking the \f(CW\*(C`stat\*(C'\fR value from Duo and throwing a Net::Duo::Exception object on call failure. .Sp This method cannot be used with the small handful of \s-1API\s0 calls that do not return \s-1JSON,\s0 such as the Auth \s-1API \s0\f(CW\*(C`/logo\*(C'\fR endpoint. .SH "AUTHOR" .IX Header "AUTHOR" Russ Allbery .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2014 The Board of Trustees of the Leland Stanford Junior University .PP Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \*(L"Software\*(R"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: .PP The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. .PP \&\s-1THE SOFTWARE IS PROVIDED \*(L"AS IS\*(R", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\s0 .SH "SEE ALSO" .IX Header "SEE ALSO" Duo Auth \s-1API\s0 .PP Duo Verify \s-1API\s0 .PP Duo Admin \s-1API\s0 .PP This module is part of the Net::Duo distribution. The current version of Net::Duo is available from \s-1CPAN,\s0 or directly from its web site at .