A D S S G o > S i g n D e v e l o p e r s G u i d e

Transcription

1 A D S S G > S i g n D e v e l p e r s G u i d e A S C E R T I A LTD J u l y D c u m e n t V e r s i n Ascertia Limited. All rights reserved. This dcument cntains cmmercial-in-cnfidence material. It must nt be disclsed t any third party withut the written authrity f Ascertia Limited. Cmmercial-in-Cnfidence

2 CONTENTS 1 INTRODUCTION SCOPE INTENDED READERSHIP CONVENTIONS TECHNICAL SUPPORT ADSS GO>SIGN SERVICE OVERVIEW GO>SIGN CLIENT APPS GO>SIGN VIEWER ADSS GO>SIGN SERVICE INTEGRATION GO>SIGN SERVICE REQUEST (JSP EXAMPLE) GO>SIGN SERVICE REQUEST (ASP.NET / C# EXAMPLE) HOW BUSINESS APPLICATIONS RECEIVE SIGNED DOCUMENTS LANGUAGE PREFERENCE SETTINGS GO>SIGN CLIENT APPS JAVASCRIPT LIBRARY PRE-PROCESSING FUNCTIONS PROCESSING FUNCTIONS POST PROCESSING FUNCTIONS GO>SIGN VIEWER JAVASCRIPT FUNCTIONS EXAMPLE SCENARIOS & DEMOS FOR GO>SIGN SERVICE DOCUMENT SIGNING DEMOS CERTIFICATION DEMOS JAVA GO>SIGN DEMO DEPLOYMENT & CONFIGURATION DEPLOYING THE JAVA DEMO APPLICATION NET GO>SIGN DEMO DEPLOYMENT & CONFIGURATION DEPLOYING THE.NET DEMO APPLICATION ON IIS 7.5 OR HIGHER FIGURES FIGURE 1 - ADSS GO>SIGN SERVICE & BUSINESS APPLICATION INTERACTION... 4 FIGURE 2 - GO>SIGN VIEWER EXAMPLE... 7 FIGURE 3 - GO>SIGN DEMO PARKLING PAGE TABLES TABLE 1 - ADSS GO>SIGN SERVICE HTTP REQUEST HEADERS TABLE 2 - HTTP REQUEST HEADERS TO INITIATE THE GO>SIGN REQUEST TABLE 3 - HTTP RESPONSE HEADERS FROM GO>SIGN SERVICE Ascertia Limited Cmmercial-in-Cnfidence Page 2 f 31

3 1 Intrductin 1.1 Scpe ADSS G>Sign Service enables business applicatins t digitally sign dcuments using lcal r server held keys by use f G>Sign Desktp r G>Sign Applet applicatin. In additin, it prvides a pwerful dcument viewer t display, navigate, and sign PDF dcuments. G>Sign Service makes it easy t integrate G>Sign Desktp r G>Sign Applet int business applicatins. This dcument prvides infrmatin n hw t integrate ADSS G>Sign Desktp r G>Sign Applet in yur business applicatins and take advantage f G>Sign Service. 1.2 Intended Readership This guide is intended fr develpers wh are integrating business applicatins with ADSS G>Sign Service. The dcument assumes a reasnable knwledge f web applicatin develpment, specifically JavaScript and HTML. 1.3 Cnventins The fllwing typgraphical cnventins are used in this guide t help lcate and identify infrmatin: Bld text identifies menu names, menu ptins, items yu can click n the screen, file names, flder names, and keybard keys. Curier New fnt identifies cde and text that appears n the cmmand line. Bld Curier New identifies cmmands that yu are required t type in. 1.4 Technical supprt If Technical Supprt is required, Ascertia has a dedicated supprt team prviding debugging assistance, integratin assistance and general custmer supprt. Ascertia Supprt can be accessed in the fllwing ways: Supprt Website Supprt Knwledge base supprt@ascertia.cm In additin t the free supprt service describe abve, Ascertia prvides frmal supprt agreements with all prduct sales. Please cntact sales@ascertia.cm fr mre details. A Prduct Supprt Questinnaire shuld be cmpleted t prvide Ascertia Supprt with further infrmatin abut yur system envirnment. When requesting help, it is always imprtant t cnfirm: System Platfrm details. ADSS Server versin number and build date. Details f specific issue and the relevant steps taken t reprduce it. Database versin and patch level. Prduct lg files Ascertia Limited Cmmercial-in-Cnfidence Page 3 f 31

4 2 ADSS G>Sign Service Overview ADSS G>Sign Service empwers business applicatins t perfrm dcument signing n user s machines using the credentials held either lcally by the user r n the server. In additin, ADSS G>Sign Service enables business applicatins t display PDF dcuments in a secure manner using a server-side HTML-based G>Sign Viewer. It is fully integrated with G>Sign PDF signing capabilities. This viewer allws users t view a dcument in flattened mde thus prviding a What Yu See Is What Yu Sign (WYSIWYS) prperty. Figure 1 - ADSS G>Sign Service & Business Applicatin Interactin The diagram shws hw ADSS G>Sign Service and business applicatin interact with each ther. The high-level prcess is as fllws: An applicatin web page sends a request t the ADSS G>Sign Service specifying which prfile it wishes t use, the data t be signed and ther ptinal parameters. The ADSS G>Sign Service receives the request and respnds t web page with the relevant JavaScript cde. The web page receives the JavaScript cde and embeds it ready fr the user. If the dcument is PDF r Wrd frmat and viewing has been requested, then the user can see the dcument and sign it using either lcally-held r server-held signing key. If the dcument is anther type r viewing was nt requested, then the applicatin must take respnsibility fr infrming the user what it is that they are abut t sign and G>Sign asks the user t sign. As part f the signing prcess, ADSS G>Sign Service can use the backend ADSS Server Services, t perfrm varius tasks including creating server-side signatures, verify lcal signatures created by the user and t enhance basic signatures int lng-term signature frmats. Furthermre, if G>Sign Service is used fr key generatin and certificatin, then ADSS Server can issue the certificates and securely stre the user s private key. 2.1 G>Sign Client Apps The tw types f G>Sign Client Apps available are G>Sign Desktp and G>Sign Applet. The G>Sign Client Apps have been designed t enable busy, nn-technical peple t easily and quickly sign dcuments and data using client held signing keys. It wrks with mdern web brwsers Ascertia Limited Cmmercial-in-Cnfidence Page 4 f 31

5 t allw citizens and businesses t g green by eliminating paper-based apprvals, and thereby aviding pstage/curier, handling, strage and shredding csts. The G>Sign Client Apps are capable f creating signatures using lcally-held signing keys (e.g. n a smartcard / secure USB tken via PKCS#11 r sftware managed keys accessed thrugh Windws CAPI r Mac Keychain keystre). As an advanced ptin G>Sign Client Apps can generate keys pairs and certificate signing requests (PKCS#10), which can be certified by ADSS Server. The G>Sign Client Apps can sign dcuments using keys and certificates created n and stred by ADSS Server in PFX (PKCS#12) frmat. The user needs t prvide the crrect PFX passwrd t sign a dcument r data bject. Business applicatins can lcally authenticate users e.g. using multi-factr authenticatin, befre requesting ADSS Server t return their respective raming credentials G>Sign Desktp G>Sign Desktp is a new middleware applicatin that allws users t sign the dcuments using lcally held signing keys withut using signed Java Applets. Brwser vendrs are discntinuing supprt fr Java Applets, as Ggle Chrme has dne already and thus G>Sign Desktp prvides a gd alternative slutin. G>Sign Desktp is a small utility applicatin that runs n the user s desktp and all cmmunicatin is via JavaScript within the web brwser sessin G>Sign Applet G>Sign Applet is a secure Java based applet plugin that is autmatically dwnladed and ran within a user s web brwser and prvides a true zer-ft print signing experience. Nte the Applet relies n a lcal deplyment f a Java Runtime Envirnment and the use f NPAPI. Sme ppular web brwsers still supprt Java Applets and NPAPI but Ggle Chrme has withdrawn supprt and thers will fllw. Micrsft Edge des nt supprt fr Java G>Sign Client Apps Benefits The main benefits f G>Sign Client Apps are: They wrk as part f a web-brwser envirnment and the assciated web pages can be easily updated and functinality immediately rlled-ut. They tightly cntrl user interactins with the dcument thrugh simple user interface with all elements being cntrlled s the user can nly perfrm the actins which are wanted. They enable digital certificate filtering t allw the business t cntrl which certificates the user can chse t sign with. Supprt fr central / remte signing t be used as an alternative t using lcal keys and certificates ADSS Server hashes the data and just the hash (typically SHA-256) is passed t the G>Sign Client Apps. The G>Sign Service manages signature frmatting, calling an apprpriate verificatin prfile t check the signature and certificate status and creating the crrect frmat f signature. Frmats supprted including PDF, MS Wrd, XML and PKCS#7 / CMS. Time-stamped, lng-term enabled digital signatures including ETSI PAdES, XAdES, and CAdES prfiles. Fr PDFs full supprt is prvided fr PDF CDS and AATL signatures. Furthermre, visible and invisible signatures are supprted, new and existing signature fields can be signed and certify signing and permissins are all available as ptins. Supprt fr raming credentials, whereby signing keys are held in a secure cntainer n ADSS Server and prvided t the G>Sign Client Apps at the time f signing. Supprt fr hardware signature tablet devices fr drawing hand signatures e.g. Wacm, Signtec etc. Ascertia Limited Cmmercial-in-Cnfidence Page 5 f 31

6 Supprts a wide variety f HTML5 brwsers and platfrms. Fr mre infrmatin, see the System Requirements sectin System Requirements G>Sign Desktp is supprted n the fllwing perating systems and web brwsers: Windws 10, Windws 8 and 8.1, Windws 7, Mac OS X 10.4 Tiger and abve Internet Explrer 9.0+, Ggle Chrme 26.0+, Firefx 20.0+, Safari 5.0+, Micrsft Edge 20.0 n Windws G>Sign Applet is supprted n the fllwing perating systems and web brwsers (assuming the latest Java Runtime Envirnment is installed): Windws 10, Windws 8 and 8.1, Windws 7, Linux, Mac OS X 10.4 Tiger and abve Internet Explrer 9.0+, Firefx 20.0+, Safari 5.0+ n Windws, Safari n Mac, Opera Latest Java Runtime Envirnment 1.8.0_66 r latest When the G>Sign Applet is used and the Java plugin is nt enabled, it alerts the user with apprpriate message and prvides a web link t install the latest versin f Java Runtime Envirnment Supprted Key Stres These cryptgraphic key stres, used t access the signing keys, are supprted: MS CAPI/CNG (Windws) Mac Keychain keystre n Mac OS X and abve PKCS#11 fr hardware-based tkens Specific eid card implementatins (these are separately licensed client specific keystre implementatins e.g. the Emirates eid card, Belgian eid card via IntIT middleware) Ascertia Raming Keys 2.2 G>Sign Viewer The G>Sign Viewer supprts PDF and Wrd frmat dcuments and prvides a number f features t aid the user experience such as page navigatin, placing blank signature fields, signing peratins, and dcument access right enfrcement. G>Sign Viewer has an advanced viewer which images the dcument in stages a few pages at a time as needed. This allws large dcuments t be quickly pened and viewing started rather than waiting fr the whle dcument t be imaged. Ascertia Limited Cmmercial-in-Cnfidence Page 6 f 31

7 2.2.1 G>Sign Viewer Benefits The keys features f G>Sign Viewer are: Figure 2 - G>Sign Viewer Example Users can view and navigate bth PDF and MS Wrd dcuments that are prvided frm the server r the user s lcal desktp, the dcument images are shwn within the user s brwser. Data leakage prtectin is prvided with plicy cntrlled dwnlad and print ptins as defined within the G>Sign Service prfile. The user can be allwed t create ne r mre blank signature fields in a PDF dcument. Existing blank signature fields and signature lines in PDF and MS Office Wrd dcuments can be signed. The business applicatin can assciate a signature field fr a user t sign, and thus can cntrl hw and where the user signs the dcument. Existing signatures can be verified by clicking the target signature field (the verificatin is perfrmed by the ADSS Server Verificatin Service making Trusted CA management simple and transparent t the user). PDF frm filling is supprted. The GUI and user visible messages supprt lcalizatin. The business applicatin can cntrl which buttns are visible n the G>Sign Viewer tlbar. Ascertia Limited Cmmercial-in-Cnfidence Page 7 f 31

8 3 ADSS G>Sign Service Integratin Business applicatins can integrate with ADSS G>Sign Service using standard HTTP messages. The business applicatin sends an HTTP POST request t the G>Sign Service, which cntains specific request headers and ptinally the dcument t be signed. If required, the dcument t be signed is placed in the HTTP POST request bdy. ADSS G>Sign Service respnds with standard HTML and JavaScript cde. The business applicatin nw embeds this in its wn web page where the user will be asked t sign. This table shws the request headers that can be used in the HTTP POST request: Header Name Mandatry Descriptin ORIGINATOR_ID YES The client ID, which must be registered in ADSS Server Client Manager, and authrised t use ADSS G>Sign Service. USER_ID NO ADSS G>Sign Service uses this parameter as a key alias if using server-side keys managed by ADSS Server (i.e. fr server-side signing). Keys generated thrugh Key Manager can be used fr server-side signing. When a raming key is used fr client-side signing ADSS G>Sign Service uses this parameter t lcate the raming key cntainer frm ADSS Certificatin Service. In the case f client side signing (when OS native API r PKCS#11 devices are used) this parameter is ptinal. KEY_PASSWORD NO ADSS G>Sign Service uses this parameter as a key passwrd fr the server-side keys held by ADSS Server (in PKCS#12/PFX frmat). This parameter is mandatry when a raming key is generated. Nte fr Key Manager generated keys the value f this parameter is NO_PASSWORD and is a mandatry parameter. USER_NAME NO Used fr %Signed_By% field in server-side and mbile signing (used in PDF signature appearance). PROFILE_ID NO Defines G>Sign prfile identifier t be used by the web applicatin. TRANSACTION_ID NO Defines the transactin identifier. This parameter is used in cnjunctin with parameter REUSE_GOSIGN_SESSION t save and recall the state f the dcument at G>Sign Service. If the business applicatin needs t perfrm multiple signing peratins withut uplading the dcument multiple times, it is a mandatry parameter. REUSE_GOSIGN_SESS ION NO Indicates that the dcument state at G>Sign Service must be maintained if multiple G>Sign prfiles are utilized. Pssible values f this parameter are true and false. If true, then Ascertia Limited Cmmercial-in-Cnfidence Page 8 f 31

9 Header Name Mandatry Descriptin dcument state is preserved and therwise nt. If the business applicatin needs t perfrm multiple signing peratins withut uplading the dcument multiple times, it is a mandatry parameter. FIELD_COORDS NO Used t create empty signature field(s) in the PDF dcument and signature appearance used at signing time. The value f this parameter is a cmmaseparated sequence representing X1, Y1, X2, Y2, page#, empty signature field name and signature appearance ID, e.g. 10,10,100,200,1,Signature1,appearance_id Multiple values are separated by & characters, e.g. 10,10,100,200,1,Signature1,appearance_id1&10 0,300,600,700,1,Signature2,appearance_id2 Nte the prvided signature appearance IDs must exist in the ADSS PDF Signature Appearances. FIELD_NAME NO Represent an empty signature field name/signature line, and its value verrides the equivalent field name/signature line, as cnfigured in G>Sign prfile. If set this will prevent the user frm signing in any ther field. If the business applicatin wants the user t nly sign the specific field, then this parameter is mandatry. Shuld the business applicatin want the user t sign multiple fields then cmma-separated field names are set in this parameter, e.g. Signature1, Signature2, Signature3. Multiple field signing is nly supprted fr PDF dcuments using G>Sign Viewer. Fr MS Office Signing bth the suggested signer address and setup ID fr the signature line are supprted. SIGNATURE_APPEARA NCE NO Signature appearance ID fr PDF dcument signing. e.g. appearance_id. Nte the prvided signature appearance ID must exist in the ADSS PDF Signature Appearances. DOCUMENT_ID NO Defines the dcument identifier prvided by the business applicatin. This is shwn t the user in G>Sign Viewer. Created and used by the business applicatin fr dcument management purpses. DOCUMENT_NAME NO Name f the dcument that is displayed t the user in G>Sign Viewer. This parameter is mandatry fr MS Office signing. Ascertia Limited Cmmercial-in-Cnfidence Page 9 f 31

10 Header Name Mandatry Descriptin If Dcument Cnversin feature is enabled in G>Sign prfile, then this parameter is mandatry. The value f this parameter must be the name f the dcument including its extensin, e.g. cntract.dcx. The fllwing file frmats can be cnverted by G>Sign Service:.dc,.dcx,.xls,.xlsx,.ppt,.pptx, dt, sxw,.rtf,.txt,.ds,.csv, tsv and.tif. Created and used by the business applicatin fr dcument management purpses. FILTER_SUBJECT_DN_ CONTAINS FILTER_ISSUER_DN_C ONTAINS FILTER_SIGNATURE_A LGO_CONTAINS FILTER_POLICY_OID_C ONTAINS NO NO NO NO String value upn which available certificates will be filtered n when the lcal key stre is used fr client side signing. Only thse certificates whse subject DN value matches the prvided string value will be listed. Pssible values are: CN, OU, O, C e.g. CN=Test Certificate, O=Ascertia This will list all the certificates frm the lcal key stre that have a cmmn name Test Certificate and rganizatin Ascertia in the certificate s Subject DN. String value upn which available certificates will be filtered n when the lcal key stre is used fr client side signing. Only thse certificates whse issuer DN value matches the prvided string value will be listed. Multiple issuer DN values can be specified using a ~ separated list. Pssible values are: CN, OU, O, C e.g. CN=Test Issuer, O=Ascertia, CN= Test Issuer2, O=Ascertia This will list all the certificates frm the lcal key stre that have a cmmn name Test Issuer and rganizatin Ascertia, r, that have a cmmn name Test Issuer2 and rganizatin Ascertia in the certificate s issuer DN. String value upn which available certificates will be filtered n when the lcal key stre is used fr client side signing. Only thse certificates whse signature algrithm(s) value matches the prvided string value will be listed. Multiple signature algrithms can be specified using a cmma-separated list, e.g. SHA1WithRSA,SHA256WithRSA,SHA384WithR SA,SHA512WithRSA This will list all the certificates frm the lcal key stre whse certificate signature algrithm matches ne f the stated values. String value upn which available certificates will be filtered n when lcal key stre is sued fr client side signing. Only thse certificates whse Ascertia Limited Cmmercial-in-Cnfidence Page 10 f 31

11 Header Name Mandatry Descriptin certificate plicy OID value matches the prvided string value will be listed. Multiple certificate plicy OIDs can be specified using a cmmaseparated list, e.g This will list all the certificates frm the lcal key stre whse certificate plicy extensin cntains the stated plicy OID(s). FILTER_KU_CONTAINS NO String value upn which available certificates will be filtered n when lcal key stre is sued fr client side signing. Only thse certificates whse certificate Key Usage value matches the prvided string value will be listed. Multiple Key Usage definitins can be specified using a cmmaseparated list. Pssible values are: digitalsignature, nnrepudiatin, keyencipherment, dataencipherment, keyagreement, keycertsign, crlsign, encipheronly, decipheronly This will list all the certificates frm the lcal key stre whse certificate Key Usage extensin cntains ne r mre f thse stated. FILTER_EKU_CONTAIN S FILTER_SHOW_EXPIRE D_CERTIFICATES FILTER_SHOW_QUALIF IED_CERTIFICATES NO NO NO String value upn which available certificates will be filtered n when lcal key stre is sued fr client side signing. Only thse certificates whse certificate Extended Key Usage value matches the prvided string value will be listed. Multiple Extended Key Usages definitins can be specified using a cmma-separated list. The pssible values are: clientauth, prtectin,smartcardlgn This will list all the certificates frm the lcal key stre whse certificate Extended Key Usage extensin cntains ne r mre f thse stated. Blean value t indicate if a filtered list f certificates shuld include expired certificates r nt. Pssible values are true r false. Blean value t indicate if a filtered list f certificates shuld include qualified certificates r nt. Pssible values are true r false. USER_LANGUAGE NO Defines the preferred language fr G>Sign Desktp, G>Sign Applet and G>Sign Viewer GUI and messages. Pssible values are en, fr, de, etc. If this parameter is nt specified, then default English language is used. If the business applicatin wishes t display the messages in different languages based n user preferences, then this parameter is mandatry. T change the language preference, see Sectin Ascertia Limited Cmmercial-in-Cnfidence Page 11 f 31

12 Header Name Mandatry Descriptin 3.4. REQUEST_TYPE NO Define the type f the request that is sent t G>Sign Service. This parameter is used in cnjunctin with TRANSACTION_ID request parameter. When the business applicatin wishes t send the hash f the dcument t G>Sign Service instead f the whle dcument then this parameter is mandatry. Currently, the nly accepted value fr this parameter is SET_HASH. When this parameter is used the business applicatin must hash the dcument and send the resulting value in the bdy f the HTTP request instead f the actual dcument. Currently this feature is nly supprted fr PDF dcuments When the single page applicatin wants t embed G>Sign Applet then this parameter becmes mandatry. The nly pssible value fr this parameter is EMBED_SPA. FINISH_URL NO Defines the URL hsted by the business applicatin t which G>Sign Viewer redirects the user t when they press the tlbar Finish buttn. SIGNING_REASON NO Signing reasn included in a signature. SIGNING_LOCATION NO Signing lcatin included in a signature. SIGNER_CONTACT_IN FORMATION NO Signer cntact infrmatin included in a signature. COMPANY_LOGO NO Defines whether r nt t include the assciated cmpany lg in a visible PDF signature. HAND_SIGNATURE_IM AGE NO Defines whether r nt t include the hand signature image in a visible PDF signature. CITY NO Defines the city signed attribute in XAdES signatures. POSTAL_CODE NO Defines the pstal cde signed attribute in CAdES and XAdES signatures. COUNTRY NO Defines the cuntry signed attribute in CAdES and XAdES signatures. STATE_OR_PROVINCE NO Defines the state r prvince signed attribute in CAdES and XAdES signatures. COMMITMENT_TYPE_I NDICATION NO Defines the cmmitment made by the signer. It is used as signed attribute in CAdES and XAdES signatures. It is used in PAdES signatures when explicit signature plicy is set t ON in the signing prfile. Ascertia Limited Cmmercial-in-Cnfidence Page 12 f 31

13 Header Name Mandatry Descriptin SIGNER_ROLE NO Defines the signer rle wh generated the signature. It s used as a signed attribute in PAdES, CAdES and XAdES signatures. DATA_OBJECT_FORMA T SIGNING_ELEMENT_N AME NO NO Defines the dcument frmat. It s used as a signed attribute in PAdES, CAdES and XAdES signatures. This parameter defines the XML elements t be signed, these can a list f tag r element names r an XPath expressins, e.g. CntractName,CntractDate r //CntractName,//CntractDate Table 1 - ADSS G>Sign Service HTTP Request Headers When G>Sign Viewer is used the business applicatin des nt need t use the G>Sign Client Apps JavaScript methds and hence the integratin is a simple prcess. Hwever, if the business applicatin des nt use the G>Sign Viewer it must utilise the JavaScript methds described in Sectin 4 t interact with the G>Sign Client Apps. 3.1 G>Sign Service Request (JSP Example) Belw is an example JSP web page cde that details hw the business applicatin sends a request t ADSS G>Sign Service. ADSS G>Sign Service returns the HTML and JavaScript cde snippet that is embedded within the web page and subsequently rendered by the web brwser that allws the interactin with G>Sign Client Apps. <html> <head> <!-- Replace the lcalhst with the hstname/ip address where the ADSS G>Sign Service is running - -> <script language="javascript" src=" type="text/javascript"></script> <script language="javascript" src=" min.js" type="text/javascript"></script> </head> <bdy> <% String str_dcname = getservletcntext().getrealpath("/") + "/data/test_input_unsigned.pdf"; FileInputStream fis = new FileInputStream(str_dcName); byte[] m_bytearrdcument = new byte[fis.available()]; fis.read(m_bytearrdcument); fis.clse(); URL bj_url = new URL(" HttpURLCnnectin bj_http = (HttpURLCnnectin) bj_url.pencnnectin(); bj_http.setdoutput(true); bj_http.setrequestmethd("post"); Ascertia Limited Cmmercial-in-Cnfidence Page 13 f 31

14 bj_http.setrequestprperty("cntent-length", m_bytearrdcument.length + ""); bj_http.setrequestprperty("cntent-type", "applicatin"); bj_http.setrequestprperty("originator_id", "samples_test_client"); bj_http.setrequestprperty("profile_id", "adss:gsign:prfile:001"); OutputStream bj_ut = bj_http.getoutputstream(); bj_ut.write(m_bytearrdcument); if (bj_http.getrespnsecde() == 200) { BufferedReader bj_br = new BufferedReader(new InputStreamReader(bj_http.getInputStream())); String str_line = ""; while ((str_line = bj_br.readline())!= null) { } ut.println(str_line); bj_br.clse(); } else { } %> ut.println("http Cde : " + bj_http.getrespnsecde()); bj_ut.clse(); </bdy> </html> 3.2 G>Sign Service Request (ASP.NET / C# Example) Belw is an example ASP.NET (C#) cde that details hw the business applicatin sends a request t ADSS G>Sign Service. ADSS G>Sign Service returns the HTML and JavaScript cde snippet that is embedded within the web page and subsequently rendered by the web brwser that allws the interactin with G>Sign Client Apps. String str_filepath = Server.MapPath("~/data/test_input_unsigned.pdf"); byte[] dcumentbytes = File.ReadAllBytes(str_filePath); HttpWebRequest request= (HttpWebRequest) HttpWebRequest.Create(" request.methd = "POST"; request.headers.add("originator_id", "samples_test_client"); request.cntentlength = dcumentbytes.length; request.cntenttype = "applicatin"; request.headers.add("profile_id", "adss:gsign:prfile:001"); Stream stream = request.getrequeststream(); stream.write(dcumentbytes, 0, dcumentbytes.length); HttpWebRespnse httprespnse = (HttpWebRespnse)request.GetRespnse(); if (httprespnse!= null) { Ascertia Limited Cmmercial-in-Cnfidence Page 14 f 31

15 } StreamReader str = new StreamReader(httprespnse.GetRespnseStream()); string viewer = str.readtend(); GSignViewer.InnerHtml = viewer; The assciated web page shuld cntain the required JavaScript imprts t allw the received HTML and JavaScript cde snippet t functin crrectly. Fr example: <!-- Replace lcalhst with the hstname/ip address where the ADSS G>Sign Service is running --> <script language="javascript" src=" type="text/javascript"></script> <script language="javascript" src=" min.js" type="text/javascript"></script> 3.3 Hw Business Applicatins Receive Signed Dcuments The business applicatin requests that ADSS G>Sign Service returns the signed dcument. It sends an HTTP POST request with the necessary request headers. ADSS G>Sign Service prcesses the request and respnds back t the business applicatin with an HTTP respnse cntaining the header infrmatin and the signed dcument. The signed dcument is placed in the bdy sectin f the HTTP respnse. The fllwing header is sent in the HTTP Pst request frm the business applicatin t initiate the request: Header Name Mandatry Descriptin TRANSACTION_ID YES Defines the transactin identifier fr ADSS G>Sign Service t prcess. Table 2 - HTTP Request Headers t Initiate the G>Sign Request The fllwing headers are sent in the HTTP respnse frm the ADSS G>Sign Service: Header Name Mandatry Descriptin TRANSACTION_ID YES Defines the transactin identifier fr the business applicatin. Nte this matches what was sent in the request. USER_ID NO Defines the user identifier if that was prvided by the business applicatin in the initial ADSS G>Sign Service request. DOCUMENT_ID NO Defines the dcument identifier that was prvided by the business applicatin in the initial ADSS G>Sign Service request. SESSION_ID NO Defines the user sessin identifier if it was prvided by the business applicatin in the initial ADSS G>Sign Service request. Nte it may nt have been sent in the initial request. GOSIGN_RESPONSE_STATU S Generic status identifier fr the transactin. Pssible values are: Success, Failure, Pending, and Declined. Ascertia Limited Cmmercial-in-Cnfidence Page 15 f 31

16 Header Name Mandatry Descriptin MESSAGE Message string as sent by the G>Sign Service. Generally, this is nly used when there is an errr. Table 3 - HTTP Respnse headers frm G>Sign Service Signed Dcument Dwnlad Request (JSP Example) Belw is an example JSP web page cde that details hw the business applicatin makes a request ADSS G>Sign Service t retrieve a signed dcument: <% URL bj_url = new URL(" HttpURLCnnectin bj_http = (HttpURLCnnectin) bj_url.pencnnectin(); bj_http.setdoutput(true); bj_http.setrequestmethd("post"); bj_http.setrequestprperty("cntent-type", "text/plain"); // Gets the transactin identifier frm the request parameter bj_http.setrequestprperty("transaction_id", request.getparameter("gsign_transactin_id")); %> byte[] m_bytearrdcument = null; if (bj_http.getrespnsecde() == 200) { InputStream = bj_http.getinputstream(); ByteArrayOutputStream buffer = new ByteArrayOutputStream(); int nread; byte[] data = new byte[1024]; //reads the signed dcuments bytes frm the HTTP respnse bdy. while ((nread = inputstream.read(data, 0, data.length))!= -1) { } buffer.write(data, 0, nread); buffer.flush(); m_bytearrdcument = buffer.tbytearray(); buffer.clse(); } else { } ut.println("http Cde : " + bj_http.getrespnsecde()); Signed Dcument Dwnlad Request (ASP.NET / C# Example) Similarly, belw is an example ASP.NET (C#) web page cde that details hw a business applicatin makes a request t ADSS G>Sign Service t retrieve the signed dcument: HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(" Ascertia Limited Cmmercial-in-Cnfidence Page 16 f 31

17 request.methd = "POST"; request.cntenttype = "text/plain"; request.headers.add("transaction_id", str_id); HttpWebRespnse httprespnse = (HttpWebRespnse)request.GetRespnse(); byte[] bytearr_dc = null; if (httprespnse!= null) { // reads the signed dcument bytes frm the HTTP respnse bdy. bytearr_dc = ReadBytesFrmStream(httprespnse.GetRespnseStream()); } 3.4 Language Preference Settings G>Sign Desktp, G>Sign Applet and G>Sign Viewer all supprt lcalisatin. The labels and messages shwn by them can be displayed in different languages. T read mre abut hw the business applicatin can instruct G>Sign Service t use different language, and fr a list f supprted cnfiguratin parameters, fllw this link: Ascertia Limited Cmmercial-in-Cnfidence Page 17 f 31

18 4 G>Sign Client Apps JavaScript Library If the business applicatin is nt using G>Sign Viewer, then HTML and JavaScript cde is required t cnnect with G>Sign Client Apps (i.e. G>Sign Desktp and G>Sign Applet). ADSS G>Sign Service prvides a JavaScript library (adss_gsign.js) that cntains a number f JavaScript functins that are used t prvide custm cnfiguratins fr G>Sign Client Apps, as well as t perfrm different actins using G>Sign Client Apps. 4.1 Pre-prcessing Functins GSign_PstInit() The business applicatin must implement this JavaScript functin in the same web page where the HTML and JavaScript cde snippet received frm G>Sign Service is embedded. This methd is autmatically called implicitly nce the G>Sign Client Apps are initialized. In this methd business applicatins can set additinal cnfiguratins fr G>Sign Client Apps, e.g. set the HTML frm name and HTML Select cntrl name, i.e. t shw a drpdwn list by calling the GSign_SetFrmName() and GSign_SetCertificateListName() respectively. This methd can als be used by the business applicatin t perfrm any custm functinality befre the user signs a dcument, e.g. displaying instructins r a guidance message. The fllwing functins must be called in the bdy f the GSign_PstInit() functin. GSign_SetFrmName(frmName) Set the name f the HTML frm which cntains the cntrls accessed by G>Sign Client Apps. GSign_SetFileChserName(fileChserName) Set the frm field name fr the HTML File cntrl t read the file frm the user machine. GSign_SetCertificateListName(GSignCertificateList) Set the frm field name fr the HTML List cntrl which wuld be ppulated by G>Sign Apps with the aliases f the certificates laded frm cnfigured keystre. GSign_SetSigningReasn(signingReasn) Set the signing reasn attribute fr a PDF signature. GSign_SetSigningLcatin(signingLcatin) Set the signing lcatin attribute fr a PDF signature. GSign_SetCntactInf(cntactInf) Sets the cntact inf attribute fr a PDF signature. GSign_SetCertificateAlias(certAlias) Set the alias f the certificate during raming key registratin. Alternatively, this value culd be sent by G>Sign Desktp/G>Sign Applet t the G>Sign prcessr fr server side dcument signing. GSign_SetSubjectDN(subjectDN) Set Subject DN fr the certificate that will be generated during raming key registratin. GSign_SetAppletDialgClrs(titleClr,titleTextClr,backgrundClr,textClr,buttn stextclr) Instruct G>Sign Client Apps t use the prvided clurs in the passwrd/pin dialgs (PKCS#11, Raming key, eid card etc.). The value f each clur must be in RGB frmat, e.g. title clur value shuld be specified as 200:200:200. GSign_SetAppletDialgTextFnt(fntName) Instruct G>Sign Client Apps t display the text in the prvided fnt in passwrd/pin dialgs (PKCS#11, Raming key, eid card etc.), e.g. Tahma. Fr mre infrmatin abut the supprted fnt names in Java, see the link belw: Ascertia Limited Cmmercial-in-Cnfidence Page 18 f 31

19 GSign_SetInputDcument(inputDcTBeSigned) Used t directly pass the base64 encded cntents f the dcument t be signed t G>Sign Client Apps. GSign_SetInputDcumentFieldName(frmFieldFrInputDc) Set the HTML frm field name cntaining the base64 encded cntents f the input dcument t be signed by G>Sign Client Apps. GSign_SetResultFilePstfix(pstfix) Set the result file pstfix if the utput dcument is t be stred lcally n the user machine. GSign_SetOutputDcumentName(utputDcumentName) Set the file name if the utput dcument is t be stred lcally n the user machine. GSign_SetOutputDcumentFieldName(frmFieldFrSignedDc) Set the HTML frm field name where the base64 encded cntents f the signed dcument can be set by G>Sign Client Apps. GSign_Base64Encde(cntentTBeEncded) Utility functin t base64 encde the textual r XML frmatted cntents. GSign_Base64Decde(cntentTBeDecded) Utility functin t decde the base64 encded textual r XML frmatted cntents. GSign_ShwCertificates() This functin ppulates a drp dwn cntrl with certificates fetched frm a cnfigured keystre based n specified filter criteria. The web applicatin s drp dwn cntrl shuld use an HTML Select cntrl and the name f the field shuld be prvided using the functin GSign_SetCertificateListName. NOTE: When using G>Sign Desktp, a callback functin name must be passed as an argument t this functin. The cde snippet fr the callback functin shuld lk like this: GSign_ShwCertificates(functin(errr){ if(errr!= null){ alert(errr.errrcde +''+ errr.message); } }); GSign_LadCertificates() This functin lads the certificates in the backgrund frm the cnfigured keystre. This is used when it is nt required t shw the certificates in a drp dwn list. If nly ne certificate is laded, then it wuld autmatically be used during the signing peratin but if there are multiple certificates laded then the first certificate frm the list wuld be used. NOTE: When using G>Sign Desktp, a callback functin name must be passed as an argument t this functin. The cde snippet fr the callback functin shuld lk like this: GSign_LadCertificates(functin(errr){ if(errr!= null){ alert(errr.errrcde +''+ errr.message); } }); Ascertia Limited Cmmercial-in-Cnfidence Page 19 f 31

20 GSign_SetCallbackFunctin(callbackFunctin) This methd instructs G>Sign Client Apps t invke the business applicatin call-back functin nce the signing peratin is dne. The call-back functin will set an errr bject if an errr ccurred during the signing prcess. Errr bject cntains an errr cde and message. If there is n errr, then errr bject will be null. This methd must be called befre the GSign_Prcess() functin. The cde snippet fr the callback functin lks like this: functin callbackfunctin(errr){ if(errr!= null){ alert(errr.errrcde +''+ errr.message); } } 4.2 Prcessing Functins GSign_Prcess() Starts the dcument signing prcess during which the user may be asked t prvide a PIN r passwrd t access the lcally held signing key. Once signature prcessing is cmpleted the cnfigured callback functin is autmatically invked. The callback functin that is invked shuld have been cnfigured using the functin GSign_SetCallbackFunctin. 4.3 Pst Prcessing Functins GSign_GetTransactinId() This methd is nly applicable when G>Sign Client Apps are embedded in the web page. It returns the transactin identifier that will be used by the business applicatin t retrieve the signed dcument frm ADSS G>Sign Service. GSign_GetErrrCde() If the requested peratin fails, then this methd can be called t retrieve the errr cde. Each errr cde is mapped t a readable errr message string frm the apprpriate messages language file. GSign_GetErrrReasn() If the requested peratin fails, then this methd can be called t retrieve the readable errr message string frm apprpriate messages language file. GSign_GetRaTransactinId() Return Transactin ID generated by a Registratin Authrity(RA) when G>Sign Service sends a certificate signing request t RA. It is a mandatry request parameter in G>Sign Service in rder t retrieve the generated certificate. GSign_GetOutputDcument() Return the base64 encded cntents f the signed dcuments. GSign_ResetApplet() Reset applet parameters which were set prir t the signing peratin. This functin shuld be called when a secnd signing peratin is required, i.e. a secnd signatry, withut reinitializing/relading the applet after the first signing peratin. Ascertia Limited Cmmercial-in-Cnfidence Page 20 f 31

21 5 G>Sign Viewer JavaScript Functins G>Sign Viewer prvides several JavaScript functins that facilitate the business applicatin t retrieve infrmatin frm the G>Sign Viewer. windw.pdfviewer.gettransactinid() Return the transactin identifier that will be used by the business applicatin t get the signed dcument frm ADSS G>Sign Service, r used in cmmunicatin with ADSS G>Sign Service fr ther functinality. GSign_NtifyStateChange(status_cde) Smetimes business applicatins wish t perfrm sme custm functinality as sn as an peratin is perfrmed by a user within G>Sign Viewer. Fr example, G>Sign Viewer ntifies the hst web page f the business applicatin that a signature field has been created, signed r a frm field has been saved. In such scenaris the business applicatin can implement this functin in the hst webpage in rder t get a ntificatin update n the dcument state change. The pssible values fr a status_cde argument passed by G>Sign Viewer are: changed_incmplete User didn t fill all the mandatry fields in the dcument) changed The user created signature field(s) r filled the frm field(s) signed A signature field is signed by the user declined User pressed the Decline buttn errr Sme errr ccurred The cde snippet fr this functin shuld lk like this: functin GSign_NtifyStateChange(status_cde){ if(status_cde == changed_incmplete ){ alert( All mandatry fields in the PDF frm are nt filled ); }else if(status_cde == changed ){ alert( Signature field(s) created r/and frm field(s) saved ); }else if(status_cde == signed ){ alert( A signature field is signed by user ); } else if(status_cde == errr ){ alert( Sme errr ccurred ); } } Clicking the Finish buttn in G>Sign Viewer tlbar redirects the brwser t the business applicatin webpage address cnfigured in G>Sign Service prfile r passed as FINISH_URL parameter t G>Sign Service. The business applicatin webpage receives the fllwing query parameters frm G>Sign Viewer, which it can use t cntinue further prcessing at business applicatin end: gsign_transactin_id The value f this parameter is a unique transactin Id generated by G>Sign Service fr this transactin which can be used t dwnlad the updated r signed dcument frm G>Sign Service. Ascertia Limited Cmmercial-in-Cnfidence Page 21 f 31

22 gsign_status The value f this parameter prvides the status f the last peratin perfrmed by user in G>Sign Viewer. The pssible values f this parameter are: unchanged The user made n changes r actins dcument. changed_incmplete The user didn t fill all the mandatry fields in the dcument. changed The user created signature field(s) r filled the frm field(s). signed A signature field is signed by the user. declined User pressed the Decline buttn. gsign_message If user declined the transactin and prvided a declining reasn then this parameter prvides the declining reasn t the business applicatin. Ascertia Limited Cmmercial-in-Cnfidence Page 22 f 31

23 6 Example Scenaris & Dems fr G>Sign Service ADSS Client SDK (Java and.net) ships with a number f web based G>Sign Service dems, which highlight hw ADSS G>Sign Service can be used in different business scenaris. These dems shw hw ADSS G>Sign Service prfiles prvide a pwerful platfrm fr business applicatins t easily implement cmplex signing prcesses. Fr infrmatin n hw t cnfigure the different ADSS G>Sign Service Prfiles, see the ADSS Server Admin Manual: T run G>Sign dem applicatin withut any changes, ADSS Server, G>Sign Desktp and ADSS Client SDK (Java/.NET) must be installed n the same machine. In additin, the web brwser shuld be accessed frm the same machine where bth ADSS Server and ADSS Client SDK (Java/.NET) are installed. T install G>Sign Desktp see the installatin guide under <ClientSDK>/GSign/Desktp/dcs/Ascertia-G-Sign-Desktp-Installatin-Guide.pdf If ADSS Server and ADSS Client SDK (Java/.NET) are installed n different machines, then G>Sign dem pages must be mdified t specify the address f the ADSS Server machine and the web brwser accessed frm ADSS Client SDK machine. Furthermre, G>Sign Service Address cnfiguratin item must be updated t reflect the IP address r hst name f ADSS Server machine. Once G>Sign dem web applicatin has been deplyed successfully, the user can access each dem by pening the available_dems.html file, which are lcated under <ClientSDK>/GSign/Dem flder. All the G>Sign dems can be tested with either the applet r desktp client by setting the apprpriate cnfiguratin item in the respective G>Sign prfile in the ADSS Server Cnsle as shwn in this figure. Ascertia Limited Cmmercial-in-Cnfidence Page 23 f 31

24 Figure 3 - G>Sign Dem Parkling Page The sectins belw explain each dem individually in detail and prvide infrmatin abut hw the dem wrks, which cnfiguratins are applied in G>Sign prfile, and where the surce files f a particular dem are available. 6.1 Dcument Signing Dems G>Sign Viewer PAdES Part 2, Lng-term Signature with Server-side Keys This is anther cmmn usage mde, which uses G>Sign Viewer t view the dcument. The signing f the dcument is perfrmed by ADSS Server. G>Sign Viewer is nly used t display the PDF dcument, create blank signature fields and sign afrementined fields using server side keys held by ADSS Server. This dem uses the sample G>Sign prfile (adss:gsign:prfile:004) cnfigured in the ADSS G>Sign Service. The user can access this dem using the fllwing URL(s): (Java) (.Net) The surce cde fr web pages used in this dem can be fund in the ADSS Client SDK under the fllwing path: <ClientSDK>/GSign/Dem/jakarta-tmcat-5.5.9/webapps/PDF-Sig-Viewer-Remte G>Sign Viewer PAdES-LTV Part 4, Lng-term Signature with PKCS#11 Anther cmmn usage mde, using G>Sign Applet and G>Sign Viewer t display PDF dcuments, create blank signature fields and sign the dcument. ADSS G>Sign Service cmputes the hash f the dcument, G>Sign Desktp perfrms hash signing and ADSS G>Sign Service verifies and enhances the PAdES signature int a Lng-Term Verificatin frmat and assembles the final PDF. Ascertia Limited Cmmercial-in-Cnfidence Page 24 f 31

25 This dem uses the PKCS# 11 keystre, and the sample G>Sign prfile (adss:gsign:prfile:005) cnfigured in the ADSS G>Sign Service. By default, the PKCS#11 device (Aladdin) is cnfigured in the G>Sign prfile. Pre-requisites: In rder t run this dem, make sure that yur desired PKCS#11 device is cnfigured in G>Sign prfile. Ensure that yu restart the G>Sign Service after any updates. The user can access this dem using the fllwing URL(s): (Java) (.Net) The surce cde fr web pages used in this dem can be fund in ADSS Client SDK under the fllwing path: <ClientSDK>/GSign/Dem/GSignDems/Pades-Sig-Viewer-Lcal G>Sign Viewer PAdES Part 2, Lng-term Signature with Raming Key This is anther fairly cmmn usage mde using the pwer f G>Sign Desktp with its G>Sign Viewer t cntrl the display f a PDF. The G>Sign Viewer is used t display a PDF dcument, creating blank signatry fields and subsequent signing. ADSS G>Sign Service handles the dcument hash cmputatin, G>Sign Desktp perfrms hash signing, ADSS G>Sign Service uses ADSS Server t verify and enhance the signature int an advanced frmat, and finally, the enhanced signature is assembled int the PDF dcument by the ADSS G>Sign Service. This dem uses a raming keystre, and the sample G>Sign prfile (adss:gsign:prfile:003) cnfigured in the ADSS G>Sign Service. A raming key is used fr lcal signing (f curse it can easily be cnfigured t use lcally held CAP/PKCS#11 based key r server-side key). Pre-requisites: In rder t run this dem, first run the dem defined in Sectin with key alias value ROAMING_KEY_ALIAS. The user can access this dem using the fllwing URL(s): (Java) (.Net) The surce cde fr web pages used in this dem can be fund in the ADSS Client SDK under the fllwing path: <ClientSDK>/GSign/Dem/GSignDems/PDF-Sig-Viewer Native Viewer PAdES Part 2, Basic Signature with Native API This is a cmmn usage scenari f G>Sign Desktp withut G>Sign Viewer. ADSS G>Sign Service is respnsible fr prducing the dcument hash. G>Sign Desktp signs the hash and finally, ADSS G>Sign Service assembles the signature int the riginal dcument. If the business applicatin displays the PDF t the user, then Adbe Reader (r any installed PDF Reader) is used and this can validate the signature lcally using whatever lcal trust anchrs exist n the user s system. This dem uses the OS native API (MSCAPI & Mac Keychain). It uses the sample G>Sign prfile (adss:gsign:prfile:001) cnfigured in ADSS G>Sign Service. The user can access this dem using the fllwing URL(s): (Java) (.Net) The surce cde fr web pages used in this dem can be fund in the ADSS Client SDK under the fllwing path: <ClientSDK>/GSign/Dem/GSignDems/PDF-Sig Ascertia Limited Cmmercial-in-Cnfidence Page 25 f 31

26 6.1.5 Native Viewer PAdES Part 2, Lng-term Signature with PKCS#11 This is a cmmn usage scenari f G>Sign Desktp when it is used with a native dcument viewer, e.g. Adbe Reader. G>Sign Service handles the dcument hash cmputatin, G>Sign Desktp signs the cmputed hash, and the G>Sign Service assembles and enhances the signature t Lng Term Verificatin frmat with the help f ADSS Server. This dem uses PKSC#11 keystre, and the sample G>Sign prfile (adss:gsign:prfile:002) cnfigured in the ADSS G>Sign Service. By default, the PKCS#11 device (Aladdin) is cnfigured in the G>Sign prfile. Pre-requisites: In rder t run this dem, make sure that yur desired PKCS#11 device is cnfigured in G>Sign prfile. Ensure that yu restart the G>Sign Service after any updates. The user can access this dem using the fllwing URL(s): (Java) (.Net) The surce cde fr web pages used in this dem can be fund in the ADSS Client SDK under the fllwing path: <ClientSDK>/GSign/Dem/GSignDems/PDF-Sig-Lcal CAdES-X-L-Envelping, Lng-term Signature with Native API This dem shws hw CAdES-BES & CAdES-XL signatures can be cmputed ver any type f dcument using G>Sign Desktp. This dem uses the OS native API (MSCAPI & Mac Keychain), and the sample G>Sign prfile (adss:gsign:prfile:008) cnfigured in the ADSS G>Sign Service. The user can access this dem using the fllwing URL(s): (Java) (.Net) The surce cde fr web pages used in this dem can be fund in the ADSS Client SDK under the fllwing path: <ClientSDK>/GSign/Dem/jakarta-tmcat-5.5.9/webapps/File-Sig XAdES-BES-Envelped, Lng-term Signature with Native API This is a cmmn usage scenari f G>Sign Desktp fr XML signatures. This dem uses the OS native API (MSCAPI & Mac Keychain), and the sample G>Sign prfile (adss:gsign:prfile:006) cnfigured in the ADSS G>Sign Service. The user can access this dem using the fllwing URL(s): (Java) (.Net) The surce cde fr web pages used in this dem can be fund in ADSS Client SDK under the fllwing path: <ClientSDK>/GSign/Dem/jakarta-tmcat-5.5.9/webapps/XML-Sig e-tendering (XAdES-BES-Envelped, Lng-term Signature with Native API) This dem is nt available by default in ADSS Client SDK. If yu want t see hw e-tendering wrks, then yu shuld request the special ADSS Server license and a dem package by sending an t supprt@ascertia.cm. This is a special usage scenari in which G>Sign Desktp is used t create an XML signature. Ascertia Limited Cmmercial-in-Cnfidence Page 26 f 31