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

The Austrian Citizen Card

Security Layer Application Interface


Document information

Designation

The Security Layer application interface for the Austrian Citizen Card

Brief designation

Security Layer application interface

Version

1.2.2

Date

2005-03-01

Document class

Convention

Document status

Recommendation

Short Name

This document specifies the interface between application and Citizen Card Environment.

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.


Contents

  1. General information
    1. Protocol elements
    2. Naming conventions
    3. Keywords
  2. Creating a signature
    1. Signatures in CMS format
      1. Request
      2. Response
    2. Signatures in XMLDSIG format
      1. Request
      2. Response
  3. Verifying a signature
    1. Signatures in CMS format
      1. Request
      2. Response
    2. Signatures in XMLDSIG format
      1. Request
      2. Response
  4. Encryption
    1. Encryption as a CMS message
      1. Request
      2. Response
    2. Encryption as an XML document
      1. Request
      2. Response
  5. Decryption
    1. Decrypting a CMS message
      1. Request
      2. Response
    2. Decrypting an XML document
      1. Request
      2. Response
  6. Hash values
    1. Hash value calculation
      1. Request
      2. Response
    2. Hash value verification
      1. Request
      2. Response
  7. Access to info boxes
    1. Types of info boxes
      1. Binary file
      2. Associative array
    2. Requesting available info boxes
      1. Request
      2. Response
    3. Creating an info box
      1. Request
      2. Response
    4. Deleting an info box
      1. Request
      2. Response
    5. Reading data in an info box
      1. Request
      2. Response
    6. Changing data in an info box
      1. Request
      2. Response
  8. Requesting properties
    1. Requesting environment properties
      1. Request
      2. Response
    2. Requesting the token status
      1. Request
      2. Response
  9. Null operation
    1. Request
    2. Response
  10. Error handling
    1. Error codes
  11. Glossary
  12. References
  13. History

1 General information

This document defines the Security Layer interface. This is the interface by means of which an application accesses functions of the Citizen Card, for example in order to create an electronic signature or to read data from the Citizen Card Environment data storage area.

For a definition indicating which of the interface commands described in this document must always be provided by a Citizen Card Environment, see Minimum implementation of the Security Layer.

For requirements placed on the user interface when any of the interface commands described in this document are executed, see Requirements for the user interface.

1.1 Protocol elements

The protocol consists of simple question/answer templates. The application sends a request coded in XML to the Citizen Card Environment. The latter returns a corresponding XML-coded response to the application.

The various protocol elements for this XML interface command are specified as an [XML schema] in Core-1.2.xsd. Together with this interface specification, this XML schema forms the normative source for protocol elements.

1.2 Naming conventions

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

The various protocol elements were assigned meaningful names and abbreviations were avoided insofar as possible. All requests end with the suffix Request, while the corresponding responses end with the suffix Response.

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

Prefix
Name space
Explanation
dsig http://www.w3.org/2000/09/xmldsig# Elements from [XMLDSIG]
xenc http://www.w3.org/2001/04/xmlenc# Elements from [XMLEnc]
etsi http://uri.etsi.org/01903/v1.2.2# Elements from [ETSIXML]
sl http://www.buergerkarte.at/namespaces/securitylayer/1.2# Elements of this specification

1.3 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 Creating a signature

The Security Layer interface supports two possible formats for creating an electronic signature: [CMS] and [XMLDSIG].

2.1 Signatures in CMS format

2.1.1 Request

A signature in [CMS] format can be used to sign precisely one data object.

Structure of the signature

First, it is necessary to indicate in the Structure attribute of the signature request (sl:CreateCMSSignatureRequest) whether or not the subsequently specified data object is to be incorporated in the signature structure (value "enveloping" or "detached").

Signature key designation

Furthermore, the identifier for the key to be used to create the signature (sl:KeyboxIdentifier) must be specified in the signature request. Identifiers for all available keys can be requested from the Citizen Card Environment using the sl:GetPropertiesRequest command.

Information about the data object

The signature request includes a container, sl:DataObject, that contains the data object to be signed (sl:Content) as well as meta information (sl:MetaInfo) for creating the signature and for any required display in the Citizen Card Environment.

The meta information must always include the mime type (see [MIME]) of the data object to be signed. A verbal description of the data object may also be specified (sl:Description). Finally, any number of other elements may be added to this meta information.

Note: If the data object to be signed is to be interpreted by the Citizen Card Environment as text, then the application must use the text/plain mime type; if it is to be interpreted in terms of the standardised viewer format of the Security Layer, then the application must use the application/xhtml+xml mime type. See also Minimum implementation of the Security Layer.

The data object to be signed can be specified in two different ways: Either the sl:Content element contains the base64-coded data, or the sl:Content element is empty, but has set its Reference attribute. In the latter case, the Citizen Card Environment must attempt to resolve the URI specified in this attribute so as to obtain the data to be signed.

2.1.2 Response

The response consists of the sl:CMSSignature element, which contains the signature created according to [CMS] in base64-coded form. For detailed specifications relating to the signature to be created in terms of digest algorithms, signature algorithms and key information, see Minimum implementation of the Security Layer.

Signed meta information

The [CMS] signature must include a signed ContentHints signature attribute according to [ESS-S/MIME], section 2.9. The (sl:MetaInfo) meta information specified in the request in the container for the (sl:DataObject) data object must be used to create this signature attribute.

An initial field contentDescription in ContentHints must be used for the sl:MimeType element from sl:MetaInfo; if the sl:Description element from sl:MetaInfo is available, then it must be coded in another field named contentDescription in ContentHints. The contentType field must be assigned the value of the object identifier for id-data (see [CMS], section 4).

Signed certificate reference

Furthermore, a signed OtherSigningCertificate signature attribute must be included in the [CMS] signature according to [ETSICMS]; this is used to identify clearly the signatory certificate to be used to verify the signature.

Timing of the creation of the signature

Finally, a SigningTime signature attribute according to [ETSICMS] must be integrated in the [CMS] signature, which contains the time at which the signature was created according to the signatory's statement.

Note: For examples of this command see the Tutorial; for user interface requirements see User interface requirements, section 3.1.

2.2 Signatures in XMLDSIG format

2.2.1 Request

Unlike the signature in [CMS] format, the signature in [XMLDSIG] format also allows several data objects to be signed with a single signature.

Signature key designation

The identifier for the key to be used to create the signature (sl:KeyboxIdentifier) must be specified in the signature request. Identifiers for all available keys can be requested from the Citizen Card Environment using the sl:GetPropertiesRequest command.

Information about the data object

The signature request for each data object to be signed contains a container (sl:DataObjectInfo) with the information for creating the signature and for any necessary display in the Citizen Card Environment. sl:DataObjectInfo has a Structure attribute that indicates whether the data object specified in the container is to be incorporated in the signature structure (value "enveloping") or whether the signature of this data object is simply to be referenced (value "detached").

Data object

A container of this kind primarily consists of information about the data object that is transformed and then signed (sl:DataObject). Depending on the Structure attribute discussed above, the following combinations are permitted for the content of sl:DataObject and its Reference attribute (all other combinations are invalid):

Structure Option Description
"enveloping" A(1,2,3)

The Reference attribute is not used; the content of sl:DataObject represents the data object. If the data object is XML-coded (the sl:XMLContent element is used in sl:DataObject), then it must be incorporated in the signature structure as parsed XML.

B(2,4) The Reference attribute contains a URI that must be resolved by the Citizen Card Environment to obtain the data object. The content of sl:DataObject remains empty. If the data object referenced in this way is text or XML data, it makes sense to incorporate the data object in the signature structure as parsed XML. During resolution, the Citizen Card Environment shall therefore evaluate information from the transport protocol in order to find out whether there is any text or XML data. In the case of a URI that has http or https as protocol, the information in the HTTP header (Content-Type) must be evaluated for this purpose.
"detached" C The Reference attribute contains a URI that must be resolved by the Citizen Card Environment to obtain the data object. The Reference attribute contains a URI that is used by the Citizen Card Environment to code the reference to the data object as part of the XML signature (attribute URI in the dsig:Reference) element. The content of sl:DataObject remains empty.
D(1.5) The Reference attribute contains a URI that is used by the Citizen Card Environment to code the reference to the data object as part of the XML signature (attribute URI in the dsig:Reference) element. The content of sl:DataObject represents the data object.

(1) If the content of sl:Dataobject is to be used explicitly to specify the data object, then three different kinds of encoding are available:

(2) A data object transmitted in case A or B must be incorporated in the XML signature, or this data object incorporated in the signature must be referenced from the associated dsig:Reference element of the XML signature in such a way that only the data transmitted in the request in sl:DataObject is signed. If, for example the data object is incorporated in the XML signature as the content of a dsig:Object element, then this dsig:Object container element must not also be signed, but only its content.

(3) If the data object is available in base64-coded form (the sl:Base64Content element is used in sl:DataObject), then the base64-decoded data must always be signed. If the Citizen Card Environment cannot integrate the base64-decoded data directly in the dsig:Object (because this contains characters that cannot be represented as XML text), then it must integrate the base64-coded data instead and use a base64 transformation as the first transformation in the associated dsig:Reference.

(4) If the referenced data object is neither text nor XML data or if the data object is not checked for text or XML data, contrary to recommendations, then it must be incorporated in the signature structure in base64-coded form. However it is necessary to sign the original data object: for this reason, a base64 transformation is to be used in the dsig:Reference referring to the integrated data object.

(5) If the URI transmitted in Reference is an internal URI according to [URI], section 4.2 (same-document reference), then it must refer to the XML document in which the signature is to be embedded (and which is transmitted in sl:SignatureEnvironment – compare the section entitled Information about the signature document).

Transformation paths

The sl:DataObjectInfo container also contains one or more transformation paths for the data object (sl:TransformsInfo).

A transformation path describes a chain of transformations to be carried out (dsig:Transforms) in order to get from the data object to the data incorporated in the hash calculation and subsequently in the signature calculation (referred to below as hash input data).

The hash input data is also the data that must be presented to the user as required in the Citizen Card Environment. To ensure that the Citizen Card Environment knows the nature of the hash input data, the transformation path also contains meta information about this (sl:FinalDataMetaInfo). The mime type (see [MIME]) must always be specified (sl:MimeType) and in addition, a verbal description of this data may also be provided (sl:Description).

Note: If the data object to be signed is to be interpreted by the Citizen Card Environment as text, then the application must use the text/plain mime type; if it is to be interpreted in terms of the standardised viewer format of the Security Layer, then the application must use the application/xhtml+xml mime type. See also Minimum implementation of the Security Layer.

If the data object is to be signed directly, then a transformation path is also specified, but not the transformation chain. When more than one transformation path is specified, the Citizen Card Environment can select a path freely.

If a transformation path is specified, the application must ensure that all name spaces used within the structure of the relevant transformations (dsig:Transforms) are explicitly declared within this structure. The Citizen Card Environment must not add name space declarations within dsig:Transforms when it transmits the structure to the signature to be created.

Supplementary objects

As an option, supplementary objects (sl:Supplements) can be specified in the sl:DataObjectInfo container. These can be transmitted so that data that is required for the data object or for display purposes as part of the transformation process does not need to be resolved by the Citizen Card Environment. The data object itself must not be transmitted as a supplementary object.

An example of this is a style sheet transformation that uses nested style sheets: Only the basic style sheet is listed as a parameter in the (dsig:Transform) transformation object; other style sheets referenced in the basic style sheet must be broken down by the Citizen Card Environment itself. This can be avoided by transmitting such referenced style sheets as supplementary objects

A supplementary object consists of optional meta information (cf. sl:FinalDataMetaInfo) on the one hand, and the actual data (sl:Content) on the other: The Reference attribute, which must be used, contains the reference to the supplementary data as URI in the form in which it would be used by the Citizen Card Environment for resolution purposes. The content of sl:Content represents the supplementary data (see also Note in section 2.2.1, Data object).

If the Citizen Card Environment encounters data requiring resolution while calculating the transformation process, it must follow this resolution procedure:

  1. Check whether the reference to be resolved occurs in an sl:Supplement within the sl:DataObjectInfo that specifies the transformation process just calculated. If this check is successful, then the data specified in this sl:Supplement is to be used as the result of the resolution. Otherwise continue with step 2.
  2. Check whether the reference to be resolved occurs in an sl:Supplement of a different sl:DataObjectInfo specified in the command to create the XML signature. The various sl:DataObjectInfo elements are to be examined in the order in which they have been specified in the command. The data specified in the first sl:Supplement found in this way are to be used as a result of the resolution. If an sl:Supplement is not found, then continue with step 3.
  3. Resolve the reference.

Information about the signature document

If the signature to be created is to be embedded in an existing XML document, the sl:SignatureInfo container will be included in the signature request. If this container is missing, the signature must not be embedded at all but is to be returned directly as the result of the request (see section 2.2.2).

The signature document

The signature document sl:SignatureInfo primarily contains details of the signature document in which the signature is to be embedded (sl:SignatureEnvironment). Either the Reference attribute contains a reference to this document that is to be resolved by the Citizen Card Environment or the document itself is specified as the content of sl:SignatureEnvironment.

There are two different direct embedding methods: Either the XML document is coded in base64 and integrated as text belonging to the sl:Base64Content child element, or the root element of the XML document is specified directly as the only child of the sl:XMLContent child element. See also the Note in section 2.2.1, Data object.

Note: If an XML document is specified as a signature document that uses a declaration document type (see [XML]), the first variant of the direct embedding (base64 encoding) shall be used so that the information contained there can be evaluated by the XML parser of the Citizen Card Environment. This information cannot be specified when embedding the root element in sl:XMLContent.

Note: The following procedure is recommended when parsing the signature document: In a first round, the Citizen Card Environment tries to parse the document for validation purposes. Information about the grammar of the document may be provided by a Document Type Declaration contained in the document (see [XML]), or XML schemas that are referenced with the mechanisms specified in [XML schema], section 2.6.3. If this first attempt fails, the Citizen Card Environment parses the document in a second pass without validation, i.e. without evaluating grammatical information.

Position of the signature

The next element, sl:SignatureLocation, contains information about the position at which the signature to be created is to be inserted in the signature document by the Citizen Card Environment.

The text of the element contains an expression according to [XPath] which is used to select the parent element of the signature to be inserted. The document node of the XML document specified in sl:SignatureEnvironment is to be used as a context node for evaluating the XPath expression. If name space prefixes are used in the XPath expression, the relevant name space declarations must be known in the context of the sl:SignatureLocation element.

The Index attribute selects the position of the signature within the parent element. If the value of Index is 0, the signature is inserted as the first child node of the parent element, while if the value of Index is n, the signature is inserted immediately after the nth child node of the parent element.

Supplementary objects

In addition, supplementary objects (sl:Supplements) that are linked with the signature document can be specified.

For example, the signature document specified in sl:SignatureEnvironment could contain a reference to the document type definition. The document referenced in this way can be transmitted by the application as a supplementary object if the Citizen Card Environment shall not resolve the reference itself, or if the Citizen Card Environment cannot resolve the reference, for example because it is a relative reference relating to the signature document.

Another example of the use of a supplementary object might be an XML schema, which is referenced in the signature document specified with sl:SignatureEnvironment using the mechanisms suggested in [XML schema] (see Note in the preceding section entitled The signature document).

A supplementary object consists of optional meta information (cf. sl:FinalDataMetaInfo in section 2.2.1, Transformation paths) on the one hand, and the actual data (sl:Content) on the other: The Reference attribute, which must be used, contains the reference to the supplementary data as URI in the form in which it would be used by the Citizen Card Environment for resolution purposes. The content of sl:Content represents the supplementary data (see also Note in section 2.2.1, Data object).

2.2.2 Response

The response contains the electronic signature coded according to [XMLDSIG]. If an sl:SignatureInfo element has been specified in the request, the response contains the document specified in sl:SignatureInfo with the signature integrated there as the only child. Otherwise the response contains the signature generated directly.

Signed data

The XML signature contains a dsig:Reference element for every data object transmitted in the request by means of the container (sl:DataObjectInfo). The transformation chain completed in the Citizen Card Environment is to be specified in its dsig:Transforms element so as to obtain data from the transmitted data object that has been used to calculate the hash value and for display in the secure viewer, if necessary.

Implicit transformation parameters

In order to be able to check the correct relationship between the reference input data and the hash input data at any subsequent point, the implicit transformation parameters of all data objects to be added to the signature must be included in a single signature manifest. If there are no implicit transformation parameters, the signature manifest must not be created.

In this context, an implicit transformation parameter is a date used by the Citizen Card Environment to calculate the transformations for a data object that is to be signed but that does not occur explicitly as a parameter in the corresponding transformation object (dsig:Transform).

The style sheet transformation mentioned in section 2.2.1 is currently the only known example that uses nested style sheets. The other style sheets referenced in the basic style sheet are implicit transformation parameters in the sense mentioned above.

The signature manifest (dsig:Manifest) contains a single reference object (dsig:Reference) for every implicit transformation parameter, which includes a hash value for the implicit transformation parameter. Transformations in the reference objects of the signature manifest must not be used. The URI attribute of a reference object contains the reference to the implicit transformation parameter in exactly the same way as it would be used by the Citizen Card Environment for resolution purposes when a signature is verified.

The input data for calculating the hash value by means of an implicit transformation parameter are produced as follows:

The signal manifest is integrated in the signature by means of a separate reference object of the signature (dsig:Reference in dsig:SignedInfo). It is required to use the Type attribute in the reference object to identify the referenced data item as a signature manifest. The attribute must have the following value:

http://www.buergerkarte.at/specifications/securitylayer/20020225#SignatureManifest

Signature attributes

The following information must be integrated in the signature using signature attributes according to [ETSIXML]. The signature attributes must be incorporated in the signature as direct incorporation in line with the instructions in sections 6.3 and, in particular, 6.3.1 by [ETSIXML]. The Type attribute mentioned in section 6.3.1 must be used.

Signed meta information

A signature attribute must be included for each data object (sl:DataObject) to be signed as specified in the request. The signature attribute should contain the specified meta information (sl:FinalDataMetaInfo).

The signed signature attribute etsi:DataObjectFormat according to [ETSIXML] is to be used for this. The sl:MimeType element from sl:FinalDataMetaInfo corresponds to the etsi:MimeType element from etsi:DataObjectFormat, while the optional sl:Description element from sl:FinalDataMetaInfo corresponds to the etsi:Description element from etsi:DataObjectFormat.

Signed certificate reference

Furthermore, a signature attribute must be included that uniquely identifies the signatory certificate used to verify the signature. The signed signature attribute etsi:SigningCertificate according to [ETSIXML] is to be used for this.

Timing of creation of the signature

Finally, a signature attribute containing the time of creation of the signature claimed by the signatory must be included. The signed signature attribute etsi:SigningTime according to [ETSIXML] is to be used for this.

Note: For examples of this command see the Tutorial; for user interface requirements see User interface requirements, section 3.1.

3 Verifying a signature

3.1 Signatures in CMS format

3.1.1 Request

This request transmits any signature in [CMS] format, which does not necessarily comply with the profile of this specification, to the Citizen Card Environment for verification.

Signatories

In the Signatories attribute, the request first contains details of the signatories specified in the CMS signature whose signatures are to be verified. The value of this attribute contains a list of positive integers, each positive integer containing the position of the signatory as it occurs in the CMS signature (SignerInfo structural element). If this attribute is not specified, then its value should be assumed to be 1, i.e. only the signature of the first signatory specified in SignerInfo is to be verified.

Verification time

As an option, the request for signature verification may next contain the time to be used to determine the validity of the signature to be verified (sl:DateTime). If this is not specified, the Citizen Card Environment must proceed as follows to determine the verification time:

Signature

The request then contains the signature to be verified according to [CMS] (sl:CMSSignature) in base64-coded form.

Data object

If the signed data object is not also coded in the [CMS] signature to be verified, it must also be transmitted in the request in the sl:DataObject element.

Meta information (sl:MetaInfo) can be specified in sl:DataObject (mime type and a reference to a description of the signed data object). After this, the data is specified in one of two ways: Either the sl:Content element contains the base64-coded data, or the sl:Content element is empty, but has set its Reference attribute. In the latter case, the Citizen Card Environment will attempt to resolve the URI specified in this attribute so as to obtain the data object to be signed.

3.1.2 Response

The following information is returned in the response for each signature to be verified as specified in the request:

First, information about the signatory's X.509 certificate is specified in sl:SignerInfo. sl:SignerInfo must consist of precisely one element dsig:X509Data which must, in turn, contain at least the following two elements:

Furthermore, this dsig:X509Data must contain the empty element sl:QualifiedCertificate if the signatory certificate is to be regarded as qualified. The following conditions must be met for this:

  1. The certificate extension qcStatements (see [QCert], 3.2.5) must be included.
  2. The esi4-qcStatement-1 statement (see [ETSIQCert], 4.2.1) must be contained within this certificate extension.

The question of whether other elements – such as the signatory certificate itself – are returned is a matter for the Citizen Card Environment. If it was not possible to identify a signatory certificate according to X.509 during verification, the question of which information about the public key is returned is also a matter for the Citizen Card Environment.

Separate results for the cryptographic verification of the signature (sl:SignatureCheck) and the checking of the signature verification data (sl:CertificateCheck) are also included.

The structure of both results is the same: The sl:Code element contains the result of the check in machine-readable form, while the optional element sl:Info contains more detailed additional information which is not specified further at this point. It would be conceivable to provide a human-readable plain text interpretation of the check results, for example.

Checking the validity of the signature

If the signature specified in the request has been created in line with this specification, then it contains a ContentHints signature attribute according to [ESS-S/MIME], section 2.9, which contains meta information about the signed data object. This signature attribute can be evaluated by the Citizen Card Environment as necessary.

The following values are defined for the content of the sl:Code element in sl:SignatureCheck:

sl:Code Meaning
0 The value of the signature has been verified successfully.
1 An error has occurred while verifying the value of the signature.

Checking the signature verification data

This involves constructing the certificate chain, from the signatory certificate to a trustworthy root certificate, and a status check for every certificate in the constructed certificate chain. The checking of the signature verification data may be omitted if an error has occurred while verifying the validity of the signature.

If the signature specified in the request has been created in line with this specification, then it contains an OtherSigningCertificate signature attribute according to [ETSICMS] with information about the signatory certificate. In such a case, this information must be used by the Citizen Card Environment as the starting point for constructing the certificate chain.

When older signatures are verified, it can happen that no more online information is provided by the certification service provider who issued the signatory certificate to enable the certificate chain to be constructed or the status of the certificates in this chain to be checked. To be able to verify such signatures nonetheless, it is recommended that the Citizen Card Environment should evaluate any existing unsigned CompleteCertificateRefs, CompleteRevocationRefs, CertificateValues and RevocationValues signature attributes according to [ETSICMS].

The following values are defined for the content of the sl:Code element in sl:CertificateCheck:

sl:Code Meaning
0 It was possible to construct a formally correct certificate chain from the signatory certificate to a trustworthy root certificate. Each certificate in this chain is valid at the check time specified in the request.
1 It was not possible to construct a formally correct certificate chain from the signatory certificate to a trustworthy root certificate.
2 It was possible to construct a formally correct certificate chain from the signatory certificate to a trustworthy root certificate. The check time for at least one certificate in this chain is outside the period of validity.
3 It was possible to construct a formally correct certificate chain from the signatory certificate to a trustworthy root certificate. The check time for all certificates in this chain is within the validity period. It was not possible to determine the certificate status for at least one certificate.
4 It was possible to construct a formally correct certificate chain from the signatory certificate to a trustworthy root certificate. The check time for all certificates in this chain is within the validity period. At least one certificate is revoked at the check time.
5 It was possible to construct a formally correct certificate chain from the signatory certificate to a trustworthy root certificate. The check time for all certificates in this chain is within the validity period. None of the certificates in this chain is revoked at the check time. At least one certificate is disabled at the check time.
99 The signature verification data has not been checked as an error has occurred while checking the validity of the signature.

Note: For examples of this command see the Tutorial; for user interface requirements see User interface requirements, section 3.2.

3.2 Signatures in XMLDSIG format

3.2.1 Request

This request transmits any signature in [XMLDSIG] format, which does not necessarily comply with the profile of this specification, to the Citizen Card Environment for verification.

Verification time

As an option, the request for signature verification may next contain the time to be used to determine the validity of the signature to be verified (sl:DateTime). If this is not specified, the Citizen Card Environment must proceed as follows to determine the verification time:

Signature

The request then contains details of the signature to be verified according to [XMLDSIG] (sl:SignatureInfo).

sl:SignatureInfo contains details of the XML document that includes the signature to be verified (sl:SignatureEnvironment). Either the Reference attribute contains a reference to this document that is to be resolved by the Citizen Card Environment or the document itself is specified as the content of sl:SignatureEnvironment.

There are two different direct embedding methods: Either the XML document is coded in base64 and integrated as text belonging to the sl:Base64Content child element, or the root element of the XML document is specified directly as the only child of the sl:XMLContent child element. See also the Note in section 2.2.1, Data object.

Note: If an XML document is specified that uses a declaration document type (see [XML]), the first variant of the direct embedding (base64 encoding) shall be used so that the information contained there can be evaluated by the XML parser of the Citizen Card Environment. This information cannot be specified when embedding the root element in sl:XMLContent.

Note: For the parsing of the XML document containing the signature to be verified, see the Recommendation in section 2.2.1.

Furthermore, with sl:SignatureLocation, sl:SignatureInfo contains an expression according to [XPath] which is to specify the position of the signature to be verified within the XML document specified with sl:SignatureEnvironment. The document node of the XML document specified in sl:SignatureEnvironment is to be used as a context node for evaluating the XPath expression. If name space prefixes are used in the XPath expression, the relevant name space declarations must be known in the context of the sl:SignatureLocation element.

Supplementary objects

As an option, supplementary objects can be transmitted in the request. These are data objects referenced within the signature structure. Examples are:

Meta information (sl:MetaInfo) may be specified for a supplementary object (sl:Supplement) (mime type and a reference to a description of the supplementary object). This is followed by the mandatory details of the content of the (sl:Content) object: The Reference attribute contains the reference to the supplementary object as a URI in precisely the same form in which it would be used by the Citizen Card Environment for resolution purposes. The content of sl:Content represents the supplementary object (see also Note in section 2.2.1, Data object).

If supplementary objects are transmitted in the request, then the Citizen Card Environment must use these instead of resolving the relevant references itself.

Note: It is necessary to specify supplementary objects if the signature structure contains references relative to the signature document.

3.2.2 Response

The response to the request for the verification of a signature in XML format first contains information about the public key of the signatory (sl:SignerInfo). If it was possible to identify an X.509 signatory certificate that corresponds to the public key, then sl:SignerInfo must contain at least the following information:

The question of whether other elements – such as the signatory certificate itself – are returned is a matter for the Citizen Card Environment. If it was not possible to identify an X.509 signatory certificate during verification, the question of which information about the public key is returned is also a matter for the Citizen Card Environment.

Furthermore, the response contains separate results for the cryptographic signature verification (sl:SignatureCheck), for the signature manifest check (sl:SignatureManifestCheck), for the checking of any other manifests (sl:XMLDSIGManifestCheck), and the checking of the signature verification data (sl:CertificateCheck).

All four results have a similar structure: The sl:Code element contains the result of the check in machine-readable form, while the sl:Info element may contain more detailed additional information (see the subsections below).

Verifying the validity of the signature

This check must take place as specified in [XMLDSIG]. This means that both the hash value of every dsig:Reference element, as well as the value of the signature (dsig:SignatureValue) are to be verified. The hash values of the reference elements (dsig:Reference) in any existing manifests (dsig:Manifest) are not to be checked.

If the signature specified in the request has been created in line with this specification, then it contains an etsi:DataObjectFormat signature attribute for every signed data object according to [ETSIXML] with meta information about the relevant data object. These signature attributes can be evaluated by the Citizen Card Environment as necessary.

The following values are defined for the content of the sl:Code element in sl:SignatureCheck:

sl:Code Meaning
0 The hash values and the value of the signature have been verified successfully.
1 An error has occurred while checking the hash value of at least one dsig:Reference of the signature. The value of the signature (dsig:SignatureValue) has not been verified.
2 The hash values have been verified successfully. However an error has occurred while verifying the value of the signature (dsig:SignatureValue).

Optional element sl:Info offers space for any additional information, for example a human-readable plain text interpretation of the check results.

If the previously named element sl:Code contains the value 1, it is also recommended that an sl:FailedReference element should be specified as a child of sl:Info in order to identify the first dsig:Reference element in which the checking of the hash value produced an error. The content of sl:FailedReference, a positive integer, specifies the number of the problematic dsig:Reference within dsig:SignedInfo. Additional sl:FailedReference elements may be specified in order to show errors when checking other dsig:Reference elements.

Checking the signature manifest

If the signature specified in the request has been created in line with this specification, then a dsig:Reference in dsig:SignedInfo must refer to the signature manifest. In such a case the hash value of every dsig:Reference of the signature manifest is to be verified. The checking of the signature verification data may be omitted if an error has occurred while verifying the validity of the signature.

The following values are defined for the content of the sl:Code element in sl:SignatureManifestCheck:

sl:Code Meaning
0

This code has one of the following meanings:

  • This signature does not require a signature manifest.
  • The signature contains a reference to the necessary signature manifest. The scope of the signature manifest meets the requirements of this specification. It has been possible to check the hash value successfully for each dsig:Reference.
1 The signature does not contain a reference to the necessary signature manifest.
2 Although the signature contains a reference to the signature manifest, its scope does not meet the requirements of this specification. The hash values of the dsig:Reference elements contained in the signature manifest were not checked.
3 The signature contains a reference to the signature manifest. The scope of the signature manifest meets the requirements of this specification. However, an error has occurred while verifying the hash value of at least one dsig:Reference of the signature manifest.
99 The signature manifest has not been checked because an error has occurred while verifying the validity of the signature.

Optional element sl:Info offers space for any additional information, for example a human-readable plain text interpretation of the check results.

If the previously named element sl:Code contains the value 3, it is also recommended that one or more sl:FailedReference elements should be specified as children of sl:Info in order to identify all the dsig:Reference elements in which the verification of the hash value produced an error. The content of the relevant sl:FailedReference element, a positive integer, specifies the number of the problematic dsig:Reference within the signature manifest.

Checking other manifests

If the signature to be verified in dsig:SignedInfo contains dsig:Reference elements that refer to conventional manifests according to [XMLDSIG] (i.e. the Type attribute in dsig:Reference is set to the value http://www.w3.org/2000/09/xmldsig#Manifest), the response for each manifest identified in this way must contain an sl:XMLDSIGManifestCheck element with the result of the manifest check. The other manifests do not need to be checked if an error has occurred while verifying the validity of the signature.

The following values are defined for the content of the sl:Code element in sl:XMLDSIGManifestCheck:

sl:Code Meaning
0 It was possible to verify the hash value successfully for every dsig:Reference of the manifest identified with sl:Info.
1 It was not possible to verify the hash value successfully for at least one dsig:Reference of the manifest identified with sl:Info.
99 No other signature manifests have been checked, as an error has occurred while verifying the validity of the signature.

Mandatory element sl:Info offers space for any additional information (not specified here), for example a human-readable plain text interpretation of the check results.

If the previously named element sl:Code contains the value 1, then, in addition one or more sl:FailedReference elements must be specified as children of sl:Info to identify all the dsig:Reference elements of the manifest in which an error occurred when checking the hash value. The content of the relevant sl:FailedReference element, a positive integer, specifies the number of the problematic dsig:Reference within the signature manifest.

Furthermore, a specification must be included in sl:Info by means of the sl:ReferringSignatureReference element, indicating to which manifest referenced in the signature the check results relate. The content of sl:ReferringSignatureReference, a positive integer, specifies the number of the dsig:Reference within dsig:SignedInfo that refers to the manifest.

Checking the signature verification data

This involves constructing the certificate chain, from the signatory certificate to a trustworthy root certificate, and a status check for every certificate in the constructed certificate chain. The checking of the signature verification data may be omitted if an error has occurred while verifying the validity of the signature.

If the signature specified in the request has been created in line with this specification, then it contains an etsi:SigningCertificate signature attribute according to [ETSIXML] with information about the signatory certificate. In such a case, this information must be used by the Citizen Card Environment as the starting point for constructing the certificate chain.

When older signatures are verified, it can happen that no more online information is provided by the certification service provider who issued the signatory certificate to enable the certificate chain to be constructed or the status of the certificates in this chain to be checked. To be able to verify such signatures nonetheless, it is recommended that the Citizen Card Environment should evaluate any existing unsigned etsi:CompleteCertificateRefs, etsi:CompleteRevocationRefs, etsi:CertificateValues and etsi:RevocationValues signature attributes according to [ETSIXML].

For the defined values for the content of the sl:Code element in sl:CertificateCheck see the subsection entitled Checking the signature verification data in the section relating to the [CMS] signature verification.

Note: For examples of this command see the Tutorial; for user interface requirements see User interface requirements, section 3.2.

4 Encryption

The commands specified in this section are used to encrypt a document (or multiple documents, depending on the message format) announced to the Citizen Card Environment. Encryption takes place on the basis of recipients using a public key specified by the application.

4.1 Encryption as a CMS message

This command is used to encrypt data as a CMS message with EnvelopedData content according to the [CMS] standard.

4.1.1 Request

The request first contains a public key (sl:RecipientPublicKey) for each recipient for whom the data is to be encrypted. The public key is contained in sl:RecipientPublicKey as a base64-coded X.509 certificate (sl:X509Certificate).

Furthermore, the data to be encrypted and meta information relating to this data is announced with sl:ToBeEncrypted.

The meta information to be specified must include the mime type (see [MIME]) of the data to be encrypted (sl:ToBeEncrypted/sl:MetaInfo/sl:MimeType); this information is required by the Citizen Card Environment for the possibly necessary display of the data to be encrypted. A verbal description of the data object may also be included (sl:ToBeEncrypted/sl:MetaInfo/sl:Description).

Two options are available for specifying the actual data to be encrypted:

The sl:EncryptCMSRequest/@ReturnBinaryResult attribute can be specified as an option in order to control the type of response to the request (cf. section 4.1.2 Response)

4.1.2 Response

The Citizen Card Environment uses the information in the request to create a CMS message with EnvelopedData as content. It must contain the following specifications:

The CMS message created in this way is returned by the Citizen Card Environment in the response. The basic structure of the response depends on the sl:EncryptCMSRequest/@ReturnBinaryResult attribute of the request.

4.1.2.1 XML response

If the sl:EncryptCMSRequest/@ReturnBinaryResult attribute is either not set or set to false, the Citizen Card Environment returns an XML response.

sl:EncryptCMSResponse/sl:CMSMessage contains the CMS message generated in base64-coded form.

4.1.2.2 Binary response

If, in contrast, the sl:EncryptCMSRequest/@ReturnBinaryResult attribute is set to true, the Citizen Card Environment does not return an XML response, but instead returns the CMS message directly and without further encoding as a response to the request.

If the transport protocol allows the mime type to be specified, then the Citizen Card Environment must set the mime type to application/pkcs7-mime; smime-type=enveloped-data.

Note: For examples of this command see the Tutorial; for user interface requirements see User interface requirements, section 3.3.

4.2 Encryption as an XML document

This command is used to encrypt data as an XML document according to the [XMLEnc] standard.

4.2.1 Request

The request first contains a public key (sl:RecipientPublicKey) for each recipient for whom the data is to be encrypted. The public key is contained in sl:RecipientPublicKey either directly (ds:KeyValue) or as a base64-coded X.509 certificate (sl:X509Certificate).

Furthermore, the data to be encrypted is announced with sl:ToBeEncrypted. This element must exist at least once and contains information about the data to be encrypted in one of three possible ways:

sl:EncryptionInfo can be used to provide information about an existing XML document in which the generated elements (xenc:EncryptedData) are to be inserted (see above). If sl:EncryptionInfo is not specified, then the request may only contain a single element – sl:ToBeEncrypted; the content of this single element must be sl:New.

The XML document is specified with sl:EncryptionInfo/sl:EncryptionEnvironment. Three options are available: If the XML document is to be referenced and if this reference is to be resolved by the Citizen Card Environment, then the sl:EncryptionEnvironment/@Reference attribute must be used. In this case, the content of sl:EncryptionEnvironment remains empty. If the XML document is to be specified explicitly, then either sl:Base64Content or sl:XMLContent is to be used as the content for sl:EncryptionEnvironment; in this case, the sl:EncryptionEnvironment/@Reference attribute remains empty. sl:Base64Content contains the XML document in base64-coded form. sl:XMLContent contains the XML document directly.

If the sl:EncryptionInfo/sl:EncryptedKeyLocation element is specified, the Citizen Card Environment must group together the information about all public keys of the recipients (sl:RecipientPublicKey) specified in the request in one or more xenc:EncryptedKey elements which must be referenced from all generated xenc:EncryptedData elements (for more detailed information on the structure of xenc:EncryptedKey or on referencing see Response). sl:EncryptedKeyLocation/@ParentSelector selects the parent element of the xenc:EncryptedKey element(s) to be inserted. sl:EncryptedKeyLocation/@NodeCount contains a specification indicating the node number at which the first xenc:EncryptedKey element must be inserted in the parent element; counting starts at zero. Any further xenc:EncryptedKey elements must be inserted after the first element.
If the element is not specified, the Citizen Card Environment must encode the information about all public keys of the recipients specified in the request in each individually created xenc:EncryptedData element directly as xenc:EncrpytedKey (for more detailed information on the structure of xenc:EncryptedKey see Response).

In addition, supplementary objects (sl:EncryptedInfo/sl:Supplement) that are linked with the existing XML document can be specified.

For example, the XML document specified in sl:EncryptionEnvironment could contain a reference to the document type definition. The document referenced in this way can be transmitted by the application as a supplementary object if the Citizen Card Environment shall not resolve the reference itself, or if the Citizen Card Environment cannot resolve the reference, for example because it is a relative reference relating to the XML document.

Another example of the use of a supplementary object might be an XML schema, which is referenced in the XML document specified with sl:EncryptionEnvironment using the mechanisms suggested in [XML schema].

A supplementary object consists of optional meta information (cf. sl:FinalDataMetaInfo in section 2.2.1, Transformation paths) on the one hand, and the actual data (sl:Content) on the other: The sl:Content/@Reference attribute, which must be used, contains the reference to the supplementary data as URI in the form in which it would be used by the Citizen Card Environment for resolution purposes. The content of sl:Content represents the supplementary data (see also Note in section 2.2.1, Data object).

4.2.2 Response

The Citizen Card Environment must create an xenc:EncryptedData element for each of the instructions contained in the request for encrypting data (sl:ToBeEncrypted). The following conditions must be met:

If an XML document was specified in the request (sl:EncryptionInfo/sl:EncryptionEnvironment), the Citizen Card Environment must return this XML document with the following modifications in the response as the content of sl:EncryptXMLResponse/sl:EncryptionEnvironment:

If an XML document was not specified in the request, the Citizen Card Environment must return the xenc:EncryptedData element created for the new content to be encrypted (sl:ToBeEncrypted/sl:New), specified in the request, as the content of sl:EncryptXMLResponse/sl:EncryptionEnvironment.

If the Citizen Card Environment cannot perform encryption for at least one date contained in the request (sl:ToBeEncrypted), then the Citizen Card Environment must return an error response (sl:ErrorResponse).

Note: For examples of this command see the Tutorial; for user interface requirements see User interface requirements, section 3.3.

5 Decryption

The commands described in this section are used to decrypt a document sent to the Citizen Card Environment in encrypted form using a private key administered in the Citizen Card Environment.

5.1 Decrypting a CMS message

This command is used to decrypt CMS messages with EnvelopedData content (as set out in the [CMS] standard). The decryption key must be a private key which is administered by the Citizen Card Environment.

5.1.1 Request

The sl:DecryptCMSRequest request in the sl:CMSMessage element first contains the CMS message with EnvelopedData content to be decrypted.

As an option, specifications can be made in relation to the data encrypted in EnvelopedData in the sl:EncryptedContent element:

When it comes to the identification of the data encryption key, the Citizen Card Environment can assume the following requirements that must be met by the application:

For detailed information about which algorithms and URL protocols a Citizen Card Environment must encompass in the context of the decryption of a CMS message, see Minimum implementation of the Security Layer, section 6.2.

The sl:DecryptCMSRequest/@ReturnResult attribute can be specified as an option in order to control the type of response to the request (cf. section 5.1.2 Response).

5.1.2 Response

The basic structure of the response depends on the sl:DecryptCMSRequest/@ReturnResult attribute of the request.

5.1.2.1 XML response

If the sl:DecryptCMSRequest/@ReturnResult attribute is either not set or set to xml, the Citizen Card Environment returns an XML response.

sl:DecryptCMSResponse/sl:DecryptedData contains the data decrypted using the key pair identified in the CMS message and contained in the Citizen Card Environment in base64-coded form.

5.1.2.2 Binary response

If, in contrast, the sl:DecryptCMSRequest/@ReturnResult attribute is set to binary, the Citizen Card Environment does not return an XML response, but instead returns the decrypted data directly and without further encoding as a response to the request.

If the transport protocol allows the mime type to be specified, then the Citizen Card Environment must use the specifications contained in the request (sl:EncryptedContent/sl:MetaInfo/sl:MimeType).

5.1.2.3 Empty response

If the sl:DecryptCMSRequest/@ReturnResult attribute is set to none, the Citizen Card Environment returns an empty response (sl:DecryptCMSResponse element without content). This option allows citizens to view the decrypted data via the user interface and/or to save it, without it subsequently being sent to the application.

Note: For examples of this command see the Tutorial; for user interface requirements see User interface requirements, section 3.4.

5.2 Decrypting an XML document

This command is used to decrypt XML documents which are either encrypted in part or in full according to the [XMLEnc] standard. The decryption key must be a private key which is administered by the Citizen Card Environment.

5.2.1 Request

The sl:DecryptXMLRequest request first contains information about the XML document encrypted according to [[XMLEnc] in the sl:EncryptedContent element. This document to be decrypted can either be referenced by specifying a URL or can be embedded directly in the command:

In principle, the XML document to be decrypted may contain any number of elements with encrypted content (xenc:EncryptedData). The sl:EncrElemsSelector element is to be used to specify which of these encrypted elements is actually to be decrypted by the Citizen Card Environment. The content of the sl:EncrElemsSelector element specifies an expression according to [XPath], whose evaluation must yield a set of nodes with any number of xenc:EncryptedData elements. The Citizen Card Environment must use the document node of the XML document to be decrypted as a context node for the evaluation of the expression.

When it comes to the identification of the data encryption key, the Citizen Card Environment can assume the following requirements that must be met by the application:

For detailed information about which algorithms, key information and URL protocols a Citizen Card Environment must encompass in the context of the decryption of an XML document, see Minimum implementation of the Security Layer, section 7.2.

Supplementary objects (sl:Supplements) can be specified as an option; these are data objects referenced within the encryption document. Examples are:

Meta information (sl:MetaInfo) may be specified for a supplementary object (sl:Supplement) (mime type and a reference to a description of the supplementary object). This is followed by the mandatory details of the content of the (sl:Content) object: The Reference attribute contains the reference to the supplementary object as a URI in precisely the same form in which it would be used by the Citizen Card Environment for resolution purposes. The content of sl:Content represents the supplementary object (see also Note in section 2.2.1, Data object). If supplementary objects are transmitted in the request, then the Citizen Card Environment must use these instead of resolving the relevant references itself.

Note: It is necessary to specify supplementary objects if the signature document contains relative references.

The sl:DecryptXMLRequest/@ReturnResult attribute can be specified as an option in order to control the type of response to the request (cf. section 5.2.2 Response).

5.2.2 Response

The basic structure of the response depends on the sl:DecryptXMLRequest/@ReturnResult attribute of the request.

5.2.2.1 XML response

If the sl:DecryptXMLRequest/@ReturnResult attribute is either not set or set to xml, the Citizen Card Environment returns an XML response.

sl:DecryptXMLResponse/sl:CandidateDocument contains the XML document that was transmitted to the Citizen Card Environment in the request either using a reference or in directly embedded form. Here, however, all those encrypted elements that meet the following conditions (xenc:EncryptedData) are replaced by their decrypted contents:

Cascaded encryption elements are not dealt with any further by the Citizen Card Environment, in other words, if the decrypted content of an encryption element in turn contains encryption elements, these are not decrypted.

If sl:DecryptXMLRequest/@EncrElemsSelector also selects encryption elements whose type (xenc:EncryptedData/@Type) either has not been specified or is neither http://www.w3.org/2001/04/xmlenc#Element nor http://www.w3.org/2001/04/xmlenc#Content, the relevant decrypted contents do not replace the encryption elements in the XML document, but are returned as separate elements sl:DecryptXMLResponse/sl:DecryptedBinaryData:

If it is not possible to decrypt even a single encryption element selected with sl:DecryptXMLRequest/sl:EncrElemsSelector, the Citizen Card Environment must return an error response (sl:ErrorResponse). If the evaluation of the XPath in sl:DecryptXMLRequest/sl:EncrElemsSelector returns an empty node set, the Citizen Card Environment must return the unchanged XML document of the request.

5.2.2.2 Binary response

If, in contrast, the sl:DecryptXMLRequest/@ReturnResult attribute is set to binary, the Citizen Card Environment does not return an XML response, but instead returns binary data directly. In order to determine this binary data, the Citizen Card Environment proceeds as follows:

If the encryption element to be investigated cannot be decrypted or if the evaluation of the XPath in sl:DecryptXMLRequest/@EncrElemsSelector returns an empty set of nodes, the Citizen Card Environment must return an error response (sl:ErrorResponse).

5.2.2.3 Empty response

If the sl:DecryptXMLRequest/@ReturnResult attribute is set to none, the Citizen Card Environment returns an empty response (sl:DecryptXMLResponse element without content). This option allows citizens to view the decrypted data via the user interface and/or to save it, without it subsequently being sent to the application.

Note: For examples of this command see the Tutorial; for user interface requirements see User interface requirements, section 3.4.

6 Hash values

6.1 Hash value calculation

This command is used to calculate hash values for one or more data objects specified in the request.

6.1.1 Request

The sl:CreateHashRequest request element contains an element, sl:HashInfo, consisting of the elements sl:HashData, sl:HashAlgorithm and (optional) sl:FriendlyName for each data object for which the Citizen Card Environment is to calculate a hash value.

The application uses sl:HashData to specify either a location from which the Citizen Card Environment is to call up the data to be hashed (using the sl:Content/@Reference attribute, content remains empty), or it specifies the data to be hashed directly (the sl:Content/@Reference attribute is not used, content is either sl:Content/sl:Base64Content or sl:Content/@sl:XMLContent).

The meta information to be specified must include the mime type (see [MIME]) of the data to be hashed (sl:HashData/sl:MetaInfo/sl:MimeType); this information is required by the Citizen Card Environment for the possibly necessary display of the data to be hashed. A verbal description of the data object may also be included (sl:HashData/sl:MetaInfo/sl:Description).

If sl:XMLContent is used to directly specify the data to be hashed, the Citizen Card Environment must convert the XML content into a sequence of bytes using canonicalisation according to [C14N] and must then add this to the actual hash calculation. Before canonicalisation, the Citizen Card Environment must separate the XML content from the context of the request element.

The application uses sl:HashAlgorithm to select the hash algorithm according to which the Citizen Card Environment is to calculate the hash value. The application can use sl:FriendlyName to assign a name to the data to be hashed that will be easy for citizens to understand. If necessary, this name is used by the Citizen Card Environment on the user interface to name the data to be hashed.

The sl:HashInfo/@RespondHashData attribute indicates whether the sl:HashData element is returned in the response element.

Note: The algorithms for calculating hash values to be supported by a Citizen Card Environment are specified in Minimum implementation of the Security Layer, section 8.

6.1.2 Response

The sl:CreateHashResponse response element contains an element, sl:HashInfo, consisting of the elements sl:HashData (optional), sl:HashAlgorithm, sl:FriendlyName (optional) and sl:HashValue for each data object for which a hash value was to be formed.

The first three elements correspond precisely to those from the corresponding sl:HashInfo of the request; the sl:HashData element only appears if the RespondHashData attribute in the corresponding sl:HashInfo of the request contains the value true. The sl:HashValue element contains the hash value calculated by the Citizen Card Environment for the data specified in the request with sl:HashInfo; this hash value is in base64-coded form.

Note: For examples of this command see the Tutorial; for user interface requirements see User interface requirements, section 3.5.

6.2 Hash value verification

This command is used to verify hash values for one or more data objects specified in the request.

6.2.1 Request

The sl:VerifyHashRequest request element contains an element, sl:HashInfo, consisting of the elements sl:HashData, sl:HashAlgorithm, (optional) sl:FriendlyName and sl:HashValue for each data object for which the Citizen Card Environment is to verify a hash value calculated for the relevant data object.

The application uses sl:HashData to specify either a location from which the Citizen Card Environment is to call up the data used to calculate the hash value to be verified (using the sl:Content/@Reference attribute, content remains empty), or it specifies this data directly (the sl:Content/@Reference attribute is not used, content is either sl:Content/sl:Base64Content or sl:Content/sl:XMLContent).

The meta information to be specified must include the mime type (see [MIME]) of the hash data to be verified (sl:HashData/sl:MetaInfo/sl:MimeType); this information is required by the Citizen Card Environment for the possibly necessary display of the hash data to be verified. A verbal description of the data object may also be included (sl:HashData/sl:MetaInfo/sl:Description).

If sl:XMLContent is used for direct specification, the Citizen Card Environment must convert the XML content into a sequence of bytes using canonicalisation according to [C14N] and must then add this to the actual hash verification. Before canonicalisation, the Citizen Card Environment must separate the XML content from the context of the request element.

The application uses sl:HashAlgorithm to specify the hash algorithm according to which the hash value to be verified has been calculated for the data specified with sl:HashData.

It can use sl:FriendlyName to give the data object for which the hash value is to be verified a name that citizens will understand. If necessary, this name is used by the Citizen Card Environment on the user interface to name the data object.

sl:HashValue contains the hash value to be verified.

6.2.2 Response

The sl:VerifyHashResponse response element contains a corresponding sl:VerificationResult element for each hash value submitted in the request element for verification. This sl:VerificationResult element may contain the sl:FriendlyName element specified in the corresponding sl:HashInfo of the request and the result of the hash value verification in sl:Result. If the Citizen Card Environment was able to verify the hash value specified in the corresponding sl:HashInfo of the request (i.e. calculating the identical hash value from the specified data according to the specified hash algorithm), then sl:Result contains the value true, or otherwise false.

Note: For examples of this command see the Tutorial; for user interface requirements see User interface requirements, section 3.6.

7 Access to info boxes

The Citizen Card Environment provides the application with data storage that is logically divided into so-called info boxes. An info box should be regarded as a data container for a set of related data.

In physical terms, such info boxes can be located either directly on the Citizen Card token or at another location controlled by the Citizen Card Environment; for example on the hard disk of the local host on which the Citizen Card Environment is running. However, this division is not apparent to the application; it is only familiar with the logical view of the info box as a data container in the Citizen Card Environment.

It is a matter for the Citizen Card Environment to take suitable steps to prevent access to data in an info box as necessary. In the case of data stored on the Citizen Card token, the security mechanisms available there (PIN, key) can be used. Similar mechanisms are also conceivable to protect sensitive data administered by the Citizen Card Environment on the hard disk.

The Security Layer interface offers the following commands for accessing data in info boxes:

Note: For examples of this command see the Tutorial; for user interface requirements see User interface requirements, section 3.7.

7.1 Types of info boxes

The two different types containing an info box are defined below.

7.1.1 Binary file

A binary file should largely be seen as a sequence of bytes that can be read or written in their entirety by means of the Security Layer. There is no provision for the reading or writing of a partial sequence of bytes in the binary file.

Reading parameters and response data

A binary file can only be read in its entirety. For this reason, no parameters are transmitted in the read request (see section 7.3.1) and the parameter element sl:BinaryFileParameters remains empty. However, the application can use the Boolean attribute sl:ContentIsXMLEntity in sl:BinaryFileParameters to inform the Citizen Card Environment whether the data stored in the binary file can be interpreted as XML.

The format in which the data is delivered to the read request (see section 7.3.2) depends on the sl:ContentIsXMLEntity attribute in the read request. If this attribute has been set to true, then sl:BinaryFileData contains the content of the binary file as parsed XML (as children of sl:XMLContent), otherwise it is in base64-coded form (sl:Base64Content).

Update parameters and response data

Because a binary file can only be changed in its entirety, the update request is to be specified as the only parameter of the entire new content of the info box, either in base64-coded form (sl:BinaryFileParameters/sl:Base64Content), or as parsed XML (sl:BinaryFileParameters/sl:XMLContent). When data is coded as XML, the xml:space attribute can be assigned the value preserve for sl:XMLContent if it is important from the perspective of the application that the Citizen Card Environment does not change white space within the transmitted XML.

No data is returned in the corresponding response to the update request (see section 7.4.2).

7.1.2 Associative array

An associative array should be seen as a set of keys, where every key is assigned a corresponding value. One major restriction is that all key pairs must always be different. A key is always an XML string, while there are no restrictions for the assigned value.

Read parameters and response data

An associative array can be accessed in three different ways:

Reading keys

The first read (sl:ReadKeys in sl:AssocArrayParameters) returns a set of keys that correspond to a specified search string (SearchString attribute in sl:Readkeys). Several keys are possible as a result because a wildcard * can be specified in the search string. This wildcard stands for any sequence of characters, except for /. Several wildcards can occur in the same search string, however, the / character must occur at least once between two wildcards. The value ** is to be specified as the search string for selecting all available keys.

If the sl:ReadKeys/@UserMakesUnique attribute is also specified, then the citizen must use the user interface of the Citizen Card Environment to select exactly one key from the set of keys found with the specified search string. This key selected by the citizen is then to be returned as the only key in the response. If the set of keys found with the specified search string is empty, the Citizen Card Environment must behave as if the sl:ReadKeys/@UserMakesUnique attribute had not been specified. For more detailed information about the requirements placed on the user interface see User interface requirements.

Note: This model for using a wildcard was chosen to facilitate the emulation of multi-dimensional arrays by the associative array. Thus, for example, a two-dimensional array could be mapped by keys in the form <Number> '/' <Number>. The 1/* search string could then be used to read out all values from the first row.

The response data contains the keys found (sl:Key elements in sl:AssocArrayData).

Reading keys and values

The second read access (sl:ReadPairs element in sl:AssocArrayParameters) is similar to the first, however not only are the keys that correspond to the search expression (SearchString attribute in sl:ReadPairs) returned as a result, but the value assigned to each key is also returned.

If the sl:ReadPairs/@UserMakesUnique attribute is also specified, then the citizen must use the user interface of the Citizen Card Environment to select exactly one key from the set of keys found with the specified search string. This key selected by the citizen is then to be returned together with the corresponding value as the only key in the response. If the set of keys found with the specified search string is empty, the Citizen Card Environment must behave as if the sl:ReadPairs/@UserMakesUnique attribute had not been specified. For more detailed information about the requirements placed on the user interface see User interface requirements.

As with the read parameters for a binary file (see section 7.1.1, Read parameters and responses) the application can use the Boolean attribute ValuesAreXMLEntities in the sl:ReadPairs element of the Citizen Card Environment to indicate whether the values assigned to the sought keys can be interpreted as XML. If not all values can be interpreted as XML, the attribute must not be set to true.

The response data (sl:AssocArrayData) contains the key/value pairs found (sl:Pair elements). sl:Pair contains the key as Key attribute and the associated value as parsed XML (sl:XMLContent) or base64-coded data (sl:Base64Content). The encoding of the values depends on the ValuesAreXMLEntities attribute discussed above. All values are either coded as parsed XML or as base64.

Reading the value for a key

The third read access (sl:ReadValue element in sl:AssocArrayParameters) allows the value assigned to a specified key (Key attribute in sl:ReadValue) to be read. As when reading keys and values, the application can also use the Boolean attribute ValueIsXMLEntity in the sl:ReadValue element of the Citizen Card Environment to indicate whether the value to be read out can be interpreted as XML.

The response data (sl:AssocArrayData) contains the specified keys (Key attribute in sl:Pair) and the associated value (content of sl:Pair). The encoding of the value depends on the attribute discussed above (ValueIsXMLEntity). It is coded either as parsed XML (sl:XMLContent) or as base64 (sl:Base64Content).

Update parameters and response data

There are three different update requests for an associative array:

Changing a key

The first request (sl:UpdateKey element in sl:AssocArrayParameters) allows the key of a key/value pair stored in the associative array to be changed. The current key (Key) and the new key (NewKey) are to be specified as attributes in sl:UpdateKey.

Changing a value

The second request (sl:UpdateValue element in sl:AssocArrayParameters) can be used to change the value of a key/value pair stored in the associative array. The key of the association to be changed (Key attribute) and the new value (content of sl:UpdateValue) are to be specified in sl:UpdateValue. If there is no entry in the associative array for the specified key, a new entry is added with the specified key and value.

The statements made in section 7.1.1, Update parameters and response data apply in relation to the encoding of the value.

Deleting a key/value pair

The third possible request (sl:DeletePair element in sl:AssocArrayParameters) allows a key/value pair to be deleted from the associative array. For this purpose, the key of the pair must be specified as the Key attribute in sl:DeletePair.

No data is returned in the corresponding response to all three possible update requests (see section 7.4.2).

7.2 Requesting available info boxes

This command is used to give the application information from the Citizen Card Environment about which info boxes are available for access purposes.

7.2.1 Request

This request is an empty command without parameters.

7.2.2 Response

The response contains a list of identifiers (sl:InfoboxIdentifier elements). Each identifier corresponds to an info box available to the application for access purposes. The identifiers are used to identify the info box in the commands described below for reading or changing data in an info box.

7.3 Creating an info box

This command is used to create an info box by means of the application.

7.3.1 Request

The sl:InfoboxCreateRequest request element first contains two elements, sl:InfoboxIdentifier and sl:InfoboxType. sl:InfoboxIdentifier indicates the identifier under which the info box to be created is to be available in the future, while sl:InfoboxType specifies the type of info box to be created (either BinaryFile for a binary info box or AssocArray for an associative field).

Two more obligatory elements follow: sl:Creator contains free text information about the operator of the application that wishes to create this info box. sl:Purpose also provides free text information about the purpose the info box meets for the application. Both elements are used by the Citizen Card Environment on the user interface to inform citizens.

The application uses the next two optional elements, sl:ReadAccessAuthorization or sl:UpdateAccessAuthorization, to indicate who is permitted to read or change the info box. Depending on whether the UserMayChange attribute is set to true or false, the Citizen Card Environment must interpret this information as a recommendation (citizen may change the suggested rights) or provision (citizen may not change the suggested rights). If either of the two elements is missing, it is up to the citizen to assign the relevant access rights. For more detailed information about the requirements placed on the user interface see User interface requirements.
Each of the two elements contains one or more sl:RequesterID elements. The content of sl:RequesterID is a pattern either for domain names or IP addresses for identifying the application with access rights. For domain names, a single specification of a wildcard * for one or more subdomains is allowed at the start of the pattern (e.g. * or *.gv.at or *.cio.gv.at, but not *io.gv.at), whereas for IP addresses, a single specification of a wildcard * for one or more bytes of the IP address is allowed at the end of the pattern (e.g. 193.170.* or 193.170.251.*, but not 193.170.25*). The AuthenticationClass attribute indicates how strictly the Citizen Card Environment must check this identification. Possible values for this attribute are anonym, pseudoanonym, certified and certifiedGovAgency. For detailed information about the significance of these authentication classes see Access protection, section 2.1.
A particular domain name or IP address must be checked against the specified pattern by the Citizen Card Environment in accordance with the sequence of the specified elements sl:RequesterID. If, for example, the patterns *.gv.at and *.cio.gv.at are specified in this sequence, the domain name www.cio.gv.at matches the pattern *.gv.at because this occurs in sequence before *.cio.gv.at.

Finally, the application can use the last two optional elements (sl:ReadUserConfirmation and sl:UpdateUserConfirmation) to indicate how the citizen must confirm a read or write access to the info box. Depending on whether the UserMayChange attribute is set to true or false, the Citizen Card Environment must interpret this information as a recommendation (citizen may change the suggested information) or provision (citizen may not change the suggested information). If either of the two elements is missing, it is up to the citizen to assign the relevant access rights. For more detailed information about the requirements placed on the user interface see User interface requirements.
Either of the two elements can contain one of the four values none, info, confirm or confirmWithSecret as text content. none means that the citizen does not need to confirm access to the info box; info means that the citizen must be informed of successful access via the user interface (e.g. as log entry); confirm means that the citizen must confirm access permission via the user interface; in the case of confirmWithSecret, the citizen must grant access permission by entering a password via the user interface.

7.3.2 Response

The sl:InfoboxCreateResponse response element is empty and confirms the successful creation of the info box.

7.4 Deleting an info box

This command is used to delete an info box by means of the application.

7.4.1 Request

The sl:InfoboxDeleteRequest request element only contains the sl:InfoboxIdentifier element; the content of this element identifies the info box to be deleted.

7.4.2 Response

The sl:InfoboxDeleteResponse response element is empty and confirms the successful deletion of the info box.

7.5 Reading data from an info box

This command allows the application to read data contained in an info box.

7.5.1 Request

The sl:InfoboxReadRequest request contains the identifier for the info box whose content is to be read (sl:InfoboxIdentifier element). The application can request the identifiers for all available info boxes with the sl:InfoboxAvailableRequest command.

Furthermore, depending on the info box type, box type-specific parameters must be specified for the read request; for a binary info box using the sl:BinaryFileParameters element, for an associative array using the sl:AssocArrayParameters element. For further information about the box type-specific parameters see section 7.1.

Box type-specific parameters can also be specified as an option; these are parameters that only make sense in the context of a very particular info box. The sl:BoxSpecificParameters element is used for this; any mix of text and elements is permitted as the content of this element.

Note: The definition of the box-specific parameters for the info boxes standardised in the Citizen Card concept can be found in the document entitled Standardised key and info boxes.

7.5.2 Response

The response consists of the requested data for the designated info box. For more information about this data, which depends on the type of info box and the type of read request, see section 7.1.

7.6 Changing data in an info box

This command allows the application to change data in an info box.

7.6.1 Request

The sl:InfoboxUpdateRequest request contains the identifier for the info box whose content is to be read (sl:InfoboxIdentifier element). The application can request the identifiers for all available info boxes with the sl:InfoboxAvailableRequest command.

Furthermore, depending on the info box type, box type-specific parameters must be specified for the update request; for a binary info box using the sl:BinaryFileParameters element, for an associative array using the sl:AssocArrayParameters element. For further information about the box type-specific parameters see section 7.1.

Box type-specific parameters can also be specified as an option; these are parameters that only make sense in the context of a very particular info box. The sl:BoxSpecificParameters element is used for this; any mix of text and elements is permitted as the content of this element.

Note: The definition of the box-specific parameters for the info boxes standardised in the Citizen Card concept can be found in the document entitled Standardised key and info boxes.

7.6.2 Response

This request is an empty command without parameters.

8 Requesting properties

Using the Security Layer interface, a number of properties of the Citizen Card Environment and the status of the Citizen Card token can be requested.

Note: For examples of this command see the Tutorial; for user interface requirements see User interface requirements, section 3.8.

8.1 Requesting environment properties

The application may require additional information about the Citizen Card Environment for certain tasks. This command is used to check these properties.

8.1.1 Request

The request consists of the empty element sl:GetPropertiesRequest.

8.1.2 Response

The response consists of the element sl:GetPropertiesResponse and contains the following properties of the Citizen Card Environment as child elements:

8.2 Requesting the token status

The Security Layer allows for the status request of the Citizen Card token used. Possible states are: ready (token available and initialised) or removed (no token available).

8.2.1 Request

If the command, consisting of the element sl:GetStatusRequest, does not contain any parameters, the Citizen Card Environment immediately returns the current status of the Citizen Card token used in the response.

However, as an option, the request can contain the two elements sl:TokenStatus and sl:MaxDelay. In a case like this, sl:TokenStatus indicates the status of the Citizen Card token required by the application and sl:MaxDelay indicates the longest time in seconds by which the Citizen Card Environment may delay the response to this request until the necessary status is attained.

8.2.2 Response

The response consists of the element sl:GetStatusResponse and contains as text of the child element sl:TokenStatus the current status of the token (either ready or removed).

9 Null operation

The null operation is a command to which the Citizen Card Environment responds without requiring any calculations. A parameterless response is sent in reply to a parameterless request.

Note: There is a useful application for this command in the context of authentication with the Citizen Card Environment when the HTTP or HTTPS binding of the Security Layer is used: Authentication is only effective when the Data URL is used; however, in order to be able to work with the data URL, at least an initial command must be sent from the citizen's browser to the Citizen Card Environment that cannot be authenticated in a meaningful way. The null operation can be used for this first command (for further details about the authentication of the application with the Citizen Card Environment compare Access protection for functions of the Citizen Card Environment).

9.1 Request

The application sends the parameterless request, consisting of the sl:NullOperationRequest element, to the Citizen Card Environment.

9.2 Response

The Citizen Card Environment receives the parameterless request and replies to it with a parameterless response, sl:NullOperationResponse.

Note: For examples of this command see the Tutorial; for user interface requirements see User interface requirements, section 3.9.

10 Error handling

If an error arises within the Citizen Card Environment that prevents a correct response to a request, an error response is returned to the application instead of the response belonging to the request.

The data structure of the error response consists of a machine-readable error code (sl:ErrorCode), and of (optional) more detailed information (sl:Info), which is not specified further here. A plain text explanation of the error or an XML structure with further details about the error would be conceivable.

Note: For examples of how errors are handled see Tutorial.

10.1 Error codes

See separate document Error codes of the Security Layer.

11 Glossary

Hash input data
The data used to calculate the hash value for a dsig:Reference. If transformations are specified for the dsig:Reference, this data corresponds to the result of the last transformation. If no transformations are specified, the hash input data is the same as the reference input data.
Implicit transformation parameter
See Description in specification text.
Reference input data
Data yielded from the resolution of the URI specified in the URI attribute of the dsig:Reference. If transformations are specified for the dsig:Reference, this data is used as input data for calculating the first transformation. If no transformations are specified, the reference input data is the same as the hash input data.
Signature manifest
See Description in specification text.

12 References

C14N
Boyer, John: Canonical XML. W3C Recommendation, March 2001. Downloaded from the World Wide Web on 14 May 2004 under http://www.w3.org/TR/2001/REC-xml-c14n-20010315.
CMS
Hously, R.: RFC 3369: Cryptographic Message Syntax (CMS). IETF Request For Comment, August 2002. Downloaded from the World Wide Web on 14 May 2004 under http://www.ietf.org/rfc/rfc3369.txt.
ESS-S/MIME
Hoffman, P.: RFC 2634: Enhanced Security Services for S/MIME. IETF Request For Comment, June 1999. Downloaded from the World Wide Web on 14 May 2004 under http://www.ietf.org/rfc/rfc2634.txt.
ETSIXML
European Telecommunications Standards Institute: ETSI TS 101903: XML Advanced Electronic Signatures (XAdES), v1.2.2. Technical Specification, April 2004. Downloaded from the World Wide Web on 14 May 2004 under http://webapp.etsi.org/exchangefolder/ts_101903v010202p.pdf.
ETSICMS
European Telecommunications Standards Institute: ETSI TS 101733: Electronic Signature Formats, v1.5.1. Technical Specification, December 2003. Downloaded from the World Wide Web on 14 May 2004 under http://webapp.etsi.org/exchangefolder/ts_101733v010501p.pdf.
KEYWORDS
Bradner, S.: RFC 2119: Key words for use in RFCs to Indicate Requirement Levels. IETF Request For Comment, March 1997. Downloaded from the World Wide Web on 14 May 2004 under http://www.ietf.org/rfc/rfc2119.txt.
MIME
Freed, N. and Borenstein, N.: RFC 2046: Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. IETF Request For Comment, November 1996. Downloaded from the World Wide Web on 14 May 2004 under http://www.ietf.org/rfc/rfc2046.txt.
PKCS#12
RSA Laboratories: PKCS#12 v1.0: Personal Information Exchange Syntax, June 1999. Downloaded from the World Wide Web on 14 May 2004 under ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-12/pkcs-12v1.pdf
URI
Berners-Lee, T. , Fielding, R. and Masinter, L.: RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax. IETF Request For Comment, August 1998. Downloaded from the World Wide Web on 14 May 2004 under http://www.ietf.org/rfc/rfc2046.txt.
XML
Bray, Tim, Paoli, Jean, Sperberg-McQueen, C.M. and Maler, Eve: Extensible Markup Language (XML) 1.0 (Second Edition). W3C Recommendation, October 2000. Downloaded from the World Wide Web on 14 May 2004 under http://www.w3.org/TR/2000/REC-xml-20001006.
XMLDSIG
Eastlake, Donald, Reagle, Joseph and Solo, David: XML-Signature Syntax and Processing. W3C Recommendation, February 2002. Downloaded from the World Wide Web on 14 May 2004 under http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/.
XMLEnc
Eastlake, Donald and Reagle, Joseph: XML Encryption Syntax and Processing. W3C Recommendation, December 2002. Downloaded from the World Wide Web on 14 May 2004 under http://www.w3.org/TR/2002/REC-xmlenc-core-20021210/.
XMLTYPE
Murata, M., St.Laurent, S., and Kohn, D.: RFC 3023: XML Media Types. IETF Request For Comment, January 2001. Downloaded from the World Wide Web on 14 May 2004 under http://www.ietf.org/rfc/rfc3023.txt.
XMLNS
Bray, Tim, Hollander, Dave and Layman, Andrew: Namespaces in XML. W3C Recommendation, January 1999. Downloaded from the World Wide Web on 14 May 2004 under http://www.w3.org/TR/1999/REC-xml-names-19990114/.
XPath
Clark, James and DeRose, Steven: XML Path Language. W3C Recommendation, November 1999. Downloaded from the World Wide Web on 14 May 2004 under http://www.w3.org/TR/1999/REC-xpath-19991116.
XML-Schema
Thompson, Henry S., Beech, David, Maloney, Murray and Mendelson, Noah: XML Schema Part 1: Structures. W3C Recommendation, May 2001. Downloaded from the World Wide Web on 14 May 2004 under http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/.

13 History

Date Version Changes
2005-03-01 1.2.2
2004-06-29 1.2.1
2004-05-15
1.2.0
  • Errata 1, 2, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 17, 18, 20 eliminated according to Errata document.
  • Term TrustedViewer replaced with Viewer.
  • New standard name space created for all protocol elements.
  • sl:CreateCMSSignatureRequest:
    • Note inserted about the mime type of the data objects to be signed.
    • ETSI SigningTime property added as a must condition.
  • sl:CreateXMLSignatureRequest:
    • Note inserted indicating how internal URIs for data to be signed are to be interpreted.
    • Data objects can now be explicitly transmitted as URL assignment (in addition to Base64Content and XMLContent).
    • Supplements can now be explicitly transmitted as URL assignment (in addition to Base64Content and XMLContent).
    • Note inserted about the mime type of the data objects to be signed.
    • ETSI etsi:SigningTime property added as a must condition.
  • sl:VerifyXMLSignatureRequest:
    • Supplements can now be explicitly transmitted as URL assignment (in addition to Base64Content and XMLContent).
  • sl:InfoboxReadRequest:
    • Optional, box-specific parameters introduced.
    • Associative array: Optional UserMakesUnique attribute when selecting keys or key/value pairs added.
  • sl:InfoboxUpdateRequest:
    • Optional, box-specific parameters introduced.
    • Associative array: Updating a nonexistent key/value pair means adding the key/value pair.
  • sl:GetPropertiesResponse:
    • sl:KeyBoxIdentifier extended to include two new attributes, Signature and Encryption, which supply information about the usability of the key pair for signature and encryption.
  • CreateSymmetricSecret command removed.
  • NullOperation command introduced.
  • CreateHash and VerifyHash commands introduced.
  • InfoboxCreate and InfoboxDelete commands introduced.
  • Decryption commands (DecryptCMS, DecryptXML) introduced.
2002-08-31
1.1.0
  • sl:CreateCMSSignatureResponse:
    • Recommendation for encoding the certificate chain limited to CertificateSet.
  • sl:VerifyCMSSignatureRequest:
    • Signatories attribute added for specifying the signatures to be verified when several signatories are specified in the CMS signature.
  • sl:VerifyCMSSignatureResponse:
    • Cardinality of the sequence (SignerInfo, SignatureCheck, CertificateCheck) extended to 1..oo in order to support CMS signatures with several signatories.
    • Addition of the recommendation that the Citizen Card Environment should be able to evaluate any existing signature attributes (CompleteCertificateRefs, CompleteRevocationRefs, CertificateValues, RevocationsValues) according to [ETSICMS] for the purpose of verifying older signatures.
    • In the result of the checking of the signature verification data, a distinction is now made between the disabling and revocation of a certificate in the certificate chain (error codes 4 and 5).
    • In the case of the information about the signatory, information is now also returned indicating whether the signatory certificate is qualified.
    • Recommendation for the encoding of the certificate chain changed to the mechanisms of XMLDSIG (X509Data, RetrievalMethod).
  • sl:CreateXMLSignatureRequest:
    • sl:SignatureInfo element added to enable the creation of enveloped signatures.
    • Example corrected accordingly.
  • sl:CreateXMLSignatureResponse:
    • Example changed in accordance with the altered sample request.
  • sl:VerifyXMLSignatureRequest:
    • Grammar for the sl:SignatureEnvironment element generalised so that XML documents with DTDs can also be specified.
    • Description of the supplementary objects generalised.
    • Example corrected in line with the changes in sl:SignatureEnvironment.
  • sl:VerifyXMLSignatureResponse:
    • Expansion of the result for signature verification to include information indicating which references of the signature could not be validated, if any.
    • Expansion of the result for the signature manifest check to show which references of the manifest could not be validated.
    • Introduction of the checking of normal manifests which are referenced in the signature to be verified.
    • Addition of the recommendation that the Citizen Card Environment should be able to evaluate any existing signature attributes (etsi:CompleteCertificateRefs, etsi:CompleteRevocationRefs, etsi:CertificateValues, etsi:RevocationsValues) according to [ETSIXML] for the purpose of verifying older signatures.
    • In the result of the checking of the signature verification data, a distinction is now made between the disabling and revocation of a certificate in the certificate chain (error codes 4 and 5).
    • In the case of the information about the signatory, information is now also returned indicating whether the signatory certificate is qualified.
  • sl:CreateSessionKeyRequest, sl:CreateSessionkeyResponse:
    • Commands removed.
  • sl:GetPropertiesResponse:
    • Cardinalities of the various environment parameters in the schema relaxed to 1..oo so that the name space of the command does not have to be changed when changes are made in the future.
    • ANY placeholder added for future environment parameters so that the namespace of the command does not have to be changed when changes are made in the future.
    • New environment parameter sl:ProtocolVersion added.
2002-08-31
1.0.2
  • Keywords used in accordance with RFC 2119.
  • NS prefix sl added to elements in all descriptions and examples.
  • References added:
    • XML
    • XML namespaces
    • XML schema
    • RFC Keyword
    • Enhanced Security Services for S/MIME.
  • Terminological consistency: Citizen Card Environment instead of Security Capsule, Citizen Card token instead of Citizen Card
  • sl:CreateCMSSignatureRequest:
    • Reference for ContentHints signature attribute changed from [ETSICMS] to [ESS-S/MIME] because this attribute was removed when [ETSICMS] was revised.
  • sl:VerifyCMSSignatureResponse:
    • Procedure for the occurrence of multiple signatories in the CMS signature to be verified made more precise.
    • Reference for ContentHints signature attribute changed from [ETSICMS] to [ESS-S/MIME] because this attribute was removed when [ETSICMS] was revised.
  • sl:CreateXMLSignatureRequest:
    • Procedure for the integration of signed data objects in the case of an "enveloped" structure made more precise.
    • Explicit specification of name space declarations within a transformation chain transmitted in the command (dsig:Transforms) required by the application.
    • Procedure for resolving data during the execution of the transformation process by the Citizen Card Environment made more precise.
  • sl:VerifyXMLSignatureResponse:
    • Meaning of error code 2 made more precise for the signature manifest check.
  • sl:InfoboxUpdateRequest:
    • Typographical error in schema and example corrected (now reads sl:InfoboxIdentifier instead of sl:InfoboxIdentifer).
  • sl:CreateSymmetricSecretRequest, sl:CreateSymmetricSecretResponse:
    • Copy/Paste error in the description of the request corrected.
    • Example of the request corrected.
    • Description of the calculation made more precise.
2002-04-24
1.0.1
  • Reference to the "Requirements for the Citizen Card Environment" specification added to the introduction.
  • Reference to the "Minimum requirements for the Security Layer" document added to the introduction.
  • "AnfBKU" reference added.
  • "ETSICMS" reference to document updated in version 1.3.1.