Name Date Size #Lines LOC

..08-Nov-2019-

python_signer/H11-Jan-2020-

unit_tests/H20-Aug-2019-

Makefile.incH A D20-Nov-20192.1 KiB4524

README.mdH A D20-Nov-20197.7 KiB232179

common.cH A D15-Jan-2019975 3311

common.hH A D11-Jan-20201.6 KiB4318

config.cH A D11-Jan-202010.6 KiB381319

config.hH A D19-Dec-20191.4 KiB4018

cookie.cH A D17-Apr-20192.4 KiB8757

cookie.hH A D19-Dec-2019940 233

jwt.cH A D17-Apr-20199.4 KiB363297

jwt.hH A D19-Dec-20191.4 KiB4927

match.cH A D17-Apr-20191.6 KiB5729

match.hH A D30-Jan-2019943 223

normalize.cH A D14-Feb-202011.7 KiB383255

normalize.hH A D19-Dec-2019991 233

parse.cH A D11-Jan-20208.1 KiB247194

parse.hH A D11-Jan-20201.3 KiB339

timing.cH A D01-Dec-2017926 233

timing.hH A D19-Dec-20191.3 KiB4724

uri_signing.cH A D29-Jan-202010.2 KiB371283

README.md

1URI Signing Plugin
2==================
3
4This remap plugin implements the draft URI Signing protocol documented [here](https://tools.ietf.org/html/draft-ietf-cdni-uri-signing-16):
5
6It takes a single argument: the name of a config file that contains key information.
7
8**Nota bene:** Take care in ordering the plugins. In general, this plugin
9should be first on the remap line. This is for two reasons. First, if no valid
10token is present, it is probably not useful to continue processing the request
11in future plugins.  Second, and more importantly, the signature should be
12verified _before_ any other plugins modify the request. If another plugin drops
13or modifies the query string, the token might be missing entirely by the time
14this plugin gets the URI.
15
16Config
17------
18
19### Keys
20
21The config file should be a JSON object that maps issuer names to JWK-sets.
22Exactly one of these JWK-sets must have an additional member indicating the
23renewal key.
24
25    {
26      "Kabletown URI Authority": {
27        "renewal_kid": "Second Key",
28        "keys": [
29          {
30            "alg": "HS256",
31            "kid": "First Key",
32            "kty": "oct",
33            "k": "Kh_RkUMj-fzbD37qBnDf_3e_RvQ3RP9PaSmVEpE24AM"
34          },
35          {
36            "alg": "HS256",
37            "kid": "Second Key",
38            "kty": "oct",
39            "k": "fZBpDBNbk2GqhwoB_DGBAsBxqQZVix04rIoLJ7p_RlE"
40          }
41        ]
42      }
43    }
44
45If there is not precisely one renewal key, the plugin will not load.
46
47Although the `kid` and `alg` parameters are optional in JWKs generally, both
48members must be present in keys used for URI signing.
49
50### Auth Directives
51
52It's occasionally useful to allow un-signed access to specific paths. To
53that end, the `auth_directives` parameter is supported. It can be used
54like this:
55
56    {
57      "Kabletown URI Authority": {
58        "renewal_kid": "Second Key",
59        "auth_directives": [
60          { auth: "allow", uri: "uri-regex:.*crossdomain.xml" },
61          { auth: "deny",  uri: "uri-regex:https?://[^/]*/public/secret.xml.*" },
62          { auth: "allow", uri: "uri-regex:https?://[^/]*/public/.*" },
63          { auth: "allow", uri: "uri-regex:.*favicon.ico" }
64        ]
65        "keys": [
6667        ]
68    }
69
70Each of the `auth_directives` will be evaluated in order for each url
71that does not have a valid token. If it matches an allowed path before
72it matches a denied one, it will be served anyway. If it matches no
73`auth_directives`, it will not be served.
74
75It's worth noting that multiple issuers can provide `auth_directives`.
76Each issuer will be processed in order and any issuer can provide access to
77a path.
78
79### More Configuration Options
80
81**Strip Token**
82When the strip_token parameter is set to true, the plugin removes the
83token from both the url that is sent upstream to the origin and the url that
84is used as the cache key. The strip_token parameter defaults to false and should
85be set by only one issuer.
86**ID**
87The id field takes a string indicating the identification of the entity processing the request.
88This is used in aud claim checks to ensure that the receiver is the intended audience of a
89tokenized request. The id parameter can only be set by one issuer.
90
91Example:
92
93    {
94      "Kabletown URI Authority": {
95        "renewal_kid": "Second Key",
96        "strip_token" : true,
97        "id" : "mycdn",
98        "auth_directives": [
99100        ]
101        "keys": [
102103        ]
104    }
105
106Usage
107-----
108
109The URI signing plugin will block all requests that do not bear a valid JWT, as
110defined by the URI Signing protocol. Clients that do not present a valid JWT
111will receive a 403 Forbidden response, instead of receiving content.
112
113Tokens will be found in either of these places:
114
115  - A query parameter named `URISigningPackage`. The value must be the JWT.
116  - A path parameter named `URISigningPackage`. The value must be the JWT.
117  - A cookie named `URISigningPackage`. The value of the cookie must be the JWT.
118
119### Supported Claims
120
121The following claims are understood:
122
123  - `iss`: Must be present. The issuer is used to locate the key for verification.
124  - `sub`: May be present, but is not validated.
125  - `exp`: Expired tokens are not valid.
126  - `nbf`: Tokens processed before this time are not valid.
127  - `aud`: Token aud claim strings must match the configured id to be considered valid.
128  - `iat`: May be present, but is not validated.
129  - `cdniv`: Must be missing or 1.
130  - `cdniuc`: Validated last, after key verificationD. **Only `regex` is supported!**
131  - `cdniets`: If cdnistt is 1, this must be present and non-zero.
132  - `cdnistt`: If present, must be 1.
133  - `cdnistd`: If present, must be 0.
134
135### Unsupported Claims
136
137These claims are not supported. If they are present, the token will not validate:
138
139  - `jti`
140  - `cdnicrit`
141  - `cdniip`
142
143In addition, the `cdniuc` container of `hash` is
144**not supported**.
145
146### Token Renewal
147
148If the `cdnistt` and `cdniets` claims are present, the token will be renewed.
149The new token will be returned via a `Set-Cookie` header as a session cookie.
150
151However, instead of setting the expiration to be `cdniets` seconds from the
152expiration of the previous cookie, it is set to `cdniets` seconds from the time
153it was validated. This is to prevent a crafty client from repeatedly renewing
154tokens in quick succession to create a super-token that lasts long into the
155future, thereby circumventing the intent of the `exp` claim.
156
157### JOSE Header
158
159The JOSE header of the JWT should contain a `kid` parameter. This is used to
160quickly select the key that was used to sign the token. If it is provided, only
161the key with a matching `kid` will be used for validation. Otherwise, all
162possible keys for that issuer must be tried, which is considerably more
163expensive.
164
165Building
166--------
167
168To build from source, you will need these libraries installed:
169
170  - [cjose](https://github.com/cisco/cjose)
171  - [jansson](https://github.com/akheron/jansson)
172  - pcre
173  - OpenSSL
174
175… as well as compiler toolchain.
176
177This builds in-tree with the rest of the ATS plugins. Of special note, however,
178are the first two libraries: cjose and jansson. These libraries are not
179currently used anywhere else, so they may not be installed.
180
181Note that the default prefix value for cjose is /usr/local. Ensure this is visible to
182any executables that are being run using this library.
183
184As of this writing, both libraries install a dynamic library and a static
185archive. However, by default, the static archive is not compiled with Position
186Independent Code. The build script will detect this and build a dynamic
187dependency on these libraries, so they will have to be distributed with the
188plugin.
189
190If you would like to statically link them, you will need to ensure that they are
191compiled with the `-fPIC` flag in their CFLAGs. If the archives have PIC, the
192build scripts will automatically statically link them.
193
194Here are some sample commands for building jansson, cjose and trafficserver
195locally using static linking.  This assumes all source is under ${HOME}/git.
196
197### Sample
198
199If using local jansson:
200
201    cd ${HOME}/git
202    git clone https://github.com/akheron/jansson.git
203    cd jansson
204    autoreconf -i
205    ./configure --disable-shared CC="gcc -fpic"
206    make -j`nproc`
207
208    # Needed for ATS configure
209    ln -s src/.libs lib
210    ln -s src include
211
212If using local cjose:
213
214    cd ${HOME}/git
215    git clone https://github.com/cisco/cjose.git
216    cd cjose
217    autoreconf -i
218    ./configure --with-jansson=${HOME}/git/jansson --disable-shared CC="gcc -fpic"
219    make -j`nproc`
220
221    # Needed for ATS configure
222    ln -s src/.libs lib
223
224ATS:
225
226    cd ${HOME}/git/
227    git clone https://github.com/apache/trafficserver.git
228    cd trafficserver
229		autoreconf -i
230    ./configure --enable-experimental-plugins --with-jansson=${HOME}/git/jansson --with-cjose=${HOME}/git/cjose
231    make -j`nproc`
232