After install and configure you virtual appliance SWS, now you can use their method to sign or apply timestamp. SWS have two interfaces SOAP or REST. SOAP is used for files under 50MB and REST interface is used for files over 50MB.
This guide is composed by this section:
SOAP INTERFACE
For test SOAP request to sign files. You can follow this step:
Download and install SoapUI from this link:
https://www.soapui.org/tools/soapui/
Once complete the installation:
open SoapUI → File → New Soap Project
And add appliance SWS method to SoapUI, like in this image:
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:
With SoapUI is possible to use the methods exposed by SWS SOAP interface.
The principal method used to sign, they are:
signPAdESList → Used for sign only PDF files
signCAdESList → Used for sign every type of files
signXAdESList → Used for sign XML files
getSignatures → permit to obtain the number of signature made since certicate creation
getAvailableSignatures → permit to obtain the numbers of signatures (valid only for device NOT pay per use, else it will generate 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 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
For verify the signature:
verifyWithPreferences → it permits to valid the signature, you can use this method for validate signature detached (the are signature composed by two files signature and file which has been signed)
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.
fieldName: use this variable with name of field signature if your PDF have a field signature else you should not set this variable.
fontName: name of the font used for the string on appereance
fontSizie: size of the font used for the string on appereance
height: specify the height (in pixel) of appereance
image: in SOAP request will be the image in base64 associated to the logo
imageFilename: used only in certain situation
imageURL: url which contain the image associated to the logo
imageVisible: set true if you want show the image in the appereance
location: this property is associated to the position of the String in appereance. The possible options are: BOTTOM, TOP, LEFT, RIGHT
reason: is a string ….insert the adobe image example