Nets Norway AS Haavard Martinsens Vei 54 NO-0045 Oslo T +47 22 89 89 89 F +47 22 81 64 54 www.nets.eu Foretaksregisteret NO 990 224 978 E-Signing Functional description Version: 2.9 Date: 25.11.2014 p. 1-59
Contents 1. Introduction... 5 Purpose... 5 Intended audience... 5 Referenced documentation... 5 Terms and definitions... 6 Acronym... 7 Change log... 8 Contact information... 8 2. E-Signing overview and functions... 9 Architecture... 9 Interfaces... 9 Security... 9 Notification... 10 eid providers... 10 eid hosting... 10 E-Ident... 10 E-Archive... 10 ID-Rights... 10 SDO... 11 PAdES... 12 3. Use cases... 14 Become customer... 14 Multisignature signing flow... 16 4. Gathering an InsertOrder... 19 The InsertOrder message... 19 Documents... 20 One or several documents... 20 Document formats and sizes... 21 The XML document format... 22 XML Examples... 22 Identification before signing (RequiresAuthentication)... 23 Signers... 23 End user... 23 Merchant... 24 Notification... 25 XML example... 25 Merchant... 26 Channels... 27 Notification... 27 Web context... 27 WebContext element... 27 Normal GUI... 28 Reduced GUI... 28 XML example... 28 Execution details... 29 Deadlines... 30 Signing process... 30 Steps... 30 Sequential signing... 31 Parallel signing... 31 Combination signing... 32 2-59
Summary of order execution... 32 Post processing... 33 Archive... 33 5. Administration of orders... 34 Intro... 34 Order status... 34 Step status... 35 Signing process status... 35 Administration messages... 36 Get signing processes... 36 Get order status... 37 Get order details... 37 Get order... 37 Get orders... 37 Cancel order... 37 Modify order deadline... 37 Modify Signing Processes... 38 Get documents... 38 Get SDO... 38 Get SDO details... 38 Merge SDOs... 38 Validate SDO... 39 GetNotificationLog... 39 Delete Document Data... 39 Get PAdES... 39 Generate PAdES... 40 6. SignWeb... 41 Intro... 41 Normal GUI... 42 Reduced GUI... 43 Iframe in Iframe... 43 Forcepkivendor... 43 7. Using ID-Rights with E-Signing... 44 Overview... 44 Functions... 44 The Organizations element... 45 The B2BPostProcessing element... 46 Response messages affected by ID-Rights... 46 Example... 46 Notices... 47 8. Notifications... 49 Intro... 49 Notification triggers... 49 Reminder settings... 50 E-mail and SMS notification... 50 9. Useful information... 51 Intro... 51 E-Signing java client API... 51 Supported XML schema versions... 51 System requirements... 51 SDO validator... 51 Support... 53 Request new functionality... 53 10. Appendix A: A complete example of an InsertOrder. 54 Content of example... 54 3-59
XML example... 56 4-59
1. Introduction Purpose This document is a functional description and will detail the concept of E- Signing. E-Signing aims to offer Merchants: - Advanced, yet user friendly, signing services based on digital IDs independent of eid providers. - An easy way to integrate systems to E-Signing - Notification services and interfaces Intended audience This document is intended for business integrators and application developers. Referenced documentation Document Nets E-Archive-E- Signing Implementation Guide Nets E-Archive Implementation Guide Nets E-Signing Sign- Web Integration Guide Nets RMS Interface Specification Nets TrustNotificationMessage Interface Specification Nets TrustSign- Message Interface Specification Nets UDD Style Guide RMSMessage XML Schema TrustNotification- Message XML Schema TrustSignMessage XML Schema Description An implementation guide on how to use the E- Archive together with E-Signing. An implementation guide on how to integrate directly to the E-Archive web services. This document describes the integration to SignWeb like the use of WebContexts, technicalities involved with reconfiguring sign process page flows and more. A detailed description of the RMSMessage XML schema A detailed description of the E-Signing Notification service. This document describes the XML messages in the TrustSignMessage communication protocol for accessing E-Signing. The UDD Style guide gives guidelines on how to implement custom style sheets and information on various constraints involved with implementing the SignWeb application within the Merchant site. The schema defining the RMSMessage XML message structure. The schema defining the TrustNotification XML message structure. A schema defining the TrustSignmessage XML message structure. 5-59
Terms and definitions Term eid provider End user Merchant Merchant certificate Order Partial SDO Reminder Signed Data Object Signer Signing order Description Equivalent to ID provider or PKI provider, i.e. BankID, BuyPass, NemID etc. The Customer s customer, signatory, signer or other physical person with which the Customer has a relationship regarding signing of electronic documents utilising E-Signing. A legal entity that is a E-Signing customer. Websites or electronic services that use the Service for secure identification, signing, archiving and/or inquiries to ID-Rights. A company can have one or more Merchants. The company/merchants eid certificate. This is equivalent to the Norwegian Virksomhetssertifikat or Brukerstedssertifikat, the Swedish Förlitande sertifikat and the Danish Virksomhedssignatur (VOCES). A construct holding documents, End users, notification rules and execution details. A Partial SDO is an SDO including only one document and all signers that have signed the document at the requested time. A partial SDO is generated after each Signing process in the order. A reminder is a setting that may only exist on a Signing process and is a notification message. A reminder has a StartTime and an interval in hours. A reminder is sent to the signer referenced to in a SigningProcess if the Start- Time is reached. The reminder is sent after every interval period. A reminder is sent to all channels defined on the referenced signer that has the OnReminderEvent trigger set. A Signed Data Object (SDO) is an XML document holding signatures and certificate revocation data along with the signed documents. This structure may be considered as an obliging digital contract and is the outcome of all SignProcesses. See the SDO section in chapter 2. An End user or Merchant that performs a signing operation. Documents, signing rules and information on the End user and/or signatory, submitted by the customer to the signing solution. A Signing order is an order to E-Signing. The Signing order consists of the document(s) to be signed, the Signer(s), the web context, execution details. The Signing order may be equivalent to the InsertOrder message in the 6-59
TrustSignMessage XML interface. Signing process Signing URL Step StepNumber Trigger A Signing process is constructed holding information about a single signer, a single document, a single WebContext and optionally a deadline and reminder settings. A Signer may only sign one document at a time. An URL that is constructed by E-Signing. If accessed, this URL will start a Signing process. A Step is a collection of Signing processes that may be executed simultaneously. The Step with the lowest StepNumber is executed first. An order may consist of many steps. Only one Step may be Active at any given time. Each Step has a StepNumber. The Step- Numbers are given in ascending order, and the Step with the lowest StepNumber is executed first. A Trigger is a setting that is found on the NotificationChannel element in the TrustSign- Message InsertOrder request. The value of this element tells E-Signing when to trigger a notification to the channel this element resides in. Acronym Acronym Description HTML HTTP HTTPS NTP PDF PKI SDO SEID SDO SMS SSL UTC HyperText Markup Language HyperText Transfer Protocol Secure HTTP Network Time Protocol Portable Document Format Public Key Infrastructure Signed Data Object Samarbeidet om Elektronisk ID Detailed information about SEID SDO: http://www.npt.no/iknowbase/content/44963/ SEID_Leveranse_3_v1.0.pdf Short Message Service Secure Socket Layer Coordinated Universal Time UTF-8 A character encoding format of ISO 10646 (RFC 3629) XML XMLDSIG XSL extensible Markup Language XML Digital Signature XML Stylesheet Language 7-59
Change log This is a list of the changes done to this document: Version Description Date 2.0 The document has been restructured 14.03.2013 and updated with new word template and new service name. 2.1 Updated with: 20.06.2013 - Merchant signing is no longer limited to BankID (NO) and Buypass in the eid hosting section of chapter2. - New version of SDO list figure in the SDOsection of chapter2. - Information about document sizes in Document formats and sizes 2.2 Information about a SDO validator 17.12.2013 added to chapter 9. Updated list of supported eids. Information about identification before signing and the use of the GetSigningProcesses message. 2.3 Added information about the parameter 16.05.2014 forcepkivendor. Removed Mobile BankID (SE) from list of eid s as this is now a part of BankID (SE). 2.4 Updated information about E- 16.06.2014 Archive, a new XML message (DeleteDocumentData) and a new order status. 2.5 Minor error correction. 19.09.2014 2.6 Error corrections. 17.10.2014 2.7 Added information about PAdES. 04.11.2014 2.8 Updated with new last page picture 10.11.2014 for PAdES 2.9 Added note in the PAdES section 25.11.2014 Contact information Nets Signing and Identification Services has its own support. All technical questions can be directed to the support. The support can be reached at: support.esecurity@nets.eu. Business related questions should be directed to: sales.esecurity@nets.eu. 8-59
2. E-Signing overview and functions Architecture Interfaces Merchants and End users communicates with E-Signing through the following interfaces: - TrustSignMessage XML scheme - TrustNotificationMessage XML scheme o This is the XML notification interface used to notify Merchants about changes to Signing orders in E-Signing. See chapter 8 about notifications and the Nets TrustNotificationMessage XML Interface specification for more information. - SignWeb o This is the interface between E-Signing and the End user (Signer). See chapter 6 for more information about Sign- Web. Security The service uses signed XML messages when interacting with E-Signing. All messages to the service are signed using a signing certificate issued from Nets CA Eurida. E-Signing validates the signature, authenticates the calling party and performs authorization checks based on the request at hand. If the calling party is authenticated and authorized then the request are handled by E-Signing. The communication line between the Merchant and Nets is based on twoway SSL using client certificates issued by the Nets CA Eurida. 9-59
Notification eid providers Notifications may be sent to both the Merchant and the Signer. More information about notifications is found in chapter 8. The following eid s are supported in E-Signing: - BankID (Norway) / BankID-app (Norway) - BankID on mobile phones ( BankID på mobil ) (Norway) - Buypass Smartcard (Norway) - BankID including Mobile BankID and Nordea e-legitimation (Sweden) - Telia e-legitimation (Sweden) - NemID POCES (Denmark) - NemID MOCES (Denmark) Information about the eid providers can be found in Appendix 2 eid providers in the Nets E-Signing Integration guide. Note: There might be some functions that are only available for some eid providers. The restrictions are found in both the above referred to integration guide and the Nets TrustSignMessage XML Interface specification. eid hosting E-Ident E-Archive E-Signing hosts a customer s Merchant certificate on behalf of the Merchant. The Merchant certificate is issued to the Merchants organization. The following is the usage of the Merchant certificate in E-Signing: - Communication with eid providers: When using the signing applet and to validate a Signers certificate. - To seal the SDO: The entire SDO is signed to ensure its integrity. - Merchant signing: A Merchant may be one of the Signers of a document, and this is specified in the Signing order. If the Merchant has more than one eid enabled, the signing eid must be specified as well. The E-Ident service has been integrated with E-Signing to identify a user prior to presenting the document. The functionality used here is Identification before signing, and if confidentiality protection of the document to be signed is required this function can be used. A signed document (SDO) may be archived automatically in E-Archive with indexes specified when adding a Signing order to E-Signing. Documents stored in E-Archive can be retrieved using the E-Archive portal through Nets customer portal or by integrating the E-Archive web services in your Merchant application. It is also possible to archive documents to another organisation s E-Archive as long as that organisation is whitelisted in the customer configuration. This may be useful when an organisation is operating in different countries with different organisation numbers. The archival status can be retrieved from E-Signing using any of the administration messages GetOrder, GetOrders, GetDocuments, GetOrderDetails and GetOrderStatus. These messages are described more in chapter 5 and in the Nets TrustSignMessage XML Interface specification. ID-Rights The ID-Rights service has been integrated with E-Signing offering the possibility to verify procuration and signing rights after all documents in a Signing order have been signed. It is also possible to fetch and attach Business certificates to the signed document (attached in the SDO structure). 10-59
More information about the use of ID-Rights together with E-Signing is found in chapter 7. SDO A digitally signed document is often represented in formats that are challenging to visualize for the customer. Digitally signed documents also require a compilation of data to be able to prove in a future conflict (court case, dispute etc.) that a specific person actually signed this specific document at a proven time in the past. The SEID SDO is a XML based data package designed to act as a selfcontained validation of one or more digital signatures on one or more documents. The reason for this format is to be able to confirm non repudiation and integrity of the signed document independent of time. Thus the result of a digital signing process can be packaged into a SEID SDO format to simplify validation, traceability and visualization of the signed document. A comparable format is PAdES which uses Acrobat reader to visualize the digital signature embedded in a.pdf document. The Nets E-Signing service produces both a SDO and a PAdES file (if requested) as the result of a digital signing process. The format is structured as an SDOlist with one or more SDOs. Each SDO consist of - One document - One or more signatures - One seal - Signing time or validation time SDOLIST SDO1 SIGNATURES 1-n SIGNATURE VALIDATION DATA (OCSP or CRL) SIGNATURE DATA SEAL SIGNATURE VALIDATION DATA (OCSP or CRL) SIGNATURE DATA DOCUMENT META DATA 1-n KEYVALUEPAIR SDO2 SIGNATURES 1-n SIGNATURE VALIDATION DATA (OCSP or CRL) SIGNATURE DATA SEAL SIGNATURE VALIDATION DATA (OCSP or CRL) SIGNATURE DATA DOCUMENT META DATA 1-n KEYVALUEPAIR A seal is a signature over the document and the signatures. The customer s merchant/organization certificate hosted by E-Signing is used to seal 11-59
the document. The E-Signing service can also make partial SDO s available. A Partial SDO is a SDO including only one document and one signer. A partial SDO is generated after each signing process in the Signing order. The partial SDO is available using the GetDocuments message in the TrustSignMessage XML interface. More information about the SEID SDO standard can be found here: http://www.npt.no/teknisk/elektronisk-signatur/elektronisk-signatur/kvaer-seid-prosjektet/_attachment/1533?_ts=138749031b1 Nets offers a SDO validator to view and validate SDO s. More information about the validator is found in chapter 9. PAdES PAdES (PDF Advanced Electronic Signatures) is a standard for signed documents, and the standard is maintained by ETSI (ETSI TS 102 778). Information about the standard and links to documents may be found at Wikipedia: http://en.wikipedia.org/wiki/pades As a customer of the E-Signing service you may choose to get the signed documents in the PAdES format. E-Signing is using the PAdES-BES standard without the use of signature policy. The signed document are following the LTV-profile (TS 102 778-4) with the use of a TSA service from GlobalSign. To retrieve the signed documents in accordance with PAdES standard there is two ways to do so in E-Signing. Firstly, you may request the document using the GetPAdES XML message, or secondly request the generation of a signed document based on a SDO using the GeneratePAdES XML message. The retrieval of the document from E-Signing with the GetPAdES message is only available for 90 days after the order has been completed. A PDF signed document from E-Signing may only be generated from a PDF file (and not from a text or XML document signed through E-Signing). When generating the PDF signed document, the E-Signing service is appending the following to the original document: - A document reference on each side of the document - A last page with the document reference and information about the signer(s) of this particular document. - An extract of the signature from each signer (as an attachment in the document) The document is sealed using a certificate issued to Nets Norway AS from GlobalSign. 12-59
The last page is added by Nets may look like this: The last page is available in four languages: - English (default if no other language are specified) - Norwegian - Danish - Swedish The default format for signed documents through E-Signing is still SDO, and this document should always be used in case of conflicts. The signed PDF document (PAdES) only includes extracts of the original signatures and not the entire signature. Note: The use of this function may have an extra cost. If it is not already priced in your agreement, please contact sales.esecurity@nets.eu to retrieve the price list and an offer. 13-59
3. Use cases This chapter includes a use case become customer with a single user and a single document and a use case with a multi signature flow. Become customer This use case describes a scenario where an End user becomes a customer of the Merchant. The use case involves the signing of one document by the End user. The agreement to become a customer is signed when the customer is inside the Merchant s web site, and is a synchronised work flow. 1. The End user accesses the Merchant s web site with the purpose of becoming a customer. At the Merchant s web site the End users finds information about how to become a customer and a form to supply contact information. 2. The Merchant uses the below information to assemble a Signing order to use E-Signing in the signing flow. The Signing order is sent to E-Signing when completed: a. A Signer ID like SSN or another unique ID b. The preferred eid the End user will use to sign the document with (for example NemID, Buypass, BankID or other eid supported by E-Signing) c. The document to be signed. This can be a preconfigured agreement that is automatically filled out with the End user s contact information. The document format is depending on the eid to be used. Most eid s support TEXT or PDF. d. The execution details about signing deadlines and archival information. e. Merchant XML notification when the Signing order is com- 14-59
plete ( OnOrderCompletion trigger). 3. The E-Signing service receives the InsertOrder XML message, and performs some internal actions before a response ok message is returned. 4. Based on the InsertOrderResponse message the Merchants requests E-Signing for a Signing URL using the GetSigningProcesses message. 5. The E-signing service replies with at Signing URL to the End user s signing process. 6. The Merchant redirects the End user to the E-Signing SignWeb interface. This redirect may happen inside an IFRAME at the Merchant s web site or as a redirect to a Nets branded web site. E- Signing display s the specified eid providers signing client with the document to be signed. The End user s reads the document and signs it inside the eid provider s applet. 7. The E-Signing SignWeb interface redirects the End user back to the Merchant s web site. 8. The E-Signing service generates a SDO (the format of the signed document) and archives the document in Nets E-Archive (if specified in the Signing order). 9. The E-Signing notification service sends a XML notification to the Merchant s system informing the Merchant that the signing process is complete. The Merchant has just got a new customer. 10. A customer service representative at the Merchant may access the E-Archive using either a portal or web services to view the new agreement. The sequence in this use case shows how the simplest possible Signing order is executed. This order fulfils the minimum criteria s: one signer and one document. The figure illustrates a synchronous signing workflow where the order is created and signed by the End user within the current End user session/sequence. E-Signing also supports asynchronous workflow. Asynchronous workflows allow Merchants to create orders not initiated by the End user. These could be created by merchant applications as part of internal processes (e.g. by customer service representatives). For such a workflow, step 1 in the above sequence does not exist and the End user is notified (email or SMS) when the Signing URL is ready. 15-59
Multisignature signing flow The figure above is a sequence diagram describing the workflow in a Signing order that involves three signers. The three signers complete their signing processes one after the other. The signers do not have the option of signing in the same time frame (parallel signing). We will have a look at how such a Signing order is assembled. The order should fulfil the following merchant criteria s: - There are three documents. It is crucial that document one is signed by signer one before document two is signed by signer two. And then document three should be signed by signer three to complete the order. - The merchant wants a notification after each signing operation (Signing process) and when the Signing order is completed. - It is important that the merchant gets notified if any of the signers reject their Signing processes, since a rejection could terminate the entire order. - Each signer must get a notification by email when his Signing process is ready for signing - The Signers have to use the eid defined by the Merchant for signing - The order must be completed by 15.04.2009 12:00 AM. The sequence diagram in the figure shows the following: 1. The merchant assembles an InsertOrder request according to its own criterias and sends it to E-Signing. E-Signing sends a success response. The order contains the following: a. 3 documents. b. 3 signers. Each signer is defined with a social security number and an email notification channel. The email notification channel is set to be triggered when the signer s 16-59
Signing process is ready. c. An XML service notification channel for the merchant itself (The InsertOrder Merchant element. See the Merchant section in chapter 4). This channel is set to be triggered if a Signing order is rejected and each time a Signing process is completed and when the Signing order as a whole is complete. d. The order deadline. e. 3 steps. i. Step 1 holds a Signing process that references signer1 and document 1. The Signing process rejection flag, TerminateOnSignerRejection, is set to true. This means that the order is terminated if this signer rejects signing the document. ii. Step 2 holds a Signing process that references signer2 and document 2. The Signing process rejection flag, TerminateOnSignerRejection, is set to true. iii. Step 3 holds a Signing process that references to signer3 and document 3. The SigningProcess rejection flag, TerminateOnSignerRejection, is set to true. 2. The first signing process with signer 1 and document 1 is set to the Active status. This triggers an email notification to signer 1 from the E-Signing notification service. The email requests signer1 to sign document 1 by accessing the Signing URL attached to the email. 3. Signer1 accesses the Signing URL and completes his Signing process. The signing process is completed and receives the Complete status. As this is the only signing process in the first step, the step is also set to Complete. 4. The Merchant has requested to be notified when each signing process is complete. Therefore, the E-Signing notification service sends an XML message to the Merchant saying just that. 5. The signing process in step 2 is now Active. This triggers an email notification to signer 2. The email requests signer2 to sign document 2 by accessing the Signing URL attached to the email. 6. Signer2 accesses the Signing URL and completes his Signing process. The signing process is completed and receives the Complete status. As this is the only signing process in the second step, the 17-59
step is also set to Complete. 7. The Merchant is again notified about the completed signing process. 8. The signing process in step 3 is now Active. This triggers an email notification to signer 3. The email requests signer3 to sign document 3 by accessing the Signing URL attached to the email. 9. Signer3 accesses the Signing URL and completes his Signing process. The signing process is completed and receives the Complete status. As this is the only signing process in the second step, the step is also set to Complete. This is also the last step in the Signing order. The order is set to Complete 10. The Merchant is again notified about both the completed signing process and the completed Signing order. The merchant has the option to retrieve information about the Signing order, both during and after completion of the Signing order. The Merchant can use any of the administration messages in the TrustSignMessage web service to request information. The GetOrderStatus is a useful message. The signed document (SDO) holds all the signer signatures along with the signed documents and acts as a digital contract. The SDO is the proof that the signing processes took place. The SDO can either be archived in E- Archive (this must be defined in the InsertOrder message) or the Merchant can use the GetSDO message to retrieve the signed document container. 18-59
4. Gathering an InsertOrder The InsertOrder message The InsertOrder message in the TrustSignmessage interface is the main XML message to E-Signing. This chapter aims to give Merchants guidance on how to assemble a Signing order. The figure below shows an overview of this message. Each Signing order must have a unique OrderID. The OrderID is used to keep track of Signing orders sent to E-Signing. The OrderID is a string with a maximum length of 40 characters. Each Signing order may have an OrderDescription describing this particular Signing order. In the following section the rest of the elements in the InsertOrder are described in details. A complete example of an InsertOrder message involving two signers and three documents is shown as an appendix in chapter 10. 19-59
Documents One or several documents A Signing order must contain one or more documents. For each document that is going to be added to the Signing order, a new Document element must be created (InsertOrder Documents Document). To add a document to the InsertOrder request do the following: - Create a new Document-element - Give the document a LocalDocumentReference. This is a label that must be unique for every Document-element in the current InsertOrder request. This label is referenced later in the InsertOrder request when the Signing Processes are assembled. - Give the document a Title. This will be displayed to the Signer and should give him an idea of the contents of the document. - Give the document a Description. This should be something that gives meaning to the Signer of this document. The description is presented to all End users signing this document. - If the document is a PDF, provide the document content as a base64-encoded byte-array If the document is a TEXT, provide the document UTF-8 bytes. The document UTF-8 bytes must be Base64-encoded. 20-59
Document formats and sizes The support of document formats are depending on the eid the End user is going to use when signing the document. The formats supported in E-Signing are: - PDF - Text - XML Regarding which document format supported for your eids, see one of the appendices in the Nets E-Signing Integration guide. There is a maximum limit for the size of each Signing order and the size of a document. This limit is currently set to 5 MB for both. This means that it is possible to create a Signing order with one document with the size of 5 MB. If there are several documents in the Signing order, the total must not exceed 5 MB. However, Nets has tested the document sizes for some of the eids, and below is the currently recommended size limit of a document for a particular eid. eid BankID (NO) / Bank- ID-app BankID på mobil (NO) BankID (SE) NemID with keycard ( nøglekort ) (DK) NemID with keyfile ( nøglefil ) (DK) Telia e-legitimation (SE) Recommended document size (base64 encoded) 3 MB 116 characters 2 MB 3 MB 1 MB 1 MB Note: It is recommended to test the size of your document. When testing the document sizes, test both to add an InsertOrder to E-Signing and to fetch the document using GetSDO or GetDocuments. Further, when using NemID, be aware that the SDO may become quite large when using both a large document and several signers. This is due to the fact that a SDO with NemID signatures includes the document itself + NemID signatures, and all NemID signatures include both the signature and the document itself. The SDO may therefore be doubled, tripled, and so on in size dependent on the number of signers. This may result in problems using the GetSDO and GetSDODetails functions from E-Signing. 21-59
The XML document format Signing an XML-document is supported, but must be handled slightly different from the merchant s point of view. The issue to keep in mind here is how to present the XML to the End user. XML Examples The Document element XML for a PDF document will be like: <Document> <LocalDocumentReference>DOC1</LocalDocumentReference> <Presentation> <Title>This is the title</title> <Description>This is the desc</description> </Presentation> <DocType> <PDF> <B64DocumentBytes>ANSGKFLSDSF==</B64DocumentBytes> </PDF> </DocType> </Document> The Document element XML for a TEXT document will be like: <Document> <LocalDocumentReference>DOC1</LocalDocumentReference> <Presentation> <Title>This is the title</title> <Description>This is the desc</description> </Presentation> <DocType> <TEXT> <B64DocumentBytes> ANSGKFLSDSF==</B64DocumentBytes> </TEXT> </DocType> </Document> The Document element XML for a XML document will be like: <Document> <LocalDocumentReference>DOC3</LocalDocumentReference> <Presentation> <Title>The title for DOC3</Title> <Description>The description for DOC3</Description> </Presentation> <DocType> <XML> <B64XMLBytes>the xml bytes b64 encoded</b64xmlbytes> <B64XSLBytes>the xsl bytes b64 encoded</b64xslbytes> </XML> </DocType> </Document> 22-59
Identification before signing (RequiresAuthentic ation) It is possible to force End users to identify themselves before presenting the document to be signed. The Identification before signing (RequiresAuthentication) function is typically used when the content of the document to be signed is sensitive. This field is a true/false parameter. If the parameter is set to true, the End users will need to identify themselves before signing. The identification and signing will be performed using the same eid provider. For some eid s the SSN from the InsertOrder will be used as a presetid, and the End user will not be presented with the page in the applet where the SSN is provided. The eid s having this feature is dependent on eid s with the possibility to set SSN as PresetID in E-Ident. Signers The Signers element is mandatory and must contain at least one Signer element. A Merchant may want to sign a document with its own eid, hosted by E-Signing (often referred to as Merchant certificate). This is done by specifying a MerchantSigner. A Signer may either be an EndUserSigner or a MerchantSigner. End user An EndUserSigner is typically an End user who is the merchant s customer. This signer signs documents using a web browser. 23-59
To add an EndUserSigner to the InsertOrder request we have to do the following: - Create new Signer EndUserSigner elements - Give each EndUserSigner a LocalSignerReference. This is a label that must be unique for every Signer element in the InsertOrder request. The LocalSignerReference value does not need to be something meaningful since it will not be displayed during signingoperation. But it must be unique because it is referenced to later in the InsertOrder request. - Provide a name for each EndUserSigner. This element is optional and cannot be verified by E-Signing, but it is highly recommended using the persons real name since this may be shown in the GUI during the End user signing process. - The Merchant may define the AcceptedPKIs element. This element tells E-Signing which eid provider the End user can choose from when signing a document. The Merchant s supported eid providers are already registered in E-Signing. The AcceptedPKIs must only contain eids that are also supported by the Merchant. For each eid specified in the AcceptedPKIs element, the Merchant may tell which SignerID the End user must have. In the CertificatePolicy element the Merchant has the option to mandate which eid (profile) the End user must use when signing a document. See the description about the forcepkivendor parameter as an option to the AcceptePKIs element in section Forcepkivendor of chapter 6. Merchant By defining a MerchantSigner, the Merchant tells E-Signing to sign a document on behalf of the Merchant using its own eid. The signer is not a physical person. E-Signing uses the Merchant s eid hosted by E-Signing to sign the document. To add an MerchantSigner to the InsertOrder request you have to do the following: - Create new Signer MerchantSigner element Give the MerchantSigner a LocalSignerReference. This is a label that must be unique for every Signer element in the InsertOrder request. The LocalSignerReference value does not need to be something meaningful since it will not be displayed during the signing operation. But it must be unique because it is referenced to later in the InsertOrder request. 24-59
Notification The Merchant may want to notify End users or get notified itself on special events regarding a Signing order. To setup End user notification, the Notification element must reside in the EndUserSigner element. The Notification element holds NotificationChannels which may contain at least 1 NotificationChannel element. A NotificationChannel element holds a Channel and a Triggers element. This is where the actual notification settings are defined. A Channel element may represent an Email, an SMS or an XML Service channel. The NotificationChannel holds a communication channel and the Triggers. The Triggers element may hold one or more Trigger elements. A Trigger element describes an event that should triggee a notification to the channel. Supported triggers for End user notifications are: - OnOrderCancellation - OnOrderCompletion - OnOrderRejection - OnOrderExpiration - OnSignProcessReady - OnSignProcessExpiration - OnReminderEvent - OnOrderFailed See chapter 8 for detailed description about notifications and the different triggers. XML example An XML example of the Signer element. Here the Signer must use BankID (NO) as the eid, the Signer will be notified using e-mail when a Signing process is ready and when a Signing order is complete. If the Signer has not signed the document after some time, an e-mail reminder is sent. <Signer> <EndUserSigner> <LocalSignerReference>01027512345</LocalSignerReference> <Name>Signer1</Name> <AcceptedPKIs> <BankID> 25-59
<CertificatePolicy>Employee</CertificatePolicy> <SignerID> <IDType>SSN</IDType> <IDValue>01027512345</IDValue> </SignerID> </BankID> </AcceptedPKIs> <Notification> <NotificationChannels> <NotificationChannel> <Channel> <Email> <EmailAddress>user@work.no</EmailAddress> </Email> </Channel> <Triggers> <Trigger>OnSignProcessReady</Trigger> <Trigger>OnOrderCompletion</Trigger> <Trigger>OnReminderEvent</Trigger> </Triggers> </NotificationChannel> </NotificationChannels> </Notification> </EndUserSigner> </Signer> Merchant The InsertOrder offers the merchant the ability to get notified on events regarding a Signing order. The Merchant element, similar to the EndUser- Signer element, may hold the Notification element. 26-59
Channels The Merchant can set up a Signing order with a number of notification channels. The supported merchant communication channels are: - XML - SMS - E-mail Note: Fax is no longer supported as a notification channel. Notification Supported triggers for merchant channels are: - OnOrderCancellation - OnOrderCompletion - OnOrderExpiration - OnOrderFailed - OnStepReady - OnStepExpiration - OnStepCompletion - OnSignProcessRejection - OnSignProcessExpiration - OnSignProcessCompletion Web context WebContext element A WebContext is a set of URLs that tells E-Signing where an End user is supposed to perform the signing process. A Merchant inserts a Signing order with the intent to have End users sign documents on the web. The E- Signing service that handles the actual signing processes is SignWeb. 27-59
After inserting a Signing order, the Merchant may retrieve a Signing URL. This URL is a pointer to a signing process involving an End user and a document. The Merchant chooses how the End user experiences the signing process by either redirecting the End user to SignWeb or presenting its own signing page. The SignURL can also be distributed to Endu sers via notification channels. If an End user is registered with the email channel and the trigger OnSignProcessReady, the End user will receive an email holding the SignURL when it is his turn to sign. The SignURLBase is the signing URL prefix. When a Signing order is inserted into E-Signing the WebContext is registered for later use. When a Merchant asks for the signing URL, E-Signing generates a unique reference and appends it to the end of the SignURLBase. Signing URL = SignURLBase + <generated reference>. Normal GUI By redirecting an End user to SignWeb, the End user s browser will display E-Signing s GUI. This is referred to as the normal GUI. There is no need to define a WebContext element when using this user interface. Reduced GUI The merchant may want to present its own look-and-feel by having the End user sign documents on its own web portal. This is referred to as the reduced GUI user interface. Details on WebContexts and the different GUIs may be found in the document Nets E-Signing SignWeb Integration guide. XML example <WebContext> <LocalWebContextRef>WebCtx_1</LocalWebContextRef> <SignURLBase>http://www.merchant.no/Sign?ref=</SignURLBase> <ErrorURL- Base>http://www.merchant.no/Sign/Error?errorCode=</ErrorURLBase> <StyleURL>http://www.merchant.no/Sign/custom.css</StyleURL> <ExitURL>http://www.merchant.no/Sign/Complete</ExitURL> </WebContext> 28-59
Execution details The ExecutionDetails element in the InsertOrder message is where the execution of the order is defined. This element holds the following information: - The order deadline - An option to set the DisplayProcessInfo element. The presence of this element with the value true tells E-Signing to display additional information about the document being signed to the End user. In a Signing order, many signers may sign the same document. The DisplayProcessInfo element tells E-Signing to display the Name, NameStatus or NameStatusTime concerning the signers of the document involved. (Not all eid providers can show this info.) - An option to set the GenerateOneTimeURL element. This element, if the value is true, forces E-Signing to generate OneTimeURL. A OneTimeURL can only be used once. If a End user accesses a signing URL, this URL is marked as used and cannot be accessed again. The second time an End user tries to access it, they would get an error message. A OneTimeURL also has a deadline which allows it to be accessible only for a limited amount of time. The time limit is set to 10 minutes. The Merchant can get new unused URLs using the GetSigningProcesses message. The OneTimeURL functionality is meant to be used in a synchronous process. - Steps and Signing processes. 29-59
Deadlines E-Signing gives the merchant the option to set a deadline on the order, on each Step and on each Signing process in a Step. The rules for order, step and signing processes deadlines: - The OrderDeadline must be after NOW (the time E-Signing receives the order) and before NOW + 90 days. This is a limit set by E- Signing. - A Step has a step number. Step 1 s deadline must be after NOW and before the OrderDeadline. Deadlines for Step 1+x must be after the previous step s deadline and before the OrderDeadline. - A Signing process deadline for Signing process must be after NOW and before the StepDeadline of which the Signing process is in. If the Step and Signing process deadlines are not set by the integrator, they are automatically to set the same as OrderDeadline. Signing process A Signing process is constructed holding information about a single signer, a single document, a single WebContext and optionally a deadline and reminder settings. A signer may only sign one document at a time. Steps A Step may hold one or more Signing processes. A Signing order may contain many Steps but only one Step may be active at a time. Each Step must contain a StepNumber which tells E-Signing the order of execution. Steps are numbered sequentially, beginning at 1. 30-59
- Step 1 with StepNumber 1. This tells E-Signing that this Step is going to be executed first. All Signing processes in a Step must be complete in order for a Step to get the Complete status. - Step 2 with StepNumber 2. This tells E-Signing that this Step is going to be executed after Step 1 has completed successfully. In the meantime this Step has the Pending status. - Step 3 with StepNumber 3. This tells E-Signing that this Step is going to be executed after Step 2 has completed successfully. In the meantime this Step has the Pending status. Sequential signing A sequential workflow is illustrated above. The figure illustrates three signers. Signer1 has to complete his signing process before signer 2 and signer 2 has to complete his signing process before signer 3 is enabled to execute his signing operation. The order of execution, in this example, is sequential and is regulated by E-Signing by the use of Steps and Signing processes. In this example, the Merchant should define three Steps with one Signing process in each Step. Parallel signing A parallel signing workflow is illustrated in the figure above. A Signing order containing a parallel signing workflow has to define only one step. All Signing processes residing in a Step are allowed to be executed simultaneously. 31-59
Combination signing If we merge the sequential and parallel Signing process examples we get a combination. The figure above illustrates a signing workflow that combines the sequential and the parallel workflows. Below is an illustration of three steps. The first step includes one signing process, step two includes two Signing processes (parallel) and the last step includes one Signing process. Summary of order execution The following summarizes the concept of the order of execution : - An order consist of one or more documents and one or more signers - A signer may sign many documents within the same Signing order - One signer and one document make up a Signing process. - Steps mandate the order of execution. - A Step s StepNumber tells E-Signing the order of execution. All Steps must be numbered from 1 and upwards. - A Signing order may only have one Active Step at any moment. All other steps are pending or complete. - A Step may consist of one or more Signing processes. All Signing processes within a Step may be executed in parallel (at the same time). 32-59
Post processing The PostProcessing element includes all information about archival. The PostProcessing element was introduced in the XML schema version 20140303. Archive When the Signing order is completed and a SDO is generated, E-Signing can archive the SDO in the Nets E-Archive. This is specified in the PostProcessing element in the InsertOrder message. The name of the archive and the archival indexes must be supplied. The archive indexes are used to locate this particular signed document in E-Archive. By using the MetaData element, the customer may archive a document to another organisation number than the one registered in the customer configuration. This may only be done if the other organisation number is whitelisted in the customers E-Signing configuration. Note: If the Signing order includes more than one document, the SDO is divided into as many SDO s as there are documents in the Signing order. Each SDO includes one document with all its signatures, and will be handled as one archive object. The E-Archive can be accessed either through a portal or through a web services. More information about E- Archive is found in Nets E-Archive User guide and Nets E-Archive Implementation Guide. 33-59
5. Administration of orders Intro Order status E-Signing keeps track by giving the Signing order, each Step and each Signing process in each Step a status. The status hierarchy is managed by strict rules. The different Signing order statuses are listed in the table below Status Active Description The Active status is the first status a Signing order will be given. The Signing order is in this status as long as there are Steps with the Active status. When the Signing order is registered it gets the Active status. Step 1 and all its Signing processes get the Active status. The rest of the Steps, and their Signing processes, get the Pending status. Can- celledby- Merchant Expired The Signing order is expired. This state is applied when a deadline is reached. The Signing order can be returned to an Active status using the ModifyOrderDeadline message. ExpiredBy- Proxy RejectedBySigner The CancelledByMerchant status is given to a Signing order when the Merchant sends a CancelOrder message on a specified Signing order to E-Signing. The Signing order is cancelled. This is a final state. The Signing order is set to the ExpiredByProxy status when either a Step or a Signing process has reached its deadline. The deadline can be modified using the ModifyOrderDeadline message. A Signing order is set to RejectedBySigner if the following occurs: - The End user has rejected to sign a document. - The TerminateOrderOnRejection setting in the InsertOrder is set to true This state may also be reached if the Merchant uses the ModifySigningProcess message. This state is a final state. Complete Failed The Signing order is set to Complete when all steps and signing processes are completed and all post processing of an order has been completed. Post processing includes creating and sealing the SDO, send notifications and archival. The Signing order will also reach this state if one or more of the Signing processes have been rejected, but the TerminateOrderOnRejection is set to false. This is a final state. A Signing order is set to Failed if one of the Signers of a document did not have the right to sign the document. This state will only occur in conjunction with the use of 34-59
ID-Rights functionality. This is a final state. Deleted The Signing order is set to Deleted if the XML message DeleteDocumentData has been performed for that particular order. Step status The different Step statuses are listed in the table below: Status Active Pending CancelledBy- Merchant Expired ExpiredBy- Proxy RejectedBySigner Description A Step is set to the Active status when the Steps prior to this Step have been completed with either a Complete or RejectedBySigner status. The first Step is set to Active at the same time as the Signing order is set to Active. Only one step may be in the Active status at the same time. A Step is set to Pending if the previous Steps have not been completed. The Step is given the CancelledByMerchant status is the Merchant sends a CancelOrder message to E-Signing. The Step is set to Expired if the Step s deadline has been reached. This can be modified using the ModifyOrderDeadline message. The Step is set to ExpiredByProxi if one or more of the Signing processes in the step have reached its deadline. This can be modified using the ModifyOrderDeadline message. A Step is set to RejectedBySigner if the following occurs: - The End user has rejected to sign a document. - The TerminateOrderOnRejection setting in the InsertOrder is set to true This state may also be reached if the Merchant uses the ModifySigningProcess message. This state is a final state. Complete The Step is set to Complete when all Signing processes are completed. The Step will also reach this state if one or more of the Signing processes have been rejected, but the TerminateOrderOnRejection is set to false. This is a final state. The next step will now reach the Active state. Signing process status The different Signing process statuses are listed in the table below: Status Description Active All Signing processes in a Step are set to Active when the Step reaches the Active status. A SignURL for the Active Signing processes are now available, and the End user can sign the document in this Signing process. 35-59
Pending CancelledBy- Merchant Expired RejectedBySigner A Signing process is set to Pending if the Signing process is not ready for signing. The previous Steps have not been completed. The Signing process is given the CancelledByMerchant status is the Merchant sends a CancelOrder message to E-Signing. The Signing process is set to Expired if the Signing process deadline has been reached. This can be modified using the ModifyOrderDeadline message. The End user has rejected to sign the document in the Signing process. This state may also be reached if the Merchant uses the ModifySigningProcess message. This state is a final state. Complete The End user has signed the document, and the signing process is completed. The Signing process is set to Complete. This is a final state. Administration messages Get signing processes The GetSigningProcesses message is used to fetch all signing processes for a given order and signer. The message uses OrderID and LocalSignerReference as input. Optionally, the Signing processes status can be specified. In return the asking application will among other get a list of all Signing processes for this signer, status of the Signing processes, details about the document in the Signing process, the SignURL (if not signed and the Signing process status is Active) and the SigningTime (if signed) This message is often used to fetch the particular SignURL that the Signer must access to sign a document. Other ways to get a signing URL is to use either e-mail notification sent directly to the Signer or XML notification sent to the Merchant application/system. This message is also used to check the status of a Signing process. The status of a Signing process is set to complete immediately after the signing has been performed. As a comparison, the status of an order is set to complete after all signatures has been set to complete and all post processing of the order has been done. Post processing includes creating and sealing the SDO, send notifications and archival. Note: This message must be implemented when using E-Signing to check the status of specific Signing processes. If notification is not used this message must be implemented to retrieve the signing URL. 36-59