[RUBY] Part 1 Running e-Gov using the SmartHR library kiji (e-Gov specifications)

1. 1. Introduction

The library kiji built into SmartHR, a cloud personnel and labor software service, is an OSS created in Ruby, and anyone can obtain, modify, and redistribute it. SmartHR kiji

In this article, we will try to generate a signed xml using the library kiji (hereinafter, kiji) and send it to the e-Gov electronic application system (hereinafter, e-Gov) with the curl command. I think that I can deeply understand the specifications of e-Gov because I move e-Gov interactively. Furthermore, we will define the problems of e-Gov and consider the possibility of improvement in the minor portal. It should be noted that the e-Gov that has been confirmed to work here is a verification environment that is open to software developers.

This time, we will introduce the e-Gov specifications as the first of all four times. The second time is e-Gov public material, the third time is execution environment construction, and the fourth time is actual machine confirmation.

The operating environment is windows10, ruby 2.6.5p114 (2019-10-01 revision 67812) [x64-mingw32], curl 7.58.0 (x86_64-pc-win32) libcurl / 7.58.0 WinSSL zlib / 12.11.

2. Assumed reader

The following readers are assumed.

--People who want to understand the specifications of e-Gov to develop software services --People who regularly use electronic applications and want to understand the specifications of e-Gov --People who want to experience xml signature --People who want to move kiji

3. 3. What is e-Gov external linkage API?

Electronic application allows you to perform administrative procedures such as paper applications and notifications from your home or office computer using the Internet. e-Gov publishes the specifications of the external linkage API for making electronic applications for various administrative procedures under the jurisdiction of each ministry for software services developed by software developers.

e-Gov processes application for procedures according to the flow of ① to ④. Of these, the API specifications for ① and ④ are subject to publication. ① The user sends the created application data to e-Gov and receives confirmation of arrival. ② e-Gov sends the completed application data to the competent ministry. ③ The ministry having jurisdiction over the procedure examines the application data and registers the result in e-Gov. ④ The user inquires to e-Gov and confirms the examination results and official document data.

The e-Gov external linkage API can be broadly classified into three types: (1) user ID registration API, (2) user authentication API, and (3) various electronic application processing APIs. In the software service, you can proceed with the desired application procedure by calling these external linkage APIs in combination.

The e-Gov external linkage API is shown below. For some APIs, check the operation with the curl command in the actual machine check.

3.1 User ID registration API

The user ID is an ID that uniquely identifies the user who makes an electronic application using the software service. In e-Gov, the user ID is registered only once for each user.

The software service sends XML with the user ID signed with the private key to e-Gov. e-Gov verifies the XML signature and registers the user ID and the identification information of the public key certificate in association with each other.

3.2 User authentication API

In e-Gov, user authentication is performed before executing various electronic application processing APIs.

The software service sends the XML with the user ID signed with the private key to e-Gov. e-Gov will issue an access key if there is no problem after confirming that the user ID has been registered in the system and the correspondence between the user ID and the certificate identification information.

From now on, in software services, it is necessary to set the access key in the HTTP header part when calling various electronic application processing APIs. The access key has a valid period, and if the access key expires after the valid period, access to various APIs will not be permitted. In this case, you need to authenticate the user again and obtain a new access key.

3.3 Various electronic application processing APIs

When considering a scenario in which a user proceeds with an electronic application procedure using a software service, it can be roughly divided into five by combining related APIs.

First, the user makes a status inquiry from the batch application. After that, the application will be withdrawn or amended as necessary based on the result of the status inquiry. Furthermore, we will acquire official documents and comments issued as the progress of the procedure examination progresses. At a timing different from the above, the user acquires a list of financial institutions that can use electronic payment and a list of payment information as needed, and maintains the certificate identification information registered in e-Gov.

The above contents are summarized.

4. Information security measures required for software services

Software services need to take the following information security measures in order to use the e-Gov external linkage API.

--Encrypt the communication path between the software service and e-Gov with SSL / TLS --The software service digitally signs the application data and attached files sent by electronic application in order to confirm the authenticity of the sender and whether or not the transmitted data has been tampered with by e-Gov, and puts it in the specified format. After storing it, send it to e-Gov --In software services, the software ID, user ID, and access key are encrypted and obfuscated. --When using software services, perform subject authentication using the user's account password. --When saving the subject authentication information in the software service, encrypt the contents.

Details are described in "External Linkage API Information Security Requirement Specification".

5. e-Gov external connection interface

Organize the e-Gov external connection interface from the perspective of input and output.

Here, after organizing the input / output data, we will explain the application data and signed xml in detail.

(1) Input

Since the software service uses the e-Gov external linkage API, it accesses the request URI specified for each API. When accessing the request URI, specify the access key and software ID in the HTTP header. Also, specify the Basic authentication ID and password together only in the verification environment.

When accessing the request URI with the POST command, you can request the application procedure from e-Gov by specifying the application data etc. in the body part of the request and sending it. Application data is the conversion of the application dataset into a format that can be accepted by e-Gov. Also, when accessing the request URI with the GET command, various information can be obtained from e-Gov by specifying the required information in the URI parameter.

The e-Gov electronic application API that uses the POST command is summarized. For these APIs, specify one of (1) application data, (2) signed xml, and (3) other in the body part of the request.

(2) Output

e-Gov returns a response to a software service request. The response includes the response code and response body (response result XML). The software service performs subsequent processing according to the response of each API.

The \ tag of the response body (response result XML) of the official document acquisition API or comment acquisition API contains the data obtained by encoding the Zip format file in Base64 format. This is an official document or comment notification issued by the competent ministry of procedure, and it is necessary for the software service side to decode it in Base64 format, decompress the Zip format file, and provide a means to show it to the user.

5.1 Application dataset and application data

The "application data set" is a data set consisting of configuration management XML, application form XML, and attached files, and is used for batch application, withdrawal application, and amendment application.

The software service signs the configuration management XML in order to confirm the authenticity of the sender and whether or not the transmitted data has been tampered with by e-Gov. In addition, the application dataset containing the signed configuration management XML (signed xml) is zipped and encoded in Base64 format.

"Application data" is the result of encoding the zip file into Base64 format and stored in the \ tag of XML, which is a format that e-Gov can accept. The format of application data is defined for each API. Details are described in "e-Gov Electronic Application System External Link API API (Version 1) Specifications".

Next, we will explain the configuration management XML, application XML, and attached files.

(1) Configuration management XML

As a logical unit that stores the attribute information of the entire data of the application form, it manages the application information that is not included in the application form XML and the relation of the logical unit of the entire data.

The physical file of configuration management information is called "configuration management XML", and except for the withdrawal request, one is always included in the application data set.

The structure of the configuration management XML is defined for each application of batch application, withdrawal request, withdrawal application, and amendment. In addition, in the individual file signature format described later, the tag structure of configuration information is defined for each of the configuration management XML for application XML, the configuration management XML for amendment, and the configuration management XML for attachments.

(2) Application form XML

It is a form to fill in application / notification items in each administrative procedure. In e-Gov, the XML format that stores application / notification items is called "application form", and the physical file is called "application form XML".

(3) Attachment

This is an attached document that is required to be submitted along with the application form according to the application / notification items in each administrative procedure. In e-Gov, other documents that are not stored in the application form are called "attached documents", and their physical files are called "attached files".

5.2 About signed xml

In e-Gov, the electronic certificate (public key) used for each user ID is used for each user ID in order to confirm the identity and detect whether the document has been tampered with based on the public key infrastructure (PKI). It is managed by associating it with the ID. Therefore, in the software service, it is necessary to create a signed xml for the application data using the private key corresponding to the digital certificate managed for each user ID.

A signed xml is an xml file with digital signature information added. For xml signatures, there is a W3C Recommendation (https://www.w3.org/TR/xmldsig-core/) that specifies the XML syntax for digital signatures.

The electronic signature information is (1) information on the algorithm used for signature value calculation and digest calculation, (2) hash value for confirming document tampering, (3) electronic signature for the hash value, and (4) electronic certificate (public key). The format of the digital signature information is as follows.

The description of each tag element of xml signature is reprinted from the Wiki. e-Gov also follows this content.

--The SignedInfo element specifies what to sign and the algorithm to use. The SignatureMethod and CanonicalizationMethod elements are used by the SignatureValue element and are included in SignedInfo to protect them from tampering. --The list of Reference elements specifies the resource to be signed by URI. The result of applying the digest (hash) algorithm (in the DigestMethod element) to the resource with all the transformations applied to the resource before computing the hash in the Transforms element (which is Base64 encoded in the DigestValue element). To specify. --The SignatureValue element is the Base64 encoded value of the signature. This value is the signature (generated by the SignatureMethod specification) after serializing the SignedInfo element by the algorithm specified by the CanonicalizationMethod element. (See the XML Normalization section for more information on normalization) --The KeyInfo element is an optional element that allows the recipient of the signature to obtain the key needed to verify the signature. Generally, it can contain a series of X.509 certificates. If it does not exist, the recipient is required to identify the key from the contents of the data.

There are two types of e-Gov signed xml: signed xml included in the application dataset and signed xml specified directly in the HTTP body part. The former is used for batch application API, etc., and the latter is used for user registration / authentication API, etc.

5.2.1 Signed xml included in the application dataset

When assigning a signature to the configuration management XML included in the application data set, (1) "standard format" that assigns a signature to the entire application data, and (2) "individual file signature format" that assigns a signature to each application form and attached file. There are two types.

The format of the electronic signature information is described in "e-Gov Electronic Application System External Link API Application Data Specification Common Data Specification".

(1) Standard format

The application data in standard format is a data set consisting of the following three files.

--Configuration management XML (including signature information) --Application XML

• Attached document

These files have the following relationships:

In the software service, the application data is created by signing according to the following procedure. (1) Calculation of hash value from configuration management information of configuration management XML ② Calculate the hash value from the application XML ③ Calculate the hash value from the attached document ④ Sign the entire hash value with the private key ⑤ Give the certificate information (public key) corresponding to the private key ⑥ Consolidate the data set into zip format and encode it in Base64 format. ⑦ Store in application data

From the received application data, e-Gov will verify the identity and whether the data has been tampered with by the following procedure. (1) Extract the Base64 format encoding result of the dataset from the application data (2) Decode in Base64 format and convert to a zip format data set. ③ Unzip the zip and get the configuration management XML (4) Compare the certificate of configuration management XML with the certificate managed by e-Gov to confirm the authenticity of the sender. ⑤ Decrypt the signature value with the certificate (public key) and extract the hash value. ⑤ Calculate hash values for each of configuration management XML, application XML, and attached files. ⑥ Compare the hash values, and if they match, determine that there is no data tampering.

The application procedures for the standard format are as follows.

--Notification of employment insurance insured qualification / electronic application --Notification of loss of employment insurance insured status (no turnover slip issued) / Electronic application --Notification of name change of employment insurance insured person / electronic application --Various change notifications / electronic applications for employment insurance establishments --Insurance relationship established (continued) / Electronic application --Notification of establishment of employment insurance business / electronic application --Health insurance / welfare annuity insurance insured qualification notification, seafarer insurance / welfare annuity insurance insured qualification acquisition notification / electronic application --Notification of name change (correction) of health insurance / welfare annuity insurance insured person, notification of name change of sailor insurance / welfare annuity insurance insured person / electronic application --Notification of change (correction) related to health insurance / welfare annuity insurance establishment / electronic application --Notification of new application of health insurance / welfare annuity insurance, notification of new application of sailor insurance / welfare annuity insurance / electronic application --Notification of change (correction) of location name of business establishment covered by health insurance / welfare annuity insurance (within jurisdiction) (outside jurisdiction) Out of jurisdiction) / Electronic application

(2) Individual file signature format

The application data in the individual file signature format is a data set consisting of the following 5 files.

--Configuration management XML --Application XML --Configuration information XML for application form

• Attached document --Configuration information XML for attached documents

These files have the following relationships:

The hash value calculated from the application form XML is signed, and the signature value is added to the configuration information XML for the application form. In addition, the hash value calculated from the attached document is signed, and the signature value is added to the configuration information XML for the attached document. Unlike the standard format, there is no signature value in the configuration management XML.

In the software service, the application data is created by signing according to the following procedure.

(1) Calculation of hash value from configuration management information of configuration information XML for application form ② Calculate the hash value from the application XML ③ Create a signature value with a private key from each hash value ④ Give the certificate information (public key) corresponding to the private key (5) Configuration information for attached documents Calculate the hash value from the XML configuration management information. ⑥ Calculate the hash value from the attached file ⑦ Create a signature value with a private key from each hash value ⑧ Give certificate information (public key) corresponding to the private key ⑨ Consolidate the data set into zip format and encode it in Base64 format ⑩ Store in application data

e-Gov verifies the identity verification and the presence or absence of data tampering from the received application data in the reverse procedure.

In addition, the application procedure corresponding to the individual file signature format is as follows. "Continuous writing" is a format that allows you to write multiple names.

--Insurance relationship established (continued) / Electronic application --Notification of acquisition of employment insurance insured qualification (serialized type) / electronic application --Notification of loss of employment insurance insured status (serialized) / electronic application --Notification of loss of employment insurance insured status (with turnover slip issued) / Electronic application --Authorization / electronic application with subcontractor as business owner --Application for issuance of turnover slip after submission of employment insurance insured disqualification notification / electronic application --Application for employment insurance old-age employment continuation benefit (old-age employment continuation basic benefit) / electronic application --Health insurance / welfare annuity insurance insured person's monthly compensation basic notification (CSV file attachment method) / Electronic application --National Pension Insured Qualification Acquisition / Type Change / Type Confirmation (Applicable to No. 3 Insured Person) Notification / Electronic Application

5.2.2 Signed xml specified directly in the HTTP body part

For API related to user ID registration, user authentication, and certificate identification information addition / update / deletion, directly specify the signed xml in the HTTP body part.

The format of the electronic signature information is described in "e-Gov Electronic Application System External Link API API (Version 1) Specifications".

These signed xmls have in common that they calculate the hash value of the entire \ tag and sign that hash value. Follow the procedure below to add signature information. ① Calculate the hash value for the entire \ tag ② Sign the hash value with the private key ⑤ Give the certificate information (public key) corresponding to the private key

For user ID registration and user authentication, do not specify the public key certificate in the \ tag.

6. About state transition of electronic application processing

In e-Gov, the status is managed by dividing it into a main state and a substate according to the progress of application processing.

6.1 Main state

For each procedure, the status changes in the order of (Processing) → (Arrival) → (Examination) → (End of examination) → (End of procedure) according to the progress.

Each state has the following meanings:

――E-Gov performs various checks on the application data. Various checks are file configuration check, XML schema check, consistency check, and format check. If there is no problem, it will transition from (in process) to (reached). ――When the examination by the ministry starts, it will transition from (reached) to (under examination). ――When the examination by the ministry is completed, it will transition from (under examination) to (end of examination). --After acquiring the official document with the software service, if you notify e-Gov of the completion of the official document acquisition, the transition from (examination completed) to (procedure completed).

6.2 Substate

(1) Pick up

When the software requests e-Gov to withdraw the procedure during (reaching) or (under review), the substate changes from (none) to (under review), and finally the main state (procedure completed) + substate (Withdrawn).

(2) Correction

If the ministry having jurisdiction over the procedure issues an amendment instruction to the application data during (under review), (substate) will change from (none) to (waiting for amendment processing). Depending on the content of the correction instruction, the software service must isolate the following sequence as follows:

If the amendment type is "resubmit" and the software service requests amendment (resubmission), it will be the main state (procedure completed) + substate (resubmitted). When the correction type is "partial correction", when the software service requests correction (partial correction), it becomes a substate (none).

The above is expressed in the state transition diagram.