SMKI Interface Design Specification - Data … · SMKI Interface Design Specification DCC Public Page 4 of 31 2 Introduction 2.1 Purpose The SMKI Interface Design Specification specifies

SMKI Interface Design Specification

DCC Public Page 1 of 31




1.1.1.1 Contents

2 Introduction ...................................................................................................... 4

2.1 Purpose ...................................................................................................... 4

3 Interface Definition ........................................................................................... 5

3.1 SMKI Portal interface via DCC Gateway Connection .................................. 6

3.1.1 Organisation Certificate Signing Requests ........................................... 6

3.1.2 Device Certificate Signing Requests .................................................... 7

3.2 Web Service Interface ............................................................................... 11

3.2.1 DCC Obligations in respect of the Web Services Interface ................. 11

3.2.2 Eligible Subscriber Obligations in respect of the Web Service Interface 12

3.3 SMKI Portal interface via the Internet ........................................................ 13

3.3.1 Organisation Certificate Signing Requests ......................................... 13

3.3.2 Device Certificate Signing Requests .................................................. 14

3.4 Additional Obligations in respect of Device Certificates ............................. 16

3.5 Availability and Service Continuity ............................................................. 17

3.6 Auditing ..................................................................................................... 17

3.7 Error Handling ........................................................................................... 17

Appendix A Schema ......................................................................................... 18

Web Service Messages ....................................................................................... 20

Example: Device Certificate Signing Request Message ................................... 20

Device Certificate Signing Request: Element Table ......................................... 20

Device Certificate Signing Request: Attribute Table ......................................... 20

Example: Device Certificate Signing Response Message – Success ............... 21

Example: Device Certificate Signing Response Message – Incorrect XML ....... 22

Example: Device Certificate Signing Response Message – Other error. .......... 23

Device Certificate Signing Response: Element Table ....................................... 23

3.7.1 Device Certificate Signing Response: Attribute Table ........................ 23

Response Status .............................................................................................. 24



Appendix B Certificate Signing Request Structure ........................................ 25

Information to be contained within an Organisation CSR ..................................... 25

Information to be contained within a Device CSR ................................................ 26

Format of Batched Certificate Signing Requests .................................................. 27

Response File .................................................................................................. 27

Appendix C Authentication Credentials .......................................................... 28

Appendix D Glossary ........................................................................................ 29



2 Introduction

2.1 Purpose

The SMKI Interface Design Specification specifies the technical details of the SMKI Service Interface insofar as it relates to Parties.

It includes the protocols and technical standards that apply to the SMKI Service Interface, which are based on open standards as laid out in Section L4.4 of the Code.

The SMKI Interfaces, as defined in this document, will be provided for both SMKI Services and Test SMKI Services.



3 Interface Definition

The SMKI Interface provides Parties with interfaces to the SMKI Services in order that Parties may access the SMKI Service.

The DCC shall make three interfaces available:

a) a SMKI Portal interface accessed via a web browser and only accessible via the DCC Gateway Connection;

b) a Web Services Interface that may be accessed by Parties’ automated systems, and only accessible via the DCC Gateway Connection; and;

c) a SMKI Portal interface made available over a secured Internet connection and accessed through a web browser that does not go through the DCC Gateway Connection.

[An additional interface for the purposes of automating the submission of Batch CSRs for Device Certificates is being considered by the DCC, which would be available to Authorised Subscribers under the Device Certificate Policy].

The DCC shall ensure that PCKS#10 certification request standard is used for the submission of Certificate Signing Requests (CSR).

The structure of Certificate Signing Requests for Organisation Certificates and Device Certificates are defined in Appendix B.

Parties shall submit Certificate Signing Requests according to the CSR structures defined in Appendix B.



3.1 SMKI Portal interface via DCC Gateway Connection

The SMKI Portal interface via DCC Gateway Connection provides an asynchronous mechanism for Authorised Responsible Officers to submit Organisation CSRs, and Device CSRs in batch or ad-hoc form.

The DCC shall ensure that the SMKI Portal interface via DCC Gateway Connection:

a) uses the HTTPS protocol, secured by mutually authenticated TLS 1.2 in line with the cryptographic standards set out in Appendix C.

b) ensure that the SMKI Portal interface presents to the user a x.509 v3 certificate that is recognised by the CA/Browser Forum for the purposes of Server Side SSL/TLS authentication;

c) uses Javascript, Cascading Style Sheets (CSS) and images;

d) is compliant with the W3C Web Content Accessibility Guidelines (v2) at “AA” level;

e) denies access to the SMKI Portal via DCC Gateway Connection without a valid credential for authentication.

The process for obtaining a DCC Gateway Connection is detailed in Section H3 of the Code.

3.1.1 Organisation Certificate Signing Requests

3.1.1.1 DCC Obligations

The DCC shall, following the receipt of a CSR for an Organisation Certificate:

a) [ensure that the Party that submitted the CSR is an Eligible Subscriber for the Certificate that is the subject of the CSR];

b) validate the format, and verify the signature of the Certificate Signing Request in line with Appendix B of this document, and Appendix B of the Code;

c) either accept and submit CSR to the RA for approval, or reject the CSR; and;

d) notify the Party of either;

i. approval of the CSR; or

ii. the reasons for the rejection of the CSR.

e) upon receipt of the CSR by the RA from the OCA, the RA will verify the content of the CSR;

f) where appropriate notify the Party of the reasons for the rejection of the CSR.

g) upon approval by the RA, ensure that the CSR is processed, the resulting Certificate lodged in the SMKI Repository, and that the Certificate is also made available for download via the SMKI Portal interface via DCC Gateway; and

h) upon rejection of an Organisation Certificate by a Party and subsequent notification to DCC of the rejection, the DCC shall revoke



the Organisation Certificate, and place the Organisation Certificate on the CRL. The CRL shall be signed by the OCA.

3.1.1.2 Eligible Subscriber Obligations

Eligible Subscribers wishing to be issued with an Organisation Certificate shall ensure that:

a) they generate a relevant CSR in line with Appendix B of this document,

and Appendix B of the Code;

b) they copy and paste the CSR into the Certificate Signing Request form

on the SMKI Portal interface formatted in line with Appendix B ;

c) the information contained in the CSR is true and accurate;

d) if the CSR is rejected by the DCC, the Party must, if they still wish to be

issued with a relevant Certificate, correct the errors and re-submit the

CSR. The Party does not need to generate a new key pair;

e) if a Certificate is not accepted in line with L11.3 of the Code, the

Subscriber shall immediately notify the DCC via the DCC Service Desk.

f) on downloading the returned Organisation Certificate they use

reasonable endeavours to establish that the information contained in the

resulting Organisation Certificate is consistent with the information

contained in the corresponding CSR;

i. should there be an inconsistency, the Party shall follow the steps

set out in Section 3.4

g) if the Certificate is not accepted by the Party, and the Party still wishes to

be issued with an Organisation Certificate, the Party must generate a

new key pair and submit the resultant CSR in line with the process set

out above.

3.1.2 Device Certificate Signing Requests

3.1.2.1 DCC Obligations in respect of Ad Hoc Device Certificate Signing Requests

The DCC shall, following the receipt of a CSR for a Device Certificate

a) [ensure that Party is an Eligible Subscriber for the Device Certificate that is the subject of the CSR];

b) validate the format of the submitted CSR in line with Appendix B) and verify the signature of the Certificate Signing Request.

c) either accept and submit the CSR to the RA for approval, or reject the CSR;



d) where appropriate notify the Party of the reasons for the rejection of the CSR; and

e) following the processing of a valid CSR by the RA, the resulting Certificate shall be lodged in the SMKI Repository and be made available for download from the SMKI Portal interface;

f) should the DCC be notified by a Party of an inconsistency, the DCC

shall log the event and investigate as appropriate.

3.1.2.2 Eligible Subscriber Obligations in respect of Ad Hoc Device Certificate Signing Requests

Eligible Subscribers shall ensure that:

a) they generate the CSR on their system in line with Appendix B of this

document, and Appendix B of the Code;


on the SMKI Portal interface, formatted in line with Appendix B;

c) the information contained in the CSR is true and accurate; and

d) if the CSR is rejected by the DCC, the Party must correct the errors and

re-submit the CSR. The Party may not need to instruct the Device to

generate a new key pair for the subsequent CSR depending on the error

condition.

e) on downloading the returned Device Certificates they use reasonable

endeavours to establish that the information contained in the resulting

Device Certificate is consistent with the information contained in the

corresponding CSR;



f) if the Certificate is not accepted by the Party, and the Party still wishes to

be issued with a Device Certificate, the Party must generate a new key

pair and submit the resultant CSR in line with the process set out above.

3.1.2.3 DCC Obligations in respect of Batch Device Certificate Signing Requests

The DCC shall:

a) [ensure that Eligible Subscribers are able to submit Batched Certificate Signing Requests (Batched CSRs)];

b) upon receipt of the Batched CSR, the DCA will validate that the number of CSRs contained within the Batched CSR is less than or equal to 50,000;



i. Should the Batched CSR contain more than 50,000 CSRs, the DCC shall reject the Batched CSR and notify the Party accordingly;

ii. Should the Batched CSR contain less than or equal to 50,000 CSRs, the Batched CSR is submitted for processing by Registration Authority Personnel.

c) inform the Party of the number of CSRs submitted within each Batched CSR;

d) ensure that the RA will, where appropriate carry out additional checks of one or more of the CSRs within a Batched CSR;

e) ensure the DCA will validate the format of the CSR, and verify the signature of each Certificate Signing Request in the Batched CSR in turn, in line with Appendix B;

f) ensure that the DCA will process and log any errors, and make available two files for download via the SMKI Portal interface comprising:

i. a .zip file containing the Certificates in Base64 encoded DER format resulting from successfully processed CSRs; and

ii. a .txt file containing a report showing the processed status of each CSR in the Batched CSR, including errors;

g) following the processing of a valid batch of CSRs by the RA, lodge the resulting Device Certificates in the SMKI Repository; and

h) Where a party informs the DCC Service Desk of non-acceptance of a Device Certificate due to the information contained in the resulting Device Certificate being inconsistent with the information submitted in the CSR, the DCC Service Desk must log the details of non-acceptance.

3.1.2.4 Eligible Subscriber Obligations in respect of Batched Device Certificate Signing Requests

Eligible Subscribers for Device Certificates who submit Batched CSRs shall ensure that:

a) they generate the CSR on their system in line with Appendix B of this

document, and Appendix B of the Code’;

b) they create a Zip file containing the individual CSRs and upload the Zip

file to the SMKI Portal interface, formatted in line with Appendix B ;

c) the information contained in the CSR is true and accurate;

d) if an individual CSR within the batch is rejected by the DCC, the Party

must correct the errors and re-submit the CSR. The Party may not need

to instruct the Device to generate a new key pair for the subsequent

CSR depending on the error condition; and

e) on downloading the returned Device Certificates in a .zip file they use


resulting Device Certificates is consistent with the information contained

in the corresponding CSRs;








out above.



3.2 Web Service Interface

The Web Service Interface provides a synchronous mechanism for Parties’ systems to submit individual Device CSRs. The Web Service Interface shall only be accessible to Authorised Subscribers who are Supplier Parties, and the DCC.

The DCC shall provide server and client side credentials for the purpose of mutual authentication. Client side credentials for Parties’ systems shall be issued by the DCC as part of the process set out in the RAPP.

Prior to gaining access to the SMKI Web Service Interface, Parties shall prepare and provide a Certificate Signing Request in electronic form for signature by the SMKI Infrastructure Certificate Authority.

The DCC shall process such Certificate Signing Request submitted by Parties in respect of the Web Services Interface and shall provide:

a) A Certificate issued under the SMKI Infrastructure Certificate Authority enabling authentication to the Web Service Interface which shall be provided in accordance with the RAPP; and

b) A CA/Browser Forum recognised Certificate Authority Root certificate for the purposes of enabling authentication of the Web Service Interface which shall be provided in accordance with the RAPP.

3.2.1 DCC Obligations in respect of the Web Services Interface

The DCC shall provide a Web Service Interface that:

a) uses XML over REST for Device CSR message requests and responses;

b) denies Parties’ systems access to the Web Service Interface without a valid credential;

c) uses the XML Schema for CSR message requests and responses defined in Appendix A;

d) uses the HTTPS protocol, secured by mutually authenticated TLS 1.2, in line

with the cryptographic standards set out in Appendix C..

On submission of a CSR to the Web Service Interface the DCC shall ensure that:

e) the DCA validates the format of the CSR in line with Appendix B of this document, and Appendix B of the Code, and verifies the signature of each Device CSR;

i. should any of the checks fail, an error will be logged and an error

message returned to the Party’s systems.

f) the DCA performs a check to ensure that the DeviceID that is the subject of the request that has been issued with existing Key Agreement and Digital Signature Certificates through the Batch or Ad Hoc CSR process;

i. should the check fail, an error will be logged and an error

message returned to the Party’s systems.

g) Where all checks are successful, the DCA will silently process and return a Device Certificate as part of the Web Service response set out in Appendix A.



h) following the processing of a valid CSR by the RA, the resulting Device Certificate shall be lodged in the SMKI Repository; and

i) upon non-acceptance of a Device Certificate by a Party due to the information contained in the resulting Certificate being inconsistent with the information contained in the CSR, and subsequent notification to the DCC Service Desk of the non-acceptance, the DCC shall log the non-acceptance.

3.2.2 Eligible Subscriber Obligations in respect of the Web Service Interface

Eligible Subscribers wishing to use the Web Service Interface shall ensure that:

a) they shall ensure that Web Service Interface credentials are used to mutually

authenticate in line with the standards set out in Appendix C.

b) the TLS session renegotiation timeout shall be set to 5 minutes on their client

system.

c) CSR messages shall be generated in the format defined in GBCS, and

submitted using the XML Schema set out in Appendix A ;

d) the information contained in the submitted CSR is true and accurate;

e) they use reasonable endeavours to establish that the information contained in

the returned Device Certificate is consistent with the information contained in

the corresponding CSR;

i. should there be an inconsistency, the Party shall follow the steps set

out in Section 3.4



3.3 SMKI Portal interface via the Internet

The SMKI Portal interface via the Internet provides an asynchronous mechanism for Authorised Responsible Officers acting on behalf of Parties not accessing the SMKI Service through the DCC Gateway to submit Ad Hoc Organisation CSRs, and Device CSRs in Batched or Ad Hoc form. The SMKI Portal interface via the Internet will be accessed over a secured Internet connection using a browser.

The DCC shall ensure that the SMKI Portal interface via the Internet:

a) uses the HTTPS protocol, secured by mutually authenticated TLS 1.2 in line with the cryptographic standards set out in Appendix C.

b) uses Javascript, Cascading Style Sheets (CSS) and images;

c) ensure that the SMKI Portal interface is compliant with the W3C Web Content Accessibility Guidelines (v2) at “AA” level;

d) denies access to the SMKI Portal via the Internet without a valid credential.

e) Provides a download link to a zip file containing the base set of Organisation Certificates and OCA Certificates required to populate device anchor slots prior to installation; and

f) Provides OCA and DCA Certificates for download for Certificate validation purposes.

3.3.1 Organisation Certificate Signing Requests

3.3.1.1 DCC Obligations in respect of Organisation Certificates

The DCC shall:

a) [ensure that the Party that submitted the CSR is an Eligible Subscriber for the Certificate that is the subject of the CSR];

b) validate the format, and verify the signature of the Certificate Signing Request in line with Appendix B of this document, and Appendix B of the Code;

c) either accept and submit CSR to the RA for approval, or reject the CSR; and;

d) notify the Party of either;

i. approval of the CSR; or

ii. the reasons for the rejection of the CSR.

e) upon receipt of the CSR by the RA from the OCA, the RA will verify the content of the CSR;

f) where appropriate notify the Party of the reasons for the rejection of the CSR.

g) Upon approval by the RA, ensure that the CSR is processed, the resulting Certificate lodged in the SMKI Repository, and that the Certificate is also made available for download via the SMKI Portal interface via DCC Gateway; and



h) upon rejection of an Organisation Certificate by a Party and subsequent notification to DCC of the rejection, the DCC shall revoke the Organisation Certificate, and place the Organisation Certificate on the CRL.

3.3.1.2 Eligible Subscriber Obligations in respect of Organisation Certificates


a) they shall generate the CSR in line with Appendix B of this document,

and Appendix B of the Code;


on the SMKI Portal interface formatted in line with Appendix B ;

c) the information contained in the submitted CSR is true and accurate;

d) if the CSR is rejected by the DCC, the Eligible Subscriber must correct

the errors and re-submit the CSR. The Eligible Subscriber may not need

to generate a new key pair;

e) they use reasonable endeavours to establish that the information

contained in the resulting Certificate is consistent with the information

contained in the CSR;

i. should there be an inconsistency, the Eligible Subscriber shall

notify the DCC Service Desk;




out above.

3.3.2 Device Certificate Signing Requests

3.3.2.1 DCC Obligations in respect of Ad Hoc Device Certificate Signing Requests

The DCC shall:

a) [ensure that Parties are eligible to subscribe for the Certificate that is the subject of the CSR];

b) upon receipt of the CSR, the DCA will validate the format, and verify the signature of the Certificate Signing Request in line with Appendix B;

c) either accept and submit CSR to the RA for approval, or reject the CSR;

d) where appropriate notify the User of the reasons for the rejection of the CSR;

e) following the processing of a valid CSR by the RA, the resulting Certificate shall be lodged in the SMKI Repository, and the Certificate



shall be made available for download from the SMKI Portal for Users in Base64 encoded DER format;

3.3.2.2 Eligible Subscriber Obligations in respect of Ad Hoc Device Certificate Signing Requests


a) they shall generate the CSR in line with Appendix B;

b) they shall copy and paste the output of the CSR into the Certificate

Signing Request form on the SMKI Portal for Users;

c) the information contained in the CSR is true and accurate; and

d) if the CSR is rejected by the DCC, the Party must correct the errors and

re-submit the CSR. The Party does not need to instruct the Device to

generate a new key pair and subsequent CSR;

3.3.2.3 DCC Obligations in respect of Batch Device Certificate Signing Requests

The DCC shall ensure that:

a) Parties are eligible to subscribe for the Batch of CSRs;

b) upon receipt of the Batch, the DCA will validate that the number of CSRs contained within the Batch is less than or equal to 50,000;

i. should the Batch contain more than 50,000 CSRs, the DCC shall reject the Batch and notify the User accordingly;

ii. Should the Batch contain less than or equal to 50,000 CSRs, the Batch is submitted to the Registration Authority queue.

c) the DCC informs the User of the number of CSRs submitted within each Batch;

d) the RA will approve the Batch of CSRs in accordance with (a);

e) the DCA will validate the format, and verify the signature of each Certificate Signing Request in the Batch in line with Appendix B and Appendix B of the Code, in turn;

f) the DCA will silently process and log any errors, and make available two files for download via the SMKI Portal for Users comprising:

i. a .zip file containing the Certificates in Base64 encoded DER format resulting from successfully processed CSRs; and

ii. a .txt file containing a report showing the processed status of each CSR in the Batch, including errors;

g) following the processing of a valid Batch by the RA, the resulting Certificates shall be lodged in the SMKI Repository; and

h) upon non-acceptance of a Certificate by an Eligible Subscriber due to the information contained in the resulting Certificate being inconsistent with the information contained in the CSR, and subsequent notification to the DCC Service Desk of the non-acceptance, the DCC shall log the non-acceptance.



3.3.2.4 Eligible Subscriber Obligations in respect of Batched Device Certificate Signing Requests


a) they shall generate the CSRs in line with Appendix B, and Appendix B of

the Code;

b) the information contained in the CSR is true and accurate;

c) they shall upload to the SMKI Portal via the Internet their Batch of CSRs

in a file in.zip format , and;

d) if the Batch is rejected by the DCA because it contains more than 50,000

CSRs, the Party must re-submit the CSRs in Batch files containing no

more than 50,000 CSRs. The Party does not need to instruct the

Devices to generate new key pairs and subsequent CSRs;

e) on downloading the returned Certificates in a .zip file they use


resulting Certificates is consistent with the information contained in the

CSRs;

i. should there be an inconsistency, the Eligible Subscriber shall

notify the DCC Service Desk; and

f) if any Certificate in the .zip file is not accepted by the Eligible Subscriber,

the Eligible Subscriber shall instruct the Device in question to generate a

new key pair and submit the resultant CSR.

3.4 Additional Obligations in respect of Device Certificates

The DCC shall not, other than in the exceptional circumstances identified below, issue more than one hundred (100) Device Certificates for the same Device ID.

Should a CSR be submitted which would cause this number to be exceeded, the DCC shall ensure that an appropriate error message is returned to the Party who submitted the CSR through the interface used to submit the CSR.

If a Party should request Device Certificates after 100 Device Certificates have been issued in relation to a Device ID, the CSR will not be processed, and the Party they should contact the DCC Service Desk in order to review with the Device Registration Authority the threshold applying in relation to the particular Device ID such that additional Device Certificates may be issued in relation to it.

In respect of Eligible Subscribers’ acceptance of Device Certificates, Eligible Subscribers shall ensure that:

a) they use reasonable endeavours to establish that the information contained in

the resulting Certificate is consistent with the information contained in the

CSR submitted by the Party;



a. should there be an inconsistency, the Party shall reject the Certificate

and notify the DCC Service Desk as to the reason for rejection;

b) Upon rejection of a Certificate, if the Party wishes to be issued with new

Certificates for that Device, they shall instruct the Device to generate a new

key pair, resulting in the submission of a new CSR in line with the process

above; and

c) If a Certificate is not accepted in line with L11.4 of the Code, the Subscriber

shall immediately notify the DCC via the DCC Service Desk.

Unless an Eligible Subscriber immediately notifies the DCC of Certificate rejection it is deemed to be accepted;

3.5 Availability and Service Continuity

The DCC shall ensure that the Uniform Resource Locators (URLs) and Internet Protocol (IP) address of the SMKI Service Interfaces shall remain unchanged in the event of the failure of an SMKI Interface component, or invocation of business continuity or disaster recovery measures. DR systems are functionally identical to the main Interface.

3.6 Auditing

All processes and communications will be logged in line with the requirements of the Code.

3.7 Error Handling

Error codes and examples of error messages in relation to the Web Service Interface are detailed in Appendix A.

Error codes and messages in relation to the SMKI Portal interface will be set out in the SMKI User Guide.



Appendix A Schema

This section specifies the XML schema that will be used to verify the contents for the web service request and response messages, as per the figures below.

The Web Service Interface version will be specified in the URL, the schema filename and data contained in the XML requests and responses. The web service interface version allowed value will be hardcoded in the schema.

There will be a different end point for each version of the Web Service interface. Different versions will be supported on separate URLs.

<?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xsd:element name="DeviceCertificateSigningResponse"> <xsd:complexType> <xsd:sequence> <xsd:element name="Version"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:enumeration value="1.0"/> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="Build" type="xsd:string" nillable="false" /> <xsd:element name="TransactionId" type="xsd:positiveInteger" nillable="false"/> <xsd:element name="Status" nillable="false"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:enumeration value="SUCCESS"/> <xsd:enumeration value="DUPLICATE"/> <xsd:enumeration value="UNKNOWN_DEVICE"/> <xsd:enumeration value="CA_ERROR"/> <xsd:enumeration value="CSR_ERROR"/> <xsd:enumeration value="FORMAT_ERROR"/> <xsd:enumeration value="WORKFLOW_ERROR"/> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:choice> <xsd:element name="Certificate" type="xsd:base64Binary" nillable="true"/> <xsd:element name="Error"> <xsd:complexType> <xsd:sequence> <xsd:element name="ErrorCode" nillable="false"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:minLength value="1"/> <xsd:maxLength value="10"/> <xsd:pattern value="[A-Z]{2}:[A-Za-z0-9]+"/> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="ErrorText" type="xsd:string" nillable="false"/> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:choice> </xsd:sequence>



<xsd:attribute name="ID" use="optional"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:minLength value="1"/> <xsd:maxLength value="32"/> </xsd:restriction> </xsd:simpleType> </xsd:attribute> </xsd:complexType> </xsd:element> <xsd:element name="DeviceCertificateSigningRequest"> <xsd:complexType> <xsd:sequence> <xsd:element name="Version"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:enumeration value="1.0"/> </xsd:restriction> </xsd:simpleType> </xsd:element> <xsd:element name="CertificateSigningRequest" nillable="false"> <xsd:simpleType> <xsd:restriction base="xsd:base64Binary"/> </xsd:simpleType> </xsd:element> </xsd:sequence> <xsd:attribute name="ID" use="required"> <xsd:simpleType> <xsd:restriction base="xsd:string"> <xsd:minLength value="1"/> <xsd:maxLength value="32"/> </xsd:restriction> </xsd:simpleType> </xsd:attribute> </xsd:complexType> </xsd:element> </xsd:schema>



Web Service Messages

Example: Device Certificate Signing Request Message

The following message is used to request a device certificate from SMKI.

Device Certificate Signing Request: Element Table Element Name Description

DeviceCertificateSigningRequest The root element

Version This element contains the version of the web service interface. In the above schema this value is set to “1.0”

CertificateSigningRequest This element contains the Base64 encoded PKCS#10 certificate signing request (CSR) without whitespace. Base64 is defined by “Standard ‘base64’ in RFC4648 section 4”. The CSR shall NOT use PEM headers. E.g. -----BEGIN CERTIFICATE REQUEST---- and -----END CERTIFICATE REQUEST----- or -----BEGIN NEW CERTIFICATE REQUEST----- and -----END NEW CERTIFICATE REQUEST-----

Device Certificate Signing Request: Attribute Table Attribute Name Description

ID The client reference to the request. This value will be returned in the response unless the original request is incorrectly formed.

Host: localhost:8080 Content-Length: 439 User-Agent: Jakarta Commons-HttpClient/3.0.1 Content-Type: application/xml;charset=UTF-8 <?xml version="1.0” encoding=”utf-8”?> <DeviceCertificateSigningRequest ID="clientId1"> <Version>1.0</Version>

<:CertificateSigningRequest>MIIBDTCBtAIBADAAMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEzg8s5FYCzGvCzb3hC4KAiNOfBKHmBBhqOIEI+Wn0mrWNu1exXBzPx6Vjy2r

OP7aTxWSVSSnUXkv8s5cLwYOsHqBSMFAGCSqGSIb3IACy52PPLM8E47WpP9bF0QHh

tMdD+SNHXESeEHULdtQN</CertificateSigningRequest> </DeviceCertificateSigningRequest>



Example: Device Certificate Signing Response Message –

Success

The following message is returned in response to Device Certificates Signing Request when SMKI has successfully issued a Device Certificate.

HTTP/1.1 200 OK Date: Tue, 13 May 2014 12:15:58 GMT Content-Length: 362 Content-Type: application/xml;charset=UTF-8 Server: Apache-Coyote/1.1 <?xml version="1.0” encoding=”utf-8”?> <DeviceCertificateSigningResponse ID="clientid1"> <Version>1.0</Version> <Build>1.1.4</Build> <TransactionId>12345</TransactionId> <Status>SUCCESS</Status>

<Certificate>MIAGCSqGSIb3DQEHAqCAMIACAQExADALBgkqhkiG9w0BBwGggDCCBOIwggPKoAMCAQICECMPM8T/FKSR1uB1XoOIkN8wDQYJKoZIhvcNAQELBQAwgZ4xCzAJB

gNVBAYTAkdCMScwJQYDVQQKEx5Ccml0aXNoIFRlbGVjbbKDoCT+vhaRRaRCwKEI41

cKlx9gFb096Pxk7wDeG4N04VTP1sLyJ8MTOE7ZvRYvGwnDu2IG+Gew0NgK8o7AAbs

ZYfDEAADEAAAAAAAAA</Certificate> </DeviceCertificateSigningResponse>




Incorrect XML

The following message is returned in response to invalidly formed Device Certificate Signing Request. In this scenario SMKI is unable to return the client supplied ID field.

HTTP/1.1 200 OK Date: Tue, 13 May 2014 12:15:58 GMT Content-Length: 362 Content-Type: application/xml;charset=UTF-8 Server: Apache-Coyote/1.1 <?xml version="1.0” encoding=”utf-8”?> <DeviceCertificateSigningResponse> <Version>1.0</Version> <Build>1.1.4</Build> <TransactionId>12344</TransactionId> <Status>FORMAT_ERROR</Status> <Error> <ErrorCode>FM:123</ErrorCode> <ErrorText>An XML format error</ErrorText> </Error> </DeviceCertificateSigningResponse>




Other error.

The following message is returned in response to Device Certificates Signing Request when SMKI failed to issue a Device Certificate.

Device Certificate Signing Response: Element Table Element Name Description

DeviceCertificateSigningResponse The root element

Version This element contains the version of the web service interface. In the above schema this value is set to “1.0”

Build This element specifies the software build of the web service.

TransactionId This is the SMKI internal reference to the request.

Status This element reports on the condition of the response. See the section “Response Status”

Certificate This element contains a Base64 encoded DER X509v3 certificate without whitespace and PEM headers. Base64 is defined by “Standard ‘base64’ in RFC4648 section 4”.

Error Container for ErrorCode and ErrorText

ErrorCode This element holds an internal reference code to a specific error occurrence. See the section “Response Status”

ErrorText This element holds a human readable error string corresponding to the ErrorCode. See the section “Response Status”

3.7.1 Device Certificate Signing Response: Attribute Table Attribute Name Description

ID This holds the client reference to the original request.

HTTP/1.1 200 OK Date: Tue, 13 May 2014 12:15:58 GMT Content-Length: 362 Content-Type: application/xml;charset=UTF-8 Server: Apache-Coyote/1.1 <?xml version="1.0” encoding=”utf-8”?> <DeviceCertificateSigningResponse ID="clientid1"> <Version>1.0</Version> <Build>1.1.4</Build> <TransactionId>12345</TransactionId> <Status>CSR_ERROR</Status> <Error> <ErrorCode>CR:9999</ErrorCode> <ErrorText>Request for duplicate certificate not permitted</ErrorText> </Error> </DeviceCertificateSigningResponse>



Response Status Value Error Code Description

SUCCESS n/a This value indicates a certificate has been generated and is returned in the response.

UNKNOWN_DEVICE UD:<Value> The request has been rejected. The device has not had a device certificate previously and hence the request to replace an existing certificate is not valid.

ISSUANCE_ANOMALY CA:<Value> The request has been rejected. A certificate issued from the submitted CSR would result in unexpected issuance behaviour. Manual action by the DCC RA team would need to be taken to allow a future submission of this CSR to result in a certificate.

CSR_ERROR CR:<Value> The request has failed. This is due to a corrupt CSR or incorrect CSR format. The client should correct the mistake and re-submit the error.

CA_ERROR CA:<Value> The request has failed. An internal error has prevented the CA from issuing the certificate. Re-submission may fix this issue.

FORMAT_ERROR FM:<Value> The request has failed. This is due to the request XML format error. The client should correct the mistake and re-submit the error.

WORKFLOW_ERROR WF:<Value> The request has failed. A workflow error has prevented to issuance of the certificate. Re-submission is unlikely to remedy this issue and should report the error code to the DCC helpdesk.


Appendix B Certificate Signing Request Structure

Information to be contained within an Organisation CSR

Section Attributes Value

Version Version 0

Subject Organisation

(id-at-organizationName)

Organisation Trading Name

Organisational Unit

(id-at-organizationalUnitName)

Remote Party Role Code of the Subject of the Certificate

Subject Unique Identifier

(id-at-uniqueIdentifier)

The 64 bit Entity Identifier of the subject of the Certificate

Subject Public Key Information

Public Key Algorithm id-ecPublicvKey

Prime256r1 (256 bit) Public Key Value

Key Usage Criticality True

Key Usage digitalSignature

or

keyAgreement

Signature Algorithm

ecdsa-with-SHA256


Information to be contained within a Device CSR

Section Attributes Value

Version Version 0

Subject Empty

Subject Public Key Information

Public Key Algorithm id-ecPublicvKey

Prime256r1 (256 bit) Public Key Data

Key Usage Criticality True

Key Usage digitalSignature

or

keyAgreement

Subject Alternative Name

General Name

Other Name

id-on-hardwareModuleName

hwType OID (to be determined by DCC)

hwSerialNum

Device ID (EUI-64)

Signature Algorithm

ecdsa-with-SHA256

CSR forms submitted to the SMKI Portal for Users, and SMKI Portal for non-Users will be accepted in PKCS#10 format Base64 encoded.

The standard format will be ASN.1 DER, including either styles of PEM header (i.e. -----BEGIN CERTIFICATE REQUEST----- and -----END CERTIFICATE REQUEST----- or -----BEGIN NEW CERTIFICATE REQUEST----- and -----END NEW CERTIFICATE REQUEST----- )

The following variants will also be accepted:

a) No PEM headers

b) Base64 all in one line

c) Base64 with line breaks at 64 or 76 characters

d) If line breaks are used the \n and \r\n are both acceptable


Format of Batched Certificate Signing Requests

The format that shall be used for .zip files is defined in Info-ZIP application note 970311.

Request File

The format of the batch request is a ZIP archive containing up to 50,000 individual

files with a “csr” extension, which must be in the following format:

a) Each of these files must be uniquely named in the root level of the archive;

b) The individual files must contain a Base64 (as defined by RFC 4868

Section 4) encoded PKCS#10 certificate signing request; and

c) The name of the individual request files is preserved within the SMKI

workflow, excluding the “csr” extension. This name is used in the

generation of the response ZIP archive.

Response File

The “Response File” is a ZIP archive containing all certificates from the request

which have been issued, in the following format:

a) Certificates will be in Base64 encoded X.509 format;

b) The filename is that of the request ZIP file with “-response” appended, and

issued certificates are stored in the root level of the archive;

c) The certificate names are the same as their corresponding request files,

but with the “crt” rather than “csr” extension.


Appendix C Authentication Credentials

The SMKI Portal for Users and Web Service Interface shall use server and client certificates with the following cryptographic properties:

Criteria Version

Protocol TLS1.2*

Protocol Encryption Algorithm

AES256

Client Certificate Key RSA 2048 bit

Client Certificate Hash Algorithm

SHA256

Server Certificate Key RSA 2048 bit

Server Certificate Hash Algorithm

SHA256

* TLS 1.2 should be implemented in accordance with Java and Apache standards. Java 7 and above supports TLS1.2. The TLS version is specified in the HTTP client protocol initialisation. To enable AES256,the Java runtime should be patched with “JCE Unlimited Strength Jurisdiction Policy Files” for the version of Java being used. This is obtained from the public Oracle Java download web pages.

The SMKI Apache web daemons will support “TLS1.2/AES256/SHA2” and above only.


Appendix D Glossary

Term Meaning as defined in SEC

Ad Hoc Certificate Signing Request

Has the meaning given to that expression in SEC Section L8.2 (SMKI Services: Target Response Times).

AES Advanced Encryption Standard

Batched Certificate Signing Request

Has the meaning given to that expression in SEC Section L8.2 (SMKI Services: Target Response Times).

Command Means a communication to a Device in the format required by the GB Companion Specification.

DCA Certificate Has the meaning given to that expression in Annex A of the Device Certificate Policy.

DCC Data Communications Company

DCC Gateway Connection

Means the DCC-provided connection for the purposes of communication with the DSP and TSP

DSP Data Service Provider

EUI-64 Means a 64-bit globally unique identifier governed by the Institute of Electrical and Electronics Engineers.

GBCS Great Britain Companion Specification

HSM Hardware Security Module

In-Use A valid Certificate that has not been revoked, expired, or operationally superseded and which the device has acknowledged as being successful installed/updated

Key Pair Means a Private Key and its mathematically-related Public Key, where the Public Key may be used to Check Cryptographic Protection in relation to a communication that has been Digitally Signed using the Private Key.

Known Remote Party

Has the meaning given to that expression in GBCS

MAC Message Authentication Code

Message Authentication Code

Has the meaning given to that expression in GBCS Companion Specification.

Organisation Certificate Policy

Means the SEC Subsidiary Document of that name set out in Appendix B of the SEC



One Way Authentication

Means the industry standard terminology for HTTPS whereby the client is not required to authenticate with a client credential.

PMA Policy Management Authority

PKI Client Means client software which supports authentication of Authorised Responsible Officers

Portal Portal is a generic term in the SMKI SEC Documents. It refers to a web-based interface, within which there may be multiple views, depending on the permissions of the individual accessing it.

Root CA The offline Certificate Authority used to sign issuing authority certificates

Root OCA Certificate

Has the meaning given to that expression in the SMKI Organisation Certificate Policy

SEC Smart Energy Code

Shared Secret Means a parameter that is (or may be) derived from a Private Key and a Public Key which are not from the same Key Pair in accordance with the GB Companion Specification.

Smart Meter means either an Electricity Smart Meter or a Gas Smart Meter (as the context requires).

SMKI Smart Meter key Infrastructure

SMKI Services Has the meaning given in Section L3.1 of the SEC

SMKI PMA Means the Sub-Committee of that name established pursuant to Section L1 (SMKI Policy Management Smart Energy Code Stage 23: Consultation Version 58 Authority).

SMKI Portal ‘Portal’ is a generic term in the SMKI environment: the portals for the OCA and DCA exist as separate URLs within the primary SMKI Portal with security applied in line with the ARO’s role.

Symmetric Key means any key derived from a Shared Secret in accordance with the GB Companion Specification

Web Service Interface

The system-to-system interface provided to the SMKI for the purposes of SMKI Subscribers refreshing Device Certificates following a Device CSR for the respective Device being approved through a Batch or Ad Hoc CSR to



the SMKI Portal.