| 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
MC/DC0%0/2
ref $self || $self
ref $self
$self
Truth table33%1/3
A || B
A= ref $selfB= $self
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
MC/DC100%1/1
shift() || 0
shift()
Truth table100%2/2
A
A= shift()
| |||||||||||||||||||||
| 59 | 97 | ▶ | unless (exists $ALREADY_REQUIRED{$required_class}) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 60 | 36 | my $rv = eval "require $required_class"; | |||||||||||||||||||
| 61 | 36 | my $error = $@; | |||||||||||||||||||
| 62 | 36 | ▶ | if ($error) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 63 | 3 | ▶ | croak $error if $croak_on_error; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 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; | |||||||||||||||||||