OAuth.pm

filter: Statementstmt 100% 43 / 43 Branchbran 100% 8 / 8 Conditioncond 60.0% 3 / 5 MC/DCmcdc 33.3% 1 / 3 Subroutinesub 100% 8 / 8 Podpod 20.0% 1 / 5 totaltotal 88.8% 64 / 72 CC 8 SCAR 10.6
CC
8
Cov
96%
smart_require
5.0
camel
3.0
message
2.0
CRAP 2.9
« OAuth/SignatureMethod/RSA_SHA1.pm ↑ Summary OAuth/V1_0A/UserAuthResponse.pm »
1 package Net::OAuth;
2 14 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 14 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 14 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 sub PROTOCOL_VERSION_1_0() {1}
7 sub PROTOCOL_VERSION_1_0A() {1.001}
8  
9 sub OAUTH_VERSION() {'1.0'}
10  
11 14 our $VERSION = '0.33';
12 14 our $SKIP_UTF8_DOUBLE_ENCODE_CHECK = 0;
13 14 our $PROTOCOL_VERSION = PROTOCOL_VERSION_1_0;
14  
15 # Process-wide default for the signature methods verify() will accept, for
16 # deployments that cannot pass allowed_signature_methods at every call site.
17 # While this is empty and no per-message list is given, verify() croaks
18 # rather than take the algorithm from the message it is verifying -- see the
19 # VERIFYING MESSAGES section of the documentation below.
20 14 our @ALLOWED_SIGNATURE_METHODS = ();
21  
22 18 ▶sub request {
Subroutine request: called CC=1 SCAR=0.0
Pod undocumented
23 18 my $self = shift;
24 18 my $what = shift;
25 18 return $self->message($what . ' Request');
26 }
27  
28 5 ▶sub response {
Subroutine response: called CC=1 SCAR=0.0
Pod undocumented
29 5 my $self = shift;
30 5 my $what = shift;
31 5 return $self->message($what . ' Response');
32 }
33  
34 24 ▶sub message {
Subroutine message: called CC=2 SCAR=7.1
Pod documented
35 24 my $self = shift;
36 24 ▶ my $base_class = ref $self || $self;
Condition33%1/3
ref $self || $self
l!l&&r!l&&!r
0240
MC/DC0%0/2
ref $self || $self
ref $self $self
Truth table33%1/3
A || B
A= ref $selfB= $self
ABresult
1X1
011
000
37 24 my $type = camel(shift);
38 24 my $class = $base_class . '::' . $type;
39 24 smart_require($class, 1);
40 23 return $class;
41 }
42  
43 24 ▶sub camel {
Subroutine camel: called CC=3 SCAR=11.0
Pod undocumented
44 24 my @words;
45 24 foreach (@_) {
46 24 ▶ while (/([A-Za-z0-9]+)/g) {
Branch: 1 branch
BranchTrueFalseTotal
if (/([A-Za-z0-9]+)/g) 74 24 98
47 74 (my $word = $1) =~ s/authentication/auth/i;
48 74 push @words, $word;
49 }
50 }
51 24 my $name = join('', map("\u$_", @words));
52 }
53  
54 14 our %ALREADY_REQUIRED = (); # class_name => rv of ->require
55  
56 97 ▶sub smart_require {
Subroutine smart_require: called CC=5 SCAR=16.1
Pod undocumented
57 97 my $required_class = shift;
58 97 ▶ my $croak_on_error = shift || 0;
Condition100%2/2
shift() || 0
l!l
2473
MC/DC100%1/1
shift() || 0
shift()
Truth table100%2/2
A
A= shift()
Aresult
11
00
59 97 ▶ unless (exists $ALREADY_REQUIRED{$required_class}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $Net::OAuth::ALREADY_REQUIRED{$required_class}) 36 61 97
60 36 my $rv = eval "require $required_class";
61 36 my $error = $@;
62 36 ▶ if ($error) {
Branch: 1 branch
BranchTrueFalseTotal
if ($error) 3 33 36
63 3 ▶ croak $error if $croak_on_error;
Branch: 1 branch
BranchTrueFalseTotal
if $croak_on_error 1 2 3
64 2 return 0;
65 }
66 33 $ALREADY_REQUIRED{$required_class} = $rv;
67 }
68 94 return $ALREADY_REQUIRED{$required_class};
69 }
70  
71 =encoding utf8
72  
73 =head1 NAME
74  
75 Net::OAuth - OAuth 1.0 for Perl
76  
77 =head1 SYNOPSIS
78  
79 use Net::OAuth::Client;
80  
81 # client_id is the Consumer Key, client_secret the Consumer Secret.
82 # Framework-agnostic: supply your own redirect and session handling.
83  
84 my $client = Net::OAuth::Client->new(
85 $client_id,
86 $client_secret,
87 site => 'https://provider.example/',
88 request_token_path => '/oauth/request_token',
89 authorize_path => '/oauth/authorize',
90 access_token_path => '/oauth/access_token',
91 callback => 'https://you.example/auth/callback',
92 session => \&session,
93 );
94  
95 # 1. Send the user to the provider to authorize.
96 $client->authorize_url;
97  
98 # 2. They return to your callback with oauth_token and oauth_verifier.
99 my $access_token = $client->get_access_token($token, $verifier);
100  
101 # 3. Use the access token to fetch a protected resource.
102 my $response = $access_token->get('/profile');
103 die $response->status_line unless $response->is_success;
104 print $response->decoded_content;
105  
106 =head1 IMPORTANT
107  
108 Net::OAuth provides a low-level API for reading and writing OAuth messages.
109  
110 You probably should start with L<Net::OAuth::Client>.
111  
112 =head1 ABSTRACT
113  
114 OAuth is
115  
116 "An open protocol to allow secure API authentication in a simple and standard method from desktop and web applications."
117  
118 In practical terms, OAuth is a mechanism for a Consumer to request protected resources from a Service Provider on behalf of a user.
119  
120 Please refer to the OAuth spec: L<http://oauth.net/documentation/spec>
121  
122 Net::OAuth provides:
123  
124 =over
125  
126 =item * classes that encapsulate OAuth messages (requests and responses).
127  
128 =item * message signing
129  
130 =item * message serialization and parsing.
131  
132 =item * 2-legged requests (aka. tokenless requests, aka. consumer requests), see L</"CONSUMER REQUESTS">
133  
134 =back
135  
136 Net::OAuth does not provide:
137  
138 =over
139  
140 =item * Consumer or Service Provider encapsulation
141  
142 =item * token/nonce/key storage/management
143  
144 =back
145  
146 =head1 DESCRIPTION
147  
148 =head2 OAUTH MESSAGES
149  
150 An OAuth message is a set of key-value pairs. The following message types are supported:
151  
152 Requests
153  
154 =over
155  
156 =item * Request Token (Net::OAuth::RequestTokenRequest)
157  
158 =item * Access Token (Net::OAuth::AccessTokenRequest)
159  
160 =item * User Authentication (Net::OAuth::UserAuthRequest)
161  
162 =item * Protected Resource (Net::OAuth::ProtectedResourceRequest)
163  
164 =item * Consumer Request (Net::OAuth::ConsumerRequest) (2-legged / token-less request)
165  
166 =back
167  
168 Responses
169  
170 =over
171  
172 =item * Request Token (Net::OAuth::RequestTokenResponse)
173  
174 =item * Access Token (Net::OAuth:AccessTokenResponse)
175  
176 =item * User Authentication (Net::OAuth::UserAuthResponse)
177  
178 =back
179  
180 Each OAuth message type has one or more required parameters, zero or more optional parameters, and most allow arbitrary parameters.
181  
182 All OAuth requests must be signed by the Consumer. Responses from the Service Provider, however, are not signed.
183  
184 To create a message, the easiest way is to use the factory methods (Net::OAuth->request, Net::OAuth->response, Net::OAuth->message). The following method invocations are all equivalent:
185  
186 $request = Net::OAuth->request('user authentication')->new(%params);
187 $request = Net::OAuth->request('user_auth')->new(%params);
188 $request = Net::OAuth->request('UserAuth')->new(%params);
189 $request = Net::OAuth->message('UserAuthRequest')->new(%params);
190  
191 The more verbose way is to use the class directly:
192  
193 use Net::OAuth::UserAuthRequest;
194 $request = Net::OAuth::UserAuthRequest->new(%params);
195  
196 You can also create a message by deserializing it from a Authorization header, URL, query hash, or POST body
197  
198 $request = Net::OAuth->request('protected resource')->from_authorization_header($ENV{HTTP_AUTHORIZATION}, %api_params);
199 $request = Net::OAuth->request('protected resource')->from_url($url, %api_params);
200 $request = Net::OAuth->request('protected resource')->from_hash({$q->Vars}, %api_params); # CGI
201 $request = Net::OAuth->request('protected resource')->from_hash($c->request->params, %api_params); # Catalyst
202 $response = Net::OAuth->response('request token')->from_post_body($response_content, %api_params);
203  
204 Note that the deserialization methods (as opposed to new()) expect OAuth protocol parameters to be prefixed with 'oauth_', as you would expect in a valid OAuth message.
205  
206 Before sending a request, the Consumer must first sign it:
207  
208 $request->sign;
209  
210 When receiving a request, the Service Provider should first verify the signature, and should say which signature methods it is willing to accept:
211  
212 $request = Net::OAuth->request('protected resource')->from_authorization_header(
213 $ENV{HTTP_AUTHORIZATION},
214 %api_params,
215 allowed_signature_methods => [qw/HMAC-SHA1 HMAC-SHA256/],
216 );
217 die "Signature verification failed" unless $request->verify;
218  
219 See L</VERIFYING MESSAGES> for why the second part matters.
220  
221 =head2 VERIFYING MESSAGES
222  
223 C<oauth_signature_method> is a message parameter: it is chosen by whoever
224 sent the message, and on the receiving side it arrives from the network
225 along with the signature it describes. C<verify> dispatches on it, so
226 without an C<allowed_signature_methods> list the sender is choosing which
227 algorithm - and therefore which key - the receiver checks their signature
228 with.
229  
230 That is a real problem for a Service Provider deployed with RSA-SHA1,
231 because it holds only the Consumer's B<public> key. An attacker who sends
232 C<oauth_signature_method=HMAC-SHA1> instead moves verification onto the
233 symmetric path, whose key L<Net::OAuth::Request/signature_key> derives
234 from C<consumer_secret> and C<token_secret> - fields RSA-SHA1 does not use
235 and which such a deployment has no reason to keep secret. The equivalent
236 downgrade between two symmetric methods (HMAC-SHA256 to HMAC-SHA1, or to
237 PLAINTEXT) is weaker but is the same mechanism.
238  
239 Pass C<allowed_signature_methods> as an API parameter to any message you
240 are going to C<verify>:
241  
242 allowed_signature_methods => [qw/RSA-SHA1/]
243  
244 C<verify> croaks if the message names anything else. Deployments that
245 cannot reach every call site - because verification happens inside a
246 framework or a wrapper module - can set the process-wide default instead:
247  
248 @Net::OAuth::ALLOWED_SIGNATURE_METHODS = qw/RSA-SHA1/;
249  
250 An C<allowed_signature_methods> on the message overrides that default.
251  
252 If neither is set, C<verify> croaks. There is no method it could safely
253 assume on your behalf: only you know which one your Consumers registered
254 with, and taking the answer from the message is the problem this list
255 exists to solve.
256  
257 Signing is not affected: a Consumer choosing the method for a message it
258 is about to send is choosing for itself, not on someone else's behalf.
259  
260 =head3 Upgrading
261  
262 This is a breaking change. Before this release C<verify> took the
263 algorithm from the message; every existing caller is therefore unpinned,
264 and will croak until it says what it accepts. The migration is one
265 parameter per verifying call site, or one package variable per process,
266 naming the method your Consumers already use - for the great majority of
267 deployments:
268  
269 @Net::OAuth::ALLOWED_SIGNATURE_METHODS = qw/HMAC-SHA1/;
270  
271 The break is deliberate: a warning would have left every deployment that
272 does not read release notes verifying with an attacker-chosen algorithm.
273  
274 When sending a message the last step is to serialize it and send it to wherever it needs to go. The following serialization methods are available:
275  
276 $response->to_post_body # a application/x-www-form-urlencoded POST body
277  
278 $request->to_url # the query string of a URL
279  
280 $request->to_authorization_header # the value of an HTTP Authorization header
281  
282 $request->to_hash # a hash that could be used for some other serialization
283  
284 =head2 API PARAMETERS vs MESSAGE PARAMETERS
285  
286 Net::OAuth defines 'message parameters' as parameters that are part of the transmitted OAuth message. These include any protocol parameter (prefixed with 'oauth_' in the message), and any additional message parameters (the extra_params hash).
287  
288 'API parameters' are parameters required to build a message object that are not transmitted with the message, e.g. consumer_secret, token_secret, request_url, request_method.
289  
290 There are various methods to inspect a message class to see what parameters are defined:
291  
292 $request->required_message_params;
293 $request->optional_message_params;
294 $request->all_message_params;
295 $request->required_api_params;
296 $request->optional_api_params;
297 $request->all_api_params;
298 $request->all_params;
299  
300 E.g.
301  
302 use Net::OAuth;
303 use Data::Dumper;
304 print Dumper(Net::OAuth->request("protected resource")->required_message_params);
305  
306 $VAR1 = [
307 'consumer_key',
308 'signature_method',
309 'timestamp',
310 'nonce',
311 'token'
312 ];
313  
314 =head2 ACCESSING PARAMETERS
315  
316 All parameters can be get/set using accessor methods. E.g.
317  
318 my $consumer_key = $request->consumer_key;
319 $request->request_method('POST');
320  
321 =head2 THE REQUEST_URL PARAMETER
322  
323 Any query parameters in the request_url are removed and added to the extra_params hash when generating the signature.
324  
325 E.g. the following requests are pretty much equivalent:
326  
327 my $request = Net::OAuth->request('Request Token')->new(
328 %params,
329 request_url => 'https://photos.example.net/request_token',
330 extra_params => {
331 foo => 'bar'
332 },
333 );
334  
335 my $request = Net::OAuth->request('Request Token')->new(
336 %params,
337 request_url => 'https://photos.example.net/request_token?foo=bar',
338 );
339  
340 Calling $request->request_url will still return whatever you set it to originally. If you want to get the request_url with the query parameters removed, you can do:
341  
342 my $url = $request->normalized_request_url;
343  
344 =head2 SIGNATURE METHODS
345  
346 The following signature methods are supported:
347  
348 =over
349  
350 =item * PLAINTEXT
351  
352 =item * HMAC-SHA1
353  
354 =item * HMAC-SHA256
355  
356 =item * RSA-SHA1
357  
358 =back
359  
360 The signature method is determined by the value of the signature_method parameter that is passed to the message constructor.
361  
362 If an unknown signature method is specified, the signing/verification will throw an exception.
363  
364 =head3 PLAINTEXT SIGNATURES
365  
366 This method is a trivial signature which adds no security. Not recommended.
367  
368 =head3 HMAC-SHA1 SIGNATURES
369  
370 This method is available if you have Digest::SHA installed. This is by far the most commonly used method.
371  
372 =head3 HMAC-SHA256 SIGNATURES
373  
374 This method is available if you have Digest::SHA installed.
375  
376 =head3 RSA-SHA1 SIGNATURES
377  
378 To use RSA-SHA1 signatures, pass in a Crypt::OpenSSL::RSA object (or any object that can do $o->sign($str) and/or $o->verify($str, $sig))
379  
380 E.g.
381  
382 Consumer:
383  
384 use Crypt::OpenSSL::RSA;
385 use File::Slurp;
386 $keystring = read_file('private_key.pem');
387 $private_key = Crypt::OpenSSL::RSA->new_private_key($keystring);
388 $request = Net::OAuth->request('request token')->new(%params);
389 $request->sign($private_key);
390  
391 Service Provider:
392  
393 use Crypt::OpenSSL::RSA;
394 use File::Slurp;
395 $keystring = read_file('public_key.pem');
396 $public_key = Crypt::OpenSSL::RSA->new_public_key($keystring);
397 $request = Net::OAuth->request('request token')->new(
398 %params,
399 allowed_signature_methods => ['RSA-SHA1'],
400 );
401 if (!$request->verify($public_key)) {
402 die "Signature verification failed";
403 }
404  
405 A Service Provider deployed this way holds only the Consumer's public
406 key, so it is the deployment with the most to lose from letting the
407 message choose the algorithm: without C<allowed_signature_methods> a
408 request naming HMAC-SHA1 would be checked against C<consumer_secret>,
409 which RSA-SHA1 does not use and such a deployment has no reason to keep
410 secret. See L</VERIFYING MESSAGES>.
411  
412 Note that you can pass the key in as a parameter called 'signature_key' to the message constructor, rather than passing it to the sign/verify method, if you like.
413  
414 =head2 CONSUMER REQUESTS
415  
416 To send a request without including a token, use a Consumer Request:
417  
418 my $request = Net::OAuth->request('consumer')->new(
419 consumer_key => 'dpf43f3p2l4k3l03',
420 consumer_secret => 'kd94hf93k423kf44',
421 request_url => 'http://provider.example.net/profile',
422 request_method => 'GET',
423 signature_method => 'HMAC-SHA1',
424 timestamp => '1191242096',
425 nonce => 'kllo9940pd9333jh',
426 );
427  
428 $request->sign;
429  
430 See L<Net::OAuth::ConsumerRequest>
431  
432 =head2 I18N
433  
434 Per the OAuth spec, when making the signature Net::OAuth first encodes parameters to UTF-8. This means that any parameters you pass to Net::OAuth, if they might be outside of ASCII character set, should be run through Encode::decode() (or an equivalent PerlIO layer) first to decode them to Perl's internal character structure.
435  
436 =head2 OAUTH 1.0A
437  
438 Background:
439  
440 L<http://mojodna.net/2009/05/20/an-idiots-guide-to-oauth-10a.html>
441  
442 L<http://oauth.googlecode.com/svn/spec/core/1.0a/drafts/3/oauth-core-1_0a.html>
443  
444 Net::OAuth defaults to OAuth 1.0 spec compliance, and supports OAuth 1.0 Rev A with an optional switch:
445  
446 use Net::OAuth
447 $Net::OAuth::PROTOCOL_VERSION = Net::OAuth::PROTOCOL_VERSION_1_0A;
448  
449 It is recommended that any new projects use this switch if possible, and existing projects move to supporting this switch as soon as possible. Probably the easiest way for existing projects to do this is to turn on the switch and run your test suite. The Net::OAuth constructor will throw an exception where the new protocol parameters (callback, callback_confirmed, verifier) are missing.
450  
451 Internally, the Net::OAuth::Message constructor checks $Net::OAuth::PROTOCOL_VERSION and attempts to load the equivalent subclass in the Net::OAuth::V1_0A:: namespace. So if you instantiate a Net::OAuth::RequestTokenRequest object, you will end up with a Net::OAuth::V1_0A::RequestTokenRequest (a subclass of Net::OAuth::RequestTokenRequest) if the protocol version is set to PROTOCOL_VERSION_1_0A. You can also select a 1.0a subclass on a per-message basis by passing
452  
453 protocol_version => Net::OAuth::PROTOCOL_VERSION_1_0A
454  
455 in the API parameters hash.
456  
457 If you are not sure whether the entity you are communicating with is 1.0A compliant, you can try instantiating a 1.0A message first and then fall back to 1.0 if that fails:
458  
459 use Net::OAuth
460 $Net::OAuth::PROTOCOL_VERSION = Net::OAuth::PROTOCOL_VERSION_1_0A;
461 my $is_oauth_1_0 = 0;
462 my $response = eval{Net::OAuth->response('request token')->from_post_body($res->content)};
463 if ($@) {
464 if ($@ =~ /Missing required parameter 'callback_confirmed'/) {
465 # fall back to OAuth 1.0
466 $response = Net::OAuth->response('request token')->from_post_body(
467 $res->content,
468 protocol_version => Net::OAuth::PROTOCOL_VERSION_1_0
469 );
470 $is_oauth_1_0 = 1; # from now on treat the server as OAuth 1.0 compliant
471 }
472 else {
473 die $@;
474 }
475 }
476  
477 At some point in the future, Net::OAuth will default to Net::OAuth::PROTOCOL_VERSION_1_0A.
478  
479 =head1 SEE ALSO
480  
481 L<http://oauth.net>
482  
483 Check out L<Net::OAuth::Simple> - it has a simpler API that may be more to your liking
484  
485 Check out L<Net::Twitter::OAuth> for a Twitter-specific OAuth API
486  
487 Check out L<WWW::Netflix::API> for a Netflix-specific OAuth API
488  
489 =head1 TODO
490  
491 =over
492  
493 =item * Support for repeating/multivalued parameters
494  
495 =item * Add convenience methods for SPs
496  
497 Something like:
498  
499 # direct from CGI.pm object
500 $request = Net::OAuth->request('Request Token')->from_cgi_query($cgi, %api_params);
501  
502 # direct from Catalyst::Request object
503 $request = Net::OAuth->request('Request Token')->from_catalyst_request($c->req, %api_params);
504  
505 # from Auth header and GET and POST params in one
506 local $/;
507 my $post_body = <STDIN>;
508 $request = Net::OAuth->request('Request Token')->from_auth_get_and_post(
509 $ENV{HTTP_AUTHORIZATION},
510 $ENV{QUERY_STRING},
511 $post_body,
512 %api_params
513 );
514  
515 =back
516  
517 =head1 AUTHOR
518  
519 Originally by Keith Grennan <foss@nearlyfree.org>
520  
521 Currently maintained by Robert Rothenberg <perl@rhizomnic.com>
522  
523 =head1 CONTRIBUTORS
524  
525 Adam Taylor
526  
527 Brad Whitaker
528  
529 Cosimo Streppone <cosimo@cpan.org>
530  
531 Daisuke Maki
532  
533 Gregor Herrmann
534  
535 James Raspass <jraspass@gmail.com>
536  
537 Jeff Dairiki
538  
539 Jens Rehsack
540  
541 Katou Akira
542  
543 Masayoshi Sekimura
544  
545 Marc Mims
546  
547 Mike Schleif
548  
549 Nobuo Danjou
550  
551 Pattawan Gerlings-Kaewduangdee (oiami)
552  
553 Sergey Romanov <sromanov-dev@yandex.ru>
554  
555 Shawn Moore <cpan@sartak.org>
556  
557 Simon Wistow
558  
559 Tomaž Šolc <avian@cpan.org>
560  
561 =head1 COPYRIGHT & LICENSE
562  
563 Copyright 2007-2012, 2024-2026 Keith Grennan
564  
565 This program is free software; you can redistribute it and/or modify it
566 under the same terms as Perl itself.
567  
568 =cut
569  
570 14 1;
« OAuth/SignatureMethod/RSA_SHA1.pm ↑ Summary OAuth/V1_0A/UserAuthResponse.pm »