Adds correct support for TLS Muthual autentication and depth verification

modified:   controllers/nginx/configuration.md
	modified:   controllers/nginx/rootfs/etc/nginx/template/nginx.tmpl
	modified:   core/pkg/ingress/annotations/authtls/main.go
	modified:   core/pkg/ingress/controller/backend_ssl.go
	modified:   core/pkg/ingress/controller/controller.go
	modified:   core/pkg/ingress/controller/util_test.go
	modified:   core/pkg/ingress/resolver/main.go
	modified:   core/pkg/ingress/types.go
	modified:   core/pkg/net/ssl/ssl.go
	modified:   examples/PREREQUISITES.md
	new file:   examples/auth/client-certs/nginx/README.md
	new file:   examples/auth/client-certs/nginx/nginx-tls-auth.yaml

examples/auth/client-certs/nginx/README.md

@@ -0,0 +1,86 @@
+# TLS authentication 
+
+This example demonstrates how to enable the TLS Authentication through the nginx Ingress controller.
+
+## Terminology
+
+* CA: Certificate authority signing the client cert, in this example we will play the role of a CA. 
+You can generate a CA cert as show in this doc.
+
+* CA Certificate(s) - Certificate Authority public key. Client certs must chain back to this cert, 
+meaning the Issuer field of some certificate in the chain leading up to the client cert must contain 
+the name of this CA. For purposes of this example, this is a self signed certificate.
+
+* CA chains: A chain of certificates where the parent has a Subject field matching the Issuer field of 
+the child, except for the root, which has Issuer == Subject.
+
+* Client Cert: Certificate used by the clients to authenticate themselves with the loadbalancer/backends.
+
+
+## Prerequisites
+
+You need a valid CA File, composed of a group of valid enabled CAs. This MUST be in PEM Format.
+The instructions are described [here](../../../PREREQUISITES.md#ca-authentication)
+
+Also your ingress must be configured as a HTTPs/TLS Ingress.
+
+## Deployment
+
+Certificate Authentication is achieved through 2 annotations on the Ingress, as shown in the [example](nginx-tls-auth.yaml).
+
+|Name|Description|Values|
+| --- | --- | --- |
+|ingress.kubernetes.io/auth-tls-secret|Sets the secret that contains the authorized CA Chain|string|
+|ingress.kubernetes.io/auth-tls-verify-depth|The verification depth Certificate Authentication will make|number (default to 1)|
+
+
+The following command instructs the controller to enable TLS authentication using the secret from the ``ingress.kubernetes.io/auth-tls-secret``
+annotation on the Ingress. Clients must present this cert to the loadbalancer, or they will receive a HTTP 400 response
+
+```console
+$ kubectl create -f nginx-tls-auth.yaml
+```
+
+## Validation
+
+You can confirm that the Ingress works. 
+
+```console
+$ kubectl describe ing nginx-test
+Name:			nginx-test
+Namespace:		default
+Address:		104.198.183.6
+Default backend:	default-http-backend:80 (10.180.0.4:8080,10.240.0.2:8080)
+TLS:
+  tls-secret terminates ingress.test.com
+Rules:
+  Host	Path	Backends
+  ----	----	--------
+  *
+    	 	http-svc:80 (<none>)
+Annotations:
+  auth-tls-secret:	default/caingress
+  auth-tls-verify-depth: 3
+
+Events:
+  FirstSeen	LastSeen	Count	From				SubObjectPath	Type		Reason	Message
+  ---------	--------	-----	----				-------------	--------	------	-------
+  7s		7s		1	{nginx-ingress-controller }			Normal		CREATE	default/nginx-test
+  7s		7s		1	{nginx-ingress-controller }			Normal		UPDATE	default/nginx-test
+  7s		7s		1	{nginx-ingress-controller }			Normal		CREATE	ip: 104.198.183.6
+  7s		7s		1	{nginx-ingress-controller }			Warning		MAPPING	Ingress rule 'default/nginx-test' contains no path definition. Assuming /
+
+
+$ curl -k https://ingress.test.com
+HTTP/1.1 400 Bad Request
+Server: nginx/1.11.9
+
+$ curl -I -k --key ~/user.key --cert ~/user.cer https://ingress.test.com 
+HTTP/1.1 200 OK
+Server: nginx/1.11.9
+
+```
+
+You must use the full DNS name while testing, as NGINX relies on the Server Name (SNI) to select the correct Ingress to be used.
+
+The curl version used here was ``curl 7.47.0``

examples/auth/client-certs/nginx/nginx-tls-auth.yaml

@@ -0,0 +1,25 @@
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+  annotations:
+    # Create this with kubectl create secret generic caingress --from-file=ca.crt --namespace=default
+    ingress.kubernetes.io/auth-tls-secret: "default/caingress"
+    ingress.kubernetes.io/auth-tls-verify-depth: "3"
+    kubernetes.io/ingress.class: "nginx"
+  name: nginx-test 
+  namespace: default
+spec:
+  rules:
+  - host: ingress.test.com
+    http:
+      paths:
+      - backend:
+          serviceName: http-svc:80
+          servicePort: 80
+        path: /
+  tls:
+  - hosts:
+    - ingress.test.com
+    # Create this cert as described in 'multi-tls' example
+    secretName: cert
+