Upload
nguyenminh
View
231
Download
2
Embed Size (px)
Citation preview
SMKI Interface Design Specification
DCC Public Page 2 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
SMKI Interface Design Specification
DCC Public Page 3 of 31
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
SMKI Interface Design Specification
DCC Public Page 4 of 31
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.
SMKI Interface Design Specification
DCC Public Page 5 of 31
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.
SMKI Interface Design Specification
DCC Public Page 6 of 31
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
SMKI Interface Design Specification
DCC Public Page 7 of 31
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;
SMKI Interface Design Specification
DCC Public Page 8 of 31
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;
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; 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;
i. should there be an inconsistency, the Party shall follow the steps
set out in Section 3.4
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;
SMKI Interface Design Specification
DCC Public Page 9 of 31
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
reasonable endeavours to establish that the information contained in the
resulting Device Certificates is consistent with the information contained
in the corresponding CSRs;
SMKI Interface Design Specification
DCC Public Page 10 of 31
i. should there be an inconsistency, the Party shall follow the steps
set out in Section 3.4
f) 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.
SMKI Interface Design Specification
DCC Public Page 11 of 31
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.
SMKI Interface Design Specification
DCC Public Page 12 of 31
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
SMKI Interface Design Specification
DCC Public Page 13 of 31
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
SMKI Interface Design Specification
DCC Public Page 14 of 31
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
Eligible Subscribers shall ensure that:
a) they shall generate the 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 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;
f) 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.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
SMKI Interface Design Specification
DCC Public Page 15 of 31
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
Eligible Subscribers shall ensure that:
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.
SMKI Interface Design Specification
DCC Public Page 16 of 31
3.3.2.4 Eligible Subscriber Obligations in respect of Batched Device Certificate Signing Requests
Eligible Subscribers shall ensure that:
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
reasonable endeavours to establish that the information contained in the
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;
SMKI Interface Design Specification
DCC Public Page 17 of 31
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.
SMKI Interface Design Specification
DCC Public Page 18 of 31
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>
SMKI Interface Design Specification
DCC Public Page 19 of 31
<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>
SMKI Interface Design Specification
DCC Public Page 20 of 31
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>
SMKI Interface Design Specification
DCC Public Page 21 of 31
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>
SMKI Interface Design Specification
DCC Public Page 22 of 31
Example: Device Certificate Signing Response Message –
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>
SMKI Interface Design Specification
DCC Public Page 23 of 31
Example: Device Certificate Signing Response Message –
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>
SMKI Interface Design Specification
DCC Public Page 24 of 31
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.
DCC Public Page 25 of 31
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
DCC Public Page 26 of 31
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
DCC Public Page 27 of 31
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.
DCC Public Page 28 of 31
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.
DCC Public Page 29 of 31
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
DCC Public Page 30 of 31
Term Meaning as defined in 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