Introduction

After installing and configuring your virtual appliance SWS, now you can use their method to sign or apply timestamp. SWS have two interfaces SOAP and REST. SOAP is used for files under 50MB and REST interface is used for files over 50MB.

SWS can manage some signature devices like:

• automatic signature (her name starts with AHI or AHIP followed by numbers)
• eSeal (her name starts with SHI or SHIP followed by numbers)
• remote signature (her name starts RHI or RHIP followed by numbers) 
• disposable signature (her name starts with RHI or RHID followed by numbers)
• long-lived signature (her name starts with RHIL or RHILD followed by numbers)

During the integration, you can only see:

• eSeal like an automatic signature
• disposable, long-lived like a remote signature

The remote signature is like an extension of the automatic signature because it requires the OTP code beyond username and password.

SWS supports three different types of signatures:

• Pades: valid only for PDF files
• Xades: valid only for XML files
• Cades: valid for every type of file

Apply timestamp on files (according to standard RFC3161)

Each type of signature and timestamp has its web method, which is described in the next sections.

In this user guide, the examples will be shown using "SoapUI". This is a free tool which can be installed on every OS. It is possible to create SOAP requests with this tool that invokes different web methods.

During the integration, the application client of SWS should recreate the same XML soap request created on SoapUI with his program language.

Soap Interface

To test SOAP interface, you can make requests with SoapUI, following this steps:

Download and install SoapUI from this link:

https://www.soapui.org/tools/soapui/

Once you complete the installation:

open SoapUI → File → New Soap Project

And add appliance SWS method to SoapUI, like the following image:

In the “Initial WSDL” text box use this URL:

http://<IP-APPLIANCE>:8080/SignEngineWeb/sign-services?wsdl

And you will get a list of methods like this:

Methods for automatic and remote signature

The main methods used to sign (valid for remote and automatic signatures) are:

signPAdES → Used for sign only PDF files

signCAdES → Used for sign every type of files

signXAdES → Used for sign XML files

getSignatures → allows obtaining the number of signatures, since the certificate was issued

getAvailableSignatures → allows obtaining the numbers of signatures (valid only for device NOT pay per use, otherwise an exception is generated)

changePassword → allows changing the password (PIN) of the device

Each method requires the Credentials object. In the next section, you will see how to populate this field.

Method signPades

In this table are defined the parameters required (IN) and the output (OUT) of this method:

Method signCades

In this table are defined the parameters required (IN) and the output (OUT) of this method:

Method signXades

In this table are defined the parameters required (IN) and the output (OUT) of this method:

Method changePassword

In this table are defined the parameters required (IN) and the output (OUT) of this method:

VERY IMPORTANT: if the customer forgets the new password, it IS NOT POSSIBLE to recover/reset the password.

Methods only for remote signature

If you are signing with a remote signature, you can also use these methods:

getOTPList → allows obtaining the list of OTPs associated with your remote signature (OTP is assigned to the owner of the certificate. For example, if you have two or more remote signatures associated with the same owner, you can use this OTP for each remote signature).

sendOtpBySMS → it will send an SMS containing the OTP code.

openSession → allows obtaining the token (like a string) for the signature instead of inserting new OTP code for each signature). The token is available for three minutes from generation.

getRemainingTimeForSession → returns time until the session is valid

closeSession → if you want to destroy the token before three minutes (however will expire after three minutes)

Method getOtpList

Method sendOtpBySMS

After this method is done the customer receives an SMS with an OTP code to use.

Method openSession

At the end of this method the customer will receive the SMS with OTP code to use.

Method getRemainingTimeForSession

Method closeSession

After this method is done the session is destroyed.

Method for apply timestamp

SWS offers methods for applying timestamp and enquiry (only for Namirial accounts).

timestamp → allows to get the file with timestamp; there are two types TSR or TSD. The TSR option means that the timestamp is in another file, while TSD means that the timestamp signature is in the same file.

getAvailableTimestamps → allows getting the timestamp; available ONLY for Namirial account.

Each method is described below with the required inputs.

Method timestamp

This method can be used with all timestamp account (not only Namirial) they must use standard RFC3161.

NOTE: Since SWS v2.5.44 this method supports Adobe Timestamp. In the timestampPreferences you should set "outputAsPDF=true".

Method getAvailableTimestamps (since SWS v2.5.44)

NOTE: TimestampUrl can be set to:

How Sign the file

To sign the file with SWS

 each method require

s parameters:

• Credentials: contain the value about signature device;
• Preferences: contain the signature details like page, appereance ecc...details of the signature such as page, appearance etc., Level of signature (B, T, LT ecc.., etc.). There are different type types of preferences PadesPreferences, CadesPreferences, XadesPreferences;
• buffer: file which you want to sign.

In thenext sections you will

learn how to set

these parameters.

Credentials Object

All

methods

for signing (signPAdES..., signCAdES..., signXAdES)

use the Credentials object,

as you can see in

the next photo:

How

to fill in these fields?

For automatic and remote signature

For every each type of signature (automatic signature and remote signature) you must fill this in these two fields:

username: contains the device name it starting with RHI..., AHI... or SHI...

password: contains the PIN associated to the device (read from blind the dummy envelope or set by the customer)

Only for remote signature

Only if you

usethe remote signature (username starts with RHI...) you should fill

in these fields:

idOtp: (optional) it specify the idOtp which you want to use for signthe signature. If you don't do not want to set the idOtp, SWS will automatically use automatically the default OTP. You can use the method getOTPList for obtain getOTPListmethod to get the idOtp.;

Otp: it contains the OTP code recived by received via SMS or read on in the Namirial app Namirial;

sessionKey: it contain contains the token (like a string) received from openSession method openSession;

securityCode: this parameter must not be set. It is used only in certain situationsituations.

How works method getOTPList?

With this method, you can

get the OTP list which can be used withthe specified username, and you

can

fill in the

Credentials.idOtpvariable.

This method it require requires only the username.

For example, with the username: RHIP20102336019765, in this the request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getOTPList>
         <credentials>
            <username>RHIP20102336019765</username>
         </credentials>
      </ser:getOTPList>
   </soapenv:Body>
</soapenv:Envelope>

You will

receive the response

:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getOTPListResponse xmlns:ns2="http://service.ws.nam/">
         <return>
            <idOtp>501719</idOtp>
            <serialNumber>20210113-091031RJ2L1</serialNumber>
            <type>SMS</type>
         </return>
         <return>
            <idOtp>537430</idOtp>
            <serialNumber>20210305-163726L0PYF</serialNumber>
            <type>OTP GENERATOR</type>
         </return>
         <return>
            <idOtp>537433</idOtp>
            <serialNumber>20210305-163726F0I75</serialNumber>
            <type>OTP PUSH</type>
         </return>
      </ns2:getOTPListResponse>
   </soap:Body>
</soap:Envelope>

During the sign signing process, it is possible to choose between this these two idOtps: 501719 (associated to with OTP SMS) and the idOTP: 537430 (associated to with OTP GENERATOR).

Isn't It is not possible to use OTP PUSH, they are used for other purposepurposes, not for signsigning.Now during

For the signature we can choose two types of idOTP: 501719 or 537430.

Sign with OTP SMS

If you decide to sign with OTP SMS, you should use the method: method sendOTPBySMS.

This method require

s only the username as input (in this example the username is: RHIP20102336019765).

The soap request will be like this:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:sendOtpBySMS>
         <credentials>
            <username>RHIP20102336019765</username>
         </credentials>
      </ser:sendOtpBySMS>
   </soapenv:Body>
</soapenv:Envelope>

And if If everything is ok, in output response will receive the response like thisbe:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:sendOtpBySMSResponse xmlns:ns2="http://service.ws.nam/"/>
   </soap:Body>
</soap:Envelope>

On your mobile phone, you will receive

an SMS containing the OTP code (composed

of 6

numbers) for

signature. Now, for example

, we have received the code: “214196”.

The OTP code just received will be the

Credentials.otpvariable during the signing process

Sign with OTP GENERATOR (App)

If you decide to sign with OTP GENERATOR, you should open the Namirial OTP App and insert the OTP code showed shown during the sign signing process.

→Show the guide "How to configure Namirial OTP App" (To Do/Add)

Sign with sessionKey 

With otp it is possible to make create only one signature, but if you have need to sign more files, with the “sessionKey” it is possible with “sessionKey”. In the The next section will be described describes how works the session works.

This function is available only for remote signature, it permits to sign at most 3 minutes using signatures. It allows signing for a maximum of 3 minutes with the same sessionKey. You can see the session like a token provided from the method “openSession”.

How obtain the sessionKey?

The

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
	xmlns:ser="http://service.ws.nam/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:openSession>
         <credentials>
            <idOtp>501719</idOtp>
            <otp>150259</otp>
            <password>13572468</password>
            <username>RHIP20102336019765</username>
         </credentials>
      </ser:openSession>
   </soapenv:Body>
</soapenv:Envelope>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:openSessionResponse xmlns:ns2="http://service.ws.nam/">	
		<return>
			f4lf7bq/cCxW6mTgL3iGjFEST5cEAZjgLnXvV3hUFzFHcTvjlH3FOkJy+kv/0Zsv1
			uNK0S7L6jMqHYSspBz+CZl7h3r5IEP2FqrK7WJQTVyrNfyr/trZmDgxYOLuACyoZVUFIlnck5Lkjihui
			sv+gZeB68Spwm+cNDdQQdUS3ngzJavHXxo9ADCX6VDIKKMe/AY0v+R51XWE90JF5LfKEThlv1OCpQC5nhnW8WKOFOm
			P4vM90d79JhFYGVVSZWtnTQ9Dg8pOMvg9wwxNm3uGkKKaS7oTp1ewd+eCG/uSC9k3H2w9GB6vQLHQEbn6d
			VVMcsIqJ0RMmZ2IgraD+scb4Q==
		</return>
      </ns2:openSessionResponse>
   </soap:Body>
</soap:Envelope>

How to check if the session has expired or is valid

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
			xmlns:ser="http://service.ws.nam/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getRemainingTimeForSession>
         <credentials>
            <username>RHIP20102336019765</username>
		    <sessionKey>
						f4lf7bq/cCxW6mTgL3iGjFEST5cEAZjgLnXvV3hUFzFHcTvjlH3FOkJy+kv/0Zsv1
						uNK0S7L6jMqHYSspBz+CZl7h3r5IEP2FqrK7WJQTVyrNfyr/trZmDgxYOLuACyoZVUFIlnck5Lkjihui
						sv+gZeB68Spwm+cNDdQQdUS3ngzJavHXxo9ADCX6VDIKKMe/AY0v+R51XWE90JF5LfKEThlv1OCpQC5nhnW8WKOFOm
						P4vM90d79JhFYGVVSZWtnTQ9Dg8pOMvg9wwxNm3uGkKKaS7oTp1ewd+eCG/uSC9k3H2w9GB6vQLHQEbn6d
						VVMcsIqJ0RMmZ2IgraD+scb4Q==
			</sessionKey>
		 </credentials>
      </ser:getRemainingTimeForSession>
   </soapenv:Body>
</soapenv:Envelope>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getRemainingTimeForSessionResponse xmlns:ns2="http://service.ws.nam/">
         <return>167</return>
      </ns2:getRemainingTimeForSessionResponse>
   </soap:Body>
</soap:Envelope>

Destroy the session manually

Sequence diagram for

Sequence diagram for

Summarize

Finally, we have all

<credentials>
	<username>AHIP20102336019478</username>
	<password>1357268</password>
</credentials>

<credentials>
	<idOtp>501719</idOtp>
	<otp>150259</otp>
	<password>13572468</password>
	<username>RHIP20102336019765</username>
</credentials>

Populate the "buffer"

The buffer contain contains the file (in byte array) which you want to sign.For example in SoapUI

In SoapUI, for example, the buffer is composed

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:signPAdES>
			<credentials>
            	<idOtp>501719</idOtp>
	            <otp>548316</otp>
    	        <password>13572468</password>
        	    <username>RHIP20102336019765</username>
	         </credentials>
    	     <buffer>BASE64-FILE-TO-SIGN</buffer>    
			 <PAdESPreferences>
				<level>B</level>
				<signerImage></signerImage>
			</PAdESPreferences>
      </ser:signPAdES>
   </soapenv:Body>
</soapenv:Envelope>

Signature Preferences

The difference between signPades, signCades and signXades are is based on the preferences:

signPades → use PadESPreferences

signCades → use CadESPreferences

signXades → use XadESPreferences

How to populate this preferences will be describe these preferences is described in the next sections.

PadES Preferences

This type of preference is used in method signPades. Their principal main options are:

SignerImage

The object SignerImage is composed by the following details:

Below the example of Pades signature with appereance:

signPadesListWithAppereance.xml

Cades Preferences

With cades signature is possible to sign every type of file, the method signCades require:

• Credentials associated to device signature
• buffer, file which you want sign
• CAdESPreferences, the preferences about CAdES signature

In the following table you can see how set correctly the CAdESPreferences

Xades Preferences

With xades signature is possible to sign only XML files, the method signXades require;

• Credentials associated to device signature
• buffer, file which you want sign
• XAdESPreferences, the preferences about XAdES signature

In the following table you can see how set correctly the XAdESPreferences

Below the example of Xades Signature Level B:

signXadesList-Level-B.txt

Below the example of Xades usign the preferences:

• signElement
• signatureId

We will sign the parts of XML with "Id=tagToSign" specified on Soap request by:

<signElement>tagToSign</signElement>

And we will set the id of digital signature to:

<signatureId>idOfSignature</signatureId>

The full example:

signXadesList-on-specifiedTagId.xml

Level

You can see how set the correct Level signature:

How apply the timestamp

Is possible to apply timestamp wit the method "timestamp", in input require:

• content: byte array of file to apply timestamp
• preferences: object with contains details about timestamp

Below the object timestamp:

Manage signer device

Like mentioned before, SWS offer method for manage the signer device.

Method changePassword

This method require different according to device type automatic/eseal or remote signature.

In output of this method will obtain the password changed. 

NOTE: after change if the hoder device forgot the new password, ISN'T POSSIBLE TO RESET the password.

changePassword on automatic/eseal signature

This method in input require:

• credentials.username
• credentials.password
• credentials.securityCode
• newPassword

Below the example:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:changePassword>
         <credentials>
            <password>13572468</password>
            <securityCode>8214260012</securityCode>
            <username>AHIP22021318589386</username>
         </credentials>
         <newPassword>NEWPASSWORD123</newPassword>
      </ser:changePassword>
   </soapenv:Body>
</soapenv:Envelope>

After this execution the password/PIN of device signature will be changed from "13572468" (old password) to "NEWPASSWORD123"

changePassword on remote signature

This method in input require:

• credentials.username
• credentials.password
• credentials.idOtp
• credentials.otp
• newPassword

Below the example:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:changePassword>
         <credentials>
			<username>RHI3644468199007</username>
            <password>847291742</password>
            <idOtp>4872</idOtp>
            <otp>876321</otp>
         </credentials>
         <newPassword>NEWPASSWORD123</newPassword>
      </ser:changePassword>
   </soapenv:Body>
</soapenv:Envelope>

After this execution the password/PIN of device signature will be changed from "847291742" (old password) to "NEWPASSWORD123"

Manage error in SWS

Every method can generate exception, for example caused by PIN not correct, sessioneKey expired or OTP not correct.

For example if we can try to execute the method signPAdESList using the same OTP used we obtain SOAP response with error 44, like in this response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <soap:Fault>
         <faultcode>soap:Server</faultcode>
         <faultstring>Codice OTP errato, riprovare con il prossimo codice</faultstring>
         <detail>
            <ns2:WSException xmlns:ns2="http://service.ws.nam/">
               <error>44</error>
               <message>Codice OTP errato, riprovare con il prossimo codice</message>
            </ns2:WSException>
         </detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

By default the error message is in Italian language. 

Below the table description with all error messages can generate SWS during your execution method:

Method getErrors

This method return a list of errors which can be generated from SWS in in

In this method is possible to obtain the list of all errors, without set the value of errorCode.

REST interface

SWS offer the interface REST for Pades and Cades signature for file with very big size (you can sign file over 1GB). Without problem of appliance memory because manage the files with a stream.

BIG files

At this link:

http://localhost:8080/SignEngineWeb/rest/service

You can find this two method:

• signPAdES
• signCAdES

signPAdES

Below the example of signPAdES request with CURL:

curl --form credentials="{\"username\":\"DEVICENAME\",\"password\":\"PASSWORD\"}";type=application/json --form preferences="{\"page\":\"1\",\"hashAlgorithm\":\"SHA256\", \"withTimestamp\": \"false\"}";type=application/json --form file=@FILE_TO_BE_SIGNED.pdf --request POST http://localhost:8080/SignEngineWeb/rest/service/signPAdES --output FILE_SIGNED.pdf

In this example we are signing the file: "FILE_TO_BE_SIGNED.pdf" and the file signed will be saved in: "FILE_SIGNED.pdf"

signCAdES

Below the example of signCAdES with CURL:

curl --form credentials="{\"username\":\"DEVICENAME\",\"password\":\"PASSWORD\"}";type=application/json --form preferences="{\"hashAlgorithm\":\"SHA256\"}";type=application/json --form file=@FILE_TO_BE_SIGNED.txt --request POST http://localhost:8080/SignEngineWeb/rest/service/signCAdES --output FILE_SIGNED.txt.p7m

In this example we are signing the file: "FILE_TO_SIGNED.txt" and the file signed will be saved in: "FILE_SIGNED.txt.p7m"

Examples (source code)

Below will find the links contains the source code with example

Java:

To add on CMS repo

Php:

C#: https://cms.firmacerta.it/download/sws_cnet.zip

C# (for SaaS instance): https://cms.firmacerta.it/download/SignEngineWebClientSaaS.zip

ADVANCED USE (visible or not?)

For example signPkcs1

VERIFY TIMESTAMP

While for verify only timestamp, you can use this methods:

timestampTSDVerify → It permits to validate TSD files (file and timestamp in the same file)

timestampTSRVerify → It permits to validate TSR files (file and timestamp in two different files)