HTTP Public Key Pinning (HPKP), added new theory section and updated Apache-Config.
authorGunnar Haslinger <gh.github@hitco.at>
Fri, 16 Oct 2015 21:35:25 +0000 (23:35 +0200)
committerGunnar Haslinger <gh.github@hitco.at>
Fri, 16 Oct 2015 21:35:25 +0000 (23:35 +0200)
src/acknowledgements.tex
src/configuration/Webservers/Apache/default-ssl
src/practical_settings/webserver.tex
src/theory/TLS.tex
src/theory/tls/HPKP.tex [new file with mode: 0644]
src/theory/tls/HSTS.tex

index a52379c..56a9aa2 100644 (file)
@@ -11,6 +11,7 @@ Dirksen-Thedens, Mathis \\
 Dulaunoy, Alexandre \\
 G├╝hring Philipp  \\
 Grigg, Ian  \\
+Haslinger, Gunnar \\
 Horenbeck, Maarten \\
 Huebl, Axel \\
 Kovacic, Daniel \\
index 9ada2e0..2475f22 100644 (file)
        SSLProtocol All -SSLv2 -SSLv3
        SSLHonorCipherOrder On
        SSLCompression off
+
        # Add six earth month HSTS header for all users...
        Header always set Strict-Transport-Security "max-age=15768000"
        # If you want to protect all subdomains, use the following header
        # ALL subdomains HAVE TO support HTTPS if you use this!
        # Strict-Transport-Security: "max-age=15768000 ; includeSubDomains"
+
+       # HTTP Public Key Pinning (HPKP) for 90 days (60*60*24*90=7776000)
+       # At least use one Backup-Key and/or add whole CA, think of Cert-Updates!
+       Header always set Public-Key-Pins "pin-sha256=\"YOUR_HASH=\"; pin-sha256=\"YOUR_BACKUP_HASH=\"; max-age=7776000; report-uri=\"https://YOUR.REPORT.URL\""
+
        SSLCipherSuite 'EDH+CAMELLIA:EDH+aRSA:EECDH+aRSA+AESGCM:EECDH+aRSA+SHA384:EECDH+aRSA+SHA256:EECDH:+CAMELLIA256:+AES256:+CAMELLIA128:+AES128:+SSLv3:!aNULL:!eNULL:!LOW:!3DES:!MD5:!EXP:!PSK:!DSS:!RC4:!SEED:!ECDSA:CAMELLIA256-SHA:AES256-SHA:CAMELLIA128-SHA:AES128-SHA'
 
+       
+       
 </VirtualHost>
 </IfModule>
index 4a17d43..0c7ac80 100644 (file)
@@ -9,13 +9,14 @@ synonyms~\footnote{https://www.mail-archive.com/openssl-dev@openssl.org/msg33405
 \begin{itemize*}
   \item Apache 2.2.22, Debian Wheezy with OpenSSL 1.0.1e
   \item Apache 2.4.6, Debian Jessie with OpenSSL 1.0.1e
+       \item Apache 2.4.10, Debian Jessie 8.2 with OpenSSL 1.0.1k
   \item Apache 2.4.7, Ubuntu 14.04.2 Trusty with Openssl 1.0.1f
 \end{itemize*}
 
 \subsubsection{Settings}
 Enabled modules \emph{SSL} and \emph{Headers} are required.
 
-\configfile{default-ssl}{42-43,52-52,62-62,162-170}{SSL configuration for an Apache vhost}
+\configfile{default-ssl}{42-43,52-52,62-62,162-177}{SSL configuration for an Apache vhost}
 
 \subsubsection{Additional settings}
 You might want to redirect everything to \emph{https://} if possible. In Apache
index 90389a1..03745ed 100644 (file)
@@ -2,8 +2,12 @@
 \label{section:TLS}
 \todo{Add a short intro}
 
-\subsection{HTTP Strict Transport Security}
+\subsection{HTTP Strict Transport Security (HSTS)}
 \label{subsection:HSTS}
 \input{"./theory/tls/HSTS.tex"}
 
+\subsection{HTTP Public Key Pinning (HPKP)}
+\label{subsection:HPKP}
+\input{"./theory/tls/HPKP.tex"}
+
 %\subsection{Server Name Indication}
\ No newline at end of file
diff --git a/src/theory/tls/HPKP.tex b/src/theory/tls/HPKP.tex
new file mode 100644 (file)
index 0000000..2cca922
--- /dev/null
@@ -0,0 +1,91 @@
+%\subsection{HTTP Public Key Pinning (HPKP)}
+Much like HTTP Strict Transport Security (HSTS), HTTP Public Key Pinning (HPKP) is a Trust On First Use (TOFU) mechanism. It protects HTTPS websites from impersonation using certificates issued by compromised certificate authorities. The data for Pinning is supplied by an HTTP-Header sent by the WebServer. 
+
+\subsubsection{HPKP Header Directives}
+\label{subsubsection:HPKP Header Directives}
+HPKP provides two different types of headers:
+\begin{itemize*}
+  \item Public-Key-Pins
+       \item Public-Key-Pins-Report-Only
+\end{itemize*}
+HPKP header can be parametrized by following directives:
+\begin{itemize*}
+  \item pin-sha256="<YOUR\_PUBLICKEY\_HASH=>"
+  \item max-age=<number-of-seconds> 
+       \item includeSubdomains 
+       \item report-uri="<https://YOUR.URL/TO-REPORT>"
+\end{itemize*}
+
+\textbf{pin-sha256} is a required directive. It can and should be used several (at least two) times for specifying the public keys of your domain-certificates or CA-certificates. Operators can pin any one or more of the public keys in the certificate-chain, and indeed must pin to issuers not in the chain (as, for example, a Backup Pin). Pinning to an intermediate issuer, or even to a trust anchor or root, still significantly reduces the number of issuers who can issue end-entity certificates for the Known Pinned Host, while still giving that host flexibility to change keys without a disruption of service. OpenSSL can be used to convert the Public Key of an X509-Certificate as follows:
+\begin{lstlisting}
+openssl x509 -in <certificate.cer> -pubkey -noout | 
+ openssl rsa -pubin -outform der | 
+ openssl dgst -sha256 -binary | 
+ openssl enc -base64
+writing RSA key
+pG3WsstDsfMkRdF3hBClXRKYxxKUJIOu8DwabG8MFrU=
+\end{lstlisting} 
+This piped usage of OpenSSL first gets the Public-Key of <certificate.cer>, converts it do DER (binary) format, calculates an SHA256 Hash and finally encodes it Base64. The output (including the ending Equal-Sign) is exactly whats needed for the \emph{pin-sha256="<YOUR\_PUBLICKEY\_HASH=>"} parameter. To generate the Hash for a prepared Backup-Key just create a Certificate-Signing-Request and replace "\texttt{openssl x509}" by "\texttt{openssl req -in <backup-cert.csr> -pubkey -noout}" as first OpenSSL command.\\ 
+Instead of using OpenSSL even WebServices like \url{https://report-uri.io/home/pkp_hash/} can be used to get a suggestion for the possible Public-Key-Hashes for a given WebSite.
+
+\textbf{max-age} is a required directive (when using the \emph{Public-Key-Pins} header). This directive specifies the number of seconds during which the user agent should regard the host (from whom the message was received) as a Known Pinned Host.
+
+\textbf{includeSubdomains} is an optional directive. This directive indicates that the same pinning applies to this Host as well as \emph{any subdomains of the host's domain name}. Be careful - you need to use a Multi-Domain/Wildcard-Certificate or use the same Pub/Private-Keypair in all Subdomain-Certificates or need to pin to CA-Certificates signing all your Subdomain-Certificates.
+
+\textbf{report-uri} is an optional directive. The presence of a report-uri directive indicates to the Browser that in the event of Pin Validation failure it should post a report to the report-uri (HTTP-Post is done using JSON, Syntax see {RFC-7469 Section 3}\footnote{\url{https://tools.ietf.org/html/rfc7469\#section-3}}). There are WebServices like \url{https://report-uri.io/} out there which can be used to easily collect and visualize these reports.
+
+\subsubsection{HPKP Client Support}
+\label{subsubsection:HPKP Client Support}
+HPKP is supported\footnote{\url{http://caniuse.com/\#feat=publickeypinning}} by these web browsers:
+\begin{itemize*}
+  \item Firefox version >= 35
+       \item Chrome version >= 38
+       \item Android Browser >= 44
+       \item Opera version >= 25 
+\end{itemize*}
+Currently (16. Oct 2015) there is no HPKP Support in: Apple Safari, Microsoft Internet Explorer and Edge.
+
+\subsubsection{HPKP Considerations}
+\label{subsubsection:HPKP Considerations}
+Before enabling HPKP it is recommended to consider following:
+\begin{itemize*}
+  \item Which Public-Keys to use for Pinning (Certificat + Backup-Certificate, CAs, Intermediate-CAs)
+       \item Proper value of \emph{max-age}. Start testing with a short Period, increase Period after deployment.
+       \item Be careful when using \emph{includeSubdomains}, are all your subdomains covered by the defined Public-Key-Hashes?
+\end{itemize*}
+
+The administrators are advised to watch for expiration of the SSL certificate and handle the renewal process with caution. If a SSL certificate is renewed without keeping the Public-Key (reusing the CSR) for an HPKP enabled domain name, the connection to site will break (without providing override mechanism to the end user).  
+
+\subsubsection{Testing HPKP}
+\label{subsubsection:Testing HPKP}
+HSTS can be tested either using locally or through the Internet. 
+
+There is a handy Bash-Script which uses OpenSSL for doing several SSL/TLS-Tests available at \url{https://testssl.sh/}
+\begin{lstlisting}
+wget -q https://testssl.sh/testssl.sh
+wget -q https://testssl.sh/mapping-rfc.txt
+chmod 755 ./testssl.sh
+./testssl.sh https://your-domain.com
+
+# Sample Output, just HSTS and HPKP Section (Full report is quite long!):
+Strict Transport Security    182 days=15724800 s, includeSubDomains
+Public Key Pinning # of keys: 2, 90 days=7776000 s, just this domain
+           matching host key: pG3WsstDsfMkRdF3hBClXRKYxxKUJIOu8DwabG8MFrU
+\end{lstlisting}
+
+For local testing it is possible to utilize Google Chrome Web browser, just open the Chrome net-internals-URL: \url{chrome://net-internals/#hsts}.
+
+For Mozilla Firefox there is an Plug-In provided by the "Secure Information Technology Center Austria" available: \url{https://demo.a-sit.at/firefox-plugin-highlighting-safety-information/}
+
+Testing over the Internet can be conducted by Qualys SSL Labs test \url{https://www.ssllabs.com/ssltest/}. \emph{Public Key Pinning (HPKP)} information is located in the \emph{Protocol Details} section. 
+
+There is also a fast online HPKP-only check at \url{https://report-uri.io/home/pkp_analyse}.
+
+\subsubsection{References}
+\begin{itemize*}
+       \item OWASP: Certificate and Public Key Pinning: \url{https://www.owasp.org/index.php/Certificate_and_Public_Key_Pinning}
+       \item HPKP Browser Compatibility List: \url{http://caniuse.com/\#feat=publickeypinning}
+  \item RFC 7469:Public Key Pinning Extension for HTTP - Examples: \url{https://tools.ietf.org/html/rfc7469\#section-2.1.5}
+\end{itemize*}
+
+
index 2eddb3e..ed09dfc 100644 (file)
@@ -33,8 +33,9 @@ HSTS is supported\footnote{\url{http://caniuse.com/stricttransportsecurity}} by
        \item Opera version >= 12.0 
        \item Opera mobile >= 16.0
        \item Safari >= 7.0
+       \item Microsoft Internet Explorer >= 11 (with update provided 09. June 2015)
+       \item Microsoft Edge >= 12
 \end{itemize*}
-Microsoft should add HSTS support in Internet Explorer 12\footnote{\url{http://status.modern.ie/httpstricttransportsecurityhsts}}.
 
 \subsubsection{HSTS Considerations}
 \label{subsubsection:HSTS Considerations}