This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/.
1 Introduction
Management services are services provided by the X-Road governing organization to manage security servers and security server clients. They are called by security servers to register in central server the configuration changes made by the security server administrator. The management services are the following:
clientReg – registering an X-Road subsystem as a client of the security server;
clientDeletion – removing a client from the security server;
authCertReg – adding an authentication certificate to the security server;
authCertDeletion – removing an authentication certificate from the security server.
ownerChange - changing the owner member of the security server.
This protocol builds on existing transport and message encoding mechanisms. Therefore, this specification does not cover the technical details and error conditions related to making HTTPS requests together with processing MIME-encoded messages. These concerns are discussed in detail in their respective standards.
This specification does not include option for partially implementing the protocol – the conformant implementation must implement the entire specification.
1.1 Terms and abbreviations
1.2 References
[REQUIREMENT] Key words for use in RFCs to Indicate Requirement Levels. Request for Comments 2119, Internet Engineering Task Force, March 1997.
[WSDL] Web Services Description Language (WSDL) 1.1. World Wide Web Consortium. 15 March 2001.
[DER] DER encoding. ITU-T X.690. July 2002.
2 Format of the Messages
2.1 clientReg - Security Server Client Registration
The client registration service is invoked by the security server when a new client is added to the server.
The body of the client registration message (request or response) contains the following fields:
client – identifier of the subsystem to be added to the security server;
server – identifier of the security server where the client is added;
The XML Schema fragment of the client registration request body is shown below. For clarity, documentation in the schema fragment is omitted.
The request is sent using HTTP POST method. The content type of the request MUST be multipart/related and the request must contain the following MIME parts.
X-Road SOAP request message. The message MUST contain the regular X-Road headers and the two data fields (server, client). The content type of this part MUST be text/xml.
Signature of the member that owns the subsystem to be registered as a security server client. The MIME part must contain signature of the SOAP request message, created with the private key corresponding to a signing certificate of the subsystem's owner. The content type of this part must be application/octet-stream. Additionally, the part MUST include header field signature-algorithm-ID that identifies the signature algorithm. Currently supported signature algorithms are SHA256withRSA, SHA384withRSA, SHA512withRSA, SHA256withRSAandMGF1, SHA384withRSAandMGF1, and SHA512withRSAandMGF1.
Signing certificate of the subsystem's owner that was used to create the second MIME part. The content type of this part MUST be application/octet-stream.
OCSP response certifying that the signing certificate was valid at the time of creation of the request. The content type of this part MUST be application/octet-stream.
The response echoes back the client and the server fields of the request and adds the field requestId.
2.2 clientDeletion - Security Server Client Deletion
The clientDeletion service is invoked by the security server when a client is unregistered.
The body of the client deletion message (request or response) contains following fields:
client – identifier of the subsystem to be removed from the security server;
server – identifier of the security server where the client is removed;
The XML Schema fragment of the client deletion request body shown below.
The response echoes back the client and the server fields of the request and adds the field requestId.
2.3 authCertReg - Security Server Authentication Certificate Registration
The authCertReg service is invoked by the security server when a new authentication certificate is added to the server.
The body of the authentication certificate registration message (request or response) contains the following fields:
server – identifier of the security server where the authentication certificate is added;
address – DNS address of the security server;
The XML Schema fragment of the authentication certificate registration request body is shown below. For clarity, documentation in the schema fragment is omitted.
Unlike the other requests, the authentication certificate registration request cannot be sent as a regular X-Road request. This is caused by a bootstrapping problem – sending an X‑Road message requires that the authentication certificate of the security server is registered at the central server. However, the certificate is registered only as a result of invoking this service. Therefore, another mechanism is needed.
The authentication certificate registration request is sent to the central server directly via HTTPS. When making the HTTPS connection the client MUST verify that the server uses the TLS certificate that is given in the global configuration.
If the central server encounters an error, it responds with a SOAP fault message.
The request is sent using HTTP POST method. The content type of the request MUST be multipart/related and the request must contain the following MIME parts.
X-Road SOAP request message. The message MUST contain the regular X-Road headers and the three data fields (server, address, authCert). The content type of this part MUST be text/xml.
Proof of possession of the authentication key. The MIME part must contain signature of the SOAP request message (the body of the first MIME part). The signature MUST be given using the private key corresponding to the authentication certificate that is being registered (authCert field of the SOAP message). The content type of this part must be application/octet-stream. Additionally, the part MUST include header field signature-algorithm-ID that identifies the signature algorithm. Currently supported signature algorithms are SHA256withRSA, SHA384withRSA, and SHA512withRSA.
Signature of the security server's owner. The MIME part must contain signature of the SOAP request message, created with the private key corresponding to a signing certificate of the security server's owner. The content type of this part must be application/octet-stream. Additionally, the part MUST include header field signature-algorithm-ID that identifies the signature algorithm. Currently supported signature algorithms are SHA256withRSA, SHA384withRSA, SHA512withRSA, SHA256withRSAandMGF1, SHA384withRSAandMGF1, and SHA512withRSAandMGF1.
Authentication certificate that is being registered (authCert field of the SOAP message). The content type of this part MUST be application/octet-stream.
Signing certificate of the security server's owner that was used to create the third MIME part. The content type of this part MUST be application/octet-stream.
OCSP response certifying that the signing certificate was valid at the time of creation of the request. The content type of this part MUST be application/octet-stream.
The central server sends responds with X-Road response message (content type MUST be text/xml). The response echoes back the three fields of the SOAP request and adds the field requestId.
2.4 authCertDeletion - Security Server Authentication Certificate Deletion
The authCertDeletion service is invoked by the security server when an authentication certificate is deleted from the server. The body of the authentication certificate deletion message (request or response) contains the following fields:
server – identifier of the security server where the authentication certificate is removed;
authCert – contents (in DER encoding) of the authentication certificate that is removed from the security server;
The XML Schema fragment of the authentication certificate deletion request body is shown below.
The request is sent using HTTP POST method. The content type of the request MUST be multipart/related and the request must contain the following MIME parts.
X-Road SOAP request message. The message MUST contain the regular X-Road headers and the two data fields (server, client). The content type of this part MUST be text/xml.
Signature of the new owner member of the security server. The MIME part must contain signature of the SOAP request message, created with the private key corresponding to a signing certificate of the new owner member. The content type of this part must be application/octet-stream. Additionally, the part MUST include header field signature-algorithm-ID that identifies the signature algorithm. Currently supported signature algorithms are SHA256withRSA, SHA384withRSA, SHA512withRSA, SHA256withRSAandMGF1, SHA384withRSAandMGF1, and SHA512withRSAandMGF1.
Signing certificate of the new owner member that was used to create the second MIME part. The content type of this part MUST be application/octet-stream.
OCSP response certifying that the new owner member's signing certificate was valid at the time of creation of the request. The content type of this part MUST be application/octet-stream.
The response echoes back the server and the client fields of the request and adds the field requestId.