Introduction

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

SWS can manage some signature device 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 Only during the integration, you can only see:

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

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

Can support SWS supports three different types of signaturesignatures:

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

Apply timestamp on files (according to standard RFC3161)

For every Each type of signature and timestamp , there is a dedicated has its web method, which will be is described in the 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. With this tool, It is possible to create SOAP request which invoke the differents 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

For test SOAP interface, you can request with SoapUI, following this steps:

Methods for sign

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

Download and install SoapUI from this link:

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

Once complete the installation:

And add appliance SWS method to SoapUI, like in this image:

Image Removed

In text box “Initial WSDL” use this URL:

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

And you will obtain the list of method like this:

Image Removed

The principal method used to sign, they are:

signPAdESList → Used for sign only PDF filessignCAdESList

signPAdESMultiFieldName → Used for sign every type of filesonly PDF files, the field signature must exist

signCAdES → Used for sign every type of files

signXAdES signXAdESList → Used for sign XML files

signPkcs1 → Used for raw signature (require the client of SWS make the cryptographic envelope)

getSignatures → permit to obtain allows obtaining the number of signature made since certicate creationsignatures, since the certificate was issued

getCertificate → allows obtaining the certificate associated to signature device

getAvailableSignatures → permit to obtain allows obtaining the numbers of signatures (valid only for device NOT pay per use, else it will generate otherwise an exception )

If you are signing with remote signature, you can use this method:

getOTPList → permit to obtain the list of OTP associate to your remote signature (exactly the OTP is associated to the holder of certificate. For example if you have two or more remote signature associate to same holder, you can use this OTP for every remote signature).

sendOtpBySMS → it will send the SMS containig the OTP code.

openSession → permit to obtain the token (like a string) for sign instead to insert new OTP code on every signature). The token is valid for three minutes from generation.

GetRemainingTimeForSession → it return the time until the session is valid

closeSession → if you want destroy the token before three minutes

If you want apply only timestamp, you can use this method:

timestamp → it permits to obtain the file with timestamp is possible to choose between two types TSR or TSD. The option TSR mean the timestamp is another files, while the TSD mean the timestamp signature is in the same file.

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)

After this introduction, below will be described every method with input required.

CREDENTIALS object

All the metod used for sign (signPAdES..., signCAdES..., signXAdES) they use the object Credentials, like you can see in this image:

How popolate this fields?

For every type of signature (automatic signature, remote signature and eseal) you must fill this two fields:

username: contain the device name it start with RHI..., AHI... or SHI...

password: contain the PIN associated to device

While only if you you are using the remote signature (username starts withi RHI...) you should fill this fields:

idOtp: (optional) it specify the idOtp which you want use for sign. If you don't want set the idOtp, SWS will use automatically the default OTP. You can use the method getOTPList for obtain the idOtp.

Otp: it contains the OTP code recived by SMS or read on app Namirial

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

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

How works method getOTPList?

If you are use remote signature or eseal can skip this section and go to “How sign files”

With this method you can obtain the OTP list which can be use with specified username, and you will can populate the variable Credentials.idOtp.

This method it require only the username.

For example with username: RHIP20102336019765, in this request:

You will obtain response like this:

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

Isn't possible to use OTP PUSH, they aren't used during the sign.

Now during the sign 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 require in input only the username (in this example the username is: RHIP20102336019765).

The soap request will be like this:

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

And on mobile phone will receive the SMS containing the OTP code (composed from 6 number) for sign, for example now we have received the code: “214196”.

The OTP code just received will the variable Crediantls.otp during the process of sign.

How Sign File

Finally we have all requisites for call metodhs for sign:

signPAdESList

signCAdESList

signXAdESList

With this three methods is possible to sign with every type of signature (automatic, remote, disposable or eseal).

Everyone of this three methods use the Credentials object filled in the same time.

The type of signature automatic or eseal, they require only the variables username and password in the object Credentials.

For example in automatic signature with username: AHI7609757152622 and password 13572468

the object Credentials will be populate like in the image:

How can you see, are set only username and password because is an automatic signature. Also in eseal are required only username and password.

While if you are using remote signature you must fill the other fields: idOtp (only if you have more idOTP received from method getOTPList), OTP or sessionKey (will see in the next section how populate this variable).

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

The other parameters will be filled in this way:

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

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

Sign using sessionKey

This function is available on remote and disposable signature, it permits to sign at most 3 minutes using the same session. You can see the sessione like a token provided from method “openSession”.

How obtain the sessionKey?

The method “openSession” it permits to obtain the sessionKey.

In input it require: username, password, otp, idOtp like in this example:

In output will obtain the value of sessionKey which will be used for sign:

SessionKey is valid for three minutes, after will expire and will needed to generate another sessionKey using the method openSession and new OTP code (isn't possible to use the same OTP already used).

Is possible to know when the session will expire with method: “getRemainingTimeForSession”. Like in this image:

How can you see in input require the username and sessionKey.

If the sessionKey is valid, the output of the method will be the time (in seconds) remaining until the session is valid:

In this output the session is valid for another 112 seconds.

Else if the session has expired the otput will be like this:

If you want destroy the session before will expire, you can use the method: “closeSession”.

In input it require the sessionKey (generate with method “openSession” and the username).

For example like in this request:

The session will be destroyed and the output will be like in this example:

Summarize:

For automatic signature and eseal the variables required in the object credentials are: username (starts with AHI or eseal SHI) and password.

While for remote and disposabe signature for sign are required also otp, idOtp (only if getOtpList return more idOtp).

With automatic or eseal signature during the sign the object Credentials will be pupolated only variables username and password, the other variable must be not set.

With remote and disposable signature the correct step for sign are:

• call method getOtpList: with input username → will obtain the idOtp

Choose the idOtp to use:

• if you choose the idOTP type SMS, you should call the method sendOtpBySMS specicifying only the username → will obtain the OTP to use during the sign

• if you choose the idOTP type GENERATOR, the OTP will be displayed in the Namirial App OTP

If you need to sign multiple files with remote or disposable disposable you should use the sessionKey how already described.

Now, is completed how populate the Credentials object for methods: signPadesList, signCadesList and signXadesList, we can populate the object bufferList.

How populate the bufferList

The bufferList contains the base64 encoded of the file to sign. If you want sign multiple files, you should create more elements of bufferList. Like in this image:

The differences between signPadesList, signCadesList and signXadesList are based on the preferences:

signPadesList → use PadESPreferences

signCadesList → use CadESPreferences

signXadesList → use XadESPreferences

How populate this preferences will be describe in the next sections.

How populate PadESPreferences

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

The variables starts with “timestamp” they are associate to timestamp details, they are:

• timestampHashAlgo: should be set to SHA-256

• timestampPassword: password associated to timestamp account

• timestampUrl: url used for applt timestamp (for example for Namirial TSA is: “https://timestamp.namirialtsp.com”)

• timestampUsername: username associate to timestamp account

While the other variables are:

• hashAlgoritm: hash algorithm used to sign (for example SHA-256)

• level: type of signature with or without timestamp, ocsp response ecc.., is possible to choose between B, T, LT, LTV, LTA

• withTimestamp: maybe true or false if you want use or not timestamp during the process of digital signature. If you set “true” this variable, you should set the variable starts with “timestamp”

• page: indicate the number page of appereance (if you don't use the appereance, you should set this to “1”)

• signerImage: this object is used for specify the details on appereance like logo image or string.

• withSignature: set to “true” if you want apply the appereance con PDF signature fiels, else set to “false”

How populate the object signerImage

Read this section only if you want apply the appereance on PDF.

The object credentials is composed by:

The object “signerImage” is used to describe how populate the appereance. Set the image and string on appereance.

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 signPadesMultiFieldName

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

PadesWithMultiFieldName

Here you can find a description of the complex object PadesMultiFieldName

ServiceError

Here you can find a description of the complex object ServiceError

NOTE: for example if you want sign a PDF wih 10 fields signatures ("field-1", "field-2", ... "field-10") using the sessionKey after 6 signatures the session key has expired in output will receive this response:

signedContent = PDF with 6 signatures (the fields signed are: "field-1", "field-2",...,"field-6"
remainingFieldNames = ["field-7","field-8","field-9","field-10"]


IMPORTANT!!!,
The serviceError will be:

serviceError.code = 69
serviceError.message = "SessionKeyScaduta"

Example of usage

In this sequence diagram, you can see usage standard (when the session key no expire):

Image Added

In this use case we are signing the signatures fields ("Field-1", "Field-2" and "Field-3") of "pdf_to_sign" and SWS make all three signatures required without problem returning the "pdf_fully_signed"

Below you can find a sequence diagram that explains the method "signPadesMultiFieldName" when the session key expire:

Image Added

In this use case our target is: sign 3 fields ("Field-1", "Field-2" and "Field-3") of "pdf_to_sign" using a session key.

Make the request using "signPadesMultiFieldName" and after two signature the session key has expire.

Therefore the response will be

• the pdf_partially_signed (contains two signatures)
• ServiceError contain the details about error (in this example session key expired)
• List of unsigned fields: Field-3

To complete all three signatures we must:

• generate "new_sessionKey"
• make a new request of signPadesMultiFieldName using pdf_partially_signed and set "Field-3" ad list fields to sign

Finally, in response we obtain the pdf_fully_signed!!!

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 signPkcs1

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

NOTE: SignPreferences is a complex object, the method require only the field: SignPreferences.hashAlgorithm

And the value can be:

• SHA-256 (default value if not specified)
• SHA-1
• SHA-384
• SHA-512

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 string with sessionKey for sign (credentials.sessionKey)

Method getRemainingTimeForSession

Method closeSession

After this method is done the session is destroyed.

Methods for 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".

TimeStampPreferences

Below will described how populate the preferences about timestamp

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

Only if youusethe automatic 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)

Only for remote signature

Only if youusethe 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 getOTPListmethod 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;

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

This method requires only the username.

The "OTP" object is compose by:

NOTE: with SWS is not possible to use the OTP with type "OTP PUSH".

Sign with OTP SMS

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

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

The sessionKey is valid for three minutes from has been generated. With this is possible unlimited files.

How to check if the sessionKey has expired or is valid

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

Destroy the session manually

The method closeSession requires in input:

• sessionKey

• username

NOTE: for security reasons, this method doesn't generate an exception if you insert the wrong sessionKey and/or username.

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:

Image Added

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:

Image Added

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.

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)

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:

NOTE: if you are using the method "signPadesMultiFieldName", the property "signAllFields" have a priority on property "fieldsNameList"

Below an example of output in Adobe if you use the option "location" and "reason":

Image Added

Use specific ttf (TrueTypeFont)

With SWS is possible to use a specific font specifying a path of ttf files. The fonts available are:

• DejaVu
• helvetica-neue

To use Dejavu, you must set value of "fontName" (signerImage.fontName) with this value:

/usr/share/fonts/dejavu/@FONTNAME@

The possible values of "@FONTNAME@" are:

• DejaVuSans-BoldOblique.ttf
• DejaVuSansCondensed-Oblique.ttf
• DejaVuSansMono-Bold.ttf
  DejaVuSans.ttf
• DejaVuSans-Bold.ttf
• DejaVuSansCondensed.ttf
• DejaVuSansMono-Oblique.ttf
• DejaVuSansCondensed-BoldOblique.ttf
  DejaVuSans-ExtraLight.ttf
• DejaVuSansMono.ttf
• DejaVuSansCondensed-Bold.ttf
• DejaVuSansMono-BoldOblique.ttf
• DejaVuSans-Oblique.ttf 

To use Helvetica-Neue, you must set value of "fontName" (signerImage.fontName) with this value:

/usr/share/fonts/helvetica-neue/@FONTNAME@

The possible values of "@FONTNAME@" are:

• HelveticaBlkIt.ttf
• HelveticaNeueBold.ttf
• HelveticaNeueCondensedBlack.ttf
• HelveticaNeueCondensedBold.ttf
• HelveticaNeueMedium.ttf
• HelveticaNeueUltraLightItal.ttf

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

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

In output (if input is correct) will have the password associated to credentials.usernam set to "newPassword".

changePassword on remote signature

Input requires:

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

In output (if input is correct) will have the password associated to credentials.usernam set to "newPassword".

Method getCertificate

This method allow to obtain the certificate associated to signer device.

This method require same input for automatic and remote signature. Below the details:

Method getAvailableSignatures

This method allow to obtain the number of signaures available

This method require same input for automatic and remote signature. Below the details:

NOTE: this method can't be used for signer device "pay-per-use" (device with unlimited signatures), will generate error with code: "56"

Method getSignatures

This method allow to obtain the number of signaures apposed since the device has been created

This method require same input for automatic and remote signature. Below the details:

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

The type "ErrorDetails" is a composed by:

• int errorCode 
• String errorLanguage (language code in 2 digit for example EN)
• String errorLanguage2 (language code in 3 digit for example ENG)
• String errorText (contain the error description in a specified language)

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

Verify the signatures/timestamp in SWS

SWS permits to verify the signature. For SWS the signature is VALID only if the signature has been apposed with qualified certificate.

For example the the certificate which has apposed the signature is qualified if:

• Root CA enroll the certificate is in the truested list
• private key is in secure device like smartcard, token or HSM

For example if the signature has been apposed with private key on file, the verify with SWS will fail because the private isn't in a secure device (like HSM).

Method for verification of digital signatures: verifyWithPreferences

This method allow to verify different types of signatures (detached or no): Pades, Xades, Cades:

Below will be described the complex object "VerifiyPreferences"

In output will obtain the verification report described by complex object: SignedDocumentReportBean

Below will be described the complex object NoteReportBean, SignatureReportBean:

Method for verification of timestamps

The timestamp can be of two different types:

• TSR (TimeStamp Response) + original file in the same file is called TSD (TimeStamp Data)
• TSR and original file in two different files

There are two method for verify the TSD and TSR:

• verifyTimeStampData
• verifyTimeStampResponse

Method verifyTimeStampResponse and verifyTimestampData

Below the description of method "verifyTimeStampResponse" permits to verify only TSR:

And the method "verifyTimestampData" permits to verify only TSD:

While the method "verifyTimeStampWithPreferences" permits to verify TSR and TSD, below the details:

Below will be described the complex object VerifyTimestampPreferences:

Below will be described the complex object TimestampReportBeanSummary:

Below will be described the complex object TimestampReportBean:

NOTE: the timestamp file is verified only if for every element of TimestampReportBean list all this conditions (in AND) are verified:

• signatureVerificationStatus = VALID
• trustedListVerificationStatus = VALID
• timestampCertificateStatus = VALID

Method for verifyCertificate

Below the description of method "verifyCertificate":

Below will be described the complex object CertificateReportBean:

LEGEND:

Below the details about certificate:

active → the certificate isn't revoked or hold

valid → isn't expired

Utilities for sign

Below will described described the method for extract the info about the files, for example extract extract the info about the fieldName in a PDF

getAvailableSignatureFieldNames

This method allow to retrieve for a given PDF file all signature fields present that there are NOT already used.

Below you can find a description of IN/OUT fields.

Example response

An example response can be found below:

[
    "SignatureField-1",
    "SignatureField-2"
]

allSignatureFieldNamesWithPreferences

This method allow to retrieve all signature field present inside a file. Using preferences the user is able to retrieve more details about the signature applied to a given signature field.

Below you can find a description of IN/OUT fields.

SignatureFieldPreferences

Here you can find a description of the complex object SignatureFieldPreferences

SignatureFieldName

Here you can find a description of the complex object SignatureFieldName

SignatureDetails

Here you can find a description of the complex object SignatureDetails

PdfRectangle

Here you can find a description of the complex object PdfRectangle

Example response

Here you can find an example response:

[
    {
        "identifier": "SignatureField-1",
        "signed": false
    },
    {
        "identifier": "SignatureField-2",
        "signatureDetails": {
            "name": "My Name and Surname",
            "signDate": 1687869549000,
            "location": "Milan",
            "reason": "Signed for general purpose",
            "page": -1,
            "appearance": {
                "width": 40.50,
                "height": 10.20,
                "x": 1.0,
                "y": 2.3
            },
            "certificate": "<base64-encoded certificate>",
            "subjectDN": "CN=My Name and Surname, SERIALNUMBER=1234567890, GIVENNAME=MyName, SURNAME=My Surname, C=IT"
        },
        "signed": true
    }
]