Verify TSR
Below an example of SOAP request:
The SOAP request for create raw signature (PKCS1):
Code Block |
---|
language | xml |
---|
title | SOAP-request-signPkcs1 |
---|
|
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
<soapenv:Header/>
<soapenv:Body>
<ser:signPkcs1>
<credentials>
<password>YOUR-DEVICE-PASSWORD</password>
<username>YOUR-DEVICE-NAME</username>
</credentials>
<hash>c1fbd2b034abaea9ec99535394f21bb556edcf1833c680ebdfcc76e1e635844b</hash>
<preferences>
<hashAlgorithm>SHA256</hashAlgorithm>
</preferences>
</ser:signPkcs1>
</soapenv:Body>
</soapenv:Envelope> |
The SOAP response will be:
Code Block |
---|
language | xml |
---|
title | SOAP-response-signPkcs1 |
---|
|
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:signPkcs1Response xmlns:ns2="http://service.ws.nam/">
<return>p1kGoLorh0dGXKOFV4NAAZSsFxEl3YEbSXSI8tlWCSkoDwKLN9wHeKaosAuuJMuL6Vl61AxiEoBFGh5/ufQLFKWaiMqvB5VYD62yXdp8f2dtMeCfqZGwLEV4ci/kd1iMvE2eYiGornXk9NoF+eg/+h6W8TZWSnYrjp0YlF1oJxOG1/r5qr+OVvWQ7n73fo3Qe6Rjw/TuSI5V+WDaboctuCIwlK5gM8R4cT552PrNLsnVYmwR4epSUTx5VYwag6IhEHYPUtUkbMGpvN+0C0cZY7NqOHPfqgrqks0HkMr4Z99DQAKOqSZHg+h4AIGvgqFGsLxSRWCbT2G7ve+qX7IVgg==</return>
</ns2:signPkcs1Response>
</soap:Body>
</soap:Envelope> |
Manage signer device
In this section you can find the example of SOAP request associated to the information about signer device, timestamp, errors
Method change password on automatic/eseal signature
Below an example of change password on automatic signer device (AHIP22021318589386):
Code Block |
---|
language | xml |
---|
title | REQUEST-AUTOMATIC/ESEAL-changePassword |
---|
|
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
<soapenv:Header/>
<soapenv:Body>
<ser:changePassword>
<credentials>
<password>13572468</password>
<securityCode>8214260012</securityCode>
<username>AHIP12345</username>
</credentials>
<newPassword>NEWPASSWORD123</newPassword>
</ser:changePassword>
</soapenv:Body>
</soapenv:Envelope> |
After this execution, the password/PIN of the device signature will be changed from "13572468" (old password) to "NEWPASSWORD123".
Method change password on remote signature
Below an example of change password on remote signer device (RHI3644468199007):
Code Block |
---|
language | xml |
---|
title | REQUEST-AUTOMATIC/ESEAL-changePassword |
---|
|
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
<soapenv:Header/>
<soapenv:Body>
<ser:changePassword>
<credentials>
<username>YOUR-DEVICE-NAME</username>
<password>YOUR-DEVICE-PASSWORD</password>
<idOtp>YOUR-ID-OTP</idOtp>
<otp>876321</otp>
</credentials>
<newPassword>NEWPASSWORD123</newPassword>
</ser:changePassword>
</soapenv:Body>
</soapenv:Envelope> |
After this execution the password/PIN of the device signature will be changed from "847291742" (old password) to "NEWPASSWORD123".
Method getCertificate
Below the SOAP request example for obtain the certificate associate to signer device: "SHI7493852568871"
Code Block |
---|
language | xml |
---|
title | SOAPREQUEST-request-getCertificate |
---|
|
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
<soapenv:Header/>
<soapenv:Body>
<ser:getCertificate>
<credentials>
<username>SHI12345</username>
</credentials>
</ser:getCertificate>
</soapenv:Body>
</soapenv:Envelope> |
The SOAP response will be:
Code Block |
---|
language | xml |
---|
title | SOAP-response-getCertificate |
---|
|
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:getCertificateResponse xmlns:ns2="http://service.ws.nam/">
<return>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</return>
</ns2:getCertificateResponse>
</soap:Body>
</soap:Envelope> |
In the tag "return" there is the base64 associated to the signer device.
verifyTimeStampResponse | linenumbers | true |
---|
|
Method getAvailableSignatures
Below the SOAP request example for obtain the certificate associate to signer device: "SHI7493852568871"
Code Block |
---|
language | xml |
---|
title | SOAP-request-getAvailableSignatures |
---|
|
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
<soapenv:Header/>
<soapenv:Body>
<ser:getCertificate>verifyTimeStampResponse>
<credentials>
<username>SHI12345</username><tsr>BASE_64_OF_TSR</tsr>
</credentials>
</ser:getCertificate>
</soapenv:Body>
</soapenv:Envelope> |
The SOAP response will be:
Code Block |
---|
language | xml |
---|
title | SOAP-response-getAvailableSignatures |
---|
|
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:getAvailableSignaturesResponse xmlns:ns2="http://service.ws.nam/">
<return>996413</return>
</ns2:getAvailableSignaturesResponse>
</soap:Body>
</soap:Envelope> |
In the tag "return" there is the number of signatures available.
Method getSignatures
Below the SOAP request example for obtain the certificate associate to signer device: "SHI7493852568871"
Code Block |
---|
language | xml |
---|
title | SOAP-request-getSignatures |
---|
|
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
<soapenv:Header/!--Optional:-->
<soapenv:Body>
<ser:getSignatures>
<credentials>
<username>SHI12345</username><content>BASE_64_OF_ORIGINAL_FILE</content>
</credentials>
</ser:getSignatures>verifyTimeStampResponse>
</soapenv:Body>
</soapenv:Envelope> |
The
SOAP response will be: Code Block |
---|
language | xml |
---|
title | SOAP-response-getSignatures |
---|
|
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:getSignaturesResponse xmlns:ns2="http://service.ws.nam/">
<return>3587</return>
</ns2:getSignaturesResponse>
</soap:Body>
</soap:Envelope> |
In the tag "return" there is the number of signatures apposed since the device has been created.
Manage errors in SWS
In this section will be described how manage the errors in SWS and obtain the info about errors.
If the SOAP request is not correct in output will obtain the SOAP response with this structure:
Code Block |
---|
<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> |
This SOAP response contains:
- error code = 44
- error message = "Codice OTP errato, riprovare con il prossimo codice"
By default SOAP response on SWS contains the error message in italian, but is possible to obtain the error message in other different languages using the method "getErrors".
Method getErrors
This method permits to obtain the list of all errors in a specified language or all languages.
For example if we want obtain the list of all errors in english language the SOAP request will be :
Code Block |
---|
language | xml |
---|
title | SOAP-request-getErrors |
---|
|
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
<soapenv:Header/>
<soapenv:Body>
<ser:getErrors>
<lang>EN</lang>
</ser:getErrors>
</soapenv:Body>
</soapenv:Envelope> |
In output will obtain a list of all errors in a specified language:
Code Block |
---|
language | xml |
---|
title | SOAP-response-getErrors |
---|
|
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:getErrorsResponse xmlns:ns2="http://service.ws.nam/">
<return>
<errorCode>0</errorCode>
<errorLanguage>EN</errorLanguage>
<errorLanguage2>ENG</errorLanguage2>
<errorText>No errors found</errorText>
</return>
<return>
<errorCode>1</errorCode>
<errorLanguage>EN</errorLanguage>
<errorLanguage2>ENG</errorLanguage2>
<errorText>Generic error</errorText>
</return>
.........................
.........................
.........................
<return>
<errorCode>1007</errorCode>
<errorLanguage>EN</errorLanguage>
<errorLanguage2>ENG</errorLanguage2>
<errorText>The OTP device was not activated</errorText>
</return>
<return>
<errorCode>1009</errorCode>
<errorLanguage>EN</errorLanguage>
<errorLanguage2>ENG</errorLanguage2>
<errorText>Unavailable attempts for the OTP device</errorText>
</return>
<return>
<errorCode>1016</errorCode>
<errorLanguage>EN</errorLanguage>
<errorLanguage2>ENG</errorLanguage2>
<errorText>The OTP device was not associated to the holder</errorText>
</return>
</ns2:getErrorsResponse>
</soap:Body>
</soap:Envelope> |
With this method is possible to obtain the description associated to a specified error code (in this example 44). Below the example:
Code Block |
---|
language | xml |
---|
title | SOAP-request-getErrors-on-specific-errorCode |
---|
|
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
<soapenv:Header/>
<soapenv:Body>
<ser:getErrors>
<lang>EN</lang>
<errorCode>44</errorCode>
</ser:getErrors>
</soapenv:Body>
</soapenv:Envelope> |
The SOAP response will be:
Code Block |
---|
language | xml |
---|
title | SOAP-request-getErrors-on-specific-errorCode |
---|
|
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:getErrorsResponse xmlns:ns2="http://service.ws.nam/">
<return>
<errorCode>44</errorCode>
<errorLanguage>EN</errorLanguage>
<errorLanguage2>ENG</errorLanguage2>
<errorText>Wrong OTP code, try again with the next code</errorText>
</return>
</ns2:getErrorsResponse>
</soap:Body>
</soap:Envelope> |
Methods for timestamp
Below the SOAP request for apply timestamp and get the timestamps available
Apply timestamp
Below an example of SOAP request for apply timestamp. In output will have the timestamp in TSD format
Code Block |
---|
language | xml |
---|
title | SOAP-request-timestamp |
---|
|
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
<soapenv:Header/>
<soapenv:Body>
<ser:timestamp>
<content>BASE64-FILE-TO-APPLY-TIMESTAMP</content>
<preferences>
<outputAsTSD>true</outputAsTSD>
<timestampHashAlgo>SHA-256</timestampHashAlgo>
<timestampUrl>TSA-URL</timestampUrl>
<timestampUsername>TSA-USERNAME</timestampUsername>
<timestampPassword>TSA-PASSWORD</timestampPassword>
</preferences>
</ser:timestamp>
</soapenv:Body>
</soapenv:Envelope> |
In output will obtain the TSD.
NOTE:
The TSA-URL for PROD environment is:
Code Block |
---|
|
https://timestamp.namirialtsp.com |
While the TSA-URL for TEST environment is:
Code Block |
---|
|
https://timestamp.test.namirialtsp.com |
Method getAvailableTimestamps
This method permits to obtain the timestamp available. Below an example:
Code Block |
---|
language | xml |
---|
title | SOAP-request-getAvailableTimestamps |
---|
|
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
<soapenv:Header/>
<soapenv:Body>
<ser:getAvailableTimestamps>
<preferences>
<timestampUrl>https://timestamp.test.namirialtsp.com/enquiry</timestampUrl>
<timestampUsername>TSA-USERNAME</timestampUsername>
<timestampPassword>TSA-PASSWORD</timestampPassword>
</preferences>
</ser:getAvailableTimestamps>
</soapenv:Body>
</soapenv:Envelope> |
The SOAP response will contain the number of timestamp available associate to TSA-USERNAME.
NOTE: if you are checking the PROD TSA account the timestampURL will be:
Code Block |
---|
|
https://timestamp.namirialtsp.com/enquiry |
Examples (source code)
Below will find the links contains the source code with examples.
Java:
To add on CMS repo
Php:
C#: https://cms.firmacerta.it/download/sws_cnet.zip
C# (for SaaS instance): https://cms.firmacerta.it/download/SignEngineWebClientSaaS.zipa list of complex objects: "TimestampReportBean" described in this section