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.

Methods

SWS offer different method according to type of device signature. For example with automatic signature isn't possible to use the method "sendOtpBySMS" because don't require the second factor for sign. Below will be described all methods offered by SWS.

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

getCertificate → allows obtaining the certificate associated to signature device

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 requires parameters:

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

In the next 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 this table:

How to fill in these fields?

For automatic and remote signature

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

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

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

Only for remote signature

Only if you use the remote signature (username starts with RHI...) you should fill in these fields:

idOtp: (optional) specify the idOtp you want to use for the signature. If you do not want to set the idOtp, set idOtp to "-1" and SWS will automatically use the default OTP. You can use getOTPList method to get the idOtp;

Otp: contains the OTP code received via SMS or read in the Namirial app;

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

Only for automatic signature

Only if you use the remote signature (username starts with AHI... or SHI...) you should fill in these fields:

securityCode: this parameter must not be set. It is used only in certain situations (for example during the change password)

How works method getOTPList?

With this method, you can get the OTP list which can be used with the specified username, and you can fill in the Credentials.idOtp variable.

This method requires only the username.

For example, with the username: RHIP20102336019765, in 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 signing process, it is possible to choose between these two idOtps: 501719 (associated with OTP SMS) and the idOTP: 537430 (associated with OTP GENERATOR).

It is not possible to use OTP PUSH, they are used for other purposes, not for signing.

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

This method requires only the username as input (in this example the username is: RHIP20102336019765).

The soap request will be:

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

If everything is ok, in output response will be:

<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.otp variable 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 shown during the signing process.

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

Sign with sessionKey 

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

This function is available only for remote 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 “openSession” method allows obtaining the sessionKey.

Input requires:

• username
• password
• otp
• idOtp

As in this example:

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

Output will have the value of sessionKey which will be used for the signature:

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

The sessionKey just obtained is valid for three minutes (it is not possible to edit this value!). After it expires, you will need to generate another sessionKey using openSession method and new OTP code (it is not possible to use the same OTP already in use).

How to check if the session has expired or is valid

You can find out when the session expires with the method getRemainingTimeForSession. This method requires input:

• username
• sessionKey (obtained from method "openSession")

Below in the example: 

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

The SOAP response will be:

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

Where 167 is the seconds until the session is active. After 180 seconds from creation, the session will be automatically deleted, but for good practice, close the session before it expires.

You can destroy the session manually before it expires with the method closeSession.

Destroy the session manually

The method closeSession requires in input:

• sessionKey
• username

Below is the SOAP request example:

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

For security reasons, this method doesn't generate an exception if you insert the wrong sessionKey and/or username. The SOAP response will be ever like this:

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

Sequence diagram for signature with session and OTP SMS

In this sequence diagram, we can summarise the methods that are called for the signature with sessionKey and OTP SMS:

Sequence diagram for signature with session with OTP App

In this sequence diagram, we can summarise the methods that are for the signature with sessionKey and OTP SMS:

Summarize

Finally, we have all the requirements to populate the Credentials object during the signing. As already mentioned, the methods for signing are:

• signPAdES
• signCAdES
• signXAdES

There are the same methods with the suffix "List", they accept in input a list of files to be signed. Therefore with only SOAP requests is possible to sign more files (using automatic signature or sessionKey).

With these three methods it is possible to sign with any type of signature (automatic and remote).

Each of these three methods uses the Credentials object filled in at the same time.

For the automatic signature, it requires only the username and password variables in the object Credentials.

For example, for an automatic signature with the username: AHI7609757152622 and password 13572468 Credentials object will be filled in as shown:

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

If you use a remote signature, you should also fill in the other fields:

• idOtp (only if you received multiple idOTP from the method getOTPList)
• OTP or sessionKey (will see in the next section how to populate this variable)

Suppose we want to sign using the OTP code received previously from the method sendOtpBySMS.

The credentials object will be filled in this way:

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

idOtp was obtained from method getOTPList method and otp is the code received from method sendOTPBySMS.

Therefore for the automatic signature, the credentials object is composed by:

• username
• password

While for the remote signature, the credentials object is composed by:

• username
• password
• otp
• idOtp (only if you have more OTP, otherwise you can set this to "-1")
• sessionKey (optional)

If you need to sign multiple files with remote signature you should use the sessionKey as described earlier.

Now, that we know how to fill the Credentials object for the methods: signPades, signCades and signXades, we can fill the object buffer.

Now we should populate the value of:

• buffer
• preferences of signature (there are different types for each type of signature)

Populate the "buffer"

The buffer contains the file (in byte array) you want to sign.

In SoapUI, for example, the buffer is composed of the base64 of the file you want to sign, as in this example:

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

You can download the complete example at this link: signPadesList.xml

The output is the base64 associated with the file you just signed as follows: RESPONSE-base64-signPadesList.b64 and decoded will be this PDF: RESPONSE-signPadesList.pdf.

Signature Preferences

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

signPades → use PadESPreferences

signCades → use CadESPreferences

signXades → use XadESPreferences

How to populate these preferences is described in the next sections.

PadES Preferences

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

SignerImage

The SignerImage object is composed of the following:

Below the example of Pades signature with appearance:

signPadesListWithAppereance.xml

Cades Preferences

With cades signature, it is possible to sign each type of file. The signCades method requires:

• Credentials assigned to device signature;
• Buffer, the file that you want to sign;
• CAdESPreferences, the preferences about CAdES signature.

In the following table, you can see how to set the CAdESPreferences correctly:

Xades Preferences

With Xades Signature it is possible to sign only XML files, the signXades method requires:

• Credentials assigned to device signature
• Buffer, file that you want to sign
• XAdESPreferences, the preferences about XAdES signature

In the following table you can learn how to set the XAdESPreferences correctly:

Below is the example of Xades Signature Level B:

signXadesList-Level-B.txt

Below, there is an example of Xades using the preferences:

• signElement
• signatureId

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

<signElement>tagToSign</signElement>

And we set the id of the digital signature to:

<signatureId>idOfSignature</signatureId>

The full example:

signXadesList-on-specifiedTagId.xml

Level

You can see how to set the correct Level signature:

How apply the timestamp

It is possible to apply timestamp with the method timestamp, in input require:

• content: byte array of the file to which the timestamp is applied;
• preferences: object containing details about timestamp.

Below the object timestamp:

Manage signer device

As already mentioned, SWS offers a method for managing the signing device.

Method changePassword

This method requires a different signature according to device type: automatic/eseal or remote.

The output of this method will change the password. 

NOTE: if the holder device forgets the new password, it IS NOT POSSIBLE TO RESET the password.

changePassword on automatic/eseal signature

Input requires:

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

Below is 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 the device signature will be changed from "13572468" (old password) to "NEWPASSWORD123".

changePassword on remote signature

Input requires:

• 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 the device signature will be changed from "847291742" (old password) to "NEWPASSWORD123".

Manage error in SWS

Each method can generate an exception, for example PIN not correct, sessioneKey expired or OTP not correct.

For example if we try to execute the signPAdESList method with the same OTP, we get the SOAP response with error 44, as 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 the Italian language. 

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

Method getErrors

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

In this method, it is possible to return the list of all errors without setting the value of errorCode.

Examples (source code)

Below will find the links contains the source code with examples.

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 verifying only timestamp, you can use these 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)