printout TB cache status; add PHP sample application to README.md

Signed-off-by: Hans Zandbelt <[email protected]>

ChangeLog

@@ -1,3 +1,7 @@
+09/26/2018
+- printout TB cache status
+- add PHP sample application to README.md
+
 09/13/2018
 - make SSL connection detection use ssl_prehand_shake callback, makeing the mod_ssl imported function obsolete
 - use tagged version of zmartzone/token_bind that supports OpenSSL 1.1.1 and exposes getNegotiatedVersion

README.md

@@ -22,6 +22,30 @@ Build and run this container on a Docker-equipped system with `./autogen.sh && .
 
 ## Application
 
+An application running on or behind the Apache server can leverage the environment variable or HTTP headers that `mod_token_binding` provides. The hard protocol security bits are dealt with by `mod_token_binding` and a trivial 2-step implementation process remains for the application itself. See below for a sample in PHP:
+
+- at session creation time: put the Token Binding ID provided in the environment variable set by mod_token_binding into the session state
+
+```
+$tokenBindingID = apache_getenv('Sec-Provided-Token-Binding-ID');
+if (isset($tokenBindingID)) {
+  $_SESSION['TokenBindingID'] = $tokenBindingID;
+}
+```
+
+- on subsequent requests: check the Token Binding ID stored in the session or token against the (current) Token Binding ID provided in an environment variable
+
+```
+if (array_key_exists('TokenBindingID', $_SESSION)) {
+  $tokenBindingID = apache_getenv('Sec-Provided-Token-Binding-ID');
+  if ($_SESSION['TokenBindingID'] != tokenBindingID) {
+    session_abort();
+  }
+}
+```
+
+**mod_auth_openidc**
+
 Since version 2.3.1 [mod_auth_openidc](https://github.com/zmartzone/mod_auth_openidc) can be configured to use the negotiated environment variables to bind its session (and state) cookie(s) to the TLS connection and to perform OpenID Connect Token Bound Authentication for an ID Token as defined in [http://openid.net/specs/openid-connect-token-bound-authentication-1_0.html](http://openid.net/specs/openid-connect-token-bound-authentication-1_0.html) using its `OIDCTokenBindingPolicy` directive as described in [https://github.com/zmartzone/mod_auth_openidc/blob/v2.3.5/auth_openidc.conf#L211](https://github.com/zmartzone/mod_auth_openidc/blob/v2.3.5/auth_openidc.conf#L211).
 
 ## Requirements

src/mod_token_binding.c

@@ -446,7 +446,7 @@ static int tb_post_read_request(request_rec *r) {
 	if (tbCacheMessageAlreadyVerified(cfg->cache, (uint8_t*) message,
 			message_len, &out_tokbind_id, &out_tokbind_id_len,
 			&referred_tokbind_id, &referred_tokbind_id_len)) {
-		tb_debug(r, "tbCacheMessageAlreadyVerified returned true");
+		tb_debug(r, "tbCacheMessageAlreadyVerified returned true (status=%s", tbCacheGetStatusString(tbCacheGetStatus(cfg->cache)));
 		tb_draft_ietf_tokbind_ttrp(r, cfg, out_tokbind_id, out_tokbind_id_len,
 				referred_tokbind_id, referred_tokbind_id_len);
 		tb_draft_campbell_tokbind_tls_term(r, cfg, conn_cfg->ssl,
@@ -455,6 +455,8 @@ static int tb_post_read_request(request_rec *r) {
 		return DECLINED;
 	}
 
+	tb_debug(r, "tbCacheMessageAlreadyVerified returned false (status=%s", tbCacheGetStatusString(tbCacheGetStatus(cfg->cache)));
+
 	if (!tbCacheVerifyTokenBindingMessage(cfg->cache, (uint8_t*) message,
 			message_len, conn_cfg->tls_key_type, ekm, &out_tokbind_id,
 			&out_tokbind_id_len, &referred_tokbind_id,