Add documentation for Holde-of-Key profile.

Thanks to Andreas Mayer for writing this documentation.

git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@3067 44740490-163a-0410-bde0-09ae8108e29a

docs/index.txt

@@ -15,12 +15,14 @@ SimpleSAMLphp Documentation
   * [Upgrading - migration to use the SAML authentication source](simplesamlphp-sp-migration)
   * [Configuring HTTP-Artifact](./simplesamlphp-artifact-sp)
   * [Using scoping](./simplesamlphp-scoping)
+  * [Holder-of-Key profile](simplesamlphp-hok-sp)
  * [Identity Provider QuickStart](simplesamlphp-idp)
   * [IdP hosted reference](simplesamlphp-reference-idp-hosted)
   * [SP remote reference](simplesamlphp-reference-sp-remote)
   * [Use case: Setting up an IdP for Google Apps](simplesamlphp-googleapps)
   * [Configuring HTTP-Artifact](./simplesamlphp-artifact-idp)
   * [Identity Provider Advanced Topics](simplesamlphp-idp-more)
+  * [Holder-of-Key profile](simplesamlphp-hok-idp)
  * [Automated Metadata Management](simplesamlphp-automated_metadata)
  * [Maintenance and configuration](simplesamlphp-maintenance) - covers session handling, php configuration etc.
  * [Authentication Processing Filters](simplesamlphp-authproc) - attribute filtering, attribute mapping, consent, group generation etc.

docs/simplesamlphp-hok-idp.txt

+Adding Holder-of-Key Web Browser SSO Profile support to the IdP
+===============================================================
+
+This document describes the necessary steps to enable support for the [SAML V2.0 Holder-of-Key (HoK) Web Browser SSO Profile](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-holder-of-key-browser-sso.pdf)
+on a simpleSAMLphp Identity Provider (IdP).
+
+The SAML V2.0 HoK Web Browser SSO Profile is an alternate version of the standard SAML Web Browser SSO Profile. Its primary benefit is the enhanced security of the SSO process
+while preserving maximum compatibility with existing deployments on client and server side.
+
+When using this profile the communication between the user and the IdP is required to be protected by the TLS protocol. Additionally, the user needs a TLS client certificate.
+This certificate is usually selfsigned and stored in the certificate store of the browser or the underlying operating system.
+
+Configuring Apache
+------------------
+
+The IdP requests a client certificate from the user agent during the TLS handshake. This behaviour is enabled with the following Apache webserver configuration:
+
+    SSLEngine on
+    SSLCertificateFile /etc/openssl/certs/server.crt
+    SSLCertificateKeyFile /etc/openssl/private/server.key
+    SSLVerifyClient optional_no_ca
+    SSLOptions +ExportCertData
+
+If the user agent can successfully prove possession of the private key associated to the public key from the certificate, the received certificate is stored in the
+environment variable `SSL_CLIENT_CERT` of the webserver. The IdP embeds the client certificate into the created HoK assertion.
+
+Enabling HoK SSO Profile on the IdP
+-----------------------------------
+
+To enable the IdP to send HoK assertions you must add the `saml20.hok.assertion` option to the `saml20-idp-hosted` metadata file:
+
+    $metadata['__DYNAMIC:1__'] = array(
+        [....]
+        'auth' => 'example-userpass',
+        'saml20.hok.assertion' => TRUE,
+    );
+
+Add new metadata to SPs
+-----------------------
+
+After enabling the Holder-of-Key Web Browser SSO Profile your IdP metadata will change. An additional HoK `SingleSignOnService` endpoint is added.
+You therefore need to update the metadata for your IdP at your SPs.
+The `saml20-idp-remote` metadata for simpleSAMLphp SPs should contain something like the following code:
+
+	'SingleSignOnService' => array (
+		array (
+			'hoksso:ProtocolBinding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
+			'Binding' => 'urn:oasis:names:tc:SAML:2.0:profiles:holder-of-key:SSO:browser',
+			'Location' => 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
+		),
+		array (
+			'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
+			'Location' => 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php',
+		),
+	),
+
+SP metadata on the IdP
+----------------------
+
+A SP using the HoK Web Browser SSO Profile must have an `AssertionConsumerService` endpoint supporting that profile.
+This means that you have to use the complex endpoint format in `saml20-sp-remote` metadata.
+In general, this should look like the following code:
+
+	'AssertionConsumerService' => array (
+		array(
+			'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
+			'Location' => 'https://sp.example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp',
+			'index' => 0,
+		),
+		array(
+			'Binding' => 'urn:oasis:names:tc:SAML:2.0:profiles:holder-of-key:SSO:browser',
+			'Location' => 'https://sp.example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp',
+			'index' => 4,
+		),
+	),
+
+(The specific values of the various fields will vary depending on the SP.)

docs/simplesamlphp-hok-sp.txt

+Using Holder-of-Key Web Browser SSO Profile on a simpleSAMLphp SP
+=================================================================
+
+This document describes how to enable the [SAML V2.0 Holder-of-Key (HoK) Web Browser SSO Profile](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-holder-of-key-browser-sso.pdf)
+on a simpleSAMLphp Service Provider (SP).
+
+The SAML V2.0 HoK Web Browser SSO Profile is an alternate version of the standard SAML Web Browser SSO Profile. Its primary benefit is the enhanced security of the SSO process
+while preserving maximum compatibility with existing deployments on client and server side.
+
+When using this profile the communication between the user and the SP is required to be protected by the TLS protocol. Additionally, the user needs a TLS client certificate.
+This certificate is usually selfsigned and stored in the certificate store of the browser or the underlying operating system.
+
+Configuring Apache
+------------------
+
+The SP requests a client certificate from the user agent during the TLS handshake. This behaviour is enabled with the following Apache webserver configuration:
+
+    SSLEngine on
+    SSLCertificateFile /etc/openssl/certs/server.crt
+    SSLCertificateKeyFile /etc/openssl/private/server.key
+    SSLVerifyClient optional_no_ca
+    SSLOptions +ExportCertData
+
+If the user agent can successfully prove possession of the private key associated to the public key from the certificate, the received certificate is stored in the
+environment variable `SSL_CLIENT_CERT` of the webserver.
+
+Enable HoK on SP
+----------------
+
+Which binding/profile the Identity Provider (IdP) should use when sending authentication responses to the SP is controlled by the `ProtocolBinding` option in the SP configuration.
+To make your SP request that the response from the IdP is send using the HoK SSO Profile, this option must be set accordingly:
+
+    'hok-sp' => array(
+        'saml:SP',
+		'ProtocolBinding' => 'urn:oasis:names:tc:SAML:2.0:profiles:holder-of-key:SSO:browser',
+    ),
+
+When this is done, you can add the metadata of your SP to the IdP and test the authentication.

docs/simplesamlphp-reference-idp-hosted.txt

@@ -202,8 +202,12 @@ The following SAML 2.0 options are available:
 
 :   Note that this requires a configured memcache server.
 
+`saml20.hok.assertion`
+:   Set to `TRUE` to enable the IdP to send responses according the [Holder-of-Key Web Browser SSO Profile](./simplesamlphp-hok-idp).
+    Defaults to `FALSE`.
+
 `saml20.sign.response`
-:   Whether `<samlp:Response> messages should be signed.
+:   Whether `<samlp:Response>` messages should be signed.
     Defaults to `TRUE`.
 
 :   Note that this option also exists in the SP-remote metadata, and
@@ -211,7 +215,7 @@ The following SAML 2.0 options are available:
     in the IdP metadata.
 
 `saml20.sign.assertion`
-:   Whether `<saml:Assertion> elements should be signed.
+:   Whether `<saml:Assertion>` elements should be signed.
     Defaults to `TRUE`.
 
 :   Note that this option also exists in the SP-remote metadata, and