for e-Government
|
Open Interfaces for e-Government |
|
Security Layer Transport Protocols
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 |
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. |
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).
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 |
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].
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.
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.
There is no more embedding encoding. XML commands are transmitted to the TCP/IP connection on a 1:1 basis.
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.
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.
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:
XMLRequest, RedirectURL, DataURL and StylesheetURL. For detailed information see section
3.2.2. 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. 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. 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.
The following form parameters are available to control procedures in the Citizen Card Environment:
XMLRequest RedirectURL DataURL StylesheetURL PushInfobox Note: Section
3.2.4 lists meaningful combinations of the RedirectURL, DataURL and StylesheetURL form parameters.
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. XMLRequest form
parameter and processes it. 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.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. 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.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.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. 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. 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.
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 |
- |
X |
X |
effective |
The result response will be sent to the server identified with |
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 |
X |
X |
X |
ineffective |
|
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.
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).
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:
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. application/octet-stream must be used. 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
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 parameterAlways 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).
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.
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.
Wenn die Befehls-Response ...
HTTP and HTTPS must be
supported as protocols for accessing the DataURL and StylesheetURL.
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.
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.
127.0.0.1,
while the default port is 3496.
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.
There is no more embedding encoding. XML commands are transmitted to the TLS connection on a 1:1 basis.
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]).
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.
127.0.0.1,
while the default port is 3496.
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.
Encoding takes place as defined in section 3.3 for the HTTP binding, with the following exceptions:
/https-security-layer-request URL. ResponseType form parameter must be set to HTTPS-Security-Layer-RESPONSE. | Date | Version |
Changes |
|---|---|---|
| 2005-03-01 | 1.2.1 |
|
| 2004-05-14 | 1.2.0 |
|
1.1.0 |
|
|
1.0.1 |
|