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 guide will be described how manage the error generated by the REST interface.

NOTE: this interface is available from SWS version: 2.5.52

Convention (manage the response)

SWS rest interface use this convention for create the response

Request is CORRECT, will return response code 200 with response body (if present) . Like in this example:

Image Removed

Request NOT-CORRECT with error managed, will return response code 400 and the header will have the field "errorMsg" with error description (in Italian) and field "errorCode" with code error. Like in this example:

Image Removed

NOTE: if you want the "errorMsg" in a specified language, you can use the method "enquiry/errors" will be described in the next section.

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 guide will be described how manage the error generated by the REST interface.

NOTE: this interface is available from SWS version: 2.5.52

Convention (manage the response)

SWS rest interface use this convention for create the response

Request is CORRECT, will return response code 200 with response body (if present) . Like in this example:

Image Added

Request NOT-CORRECT with error managed, will return response code 400 and the header will have the field "errorMsg" with error description (in Italian) and field "errorCode" with code error. Like in this example:

Image Added

NOTE: if you want the "errorMsg" in a specified language, you can use the method "enquiry/errors" will be described in the next section.

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

Description

return the number of signatures which "device_signer" can apply

HttpMethod

POST

Path

/rest/enquiry/signatures-available

Request

Expand

title	request-enquiry-signatures-available

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

Response

Number of signatures available

ENQUIRY: otps

Description

return the otp list associated to "device_signer"

HttpMethod

POST

Path

/rest/enquiry/otps

Request

Expand

title	request-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

Description

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

HttpMethod

POST

Path

/rest/enquiry/certificatetimestamps-available

Request

Expand

title	request-enquiry-certificatetimestamps-available

{
"

credentials

timestampUrl":

{
"username

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

device_signer"
}

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

Responsereturn

the byte array of certificate associated to device_signerNumber of timestamps available

ENQUIRY:

signatures

errors

POST

Description

return the numer of signatures apposed from "device_signer"error description associated to error code

HttpMethod

POST

Path

/rest/enquiry/signatureserrors

Request

Description

return the number of signatures which "device_signer" can apply

HttpMethod

Expand

title	request-enquiry-signatureserrors

{

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

Response

Number of signatures apposed

ENQUIRY: signatures-available

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

Response

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

Description

remove the certificate from cache of SWS

HttpMethod

PUT

Path

/rest/enquiry/signatures-availableadmin/remove-certificate-from-cache

Request

Expand

title	request-enquiry-signatures-availableremove-certificate-from-cache

{
"

credentials

error_code":

{

integer,

"

username

lang": "

device_signer"
}

COUNTRY-CODE-2DIGIT"
}

Response

Number of signatures available

ENQUIRY: otps

Timestamps

TIMESTAMPS: apply

Descriptionreturn the otp list associated to "device_signer"

permits to apply timestamp on specified file

HttpMethod

POST

Path

/rest/enquirytimestamps/otpsapply

Request

timestampPreferences

Expand

title	request-enquirytimestamps-otpsapply

Expand

title	response-enquiry-otps

{

"

credentials

filenameInTSD":

{

"

username

string"

:

,
"

device_signer"
}
}

Response

[
    {
        "idOtp": number,
        "serialNumber": "string",
        "type": "otp-type-enum"
    },
{
        "idOtp": number,
        "serialNumber": outputAsPDF": boolean,
"outputAsTSD": boolean,
"outputBase64Encoded": boolean,
"timestampHashAlgo": "string",
"timestampPassword": "string",
"timestampUrl": "string",
          "typetimestampUsername": "otp-type-enumstring"
    }
]

ENQUIRY: timestamps-available

Description

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

}

content

file to apply timestamp

Response

User

USER: change-password

HttpMethod	POST
Description	permits to change the password associated to device signer
Path	/rest/enquiryuser/timestampschange-availablepassword
Request (for remote device signer)

ADMIN: remove-certificate-from-cache

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

Description

remove the certificate from cache of SWS

HttpMethod

PUT

Path

Expand

title	request-user-enquirychange-timestampspassword-availableremote

{
  "timestampUrlcredentials": "timestamp-namirial-enquiry-url",
  "timestampUsername{
    "idOtp": idOtp or -1,
    "otp": "tsa-usernameotpCode",
      "timestampPasswordpassword": "tsaold-password"
}

Response

Number of timestamps available

ENQUIRY: errors

Descriptionreturn the error description associated to error codeHttpMethodPOSTPath

/rest/enquiry/errors

Request

Expand

title	request-enquiry-errors

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

Response

Expand

title	response-enquiry-errors

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

Admin

-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

TIMESTAMPS: apply

Description

permits to open the sessione for apply multiple sign with remote device

HttpMethod

POST

Path

/rest/sign/openSession

Request

Expand

title	request-enquiry-remove-certificate-from-cachesign-openSession

{
  "error_code"credentials": {
    "idOtp": -1,
    "otp": "775351",
    "password": integer"12345678",
      "langusername": "COUNTRY-CODE-2DIGITRHIP22021116852552"
  }
}

Response

Timestamps

String with the session

SIGN: getRemainingTimeForSession

USER: change-password

Description

permits to apply timestamp on specified fileobtain the time until the session is valid

HttpMethod

POST

Path

/rest/timestampssign/applygetRemainingTimeForSession

RequesttimestampPreferences

Expand

title	request-timestampssign-applygetRemainingTimeForSession

{
"filenameInTSDcredentials": "string",
"outputAsPDF": boolean,
"outputAsTSD": boolean,
"outputBase64Encoded": boolean,
"timestampHashAlgo": "string",
"timestampPassword": "string",
"timestampUrl": "string",
"timestampUsername": "string"
}

content

file to apply timestamp

Response

User

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

Response

Seconds until the session is valid

SIGN: closeSession

Description

permits to change the password associated to device signerdestroy the session before will expire

HttpMethod

POST

Path

/rest/usersign/change-passwordcloseSession

Request (for remote device signer)

Expand

title	request-user-change-password-remotesign-closeSession

{
  "credentials": {
    "idOtpsessionKey": 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-remoteRHIP22021116852552"
  }
},
  "newPassword": "new-password-of-device-signer-remote"
}

Request (for automatic device signer)

Response

SIGN: sendOtpBySMS

Description

permits to destroy the session before will expire

HttpMethod

POST

Path

/rest/sign/sendOtpBySMS

Request

Expand

title	request-user-change-password-automaticsign-sendOtpBySMS

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

Response

Password update succesfully

Sign

SIGN:

openSession

signCades

Description

permits to open the sessione for apply multiple sign with remote deviceapply the cades signature

HttpMethod

POST

Path

/rest/sign/openSessionsignCades

Request

credentials

Description

permits to obtain the time until the session is valid

HttpMethod

POST

Path

/rest/sign/getRemainingTimeForSession

Request

Expand

title	request-signsignCades-openSessioncredentials

{

"credentialsusername": {
"idOtp": -1"device signer name",

"otppassword": "775351PIN of device signer name",

"passwordidOtp": "12345678"associated to device signer or -1,

"usernameotp": "RHIP22021116852552otp code"
}
}

Response

String with the session

SIGN: getRemainingTimeForSession

Expand

title	request-sign-closeSession

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

Response

SIGN: sendOtpBySMS

Descriptionpermits to destroy the session before will expireHttpMethodPOSTPath

/rest/sign/sendOtpBySMS

Request

Expand

title	request-sign-sendOtpBySMS

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

Response

SIGN: signCades

,

"sessionKey":"string with sessionKey"

}

cadesPreferences

Expand

title	request-signsignCades-getRemainingTimeForSessioncadesPrefernces

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

Response

Seconds until the session is valid

SIGN: closeSession

Descriptionpermits to destroy the session before will expireHttpMethodPOSTPath

/rest/sign/closeSession

Request

Description

permits to apply the cades signature

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

buffer

file to sign

Response

byte array of signed files

SIGN: signCades (detached output p7s)

If you want make the Cades detached signature, SWS not require all files to sign, but only the hash. The tag "buffer" will be the hash of the file.

For example if we want the cades detached signature of this PDF the procedure is:

1) Calculate the hash of this file, for example with the openssl:

Code Block
openssl dgst -sha256 -binary FILE_TO_BE_SIGN \| openssl enc -a

And in output will obtain the hash to sign, will be:

Code Block
HASH TO SIGN = msj3f4hJCSELbMkWjkFwNrf0XhkebTnAKaKhx4686DY=

This string "msj.....DY=" will be the "buffer" on REST signCades

HttpMethod	POST
Description	permits to obtain the cades detached signature (p7s) , from the hash associated to the file to sign
Path	/rest/sign/signCades

Requestcredentials

Expand

title	request-signCades-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

Request

credentials

Expand

title	request-signCades-

cadesPrefernces

credentials

{

"

filenameInTSD

username":"

string

device signer name",

"

outputAsPDF

password":

boolean,
"outputAsTSD": boolean

"PIN of device signer name",

"

outputBase64Encoded": boolean,
"timestampHashAlgo": "string",
"timestampPassword": "string",
"timestampUrl": "string",
"timestampUsername": "string",
"hashAlgorithm": "string",
"level": "enum",
"withTimestamp": boolean,
"counterSignature": true,
"counterSignatureIndex": 0,
"detached": boolean
}bufferfile to sign

idOtp":associated to device signer or -1,

"otp":"otp code",

"sessionKey":"string with sessionKey"

}

cadesPreferences

Expand

title	request-signCades-cadesPrefernces

{"detached": true}

buffer

btye array relates to the hash files to sign (for example like this)

Response

byte array of signed files

SOAP RESPONSE:

In output will obtain the hash signed and the certificate associated to the private key which has signed the hash, the response will be this

SIGN: signPades

Description

permits to apply the pades signature

HttpMethod

POST

Path

/rest/sign/signPades

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"

}

padesPreferences

Expand

title	request-signPades-padesPreferences

{
"filenameInTSD": "string",
"outputAsPDF": boolean,
"outputAsTSD": boolean,
"outputBase64Encoded": boolean,
"timestampHashAlgo": "string",
"timestampPassword": "string",
"timestampUrl": "string",
"timestampUsername": "string",
"hashAlgorithm": "string",
"level": "enum",
"withTimestamp": boolean,
"encryptInAnyCase": boolean,
"encryptionPassword": "string",
"lockFields": [
"string"
],
"needAppearanceDisabled": boolean,
"page": 0,
"signerImage": {
"fieldName": "string",
"fontName": "string",
"fontSize": 0,
"image": "string",
"imageFilename": "string",
"imageURL": "string",
"imageVisible": boolean,
"location": "string",
"reason": "string",
"scaled": true,
"signerName": "string",
"textPosition": "enum",
"textVisible": boolean,

"scaledText": boolean,
"width": int,

"height":int,
"x": int,
"y": int
},
"signerImageReference": "string",
"withSignatureField": boolean
}

image

file with image (of appereance)

buffer

PDF file to sign

Response

byte array of signed files

SIGN: signXades

Description

permits to apply the xades signature

HttpMethod

POST

Path

/rest/sign/signXades

Request

credentials

Expand

title	request-signXades-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-signXades-xadesPreferences

{
"filenameInTSD": "string",
"outputAsPDF": boolean,
"outputAsTSD": boolean,
"outputBase64Encoded": boolean,
"timestampHashAlgo": "string",
"timestampPassword": "string",
"timestampUrl": "string",
"timestampUsername": "string",
"hashAlgorithm": "string",
"level": "enum",
"withTimestamp": boolean,
"detached": boolean,
"detachedReferenceURI": "string",
"signElement": "string",
"signatureId": "string",
"withoutSignatureExclusion": boolean,
"xPathQuery": "string"
}

buffer

XML file to sign

Response

byte array of signed files

SIGN: signPKCS1

Description

permits to apply the raw signature (PKCS1)

HttpMethod

POST

Path

/rest/sign/signPKCS1

Request

credentials

Expand

title	request-signPkcs1-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"

}

signPreferences

Expand

title	request-signPKCS1-signPreferences

{
"hashAlgorithm": "enum"
}

buffer

hash to sign

Response

byte array associated to hash signed

Verify

VERIFY: signatures

Description

permits to verify the signatures

HttpMethod

POST

Path

/rest/verify/signatures

Request

signedContent

file to verify

preferences

Expand

title	request-verify-signatures

{
"detachedContent": "string",
"language": "COUNTRY_CODE_2_DIGIT" (es: IT),
"pdfEncryptionPassword": "string",
"recursive": true,
"verifyOnDate": "YYYY-mm-dd" (for example: 2022-10-24)
}

Response

Report with verify, this is a complex object: "SignedDocumentReportBean"

Verify timestamp

With SWS is possible to verify TSD and TSR using the preferences, below will be described the REST request.

VERIFY: tsr or tsd

Description

permits to verify the timestamps in tsd or tsr format

HttpMethod

POST

Path

/rest/verify/timestamps

Request

timestampedContent

file with timestamp

detachedContent

file original, where timestamp has ben applied (use this field only if you are verifying TSR)

preferences

Expand

title	request-verify-timestamps-preferences

{
"responseWithoutContent": boolean,
"language": "COUNTRY_CODE_2_DIGIT" (es: IT)
}

Response

Return a complex object "TimestampReportBeanSummary"

VERIFY: tsd

Description

permits to verify the timestamps

HttpMethod

POST

Path

/rest/verify/timestamps/tsd

Request

tsd

timestamp to verify

preferences

Expand

title	request-verify-timestamps-preferences

{
"responseWithoutContent": boolean,
"language": "COUNTRY_CODE_2_DIGIT" (es: IT)
}

Response

Return a list of complex objects: "TimestampReportBean"

VERIFY: tsr

Description

permits to verify the timestamps

HttpMethod

POST

Path

/rest/verify/timestamps/tsr

Request

tsr

timestamp to verify

content

file original, where timestamp has ben applied

preferences

Expand

title	request-verify-timestamps-preferences

|

{
"responseWithoutContent": boolean,
"language": "COUNTRY_CODE_2_DIGIT" (es: IT)
}

Response

Return a complex object "TimestampReportBean"

...

Version	Old Version 70	New Version 71
Changes made by	Lorenzo Cardinali	Lorenzo Cardinali
Saved on	May 15, 2023	Jun 12, 2023

Content Comparison

Versions Compared

Key

Introduction

Convention (manage the response)

Enquiry

ENQUIRY: certificate

Introduction

Convention (manage the response)

Enquiry

ENQUIRY: certificate

ENQUIRY: signatures

ENQUIRY: signatures-available

ENQUIRY: otps

ENQUIRY: timestamps-available

ENQUIRY:

errors

ENQUIRY: signatures-available

Admin

ADMIN: remove-certificate-from-cache

Timestamps

TIMESTAMPS: apply

ENQUIRY: timestamps-available

User

USER: change-password

ADMIN: remove-certificate-from-cache

ENQUIRY: errors

Admin

Sign

SIGN: openSession

Timestamps

SIGN: getRemainingTimeForSession

User

SIGN: closeSession

SIGN: sendOtpBySMS

SIGN:

signCades

SIGN: getRemainingTimeForSession

SIGN: sendOtpBySMS

SIGN: signCades

SIGN: closeSession

SIGN: signCades (detached output p7s)

SIGN: signPades

SIGN: signXades

SIGN: signPKCS1

Verify

VERIFY: signatures

Verify timestamp

VERIFY: tsr or tsd

VERIFY: tsd

VERIFY: tsr