You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 14 Next »

Signature creation and validation service API's

Signature creation and validation service (SignAPI) hosts:

EnvironmentHost <SignAPI_base_url>
Testsignapi.prep.eparaksts.lv
LiveTBD (signapi.eparaksts.lv)

Signature creation and validation service API's overview

Session API

Description

Signature creation and validation service API's (SignAPI) work is based on sessions.

Received session identifier shall be used in all future requests as reference to a specific set of files.

signAPI provides session storage on a perpetual basis and is used as an identifier for a particular file or set of files.

Service provifers only need to retrieve the session identifier once and Service provider shall save session identifier with the parameters of a related particular file or set of files. 

Session API URL

/api-session/v1.0/
MethodEndpointDescription
GETstartData processing session creation
GET{sessionId}/closeClosing data processing session

Storage API

/api-storage/v1.0/
MethodEndpointDescription
PUT{sessionId}/uploadUpload file
GET{sessionId}/listRetrieve file list in specific session
GET{sessionId}/{documentiId}Download file
DELETE{sessionId}/{documentiId}Delete file

Signing API

/api-signing/v1.0/
MethodEndpointDescription
POSTcalculateDigest/{sessionId}Signable data calculation
POSTputSignature/{sessionId}Signature adding and LVRTC issued Time stamp request
POSTfinalizeSignature/{sessionId}Signed document finalization
POSTfinalizeSignatureMob/{sessionId}Signed document finalization using eParaksts mobile related signature
POSTeSeal/{sessionId}Electronic stamp creation (internal use only)
POSTarchive/{sessionId}Archive timestamp requesting.

Validation API

/api-validation/v1.0/
MethodEndpointDescription
GET{sessionId}/{documentiId}/validateValidation of signed file

Configuration API

/api-config/v1.0/
MethodEndpointDescription
GET Retrieve Service provider's configuration (Service provider can receive only hes configuration)

 

Session API

Session - Create

Scope

Ensure that a file processing session is created, which is then used to refer to the processes it takes.

Description

SignAPI creates a session folder that uses the session ID as folder name

Request

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

GET /api-session/v1.0/start

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.

Unable to render {include} The included page could not be found.

Example

GET /api-session/v1.0/start HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

JSON object:

{
    "data": {
        "sessionId": {string}
    }
}
PropertyTypeDescription
sessionIdString (64)

File processing session identifier.

Example

{
    "data": {
        "sessionId": "5a1ef5321d1bd9a2966d673c84c7ded630a1923965e3efcfc1787260cbe8223d"
    }
}




Session - Close

Scope

Delete file processing session and related documents from memory.

Description

  1.  Deleting files stored and created in the file processing session.
  2.  Deleting the file processing session directory.

Request

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

GET /api-session/v1.0/{sessionId}/close
PlopertyTypeUsageDescription
sessionId
String (64)MandatorySession 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.

Unable to render {include} The included page could not be found.

Example

GET /api-session/v1.0/77740b301f0880ef498cb1e474e8060b3e538cfeea8ebf508c2bad4b72b56a87/close HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

JSON object:

{
    "data": "Session {sessionId} closed"
}
PropertyTypeDescription
sessionId
StringFile processing session identifier


Example

{
    "data": "Session 77740b301f0880ef498cb1e474e8060b3e538cfeea8ebf508c2bad4b72b56a87 closed"
}




Storage API

File Upload

Scope

New file adding to the specific file processing session.

Description

1. The file 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:

PUT /api-storage/v1.0/{sessionId}/upload 
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.

Unable to render {include} The included page could not be found.

Body

PropertyTypeUsageDescription
file
Binary dataMandatoryFile to be uploaded


Example

PUT /api-storage/v1.0/77740b301f0880ef498cb1e474e8060b3e538cfeea8ebf508c2bad4b72b56a87/upload HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

JSON object:

{
    "data": [ 
				{
        	"includedDocuments": [
            	{
              	  "id": {String},
             	   "name": {String},
             	   "size": {Number},
					"type": {String}
				}
        	],
        	"id": {String},
        	"name": {String},
       		"size": {Number},
			"type": {String}
		 		}
			]
}
PropertyTypeDescription
data
Object
Data Object
data.includedDocuments
Array
If uploaded file is ASICE (EDOC), list of files included in ASIC container.
data.includedDocuments.id
String
Included file identifier, must be used if you need to download current included file.
data.includedDocuments.name
String
Included file name.
data.includedDocuments.size
Number
Included file size in bytes
data.includedDocuments.type
String

Processed file type.

"file" - In case of file or ASICE container

data.id
String
File Identifier (documentId)
data.name
String
File name
data.size
Integer
File size in bytes
data.type
String

Processed file type:

"file" - In case of file or ASICE container

Example if uploaded file is not ASICE container

{
    "data": {
        "id": "cc8bcb560bbfee4c190433ea63c549d1",
        "name": "test.doc",
        "size": 41280,
		"type": "file"
 			}
}

Example if ASICE container is uploaded 

{
    "data": {
        "includedDocuments": [
            {
                "id": "3cbc266934776e581bcb406f15bb5ffd",
                "name": "Receipt.doc",
                "size": 22528,
				"type": "file"
 			}
        ],
        "id": "23a3abe0a211478ae55554649178568e",
        "name": "Receipt.edoc",
        "size": 14805,
		"type": "file"
 			}
}




Add Document Digest

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.

Unable to render {include} The included page could not be found.

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.

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"
        }
    ]
}

File List

Scope

Retrieve a list of files in a file processing session.

Description

1. Returns information about files stored in the file processing session:
1.1. If the session files are not yet signed, a list of all files is returned;
1.2. If the session files are signed, the signed file (EDOC / PDF) is returned.

Request

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

GET /api-storage/v1.0/{sessionId}/list
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.

Unable to render {include} The included page could not be found.

Example

GET /api-storage/v1.0/77740b301f0880ef498cb1e474e8060b3e538cfeea8ebf508c2bad4b72b56a87/list HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

JSON object:

{
    "data": {
        "includedDocuments": [
            {
                "id": {String},
                "name": {String},
                "size": {Number},
				"type": {String}
 			}
        ],
        "id": {String},
        "name": {String},
        "size": {Number},
		"type": {String}
 			}
}

PropertyTypeDescription
data
Object
Data Object
data.includedDocuments
Array

Files included in signed container

data.includedDocuments.id
String
Included file Identifier (documentId)
data.includedDocuments.name
String
Included file name
data.includedDocuments.size
Integer
Included file size in bytes
data.includedDocuments.type
String

Processed file type:

"file" - In case of file or ASICE container

"hash" - In case if file digest and file name is added to session
data.id
String
File Identifier (documentId)
data.name
String
File name  File size in bytes
data.size
String 
File size in bytes
data.type
String 

Processed file type:

"file" - In case of file or ASICE container

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


Examples

Example of ASICE container containing one file
{
    "data": {
        "includedDocuments": [
            {
                "id": "3cbc266934776e581bcb406f15bb5ffd",
                "name": "Receipt.doc",
                "size": 22528,
				"type": "file"
			}
        ],
        "id": "23a3abe0a211478ae55554649178568e",
        "name": "Receipt.edoc",
        "size": 14805,
		"type": "file"
 			}
}
Example of ASICE container when file digest and name is signed
 {
    "data": [
        {
            "includedDocuments": [
                {
                    "id": "dc7a737f0d3dcb288902ed1df4942ee3",
                    "name": "Report.docx",
                    "size": 0,
                    "type": "hash"
                }
            ],
            "id": "592ad9f0c4f9356db0d0d3716a87d5f1",
            "name": "DigestEdoc.edoc",
            "size": 8891,
            "type": "file"
        }
    ]
}




File Download

Scope

Download a file from the file processing session

Description

Returns a requested file.

Request

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

GET /api-storage/v1.0/{sessionId}/{documentId}
PropertyTypeUsageDescription
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.

Unable to render {include} The included page could not be found.

Example

GET /api-storage/v1.0/cd6afb8b7e9fd6aa2b2ef7b981fa98cb59128fdef6c064f74dc9cef529a79d17/cc8bcb560bbfee4c190433ea63c549d1
HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

Binary object

PropertyTypeDescription
File
Binary data
Requested file

File Delete

Scope

Delete a file in a file processing session.

Description

The specified file is deleted from the session.

Request

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

DELETE /api-storage/v1.0/{sessionId}/{documentId}
PropertyTypeUsageDescription
sessionId
String (64)MandatoryFile processing session identifier
documentId
String (64)MandatoryDocument identifier, received from "upload" 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.

Unable to render {include} The included page could not be found.

Example

DELETE /api-storage/v1.0/cd6afb8b7e9fd6aa2b2ef7b981fa98cb59128fdef6c064f74dc9cef529a79d17/cc8bcb560bbfee4c190433ea63c549d1
HTTP/1.1
Authorization: Bearer a477b3a3366768c07e4c458f518711b4b351e8d2c2f0f78a1524e4d3efd00603
Host: signapi-prep.eparaksts.lv

Response

JSON object:

{
    "data": "Document {documentId} deleted"
}
PropertyTypeDescription
documentId
String
Document identifier, received from "upload" operation as "id" property

Example

{
    "data": "Document cc8bcb560bbfee4c190433ea63c549d1 deleted"
}






 

 

 

 

  • No labels