Open Interfaces for e-Government

The Austrian Citizen Card

Security Layer Transport Protocols

Document information

Table of contents

1. General information
   1. Naming conventions
   2. Keywords
2. TCP/IP binding
   1. Identifier, parameters and default address
   2. Procedure
   3. Encoding
3. HTTP binding
   1. Identifier, parameters and default address
   2. Procedure
   3. encoding
4. SSL/TLS binding
   1. Identifier, parameters and default address
   2. Procedure
   3. Encoding
5. HTTPS binding
   1. Identifier, parameters and default address
   2. Procedure
   3. Encoding
6. References
7. History

1 General information

The Security Layer application interface document defines the XML commands that allow an application to use the Citizen Card function by means of the Security Layer interface. This document describes how these XML commands can be integrated in certain transport protocols. The following schematic diagram shows the principles underlying the Citizen Card Environment structure. The XML commands are bound to transport protocols by means of different modules, for example to TCP/IP and HTTP in the diagram. The modules provide the necessary implementation and encoding – the functional modules of the Citizen Card Environment only operate with the defined XML commands and are unaware of transport and of the properties of the protocol used.

The address of a binding is determined by the Internet socket used. The socket address consists of two components: IP address and port number. A default IP address (or DNS name) and a default port number are specified for every binding of a local Citizen Card Environment.

If a distinction can be made between bindings on the basis of the type of data transmitted, it is possible for bindings to use the same port. In particular, it is pointed out that the TCP/IP binding and the HTTP binding must be able to share an address, just like the TLS and HTTPS binding (this requirement arises from the default values for the ports). The Internet Assigned Numbers Authority (IANA) has reserved two ports [port numbers] for bindings of the Security Layer (see default values in sections 2.1, 3.1, 4.1 and 5.1).

1.1 Naming conventions

For better readability, this document dispenses with non-gender-specific formulations. However, the formulations expressly relate to both sexes.

The following name space prefixes are used in this specification to identify the name spaces of XML elements:

1.2 Keywords

This document uses the following keywords to categorise requirements: must, must not, required, should, should not, recommended, may, and optional. The interpretation of these keywords is set down in [Keywords].

2 TCP/IP binding

The TCP/IP binding is a 1:1 implementation of the Security Layer commands. A typical TCP/IP connection is used by means of a socket. The XML commands according to the Security Layer application interface are transmitted without further encoding or implementation/embedding in the connection.

2.1 Identifier, parameters and default address

The identifier and parameters of a binding are used in the GetProperties command of the Security Layer. The identifier for this binding is TCP/IP and has no parameters.

The default IP address of the TCP/IP binding for local Citizen Card Environments is 127.0.0.1, while the default port is 3495.

2.2 Procedure

1. The Citizen Card Environment opens the service at the defined address and waits for incoming connections.
2. The application opens up a connection to the service address.
3. The application transmits the XML request.
4. The Citizen Card Environment processes the XML request and sends an XML response.
5. The Citizen Card Environment closes the connection.

2.3 Encoding

There is no more embedding encoding. XML commands are transmitted to the TCP/IP connection on a 1:1 basis.

3 HTTP binding

The HTTP binding allows the application to access the Citizen Card functions directly by means of the citizen's web browser without requiring other active components (such as an applet). This requires that the XML request should be embedded in an HTTP request.

3.1 Identifier and parameter

The identifier and parameters of the binding are used in the GetProperties command of the Security Layer. The identifier for this binding is HTTP and has no parameters.

The default IP address of the HTTP binding for local Citizen Card Environments is 127.0.0.1, while the default port is 3495.

3.2 Procedure

3.2.1 General information

3.2.1.1 Terminology

The application transmits an HTML form (cf. [HTML 4], section 17.13), containing a series of form elements to the Citizen Card Environment in the HTTP binding. In the next sections, the form elements are divided into the following categories:

Form parameters

Form parameters are form elements that are specified to control procedures in the Citizen Card Environment. The names of these elements are XMLRequest, RedirectURL, DataURL and StylesheetURL. For detailed information see section 3.2.2.

Forwarding parameters

Forwarding parameters are form elements that are forwarded from the Citizen Card Environment to the server identified with DataURL as form elements when the DataURL form parameter is used. A form element becomes a forwarding parameter when its name ends with _ (underscore). See also section 3.3.2.2.

Forwarding headers

Forwarding headers are form elements that are forwarded from the Citizen Card Environment to the server identified with DataURL as HTTP headers when the DataURL form parameter is used. A form element becomes a forwarding header when its name ends with __ (double underscore). There are no restrictions on naming the forwarding header; the value for the forwarding header consists of the HTTP header name, a colon and the HTTP header value (in other words exactly the same as a header line in the HTTP request. e.g. Header: Value. See also section 3.3.2.2.

Other form fields

Other form fields are those form elements that do not fall under one of the categories mentioned above. They are not evaluated by the Citizen Card Environment, but can be referenced from a Security Layer command (cf. section 3.2.1.2).

3.2.1.2 Referencing form fields

In the context of the HTTP binding, it is possible to reference form elements transmitted in the HTTP request from a Security Layer command. Reference can be made not only to the form parameters defined above, but also to any form elements (form parameters, forwarding parameters, forwarding headers and other form fields). Possible application scenarios are referencing in Create(XML|CMS)Signature and Verify(XML|CMS)Signature signature commands.

The protocol to be used in a URL of this kind is formdata. The name of the form elements to be referenced are to be specified as the opaque part of the URL. The Citizen Card Environment must return the value of the referenced form element as the resolution of the URL.

For example, if the HTML format for the form element is <input name="summary" value="Brief Summary"/>, then this element is referenced with the formdata:summary URL. The resolution results in the string Brief Summary.

3.2.2 Form parameters

The following form parameters are available to control procedures in the Citizen Card Environment:

XMLRequest

This must be specified and contains the Security Layer command request as an XML structure.

RedirectURL

May be specified and is used to divert the application asynchronously. See section 3.2.3.

DataURL

May be specified and is used to send the result of the processing of the command by the Citizen Card Environment to a particular server instead of allowing it to be sent to the application in the HTTP response. See section 3.2.3.

StylesheetURL

May be specified and if necessary is used by the Citizen Card Environment to transform the result of command processing before it is returned in the HTTP response to the application. See section 3.2.3.

PushInfobox

May be specified and if it is specified it tells the Citizen Card Environment that the content of the info box named after this info box and the result of the of the executed command should be accepted and further processed by the server specified by the form parameter DataURL. Multiple info box identifier can be specified by separating them with a comma (',');

Note: The form parameter PushInfobox must not be equalized to a request to read an info box (see Abschnitt 7.5, "Lesen von Daten einer Infobox").

Note: Section 3.2.4 lists meaningful combinations of the RedirectURL, DataURL, StylesheetURL and PushInfobox form parameters.

3.2.3 Step-by-step procedure

1. The Citizen Card Environment opens the service at the defined port and waits for incoming connections.
2. An application issues an HTTP request to the specified address. The connection created in this way is referred to as a browser connection below.
3. If the RedirectURL form parameter has been specified, the Citizen Card Environment responds to the application with an HTTP Redirect (HTTP code: 302 or 303) with the URL specified in this parameter and closes the browser connection.
4. The Citizen Card Environment takes the command request to be processed from the XMLRequest form parameter and processes it.
5. If the DataURL form parameter has been specified, the Citizen Card Environment sends the command response in encoded form, as described in section 3.3.2.2, to the server identified with DataURL. The server's response influences the process as follows:
   1. HTTP code 200, content type: text/xml or text/plain or text/html and content of the HTTP response equals <ok/> (in exactly this sequence): processing continues at step 6.
   2. HTTP code 200, content type: text/xml and content of the HTTP response does not equal <ok/> : The data is evaluated as a command request and assigned to the XMLRequest form parameter. The form parameter PushInfobox is rejected, the other form parameters (StylesheetURL, RedirectURL and DataURL), forwarding parameters and headers and other (reference-capable) form fields remain unchanged. Processing continues at step 4.
   3. HTTP code 307, content type: text/xml: The contents of the HTTP response will be evaluated as a command and assigned to the XMLRequest form parameter. The contents of the Location HTTP header are assigned to the DataURL form parameter. The form parameter PushInfobox is rejected, the other form parameters (StylesheetURL and RedirectURL), forwarding parameters and headers and other (reference-capable) form fields remain unchanged. Processing continues at step 4.
   4. HTTP code 200, content type: application/x-www-form-urlencoded or multipart/form-data: The contents of the HTTP response are evaluated as a collection of form elements. The previous form parameters, forwarding parameters and headers and other (reference-capable) form fields are discarded. Instead, the form parameters, forwarding parameters and headers and the other (reference-capable) form fields contained in the HTTP response are used. Processing continues at step 3.
   5. HTTP-Code 200, where the combination of content type and content of the HTTP response does not fall within the parameters of points 5a, 5b or 5d; HTTP code 307, where the content type does not come under point 5c; HTTP code 301, 302, 303: The HTTP response is forwarded to the browser connection without change, the browser window is closed and processing is ended.
   6. Other scenarios (e.g. HTTP code 404): The Citizen Card Environment issues a corresponding error message via the user interface, also transmits this to any still existing browser connection, closes this and halts processing.
6. If the StylesheetURL form parameter is specified, the Citizen Card Environment reads an XSL style sheet from the address specified there and uses it to transform the command response.
7. If the RedirectURL form parameter has not been specified, the Citizen Card Environment sends the command response (which may have been transformed) in the existing browser connection and closes the browser connection.

A server-based Citizen Card Environment may also handle the user interface communications between steps 2 and 3 (when a Redirect is used) or between steps 2 and 7 (other) (and set cookies in the process, for example). Thus, the application may not assume that the Redirect or the command result will be returned instantly as a response to the sent HTTP request.

Note: If a RedirectURL is specified, the browser connection is ended in step 3. It is then no longer possible to send data to the browser connection (for example in scenario 5e) even though this may be necessary. In this case, the Citizen Card Environment must issue an appropriate error message via the user interface.

Note: If a condition is formulated in the above procedure requiring, for example, that the content type HTTP header must be text/plain, this simply means that the media type must always be text/plain. If the actual value of content type is text/plain; charset=ISO-8859-1, then this condition is also met.

Note: The explanations for scenarios 5b, 5c and 5d show that both the changed and unchanged parameters must be sent again to the server identified with DataURL in the next HTTP response.

Note: An application that uses the DataURL form parameter should generally assume that a Citizen Card Environment has not implemented cookie management and thus, should not use the HTTP cookie mechanism.

3.2.4 Combining form parameters

The procedure described in section 3.2.3 results in effective and ineffective combinations of the RedirectURL, DataURL and StylesheetURL form parameters. The following table contains an overview and explains the effects in brief:

3.3 Encoding

3.3.1 HTTP request

The HTTP request of the application to the Citizen Card Environment must be encoded in accordance with [HTTP 1.1]. The method must be either GET or POST and both variants must be supported by the Citizen Card Environment. (Note: Some Web clients only support a limited GET request size.) Encoding can take the form of application/x-www-form-urlencoded or multipart/form-data; both formats must be supported by the Citizen Card Environment.

If the HTTP request is sent to a local Citizen Card Environment, it must be sent to the /http-security-layer-request URL. Otherwise the Citizen Card Environment must respond with an HTTP 404 error message. If, on the other hand, the HTTP request is sent to a server-based Citizen Card Environment, the service provider may specify any URL.

3.3.2 HTTP response and HTTP request to DataURL

3.3.2.1 HTTP response to the browser connection

Identification of the Citizen Card Environment

If the Citizen Card Environment sends the command response in the existing browser connection (cf. section 3.3.2, item 7), the Citizen Card Environment must identify itself using the HTTP header Server (cf. [[HTTP 1.1], section 14.38). The format of the HTTP header Server must be as follows:

Server = "Server" ":" User-Agent = "User-Agent" ":" "citizen-card-environment" "/" cceVersion " " productName "/" productVersion

Thus, two product tokens are to be specified: The first indicates that the server is a Citizen Card Environment; cceVersion specifies the latest version of the Security Layer specification that supports the Citizen Card Environment (for example 1.2 for this version). The second product token identifies the manufacturer of the Citizen Card Environment; productName and productVersion can be freely selected within the parameters of [HTTP 1.1].

The Citizen Card Environment must identify itself using the same method when it sends an HTTP Redirect in the existing browser connection (cf. section 3.2.2, item 3).

Encoding of the HTTP response

The command response is transmitted to the browser as useful HTTP response contents (cf. section 3.2.3, scenario 5a). The Citizen Card Environment must set the HTTP header Content-Type:

• If the command response is available as an XML structure, then it is necessary to use either the value text/xml (if the command response according to section 3.2.3, step 6 was not transformed with the help of a style sheet), or the MIME Media Type resulting from the style sheet transformation used.
• If the command response is not available as an XML structure (e.g. binary response to the DecryptCMS or DecryptXML commands), the content type must be set in line with the data transmitted in binary form. If the content type of the data transmitted in binary form is unknown, then the value application/octet-stream must be used.

3.3.2.2 HTTP request to DataURL

Identification of the Citizen Card Environment

If the Citizen Card Environment sends the command response by HTTP request to the server identified with DataURL (cf. section 3.3.2, item 5), the Citizen Card Environment must identify itself using the HTTP header User-Agent (cf. [HTTP 1.1], section 14.43). The User-Agent HTTP header must correspond to the following model; the variables used in the model must be interpreted as described in section 3.3.2.1:

User-Agent = "User-Agent" ":" "citizen-card-environment" "/" cceVersion " " productName "/" productVersion

Encoding of the HTTP request

The HTTP request to the server identified with DataURL must comply with the POST method (cf. [HTTP 1.1], section 9.5), must be encoded as multipart/form-data, and must contain the following form fields:

Note: Advice for application developers: Some implementation of the security layer (citizen card environments) use application/x-www-form-urlencoded instead of multipart/form-data for encoding the http request. To ensure compatibility with all implementations developers should evaluate the http-header Content-Type.

ResponseType form parameter

Always set to the value HTTP-Security-Layer-RESPONSE (can be used for distinguishing purposes in later versions).

XMLResponse form parameter

Contains the command response if it is available as XML structure. The Content-Type header of this MIME Part must be used and assigned the permanent value text/xml (also confer note 2 in section 3.2.3).

BinaryResponse form parameter

Contains the command response if it does not exist as an XML structure (e.g. binary response to the commands sl12:DecryptCMSRequest or sl12:DecryptXMLRequest). The Content-Type header of this MIME Part must be used to identify the content type of the binary response. If the content type is unknown, then the field value must be specified with application/octet-stream (also confer note 2 in section 3.2.3).

Forwarding parameters

The forwarding parameters that may be contained in the HTTP request to the Citizen Card Environment (cf. section 3.2.1.1) are included in the HTTP request to the server identified by DataURL without change.

Forwarding headers

The forwarding parameters that may be contained in the HTTP request to the Citizen Card Environment (cf. section 3.2.1.1) are included as HTTP headers in the HTTP request to the server identified by DataURL.

If the comand response does not represent an error response, the HTTP-request to the the server, represented by DataURL, MAY contain form parameters for infoboxes with identifiers

• that are headed in the form parameter PushInfobox included in the HTTP-request to the Citizen Card Environment (cf. section 3.2.2) and
• where the names differ from the above specified form parameter (ResponseType, XMLResponse, BinaryResponse and forwarding parameters).

The name of such a form parameter MUST be equal to the corresponding info box; the parameter's value MUST match the read request of the denoted info box (cf section 7.5). When accessing the info box the same rules, regarding access-protection, as in reading an info box (cf section 7.5)  MUST be applied. If the access to an info box is forbidden because of access protection, the HTTP request, sent to the the server specified by DataUrl, MUST NOT contain the form parameter specifying the info box.

If the command response is the answer to a former info box read request, box-specific parameters MUST be, if possible, applied to info boxes that are passed as form parameters.

Note: If e.g. electronic mandates are passed within the command response to an identity link info box read request, then an included box-specific parameter (e.g. sl:IdentityLinkDomainIdentifyer) has to be applied to the forwarded electronic mandates as well.

3.3.3 Protocols for DataURL and StylesheetURL

HTTP and HTTPS must be supported as protocols for accessing the DataURL and StylesheetURL.

4 SSL/TLS binding

The TLS binding is a 1:1 implementation of the Security Layer commands. A typical TLS connection [TLS] is used by means of a socket. The XML commands according to the Security Layer application interface are transmitted without further encoding or implementation/embedding in the connection.

In terms of procedure and structure, the TLS binding corresponds to the TCP/IP binding, except that the underlying transport protocol is TLS.

4.1 Identifier, parameters and default address

The identifier and parameters of a binding are used in the GetProperties command of the Security Layer. The identifier for this binding is TLS and has no parameters.

4.2 Procedure

The procedure is the same as for the TCP/IP binding (cf. section 2.2), except that in point 2, when establishing the connection, a handshake and channel encryption take place in accordance with TLS.

4.3 Encoding

There is no more embedding encoding. XML commands are transmitted to the TLS connection on a 1:1 basis.

5 HTTPS binding

Like the HTTP binding of the application, the HTTPS binding allows the Citizen Card functions to be accessed directly and without further active components (e.g. an applet). This requires that the XML request should be embedded in an HTTP request.

The HTTPS binding is the same as the HTTP binding, except that the underlying transport protocol is HTTPS [HTTPS] (HTTP with TLS [TLS]).

5.1 Identifier, parameters and default address

The identifier and parameters of a binding are used in the GetProperties command of the Security Layer. The identifier for this binding is HTTPS and has no parameters.

5.2 Procedure

The procedure is the same as for the HTTP binding, except that in point 2, when establishing the connection, a handshake and channel encryption take place in accordance with TLS.

5.3 Encoding

Encoding takes place as defined in section 3.3 for the HTTP binding, with the following exceptions:

• If the HTTP request is sent to a local Citizen Card Environment, it must be sent to the /https-security-layer-request URL.
• If the XML response is sent to a DataURL Server by HTTP(S) request, then the ResponseType form parameter must be set to HTTPS-Security-Layer-RESPONSE.

6 References

HTML 4

Dave Ragget, Arnaud Le Hors and Ian Jacobs: HTML 4.01 Specification.W3C Recommendation, December 1999. Downloaded from the World Wide Web on 14 May 2004 under http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/.

HTTP 1.1

R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leech and T. Berners-Lee: Hypertext Transfer Protocol – HTTP/1.1. IETF Request For Comment, June 1999. Downloaded from the World Wide Web on 14 May 2004 under http://www.ietf.org/rfc/rfc2616.txt.

HTTPS

E. Rescorla: HTTP over TLS: IETF Request For Comment, May 2000. Downloaded from the World Wide Web on 14 May 2004 under http://www.ietf.org/rfc/rfc2818.txt.

KEYWORDS

Bradner, S.: RFC 2119: Key words for use in RFCs to Indicate Requirement Levels. IETF Request For Comment, März 1997. Downloaded from the World Wide Web on 14 May 2004 under http://www.ietf.org/rfc/rfc2119.txt.

TLS

T. Dierks and C. Allen: The TLS Protocol Version 1.0. IETF Request For Comment, January 1999. Downloaded from the World Wide Web on 14 May 2004 under http://www.ietf.org/rfc/rfc2246.txt.

IANA – Port numbers

Internet Assigned Numbers Authority: Port numbers. Downloaded from the World Wide Web on 14 May 2004 under http://www.iana.org/assignments/port-numbers

7 History