comsigntrust signer-1 signflow integration api document … · 1.3 this document will outline the...

Signer-1 SignFlow Integration API

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

1.6.2012 Yoni Stephan

Version 1.0 Alex Raitskin 18.11.2012 Yoni Stephan





Contents 1. General ..................................................................................................................................................... 3

2. Terms ........................................................................................................................................................ 3

3. General Flow ............................................................................................................................................. 3

4. Transaction Setup ..................................................................................................................................... 4

5. Signing Page ............................................................................................................................................ 12

6. Transaction Query (Optional) ................................................................................................................. 15


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.


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

4.6 XML Request <request>

<language>ENG</language>

<command>doCreateSigPage</command>

<requestId>7777-3333-2222-3333</requestId>

<version>1</version>

<doCreateSigPage>

<branding>

<topTitle>Please sign this NDA document.</topTitle>

<bottomTitle>For support please call 44-1999-222</bottomTitle>

<logo>

<url>logo.jpg</url>

</logo>

</branding>

<sessionDurationLimit>120</sessionDurationLimit> 

<signerProfileId>SIGNER_111232328</signerProfileId>

<documentType>PDF</documentType>

<PDF>

<source>

<uncPath>\\shared\NDA.pdf</uncPath>



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


4.7 Request Tags

4.7.1 Most of the tags are fixed values, and should be submitted exactly as in the example

above.

4.7.2 The following are the variable tags details:

Tag Name Type Value Value Mandatory

Description

language AlphaNumeric ENG

FRE

RUS

SPN

Yes 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



Description

digital certificate

defined during the

enrollment phase.

documentType AlphaNumeric PDF

DOCX

XLSX

PPTX

TIFF

Yes Indicates a request for

MPI page and

transaction setup

source [tag]

AlphaNumeric

(tag)

tag should be

used for archival

and logging

reference

Yes 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



Description

suite to use

enablePreview Integer 1

0

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.

enableDownload Integer 1

0

Yes A hyperlink should be

available to the user to

download the file and

view it locally on his

desktop.

signatureType AlphaNumeric qualified

advanced

Yes

qualified Yes if

qualified

signature is

selected.

For a remote qualified

signature two factor

authentication is

required along the PIN

to the remote

cryptographic device.

qAuthenticationMethodFactorOne AlphaNumeric OTP

SMS

PINCODE

PKI

Yes if

qualified

signature is

selected.

PKI – for software or

smart card SSL mutual

authentication.

qAuthenticationMethodFactorTwo AlphaNumeric OTP

SMS

PINCODE

PKI

Yes if

qualified

signature is

selected.

advanced [adhoc] Boolean true

false

Yes if

advanced

signature is

selected.

Set adhoc to true if

the digital signature

should be created

for the current

transaction.

adhocDN Alphanumeric Yes if

advanced

The distinguished

name of the



Description

signature is

selected

and adhoc

attribute is

set to

"true".

dynamically created

certificate.

aAuthenticationMethod OTP

SMS

PINCODE

PKI

INTEGRATED

Yes if

advanced

signature is

selected.

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 Specifies the return

page to which the


redirect in case of

success.

onError Specifies the return

page to which the


redirect in case of

failure.

customData Additional XML

passed in purpose to

meet specific EA

requirements and

customizations.


4.8 XML Response

<ashrait> <?xml version="1.0" encoding="UTF-8"?>

<response>

<requestId>7777-3333-2222-3333</requestId>

<requestStatus>Approved</requestStatus>

<errorCode/>

<transactionId>1234-1234-1234-1234</transactionId>

<redirectUrl>http://signer/id=aasdadfsdfsdfsdyertfsdf</redirectUrl>

<customData>

</customData>

</response>


4.9 Response Tags

4.9.1 The response has many tags that are relevant to different ComSignTrust extended

functionality capabilities.

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


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

https://signserver/PerformSignature.aspx?txId=<transactionID>

or specifically like this:

https://signserver/PerformSignature.aspx?txId=459c35c1-80d14fa7-b6ac-60c33987b958


5.4 Signing Page

5.4.1 Once redirected to the signing page, the default page looks like this:

5.4.2 When submitted (Sign/Reject button is pressed) the actual operation is performed.

5.4.3 When done, the user is redirected back to a predefined successUrl or errorUrl on the EA

web site (predefined landing pages).


5.4.4 The redirection to the landing pages will contain additional parameters that specify the

request/transaction status.

5.5 Success Page

5.5.1 Success Page example:

5.5.2 Additional OK Page variable (URL request string variables):

Field Name Value Description

uniqueID Unique

transaction ID

The unique transaction ID as

EA gave on transaction

creation

custom Defined by the EA

customizations.

5.6 Error Page

5.6.1 Error Screen example:

5.6.2 Additional Error Page variables (URL request string variables):

5.6.3 In case of error (onError redirection) additional two parameters will be added:

ErrorCode and ErrorText as well.

5.6.4 Addition Error page GET variables:

Field Name Value Description

uniqueID Unique

transaction ID

The unique transaction

ID as EA gave on

transaction creation

custom Defined by the EA

customizations.

errorCode Error Code Numeric error code

errorText Error Text Error Description


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>


<expectedDocumentResponse>

</expectedDocumentResponse>

</doQuery>

</request>

8.4 Request Tags

8.4.1 The following are the necessary tags for querying the system:

Description Value Mandatory

Value Type Tag Name

Unique

transactionId

returned

during the

initiation of

the signature

page.

Yes GUID AlphaNumeric transactionId

Describes how the

signed document

should be returned.

encodedFile

uncPath

AlphaNumeric expectedDocumentResponse

8.5 XML Response <response>


<signatureStatus>Success</signatureStatus>

<errorCode/>

<failureDescription/>

<encodedFile/>

<uncPath/>

<dateTime/>

<rejectReason/>

</response>


8.6 Response Tags

8.6.1 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

Tells if the signing

operation is completed

successfully, pending or

failed. For failure

additional description

and code is provided in

the below tags.

errorCode AlphaNumeric One of the

error codes

defined in

Appendix B.

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.


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:

https://signserver/signature.aspx

1.4.1 Test server name will be sent in the Signer - 1 integration documentation.

1.5 Request

1.5.1.1 Request Parameters (submitted via HTTPS Post):

1.5.1.4 SIG_INIT =<transaction details according to XML API standards detailed in the

following sections>

1.6 Response

1.6.1 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


Connection Error 992

Document does not exist 993

comsigntrust signer-1 signflow integration api document … · 1.3 this document will outline the...

Documents