TACKpy version 0.9.6                                             Feb 23 2012
Trevor Perrin <tackpy at trevp.net>
============================================================================

Licenses/Acknowledgements
==========================
TACKpy is written (mostly) by Trevor Perrin. It includes crypto code from
Peter Pearson (ECDSA) and Bram Cohen (AES).

All code in TACKpy has been dedicated to the public domain by its authors. See
the LICENSE file for details.


Installation
=============
TACKpy requires Python 2.6 or greater, or Python 3.

Run "python setup.py install" or "make install".  This installs:
 - The "TACKpy" library for use by other Python programs (such as TLS Lite).
 - The "TACK.py" command for working with TACKs.

To use TACK.py without installation you can run "selfcontained/TACK.py".

If you have M2Crypto installed, TACKpy will use it for elliptic curve and AES
operations.


TACK.py quick start 
==================== 
You will need to create one or more TACK keys to "pin" your hostnames to. You
should use a different key for each hostname, unless those hostnames are
closely related (such as aliases for the same host, or hosts sharing a TLS
private key). Once you decide how many TACK keys you need, and the assignment
of hostnames to keys, do the following:

Create a TACK key:
  1) Run "TACK.py genkey > KEY.pem" (replace "KEY" with a specific name)
  2) Back up the key file where it won't be lost or stolen.

If a hostname is using TACK, each server at that hostname must have a TACK
that signs the public key in the server's certificate. To create and deploy
these TACKs, do the following:

Create a TACK for a certificate's public key:
  1) Run "TACK.py sign -k KEY.pem -c CERT > TACK.pem".

Deploy TACKs to a hostname 
  1) Deploy TACKs to each server at the hostname.
       - Apache: Set "SSLTackFile" to a TACK file.
  2) Once all servers are serving a TACK, activate pinning on each server.
       - Apache: Set "SSLTackPinActivation On".
  3) Test the site (if there are problems, see "Removing TACKs").
  4) Whenever you change a server's certificate, you must replace its TACK.


Removing TACKs
===============

Disabling pin activation
-------------------------
If you wish to stop using TACK for a hostname but can tolerate a "waiting
period" before the TACKs are removed, simply disable pin activation at all
servers for that hostname (Apache: "SSLTackPinActivation Off"). Then wait
for all existing client pins to become inactive.

The waiting period required is equal to the length of time that pin activation
has been enabled for any servers at the hostname, or a maximum of 30 days.
Once the waiting period is elapsed, all TACKs for the hostname can be safely
removed.

(For example: If you start using a TACK for "example.com", then decide to
disable pin activation after one day, you can remove the TACK at the end of
the second day.)

Break signatures
-----------------
If you wish to abruptly stop publishing a TACK for a hostname, or abruptly
change the hostname's TACK key, or signal that a TACK key has been
compromised, then you may publish a "break signature" from the TACK key as
part of the TLS connection.

This break signature must remain published at the hostname until all pins
between the hostname and the old TACK key have become inactive (30 days at
most; this is exactly the same as the "waiting period" described in previous
section).

A break signature from a TACK key causes any client who encounters it to
discard all pins involving the TACK key. Thus, once a break signature is
published for a TACK key, all existing pins and TACKS for the TACK key cease
providing security.

A server can have up to eight break signatures. However, keep in mind that
break signatures add to TLS handshake overhead, so are best avoided.

Create a break signature for a TACK:
  1) Run "TACK.py break -k KEY.pem > TACK_Break_Sig.pem"
  2) Add the break signature to your web server.


Advanced uses
==============

Revoking older generations of a TACK 
-------------------------------------
If a server's TLS public key (not its TACK key) has been compromised and you
are switching to a new TLS key, you may revoke the TACK for the old key by "-m
<min_generation>" in the "sign" command. <min_generation> is a number from
0-255 that is larger than the generation of the TACK you wish to revoke.

Clients who encounter the new TACK will reject older generations from then on.
Prior to publishing a new <min_generation> you should replace all your TACKs
with this generation number (or higher) by signing with "-g <generation>".

For example: By default TACK signatures have generation=0, so the first time
you use this capability you will want to set "-m1" after pushing out a new set
of TACKs signed with "-g1". If you use it a second time, you will set "-m2",
and so on.

Security Consideration: This only provides protection if clients receive the
new min_generation. For a more robust defense against SSL key compromise,
consider using short-lived TACKs.

Short-lived TACKs
------------------
Every TACK contains a signature covering a TLS public key. The TLS key is
contained in a certificate. By default the TACK signature is set to expire at
the same time as the certificate, and must be replaced by an updated TACK at
that point.

If you shorten the TACK's expiration time, then a compromised SSL certificate
will become unusable to an attacker once the TACK expires. For example, every
day at midnight you could deploy a new TACK that expires within 48 hours.

A good way to handle short-lived TACKs is to generate a batch of them and
store the TACKs on a secure system that distributes them to servers. This way,
you do not have to use your TACK key to sign new TACKs frequently.

You can generate a batch of TACKs with the "-n NUM@INTERVAL" argument to
"sign", specifying the number of TACKs and the interval between their
expiration times. The "-o" argument is taken as a filename prefix, and the
"-e" time is used as the first expiration time.  Example:

TACK.py sign -k KEY.pem -c CERT -n 365@1d -e 2013-01-02Z -o T1

produces 365 TACKs, one expiring at midnight (UTC) each day of 2013:
  T1_0000.pem
  T1_0001.pem
  T1_0002.pem
  ...
  T1_0364.pem