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

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-timestamps-certificateavailable

{
"

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

Description

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

HttpMethod

POST

Path

/rest/enquiry/signatureserrors

Description

return the number of signatures which "device_signer" can apply

HttpMethod

POST

Path

/rest/enquiry/signatures-available

Request

Expand

title	request-enquiry-signatureserrors

{
"

credentials

error_code":

{

integer,

"

username

lang": "

device_signer"
}
}

Response

Number of signatures apposed

ENQUIRY: signatures-available

POST

COUNTRY-CODE-2DIGIT"
}

Response

Description

return the otp list associated to "device_signer"

HttpMethod

Expand

title	requestresponse-enquiry-signatures-available

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

Response

Number of signatures available

ENQUIRY: otps

errors

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

Admin

ADMIN: remove-certificate-from-cache

HttpMethod	PUT
Description	remove the certificate from cache of SWS
Path	/rest/enquiry/otps	Request

Expand

title	request-enquiry-otps

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

Response

admin/remove-certificate-from-cache

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

Expand

title	responserequest-enquiry-otps

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

ENQUIRY: timestamps-available

remove-certificate-from-cache

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

Response

Timestamps

TIMESTAMPS: apply

Description

permits to apply timestamp on specified file

HttpMethod

POST

Path

/rest/enquirytimestamps/timestamps-availableapply

Request

timeStampPreferences

Description

return the error description associated to error code

Expand

title	request-enquiry-timestamps-available

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

Response

Number of timestamps available

ENQUIRY: errors

timestamps-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/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

ADMIN: remove-certificate-from-cache

TIMESTAMPS: apply

Request

Description

remove the certificate from cache of SWS

HttpMethod

PUT

Path

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

user/change-password

Request (for remote device signer)

Expand

title	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-enquiryuser-removechange-certificatepassword-from-cacheautomatic

{
  "error_code": integercredentials": {
"securityCode": "securityCode associate to automatic device signer",
    "password": "old-password-of-device-signer-automatic",
    "username": "device-signer-automatic"
  },
  "langnewPassword": "COUNTRY-CODE-2DIGITnew-password-of-device-signer-automatic"
}

Response

Timestamps

Password update succesfully

Sign

SIGN: openSession

HttpMethod	POST
Description	permits to apply timestamp on specified fileopen the sessione for apply multiple sign with remote device
Path	/rest/timestampssign/applyopenSession
RequesttimeStampPreferences

USER: change-password

Description

permits to change the password associated to device signer

Expand

title	request-timestampssign-apply

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

content

file to apply timestamp

Response

User

openSession

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

Response

String with the session

SIGN: getRemainingTimeForSession

Description

permits to obtain the time until the session is valid

HttpMethod

POST

Path

/rest/usersign/change-passwordgetRemainingTimeForSession

Request (for remote device signer)

Expand

title	request-user-change-password-remotesign-getRemainingTimeForSession

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

Seconds until the session is valid

SIGN: closeSession

HttpMethod	POST
Description	permits to destroy the session before will expire
Path	/rest/sign/closeSession
Request

SIGN: openSession

Description

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

Expand

title	request-user-change-password-automaticsign-closeSession

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

Response

Password update succesfully

Sign

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

Response

SIGN: sendOtpBySMS

Description

permits to destroy the session before will expire

HttpMethod

POST

Path

/rest/sign/openSessionsendOtpBySMS

Request

Expand

title	request-sign-openSessioncloseSession

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

ResponseString with the session

SIGN:

getRemainingTimeForSession

signCades

Description

permits to obtain the time until the session is validapply the cades signature

HttpMethod

POST

Path

/rest/sign/getRemainingTimeForSessionsignCades

RequestRequest

credentials

Expand

title	request-signsignCades-getRemainingTimeForSessioncredentials

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

Description

permits to destroy the session before will expire

HttpMethod

POST

Path

/rest/sign/closeSession

Request

"username":"device signer name",

"password":"string",

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

"otp":"otp code",

"sessionKey":"string with sessionKey"

}

content

file to apply cades

Response

Expand

title	request-signCades-

sign-closeSession

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

Response

credentials-automatic

{

"username":"device signer name",

"password":"string",

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

"otp":"otp code",

"sessionKey":"string with sessionKey"

}

Version	Old Version 22	New Version 23
Changes made by	Lorenzo Cardinali	Lorenzo Cardinali
Saved on	Aug 30, 2022	Aug 30, 2022

Content Comparison

Versions Compared

Key

Introduction

Enquiry

ENQUIRY: certificate

Introduction

Enquiry

ENQUIRY: certificate

ENQUIRY: signatures

ENQUIRY: signatures-available

ENQUIRY: otps

ENQUIRY: timestamps-available

ENQUIRY:

errors

ENQUIRY: signatures-available

ENQUIRY: otps

Admin

ADMIN: remove-certificate-from-cache

ENQUIRY: timestamps-available

Timestamps

TIMESTAMPS: apply

ENQUIRY: errors

User

USER: change-password

Admin

ADMIN: remove-certificate-from-cache

Timestamps

Sign

SIGN: openSession

USER: change-password

User

SIGN: getRemainingTimeForSession

SIGN: closeSession

SIGN: openSession

Sign

SIGN: sendOtpBySMS

SIGN:

signCades

SIGN: closeSession