Helper for web sites to request client certificates
If a web sites requires additional user authentication to sign a transaction an ActiveX control or a browser plugin can be used to access the certificate store of the user.
But ActiveX controls and Java Plugins are no more supported by modern browsers and the Web Cryptography API does not allow to access user certificate stores.
The only solution is to request user certificates via a separate TLS session. The Application Gateway can help to make this easier.
Overview of the message flow:
1) If a user wants to sign a transaction the web server responds with a web page with a hidden form that redirects to the Application Gateway.
-- Here is an example for this form.
-- The form fields challenge and hashalg are required, the form field responsepath is optional.
2) The routing entry at the Application Gateway is a web site with keywords SIGNRQ, SSL, CCR, CCNRQ, SSLCC and ADDH or AUTOH (optional, see below).
-- The Application Gateway requests a client certificate.
-- If the client certificate is valid it signs the challenge and the client certificate (keyword SSLCC is used to specify the signing certificate) and
-- returns the signature, the certificates etc. The response can be configured. For example it can be be a hidden form that redirects to the web server via http(s) POST
-- Here is the default response of the Application Gateway.
3) The web server has to validate the received POST message using a method that is provided (implemented in C#)
-- See the method here.
Notes on certificate caching:
Web browsers cache the selection of certificates or even if no certificate has been selected.
Therefore the user will not be asked when a request will be retried.
The solution is to use a different name DNS (server) name of the Application Gateway, the IP address and IP port can be the same.
In case the user does not select a certificate or the certificate is invalid the returned signature and user certificate is empty.
The web sever can retry the request using a different name of the Application Gateway so that the web browser prompts the user to select a certificate.
For hints on user certificate selection and configuration of the trusted issuers list see keyword example.
Keyword SIGNRQ:respOk|respErr
This keyword activates this helper function and it is valid only for web routing entries.
Any POST requests are expected to have the format as defined in this example. The form fields challenge and hashalg are required, the form field responsepath is optional.
The parameters respOk and respErr (response in case of an error) are optional and are names of (.htm) files (templates) to construct the response.
Templates for responses are selected as follows:
- First priority: Files specified as SIGNRQ parameters are used. If full paths are not specified: The default directory is used (where the Application is running).
- Second priority: Files specified in the client request are used. Paths specified in keyword DIR are considered (see web definition).
- In case of error and if the name of the file is derived from the client request: The file name ist extened with the string "_err". e.g. resp.htm -> resp_err.htm
- If no file is specified or the file could not be found: builtin defaults are used.
Remark for response template in case of success:
- The strings %responsepath%, %challenge%, %hashalg%, %signature%, %usercert% and %appgwcert% are replaced by the actual values.
Remark for response template in case of error:
- The strings %responsepath%, %challenge%, %hashalg% and %errmsg% are replaced by the actual values.
Notes when using Ajax (XMLHttpRequest) to access the Application Gateway at SIGNRQ entries:
Be aware of the Cross-Origin Resource Sharing (CORS) mechanism as decribed e.g. here.
The Access-Control-Allow-Origin http header at the SIGNRQ entry must be specified. For explict definition use the keyword ADDH, e.g.
ADDH:"Access-Control-Allow-Origin: https://myserver.x.com"
Additionally some browsers (e.g. Firefox, IE11) need the withCredentials attribute to be set in order to respond to certificate requests from the server:
Example:...
myAjax = new XMLHttpRequest();
...
myAjax.open("POST",url,true);
myAjax.withCredentials = true;
myAjax.send(postdata);
...
Now the HTTP header Access-Control-Allow-Credentials must be returned in the response. See the definition.
At the end the keyword ADDH with two parameters is needed, see example:
ADDH:"Access-Control-Allow-Origin: origin|Access-Control-Allow-Credentials: true"
As an alternative the keyword AUTOH can be used (works in combination with keyword SIGNRQ only):
This keyword returns following two HTTP headers:
Access-Control-Allow-Origin: origin
Access-Control-Allow-Credentials: true
where origin is copied from the HTTP request.
Note on Internet Explorer 9, 10 and 11:
In order to allow the user to select a client certificate using XMLHttpRequest: Internet Explorer needs some registry settings as defined in KB2894776.
Here you can find an example with Ajax.
Keyword SIGNRESP:
This keyword is valid only for web routing entries and used for testing the SIGNRQ functionality with the Application Gateway
Any POST requests are expected to to transmit fields as defined in this example.
Following keywords define arguments of CheckSignResponse for testing in combination with keyword SIGNRESP:
ISSA:appgwcertIssuer, ROOA:appgwcertRoot, RVMA:appgwcertRevocationMode
ISSU:usercertIssuer, ROOU:usercertRoot, RVMU:usercertRevocationMode
