Skip to end of metadata
Go to start of metadata
DV-OD sequence diagram

This page describes the messages for the interface specification between a Dienstverlener (DV) (service provider) and an Ondertekendienst (OD).

The interface specification described in this document is used to implement the use case GUC6 Ondertekenen (Signing) and MUST be implemented by every Ondertekendienst and offered to their users, the DVs. This is in order to prevent lock-in and enables middleware suppliers to write generic code that can be used by all Herkenningsmakelaars.

In the interface described here, the use case GUC6 Ondertekenen is populated with a DSS 1.0 SignRequest and SignResponse, a SAML 2.0 AuthnRequest and Response and a DSS 1.0 PendingRequest and SignResponse.

See http://docs.oasis-open.org/dss/v1.0/oasis-dss-core-spec-v1.0-os.html and http://docs.oasis-open.org/dss/v1.0/oasis-dss-profiles-asynchronous_processing-spec-v1.0-os.html for relevant DSS specifications.

The specific contents of these messages is described below. A column in a message description that starts with 'SAML:' or 'DSS:' indicates that this is a standard value within the official SAML resp. DSS specification. A value that starts with 'Elektronische Toegangsdiensten' indicates that the value is specific to Elektronische Toegangsdiensten.

 

SignRequest (1)

This paragraph describes the DSS 1.0 SignRequest.

Element/@Attribute0..nDescription

@RequestID

1

Elektronische Toegangsdiensten: Unique request characteristic. MUST identify the request uniquely within the scope of the sender and receiver for a period of at least 12 months.

@Profile

1

Elektronische Toegangsdiensten: MUST contain "urn:etoegang:1.10:dss:profiles:PDFSignature". This identifies the profile described in these specifications.

OptionalInputs1

Elektronische Toegangsdiensten: MUST be present.

Additional Optional Inputs MAY be specified by each individual Ondertekendienst.

ExpiresAfter0..1Elektronische Toegangsdiensten: MAY be present. Indicates the time before which the request should be completed.
RequiredFeature0..2

Elektronische Toegangsdiensten: MAY be present. Indicates a certain feature is required. Possible values: UserCanForward, UserCanRequestAdditionalSigner

DisabledFeature0..2Elektronische Toegangsdiensten: MAY be present. Indicates a certain feature is disabled. Possible values: UserCanForward, UserCanRequestAdditionalSigner
ServicePolicy0..1

DSS: MAY be present. An Ondertekendienst MAY support this feature.

ClaimedIdentity0..2

Elektronische Toegangsdiensten: Zero, one (only KvK-nummer/RSIN/FI-nummer) or two elements (KvK-nummer/RSIN/FI-nummer and ActingEntityID) MAY be present. An Ondertekendienst MUST support this feature.

If not present the Ondertekendienst will allow signing of the document by any authenticated User.

If only KvK-nummer/RSIN/FI-nummer is present the Ondertekendienst will only allow signing of the document if the User is allowed to sign on behalf of the entity identified in this ClaimedIdentity.

If KvK-nummer/RSIN/FI-nummer and ActingEntityID are present the Ondertekendienst will only allow signing of the document if the User can provide the same pseudonym as indicated in ActingEntityID and is allowed to sign on behalf of the entity identified in this ClaimedIdentity.

Usage of this field is mutually exclusive with the field RequiredSigners. The field will be deprecated in future versions of AS and will be replaced by RequiredSigners

Name1Elektronische Toegangsdiensten: MUST contain either an 8 digit KvK-nummer or RSIN of FI nummer or a specific pseudonym of the ActingEntityID.
RequiredSigners0..n

Elektronische Toegangsdiensten: Zero or more. Mutually exclusive with the field ClaimedIdentity. If not present the Ondertekendienst will allow signing of the document by any authenticated User.

If only KvK-nummer/RSIN/FI-nummer is present the Ondertekendienst will only allow signing of the document if the User is allowed to sign on behalf of the entity identified in this RequiredSigner.

If KvK-nummer/RSIN/FI-nummer and additional attributes are present the Ondertekendienst will only allow signing of the document if the User can provide the same attributes and is allowed to sign on behalf of the entity identified in this RequiredSigner.

RequiredSigner1..n

Elektronische Toegangsdiensten: One or more. An Ondertekendienst must support this feature if it offers Meervoudig Ondertekenen.

Under RequiredSigners, the DV can list one or more <RequiredSigner> elements, each of those containing a list of attributes (according to Attribuutcatalogus) specifying every required Signer

@NameQualifier1Elektronische Toegangsdiensten: MUST contain "urn:etoegang:1.9:EntityConcernedID:KvKnr" resp. "urn:etoegang:1.9:EntityConcernedID:RSIN" resp. "urn:etoegang:1.13:EntityConcernedID:FI resp. "urn:etoegang:core:ActingEntityID".
@Format0Elektronische Toegangsdiensten: SHALL NOT be present.
SupportingInfo0Elektronische Toegangsdiensten: SHALL NOT be present.
Language0..1DSS: MAY be present. An Ondertekendienst MAY support this feature.
AdditionalProfile1Elektronische Toegangsdiensten: MUST contain "urn:oasis:names:tc:dss:1.0:profiles:asynchronousprocessing:1.0".
Schemas0..1DSS: MAY be present. An Ondertekendienst MAY support this feature.
InputDocuments1Elektronische Toegangsdiensten: MUST be present.
Document1Elektronische Toegangsdiensten: Exactly one MUST be present. Signing multiple documents is not (yet) part of the scope of these specifications.
Base64XML0

Elektronische Toegangsdiensten: SHALL NOT be present.

InlineXML0Elektronische Toegangsdiensten: SHALL NOT be present.
EscapedXML0Elektronische Toegangsdiensten: SHALL NOT be present.
Base64Data1Elektronische Toegangsdiensten: MUST contain the Base64 encoded PDF that the DV want to have signed by the User.
@MimeType1Elektronische Toegangsdiensten: MUST contain "application/pdf"
AttachmentReference0Elektronische Toegangsdiensten: SHALL NOT be present.
TransformedData0Elektronische Toegangsdiensten: SHALL NOT be present.
DocumentHash0Elektronische Toegangsdiensten: SHALL NOT be present. Not supported in this phase.
Other0Elektronische Toegangsdiensten: SHALL NOT be present. 
XML-schema ETD optional inputs
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="urn:etoegang:1.11:optional-inputs"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    xmlns:eoi="urn:etoegang:1.11:optional-inputs"
    elementFormDefault="qualified"
    attributeFormDefault="unqualified">

    <xs:import namespace="urn:oasis:names:tc:SAML:2.0:assertion" schemaLocation="http://docs.oasis-open.org/security/saml/v2.0/saml-schema-assertion-2.0.xsd"/>

    <xs:element name="ExpiresAfter" type="xs:dateTime" />
  
    <xs:element name="RequiredFeature" type="xs:token" />
    <xs:element name="DisabledFeature" type="xs:token" />

    <xs:element name="RequiredSigners" type="eoi:RequiredSignersType" />
    <xs:complexType name="RequiredSignersType">
        <xs:sequence>
            <xs:element name="RequiredSigner" type="saml:AttributeStatementType" maxOccurs="unbounded" />
        </xs:sequence>
    </xs:complexType>
</xs:schema>

 

 

Example DV-OD SignRequest
<?xml version="1.0" encoding="UTF-8"?>
<SignRequest xmlns="urn:oasis:names:tc:dss:1.0:core:schema" RequestID="123456789" Profile="urn:etoegang:1.11:dss:profiles:PDFSignature"
    xmlns:eoi="urn:etoegang:1.11:optional-inputs"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <OptionalInputs>
    <Language>nl</Language>
    <AdditionalProfile>urn:oasis:names:tc:dss:1.0:profiles:asynchronousprocessing:1.0</AdditionalProfile>
    <eoi:ExpiresAfter>2016-05-30T09:00:00</eoi:ExpiresAfter>    
    <eoi:RequiredFeature>UserCanForward</eoi:RequiredFeature>
    <eoi:DisabledFeature>UserCanRequestAdditionalSigner</eoi:DisabledFeature>
    <eoi:RequiredSigners>        
        <eoi:RequiredSigner>
            <saml:Attribute Name="urn:etoegang:1.9:attribute:FamilyName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">Jansen</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="urn:etoegang:1.9:attribute:FirstName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">Arie</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="urn:etoegang:1.9:EntityConcernedID:KvKnr" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">12345678</saml:AttributeValue>
            </saml:Attribute>
        </eoi:RequiredSigner>
        <eoi:RequiredSigner>
            <saml:Attribute Name="urn:etoegang:1.9:attribute:FamilyName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">Pietersen</saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="urn:etoegang:1.9:attribute:FirstName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">Bernhard</saml:AttributeValue>
            </saml:Attribute>
        </eoi:RequiredSigner>
    </eoi:RequiredSigners>
  </OptionalInputs>
  <InputDocuments>
    <Document>
      <Base64Data MimeType="application/pdf">[Base64EncodedPDF]</Base64Data>
    </Document>
  </InputDocuments>
</SignRequest>

Rules for processing requests

 

  • In case a RequiredFeature cannot be fulfilled by the signing service (OD), the OD MUST respond with a SignResponse error message containing ResultMajor "RequesterError" and ResultMinor "NotSupported"."

SignResponse - pending (2)

This paragraph describes the DSS 1.0 SignResponse for status pending.

Element/@Attribute0..nDescription

@RequestID

1

Elektronische Toegangsdiensten: MUST contain the RequestID from the Request.

@Profile

1

Elektronische Toegangsdiensten: MUST contain "urn:etoegang:1.10:dss:profiles:PDFSignature".

Result1

DSS: MUST be present.

ResultMajor1

DSS: MUST be present.

Elektronische Toegangsdiensten: MUST contain "urn:oasis:names:tc:dss:1.0:profiles:asynchronousprocessing:resultmajor:Pending"

ResultMinor0..1

Elektronische Toegangsdiensten: DSS: MAY be present. An Ondertekendienst MAY return a value indicating that the request has been forwarded: "urn:etoegang:1.11:dss:resultminor:AwaitingMultipleSignatures

or

Elektronische Toegangsdiensten: DSS: MAY be present. An Ondertekendienst MAY return a value indicating that the request has been forwarded: "urn:etoegang:1.11:dss:resultminor:ForwardedToDesignatedSigner

ResultMessage0Elektronische Toegangsdiensten: SHALL NOT be present.
OptionalOutputs1Elektronische Toegangsdiensten: MUST be present.
AdditionalProfile1Elektronische Toegangsdiensten: MUST contain "urn:oasis:names:tc:dss:1.0:profiles:asynchronousprocessing:1.0".
ResponseID1Elektronische Toegangsdiensten: MUST identify the response uniquely within the scope of the Ondertekendienst for a period of at least 12 months.
SignatureObject0Elektronische Toegangsdiensten: SHALL NOT be present.

Note: exception handling for incorrect DSS SignRequest messages is handled conform DSS specifications.

Example OD-DV SignResponse (pending)
<?xml version="1.0" encoding="UTF-8"?>
<SignResponse xmlns="urn:oasis:names:tc:dss:1.0:core:schema" RequestID="123456789" Profile="urn:etoegang:1.10:dss:profiles:PDFSignature">
   <Result>
    <ResultMajor>urn:oasis:names:tc:dss:1.0:profiles:asynchronousprocessing:resultmajor:Pending</ResultMajor>
  </Result>
  <OptionalOutputs>
    <AdditionalProfile>urn:oasis:names:tc:dss:1.0:profiles:asynchronousprocessing:1.0</AdditionalProfile>
    <ResponseID>111111111111</ResponseID>
  </OptionalOutputs>
</SignResponse>

AuthnRequest (3)

See Interface specifications DV-HM AuthnRequest.

The DV creates exactly the same AuthnRequest as it would to an Herkenningsmakelaar, with one exception. It MUST add to Extensions an Attribute with Name "DocumentSigningID", Value "ResponseID value from SignResponse"

Response (4)

See Interface specifications DV-HM Response.

The OD creates its own Response message according to the specs for the HM Response (as if it were an HM) based on the information in the Summary Assertion of the HM. The OD MUST include the Summary Assertion obtained from the HM in the Advice element of the Summary Assertion and MUST add to the Attribute Statement of the Summary Assertion a SAML Attribute with Name "DocumentSigningID", Value "DocumentSigningID value from AuthnRequest".

In case the interaction started with a non-logged in user, the DV MAY start a user session based on the SAML response . In case the pseudonym asserted in the SAML response does not correspond with the existing user session, the DV MUST end that session.

PendingRequest (5)

This paragraph describes the DSS 1.0 PendingRequest.

Element/@Attribute0..nDescription

@RequestID

1

Elektronische Toegangsdiensten: Unique request characteristic. MUST identify the request uniquely within the scope of the sender and receiver for a period of at least 12 months.

@Profile

1

Elektronische Toegangsdiensten: MUST contain "urn:etoegang:1.10:dss:profiles:PDFSignature".

OptionalInputs1Elektronische Toegangsdiensten: MUST be present.
AdditionalProfile1Elektronische Toegangsdiensten: MUST contain "urn:oasis:names:tc:dss:1.0:profiles:asynchronousprocessing:1.0".
ResponseID1Elektronische Toegangsdiensten: MUST contain the value for ResponseID from the SignResponse from step 2.
Example DV-OD PendingRequest
<?xml version="1.0" encoding="UTF-8"?>
<async:PendingRequest xmlns="urn:oasis:names:tc:dss:1.0:core:schema" RequestID="123456789" Profile="urn:etoegang:1.10:dss:profiles:PDFSignature"  xmlns:async="urn:oasis:names:tc:dss:1.0:profiles:asynchronousprocessing:1.0">
  <OptionalInputs>
    <AdditionalProfile>urn:oasis:names:tc:dss:1.0:profiles:asynchronousprocessing:1.0</AdditionalProfile>
    <ResponseID>123456788</ResponseID>
  </OptionalInputs>
</async:PendingRequest>

SignResponse - final - success (6)

This paragraph describes the DSS 1.0 SignResponse for status final for successful signing.

Element/@Attribute0..nDescription

@RequestID

1

Elektronische Toegangsdiensten: MUST contain the RequestID from the Request.

@Profile

1

Elektronische Toegangsdiensten: MUST contain "urn:etoegang:1.10:dss:profiles:PDFSignature".

Result1

DSS: MUST be present.

ResultMajor1

DSS: MUST be present.

Elektronische Toegangsdiensten: MUST contain "urn:oasis:names:tc:dss:1.0:resultmajor:Success"

ResultMinor0..1DSS: MAY be present. An Ondertekendienst MAY support this feature.
ResultMessage0..1DSS: MAY be present. An Ondertekendienst MAY support this feature.
OptionalOutputs1

Elektronische Toegangsdiensten: MUST be present.

For any additional Optional Inputs accepted by an Ondertekendienst additional Optional Outputs MAY be supported.

ResponseID1Elektronische Toegangsdiensten: MUST identify the response uniquely within the scope of the Ondertekendienst for a period of at least 12 months.
DocumentWithSignature1Elektronische Toegangsdiensten: MUST be present.
Document1Elektronische Toegangsdiensten: Exactly one MUST be present.
Base64XML0

Elektronische Toegangsdiensten: SHALL NOT be present.

InlineXML0Elektronische Toegangsdiensten: SHALL NOT be present.
EscapedXML0Elektronische Toegangsdiensten: SHALL NOT be present.
Base64Data1Elektronische Toegangsdiensten: MUST contain the Base64 encoded PDF that is signed by the User.
@MimeType1Elektronische Toegangsdiensten: MUST contain "application/pdf"
AttachmentReference0Elektronische Toegangsdiensten: SHALL NOT be present.
SignatureObject0Elektronische Toegangsdiensten: SHALL NOT be present.
Example OD-DV SignResponse (final - success)
<?xml version="1.0" encoding="UTF-8"?>
<SignResponse xmlns="urn:oasis:names:tc:dss:1.0:core:schema" RequestID="123456789" Profile="urn:etoegang:1.10:dss:profiles:PDFSignature">
  <Result>
    <ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:Success</ResultMajor>
  </Result>
  <OptionalOutputs>
    <DocumentWithSignature>
      <Document>
        <Base64Data MimeType="application/pdf">[Base64EncodedSignedPDF]</Base64Data>
      </Document>
    </DocumentWithSignature>
    <AdditionalProfile>urn:oasis:names:tc:dss:1.0:profiles:asynchronousprocessing:1.0</AdditionalProfile>
    <ResponseID>111111111111</ResponseID>
  </OptionalOutputs>
</SignResponse>

SignResponse - final - no success (6a)

This paragraph describes the DSS 1.0 SignResponse for status final for not successful signing for a successful SignRequest. Reasons can be time-out (User abandonment), cancellation, wrong signer ID, wrong LOA, etc.

Element/@Attribute0..nDescription

@RequestID

1

Elektronische Toegangsdiensten: MUST contain the RequestID from the Request.

@Profile

1

Elektronische Toegangsdiensten: MUST contain "urn:etoegang:1.10:dss:profiles:PDFSignature".

Result1

DSS: MUST be present.

ResultMajor1

DSS: MUST be present.

Elektronische Toegangsdiensten: MUST contain "urn:oasis:names:tc:dss:1.0:resultmajor:ResponderError"

ResultMinor0..1DSS: MAY be present. An Ondertekendienst MAY support this feature.
ResultMessage0..1DSS: MAY be present. An Ondertekendienst MAY support this feature.
OptionalOutputs1

Elektronische Toegangsdiensten: MUST be present.

For any additional Optional Inputs accepted by an Ondertekendienst additional Optional Outputs MAY be supported.

AdditionalProfile1Elektronische Toegangsdiensten: MUST contain "urn:oasis:names:tc:dss:1.0:profiles:asynchronousprocessing:1.0".
ResponseID1Elektronische Toegangsdiensten: MUST identify the response uniquely within the scope of the Ondertekendienst for a period of at least 12 months.
SignatureObject0Elektronische Toegangsdiensten: SHALL NOT be present.
Example OD-DV SignResponse (final - no success)
<?xml version="1.0" encoding="UTF-8"?>
<SignResponse xmlns="urn:oasis:names:tc:dss:1.0:core:schema" RequestID="123456789" Profile="urn:etoegang:1.10:dss:profiles:PDFSignature">
  <Result>
    <ResultMajor>urn:oasis:names:tc:dss:1.0:resultmajor:ResponderError</ResultMajor>
	<ResultMinor>urn:oasis:names:tc:dss:1.0:resultminor:NotSupported</ResultMinor>
	<ResultMessage>More info on error</ResultMessage>
</Result>
  <OptionalOutputs>
    <AdditionalProfile>urn:oasis:names:tc:dss:1.0:profiles:asynchronousprocessing:1.0</AdditionalProfile>
    <ResponseID>111111111111</ResponseID>
  </OptionalOutputs>
</SignResponse>
  • No labels