ComSignTrust Signer-1 SignFlow Integration API Document

Transcription

1 ComSignTrust Signer-1 SignFlow Integration API Document Version: 1.8 Date: 10/10/2013 ComSignTrust TM LTD All rights reserved Version Writer Date Review by Version 0.9 Alex Raitskin, Daniel Gorelic Yoni Stephan Version 1.0 Alex Raitskin Yoni Stephan Version 1.3 Alex Raitskin Yoni Stephan Version 1.5 Alex Raitskin Yoni Stephan Version 1.8 Alex Raitskin Yoni Stephan Signer-1 SignFlow Integration API Page 1

2 Contents 1. General Terms General Flow Transaction Setup Signing Page Transaction Query (Optional) Signer-1 SignFlow Integration API Page 2

3 1. General 1.1 ComSignTrust Redirect module (SignFlow) enables users to perform digital signing operations without having to deal with details of signature generation. 1.2 The idea is based on securely receiving transaction data from the EA, redirecting users to dynamically constructed web page, and then securely receiving the signature operation results (success/failure). 1.3 This document will outline the API the EA has to implement for interacting with the ComSignTrust Redirect module. 2. Terms 2.1 DSP Digital signature plugin. 2.2 EA Enterprise System (ERP, CRM, BPM, Bespoke system)/website (SharePoint, portals) that performs signature requests. 2.3 End User Digital Signature Owner user who performs online digital signing in the EA application/site. 3. General Flow 3.1 EA, using XML over HTTP, will transfer the reference of the document or the document itself to Signer-1 signing portal. 3.2 The EA redirects the user to the Signer1 web application where the user has to authenticate and has to enter required data in order to review and sign the document. 3.3 After a successful authentication and user approval of the document, the document is signed and the user is either redirected back to the EA or a predefined callback is triggered to notify of the signing transaction completion. 3.4 If the process is disrupted or abandoned for any reason - the transaction ID can be used to verify its current state. 3.5 It is expected that the e-signature (either Advanced or Qualified) is stored in the Signer1 according to the ETSI regulations and used in the background while signature is needed, allowing the signer to use his HSM PIN (Personal Identification Number of the user in the HSM). 3.6 The signed and sealed document will be returned to the EA. Signer-1 SignFlow Integration API Page 3

4 3.7 Signing Process Diagram: 4. Transaction Setup 4.1 The following is the XML that should be posted as the SIG_INIT request variable (via https or web service). 4.2 For posting the request please refer to appendix A. 4.3 When sending this request, a transaction is set up in the system background and a URL is retrieved, in the page opened when accessing the URL, the digital signature owner is adding required transaction information (card number, exp date, etc'. Signer-1 SignFlow Integration API Page 4

5 4.6 XML Request <request> <language>eng</language> <command>docreatesigpage</command> <requestid> </requestid> <version>1</version> <docreatesigpage> <branding> <toptitle>please sign this NDA document.</toptitle> <bottomtitle>for support please call </bottomTitle> <logo> <url>logo.jpg</url> </logo> </branding> <sessiondurationlimit>120</sessiondurationlimit> <!-- seconds --> <signerprofileid>signer_ </signerprofileid> <documenttype>pdf</documenttype> <PDF> <source> <uncpath>\\shared\nda.pdf</uncpath> <!-- <encodedfile></encodedfile> --> </source> <signaturefields> <sigfield name="sig1" isrequired="true"> <rect>0,0,100,100</rect> <page>1</page> <alg>rsa-sha256</alg> </sigfield> </signaturefields> </PDF> <enablepreview>1</enablepreview> <enabledownload>1</enabledownload> <signaturetype>qualified</signaturetype> <qualified mechanism="remote"> <qauthenticationmethodfactorone>sms</qauthenticationmethodfactorone> <qauthenticationmethodfactortwo>pincode</qauthenticationmethodfactortwo> </qualified> <! <advanced isadhoc="false"> <adhocdn></adhocdn> <aauthenticationmethod>pincode</aauthenticationmethod> </advanced>--> <return> <onsuccess>success.aspx</onsuccess> <onerror>error.aspx</onerror> </return> <customdata> </customdata> </docreatesigpage> </request> Signer-1 SignFlow Integration API Page 5

6 4.7 Request Tags Most of the tags are fixed values, and should be submitted exactly as in the example above The following are the variable tags details: Tag Name Type Value Value Mandatory language AlphaNumeric ENG FRE RUS SPN Yes Description Specifies the language of the dynamically constructed signing page command AlphaNumeric docreatesigpage Yes Type of page to be built use "docreatesigpage" for signing operation. requestid AlphaNumeric Guid Yes A unique GUID used to identify and monitor the signing operation. version AlphaNumeric 1 Yes branding No The custom texts and logo to be set on the signing page. sessiondurationlimit Integer Yes Time before the generated signing page becomes invalid. signerprofileid AlphaNumeric Yes This is the unique identifier of the user's Signer-1 SignFlow Integration API Page 6

7 Tag Name Type Value Value Mandatory documenttype AlphaNumeric PDF DOCX XLSX PPTX TIFF source [tag] AlphaNumeric (tag) tag should be used for archival and logging reference Yes Yes Description digital certificate defined during the enrollment phase. Indicates a request for MPI page and transaction setup The reference to the document to be signed. Can be used with either uncpath or encodedfile mutually exclusive. uncpath AlphaNumeric No Path to the document on a shared folder. encodedfile AlphaNumeric No Base64 encoded document signaturefields Yes For PDF only. List of sigfield elements. sigfield Yes For PDF only. Contains the description of the signature field to be signed. If the field does not exist it will be created in the position defined by the rect and page elements. The "alg" element describes what type of algorithm Signer-1 SignFlow Integration API Page 7

8 Tag Name Type Value Value Mandatory Description suite to use enablepreview Integer 1 0 enabledownload Integer 1 0 Yes Yes The user will be able to preview the document on the signing page if such capability is available for the selected type of document. A hyperlink should be available to the user to download the file and view it locally on his desktop. signaturetype AlphaNumeric qualified advanced qualified qauthenticationmethodfactorone AlphaNumeric qauthenticationmethodfactortwo AlphaNumeric OTP SMS PINCODE PKI OTP SMS PINCODE PKI advanced [adhoc] Boolean true false Yes Yes if qualified signature is selected. Yes if qualified signature is selected. Yes if qualified signature is selected. Yes if advanced signature is selected. adhocdn Alphanumeric Yes if advanced For a remote qualified signature two factor authentication is required along the PIN to the remote cryptographic device. PKI for software or smart card SSL mutual authentication. Set adhoc to true if the digital signature should be created for the current transaction. The distinguished name of the Signer-1 SignFlow Integration API Page 8

9 Tag Name Type Value Value Mandatory aauthenticationmethod OTP SMS PINCODE PKI INTEGRATED signature is selected and adhoc attribute is set to "true". Yes if advanced signature is selected. Description dynamically created certificate. INTEGRATED for Active directory authentication. return Yes Specifies the return page to which the signing portal should redirect in case of success of failure. onsuccess onerror customdata Specifies the return page to which the signing portal should redirect in case of success. Specifies the return page to which the signing portal should redirect in case of failure. Additional XML passed in purpose to meet specific EA requirements and customizations. Signer-1 SignFlow Integration API Page 9

10 4.8 XML Response <ashrait> <?xml version="1.0" encoding="utf-8"?> <response> <requestid> </requestid> <requeststatus>approved</requeststatus> <errorcode/> <transactionid> </transactionid> <redirecturl> <customdata> </customdata> </response> Signer-1 SignFlow Integration API Page 10

11 4.9 Response Tags The response has many tags that are relevant to different ComSignTrust extended functionality capabilities The following are the necessary tags for integration: Tag Name Type Value Description requestid AlphaNumeric GUID Defined In the request XML. requeststatus AlphaNumeric Success Error errorcode AlphaNumeric One of the error codes defined in Appendix B. transactionid AlphaNumeric GUID Used in the query XML to check the current status of the signing operation. redirecturl AlphaNumeric URL A temporary URL to where the EA should redirect the user. customdata Additional XML returned in purpose to meet specific EA requirements and customizations. Signer-1 SignFlow Integration API Page 11

12 5. Signing Page 5.1 Once the transaction setup was performed, the EA now holds the temporary signature page URL retrieved from the response (redirecturl tag). 5.2 Once retrieved, the EA should redirect the user to the signing page. 5.3 A retrieved signing page may look in this form (server DNS name may change according to the dedicated hosted page server): or specifically like this: Signer-1 SignFlow Integration API Page 12

13 5.4 Signing Page Once redirected to the signing page, the default page looks like this: When submitted (Sign/Reject button is pressed) the actual operation is performed When done, the user is redirected back to a predefined successurl or errorurl on the EA web site (predefined landing pages). Signer-1 SignFlow Integration API Page 13

14 5.4.4 The redirection to the landing pages will contain additional parameters that specify the request/transaction status. 5.5 Success Page Success Page example: Additional OK Page variable (URL request string variables): Field Name Value Description uniqueid custom Unique transaction ID The unique transaction ID as EA gave on transaction creation Defined by the EA customizations. 5.6 Error Page Error Screen example: Additional Error Page variables (URL request string variables): In case of error (onerror redirection) additional two parameters will be added: ErrorCode and ErrorText as well Addition Error page GET variables: Field Name Value Description uniqueid custom Unique transaction ID The unique transaction ID as EA gave on transaction creation Defined by the EA customizations. errorcode Error Code Numeric error code errortext Error Text Error Description Signer-1 SignFlow Integration API Page 14

15 6. Transaction Query (Optional) 8.1 An additional feature ComSignTrust offers is querying the signing portal for the full signing operation details. 8.2 The can be optionally implemented by the EA. Of course, the query is using the same ComSignTrust HTTPS Post or Web service mechanism, using the following XML to perform the transaction. 8.3 XML Request <request> <version>1</version> <command>doquery</command> <doquery> <transactionid> </transactionid> <expecteddocumentresponse> </expecteddocumentresponse> </doquery> </request> 8.4 Request Tags The following are the necessary tags for querying the system: Description Unique transactionid returned during the initiation of the signature page. Describes how the signed document should be returned. Value Mandatory Value Type Tag Name Yes GUID AlphaNumeric transactionid encodedfile uncpath AlphaNumeric expecteddocumentresponse 8.5 XML Response <response> <transactionid> </transactionid> <signaturestatus>success</signaturestatus> <errorcode/> <failuredescription/> <encodedfile/> <uncpath/> <datetime/> <rejectreason/> </response> Signer-1 SignFlow Integration API Page 15

16 8.6 Response Tags The following are the necessary tags for integration: Tag Name Type Value Description transactionid AlphaNumeric GUID Unique transactionid returned during the initiation of the signature page. signaturestatus AlphaNumeric Success Pending Failure errorcode AlphaNumeric One of the error codes defined in Appendix B. Tells if the signing operation is completed successfully, pending or failed. For failure additional description and code is provided in the below tags. failuredescription AlphaNumeric encodedfile AlphaNumeric Base64 encoded file if that option was selected. uncpath AlphaNumeric Shared path to the signed file. datetime AlphaNumeric TimeDate Time of operation completion. rejectreason AlphaNumeric Rejection comment as was filled by the user. Appendix A: Posting Web Service/HTTPS Request 1. Signer-1 SignFlow Integration API Page 16

17 HTTPS Post request 1.1 This request is used for acquiring the signing page URL. 1.2 The merchant system should post a HTTPS POST request for sending the transaction. 1.3 Always use the server name when accessing the web service (which should be the server and the certificate name) this preventing certificate authentication errors. 1.4 Accessing the HTTPS interface is via the following URL: Test server name will be sent in the Signer - 1 integration documentation. 1.5 Request Request Parameters (submitted via HTTPS Post): SIG_INIT =<transaction details according to XML API standards detailed in the following sections> 1.6 Response The response is formatted as a single string containing the XML response. Appendix B: Additional Error Codes 1. Error Codes Message Error Code Success 000 Document rejected by user 982 Invalid request or post parameters 983 Certificate is Expired 984 Certificate is revoked 985 PIN locked 986 Internal Server Error 987 Transaction has expired (timeout) 988 Transaction already submitted 989 Transaction not found 990 Document Error 991 Signer-1 SignFlow Integration API Page 17

18 Connection Error 992 Document does not exist 993 Signer-1 SignFlow Integration API Page 18