Content Comparison

Table of Contents

Introduction

The REST interface offered by SWS is exposed at the path:

Code Block
http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/

This path is composed by other sub-path for every of purpose:

admin: method for sws like remove certificate from cache
enquiry: contain the method for obtain the information like signatures available, signer certificate, timestamps available ecc...
sign: this is the principal path of SWS and contain the methods for apply the signature
timestamps: methods for apply the timestamp on every type of file

And in this guid will be described how manage the error generated by the REST interface.

Enquiry

ENQUIRY: certificate

Descriptionreturn the certifcate associated to "device_signer"

Table of Contents

Introduction

The REST interface offered by SWS is exposed at the path:

Code Block
http://<IP-APPLIANCE>:8080/SignEngineWeb/rest/

This path is composed by other sub-path for every of purpose:

admin: method for sws like remove certificate from cache
enquiry: contain the method for obtain the information like signatures available, signer certificate, timestamps available ecc...
sign: this is the principal path of SWS and contain the methods for apply the signature
timestamps: methods for apply the timestamp on every type of file

And in this guid will be described how manage the error generated by the REST interface.

Enquiry

ENQUIRY: certificate

Description

return the certifcate associated to "device_signer"

HttpMethod

POST

Path

/rest/enquiry/certificate

Request

Expand

title	request-enquiry-certificate

{
  "credentials": {
    "username": "device_signer"
  }
}

Response

return the byte array of certificate associated to device_signer

ENQUIRY: signatures

Description

return the numer of signatures apposed from "device_signer"

HttpMethod

POST

Path

/rest/enquiry/signatures

Request

Expand

title	request-enquiry-signatures

{
  "credentials": {
    "username": "device_signer"
  }
}

Response

Number of signatures apposed

ENQUIRY: signatures-available

HttpMethod	POST
Description	return the number of signatures which "device_signer" can apply
Path	/rest/enquiry/

certificate

signatures-available

Request

Expand

title	request-enquiry-signatures-

certificate

available

{
  "credentials": {
    "username": "device_signer"
  }
}

Response

Number of signatures available

ENQUIRY: otps

Description

return the

byte array of certificate

otp list associated to "device_signer

ENQUIRY: signatures

Descriptionreturn the numer of signatures apposed from

"

HttpMethod

POST

Path

/rest/enquiry/otps

Request

Expand

title	request-enquiry-otps

{
"credentials": {
"username": "device_signer"

HttpMethod

}

POST

}

Path

/rest/enquiry/signatures

Request

Response

Expand

title

request

response-enquiry-

signatures

otps

[
{

  "credentials": {
    "username": "device_signer"
  }
}ResponseNumber of signatures apposed

ENQUIRY: signatures

        "idOtp": number,
        "serialNumber": "string",
        "type": "otp-type-enum"
    },
{
        "idOtp": number,
        "serialNumber": "string",
        "type": "otp-type-enum"
    }
]

ENQUIRY: timestamps-available

Description

return the

number of signatures which "device_signer" can apply

HttpMethod	POST
numeber of timestamp available (valid only for Namirial TSA account)
Path	/rest/enquiry/

signatures

timestamps-available

Request

Expand

title	request-enquiry-

signatures

timestamps-available

{
"

credentials

timestampUrl":

{
"username

"timestamp-namirial-enquiry-url",
"timestampUsername": "

device_signer"
}

tsa-username",
"timestampPassword": "tsa-password"
}

Response

Number of

signatures

timestamps available

ENQUIRY:

otps

errors

Description

return the

otp list

error description associated to

"device_signer"

HttpMethod	POST
error code
Path	/rest/enquiry/

otps

errors

Request

Expand

title	request-enquiry-errors

{
"error_code": integer,
"lang": "COUNTRY-CODE-2DIGIT"
}

Response

Expand

title	response-enquiry

-otps{
  "credentials": {
    "username": "device_signer"
  }
}Response

Expand

title	response-enquiry-otps

[
    {
        "idOtp": number,
        "serialNumber": "string",
        "type": "otp-type-enum"
    },
{
        "idOtp": number,
        "serialNumber": "string",
        "type": "otp-type-enum"
    }
]

ENQUIRY: timestamps-available

Descriptionreturn the numeber of timestamp available (valid only for Namirial TSA account)

-errors

[
    {
        "errorCode": integer,
        "errorLanguage": "CONUNTRY-CODE-2DIGIT",
        "errorLanguage2": "COUNTRY-CODE-3DIGIT",
        "errorText": "Description error in language"
    }
]

Admin

ADMIN: remove-certificate-from-cache

Description

remove the certificate from cache of SWS

HttpMethod

PUT

Path

/rest/admin/remove-certificate-from-cache

Request

Expand

title	request-enquiry-remove-certificate-from-cache

{
"error_code": integer,
"lang": "COUNTRY-CODE-2DIGIT"
}

Response

Timestamps

TIMESTAMPS: apply

HttpMethod	POST
Description	permits to apply timestamp on specified file
Path	/rest/

enquiry

timestamps/

timestamps-available

apply

Request

timeStampPreferences

Expand

title	request-

enquiry-

timestamps-

available

{
  "timestampUrl": "timestamp-namirial-enquiry-url",
  "timestampUsername": "tsa-username",
  "timestampPassword": "tsa-password"
}

ResponseNumber of timestamps available

ENQUIRY: errors

Descriptionreturn the error description associated to error code

apply

{
"filenameInTSD": "string",
"outputAsPDF": true,
"outputAsTSD": true,
"outputBase64Encoded": true,
"timestampHashAlgo": "string",
"timestampPassword": "string",
"timestampUrl": "string",
"timestampUsername": "string"
}

content

file to apply timestamp

Response

User

USER: change-password

HttpMethod	POST
Description	permits to change the password associated to device signer
Path	/rest/

enquiry/errorsRequest

Expand

title	request-enquiry-errors

{
"error_code": integer,
"lang": "COUNTRY-CODE-2DIGIT"
}

Response

user/change-password

Request (for remote device signer)

Expand

title

response-enquiry-errors

[
    {
        "errorCode": integer,
        "errorLanguage": "CONUNTRY-CODE-2DIGIT",
        "errorLanguage2": "COUNTRY-CODE-3DIGIT",
        "errorText": "Description error in language"
    }
]

Admin

ADMIN: remove-certificate-from-cache

Descriptionremove the certificate from cache of SWSHttpMethodPUTPath

/rest/admin/remove-certificate-from-cache

Request

Expand

title	request-enquiry-remove-certificate-from-cache

{
"error_code": integer,
"lang": "COUNTRY-CODE-2DIGIT"
}

Response

Timestamps

TIMESTAMPS: apply

Descriptionpermits to apply timestamp on specified file

request-user-change-password-remote

{
  "credentials": {
    "idOtp": idOtp or -1,
    "otp": "otpCode",
    "password": "old-password-of-device-signer-remote",
    "username": "device-signer-remote"
  },
  "newPassword": "new-password-of-device-signer-remote"
}

Request (for automatic device signer)

Expand

title	request-user-change-password-automatic

{
  "credentials": {
"securityCode": "securityCode associate to automatic device signer",
    "password": "old-password-of-device-signer-automatic",
    "username": "device-signer-automatic"
  },
  "newPassword": "new-password-of-device-signer-automatic"
}

Response

Password update succesfully

Sign

SIGN: openSession

HttpMethod	POST
Description	permits to open the sessione for apply multiple sign with remote device
Path	/rest/

timestamps

sign/

apply

openSession

Request

timeStampPreferences

Expand

title	request-

timestamps

sign-

apply

openSession

{

"

filenameInTSD

credentials":

"string",
"outputAsPDF": true,
"outputAsTSD": true,
"outputBase64Encoded": true,
"timestampHashAlgo": "string",
"timestampPassword": "string",
"timestampUrl": "string",
"timestampUsername": "string"
}contentfile to apply timestampResponse

User

USER: change-password

Descriptionpermits to change the password associated to device signer

{
    "idOtp": -1,
    "otp": "775351",
    "password": "12345678",
    "username": "RHIP22021116852552"
  }
}

Response

String with the session

SIGN: getRemainingTimeForSession

HttpMethod	POST
Description	permits to obtain the time until the session is valid
Path	/rest/

user

sign/

change-password

getRemainingTimeForSession

Request

(for remote device signer)

Expand

title	request-

user-change-password-remote

sign-getRemainingTimeForSession

{
"credentials": {
"

idOtp

sessionKey":

idOtp or -1,
"otp": "otpCode",
"password": "old-password-of-device-signer-remote

"zZto1G0DpL/vBFkTnK7caquzY5pasOlzS+bQG7wUkOONnbV7Vhd+JSPTjP7ZqTYR12QjS0W89T7UmnQB2KzAQ3C4NalDgFE67ntqoGm7uOU7+oOPLvKQv/p5aeZ2bcjKe6x5KQPUEH//rKaExFcLcLj8cnwXfFBixJ4MN+3o8S5535HcRxWv+YoTHHgAY16Fh0yJGfLL3x/4W+HJeiIYL2cHpKNTGkKcGTM8Eon0R+djNFvKzZSF1VIETPADqDdvgLYkRWODd3yoUvExGk5BcQKVm0Z7Nd7NMKl4NRbHumdqmqy81jchQv2qlXIxSpjZ0GTnL4vDZMF2MP2DGHPoWw==",
"username": "

device-signer-remote

RHIP22021116852552"

},
"newPassword": "new-password-of-device-signer-remote"
}Request (for automatic device signer)

}
}

Response

Seconds until the session is valid

SIGN: closeSession

SIGN: openSession

Description

permits to destroy the session before will expire

HttpMethod

POST

Path

/rest/sign/closeSession

Request

Expand

title	request-

user-change-password-automatic

sign-closeSession

{
"credentials": {

"securityCode": "securityCode associate to automatic device signer",

"

password

sessionKey": "

old-password-of-device-signer-automatic",
    "username": "device-signer-automatic"
  },
  "newPassword": "new-password-of-device-signer-automatic"
}ResponsePassword update succesfully

Sign

zZto1G0DpL/vBFkTnK7caquzY5pasOlzS+bQG7wUkOONnbV7Vhd+JSPTjP7ZqTYR12QjS0W89T7UmnQB2KzAQ3C4NalDgFE67ntqoGm7uOU7+oOPLvKQv/p5aeZ2bcjKe6x5KQPUEH//rKaExFcLcLj8cnwXfFBixJ4MN+3o8S5535HcRxWv+YoTHHgAY16Fh0yJGfLL3x/4W+HJeiIYL2cHpKNTGkKcGTM8Eon0R+djNFvKzZSF1VIETPADqDdvgLYkRWODd3yoUvExGk5BcQKVm0Z7Nd7NMKl4NRbHumdqmqy81jchQv2qlXIxSpjZ0GTnL4vDZMF2MP2DGHPoWw==",
"username": "RHIP22021116852552"
}
}

Response

SIGN: sendOtpBySMS

Description

permits to

open the sessione for apply multiple sign with remote device

HttpMethod	POST
destroy the session before will expire
Path	/rest/sign/

openSession

sendOtpBySMS

Request

Expand

title	request-sign-

openSession

closeSession

{
"credentials":

{

"idOtp": -1,
"otp": "775351",

"

password": "12345678",
"

username": "RHIP22021116852552"
}
}

Response

String with the session

SIGN:

getRemainingTimeForSession

signCades

Description

permits to

obtain the time until the session is valid

HttpMethod	POST
apply the cades signature
Path	/rest/sign/

getRemainingTimeForSession

signCades

Request

credentials

Expand

title	request-

sign

signCades-

getRemainingTimeForSession

credentials

{

  "credentials": {
    "sessionKey": "zZto1G0DpL/vBFkTnK7caquzY5pasOlzS+bQG7wUkOONnbV7Vhd+JSPTjP7ZqTYR12QjS0W89T7UmnQB2KzAQ3C4NalDgFE67ntqoGm7uOU7+oOPLvKQv/p5aeZ2bcjKe6x5KQPUEH//rKaExFcLcLj8cnwXfFBixJ4MN+3o8S5535HcRxWv+YoTHHgAY16Fh0yJGfLL3x/4W+HJeiIYL2cHpKNTGkKcGTM8Eon0R+djNFvKzZSF1VIETPADqDdvgLYkRWODd3yoUvExGk5BcQKVm0Z7Nd7NMKl4NRbHumdqmqy81jchQv2qlXIxSpjZ0GTnL4vDZMF2MP2DGHPoWw==",
    "username": "RHIP22021116852552"
  }
}ResponseSeconds until the session is valid

SIGN: closeSession

Descriptionpermits to destroy the session before will expireHttpMethodPOSTPath

/rest/sign/sendOtpBySMS

Request

Expand

title	request-sign-closeSession

{
  "credentials": {
    "username": "RHIP22021116852552"
  }
}

ResponseSIGN: signCades

Descriptionpermits to destroy the session before will expireHttpMethodPOSTPath

/rest/sign/closeSession

Request

"username":"device signer name",

"password":"PIN of device signer name",

"idOtp":associated to device signer or -1,

"otp":"otp code",

"sessionKey":"string with sessionKey"

}

cadesPreferences

Expand

title	request-

sign-closeSession

{
  "credentials": {
    "sessionKey": "zZto1G0DpL/vBFkTnK7caquzY5pasOlzS+bQG7wUkOONnbV7Vhd+JSPTjP7ZqTYR12QjS0W89T7UmnQB2KzAQ3C4NalDgFE67ntqoGm7uOU7+oOPLvKQv/p5aeZ2bcjKe6x5KQPUEH//rKaExFcLcLj8cnwXfFBixJ4MN+3o8S5535HcRxWv+YoTHHgAY16Fh0yJGfLL3x/4W+HJeiIYL2cHpKNTGkKcGTM8Eon0R+djNFvKzZSF1VIETPADqDdvgLYkRWODd3yoUvExGk5BcQKVm0Z7Nd7NMKl4NRbHumdqmqy81jchQv2qlXIxSpjZ0GTnL4vDZMF2MP2DGHPoWw==",
    "username": "RHIP22021116852552"
  }
}

Response

SIGN: sendOtpBySMS

signCades-cadesPrefernces

{
"filenameInTSD": "string",
"outputAsPDF": boolean,
"outputAsTSD": boolean,
"outputBase64Encoded": boolean,
"timestampHashAlgo": "string",
"timestampPassword": "string",
"timestampUrl": "string",
"timestampUsername": "string",
"hashAlgorithm": "string",
"level": "enum",
"withTimestamp": boolean,
"counterSignature": true,
"counterSignatureIndex": 0,
"detached": boolean
}

content

file to sign

Response

byte array of signed files

SIGN: signPades

Description

permits to apply the

cades

HttpMethod	POST
pades signature
Path	/rest/sign/

signCades

signPades

Request

credentials

Expand

title	request-

signCades

signPades-credentials

{

"username":"device signer name",

"password":"PIN of device signer name",

"idOtp":associated to device signer or -1,

"otp":"otp code",

"sessionKey":"string with sessionKey"

}

cadesPreferences

padesPreferences

Expand

title	request-

signCades

signXades-

cadesPrefernces

xadesPreferences

{
"filenameInTSD": "string",
"outputAsPDF": boolean,
"outputAsTSD": boolean,
"outputBase64Encoded": boolean,
"timestampHashAlgo": "string",
"timestampPassword": "string",
"timestampUrl": "string",
"timestampUsername": "string",
"hashAlgorithm": "string",
"level": "enum",
"withTimestamp": boolean,
"

counterSignature

encryptInAnyCase":

true

boolean,
"

counterSignatureIndex

encryptionPassword":

0

"string",
"

detached

lockFields":

boolean
}contentfile to signResponsebyte array of signed files

SIGN: signPades

Descriptionpermits to apply the pades signatureHttpMethodPOSTPath

/rest/sign/signPades

Requestcredentials

Expand

title	request-signPades-credentials

{

"username":"device signer name",

"password":"PIN of device signer name",

"idOtp":associated to device signer or -1,

"otp":"otp code",

"sessionKey":"string with sessionKey"

}

padesPreferences Expand

title	request-signXades-xadesPreferences

{
"filenameInTSD

[
"string"
],
"needAppearanceDisabled": boolean,
"page": 0,
"signerImage": {
"fieldName": "string",
"fontName": "string",
"fontSize": 0,
"image": "string",
"imageFilename": "string",
"imageURL": "string",
"imageVisible": boolean,
"location": "string",
"reason": "string",
"

outputAsPDF

scaled":

boolean

true,
"

outputAsTSD

signerName":

boolean

"string",
"

outputBase64Encoded

textPosition":

boolean

"enum",
"

timestampHashAlgo

textVisible": boolean,
"

string

width": int,

"

timestampPassword

height":

"string"

int,
"

timestampUrl

x": int,
"

string

y": int
},
"

timestampUsername

signerImageReference": "string",
"

hashAlgorithm": "string",
"level": "enum",
"withTimestamp": boolean,
"encryptInAnyCase": boolean,
"encryptionPassword": "string",
"lockFields": [
"string"
],
"needAppearanceDisabled": boolean,
"page": 0,
"signerImage": {
"fieldName": "string",
"fontName

withSignatureField": boolean
}

image

file with image (of appereance)

content

PDF file to sign

Response

byte array of signed files

SIGN: signXades

Description

permits to apply the pades signature

HttpMethod

POST

Path

/rest/sign/signXades

Request

credentials

Expand

title	request-signPades-credentials

{

"username":"device signer name",

"password":"PIN of device signer name",

"idOtp":associated to device signer or -1,

"otp":"otp code",

"sessionKey":"string with sessionKey"

}

xadesPreferences

Expand

title	request-signPades-padesPreferences

{
"filenameInTSD": "string",

"

fontSize

outputAsPDF":

0

boolean,

"

image

outputAsTSD":

"string"

boolean,

"

imageFilename

outputBase64Encoded":

"string"

boolean,

"

imageURL

timestampHashAlgo": "string",

"

imageVisible

timestampPassword":

boolean

"string",

"

location

timestampUrl": "string",

"

reason

timestampUsername": "string

",

"

scaled": true

,

"

signerName

hashAlgorithm": "string",

"

textPosition

level": "enum",

"

textVisible

withTimestamp": boolean,

"

width

detached":

int

boolean,

"

height

detachedReferenceURI":

int,

"

x

string"

: int

,

"

y

signElement":

int
}

"string",
"

signerImageReference

signatureId": "string",
"

withSignatureField

withoutSignatureExclusion": boolean,
"xPathQuery": "string"
}

imagefile with image (of appereance) contentPDF

content	XML file to sign
Response	byte array of signed files

SIGN:

signXades

signPKCS1

Description

permits to apply the pades signature

HttpMethod

POST

Path

/rest/sign/signXadessignPKCS1

Request

credentials

Expand

title	request-signPades-credentials

{

"username":"device signer name",

"password":"PIN of device signer name",

"idOtp":associated to device signer or -1,

"otp":"otp code",

"sessionKey":"string with sessionKey"

}

xadesPreferencessignPreferences

{
"filenameInTSD": "string",
"outputAsPDF": boolean,
"outputAsTSD": boolean,
"outputBase64Encoded": boolean,
"timestampHashAlgo": "string",
"timestampPassword

Expand

title	request-signPadessignPKCS1-padesPreferences

signPreferences

{
    "filenameInTSD": "string",
    "timestampUrloutputAsPDF": "string"true,
    "timestampUsernameoutputAsTSD": "string"true,
    "hashAlgorithmoutputBase64Encoded": "string"false,
    "leveltimestampHashAlgo": "enum",
    "withTimestamptimestampPassword": boolean,
"detachedstring": boolean,
    "detachedReferenceURItimestampUrl": "string",
    "signElementtimestampUsername": "string",
    "signatureIdhashAlgorithm": "stringenum",
    "withoutSignatureExclusionlevel": boolean"enum",
"xPathQuerywithTimestamp": "string"true
}

contentbuffer

XML file hash to sign

Response

byte array of associated to hash signed files

Version	Old Version 33	New Version 34
Changes made by	Lorenzo Cardinali	Lorenzo Cardinali
Saved on	Sept 01, 2022	Sept 07, 2022

Content Comparison

Versions Compared

Key

Introduction

Enquiry

ENQUIRY: certificate

Introduction

Enquiry

ENQUIRY: certificate

ENQUIRY: signatures

ENQUIRY: signatures-available

ENQUIRY: otps

ENQUIRY: signatures

ENQUIRY: timestamps-available

ENQUIRY:

errors

ENQUIRY: timestamps-available

Admin

ADMIN: remove-certificate-from-cache

Timestamps

TIMESTAMPS: apply

ENQUIRY: errors

User

USER: change-password

Admin

ADMIN: remove-certificate-from-cache

Timestamps

TIMESTAMPS: apply

Sign

SIGN: openSession

User

USER: change-password

SIGN: getRemainingTimeForSession

SIGN: closeSession

Sign

SIGN: sendOtpBySMS

SIGN:

signCades

SIGN: closeSession

SIGN: sendOtpBySMS

SIGN: signPades

SIGN: signPades

SIGN: signXades

SIGN:

signPKCS1