--- title: HTTP Public Key Pinning (HPKP) slug: Web/HTTP/Public_Key_Pinning tags: - Anleitung - HPKP - HTTP - Sicherheit - Webentwicklung translation_of: Web/HTTP/Public_Key_Pinning original_slug: Web/Security/Public_Key_Pinning ---
{{HTTPSidebar}}

Die Public Key Pinning Erweiterung für HTTP ({{Glossary("HPKP")}}) ist ein Sicherheitsfeature, das einem Webclient mitteilt, einen spezifischen kryptographischen Schlüssel mit einem bestimmten Webserver in Verbindung zu bringen um {{Glossary("MITM")}} mit gefälschten Zertifikaten zu vermeiden.

Um die Echtheit des öffentlichen Schlüssels eines Servers in {{Glossary("TLS")}}-Sessions sicherzustellen, wird dieser in ein X.509-Zertifikat gepackt, welches meistens von einer Zertifizierungsstelle ({{GLossary("CA")}}) signiert wird. Webclients wie Browser vertrauen vielen Zertifizierungsstellen, die Zertifikate für beliebige Domainnamen erstellen können. Wenn ein Angreifer dazu in der Lage ist, eine einzelne Zertifizierungsstelle zu infiltrieren, kann er MITM-Angriffe auf verschiedene TLS-Verbindungen starten. HPKP kann diese Gefahr für das {{Glossary("HTTPS")}}-Protokoll dadurch umgehen, dass dem Client mitgeteilt wird, welcher öffentliche Schlüssel zu einem bestimmten Webserver gehört.

HPKP is ein Trust on First Use ({{Glossary("TOFU")}}) ("Bei der ersten Benutzung vertrauen") Verfahren. Beim ersten Webseitenbesuch übermittelt der Server einen HTTP-Header um dem Client zu zeigen, welche öffentliche Schlüssel zu ihm gehören. Der Client speichert diese Information für eine angegebene Zeit. Wenn der Client die Webseite erneut besucht, erwartet er, dass mindestens ein Zertifikat der Zertifikatkette einen öffentlichen Schlüssel enthält, dessen Fingerprint dem Client bereits per HPKP bekannt ist. Wenn der Server einen unbekannten öffentlichen Schlüssel liefert, sollte der Client einen Fehler anzeigen.

Firefox (und Chrome) deaktivieren die Pin Validierung für Pinned Hosts mit Zertifikatketten, die bei einem benutzerdefinierten trust anchor terminieren (anstatt bei einem eingebauten trust anchor). Dies bedeutet, dass alle Pinning-Nichteinhaltungen für Nutzer ignoriert werden, welche ein Root-Zertifikat importiert haben.

HPKP aktivieren

Dieses Feature kann einfach aktiviert werden indem ein {{HTTPHeader("Public-Key-Pins")}} HTTP-Header beim Aufruf der Seite über HTTPS zurückgegeben wird:

Public-Key-Pins: pin-sha256="base64=="; max-age=expireTime [; includeSubdomains][; report-uri="reportURI"]
pin-sha256
Der Parameter beinhaltet einen Base64 codierten Subject Public Key Information ({{Glossary("SPKI")}}) Fingerprint. Es ist auch möglich mehrere Pins zu verschiedenen öffentlichen Schlüsseln zu definieren. Einige Browser werden hier zukünftig neben SHA-256 evtl. weitere Hash-Algorithmen erlauben. Weiter unten ist beschrieben, wie diese Informationen entweder aus dem Zertifikat oder der Schlüsseldatei extrahiert werden können.
max-age
Die Zeit (in Sekunden) in Sekunden, die ein Browser sich merken soll, dass auf diese Seite nur bei Benutzung eines der öffentlichen Schlüssel zugegriffen werden darf.
includeSubdomains {{ optional_inline() }}
Wenn dieser optionale Parameter angegeben wird, wird die Regel auch auf alle Subdomains der Site angewandt.
report-uri {{ optional_inline() }}
Wenn dieser optionale Parameter angegeben wird, werden Pinvalidierungsfehlschläge an die angegebene URL gemeldet.

Anmerkung: Die aktuelle Spezifikation verlangt die Aufnahme eines zweiten Pins für einen Backup-Schlüssel, der noch nicht in der Produktion verwendet wird. Dies ermöglicht es, den öffentlichen Schlüssel des Servers zu ändern, ohne die Zugänglichkeit für Clients zu beeinträchtigen, die die Pins bereits bemerkt haben. Dies ist z.B. dann wichtig, wenn der alte Schlüssel beschädigt wird.

Base64-enkodierte Public Key Informationen extrahieren

Note: Während das folgende Beispiel zeigt, wie man einen Pin auf ein Serverzertifikat setzt, wird empfohlen, den Pin auf das Zwischenzertifikat der CA zu setzen, die das Serverzertifikat ausgestellt hat, um Verlängerungen und Rotationen von Zertifikaten zu erleichtern.

First you need to extract the public key information from your certificate or key file and encode them using Base64.

The following commands will help you extract the Base64 encoded information from a key file, a certificate signing request, or a certificate.

openssl rsa -in my-key-file.key -outform der -pubout | openssl dgst -sha256 -binary | openssl enc -base64
openssl req -in my-signing-request.csr -pubkey -noout | openssl rsa -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64
openssl x509 -in my-certificate.crt -pubkey -noout | openssl rsa -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

The following command will extract the Base64 encoded information for a website.

openssl s_client -connect www.example.com:443 | openssl x509 -pubkey -noout | openssl rsa -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

Beispiel für ein HPKP-Header

Public-Key-Pins: pin-sha256="cUPcTAZWKaASuYWhhneDttWpY3oBAkE3h2+soZS7sWs="; pin-sha256="M8HztCzM3elUxkcjR2S5P4hhyBNf6lHkmjAHKhpGPWE="; max-age=5184000; includeSubdomains; report-uri="https://www.example.net/hpkp-report"

In this example, pin-sha256="cUPcTAZWKaASuYWhhneDttWpY3oBAkE3h2+soZS7sWs=" pins the server's public key used in production. The second pin declaration pin-sha256="M8HztCzM3elUxkcjR2S5P4hhyBNf6lHkmjAHKhpGPWE=" also pins the backup key. max-age=5184000 tells the client to store this information for two month, which is a reasonable time limit according to the IETF RFC. This key pinning is also valid for all subdomains, which is told by the includeSubdomains declaration. Finally, report-uri="https://www.example.net/hpkp-report" explains where to report pin validation failures.

Setting up your webserver to include the HPKP header

The concrete steps necessary to deliver the HPKP header depend on the web server you use.

Note: These examples use a max-age of two months and include all subdomains. It is advised to verify that this setup will work for your server.

HPKP hat das Potential Nutzer für eine lange Zeit auszusperren, wenn es inkorrekt genutzt wird! Die Benutzung von Backup-Zertifikaten und/oder das Pinnen der Zertifizierungsstelle wird dringend empfohlen.

Apache

HPKP kann im Apache Webserver beispielsweise mit der folgenden Konfiguration aktiviert werden. Die Parameter müssen dann nur noch auf das Zielsystem angepasst werden. Das Apache Modul mod_headers wird benötigt.

Header always set Public-Key-Pins "pin-sha256=\"base64+primary==\"; pin-sha256=\"base64+backup==\"; max-age=5184000; includeSubDomains"

Nginx

Adding the following line and inserting the appropriate pin-sha256="..." values will enable HPKP on your nginx. This requires the ngx_http_headers_module.

add_header Public-Key-Pins 'pin-sha256="base64+primary=="; pin-sha256="base64+backup=="; max-age=5184000; includeSubDomains';

Lighttpd

The following line with your relevant key information (pin-sha256="..." fields) will enable HPKP on lighttpd.

setenv.add-response-header  = ( "Public-Key-Pins" => "pin-sha256=\"base64+primary==\"; pin-sha256=\"base64+backup==\"; max-age=5184000; includeSubDomains")

Note: This requires the mod_setenv server.module loaded which can be included by the following if not already loaded.

server.modules += ( "mod_setenv" )

IIS

Add the following line to the Web.config file to send the Public-Key-Pins header:

<system.webServer>
  ...

  <httpProtocol>
    <customHeaders>
      <add name="Public-Key-Pins" value="pin-sha256=&quot;base64+primary==&quot;; pin-sha256=&quot;base64+backup==&quot;; max-age=5184000; includeSubDomains" />
    </customHeaders>
  </httpProtocol>

  ...
</system.webServer>

Browserkompatibilität

{{Compat("http.headers.Public-Key-Pins")}}

Spezifikationen

Spezifikation Titel
{{RFC("7469", "Public-Key-Pins", "2.1")}} Public Key Pinning Erweiterung für HTTP

Siehe auch