TACKpy

.gitignore

@@ -1 +1,2 @@
 *.pyc
+.idea

LICENSE

@@ -1,10 +1,11 @@
 
-TACKpy includes code from different sources. All code is dedicated to the
+Tackpy includes code from different sources. All code is dedicated to the
 public domain by its authors. In particular:
 
 - 
 
-Code written by Trevor Perrin is available under the following terms:
+Code written by Trevor Perrin and Moxie Marlinspike is available under the
+following terms:
 
 This is free and unencumbered software released into the public domain.
 

Makefile

@@ -1,64 +1,53 @@
 
+TESTDIR = testoutput
+
 .PHONY : default
 default:
-	@echo To install TACKpy run \"./setup.py install\" or \"make install\"
-
-SCDIR := selfcontained
-
-# Variables for testing
-TESTDIR = testoutput
-EXEC = TACK.py
-CERT1 = ./testdata/serverX509Cert.pem
-CERT2 = ./testdata/serverX509Cert.der
+	@echo To install tackpy run \"./setup.py install\" or \"make install\"
+	@echo
 
 .PHONY: install
 install:
 	./setup.py install
 
+.PHONY: dist
+dist:
+	./setup.py sdist
+
 .PHONY : clean
 clean:
-	rm -f src/*.pyc
-	rm -rf $(SCDIR)
-	rm -rf $(TESTDIR)
+	rm -f `find . -name *.pyc`
 	rm -rf build
 	rm -rf dist
+	rm -rf $(TESTDIR)
 
-.PHONY: selfcontained
-selfcontained:
-	rm -rf $(SCDIR)
-	mkdir $(SCDIR)
-	./make_selfcontained.py > $(SCDIR)/TACK.py
-	chmod +x $(SCDIR)/TACK.py
-
-dist: selfcontained
-	./setup.py sdist
+# Variables for testing
+TESTDIR = testoutput
+EXEC = ./tack.py
+CERT1 = ./testdata/serverX509Cert.pem
+CERT2 = ./testdata/serverX509Cert.der
 
 .PHONY: test
 test:
 	rm -rf $(TESTDIR)
 	mkdir $(TESTDIR)
-	$(EXEC) test
-	# NOTE: USE 'asdf' for passwords...
-	$(EXEC) genkey > $(TESTDIR)/TACK_Key1.pem 
-	$(EXEC) genkey -p asdf > $(TESTDIR)/TACK_Key2.pem 
+	$(EXEC) genkey -p asdf > $(TESTDIR)/TACK_Key1.pem 
+	$(EXEC) genkey -x -p asdf > $(TESTDIR)/TACK_Key2.pem 
 	$(EXEC) genkey -p asdf -o $(TESTDIR)/TACK_Key3.pem 
-	$(EXEC) sign -k $(TESTDIR)/TACK_Key1.pem -c $(CERT1) > $(TESTDIR)/TACK1.pem	
-	$(EXEC) sign -k $(TESTDIR)/TACK_Key1.pem -p asdf -c $(CERT2) -o $(TESTDIR)/TACK2.pem		
-	$(EXEC) sign -k $(TESTDIR)/TACK_Key1.pem -p asdf -c $(CERT1) -m2 -o $(TESTDIR)/TACK3.pem			
-	$(EXEC) sign -k $(TESTDIR)/TACK_Key1.pem -p asdf -c $(CERT1) -o $(TESTDIR)/TACK4.pem			
-	$(EXEC) sign -k $(TESTDIR)/TACK_Key1.pem -p asdf -e 2030-06-06Z -c $(CERT1) -o $(TESTDIR)/TACK5.pem
-	$(EXEC) sign -k $(TESTDIR)/TACK_Key1.pem -p asdf -g2 -m2 -c $(CERT1) -o $(TESTDIR)/TACK6.pem
-	$(EXEC) sign -k $(TESTDIR)/TACK_Key1.pem -p asdf -m250 -g251 -c $(CERT1) -o $(TESTDIR)/T6 -e 2013-01-02Z -n 3@1d
-	$(EXEC) break -k $(TESTDIR)/TACK_Key1.pem -p asdf > $(TESTDIR)/TACK_Break_Sig1.pem
-	$(EXEC) b -k $(TESTDIR)/TACK_Key2.pem -p asdf -o $(TESTDIR)/TACK_Break_Sig2.pem
-	cat $(TESTDIR)/TACK_Break_Sig1.pem $(TESTDIR)/TACK_Break_Sig2.pem > $(TESTDIR)/TACK_Break_Sigs.pem
-	$(EXEC) tackcert -i $(TESTDIR)/TACK3.pem > $(TESTDIR)/TACK_Cert3.pem
-	$(EXEC) tackcert -i $(TESTDIR)/TACK4.pem -b $(TESTDIR)/TACK_Break_Sigs.pem > $(TESTDIR)/TACK_Cert4.pem
-	$(EXEC) tackcert -i $(TESTDIR)/TACK_Cert3.pem > $(TESTDIR)/TACK3_FromCert.pem
+	$(EXEC) sign $(TESTDIR)/TACK_Key1.pem -p asdf $(CERT1) > $(TESTDIR)/TACK1.pem	
+	cat $(TESTDIR)/TACK_Key1.pem | $(EXEC) sign - -p asdf $(CERT2) -o $(TESTDIR)/TACK2.pem		
+	$(EXEC) sign -x $(TESTDIR)/TACK_Key1.pem -p asdf $(CERT1) -m2 -o $(TESTDIR)/TACK3.pem			
+	$(EXEC) sign $(TESTDIR)/TACK_Key1.pem -p asdf $(CERT1) -o $(TESTDIR)/TACK4.pem			
+	$(EXEC) sign -x $(TESTDIR)/TACK_Key1.pem -p asdf -e 2030-06-06Z $(CERT2) -o $(TESTDIR)/TACK5.pem
+	cat $(CERT1) | $(EXEC) sign $(TESTDIR)/TACK_Key1.pem -p asdf -g2 -m2 - -o $(TESTDIR)/TACK6.pem
+	cat $(CERT2) | $(EXEC) sign $(TESTDIR)/TACK_Key1.pem -p asdf -m250 -g251 - -o $(TESTDIR)/T6 -e 2013-01-02Z -n 3@1d
+	$(EXEC) pack $(TESTDIR)/TACK3.pem > $(TESTDIR)/TACK_Ext3.pem
+	cat $(TESTDIR)/TACK3.pem $(TESTDIR)/TACK4.pem > $(TESTDIR)/TACK3_4.pem
+	$(EXEC) pack $(TESTDIR)/TACK3_4.pem > $(TESTDIR)/TACK_Ext3_4.pem
+	$(EXEC) unpack $(TESTDIR)/TACK_Ext3_4.pem -o $(TESTDIR)/TACK_Ext3_4_Unpack.txt
 	$(EXEC) view $(TESTDIR)/TACK_Key1.pem > $(TESTDIR)/TACK_View_Key1.txt
-	$(EXEC) view $(TESTDIR)/TACK1.pem > $(TESTDIR)/TACK_View1.txt
-	$(EXEC) v $(TESTDIR)/TACK_Break_Sigs.pem > $(TESTDIR)/TACK_View_Break_Sigs.txt
+	cat $(TESTDIR)/TACK1.pem | $(EXEC) view - > $(TESTDIR)/TACK_View1.txt
 	$(EXEC) v $(CERT1) > $(TESTDIR)/TACK_View_Cert1.txt
-	$(EXEC) v $(CERT2) > $(TESTDIR)/TACK_View_Cert2.txt
-	$(EXEC) v $(TESTDIR)/TACK_Cert3.pem > $(TESTDIR)/TACK_View_TACK_Cert3.txt 
+	cat $(CERT2) | $(EXEC) v - > $(TESTDIR)/TACK_View_Cert2.txt
+	$(EXEC) v $(TESTDIR)/TACK_Ext3.pem > $(TESTDIR)/TACK_View_TACK_Ext3.txt 
 	@echo OK

README

@@ -1,150 +1,142 @@
-TACKpy version 0.9.6                                             Feb 23 2012
-Trevor Perrin <tackpy at trevp.net>
+Tackpy version 0.9.9b                                            Sep 25 2012
 ============================================================================
 
 Licenses/Acknowledgements
 ==========================
-TACKpy is written (mostly) by Trevor Perrin. It includes crypto code from
-Peter Pearson (ECDSA) and Bram Cohen (AES).
+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
+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.
+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.
+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 TACK.py without installation you can run "selfcontained/TACK.py".
+To use the command-line tool without installation run "./tack.py".
 
-If you have M2Crypto installed, TACKpy will use it for elliptic curve and AES
-operations.
+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.
 
-TACK.py quick start 
-==================== 
+
+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.py genkey > KEY.pem" (replace "KEY" with a specific name)
+  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
+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.
+these tacks, do the following:
 
-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.)
+Create a tack for a certificate's public key:
+  1) Run "tack sign KEY.pem CERT > TACK.pem".
 
-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.
+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.
 
-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.
+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.
 
-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.
+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.
 
-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.
+(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 
+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
+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.
+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>".
+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 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.
+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 SSL key compromise,
-consider using short-lived TACKs.
+new min_generation. For a more robust defense against TLS key compromise,
+consider using short-lived tacks.
 
-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.
+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 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.
+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.
+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
+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
+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:
+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.