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

Dokumenta kopsavilkuma pievienošana

Scope

Purpose of the "Add document digest" operation is to avoid file transfering (if there is extra security requirements) out of internal network.

Operation add signable file digest (HASH) and filename to the file processing session.

Only possible for signing ASICE (EDOC) document types.

Description

1. The file digest and file name is attached to the file processing session;
2. The file description information is returned.

Request

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

POST /api-storage/v1.0/{sessionId}/addDocumentDigest 
PropertyTypeUsageDescription
sessionId
String (64)MandatoryFile processing session identifier

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
}



Body

{
    "files": [
            {
                "name": {String},
                "digest": {String},
				"digest_algorithm": {String}
            }
        ],
    "signatureIndex": {String}
}

PropertyTypeUsageDescription
files
Array
MandatoryFile digest and name array
files.name
String
MandatoryThe name of the file (with extension) from which the diggest was calculated
files.digest
String
MandatoryCalculated file digest in Base64 encoding. (warning) See note below.
files.digest_algorithm
String
MandatoryUsed HASH Algorithm (Only SHA256 is supported)
signatureIndex
String
Optional

Signature sequence index, starting with "0", which means the first signature (XAdES signature file name signatures0.xml)

If Property is not used, signature index will be "0".

(warning) If there is planed that file will be signed by more than one signer, this parameter shall be used by increasing by 1 for each next signature. ASICE container can't contain more then one signature with same file name.

Otherwise, service provider shall rename signature file before adding it to ASICE container.

File diggest calculation

(warning) Only SHA256 at this moment is supported.

(lightbulb) Fist calculate SHA256 HASH from the file you need to sign. Then take SHA256 HASH and make HEX to Base64 encoding. For example encoding you can use https://base64.guru/converter/encode/hex

Guidelines for using file digest till ASICE finalizing.

 Click here to expand...

Guidelines for using file digest till ASICE finalizing.

Digest preparation and signing

  1. Hash from files to be signed shall be calculated at service provider premises.
  2. Digest shall be encoded from calculated hash (HEX to Base64).
  3. Service provider shall receive authorisation token (Introspect scope) for accessing SignAPI
  4. Request "Add document digest" operation  (POST /api-storage/v1.0/{sessionId}/addDocumentDigest)
  5. Request "Calculate Digest" operation (POST /api-sign/v1.0/calculateDigest)
  6. Request "Finalize Signing" operation (POST /api-sign/v1.0/finalizeSigning)
  7. Request "File list" operation (GET /api-session/v1.0/{sessionId}/list) - get ASICE container "documentId" property
  8. Request "File download" operation (GET /api-session/v1.0/{sessionId}/{documentId}) - download signed ASICE container.
  9. Open container with zip processing tools (probably need to rename extension to ".zip").
  10. Add file, from which digest was calculated to container's root folder.
  11. When file is added - change extension back to ".edoc" or ".asice" if needed.

Adding additional signature to existing ASICE container

(in case when file digest is signed by more than one signer)

  1. If you have already signed ASICE with at least one signature, and you don't have stored signed file/s digest:
  2. Unpack ASICE container - extract file/s to be signed;
  3. Follow steps 1 to 9 from "Digest preparation and signing";
  4. Go to "META-INF" folder and extract signature XML file (Shall contain "signatures" name within file name (signatures1.xml));
  5. Open existing ASICE (where you want to add signature);
  6. Open "META-INF" folder:
  7. Check, if folder did not contain signature file with same filename as extracted in step 4:
    1. if contains, rename index of signature XML file extracted in step 4
  8. Add signature XML file to the "META-INF" folder
  9. When signature XML file is added - change extension back to ".edoc" or ".asice" if needed.





Superted HASH'es

Only SHA256 HASH is supported

ASICE and EDOC

EDOC container is Equal to ASIC container just uses ".edoc" extension.

".edoc" is popular extension (legacy) in Latvia, but ".asice" extensions are used as well and are supported.

".asice" extension is EU recognized (in countries where ASICE containers are in use).

ASICE container contains XAdES (XML Advanced electronic signature).






Signature XML files

ASICE container contains "META-INF" folder

Each signature creates a single XML file

Signature XML files Shall contain name "signatures" + index (in case of API "signatures0.xml or signatures1.xml")

All signature names shall be uniqe

(lightbulb) To avoid same names, use "signatureIndex" property in "Add Document Digest" operation

Example with one file digest and name

POST /api-storage/v1.0/77740b301f0880ef498cb1e474e8060b3e538cfeea8ebf508c2bad4b72b56a87/addDocumentDigest HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv
{
    "files": [
            {
                "name": "10-10.pdf",
                "digest": "u69UTpGwlSfNpIMYhXPIa612ELFu+Y8zWaVCApzlQdE=",
				"digest_algorithm": "SHA256"
            }
        ],
    "signatureIndex": "0"
}


Example with multiple file digest and name

POST /api-storage/v1.0/77740b301f0880ef498cb1e474e8060b3e538cfeea8ebf508c2bad4b72b56a87/addDocumentDigest HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv
{
    "files": [
            {
                "name": "10-10.pdf",
                "digest": "u69UTpGwlSfNpIMYhXPIa612ELFu+Y8zWaVCApzlQdE=",
				"digest_algorithm": "SHA256"
            },
            {
                "name": "10-11.docx",
                "digest": "u69UTpGwlSfNpIMYhXPIa612ELFu+Y8zWaVCApzlQdB=",
				"digest_algorithm": "SHA256"
            },
            {
                "name": "10-12.pdf",
                "digest": "u69UTpGwlSfNpIMYhXPIa612ELFu+Y8zWaVCApzlQdC=",
				"digest_algorithm": "SHA256"
            }
        ],
    "signatureIndex": "0"
}

Response

JSON object:

{
    "data": [
        {
            "id": {String},
            "name": {String},
            "size": {Number},
			"type": {String}
        }
    ]
}
PropertyTypeDescription
data
Object
Data Object
data.id
String
File Identifier (documentId)
data.name
String
File name
data.size
Integer
File size in bytes (always will be "0" since filename and digest was added)
data.type
String

Processed file type:

"hash" - In case if file digest and file name is added to session

Example if one file digest and name

{
    "data": [
        {
            "id": "6921c9e8afd22a9a391d5318e08da85d",
            "name": "10-10.pdf",
            "size": 0,
			"type": "hash"
        }
    ]
}

Example if multiple file digest and name is added

{
    "data": [
        {
            "id": "6921c9e8afd22a9a391d5318e08da85d",
            "name": "10-10.pdf",
            "size": 0,
			"type": "hash"
        },
        {
            "id": "9f1702526028570f5f6c2813417797a0",
            "name": "10-11.docx",
            "size": 0,
			"type": "hash"
        },
        {
            "id": "5d05429bc930622ee008ed4ded1b2de1",
            "name": "10-12.pdf",
            "size": 0,
			"type": "hash"
        }
    ]
}
  • No labels