You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 24 Next »

Introduction

Below will be detailed the SOAP request for sign, change password ecc...

All the methods described are on interface:

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

The SOAP request examples are generated using SoapUI, you can use this guide to configure SoapUI on your pc.

In this guide will be described the example of Soap Requests.


Credentials Object

All methods for sign require the ojbect Credentials is used to specify the device signature are you using for sign. This object is composed by this variables:

SOAP-credentials-object
<credentials>
	<username>?</username>
	<password>?</password>
	<idOtp>?</idOtp>
	<otp>?</otp>
	<securityCode>?</securityCode>
    <sessionKey>?</sessionKey>
</credentials>


According the device signature (automatic or remote) are you using you should populate different fields.


Automatic Signature

Below the example of Credentials :

SOAP-Credentials-object-automatic-signature
 <credentials>
	<username>AHI123456</username>
	<password>13572468</password>
 </credentials>

Fileds required:

  • username
  • password

Remote Signature

If you sign with the remote there are two ways:

  • specify "idOtp" and "otp"
  • specify the sessionKey


Example with "idOtp" and "otp":

SOAP-Credentials-object-remote-signature-idotp-otp
<credentials>
	<username>RHIP1234567</username>
	<password>13572468</password>
	<idOtp>501719</idOtp>
	<otp>150259</otp>
</credentials>

Example with "sessionKey"

SOAP-Credentials-object-remote-signature-sessionKey
<credentials>
	<username>RHIP1234567</username>
	<password>13572468</password>
	<sessionKey>sadlijhdfkjslherpoufdblkhesljherihbfdoihejheroihger</sessionKey>
 </credentials>

If you decide to sign with idOtp and OTP you must obtain the OTP code for sign (from SMS, App and Token) and idOtp.

How obtain the idOtp and OTP code


Below will described with SOAP request how obtain idOtp (with method getOtpList) and OTP code.


Obtain the idOtp


You can obtain the idOtp with method getOtpList. Below the example of SoapRequest. In this example we are using the devicename: "RHIP20102336019765":


REQUEST-getOTPList
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:getOTPList>
         <credentials>
            <username>RHIP20102336019765</username>
         </credentials>
      </ser:getOTPList>
   </soapenv:Body>
</soapenv:Envelope>


In output the SOAP response will be:


RESPONSE-getOTPList
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getOTPListResponse xmlns:ns2="http://service.ws.nam/">
         <return>
            <idOtp>501719</idOtp>
            <serialNumber>20210113-091031RJ2L1</serialNumber>
            <type>SMS</type>
         </return>
         <return>
            <idOtp>537430</idOtp>
            <serialNumber>20210305-163726L0PYF</serialNumber>
            <type>OTP GENERATOR</type>
         </return>
         <return>
            <idOtp>537433</idOtp>
            <serialNumber>20210305-163726F0I75</serialNumber>
            <type>OTP PUSH</type>
         </return>
      </ns2:getOTPListResponse>
   </soap:Body>
</soap:Envelope>

During the signing process, it is possible to choose between these two idOtps: 501719 (associated with OTP SMS) and the idOTP: 537430 (associated with OTP GENERATOR).

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


For the signature we can choose two types of idOTP: 501719 or 537430.


Obtain the OTP code


With OTP SMS we can obtain the code using the method "sendOtpBySMS" like in this SOAP request:


REQUEST-sendOTPBySMS
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:sendOtpBySMS>
         <credentials>
            <username>RHIP20102336019765</username>
         </credentials>
      </ser:sendOtpBySMS>
   </soapenv:Body>
</soapenv:Envelope>


If everything is ok, in output response will be:

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


On your mobile phone, you will receive an SMS containing the OTP code (composed of 6 numbers) for signature. Now, for example, we have received the code: “214196”.


While with OTP App and Token you don't require the method of SWS because you can read the OTP code on Token display or on your smartphone display (if you are using the App).


Manage the sessionKey


Below will be describe the SOAP request example for obtain the sessionKey, check if the sessionKey is valid and destroy the sessionKey

Obtain the sessionKey


Below the SOAP request example for create the openSession:


REQUEST-openSession
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
	xmlns:ser="http://service.ws.nam/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:openSession>
         <credentials>
            <idOtp>501719</idOtp>
            <otp>150259</otp>
            <password>13572468</password>
            <username>RHIP20102336019765</username>
         </credentials>
      </ser:openSession>
   </soapenv:Body>
</soapenv:Envelope>


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


RESPONSE-REMOTE-openSession
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:openSessionResponse xmlns:ns2="http://service.ws.nam/">	
		<return>
			f4lf7bq/cCxW6mTgL3iGjFEST5cEAZjgLnXvV3hUFzFHcTvjlH3FOkJy+kv/0Zsv1
			uNK0S7L6jMqHYSspBz+CZl7h3r5IEP2FqrK7WJQTVyrNfyr/trZmDgxYOLuACyoZVUFIlnck5Lkjihui
			sv+gZeB68Spwm+cNDdQQdUS3ngzJavHXxo9ADCX6VDIKKMe/AY0v+R51XWE90JF5LfKEThlv1OCpQC5nhnW8WKOFOm
			P4vM90d79JhFYGVVSZWtnTQ9Dg8pOMvg9wwxNm3uGkKKaS7oTp1ewd+eCG/uSC9k3H2w9GB6vQLHQEbn6d
			VVMcsIqJ0RMmZ2IgraD+scb4Q==
		</return>
      </ns2:openSessionResponse>
   </soap:Body>
</soap:Envelope>


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


Check the sessionKey status


Below the SOAP request example for check the sessionKey status:

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


The SOAP response will be:

RESPONSE-remote-getRemainingTimeForSession
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getRemainingTimeForSessionResponse xmlns:ns2="http://service.ws.nam/">
         <return>167</return>
      </ns2:getRemainingTimeForSessionResponse>
   </soap:Body>
</soap:Envelope>


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

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


Destroy the sessionKey


Below the example of SOAP request for destroy the session:


REQUEST-remote-closeSession
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
	<soapenv:Header/>
		<soapenv:Body>
			<ser:closeSession>
				<credentials>					
				  <username>RHIP20102336019765</username> 
<sessionKey>f4lf7bq/cCxW6mTgL3iGjFEST5cEAZjgLnXvV3hUFzFHcTvjlH3FOkJy+kv/0Zsv1uNK0S7L6jMqHYSspBz+CZl7h3r5IEP2FqrK7WJQTVyrNfyr/trZmDgxYOLuACyoZVUFIlnck5Lkjihuisv+gZeB68Spwm+cNDdQQdUS3ngzJavHXxo9ADCX6VDIKKMe/AY0v+R51XWE90JF5LfKEThlv1OCpQC5nhnW8WKOFOm P4vM90d79JhFYGVVSZWtnTQ9Dg8pOMvg9wwxNm3uGkKKaS7oTp1ewd+eCG/uSC9k3H2w9GB6vQLHQEbn6dVVMcsIqJ0RMmZ2IgraD+scb4Q==
					</sessionKey>					
				</credentials>
			</ser:closeSession>
		</soapenv:Body>
</soapenv:Envelope>


The SOAP response will be ever like this:

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

Summarize


The credentials object for automatic signature is composed like in this example:


REQUEST-AUTOMATIC-Credentials
<credentials>
	<username>AHIP20102336019478</username>
	<password>1357268</password>
</credentials>


With remote signature if you don't use the sessionKey the object Credentials will be:

REQUEST-Credentials-Remote-OTP-SMS
<credentials>
	<password>13572468</password>
	<username>RHIP20102336019765</username>
	<idOtp>501719</idOtp>
	<otp>150259</otp>
</credentials>


While if you are using the sessionKey the object Credentials will be:

REQUEST-Credentials-Remote-OTP-SMS
<credentials>
	<password>13572468</password>
	<username>RHIP20102336019765</username>
<sessionKey>f4lf7bq/cCxW6mTgL3iGjFEST5cEAZjgLnXvV3hUFzFHcTvjlH3FOkJy+kv/0Zsv1uNK0S7L6jMqHYSspBz+CZl7h3r5IEP2FqrK7WJQTVyrNfyr/trZmDgxYOLuACyoZVUFIlnck5Lkjihuisv+gZeB68Spwm+cNDdQQdUS3ngzJavHXxo9ADCX6VDIKKMe/AY0v+R51XWE90JF5LfKEThlv1OCpQC5nhnW8WKOFOm P4vM90d79JhFYGVVSZWtnTQ9Dg8pOMvg9wwxNm3uGkKKaS7oTp1ewd+eCG/uSC9k3H2w9GB6vQLHQEbn6dVVMcsIqJ0RMmZ2IgraD+scb4Q==
	</sessionKey>
</credentials>

Methods for sign


Below will be described the SOAP request example for every type of signature:

  • Pades
  • Cades
  • Xades



SignPades


The SOAP request for create Pades signature:

signPades
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:signPAdES>
         <credentials>
            <password>foo123</password>
            <username>demo</username>
         </credentials>
         <buffer>BASE64-TO-SIGN</buffer>  
		<PAdESPreferences>       
    		<level>B</level>
		    <signerImage>
				<imageVisible>true</imageVisible>
				<image>BASE64-IMAGE-LOGO</image>
				<x>30</x>
				<y>30</y>
				<width>50</width>
				<height>50</height>
				<signerName>Name of Signer</signerName>
		   </signerImage>
		</PAdESPreferences>
    </ser:signPAdES>
   </soapenv:Body>
</soapenv:Envelope>


At this link is possible to see the full example (with file to sign and logo image) of signature Pades with appereance.


SignCades


The SOAP request for create Cades signature:

signCades
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.nam/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:signCAdES>
         <credentials>
            <password>foo123</password>
            <username>demo</username>
         </credentials>
         <buffer>VGhpcyBpcyB0aGUgZmlsZSB0byBiZSBzaWduZWQgZm9yIHRlc3Qu</buffer>
         <CAdESPreferences>
            <level>B</level>
         </CAdESPreferences>
      </ser:signCAdES>
   </soapenv:Body>
</soapenv:Envelope>

In this example the buffer to sign is "txt" files.

The SOAP request will be:

SOAP-response-signCades
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:signCAdESResponse xmlns:ns2="http://service.ws.nam/">       	<return>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</return>
      </ns2:signCAdESResponse>
   </soap:Body>
</soap:Envelope>

SignXades


The SOAP request for create Xades signature:

signXades



  • No labels