Signed URL Plugin¶
This plugin checks a signature query string on a URL and rejects (HTTP 403
)
or redirects (HTTP 302
) when the check fails. The signature is based on a
secret key that both a signing portal and the Traffic Server cache share. The algorithm
for the signature may be either MD5
or SHA1
. When the signature check
passes, the query string of the request is stripped and continues to process as
if there were no query string at all.
Installation¶
To make this plugin available, you must either enable experimental plugins when building Traffic Server:
./configure --enable-experimental-plugins
Or use tsxs to compile the plugin against your current Traffic Server build. To do this, you must ensure that:
Development packages for Traffic Server are installed.
The tsxs binary is in your path.
The version of this plugin you are building, and the version of Traffic Server against which you are building it are compatible.
Once those conditions are satisfied, enter the source directory for the plugin and perform the following:
make -f Makefile.tsxs
make -f Makefile.tsxs install
Configuration¶
Configuring URL signature verification within Traffic Server using this plugin is a two step process. First, you must generate a configuration file containing the list of valid signing keys. Secondly, you must indicate to Traffic Server which URLs require valid signatures.
Generating Keys¶
This plugin comes with two Perl scripts which assist in generating signatures. For Traffic Server to verify URL signatures, it must have the relevant keys. Using the provided genkeys script, you can generate a suitable configuration file:
./genkeys.pl > url_sig.config
The resulting file will look something like the following, with the actual keys differing (as they are generated randomly each time the script is run):
key0 = YwG7iAxDo6Gaa38KJOceV4nsxiAJZ3DS
key1 = nLE3SZKRgaNM9hLz_HnIvrCw_GtTUJT1
key2 = YicZbmr6KlxfxPTJ3p9vYhARdPQ9WJYZ
key3 = DTV4Tcn046eM9BzJMeYrYpm3kbqOtBs7
key4 = C1r6R6MINoQd5YSH25fU66tuRhhz3fs_
key5 = l4dxe6YEpYbJtyiOmX5mafhwKImC5kej
key6 = ekKNHXu9_oOC5eqIGJVxV0vI9FYvKVya
key7 = BrjibTmpTTuhMHqphkQAuCWA0Zg97WQB
key8 = rEtWLb1jcYoq9VG8Z8TKgX4GxBuro20J
key9 = mrP_6ibDBG4iYpfDB6W8yn3ZyGmdwc6M
key10 = tbzoTTGZXPLcvpswCQCYz1DAIZcAOGyX
key11 = lWsn6gUeSEW79Fk2kwKVfzhVG87EXLna
key12 = Riox0SmGtBWsrieLUHVWtpj18STM4MP1
key13 = kBsn332B7yG3HdcV7Tw51pkvHod7_84l
key14 = hYI4GUoIlZRf0AyuXkT3QLvBMEoFxkma
key15 = EIgJKwIR0LU9CUeTUdVtjMgGmxeCIbdg
error_url = 403
This file should be placed in your Traffic Server etc
directory, with permissions and
ownership set such that only the Traffic Server processes may read it.
Important
The configuration file contains the full set of secret keys which Traffic Server will be using to verify incoming requests, and as such should be treated with as much care as any other file in your infrastructure containing keys, pass phrases, and other sensitive data. Unauthorized access to the contents of this file will allow others to spoof requests from your signing portal, thus defeating the entire purpose of using a signing portal in the first place.
Requiring Signatures on URLs¶
To require a valid signature, verified by a key from the list you generated
earlier, modify your remap.config
configuration to include this plugin
for any rules you wish it to affect.
Two parameters for each remap rule are required, and a third one is optional:
@plugin=url_sig.so @pparam=<config file> @pparam=pristineurl
The first simply enables this plugin for the rule. The second specifies the location of the configuration file containing your signing keys. The third one, if present, causes authentication to be performed on the original (pristine) URL as received from the client. (The value of the parameter is not case sensitive.)
For example, if we wanted to restrict all paths under a /download
directory
on our website foo.com
we might have a remap line like this:
map http://foo.com/download/ http://origin.server.tld/download/ \
@plugin=url_sig.so @pparam=url_sig.config
Signing a URL¶
Signing a URL is solely the responsibility of your signing portal service. This
requires that whatever application runs that service must also have a list of
your signing keys (generated earlier in Configuration and stored in the
url_sig.config
file in your Traffic Server configuration directory). How your signing
portal application is informed about, or stores, these keys is up to you, but
it is critical that the keyN
index numbers are matched to the same keys.
Signing is performed by adding several query parameters to a URL, before redirecting the client. The parameters’ values are all generated by your signing portal application, and then a hash is calculated by your portal, using the entire URL just constructed, and attached as the final query parameter.
Note
Ordering is important when adding the query parameters and generating the
signature. The signature itself is a hash, using your chosen algorithm, of
the entire URL to which you are about to redirect the client, up to and
including the S=
substring indicating the signature parameter.
The following list details all the query parameters you must add to the URL you will hand back to the client for redirection.
- Client IP
The IP address of the client being redirected. This must be their IP as it will appear to your Traffic Server cache. Both IP v4 and v6 addresses are supported:
C=<ip address>
- Expiration
The time at which this signature will no longer be valid, expressed in seconds since epoch (and thus in UTC):
E=<seconds since epoch expiration>
- Algorithm
The hash algorithm which your signing portal application has elected to use for this signature:
A=<algorithm number>
The only supported values at this time are:
Value
Algorithm
1
HMAC_SHA1
2
HMAC_MD5
- Key Index
The key number, from your plugin configuration, which was used for this signature. See Configuration for generating these keys and determining the index number of each:
K=<key number>
- Parts
Configures which components of the URL to use for signature verification. The value of this parameter is a string of ones and zeros, each enabling or disabling the use of a URL part for signatures. The URL scheme (e.g.
http://
) is never part of the signature. The first number of this parameter’s value indicates whether to include the FQDN, and all remaining numbers determine whether to use the directory parts of the URL. If there are more directories in the URL than there are numbers in this parameter, the last number is repeated as many times as necessary:P=<parts specification>
Examples include:
Value
Effect
1
Use the FQDN and all directory parts for signature verification.
01
Ignore the FQDN, but verify using all directory parts.
0110
Ignore the FQDN, and use only the first two directory parts, skipping the remainder, for signatures.
110
Use the FQDN and first directory for signature verification, but ignore the remainder of the path.
- Signature
The actual signature hash:
S=<signature hash>
The hash should be calculated in accordance with the parts specification you have declared in the
P=
query parameter, which if you have chosen any value other than1
may require additional URL parsing be performed by your signing portal.Additionally, all query parameters up to and including the
S=
substring for this parameter must be included, and must be in the same order as they are returned to the client for redirection. For obvious reasons, the value of this parameter is not included in the source string being hashed.As a simple example, if we are about to redirect a client to the URL
https://foo.com/downloads/expensive-app.exe
with signature verification enabled, then we will compute a signature on the following string:foo.com/downloads/expensive-app.exe?C=1.2.3.4&E=1453846938&A=1&K=2&P=1&S=
And, assuming that key2 from our secrets file matches our example in Configuration, then our signature becomes:
8c5cfa440458233452ee9b5b570063a0e71827f2
Which is then appended to the URL for redirection as the value of the
S
parameter.For an example implementation of signing which may be adapted for your own portal, refer to the file
sign.pl
included with the source code of this plugin.
Signature query parameters embedded in the URL path.
Optionally signature query parameters may be embedded in an opaque base64 encoded container embedded in the URL path. The format is a semicolon, siganchor string, base64 encoded string.
url_sig
automatically detects the use of embedded path parameters. The following example shows how to generate an embedded path parameters withsign.pl
:./sign.pl --url "http://test-remap.domain.com/vod/t/prog_index.m3u8?appid=2&t=1" --useparts 1 \ --algorithm 1 --duration 86400 --key kSCE1_uBREdGI3TPnr_dXKc9f_J4ZV2f --pathparams --siganchor urlsig curl -s -o /dev/null -v --max-redirs 0 'http://test-remap.domain.com/vod/t;urlsig=O0U9MTQ2MzkyOTM4NTtBPTE7Sz0zO1A9MTtTPTIxYzk2YWRiZWZk'
Edge Cache Debugging¶
To include debugging output for this plugin in your Traffic Server logs, adjust the values
for proxy.config.diags.debug.enabled
and
proxy.config.diags.debug.tags
in your records.config
as so:
CONFIG proxy.config.diags.debug.enabled INT 1
CONFIG proxy.config.diags.debug.tags STRING url_sig
Once updated, issue a traffic_ctl config reload
to make the settings
active.
Example¶
Enable experimental plugins when building Traffic Server:
./configure --enable-experimental-plugins
Generate a secrets configuration for Traffic Server (replacing the output location with something appropriate to your Traffic Server installation):
genkeys.pl > /usr/local/trafficserver/etc/trafficserver/url_sig.config
Verify that your configuration looks like the following, with actual key values altered:
key0 = YwG7iAxDo6Gaa38KJOceV4nsxiAJZ3DS key1 = nLE3SZKRgaNM9hLz_HnIvrCw_GtTUJT1 key2 = YicZbmr6KlxfxPTJ3p9vYhARdPQ9WJYZ key3 = DTV4Tcn046eM9BzJMeYrYpm3kbqOtBs7 key4 = C1r6R6MINoQd5YSH25fU66tuRhhz3fs_ key5 = l4dxe6YEpYbJtyiOmX5mafhwKImC5kej key6 = ekKNHXu9_oOC5eqIGJVxV0vI9FYvKVya key7 = BrjibTmpTTuhMHqphkQAuCWA0Zg97WQB key8 = rEtWLb1jcYoq9VG8Z8TKgX4GxBuro20J key9 = mrP_6ibDBG4iYpfDB6W8yn3ZyGmdwc6M key10 = tbzoTTGZXPLcvpswCQCYz1DAIZcAOGyX key11 = lWsn6gUeSEW79Fk2kwKVfzhVG87EXLna key12 = Riox0SmGtBWsrieLUHVWtpj18STM4MP1 key13 = kBsn332B7yG3HdcV7Tw51pkvHod7_84l key14 = hYI4GUoIlZRf0AyuXkT3QLvBMEoFxkma key15 = EIgJKwIR0LU9CUeTUdVtjMgGmxeCIbdg error_url = 403
Enable signature verification for a remap rule in Traffic Server by modifying
remap.config
(here we will just remap to Google’s homepage for demonstrative purposes):map http://test-remap.domain.com/download/foo http://google.com \ @plugin=url_sig.so @pparam=url_sig.config
Reload your Traffic Server configuration to ensure the changes are active:
traffic_ctl config reload
Attempt to access the now-protected URL without a valid signature. This will fail, and that is a good thing, as it demonstrates that Traffic Server now rejects any requests to paths matching that rule which do not include a valid signature.:
$ curl -vs -H'Host: test-remap.domain.com' http://localhost:8080/download/foo * Adding handle: conn: 0x200f8a0 * Adding handle: send: 0 * Adding handle: recv: 0 * Curl_addHandleToPipeline: length: 1 * - Conn 0 (0x200f8a0) send_pipe: 1, recv_pipe: 0 * About to connect() to localhost port 8080 (#0) * Trying 127.0.0.1... * Connected to localhost (127.0.0.1) port 8080 (#0) > GET /download/foo HTTP/1.1 > User-Agent: curl/7.32.0 > Accept: */* > Host: test-remap.domain.com > < HTTP/1.1 403 Forbidden < Date: Tue, 15 Apr 2014 22:57:32 GMT < Connection: close * Server ATS/5.0.0 is not blacklisted < Server: ATS/5.0.0 < Cache-Control: no-store < Content-Type: text/plain < Content-Language: en < Content-Length: 21 < * Closing connection 0 Authorization Denied$
Generate a signed URL using the included
sign.pl
script:sign.pl --url http://test-remap.domain.com/download/foo \ --useparts 1 --algorithm 1 --duration 60 --keyindex 3 \ --key DTV4Tcn046eM9BzJMeYrYpm3kbqOtBs7
Now access the protected URL with a valid signature:
$ curl -s -o /dev/null -v --max-redirs 0 -H 'Host: test-remap.domain.com' \ 'http://test-remap.domain.com/download/foo?E=1453848506&A=1&K=3&P=1&S=7aea86592de3e9c1b05771b2538a30956c6f10a3' * Adding handle: conn: 0xef0a90 * Adding handle: send: 0 * Adding handle: recv: 0 * Curl_addHandleToPipeline: length: 1 * - Conn 0 (0xef0a90) send_pipe: 1, recv_pipe: 0 * About to connect() to localhost port 8080 (#0) * Trying 127.0.0.1... * Connected to localhost (127.0.0.1) port 8080 (#0) > GET /download/foo?E=1397603088&A=1&K=3&P=1&S=28d822f68ac7265db61a8441e0877a98fe1007cc HTTP/1.1 > User-Agent: curl/7.32.0 > Accept: */* > Host: test-remap.domain.com > < HTTP/1.1 200 OK < Location: http://www.google.com/ < Content-Type: text/html; charset=UTF-8 < Date: Tue, 15 Apr 2014 23:04:36 GMT < Expires: Thu, 15 May 2014 23:04:36 GMT < Cache-Control: public, max-age=2592000 * Server ATS/5.0.0 is not blacklisted < Server: ATS/5.0.0 < Content-Length: 219 < X-XSS-Protection: 1; mode=block < X-Frame-Options: SAMEORIGIN < Alternate-Protocol: 80:quic < Age: 0 < Connection: keep-alive < { [data not shown] * Connection #0 to host localhost left intact