1oauth(n)                             oauth                            oauth(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       oauth - oauth API base signature
9

SYNOPSIS

11       package require Tcl  8.5
12
13       package require oauth  ?1.0.3?
14
15       ::oauth::config
16
17       ::oauth::config ?options...?
18
19       ::oauth::header baseURL ?postQuery?
20
21       ::oauth::query baseURL ?postQuery?
22
23______________________________________________________________________________
24

DESCRIPTION

26       The  oauth package provides a simple Tcl-only library for communication
27       with oauth [http://oauth.net] APIs.  This current version of the  pack‐
28       age  supports  the  Oauth  1.0  Protocol,  as  specified  in  RFC  5849
29       [http://tools.ietf.org/rfc/rfc5849.txt].
30

TLS SECURITY CONSIDERATIONS

32       This package uses the TLS package to handle the security for https urls
33       and other socket connections.
34
35       Policy  decisions like the set of protocols to support and what ciphers
36       to use are not the responsibility of TLS, nor of  this  package  itself
37       however.   Such  decisions are the responsibility of whichever applica‐
38       tion is using the package, and are likely  influenced  by  the  set  of
39       servers the application will talk to as well.
40
41       For  example,  in light of the recent POODLE attack [http://googleonli
42       nesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-
43       ssl-30.html] discovered by Google many servers will disable support for
44       the SSLv3 protocol.  To handle this change the applications  using  TLS
45       must  be  patched,  and not this package, nor TLS itself.  Such a patch
46       may be as simple as generally activating tls1 support, as shown in  the
47       example below.
48
49
50                  package require tls
51                  tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
52
53                  ... your own application code ...
54
55

COMMANDS

57       ::oauth::config
58              When this command is invoked without arguments it returns a dic‐
59              tionary containing the current values of all options.
60
61       ::oauth::config ?options...?
62              When invoked with arguments, options followed by  their  values,
63              it  is  used  to set and query various parameters of application
64              and client, like proxy host and user  agent  for  the  HTTP  re‐
65              quests. The detailed list of options is below:
66
67              -accesstoken string
68                     This is the user's token.
69
70              -accesstokensecret string
71                     This is the user's secret token.
72
73              -consumerkey string
74                     This is the public token of your app.
75
76              -consumersecret string
77                     This is the private token of your app.
78
79              -debug bool
80                     The  default  value  is off. If you change this option to
81                     on, the basic signature just created will be  printed  to
82                     stdout, among other debug output.
83
84              -oauthversion version
85                     This is the version of the OAuth protocol to use.  At the
86                     moment only 1.0 is supported, the default.
87
88              -proxyhost hostname
89                     You can set up a proxy host for send contact the  oauth's
90                     api server.
91
92              -proxyport port-number
93                     Port number of your proxy.
94
95              -signmethod method
96                     The  signature  method  to  use.  OAuth 1.0 only supports
97                     HMAC-SHA1, the default.
98
99              -timeout milliseconds
100                     Timeout in milliseconds  for  your  query.   The  default
101                     value is 6000, i.e. 6 seconds.
102
103              -urlencoding encoding
104                     The  encoding  used  for  creating the x-url-encoded URLs
105                     with ::http::formatQuery. The default is utf-8, as speci‐
106                     fied by RFC 2718 [http://tools.ietf.org/rfc/rfc2718.txt].
107
108       ::oauth::header baseURL ?postQuery?
109              This command is the base signature creator. With proper settings
110              for various tokens and secrets (See ::oauth::config) the  result
111              is the base authentication string to send to the server.
112
113              You  do  not need to call this procedure to create the query be‐
114              cause ::oauth::query (see below) will do for it for you.   Doing
115              so is useful for debugging purposes, though.
116
117              url baseURL
118                     This  argument  is  the URI path to the OAuth API server.
119                     If you plan send a GET query, you should provide  a  full
120                     path.
121
122
123                     HTTP GET
124                     ::oauth::header {https://api.twitter.com/1.1/users/lookup.json?screen_name=AbiertaMente}
125
126
127              url-encoded-string postQuery
128                     When  you  have to send a header in POST format, you have
129                     to put the query string into this argument.
130
131
132                     ::oauth::header {https://api.twitter.com/1.1/friendships/create.json} {user_id=158812437&follow=true}
133
134
135       ::oauth::query baseURL ?postQuery?
136              This procedure will use the settings made  with  ::oauth::config
137              to  create the basic authentication and then send the command to
138              the server API.  It takes the same arguments as ::oauth::header.
139
140              The returned result will be a list containing  2  elements.  The
141              first  element  will  be a dictionary containing the HTTP header
142              data response.  This allows you, for example, to  check  the  X-
143              Rate-Limit  from OAuth.  The second element will be the raw data
144              returned from API server.  This string is usually a json  object
145              which can be further decoded with the functions of package json,
146              or any other json-parser for Tcl.
147
148              Here is an example of how it would work in Twitter. Do not  for‐
149              get  to  replace  the placeholder tokens and keys of the example
150              with your own tokens and keys when trying it out.
151
152              % package require oauth
153              % package require json
154              % oauth::config -consumerkey {your_consumer_key} -consumersecret {your_consumer_key_secret} -accesstoken {your_access_token} -accesstokensecret {your_access_token_secret}
155
156              % set response [oauth::query https://api.twitter.com/1.1/users/lookup.json?screen_name=AbiertaMente]
157              % set jsondata [lindex $response 1]
158              % set data [json::json2dict $jsondata]
159              $ set data [lindex $data 0]
160              % dict for {key val} $data {puts "$key => $val"}
161              id => 158812437
162              id_str => 158812437
163              name => Un Librepensador
164              screen_name => AbiertaMente
165              location => Explico mis tuits ahí →
166              description => 160Caracteres para un SMS y contaba mi vida entera sin recortar vocales. Ahora en Twitter, podemos usar hasta 140 y a mí me sobrarían 20 para contaros todo lo q
167              url => http://t.co/SGs3k9odBn
168              entities => url {urls {{url http://t.co/SGs3k9odBn expanded_url http://librepensamiento.es display_url librepensamiento.es indices {0 22}}}} description {urls {}}
169              protected => false
170              followers_count => 72705
171              friends_count => 53099
172              listed_count => 258
173              created_at => Wed Jun 23 18:29:58 +0000 2010
174              favourites_count => 297
175              utc_offset => 7200
176              time_zone => Madrid
177              geo_enabled => false
178              verified => false
179              statuses_count => 8996
180              lang => es
181              status => created_at {Sun Oct 12 08:02:38 +0000 2014} id 521209314087018496 id_str 521209314087018496 text {@thesamethanhim http://t.co/WFoXOAofCt} source {<a href="http://twitter.com" rel="nofollow">Twitter Web Client</a>} truncated false in_reply_to_status_id 521076457490350081 in_reply_to_status_id_str 521076457490350081 in_reply_to_user_id 2282730867 in_reply_to_user_id_str 2282730867 in_reply_to_screen_name thesamethanhim geo null coordinates null place null contributors null retweet_count 0 favorite_count 0 entities {hashtags {} symbols {} urls {{url http://t.co/WFoXOAofCt expanded_url http://www.elmundo.es/internacional/2014/03/05/53173dc1268e3e3f238b458a.html display_url elmundo.es/internacional/… indices {16 38}}} user_mentions {{screen_name thesamethanhim name Ἑλένη id 2282730867 id_str 2282730867 indices {0 15}}}} favorited false retweeted false possibly_sensitive false lang und
182              contributors_enabled => false
183              is_translator => true
184              is_translation_enabled => false
185              profile_background_color => 709397
186              profile_background_image_url => http://pbs.twimg.com/profile_background_images/704065051/9309c02aa2728bdf543505ddbd408e2e.jpeg
187              profile_background_image_url_https => https://pbs.twimg.com/profile_background_images/704065051/9309c02aa2728bdf543505ddbd408e2e.jpeg
188              profile_background_tile => true
189              profile_image_url => http://pbs.twimg.com/profile_images/2629816665/8035fb81919b840c5cc149755d3d7b0b_normal.jpeg
190              profile_image_url_https => https://pbs.twimg.com/profile_images/2629816665/8035fb81919b840c5cc149755d3d7b0b_normal.jpeg
191              profile_banner_url => https://pbs.twimg.com/profile_banners/158812437/1400828874
192              profile_link_color => FF3300
193              profile_sidebar_border_color => FFFFFF
194              profile_sidebar_fill_color => A0C5C7
195              profile_text_color => 333333
196              profile_use_background_image => true
197              default_profile => false
198              default_profile_image => false
199              following => true
200              follow_request_sent => false
201              notifications => false
202

BUGS, IDEAS, FEEDBACK

204       This document, and the package it describes, will  undoubtedly  contain
205       bugs  and  other problems.  Please report such in the category oauth of
206       the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
207       also  report any ideas for enhancements you may have for either package
208       and/or documentation.
209
210       When proposing code changes, please provide unified diffs, i.e the out‐
211       put of diff -u.
212
213       Note  further  that  attachments  are  strongly  preferred over inlined
214       patches. Attachments can be made by going  to  the  Edit  form  of  the
215       ticket  immediately  after  its  creation, and then using the left-most
216       button in the secondary navigation bar.
217

KEYWORDS

219       RFC 2718, RFC 5849, oauth, twitter
220

CATEGORY

222       Networking
223
225       Copyright (c) 2014 Javi P. <hxm@eggdrop.es>
226
227
228
229
230tcllib                               1.0.3                            oauth(n)
Impressum