Logo BKA Open Interfaces
for e-Government
Logo A-SIT

The Austrian Citizen Card

Security Layer Transport Protocols


Document information

Designation

Transport protocols for the Security Layer application interface of the Austrian Citizen Card

Brief designation

Security Layer transport protocols

Version

1.2.1

Date

2005-03-01

Document class

Convention

Document status

Recommendation

Short Name

The Security Layer application interface document defines the XML structure and the required functionality of the Security Layer interface commands. This document describes how these XML commands can be integrated in a number of transport protocols.

Authors

Arno Hollosi
Gregor Karlinger

Work group

Federal Chancellery, Federal Staff Unit for ICT Strategy, Technology and Standards

©

This specification is supplied by A-SIT and the Federal Chancellery. It may be used without modification provided that reference is made to this copyright notice. The specification may be expanded, however any additional material must be clearly identified and the expanded specification must be made freely available.


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
      1. General information
        1. Terminology
        2. Referencing form parameters
      2. Form parameters
      3. Step-by-step procedure
      4. Combining form parameters
    3. encoding
      1. HTTP request
      2. HTTP response and HTTP request to DataURL
        1. HTTP response to the browser connection
        2. HTTP request to DataURL
      3. Protocols for DataURL and StylesheetURL
  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:

Prefix
Name space
Explanation
sl http://www.buergerkarte.at/namespaces/securitylayer/1.2# Elements of the interface specification

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.

Note: Section 3.2.4 lists meaningful combinations of the RedirectURL, DataURL and StylesheetURL 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 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 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:

RedirectURL
DataURL
StylesheetURL
Meaning
Effect
-
-
-

limited effectiveness

Command response will be sent directly to the calling application. Only suitable for evaluation by programmes or scripts. Not suitable for end-users because they will be confronted with XML as plain text.

-
-
X

effective

Command response will be transformed into HTML and sent directly to the calling application.

-
X
-

effective

Effective. Command response will be sent to the server identified with DataURL. The server is responsible for a meaningful concluding response to the application (scenarios 5a or 5e).

-
X
X

effective

The result response will be sent to the server identified with DataURL. The calling application receives a result transformed to HTML: this corresponds to synchronous user guidance. Only effective in scenarios 5a, 5b, 5c. There is no point in specifying the StylesheetURL in scenarios 5d, 5e and 5f.

X
-
- / X

ineffective

The application is diverted, but the command response cannot be received by anyone.

X
X
-

effective

The application immediately receives a Redirect and the command response is sent to the server identified with DataURL: this corresponds to asynchronous user guidance.

X
X
X

ineffective

StylesheetURL is useless. Instead the previous scenario should be used.

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:

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:

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.

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.

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

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.

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

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:

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

Date
Version
Changes
2005-03-01
1.2.1
  • Erratum 31 eliminated.
2004-05-14
1.2.0
  • Errata16 and 19 eliminated according to Errata document.
  • Provisions added in section 3.3.2 for identifying the CCE with the Server and User-Agent HTTP headers.
  • Confusion in section 3.2.3 eradicated.
  • Forwarding headers introduced.
  • Document reorganised.
  • Environment variables removed.
  • If the HTTP(S) request is made to a server-based CCE, the service provider has free choice of URL.
  • A server-based CCE may also handle the communication of the user interface in the existing browser connection between steps 2 and 3 or 2 and 7 of the procedure described in section 3.2.
2003-08-31
1.1.0
  • Revision of the HTTP binding Response and effects of the DataURL specified in detail (section 3.3).
  • Effects on safety when the HTTP binding is used explained in greater detail (section 3.6).
  • RedirectURL can also return code 302 (section 3.3).
  • Multipart/form data also accepted as encoding in HTTP binding (section 3.4).
  • Forwarding fields defined for HTTP binding (section 3.4).
  • Form fields can be referenced (section 3.5).
  • Examples revised (section 3.7) and application scenarios outlined (section 3.8).
  • Global replacement of the term "security capsule" with "Citizen Card Environment"
2003-03-18
1.0.1
  • Entry of the IANA-registered port numbers as default port numbers for TCP/IP, TLS, HTTP, HTTPS
  • Reference added to the IANA list of registered port numbers.
  • Error in section numbering in section 3 corrected.
  • The required query URL changed to lowercase throughout in sections 3.4 and 5.4.
  • ResponseType added to section 5.4 of the documentation.
  • Change in section 3.4 relating to DataURL "Als Protokolle sind verpflichtend HTTP und HTTPS zu unterstützen." (HTTP and HTTPS must be supported as protocols.) explicitly added to the document.