Working with digital signatures

🌐 This document is available in both English and Ukrainian. Use the language toggle in the top right corner to switch between versions.

1. Main scenarios

1.1. Validating digital signatures applied by an officer

Signature validation sequence diagram:

The validation chain is implemented in the following classes:

The service performs the following checks of the officer’s signature:

EDS is valid.
EDS contains a time stamp.
The time difference between the moment of putting the signature and the current time does not exceed the value specified in the timeout-ms parameter, by default it is 2 minutes (120,000 ms).
The data integrity is not compromised (the hash value from the signature corresponds to the hash calculated by the service based on the received data).
The document was signed using a key that belongs to the authenticated user using it. The user data from the EDS corresponds to the data in the JWT access token and contains the full name, RNOKPP, EDRPOU.

Request:

POST /api/esignature/officer/verify --header 'X-Access-Token: token'

Request body:

{
    "signature": "string",
    "data": "string"
}

Responses:

200 OK: Signature is valid

Response body:

{
    "isValid": true,
    "error": null
}

200 OK: Signature validation error

Response body:

{
    "isValid": false,
    "error": {
        "code": "ERROR_EMPTY_EDRPOU",
        "message": "Signature does not contain EDRPOU",
        "localizedMessage": "Підпис не містить ЄДРПОУ код"
    }
}

400 Bad request: Invalid request

Response body:

{
    "code": "string",
    "message": "string",
    "localizedMessage": "string"
}

1.2. Validation of the digital signature added by a citizen

Signature validation sequence diagram:

The validation check chain is implemented in the following classes:

The service performs the following checks of the citizen’s signature:

EDS is valid.
EDS contains a time stamp.
EDS belongs to an individual, contains Full name and RNOKPP and does not contain EDRPOU.
JWT token belongs to an individual, contains name and RNOKPP and does not contain USREOU.
The time difference between the moment of putting the signature and the current time does not exceed the value specified in the timeout-ms parameter, by default it is 2 minutes (120,000 ms).
The data integrity is not compromised (the hash value from the signature corresponds to the hash calculated by the service based on the received data).
The document was signed using a key that belongs to the authenticated user using it. The user data from the EDS corresponds to the data in the JWT access token.

Request:

POST /api/esignature/citizen/verify --header 'X-Access-Token: token'

Request body:

{
  "allowedSubjects": ["CITIZEN"],
  "signature": "string",
  "data": "string"
}

allowedSubjects: The package of validation rules for signature verification, may contain [CITIZEN, ENTREPRENEUR, LEGAL]. In the case of using several rules, the signature is valid if it passes at least one of the checks. In case of failed checks for any of the packages, the first found error is returned. Verification for ENTREPRENEUR and LEGAL takes place using the same validator as for the officer.

Responses:

200 OK: Signature is valid

Response body:

{
    "isValid": true,
    "error": null
}

200 OK: Signature validation error

Response body:

{
    "isValid": false,
    "error": {
        "code": "ERROR_SIGNATURE_NAME_MISMATCH",
        "message": "Signature and current user full name mismatch",
        "localizedMessage": "The full name in the signature differs from the full name of the user"
    }
}

400 Bad request: Invalid request

Response body:

{
    "code": "string",
    "message": "string",
    "localizedMessage": "string"
}

1.3. Getting the signature owner information

Getting the information about who out the signature is done by checking the validity of the signature, taking into account the allowed time interval specified in the sign.auth.timeout-ms parameter, by default 1 minute (60,000 ms). Request:

POST /api/esignature/owner --header 'X-Access-Token: token'

Request body:

{
  "signature": "string",
  "data": "string"
}

Responses:

200 OK: Signature validated and signatory data received

Response body:

{
  "fullName": "string",
  "drfo": "string",
  "edrpou": "string"
}