Eesti Pank / Bank of Estonia

Frontpage » Statistical Indicators » Financial sector statistics » Technical specifications for electronic reports
 
Tühik

Technical Specifications for Electronic Reports Submitted to Eesti Pank and Filed through Eesti Pank

    Format of Reports
    Short Description of a Report Formatted as an XML Document
    XML Schemas of Reports
    Encryption and Signing of Reports
    Key Management
    Transmission of Reports
    Reaction of the Robot (the application that processes reports) to the Received Messages
    Forwarding of Warnings to the Reporting Entities

Format of Reports

The reports submitted to Eesti Pank (EP) or the Financial Supervision Authority (FI) are formatted as XML documents the structure and contents of which are established by the XML schemas referred by http://www.fi.ee/schemas (see also http://www.w3.org/XML/Schema).

Short Description of a Report Formatted as an XML Document

A report and the accompanying descriptive information (header) are submitted as a message, the general form of which is the following:

<message>
	<message_header>
		...
	</message_header>
	<report>
		...
	</report>
</message>

 

Message Header
Element XML element Mandatory
Message header message_header Yes
Financial institution's code from Yes
Message creation date date Yes
Sender's name sender Yes
Sender's e-mail send_mail Yes
Sender's telephone send_phone No
Comments comment No
Request to confirm the delivery of message require_receipt No

Example:

<message_header>
		<from>765</from>
		<date>2001-10-10T11:20:23</date>
		<sender>Jaan Kask</sender>
		<send_mail>jaan.kask@maapank.ee</send_mail>
		<send_phone>6666666</send_phone>
		<require_receipt>yes</require_receipt>
</message_header>

 

Report

 
<report>
	<report_header>
		...
	</report_header>
	<row>
	...
	</row>
	...	
<row>
	...	
</row>
</report>

 

Header of a Report
Element XML element Mandatory
Report header report_header Yes
Report code typeid Yes
Report date timeid Yes
Report compiler's name compiler Yes
Report compiler's e-mail comp_mail Yes
Report compiler's telephone comp_phone Yes

Example:

 <report_header>
		<typeid>162</typeid>
		<timeid>2001-09-30</timeid>
		<compiler>Jelizaveta Ivanova</compiler>
		<comp_mail>liza@maapank.ee</comp_mail>
		<comp_phone>7777777</comp_phone>
</report_header>

 

Reporting Row
Element XML element Mandatory
Reporting row row Yes
Row 1 element According to the report schema Yes
Row 2 element According to the report schema Yes
... ... ...

Example:

<row>
		<pangakaart_liik_1>3</pangakaart_liik_1>
		<pangakaart_liik_2>5</pangakaart_liik_2>
		<kasutussagedus>1</kasutussagedus>
		<pangakaartide_arv>39739</pangakaartide_arv>
</row>

Example of an integral report formatted as an XML document:

<?xml version="1.0" encoding="ISO-8859-1"?>
<message xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="./x_aruanne162.xsd">
	<message_header>
		<from>765</from>
		<date>2001-10-10T11:20:23</date>
		<sender>Jaan Kask</sender>
		<send_mail>jaan.kask@maapank.ee</send_mail>
		<send_phone>6666666</send_phone>
		<require_receipt>yes</require_receipt>
	</message_header>
	<report>
		<report_header>
			<typeid>162</typeid>
			<timeid>2001-09-30</timeid>
			<compiler>Jelizaveta Ivanova</compiler>
			<comp_mail>liza@maapank.ee</comp_mail>
			<comp_phone>7777777</comp_phone>
		</report_header>
		<row>
			<pangakaart_liik_1>2</pangakaart_liik_1>
			<pangakaart_liik_2>1</pangakaart_liik_2>
			<kasutussagedus>2</kasutussagedus>
			<pangakaartide_arv>1520</pangakaartide_arv>
		</row>
		<row>
			<pangakaart_liik_1>1</pangakaart_liik_1>
			<pangakaart_liik_2>1</pangakaart_liik_2>
			<kasutussagedus>2</kasutussagedus>
			<pangakaartide_arv>1231</pangakaartide_arv>
		</row>
		<row>
			<pangakaart_liik_1>1</pangakaart_liik_1>
			<pangakaart_liik_2>3</pangakaart_liik_2>
			<kasutussagedus>2</kasutussagedus>
			<pangakaartide_arv>567</pangakaartide_arv>
		</row>
	</report>
</message>

XML Schemas of Reports

The general structure of reports formatted as XML documents is described by the XML schema 'x_headers.xsd'. In addition, every report is described by a corresponding XML schema, which is also the formal presentation of the legal instrument establishing the report. As the schema describing a report may change over time (for example, the decree regulating the schema is amended, errors in a schema are corrected, a schema is specified, etc), schemas have been provided with version numbers.
In order to find the proper schema for a report of a certain value date, the XML document 'skeemid.xml' is used. It contains the code of the related report, the term of validity of a schema, the version of the schema, and the name of the schema file. The schema file is found according to the following procedure:
Elements <versioon> and <fail> are found from the file 'skeemid.xml' using the code and value date (which must be in the range from <alates> to <kuni>)
The address referring to a respective schema is http://www.fi.ee/schemas/[version]/[file] ([] marks the value of a corresponding element. For example, the address referring to the balance sheet schema may be in the form 'http://www.fi.ee/schemas/1.4/x_aruanne21.xsd'.).

The XML document containing a report is considered to be correct if comparison thereof with a corresponding valid schema (depending on the value date of the report) reveals no errors.

Encryption and Signing of Reports

Unless a report is encrypted and signed, it will not be accepted for processing. Public-key algorithms realised by applications (e.g, PGP, GnuPG) supporting the OpenPGP standard (http://www.ietf.org/rfc/rfc2440.txt) are used to protect reports.

Type of the encryption and signing key : RSA
Length of the public key pair: 1024 bits
Encryption algorithms: IDEA, 3DES, CAST5
Hash function: MD5, SHA1
Compression algorithm: -, ZIP
Robot's public key: "EPSTAT;ARUANDLUS;Peeter Liik;15.09.2003"
Key ID: 0xD97B994D
Fingerprint: 6E47 DE7E 80CD 75D7 8CFE 4978 DDFA 0036

The key was renewed on 16/09/2003.
Robot's public key: "EPSTAT;ARUANDLUS;Peeter Liik;15.09.2005 <peeter.liik@epbe.ee>"
Key ID: 0x335FEC39
Fingerprint: 8F38 4874 15D8 2A70 687D 1F9C CD67 B6C1

The key was renewed on 19/09/2005.
Robot's public key: "EPSTAT;ARUANDLUS;Peeter Liik;19.09.2007 <peeter.liik@epbe.ee>"
Key ID: 0x95D31D99
Fingerprint: 1333 7625 04D6 3988 22B8 41BC 5B09 43DA

The key is going to be renewed on 19/09/2007.
The old and new key are both valid within 30 days as of the renewal, since then it is prohibited to use the old key!

Robot's public key: "EPSTAT;ARUANDLUS;Peeter Liik;19.09.2009 <peeter.liik@epbe.ee>"
Key ID: 0x1538DE3B
Fingerprint: 421B CAF5 1DAA 98C3 490F 8210 F612 D8FB

GnuPG has been tested starting from the version 1.0.7 together with the command line key – pgp6 and PGP starting from the version 2.6 (however, it is recommendable to use versions starting from the 6.5).
Encryption and signing have to be performed as a common activity (command line keys -es).

Key Management

1. Requirements to keys
     The key string must include the code of the institution, the word ARUANDLUS, the name of the employee that uses the key and the final date of validity of the key pair. EP uses EPSTAT as the code of institution.
    The key pairs must be changed at least once every two years.
    The used key pairs must be retained in order to ensure handling of the changed data.
2. Organisation of work in an institution forwarding reports
    An institution forwarding reports must appoint an employee to organise data exchange with EP. The responsible employee guarantees the handling of the institution's keys and the changed data.
    The responsible employee arranges the generation of the necessary number of key pairs (key pairs of the institution's reporting), organises the use of the keys by the employees involved and forwards the public key(s) to the key manager appointed by EP.
    Only the employee represented in the username is allowed to know the password protecting the personal key of the key pair of the institution's reporting.
    The institution signs the data subject to electronic forwarding by the personal reporting key, encrypts them by the EP public key, and forwards them to EP.
    The institution decrypts the electronic data received from EP and makes sure these are integral and authentic.
3. Organisation of work at EP
    The EP key manager ensures the handling of used keys and changed data.
    The EP key manager generates the key pair (EP key pair), organises the usage thereof in EP and forwards the public key to the institutions' responsible employees.
    Only the key manager is allowed to know the password protecting the personal key of the EP key pair.
    EP decrypts the electronic data received from a credit institution and makes sure these are integral and authentic.
    In case of need, EP signs the data subject to electronic forwarding by a personal key, encrypts these by the public key of an institution's reporting, and forwards these to the institution.

4. First change of keys
The responsible employee of an institution and the EP key manager change public keys electronically. The integrity and authenticity of the keys is established by comparing the fingerprints of the keys.

5. Further change of keys
Upon a regular change of keys, the new public keys are signed by the valid personal key and forwarded electronically.
In case there occurs an emergency situation (a personal key is disclosed, lost, or destroyed), the addressees are immediately notified thereof, new key pairs are generated, and key pairs are changed according to the procedure described in clause 4.
The key pairs that have become invalid as a result of planned key changes or emergency situations must be removed from use.

Transmission of Reports

A signed and encrypted report (or reports) are forwarded as e-mail attachment(s) to xml@fi.ee
The principle here is: 1 attachment = 1 report = 1 XML document.
The e-mail has to be in the MIME encoding. Other encodings, such as UUcode are not allowed.
The Subject line and the body of the e-mail are left empty.
The number of attachments is not limited, the only thing to be followed is the good practice of sending e-mails (maximum 1 MB).
It is not allowed to compress the XML document sent as an attachment before or after encryption and signing.

Reaction of the Robot (the application that processes reports) to the Received Messages

If the Robot receives a correct message, it only reacts if the value of the element <require_receipt> was 'yes'. If that is the case, the sender receives a note from the Robot confirming that the respective report (the name of the attached file is indicated) has been received for processing.
In case of a faulty report, an error message is sent to the addressee indicated by the sender.
More general errors are sent at the address indicated in the header of the message, whereas errors relating to the report are forwarded to the address in the header of the report. There also occur situations where errors can be sent only to the actual sender of the message (or a certain address).
In case the value of the element <comment> has not been left empty, the Robot will forward the comment to the person at EP/FI that processes the report.

Forwarding of Warnings to the Reporting Entities

In case a formally correct report has not been received by the specified date, the reporting entity is forwarded a warning message. The message is sent at the e-mail address indicated by the reporting institution.

Additional information:
Peeter Liik
668 0976
pliik@epbe