Introduction

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

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

Sign interface#MethodgetAvailableSignatures 

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

signPAdESMultiFieldName → Used for sign only PDF files, the field signature must exist

signCAdES → Used for sign every type of files

signXAdES → Used for sign XML files

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

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:

signPades
NameTypeDescriptionIN/OUT
credentialsCredentialsSee the Credentials section to see how to populate this objectIN
bufferbyte[]Byte array which you want to signIN
PAdESPreferencesPAdESPreferencesSpecify the details of PadesSignature. See the PadesPreferences section to populate the objectIN

byte[]Byte array containing the files just signedOUT

Method signPadesMultiFieldName

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

signPadesMultiFieldName AVAILABLE FROM VERSION 2.5.57
NameTypeDescriptionIN/OUT
credentialsCredentialsSee the Credentials section to see how to populate this objectIN
bufferbyte[]Byte array which you want to signIN
PAdESPreferencesPAdESPreferencesSpecify the details of PadesSignature. See the PadesPreferences section to populate the objectIN

PadesWithMultiFieldNameComplex object with details about signatures and error (if present)OUT

PadesWithMultiFieldName

Here you can find a description of the complex object PadesMultiFieldName

PadesMultiFieldName

Name

Type

Description

Included from SWS version

signedContent

byte[]

File signed fully or partially

2.5.57

remainingFieldNames

List<String>

List of unsigned fields (if the file signed is partially)

2.5.57

serviceErrorServiceErrorComplex object with details about error. This field is populated if the "signedContent" is partially signed2.5.57

ServiceError

Here you can find a description of the complex object ServiceError

ServiceError

Name

Type

Description

Included from SWS version

code

int

error code generated during the signature

2.5.57

message

String

error message generated during the signature

2.5.57

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:

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

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:


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:

signCades
NameTypeDescriptionIN/OUT
credentialsCredentialsSee the Credentials section to see how to populate this objectIN
bufferbyte[]Byte array that you want to signIN
CAdESPreferencesCAdESPreferencesSpecify the details of PadesSignature. See the CadesPreferences section to populate this objectIN

byte[]List of byte array containing the file just signedOUT

Method signXades

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

signXades
NameTypeDescriptionIN/OUT
credentialsCredentialsSee the Credentials  section to see how to populate this objectIN
bufferbyte[]Byte array that you want signIN
XAdESPreferencesXAdESPreferencesSpecify the details of XadesSignature. See the XadesPreferences section to populate this objectIN

byte[]Byte array containing the file just signedOUT

Method signPkcs1

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

signPkcs1
NameTypeDescriptionIN/OUT
credentialsCredentialsSee the Credentials  section to see how to populate this objectIN
bufferbyte[]hash associated the file you want signIN
SignPreferencesSignPreferencesSpecify the hash algorithm used to sign the hashIN

byte[]Byte array containing the hash associated to the file just sgnedOUT

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:

signXadesList
NameTypeDescriptionIN/OUT
credentialsCredentialsSee the Credentials section to see how to populate this objectIN
newPasswordStringString that contains the new passwordIN

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

getOtpList
NameTypeDescriptionIN/OUT
credentialsCredentialsSee the Credentials section to see how populate this objectIN

List<OTP>List of OTP assigned to the CredentialsOUT

Method sendOtpBySMS

sendOtpBySMS
NameTypeDescriptionIN/OUT
credentialsCredentialsSee the Credentials section to see how populate this objectIN

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

Method openSession

openSession
NameTypeDescriptionIN/OUT
credentialsCredentialsSee the section Credentials for see how populate this objectIN

StringSessionkey to use for signOUT

At the end of this method the customer will receive string with sessionKey for sign (credentials.sessionKey)

Method getRemainingTimeForSession

getRemainingTimeForSession
NameTypeDescriptionIN/OUT
credentialsCredentialsSee the section Credentials for see how populate this objectIN

intSeconds left until the session is validOUT

Method closeSession

closeSession
NameTypeDescriptionIN/OUT
credentialsCredentialsSee the section Credentials for see how populate this objectIN

After this method is done the session is destroyed.

Methods for timestamp

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

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

getAvailableTimestampsallows getting the timestamp; available ONLY for Namirial account.

Each method is described below with the required inputs.

Method timestamp

timestamp
NameTypeDescriptionIN/OUT
contentbyte[]Byte array to which the timestamp is applied.IN
preferencesTimeStampPreferencesPreferences about timestamp url, username, password, etc.IN

byte[]Timestamp in binary format.OUT

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

timeStampPreferences
NameTypeMandatoryDefault valueDescriptionIncluded from SWS version
timestampUrlStringyes
Url for timestamp service
timestampUsernameStringyes
Username for timestamp service
timestampPasswordStringyes
Password for timestamp service
outputAsTSDboolean
true
  • TRUE permits to obtain in output the file+timestamp (TSD)
  • FALSE permits to obtain in output only timestamp (TSR)

outputBase64Encodedboolean
falsereturn the output in base64 encode
outputAsPDFboolean
falseAllow to obtain the timestamp according to Adobe standard2.5.44
timestampHashAlgoString
SHA256Hash algorithm used for generate the timestamp



Method getAvailableTimestamps (since SWS v2.5.44)

getAvailableTimestamps
NameTypeDescriptionIN/OUT
preferencesTimeStampPreferencestimestamp url, username, passwordIN

LongNumber of timestamps available. An exception will be generated for the payperuse .OUT

NOTE: TimestampUrl can be set to:

TIMESTAMP URLEnvironment
https://timestamp.namirialtsp.com/enquiryPROD
https://timestamp.test.namirialtsp.com/enquiryTEST

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:

Credentials
NameTypeDescription
usernameStringDevice name starts with: RHI (remote/disposable), SHI (eSeal) or AHI (automatic)
passwordStringPIN associated to device name (can be set by the customer or read into blind envelope)
idOtpintotp identifier associated to device (used only in remote signature) can be SMS, App, Token . Every remote device can have one or more idOtp (for example se
otpStrinngotp code for sign/change password (this is used only in remote device)

sessionKey

Stringstring code (like a token) valid 3 minutes for sign (instead to insert every times new otp code)
securityCodeStringThis is the second factor (used in automatic and eSeal) for change the password. This code is linked to the portal account.

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 you use the 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 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;


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.

getOTPList
NameTypeDescriptionIN/OUT
credentialsCredentialsYou must specify only credentials.username with the device name (RHI...)IN

List<OTP>list of OTPs associated to device nameOUT


The "OTP" object is compose by:

OTP
NameTypeDescription
idOtpintidentifier otp used for sign/change password
serialNumberStringthis field isn't used by SWS, this is serial number printed on OTP token
typeString

The possible values are:

  • SMS
  • OTP PUSH (not consider this value for SWS, this is used for other purpose)
  • OTP GENERATOR (OTP showed on Namirial App)
  • FISICO (this is the otp token)


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.

sendOTPBySMS
NameTypeDescriptionIN/OUT
credentialsCredentialsYou must specify only credentials.username with the device name (RHI...)IN

voidwill receive on your mobile phone the SMS with OTP codeOUT

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


openSession
NameTypeDescriptionIN/OUT
credentialsCredentials

You must specify:

  • credentials.username with the device name (RHI...)
  • credentials.password
  • credentials.idOtp
  • credentials.otp
IN

Stringwill receive the session which will be used for sign will be the value of credentials.sessionKeyOUT

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


You can find out when the session expires with the method getRemainingTimeForSession. This method requires input:
  • username
  • sessionKey (obtained from method "openSession")


getRemainingTimeForSession
NameTypeDescriptionIN/OUT
credentialsCredentials

You must specify:

  • credentials.username with the device name (RHI...)
  • credentials.sessionKey
IN

intseconds until the sessionKey is validOUT
Destroy the session manually

The method closeSession requires in input:

  • sessionKey

  • username


closeSession
NameTypeDescriptionIN/OUT
credentialsCredentials

You must specify:

  • credentials.username with the device name (RHI...)
  • credentials.sessionKey
IN


the sessionKey will be destroyedOUT

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:

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:



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:

REQUEST-remote-signPades
<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 followsRESPONSE-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:

PAdESPreferences
NameTypeMandatoryDefault valueDescriptionIncluded from SWS version
hashAlgorithmString
SHA256Algorithm you want to use for signature. Possible values are: SHA1, SHA256, SHA384, SHA512.
levelLevel
BSee the description of Level type.
signTypeint



encryptInAnyCaseboolean
false

filenameInTSDString

Not used.
outputAsTSDboolean

Not used.
withTimestampboolean
falseSpecify wheater you want to add the timestamp to the signed file or not,
outputBase64Encodedboolean
falseSet true if you want the file signed in Base64 encoding.
timestampHashAlgoString
SHA-256Algorithm you want to use during the process of applying timestamp.
timestampUrlString

URL of timestamp provider with standard RFC3161.

Namirial URL:

PROD: https://timestamp.namirialtsp.com / http://timestamp.namirialtsp.com

TEST: https://timestamp.test.namirialtsp.com / http://timestamp.test.namirialtsp.com


timestampUsernameString

Username of timestamp credentials.


timestampPasswordString

Password of timestamp credentials.
needAppearanceDisabledboolean
falseDeprecated.
page

1Indicate the page number on which you want to apply the signature appearance. If you want to add the appearance on the last page of the PDF file, you should set it to "-1".
withTimestampboolean
falseSet true if you want to apply the timestamp after the signature.
encryptionPasswordString

Specify the password PDF, if present.
lockFieldsList<String>



signerImageSignerImage

See the description of SignerImage.
signerImageReferenceString

Used to specify the template to be used. (used in old version)
withSignatureFieldboolean
falseSet true if you want to apply the signature on signature field in the PDF file.

SignerImage

The SignerImage object is composed of the following:

SignerImage
NameTypeMandatoryDefault valueDescriptionIncluded from SWS version
imagebyte[]

Contains the image you want to apply to the appearance.
signerNameString

Contains the text you want to type to the appearance.
reasonString

Indicate the reason for the signature.
textVisibleboolean
trueAllows the text to be shown on appearance or not.
textPositionString

Position of the "signerName" on appearance. It is possible to choose between:

  • TOP
  • BOTTOM
  • RIGHT
  • LEFT

xint

X coordinate of the appearance (0 is on left of the page).
yint

Y coordinate of the appearance (0 is on bottom of the page).
widthint

Specify the width of the appearance.
heightint

Specify the height of the appearance.
fieldName


Specify the fieldname to which the signature is to be applied. This fieldName must already exist in the PDF file before the signature is applied.
fontNameString
Times-Roman

Specify the font to be used for the text on the appearance. The possible values are:

  • Times-Roman
  • Times-Bold
  • Times-Italic
  • Times-BoldItalic
  • Helvetica
  • Helvetica-Bold
  • Helvetica-Oblique
  • Helvetica-BoldOblique
  • Courier
  • Courier-Bold
  • Courier-Oblique
  • Courier-BoldOblique
  • Symbol
  • ZapfDingbats

OR

Specify the ttf absolute path which contain custom font (see this section below to use specific ttf)

2.5.39
imageURLString

URL to get the logo for appearance.
imageVisibleboolean
falseAllows the logo to be displayed or not when it appears.
fontSizeint
10Allows the fontsize to set set.
imageFilenameString

Path of the logo on appearance.
scaledboolean
falseSet true if you want to resize the logo on appearance.
scaledTextboolean
falseReduce the font size until fit on the appereance
locationString

Place of the signature.2.5.53
fieldsNameListList<String>

List of fields signatures you want sign2.5.57
signAllFieldsboolean
falseAllow to sign all fields signatures available in a PDF2.5.57

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

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:

CAdESPreferences
NameTypeMandatoryDefault valueDescriptionIncluded from SWS version
filenameInTSD




outputAsTSD




outputBase64Encodedboolean
falseEncodes the just signed file in base64.
timestampHashAlgoString
SHA-256

Algorithm you want to use during the process of applying timestamp.


timestampPassword




timestampUrlString

URL of the timestamp provider with the RFC3161 standard.

Namirial URL:

PROD: https://timestamp.namirialtsp.com / http://timestamp.namirialtsp.com

TEST: https://timestamp.test.namirialtsp.com / http://timestamp.test.namirialtsp.com


timestampUsernameString

Username of the timestamp credentials.
hashAlgorithmStringyesSHA256Algorithm which you want to use for signing. Possible values: SHA1, SHA256, SHA384, SHA512.
levelLevel
BSee the description of Level type.
withTimestampboolean
false

Set true if you want to apply the timestamp after the signature.


counterSignature




counterSignatureIndex




detachedboolean
falseSet true if you want the signature and the files in two different files. The output will be the signature.

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:

XAdESPreferences
NameTypeMandatoryDefault valueDescriptionIncluded from SWS version
filenameInTSD




outputAsTSD




outputBase64Encodedboolean
falseEncodes the just signed file in base64.
timestampHashAlgoString
SHA-256

Algorithm you want to use during the process of applying timestamp.


timestampPassword




timestampUrlString

URL of the timestamp provider with the RFC3161 standard.

Namirial URL:

PROD: https://timestamp.namirialtsp.com / http://timestamp.namirialtsp.com

TEST: https://timestamp.test.namirialtsp.com / http://timestamp.test.namirialtsp.com


timestampUsernameString

Username of the timestamp credentials.
hashAlgorithmStringyesSHA256Algorithm you want to use for signing. Possibile values: SHA1, SHA256, SHA384, SHA512
levelLevel
BSee the description of Level type.
withTimestampboolean
false

Set true if you want to apply the timestamp after the signature.


detachedboolean
falseSet true if you want the signature and the files in two different files. The output will be the signature.
detachedReferenceURIString



signElementString

Allows to specify the "Id" on XML which you want to sign.
signatureIdString

Allows to specify the "Id" of the signature.
withoutSignatureExclusionboolean
falseAllows to sign the file with/without previous signature.
XPathQueryString

Allows to sign a specified path of XML

Level

You can see how to set the correct Level signature:

Level
ValueDescriptionApply on signatureIncluded from SWS version
BIn the signed file the electronic signature and the signing certificate are added.Pades, Cades, Xades
TLike B-Level, but adds a time-stamp, respectively a time-mark that proves the signature existed at a certain date and time.Pades, Cades, Xades
LTLike T-Level, but adds VRI (Verification Related Information) data to the DSS (Long Term).Pades, Cades, Xades
LTALike LT-level, but adds a time stamp document and VRI data for the TSA (Time Stamping Authority). An LTA may help to validate the signature beyond any event that may limit its validity (Long Term with Archive Time-Stamps).Pades, Cades, Xades
LTV(Long Term Validation) contains the OCSP/CRL response after the signature. It is used for validation after the signing certificate has expired.Pades

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:


NameTypeMandatoryDefault valueDescriptionIncluded from SWS version
filenameInTSD




outputAsTSD




outputBase64Encodedboolean
falseEncoded the file just signed in base64.
timestampHashAlgoString
SHA-256

Algorithm you want to use during the process of applying timestamp.


timestampPassword




timestampUrlString

URL of the timestamp provider with RFC3161 standard.

Namirial URL:

PROD: https://timestamp.namirialtsp.com / http://timestamp.namirialtsp.com

TEST: https://timestamp.test.namirialtsp.com / http://timestamp.test.namirialtsp.com



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:

NameTypeDescriptionIN/OUT
credentialsCredentials

You must specify:

  • credentials.username with the device name (RHI..., AHI, SHI)
IN

byte[]byte array of certificate associated to signer deviceOUT

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:

NameTypeDescriptionIN/OUT
credentialsCredentials

You must specify:

  • credentials.username with the device name (RHI..., AHI, SHI)
IN

intnumber of signatures availablesOUT

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:

NameTypeDescriptionIN/OUT
credentialsCredentials

You must specify:

  • credentials.username with the device name (RHI..., AHI, SHI)
IN

intnumber of signatures apposedOUT

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:


Error details
Error numberDescription
EnglishItalian
0No errors foundNessun errore riscontrato
1Generic errorErrore Generico
2Virtual device not foundDispositivo virtuale inesistente
3Virtual device lockedDispositivo virtuale bloccato
4Wrong credentialsCredenziali errate
5Wrong emergency codeCodice di emergenza errato
6Virtual device status changes deniedModifiche allo stato del dispositivo virtuale negate
7Signature errorErrore nella firma
8Error creating slotErrore nella creazione dello slot
9Error deleting slotErrore nella eliminazione dello slot
10PIN change errorErrore nel cambio PIN
11Key generation errorErrore nella generazione chiave
12Error in key management configurationErrore nella configurazione del sistema di gestione delle chiavi
13Wrong company codeCodice azienda errato
14No available slotsNessuno slot disponibile
15Virtual device already existsDispositivo virtuale gia' esistente
16Operation performed using a wrong certificateOperazione eseguita usando il certificato errato
17Wrong virtual device codeCodice dispositivo virtuale errato
18Slot already usedSlot gia' utilizzato
22Incompatible file format for the signature type requiredRichiesta una firma di file di formato non compatibile con il tipo di firma richiesto
23Unsupported hash algorithmAlgoritmo di hash non supportato
24Error decrypting CMS dataErrore nella decifratura del CMS EnvelopedData
25Error importing key and certificatesErrore nell'importazione di chiave e certificati
26The public key in the certificate does not match the private keyChiave pubblica nel certificato non corrisponde a quella privata
27Web method denied for the credentials or ssl certificate usedEseguita una chiamata a web method mediante credenziali o certificato ssl non abilitato per questa funzione
28CA doesn't existLa CA inserita non esiste
29The user didn't enter all required fields for the profileL'utente non ha inserito tutti i campi richiesti per il profilo
30EJBCA errorErrore di EJBCA
31Authorization deniedAutorizzazione negata
32Error due to waiting for data approvalErrore dovuto all'attesa per l'approvazione dei dati
33Error approving the entered dataErrore nell'approvazione dei dati inseriti
34Illegal queryErrore per query illegale
35Certificate already revokedCertificato gia' revocato in precedenza
36I / O error, caused by writing / reading / converting a file / byte array / stringErrore di I/O, causato dalla scrittura/lettura/conversione di un file/array di byte/stringa
37Payment verification failedVerifica di pagamento non andata a buon fine
38No available signaturesEseguite tutte le firme a disposizione
42A denied feature is invoked in the current modeE' stata richiamata una funzionalita' non permessa nella modalita' corrente
43A denied feature is invoked in the implementation usedE' stata richiamata una funzionalita' non permessa nell'implementazione usata
44Wrong OTP code, try again with the next codeCodice OTP errato, riprovare con il prossimo codice
45The key isn't associated to a certificateLa chiave non ha associato un certificato
46Unknown certificate formatE' stato passato un certificato di formato sconosciuto
47It isn't possible to open the slotNon e' stato possibile aprire lo slot
49Key login errorErrore di login sulla chiave
50Error generating the CSRErrore nella generazione del CSR
51The maximum number of attempts to access the virtual device is reachedRaggiunto il numero massimo di tentativi di accesso al dispositivo virtuale
52Error decryptingErrore nella decifra
53The certificate has expiredIl certificato associato alla chiave e' scaduto
54There are no tokens for automatic signature with Cosign HSMNon sono disponibili token per la firma automatica con hsm Cosign
55Error updating certificate in dbErrore durante l'aggiornamento del certificato nel db
56Wrong method useErrato utilizzo del metodo
57Method not implemented yetMetodo non ancora implementato
58Error assigning the OTPErrore durante l'assegnazione dell'OTP
59Error assigning the static tokenErrore durante l'assegnazione del token statico
60Error deleting the accountErrore durante la cancellazione dell'account
61Error activating the accountErrore durante l'attivazione dell'account
62Error loading the accountErrore durante il caricamento dell'account
63Error unlocking the accountErrore durante lo sblocco dell'account
64Unavailable hsm licensesLicenze per hsm esaurite
65PIN too shortPIN troppo corto
66Session key incorrectSession key errata
67Session key not specifiedSession key non specificata
68Session key undefinedSession key non definita
69Session key expiredSession key scaduta
70Session key not usableSession key non utilizzabile
71Error generating session keyErrore durante la generazione della session key
72Error incrementing the session counterErrore durante l'incremento del session counter
73Error sending OTP codeErrore durante l'invio del codice OTP
74Error deleting session keyErrore durante la cancellazione della session key
76Error appositioning timestampErrore durante l'apposizione della marca temporale
77Error closing sessionErrore durante la chiusura della sessione
78The number of documents to be signed differs from the number of signature preferencesIl numero di documenti da firmare differisce dal numero di preferenze di firma
79Error detecting Security WorldErrore durante il rilevamento del Security World
80Error detecting the ModuleErrore durante il rilevamento del Modulo
81Error reading the SoftCardErrore durante la lettura della SoftCard
82Error writing the SoftCardErrore durante la scrittura della SoftCard
83Error deleting the SoftCardErrore durante la cancellazione della SoftCard
84Error loading SoftCardErrore durante il caricamento della SoftCard
85SoftCard not loadedSoftCard non caricata
86SoftCard already exists in the systemSoftCard gia' esistente a sistema
87SoftCard does not existSoftCard inesistente
88Error reading the keyErrore durante la lettura della chiave
89Error writing the keyErrore durante la scrittura della chiave
90Error deleting the keyErrore durante la cancellazione della chiave
91Error decrypting the RSA dataErrore durante la decifratura RSA
92Error decrypting the CMS envelopeErrore durante la decifratura CMS
93Error creating the SoftCardErrore durante la creazione della SoftCard
94The size of the hash does not coincide with the expected one by the algorithmLa dimensione dell'hash non coincide con quella prevista dall'algoritmo
95Error loading Cosign TokensErrore durante il caricamento dei Token Cosign
96The system takes too much time, HSM overload. Try againIl sistema impiega troppo tempo, HSM sovraccarico. Riprovare
97Timeout passedTimeout superato
98No signature device associated to the userNessun dispositivo di firma remota risulta associato all'utente in questione
1001The OTP device does not existDispositivo OTP non esistente a sistema
1007The OTP device was not activatedIl dispositivo OTP non risulta essere stato attivato
1009Unavailable attempts for the OTP deviceSuperato il numero massimo di tentativi per il dispositivo OTP
1016The OTP device was not associated to the holderIl dispositivo OTP non risulta essere stato associato al titolare

Method getErrors

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

NameTypeOptionalDescriptionIN/OUT
langString
String county code in 2 digit, accept only EN, IT.IN
errorCodeIntegertrueSpecify the error code you want to receive in the error description. If not specified will return return all errors in a specified language.IN

List<ErrorDetails>
Return a list with the error(s) description.OUT

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:



NameTypeMandatoryDescriptionIN/OUT
signedContentbyte[]✔️file to be verifiedIN
preferencesVerifyPreferences
Contain the preferences to be used during the verify processIN

SignedDocumentReportBean
Composite class which contain the report of a signatureOUT

Below will be described the complex object "VerifiyPreferences"

VerifyPreferences
NameTypeMandatoryDefault valueDescriptionIncluded from SWS version
checkByteRangeboolean



detachedContentbyte[]

Contain the original file if you are verifying a detached signature
includeFea

falseIf set to true permits to verify the FEA (Firma Elettronica Avanzata) signature
languageString
IT

Contain the country code two digit and specify the language of verification report. 


mandatoryRevocationCheckboolean
false

pdfEncryptionPasswordString

Contains the password of PDF files (if you are verifying PDF files with password)
recursiveboolean
falseCheck if there are signatures in the file which has been signed
verifyOnDateDate

Date of verification at specified date
namirialboolean
falsePermits to use custom tsl specified on properties. Used only for test purpose.
withoutPlainDocumentboolean
falsePermits to omit the plain document2.5.54

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


SignedDocumentReportBean
NameTypeDescriptionIncluded from SWS version
overallVerifiedbooleanVery IMPORTANT: outcome of verification, if true the signature is VALID
checkDateDateDate of execute of verification
verificationDateDateDate of verification. For example if the verification date is: "2021-09-03 15:30:00" specificy i want verify in that date.
plainDocumentbyte[]Original file (present only in Cades signatures)
noteReportListNoteReportBeanList of notes to support the signature evaluation
signatureReportListSignatureReportBeanList of specific report on a single signature
nrOfSignaturesintNumber of signature in the file are you verifiyng
signatureFormatString

Specify the type of signature. Can be: Pades, Cades or Xades


timestampReportListTimestampReportBeanReports list in possible timestamps apposed to the signature

Below will be described the complex object NoteReportBean, SignatureReportBean:

NoteReportBean
NameTypeDescriptionIncluded from SWS version
policyintNote validity area (0=ALL, 1=IT, 2=EU)
aboutintObject of the note (O=other, 1=Signature, 2=holder, 3=issuer, 4=timestamp)
typeintType of the note (1=INFO, 2=WARNING, 3=ERROR)
synopsisStringBrief description of the note (for example: "Key on secure device")
descriptionStringDetailed description of the note: "The private key associated with the test azienda certificate is stored in a secure device compliant with European Regulation 2014/910/EU"
SignatureReportBean
NameTypeDescriptionIncluded from SWS version
integritybooleanIt defines the integrity of signature
signatureAlgorithmNameStringAlghoritm used to sign
serialNumberBigIntegerSerial of the signing certificate
subjectDNStringSubject DN of the signing certificate
subjectCNStringCommon Name (CN) in the subject DN associated to the signing certificate
issuerDNStringSubject DN associated to the issuer of signing certificate
issuerDNStringCommon name (CN) of subject DN associated to the issuer of signing certificate
issuerCertificateStatusenumIssuer's certificate status. It can have the following values: VALID, REVOKE, UNKNOWN
issuerInTrustedListbooleanIt defines if the issuer of the signing certificate is a trusted entity defined by the European TSL
keySizeintsize of key associated to the signer certificate
qcComplianceStatusenumIt defines if the signatures is in line with the Qualified Signature requirements. It can have the following values: VALID, INVALID, UNDETERMINATED, VALID_WITH_WARNINGS, INFORMATION
qcSSCDStatusenumIf defines if the signature was created by a secure device (like smartcard, token, hsm) NOT file (p12, jks)
signatureDateDateDate of signature
trustedSignatureDatebooleanSet to true if the signature include timestamp (to guarantee the date of signature)
derEncodedSignerCertbyte[]Signer certificate in X509 format
signerCertifcateNotBeforeDateStart date of the validity of the signing certificate
signerCertificateNotAfterDateEnd date of the validity of the signing certificate
signerCertificateStatusenum

Status of certificate. The value can be:

  • VALID
  • REVOKED
  • HOLD
  • UNKNOWN

idintnumber of signature

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:

NameTypeMandatoryDescriptionIN/OUT
tsrbyte[]✔️tsr to verifyIN
contentbyte[]✔️original fileIN

TimestampReportBean
Report with detail of verificationOUT



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

NameTypeMandatoryDescriptionIN/OUT
tsdbyte[]✔️tsd to verifyIN

List<TimestampReportBean>
Report with detail of verificationOUT

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

NameTypeMandatoryDescriptionIN/OUTIncluded from SWS version
timestampedContedbyte[]✔️tsr or tsd to verifyIN2.5.55
preferences

VerifyTimestampPreferences


Contain the preferences about verify like language, original files (if you are verifying a TSR file)IN"

TimestampReportBeanSummary


Report with detail of verificationOUT"

Below will be described the complex object VerifyTimestampPreferences:

VerifyTimestampPreferences

Name

Type

Default valueMandatory

Description

detachedContent

byte[]



Contain the original file where has been applied the timestamp, use this field only if you are verifying the TSR

responseWithoutContent

boolean

false

Permits to remove the original files from the response (use this flag for reduce the bandwith usage)

language

String

IT

Specify the language report associated to verify

Below will be described the complex object TimestampReportBeanSummary:

TimestampReportBeanSummary

Name

Type

Description

timestampReportList

List<TimestampReportBean>

Detailed report of every timestamp in TSD file

noteReportList

List<NoteReportBean>

Other details about timestamp

overallVerified

boolean

Very IMPORTANT: outcome of verification, if true the all timestamps are VALID

Below will be described the complex object TimestampReportBean:

TimestampReportBean

Name

Type

Description

Included from SWS version

index

Integer

Return the number of timestamp verified


date

Date

When the timestamp has been apposed


signatureVerificationStatus

enum

The status of the integrity of the timestamp (indicates if the token's signature is intact), the value can be:

  • VALID
  • INVALID


trustedListVerificationStatus

enum

The status of the root certificates associated, the value can be:

  • VALID
  • INVALID
  • UNDETERMINATED


timestampCertificateStatus

enum

The status of certifcate which has apposed the timestamp, the value can be:

  • VALID
  • INVALID
  • UNDETERMINATED


issuer

String

Subject DN associated to the issuer certificate


subject

String

Subject DN associated to timestamp certificate


issuerCN

String

CN (Common Name) of Subject DN associated to the issuer certificate


subjectCN

String

CN (Common Name) of Subject DN associated to the timestamp certificate


serialNumber

BigInteger

Serial number associated to timestamp certificate


signatureAlgorithm

String

Algorithm used for apply the timestamp


hashAlgorithm

String

Algorithm used for the hash generation for document hash


comment

String

Message explain the details of the error if present


timestampCertData

byte[]

Certificate associated to timestamp


content

byte[]

File oringinal which has been applied the timestamp


contentFilename

String

Return the filename if present else will return "originalFile.bin"


contentMimeType

String

Return the content type associated to the file if present. Else will return "application/octect-stream"


timeStampToken

byte[]

Contain the timestamp associated


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

NameTypeMandatoryDescriptionIN/OUT
certificatebyte[]✔️certificate to verifyIN

CertificateReportBean
Report with detail of verificationOUT


Below will be described the complex object CertificateReportBean:

CertificateReportBean

Name

Type

Description

Included from SWS version

trusted

boolean

Set to TRUE mean the root certificate of the chain is in trusted list. The root of the chain is the self-signed certificate (where issuerDN = subjectDN)


subjectValid

boolean

TRUE: if the certificate isn't expired

FALSE: the certificate is expired


subjectRevokedboolean

TRUE: if the certificate is hold or revoked

FALSE: the certificate is active


subjectRevocationDateDatedate of revoke/hold
issuerValidboolean

TRUE: if the issuer of the certificate isn't expired

FALSE: the certificate is expired


issuerRevokedboolean

TRUE: if the issuer certificate is hold or revoked

FALSE: the issuer certificate is active


issuerRevocationDateDatedate of revoke/hold


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.

NameTypeMandatoryDescriptionIN/OUT
bufferbyte[]✔️The file to search for signature fieldsIN
encryptionPasswordStringThe encryption password of the PDF in the file is encryptedIN

List<String>
List of all signature field names availableOUT


Example response

An example response can be found below:

Example response
[
    "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.

NameTypeMandatoryDescriptionIN/OUT
bufferbyte[]✔️The file to search for signature fieldsIN
preferencesSignatureFieldPreferencesPreferences to be applied to the search operationIN

List<SignatureFieldName>
List of all signature field namesOUT

SignatureFieldPreferences

Here you can find a description of the complex object SignatureFieldPreferences

SignatureFieldPreferences

Name

Type

Description

Included from SWS version

withDetails

boolean

Show details about the signature field signed, for example the appearence ( height, widht, x, y),

signer name, sign date, the reason, location and the page

DEFAULT=false

2.5.56

withCertificate

boolean

Retrieve the signer certificate in base64 encoding and certificate subjectDN

DEFAULT=false

2.5.56

encryptionPasswordStringThe encryption password used to protect the PDF given in input if present2.5.56

SignatureFieldName

Here you can find a description of the complex object SignatureFieldName

SignatureFieldName

Name

Type

Description

Included from SWS version

identifier

String

Signature field name identifier

2.5.56

signed

boolean

TRUE: the signature field is already signed

FALSE: the signature field is not signed

2.5.56

signatureDetailsSignatureDetailsComplex object containing details about the signature applied to a given field if signed2.5.56

SignatureDetails

Here you can find a description of the complex object SignatureDetails

SignatureDetails

Name

Type

Description

Included from SWS version

name

String

Signer name applied to a given signature field

2.5.56

signDate

Timestamp

Unix timestamp representing the date of when the signature has been applied

2.5.56

locationStringThe location of where the signature has been applied2.5.56
reasonStringReason applied to a given signature2.5.56
pageIntegerPage where the signature field is present ( -1 if the page is not found )2.5.56
appearancePdfRectangleComplex object containing info about the signature field box2.5.56
certificateStringBase64-encoding of the signer certificate2.5.56
subjectDNStringSubjectDN of the signer certificate2.5.56

PdfRectangle

Here you can find a description of the complex object PdfRectangle

PdfRectangle

Name

Type

Description

Included from SWS version

witdth

Float

Width of the signature field

2.5.56

height

Float

Heigth of the signature field

2.5.56

xFloatLower left X-Axis position of the signature field2.5.56
yFloatLower left Y-Axis position of the signature field2.5.56

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