Page tree
Skip to end of metadata
Go to start of metadata

Validācijas API

Scope

To receive validation data of signed document.

Descriprion

1. Validation information is returned for the specified file;
2. If the file is not signed, an error message is returned;

Request

The Service provider's application sends the following GET request using TLS:

GET /api-validation/v1.0/{sessionId}/{documentId}/validate
Property
Type
Usage
Description
sessionId
String (64)MandatoryFile processing session identifier
documentId
String (64)MandatoryDocument identifier, received from "upload" or "list" operation as "id" property

Authorization

The request must contain an Authorization header with an OAuth Introspect access token obtained via Integration Platform a Service provider's credentials grant flow.

 Sign API authorization - Obtain a Introspect access token

Introspect piekļuves talona (token) saņemšana

Description

This operation obtains an OAuth 2.0 access token. This operation can be invoked as part of an OAuth 2.0 Service provider's credentials grant flow.

Introspect access token

When the Service provider's credentials grant flow is used, the obtained access token demonstrates the administrative authorization of the Service provider's application making the call for accessing certain resources or services (i.e., without direct intervention of the resource's owner), or for accessing resources of the Service provider's application. Token is issued when the authorization server that processes the request is not associated to an identity provider. A token of this type can be used for accessing resources not associated to end-users or to end-user resources of any domain.

This type of access token is used to get access to Signature creation and validation service API's

Request

To obtain the token, the Service provider's application must send a request like the following to authorization server using TLS. This request is sent directly from the Service provider’s application to authorization server and does not go via the browser.

POST /trustedx-authserver/oauth/{as}/token

Parameter

Title

Type

Field

Description

as

path

mandatory

Use "lvrtc-eipsign-as"

Host:

Test environment: eidas-demo.eparaksts.lv

Production: eidas.eparaksts.lv

Content-Type Header

Content-Type: application/x-www-form-urlencoded; charset=UTF-8


In HTTP POST request is necessary to incorporated the following main attribute: Authorization – API access token.

Authorization: Basic <API-Key>

How to generate API Access Key

 API Access Key basics...

Before Service provider access Integration platform API, LVRTC shall register Service provider as customer of Integration platform. After signing a contract with LVRTC (Test of Production environment) LVRTC generates Service Provider’s application identifier – (client_id) and shared secret (client_secret), intended for the customer usage.
API Access Key (API Key) is generated from the Service provider’s application identifier (client_id), a secret shared with the platform (client_secret)  on the following basis:

Service provider's application identifier client_id are converted using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "Portāls" conversion result is "port%C4%81ls".

Service provider's application password client_secret is converted by using the UTF-8 character encoding and URL encoding conditions.

(warning)  For example, value "drošība" conversion result is "dro%C5%A1%C4%ABba".

Both values of the previous two steps must be combined with separator colon “:” between them.

(warning)  For example, by using previous examples, the result will be "port%C4%81ls:dro%C5%A1%C4%ABba".

Obtained value must be converted using base 64 encoding without line breaks.

(warning)  For example, values "port%C4%81ls:dro%C5%A1%C4%ABba" conversion result is "CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh".

"MIME Tools" tool in "Notepad + +" can be used for this purpose.

API-Key = base64[url_encode(utf8(<client_id>)) ':' url_encode(utf8(<client_secret>))]

Body

The content of the request for Introspect access token (used for access SignAPI service):

Property

Usage

Description

grant_type

mandatory

Must have the client_credentials value .

scopemandatoryMust have the urn:safelayer:eidas:oauth:token:introspect value

Example (Introspect access token)

The following example shows a situation in which the Service provider’s application with the identifier "Portal" and the password "drošība" authority shall transmit the request to the server with the identifier "lvrtc-eips-as":

POST /trustedx-authserver/oauth/lvrtc-eipsign-as/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic CG94ydCVDNCUMWxzOmRybyVDNSVBMSVDNCVBQmJh
Host: eidas-demo.eparaksts.lv
grant_type=client_credentials&
			scope=urn%3Asafelayer%3Aeidas%3Aoauth%3Atoken%3Aintrospect

Response

In response, Integration platform authorization server issues a bearer-type OAuth 2.0 access token and returns it in a JSON structure.

{
"access_token" : {string}, 
"token_type" : "Bearer", 
"expires_in" : {number}
}

Parameter

PropertyDescription
access_token
Access token generated by Authorization server. The token has the characteristics specified in the configuration of the authorization server that processed the request and consists of a random string of the number of bytes specified in the Access token number of random bytes (by default, 32), encoded in hexadecimal.
token_type
Type of access token. Always has the "bearer" value. (Bearer type OAuth 2.0 access token).
expires_in
Lifetime (in seconds) of the access token. The Service provider’s application must perform the access the token authorizes before the token expires. This value can be configured in the Token timeout option of the authorization server (by default, 120 seconds). Once this timeout has expired, the token becomes invalid, and the Service provider’s application must obtain another one if it wants to continue invoking the protected services.

Example

Introspect access token:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8 
Cache-Control: no-store, no-cache, must-revalidate 
Pragma: no-cache
{
 "scope": "urn:safelayer:eidas:oauth:token:introspect",
 "access_token": "dfffb0d7f90bed142464750cacad5e4b9e23f58ecb1d77e3bdf706ba208ad16a",
 "token_type": "Bearer",
 "expires_in": 600
}



Example

GET /api-validation/v1.0/965af52843d969ab6011c6ba8effbdc307e26517280566ce18a807f37a9029aa/c97823faa1a54658e75207e1a791da2c/validate HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

General structure of validation response (JSON object):

{
    "data": {
        "includedFiles": [
            {
                "filename": {String}
            }
        ],
        "signatureForm": {String},
        "signaturesExt": [
            {
                "id": {String},
                "info": {
                    "bestSignatureTime": {Datetime}
                },
                "errors": [
                    {
                        "content": {String}
                    }
                ],
                "signedBy": {String},
                "warnings": [
                    {
                        "content": {String}
                    }
                ],
                "indication": {String},
                "signatureLevel": {String},
                "signatureFormat": {String},
                "signerSerialNumber": {String}
            }
        ],
        "validationTime": {Datetime},
        "signaturesCount": {Number},
        "validationLevel": {String},
        "validatedDocument": {
            "filename": {String}
        },
        "validSignaturesCount": {Number}
    }
}

Property
Description
includedFiles
ArrayInformation about files included in the ASIC container.
includedFiles.filename
StringName of the faile included in the ASIC container.
signatureForm
StringFormat (and optionally version) of the digitally signed document container.
signaturesExt
ArrayCollection of signatures found in digitally signed document
signaturesExt.id
StringSignature ID attribute
signaturesExt.info
ObjectObject containing trusted signing time information.
signaturesExt.info.bestSignatureTime
Date

Time value that is regarded as trusted signing time, denoting the earliest time when it can be trusted by the validation application (because proven by some Proof-of-Existence present in the signature) that a signature has existed.

The source of the value depends on the signature profile (see also SignatureFormat parameter):

- Signature with time-mark (LT_TM level) - the producedAt value of the earliest valid time-mark (OCSP confirmation of the signer's certificate) in the signature.

- Signature with time-stamp (LT or LTA level) - the genTime value of the earliest valid signature time-stamp token in the signature.

- Signature with BES or EPES level - the value is empty, i.e. there is no trusted signing time value available.

signaturesExt.signedBy
StringSignature/Seal Creator. CN (common name) value portion in signer's certificate's subject distinguished name
signaturesExt.errors
ArrayInformation about validation error(s), array of error messages.
signaturesExt.warnings
ArrayBlock of validation warnings that do not affect the overall validation result.
signaturesExt.indication
String

Overall result of the signature's validation process, according to ETSI EN 319 102-1 "Table 5: Status indications of the signature validation process".

Note that the validation results of different signatures in one signed document (signature container) may vary.

Possible values:

TOTAL-PASSED

TOTAL-FAILED

INDETERMINATE

signaturesExt.subindicationStringAdditional subindication in case of failed or indeterminate validation result, according to ETSI EN 319 102-1 "Table 6: Validation Report Structure and Semantics"
signaturesExt.signatureLevel
String

Legal level of the signature, according to Regulation (EU) No 910/2014.

- Possible values on positive validation result:

QESIG

QESEAL

QES

QES_EDL - "ADES_QC" signature, which according to Latvian Electronic Documents Law is equivalent to a handwritten signature

ADESIG_QC

ADESEAL_QC

ADES_QC

ADESIG

ADESEAL

ADES

- Possible values on indeterminate validation result:

prefix INDETERMINATE is added to the level described in positive result. For example INDETERMINATE_QESIG

- Possible values on negative validation result:

In addition to abovementioned

NOT_ADES_QC_QSCD

NOT_ADES_QC

NOT_ADES

NA

signaturesExt.signatureFormat
String

Format and profile (according to Baseline Profile) of the signature. See XAdES Baseline Profile, CAdES Baseline Profile and PAdES Baseline Profile for detailed description of the Baseline Profile levels.

Possible values:

XAdES_BASELINE_B

XAdES_BASELINE_B_BES

XAdES_BASELINE_B_EPES

XAdES_BASELINE_T

XAdES_BASELINE_LT - long-term level XAdES signature where time-stamp is used as a assertion of trusted signing time

XAdES_BASELINE_LT_TM - long-term level XAdES signature where time-mark is used as a assertion of trusted signing time.

XAdES_BASELINE_LTA

CAdES_BASELINE_B

CAdES_BASELINE_T

CAdES_BASELINE_LT

CAdES_BASELINE_LTA

PAdES_BASELINE_B

PAdES_BASELINE_T

PAdES_BASELINE_LT

PAdES_BASELINE_LTA

signaturesExt.signerSerialNumber
StringSERIALNUMBER value portion in signer's (natural person) certificate's subject distinguished name.
signaturesExt.registrationNumber
StringOID 2.5.4.97 (organizationIdentifier) value portion in signer's (legal person) certificate's subject distinguished name. 
validationTime
DateTime of validating the signature by the service.
signaturesCount
NumberNumber of signatures found inside digitally signed file.
validSignaturesCount
NumberSignatures count that have validated to TOTAL-PASSED. See also SignatureExt.Indication field.
validationLevel
String

Validation process against what the document is validated, only applicable on DSS based validations.

Possible values:

ARCHIVAL_DATA

validatedDocument
ObjectObject containing information about validated document.
validatedDocument. filename
StringDigitally signed document's file name.

Example

{
    "data": {
        "signatureForm": "ASiC-E",
        "signaturesExt": [
            {
                "id": "S1",
                "info": {
                    "bestSignatureTime": "11.11.2019. 08:32:04"
                },
                "signedBy": "ANDRIS PARAUDZIŅŠ",
                "warnings": [
                    {
                        "content": "Signature warnings here"
                    }
                ],
                "indication": "TOTAL-PASSED",
				"subindication": "subindication details here"
                "signatureLevel": "QESIG",
                "signatureFormat": "XAdES_BASELINE_LT",
                "signerSerialNumber": "PNOLV-324954-21338"
            }
        ],
        "validationTime": "30.12.2019. 06:39",
        "signaturesCount": 1,
        "validationLevel": "ARCHIVAL_DATA",
        "validatedDocument": {
            "filename": "test.edoc"
        },
        "validSignaturesCount": 1
    }
}

  • No labels