Versions Compared

Version Old Version 19 New Version 20
Changes made by

Lorenzo Cardinali

Lorenzo Cardinali

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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


Descriptionreturn the certifcate associated to "device_signer"
HttpMethodPOST
Path
/rest/enquiry/certificate
Request


Expand
titlerequest-enquiry-certificate
{
  "credentials": {
    "username": "device_signer"
  }
}


Responsereturn the byte array of certificate associated to device_signer


ENQUIRY: signatures


Descriptionreturn the numer of signatures apposed from "device_signer"
HttpMethodPOST
Path
/rest/enquiry/signatures
Request


Expand
titlerequest-enquiry-signatures
{
  "credentials": {
    "username": "device_signer"
  }
}


ResponseNumber of signatures apposed



ENQUIRY: signatures-available


Descriptionreturn the number of signatures which "device_signer" can apply
HttpMethodPOST
Path
/rest/enquiry/certificatesignatures-available
Request


Expand
titlerequest-enquiry-certificatesignatures-available
{
  "credentials": {
    "username": "device_signer"
  }
}


Responsereturn the byte array of certificate associated to device_signerNumber of signatures available



ENQUIRY:

signatures

otps


Descriptionreturn the numer of signatures apposed from otp list associated to "device_signer"
HttpMethodPOST
Path
/rest/enquiry/signaturesotps
RequestDescriptionreturn the number of signatures which


Expand
titlerequest-enquiry-signaturesotps
{
  "credentials": {
    "username": "device_signer"
  }
}
ResponseNumber of signatures apposed

ENQUIRY: signatures-available

Descriptionreturn the otp list associated to "device_signer"

    "username": "device_signer"
can apply
HttpMethodPOST
Path
/rest/enquiry/signatures-available
Request
Expand
titlerequest-enquiry-signatures-available
{
  "credentials": {
    "username": "device_signer"
  }
}
ResponseNumber of signatures available

ENQUIRY: otps


  }
}


Response


Expand
titleresponse-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)
HttpMethodPOST
Path
/rest/enquiry/otpstimestamps-available
Request


Expand
titlerequest-enquiry-otps
{
  "credentials": {
    "username": "device_signer"
  }
}
Response
[
    {
        "idOtp": number,
        "serialNumber": "string",
        "type
Expand
titleresponse-enquiry-otps
timestamps-available

{
  "timestampUrl": "otptimestamp-namirial-typeenquiry-enumurl"
    },
   {
        "idOtp": number,
        "serialNumber  "timestampUsername": "stringtsa-username",
          "typetimestampPassword": "otptsa-type-enumpassword"
    }
]


ResponseNumber of timestamps available


ENQUIRY:

timestamps-available

errors


Request
Descriptionreturn the numeber of timestamp available (valid only for Namirial TSA account)error description associated to error code
HttpMethodPOST
Path
/rest/enquiry/timestamps-available
errors
Request


Expand
titlerequest-enquiry-errors

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


Response


{
  "timestampUrl
Expand
titlerequestresponse-enquiry-timestamps-available
errors

[
    {
        "errorCode": integer,
        "errorLanguage": "timestampCONUNTRY-namirialCODE-enquiry-url2DIGIT",
          "timestampUsernameerrorLanguage2": "tsaCOUNTRY-CODE-username3DIGIT",
          "timestampPassworderrorText": "tsa-passwordDescription error in language"
    }

ResponseNumber of timestamps available
ENQUIRY: errors

]



Admin

ADMIN: remove-certificate-from-cache


Descriptionreturn the error description associated to error coderemove the certificate from cache of SWS
HttpMethodPOSTPUT
Path
/rest/enquiry/errors
Request
Expand
titlerequest-enquiry-errors

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

Response
admin/remove-certificate-from-cache
Request


[
    {
        "errorCode
Expand
titleresponserequest-enquiry-errors
-remove-certificate-from-cache

{
  "error_code": integer,
          "errorLanguagelang": "CONUNTRYCOUNTRY-CODE-2DIGIT",
        "errorLanguage2": "COUNTRY-CODE-3DIGIT",
        "errorText": "Description error in language"
    }]


Response


Admin

Timestamps

ADMIN: remove-certificate-from-cache

Descriptionremove the certificate from cache of SWS

TIMESTAMPS: apply

Descriptionpermits to apply timestamp on specified file
HttpMethodPUTPOST
Path
/rest/admin/remove-certificate-from-cache
Request
Expand
titlerequest-enquiry-remove-certificate-from-cache

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

Response

Timestamps

TIMESTAMPS: apply

permits to apply timestamp on specified file
Description
timestamps/apply
Request
timeStampPreferences


Expand
titlerequest-timestamps-apply

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


contentfile to apply timestamp


Response


User

USER: change-password

Descriptionpermits to change the password associated to device signer
HttpMethodPOST
Path
/rest/timestampsuser/applychange-password

USER: change-password

Descriptionpermits to change the password associated to device signer
HttpMethodPOST
Path
/rest/user/change-password
Request timeStampPreferences(for remote device signer)
Request (for remote


Expand
titlerequest-user-change-timestamps-apply

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

contentfile to apply timestamp
Response

User

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
titlerequest-user-change-password-remoteautomatic

{
  "credentials": {
        "idOtpsecurityCode": idOtp or -1,
    "otp": "otpCode"securityCode associate to automatic device signer",
    "password": "old-password-of-device-signer-remoteautomatic",
    "username": "device-signer-remoteautomatic"
  },
  "newPassword": "new-password-of-device-signer-remote"
}

Request (for automatic device signer)

automatic"
}


ResponsePassword update succesfully


Sign

SIGN: openSession


Descriptionpermits to open the sessione for apply multiple sign with remote device
HttpMethodPOST
Path
/rest/sign/openSession
Request


Expand
titlerequest-user-change-password-automaticsign-openSession

{
  "credentials": {
        "securityCodeidOtp": "securityCode associate to automatic device signer" -1,
    "passwordotp": "old-password-of-device-signer-automatic775351",
    "usernamepassword": "device-signer-automatic"
  }12345678",
      "newPasswordusername": "new-password-of-device-signer-automatic"RHIP22021116852552"
  }
}


ResponsePassword update succesfully
Sign
String with the session


SIGN:

openSession

getRemainingTimeForSession


Descriptionpermits to open the sessione for apply multiple sign with remote deviceobtain the time until the session is valid
HttpMethodPOST
Path
/rest/sign/openSessiongetRemainingTimeForSession
Request


{
  "credentials": {
    "idOtp": -1,
    "otp": "775351",
    "password": "12345678
Expand
titlerequest-sign-openSession
getRemainingTimeForSession

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


ResponseString with Seconds until the session is valid


SIGN:

getRemainingTimeForSession

closeSession


Descriptionpermits to obtain the time until destroy the session is validbefore will expire
HttpMethodPOST
Path
/rest/sign/getRemainingTimeForSessioncloseSession
Request


Expand
titlerequest-sign-getRemainingTimeForSession

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


ResponseSeconds until the session is valid