README

Tackpy version 0.9.9b                                            Sep 25 2012
============================================================================

Licenses/Acknowledgements
==========================
Tackpy is written by Trevor Perrin and Moxie Marlinspike. 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 "make install" or "python setup.py install".  This installs:
 - The "tack" library for use by other Python programs (such as TLS Lite).
 - The "tack" command-line tool.

To use the command-line tool without installation run "./tack.py".

OpenSSL
--------
Tackpy tries to use OpenSSL for AES and ECDSA operations. If OpenSSL cannot be
loaded, Tackpy will fall back to using slower python crypto code. 

To use OpenSSL on Windows you need "libeay32.dll" on your path. On Red Hat
systems you need to provide your own libcrypto as the system default does not
include elliptic curve support.


Quick start with command-line tool
=================================== 
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 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 sign KEY.pem CERT > TACK.pem".

Deploy tacks to a hostname 
  1) Deploy tacks to each server at the hostname.
       - Apache: Set "SSLTACKTackFile" to a tack file.
  2) Set the activation flag on each server.
       - Apache: Set "SSLTACKActivationFlags 1".
  3) Test the site (if there are problems, see "Pin deactivation").
  4) Whenever you change a server's certificate, you must replace its tack.


Pin deactivation
=================
If you wish to stop using TACK for a hostname, simply disable the activation
flag at all servers for that hostname (Apache: "SSLTACKActivationFlags 0").
Then wait for all existing client pins to become inactive.

The waiting period required is equal to the length of time that the activation
flag 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 the activation flag after one day, you can remove the tack at the end
of the second day.)


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

Revoking older generations of a tack 
-------------------------------------
If a server's TLS 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 generation tacks 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 tacks 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 TLS 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 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 TLS key 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 sign KEY.pem 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

TACK Key rollover
------------------
You may "rollover" a hostname from one TACK key to another without an
interruption in security by publishing two tacks simultaneously. This allows
clients to form pins based on the second tack prior to the first tack being
removed.

To perform a rollover, simply append the new tack to the SSLTACKTackFile, and
set the SSLTACKActivationFlags to 3 (1 activates the first tack, 2 activates
the second tack, and 3 activates both). Allow at least 30 days, then
deactivate the first tack by setting SSLTACKActivationFlags to 2. Allow at
least another 30 days, then delete the first tack and set
SSLTACKActivationFlags to 1. The rollover is now complete.