Open Interfaces for e-Government

The Austrian Citizen Card

Security Layer Application Interface

Document information

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. Batch signatures
1. Signature Bulk-Request
2. Signature Bulk-Response
3. Signature Verification Bulk-Request
4. Signature Verification Bulk-Response
11. Card management
1. Request
2. Response
12. Card channel
1. Request
2. Response
13. Error handling
    1. Error codes
14. Glossary
15. References
16. 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:

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] ([CAdES]) and [XMLDSIG] ([XAdES]).

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. Optionally a range within the data object, that is excluded from the signature(sl:ExcludedByteRange), MAY be specified.

The meta information must always include the mime type (see [MIME]) of the data object to be signed. Finally, any number of other elements may be added to this meta information.

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 [CAdES] 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 [CAdES], section 5.11.5. The (sl:MimeType from 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 ESS signing-certificate signature attribute must be included in the [CMS] signature according to [ESS-S/MIME] if SHA-1 is used for the signature calculation. If other hash algorithms are used, the [CMS] signature MUST include an ESS signing-certificate-v2 attribute for the identification of the signatory certificate that is used to verify the signature.

Timing of the creation of the signature

Finally, a SigningTime signature attribute according to [CMS] 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):

(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:

• sl:Base64Content: This contains the data object in base64-coded form.
• sl:XMLContent: This contains the data object in XML code. If it is important from the perspective of the application that the Citizen Card Environment does not change white space within the transmitted XML, the xml:space attribute for sl:XMLContent can be assigned the preserve value. The content model of sl:XMLContent is defined so that it permits any mix of text and XML mark-up. This also includes pure text. This means, for example, that <sl:XMLContent>Text</sl:XMLContent> is also a valid instance of sl:XMLContent.
• sl:LocRefContent: This contains a reference to the data object that is to be resolved by the Citizen Card Environment in order to obtain the data object.

(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. The Citizen Card Environment may:

1. integrate the base64-decoded data directly in the dsig:Object or
2. integrate the base64-coded data 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. If  Index is -1, the signature is inserted after the last 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 [XAdES]. 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:

• If the implicit transformation parameter is specified as a reference which is to be resolved by the Citizen Card Environment itself, then a distinction is to be made between an external and an internal reference:
  • The resolution of an external reference must return a byte stream. This byte stream forms the input data for calculating the hash.
  • The resolution of an internal reference must return a set of XPath nodes (cf. [XMLDSIG, section 4.3.3.3]). This set of nodes must be canonised according to [C14N] so as to produce a unique byte stream. This byte stream then forms the input data for calculating the hash.
• If the implicit transformation parameter is specified as a reference which is not to be resolved by the Citizen Card Environment itself, because a corresponding supplementary object was specified in the request, then a distinction is to be made between an external and an internal reference:
  • If the supplementary object contains data for an external reference, this data must be available in base64 format (in sl:Supplement/sl:Content/sl:Base64Content). The base64-decoded data then forms the input data for calculating the hash.
  • If the supplementary object contains data for an internal reference, this data must be available as XML (in sl:Supplement/sl:Content/sl:XMLContent). A set of XPath nodes is to be generated from this data according to [XMLDSIG, section 4.3.3.3]. This set of nodes must be canonised according to [C14N] so as to produce a unique byte stream. This byte stream then forms the input data for calculating the hash.

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 [XAdES]. 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 [XAdES]. The Type attribute mentioned in section 6.3.1 must be used.

Note for application developers: Several security layer implementations (CCE implementations) create the required attributes according to [ETSIXML]([XAdES]), version 1.1.1. To ensure compatibility developers should also support signature attributes according to [ETSIXML], version 1.1.1.

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 [XAdES] 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 [XAdES] 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 [XAdES] 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:

• If the signature contains a SigningTime signature attribute according to [CAdES], which contains the time of creation of the signature claimed by the signatory, then the time specified there is to be used as the verification time.
• If there is no such signature attribute, then the time when the verification request reaches the Citizen Card Environment is to be used as 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:

• dsig:SubjectName contains the name of the signatory from the signatory certificate. The element is to be coded as indicated in [XMLDSIG], section 4.4.4. dsig:X509Data must contain such an element.
  
• dsig:IssuerSerial contains the name of the issuer and the serial number of the signatory certificate. The element is to be coded as indicated in [XMLDSIG], section 4.4.4. dsig:X509Data must contain such an element.

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:

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 either an ESS signing-certificate attribute according to [ESS-S/MIME] if SHA-1 was used for the signature calculation; or a signature attribute ESS signing-certificate-v2 according to [RFC 5035] for other hash algorithms that contains informations according to the signatory certificate. Older versions of this specification used the OtherSigningCertficate attribute according to [ETSICMS]. 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 [CAdES].

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

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:

• If the signature contains an etsi:SigningTime signature attribute according to [XAdES], which contains the time of creation of the signature claimed by the signatory, then the time specified there is to be used as the verification time.
• If there is no such signature attribute, then the time when the verification request reaches the Citizen Card Environment is to be used as 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:

• a data object referenced in the URI attribute of a dsig:Reference element of the signature;
• referenced parameters for transformations in a dsig:Reference element of the signature (e.g. a style sheet referenced in the basic style sheet of an XSLT transformation);
• referenced information for validating the document containing the signature (reference in the document type declaration, references to XML schemas using the mechanisms specified in [XML Schema], section 2.6.3);
• referenced information for the location of the certificate used for signature verification (cf. [XMLDSIG], section 4.4.3).

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:

• Precisely one dsig:X509Data element, which in turn must contain at least three elements:
  • dsig:SubjectName contains the name of the signatory from the signatory certificate. The element is to be coded as indicated in [XMLDSIG], section 4.4.4. dsig:X509Data must contain such an element.
    
  • dsig:IssuerSerial contains the name of the issuer and the serial number of the signatory certificate. The element is to be coded as indicated in [XMLDSIG], section 4.4.4. dsig:X509Data must contain such an element.

  • 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 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 [XAdES] 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:

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:

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:

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 [XAdES] 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 [XAdES].

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 Citizen Card Environment shall resolve the data to be encrypted from a specified location: sl:ToBeEncrypted/sl:Content/@Reference contains the relevant URL; sl:ToBeEncrypted remains empty.
• The data to be encrypted is transmitted directly to the Citizen Card Environment: sl:ToBeEncrypted/sl:Content contains the data in base64-coded form; sl:ToBeEncrypted/sl:Content/@Reference is not used.

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:

• A KeyTransRecipientInfo type field is to be created for each public key specified in the request. Thus, Key Transport must always be used as the method for key management.
• The encrypted data is to be integrated in the CMS message using the encryptedContent field (EncryptedContentInfo type). There is no provision for separating message and data.
• The encrypted data is to be identified as data using the contentType field (EncryptedContentInfo type) (see [CMS], section 4).

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:Element: An element of an existing XML document is encrypted by the Citizen Card Environment and is replaced by a corresponding element (xenc:EncryptedData). sl:Element/@Selector contains an expression according to [XPath] which is used to select clearly the specific element to be encrypted within the existing XML document. The context node for evaluating the expression is the document node of the XML document. Name space prefixes used in the expression must be known in the context of sl:Element/@Selector. If sl:Element/@EncDataReference is specified, the encrypted data must not be incorporated by the Citizen Card Environment in base64 code in the relevant element (xenc:EncrpytedData), but instead must be referenced. The URI specified in sl:Element/@EncDataReference must be used as a reference.
  Note: If sl:Element is used, an existing XML document must be specified (see below).
• sl:ElementContent: The content of an element of an existing XML document is encrypted by the Citizen Card Environment and replaced by a corresponding element (xenc:EncryptedData). The significance of the sl:ElementContent/@Selector and sl:ElementContent/@EncDataReference attributes is the same as for the corresponding attributes in sl:Element.
  Note: If this sl:ElementContent is used, an existing XML document must be specified (see below).
• sl:New: Any data arising shall be encrypted and inserted as an xenc:EncryptedData in an existing or new XML document. The location at which the generated xenc:EncryptedData is to be inserted in the XML document is specified using the sl:New/@ParentSelector and sl:New/@NodeCount attributes. sl:New/@ParentSelector selects the parent element of the future xenc:EncryptedData using an expression according to [XPath]; the context node for evaluating the expression is the document node of the XML document. Name space prefixes used in the expression must be known in the context of sl:New/@ParentSelector. sl:New/@NodeCount contains a specification indicating the node number at which xenc:EncryptedData is to be inserted in the parent element; counting starts at zero. The data to be encrypted and meta information is specified as the content of sl:New. The meta information to be specified must include the mime type (see [MIME]) of the data to be encrypted (sl:New/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:New/sl:MetaInfo/sl:Description). Three options are available for specifying the actual data to be encrypted: sl:New/sl:Content/sl:Base64Content contains the data to be encrypted in base64-coded form; this must be decoded by the Citizen Card Environment before encryption takes place. sl:New/sl:Content/sl:XMLContent contains the data to be encrypted as an XML fragment. sl:new/sl:Content/sl:LocRefContent contains a reference that must be resolved by the Citizen Card Environment in order to reach the data to be encrypted. The significance of the sl:New/sl:Content/@EncDataReference attribute is the same as for the corresponding attribute in sl:Element.
  Note: If sl:New is used, but no existing XML document is specified (see below), the Citizen Card Environment must create a new XML document. In this case, sl:New/@ParentSelector must select the document node (e.g. with /), while sl:New/@NodeCount must contain the value 0.

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, according to the request, an element of an existing XML document or the content of such an element is to be encrypted (sl:ToBeEncrypted/sl:Element or sl:ToBeEncrypted/sl:ElementContent), then the xenc:EncryptedData/@Type attribute must be set to http://www.w3.org/2001/04/xmlenc#Element or http://www.w3.org/2001/04/xmlenc#Content. Otherwise, this attribute must not be used.
• One of the algorithms for data encryption listed in Minimum implementation of the Security Layer, section 7.1.1, must be specified in xenc:EncryptedData/xenc:EncryptionMethod.
• The xenc:EncryptedData/ds:KeyInfo element must be used by the Citizen Card Environment; it must reference all public keys for key transport specified in the request, if the sl:EncryptionInfo/sl:EncryptedKeyLocation element was used in the request; otherwise, the xenc:EncryptedData/ds:KeyInfo element must contain these keys.
  If they are contained directly, the Citizen Card Environment must use an xenc:EncrypedKey element in ds:KeyInfo for every public key specified in the request. The following conditions must be met:
  • One of the algorithms for key encryption listed in Minimum implementation of the Security Layer, section 7.2.1.2, must be specified in xenc:EncryptedKey/xenc:EncryptionMethod.
  • The xenc:EncryptedData/ds:KeyInfo element must be used by the Citizen Card Environment in the following way:
  • If xenc:EncryptedKey/xenc:EncryptionMethod contains an algorithm for asymmetric encryption (key transport), then xenc:EncryptedData/ds:KeyInfo MUST contain exactly one ds:KeyValue element with the encoding of the public key.
  • If xenc:EncryptedKey/xenc:EncryptionMethod contains an algorithm for symmetric encryption (symmetric key wrap), then  xenc:EncryptedData/ds:KeyInfo MUST contain exactly one xenc:AgreementMethod element with an algorithm for key agreement from the list defined in Minimum implementation of the Security Layer, section 7.2.1.3
  • xenc:EncryptedData/xenc:CipherData/xenc:CipherValue contains the encrypted symmetrical key for data encryption.
  If referencing is used, the Citizen Card Environment must use a ds:RetrievalMethod element in ds:KeyInfo for each public key specified in the request. The following conditions must be met:
  • The ds:RetrievalMethod/@Type attribute must be set to http://www.w3.org/2001/04/xmlenc#EncryptedKey.
  • The ds:RetrievalMethod/@URI attribute must refer to the referenced xenc:EncryptedKey element.
  • The conditions for direct containment apply to the referenced xenc:EncryptedKey element.
• The xenc:EncryptedData/xenc:CipherData element must reference the data encrypted with the symmetrical encryption key (if, in the relevant sl:ToBeEncrypted element of the request, the EncDataReference attribute in sl:Element, sl:ElementContent or sl:New was set) or must (otherwise) contain it directly.
  If referencing is used, the Citizen Card Environment must use the xenc:CipherData/xenc:CipherReference element. The following conditions must be met:
  • Transformations may not be used.
  • xenc:CipherReference/@URI must be set to the value specified in sl:Element/@EncDataReference or sl:ElementContent/@EncDataReference or sl:New/@EncDataReference.
  • The encrypted data is to be returned in the response in an sl:EncryptedData element. sl:EncryptedData/@EncDataReference must be set to the value specified in sl:Element/@EncDataReference or sl:ElementContent/@EncDataReference or sl:New/@EncDataReference.

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:

• For every XML element to be encrypted specified in the request (sl:ToBeEncrypted/sl:Element), the Citizen Card Environment must replace the specified element of the XML document with the correspondingly created xenc:EncryptedData element.
• For all XML element content to be encrypted specified in the request (sl:ToBeEncrypted/sl:ElementContent), the Citizen Card Environment must replace the content of the specified element of the XML document with the correspondingly created xenc:EncryptedData element.
• For all new content to be encrypted specified in the request (sl:ToBeEncrypted/sl:New), the Citizen Card Environment must insert the correspondingly created xenc:EncryptedData element at the specified position (sl:New/@ParentSelector, sl:New/@NodeCount) in the XML document.
• If the sl:EncryptionInfo/sl:EncryptedKeyLocation element was used in the request, the Citizen Card Environment must insert xenc:EncryptedKey elements for all public keys belonging to the recipients specified in the request at the specified position.

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:

• The application can specify the mime type of the encrypted data in sl:EncryptedContent/sl:MetaInfo/sl:MimeType; this information must be used by the Citizen Card Environment in the case of a binary response to specify the mime type if this is permitted in the transport protocol used.
• In sl:EncryptedContent/sl:Content the application must specify the value of the encryptedContent field (in other words the encrypted data) if this is not contained in the CMS message to be decrypted. It can use either sl:Content/@Reference or slContent/sl:Base64Content for this purpose. sl:Content/@Reference contains a URL that the Citizen Card Environment must resolve in order to access the encrypted data. slContent/sl:Base64Content contains the encrypted data in base64-coded form.

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:

• The public key of a key pair contained in the Citizen Card Environment and suitable for encryption purposes was used to encrypt a symmetrical key with which the actual encryption then took place.
• This public key is identified in the KeyTransRecipientInfo field in the CMS message either by means of a combination of Issuer and SerialNumber or a SubjectKeyIdentifier of the relevant certificate.

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:

• If the XML document to be decrypted is to be referenced, the sl:EncryptedContent/@Reference attribute is to be used for referencing purposes. Reference must be a URL that can be resolved by the Citizen Card Environment. The content of sl:EncryptedContent remains empty.
• If, in contrast, the XML document to be decrypted is to be embedded, this takes place directly as the content of sl:EncryptedContent/sl:Base64Content or sl:EncryptedContent/sl:XMLContent. If the first variant is used, sl:Base64Content contains the base64-coded XML document; in the second variant, sl:XMLContent contains the root element of the XML document as the only node. sl:EncryptedContent/@Reference is not used in either case.

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:

• If direct data encryption was used, then the public key used must be identified in xenc:EncryptedData/ds:KeyInfo with ds:KeyName, ds:KeyValue or ds:X509Data. ds:KeyName must contain the identifier for a key available in the Citizen Card Environment. Identifiers for all available keys can be requested by the Citizen Card Environment using the GetProperties command. ds:KeyValue must contain the public key used for encryption purposes. ds:X509Data must contain precisely one X.509 certificate (ds:X509Certificate) which certifies the public key used for encryption purposes.
• If indirect data encryption was used, then xenc:EncryptedData/ds:KeyInfo must either contain an xenc:EncryptedKey element or at least a ds:RetrievalMethod element that references an xenc:EncryptedKey element. xenc:EncryptedKey must contain the specifications of the symmetrical key used and must identify the key used to encrypt the symmetrical key available in the Citizen Card Environment in ds:KeyInfo in one of the ways mentioned above.
• A public key available in the CCE was used for the agreement of a symmetric key. This symmetric key was then used for the data encryption (key agreement/ indirect encryption). xenc:EncryptedData/ds:KeyInfo MUST contain an element xenc:AgreementMethod, but at least an element ds:RetrievalMethod that references to an xenc:AgreementMethod element. The xenc:AgreementMethod/xenc:RecipientKeyInfo element MUST specify the key (available in the CCE) used for key agreement. 
• A public key available in the CCE was used for the agreement of a symmetric key. This symmetric key was used to encrypt the the symmetric key used for the data encryption(key agreement / symmetric key wrap). xenc:EncryptedData/ds:KeyInfo MUST either contain an element xenc:EncryptedKey or at least an element ds:RetrievalMethod, that references an xenc:EcnryptedKey element. xenc:EcnryptedKey MUST contain an element xenc:AgreementMethod, that uses the element xenc:AgreementMethod/xenc:RecipientKeyInfo, in one of the ways mentioned above, to identify the key (available in the CCE) used for the key agreement.

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:

• encrypted data referenced in an xenc:EncryptedData element;
• an encrypted, symmetrical key referenced in an xenc:EncryptedKey element;
• an xenc:EncryptedKey element referenced in a ds:RetrievalMethod element.

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:

• the encrypted element was selected with sl:DecryptXMLRequest/sl:EncrElemsSelector in the decryption request;
• the type of the encryption element specified in the xenc:EncryptedData/@Type attribute is either http://www.w3.org/2001/04/xmlenc#Element or http://www.w3.org/2001/04/xmlenc#Content.

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:

• sl:DecryptedBinaryData/@EncrElemSelector contains the reference to the corresponding encryption element in the XML document of the request as an expression according to [XPath]; the encryption element must be uniquely selected by this expression, i.e. it must return a set of nodes that contains precisely one xenc:EncryptedData element. The context node for evaluating the expression is the document node of the XML document of the request.
• sl:DecryptedBinaryData/@MimeType contains the mime type of the decrypted data as an option precisely when this has already been specified in the encryption element with xenc:EncryptedData/@MimeType.
• sl:DecryptedBinaryData/@Encoding contains the transport encoding of the decrypted data as an option precisely when this has already been specified in the encryption element with xenc:EncryptedData/@Encoding.
• The content of sl:DecryptedBinaryData consists of the decrypted data in base64-coded form. If the decrypted data is already available in base64-coded form (i.e. if the xenc:EncryptedData/@Encoding attribute of the encryption element has the value http://www.w3.org/2000/09/xmldsig#base64), then it must not be coded in base64 again.

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:

• Only the first encryption element that returns the evaluation of the XPath expression in sl:DecryptXMLRequest/sl:EncrElemsSelector is examined; the order of occurrence in the XML document (document-order) applies.
• The encryption element determined in this way is decrypted; instead of an XML response, the resulting binary data is returned directly and without further encoding as a response to the request.

• If the transport protocol allows the transport encoding or the mime type to be specified, then the Citizen Card Environment must use the specifications that may be contained in the encryption element (xenc:EncryptedData/@MimeType or xenc:EncryptedData/@Encoding).

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:

• Requesting available info boxes
• Reading data in an info box
• Changing data in an info box

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.

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:

• sl:ViewerMediaType: Supported formats of the display: If the display capabilities of the Citizen Card Environment are known, the application can take account of these capabilities in requests for the creation of a signature.
  Note: For viewer formats that are always to be supported by a Citizen Card, see the specification document Minimum implementation of the Security Layer.
• sl:XMLSignatureTransform: Supported transformations for creating/verifying an XML signature: If the transformation support capabilities of the Citizen Card Environment are known, the application can take account of these capabilities in requests for the creation of a signature.
  Note: For transformations that are always to be supported by a Citizen Card, see the specification document Minimum implementation of the Security Layer.
• sl:KeyboxIdentifier: Identifiers for all key pairs available in the Citizen Card Environment at the time of the request: These identifiers are required for all commands whose execution requires the use of a particular key pair by the Citizen Card Environment. For each key pair, a specification indicates whether it is suitable for use in the signature (Signature attribute) or encryption (Encryption attribute) context.
  Note: For key pair identifiers that are always to be supported by a Citizen Card, see the specification document Standardised key and info boxes.
• sl:Binding: Supported bindings to transport protocols: This enables the application to ascertain which transport protocols can be used to address the Citizen Card Environment. An identifier and, as an option, a set of binding-specific parameters are returned for each implemented binding.
  Note: For identifiers and possible parameters see the document entitled Binding to transport protocols. For transport protocols that are always to be supported by a Citizen Card, see the specification document Minimum implementation of the Security Layer.
• sl:ProtocolVersion: Supported protocol versions of the Security Layer: This enables the application to ascertain which protocol versions of the Security Layer are supported by the Citizen Card Environment. The protocol version described by this specification document is 1.2.

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 Batch signatures

Batch signatures are signatures that are independent from each other, based on the same key pair and their creation is triggered by a unique input of the authorization code (PIN). In a bulk request several requests of the same type are combined into one request. Bulk requests are only useful if the combination of several individual request affects the user interaction. In the other cases individual request can be used.

The bulk request contains an optional attribute per individual request that specifies a name that is showed within the citizen card environment.

Bulk requests are answered by bulk responses which MUST contain an individual single response to every request within the bulk request. The assignment of individual responses to requests is based on the order within the bulk request or response. To simplify this assignment and the selection of individual requests/responses within the bulk requests/responses it is possible to specify an id attribute (type xsd:ID) for every individual request. This id is then included in the related response. The order of the individual responses has to accord to the order of the individual requests even if the id attribute is set.

Regarding error handling it has to be distinguished between errors related to the bulk request itself and the individual requests within the bulk request. If an error occurs while handling an individual request within a bulk request, an error response is added at the corresponding position within the bulk response. If the whole bulk request can not be processed correctly an error response with the corresponding error code (3xxx) is sent back instead of a bulk response.

10.1 Signature bulk-request

A Signature bulk-request consists of individual signature requests where CMS and XML types may be mixed. The individual requests MUST specify the same signature key so every request MUST specify the same key box identifier(sl:KeyboxIdentifier). If this is not the case an error response containing the error code 3003 (XML structure of the command request contains an invalid combination of optional elements or attributes.) is returned. 

When executing a bulk request die citizen card environment MUST display a list containing the data to be signed. The citizen card environment MUST offer the possibility to show the individual data to be signed in the same manner as individual signature requests. Entering the PIN code triggers the signature creation for the whole data to be signed. The citizen card environment MAY offer the opportunity to exclude individual data from the signature creation by the citizen. Instead of the signature answer within the bulk response an error response with the error code 6001 (Canceled by the citizen via the user interface.) MUST be returned at the corresponding position within the bulk response.

10.2 Signature bulk-response

The bulk response represents the answer to a bulk request. The order of the individual responses within the bulk response MUST match the order of the individual requests within the bulk request.

10.3 Signature verification bulk-request

A signature verification bulk request contains multiple CMS and XML signature verification requests. Every individual signature result MUST be presented within a list so the user is able to verify the result and the data of every individual signature.

10.4 Signature verification bulk-response

This response represents the answer to a verification bulk request. It contains the ordered individual responses to the requests withing the bulk request.

11 Card management

11.1. Card management request

The request sl:CardManagementRequest contains one or more sl:CardAction entries. The parameter action can contain the following values:

• ActivatePIN: activate the PIN
• ChangePIN: change the PIN
• UnblockPIN:  cancel the PIN block
• ReadPINStatus: read the PIN state

• SecureSignatureApplication
• CertifiedApplication
• InfoboxApplication

11.2. Card management response

The answer sl:CardManagementResponse contains the same sl:CardAction entries as the request. The parameter Result contains the result. The following values are possible:

• OK
• Error
• Blocked: PIN is blocked, to much wrong entries
• Active
• Inactive

12 Card channel

12.1 Card channel request

The entry sl:Script containst the script to be executed on the card. It may contain multiple instances of the following attributes:

• sl:Reset: may contain the optional parameter cold. Executes a warm reset, or if parameter cold is set a cold reset of the card.
• sl:CommandAPDU: contains the parameters sequence and of, and may contain the optional parameter expectedSW. This entry contains teh command-apdu that should be executed on the card. The parameter sequence contains the number of the step within the command and the parameter of contains the total number of steps within the comand. Every sl:CommandAPDU entry MUST contain the same of parameter and MUST include the same number of numbered command entries. The parameter expectedSW can be used to compare the commands resulting status word with the expected one.

12.2 Card channel response

13 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.

14 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.

15 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.

CAdES

European Telecommunications Standards Institute: ETSI TS 101733: Electronic Signatures and Infrastructures (ESI); CMS Advanced Electronic Signatures (CAdES) v2.2.1 , Technical Specification, April 2013

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

RFC 5035

Schaad, J.: RFC 5035: Enhanced Security Services (ESS) Update: Adding CertID Algorithm Agility , IETF Request For Comment, August 2007

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.

XAdES

European Telecommunications Standards Institute: ETSI TS 101903: XML Advanced Electronic Signatures (XAdES), v1.4.2 , Technical Specification, Dezember 2010c

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/.

16 History

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/

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.

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