6 PKI portal, Ua interface

24.1093GPPBootstrapping interface (Ub) and network application function interface (Ua)Protocol detailsRelease 17TS

6.1 Introduction

3GPP TS 33.221 [4] specifies the enrolment of subscriber certificates and the delivery of CA certificates to the UE. The TS specifies that the authentication of these procedures be based on bootstrapping procedure and more generally on the HTTP Digest authentication as described in clause 5.2 of the present document.

6.2 Subscriber certificate enrolment

The subscriber certificate enrolment procedure contains the following requests:

– an enrolment request in the form of PKCS#10 [16];

– an optional request for WIM specific authentication code for key generation [19]; and

– an optional request for WIM specific authentication code for proof of key origin [19].

Respectively, the subscriber certificate enrolment procedure contains the following responses:

– a subscriber certificate; and

– a WIM specific authentication code [19].

NOTE: The on board key generation and the generation of the proof of key origin requires a WIM specific authentication code. Whether it is, is decided by the issuer of the WIM card.

6.2.1 Enrolment procedure

The UE shall generate a PKCS#10 certification request [16] according to 3GPP TS 33.221 [4]. The UE shall send the PKCS#10 certification request to the PKI portal in the HTTP payload in a HTTP POST request. The Request-URI shall indicate the desired response type. Upon successful enrolment, PKI portal shall return the enrolled subscriber certificate in the desired format.

The UE populates the HTTP POST request as follows:

– the HTTP version shall be 1.1 which is specified in RFC 7230 [30];

– the base of the Request-URI is extracted from the full PKI portal URI (e.g. if the full PKI portal URI is "http://pki-portal.operator.com/enrol" then the Request-URI shall be "/enrol".

NOTE 1: In case a proxy is used between the UE and the PKI portal, then the full Request-URI will be used in the HTTP Post request.

– the Request-URI shall contain an URI parameter "response" that shall be set to "single", "pointer", or "chain" depending on the UE’s desired response type (e.g. Request-URI may take the form of "/enrol?response=single" for certificate delivery);

NOTE 2: The PKI portal might ignore the UE’s desired response type, and the UE should be capable of receiving the issued subscriber certificate in any of the response types.

– the UE may add additional URI parameters to the Request-URI;

NOTE 3: The PKI portal might ignore the additional URI parameters.

– the HTTP header Content-Type shall be "application/x-pkcs10";

– the HTTP header Content-Length shall be the length of the Base64 encoded PKCS#10 certification request in Octets; and

– the HTTP payload shall contain the Base64 encoded PKCS#10 certification request and optionally surrounded by "—– BEGIN CERTIFICATE REQUEST —–" and "—– END CERTIFICATE REQUEST —–" tags;

– the UE may add additional HTTP headers to the HTTP POST request.

The UE sends the HTTP POST request to the PKI portal. The PKI portal checks that the HTTP request is valid, and extracts the Base64 encoded PKCS#10 certification request for further processing. The PKI portal shall verify that the subscriber is authorized to receive the particular type of certificate by checking subscriber’s user security settings received from the BSF as specified 3GPP TS 33.220 [1].

Upon successful subscriber certificate creation procedure, the PKI portal shall return the subscriber certificate to the UE in the UE’s desired format or in the PKI portal’s desired format.

The response format type shall be one of the following:

– the subscriber certificate itself (i.e. desired response type was "single");

– a pointer to the subscriber certificate (i.e. desired response type was "pointer"); or

– a certificate chain that contains full certification chain from subscriber certificate to the root certificate (i.e. desired response type was "chain").

If response format type is "single", the PKI portal shall populate HTTP response as follows:

– the HTTP status code shall be 200;

– the HTTP header Content-Type shall be "application/x-x509-user-cert";

– the HTTP header Content-Length shall be the length of the HTTP payload in octets;

– the HTTP payload shall contain the Base64 encoded subscriber certificate and optionally surrounded by
"—– BEGIN CERTIFICATE —–" and "—– END CERTIFICATE —–" tags;

– the PKI portal may add additional HTTP headers to the HTTP response.

If response format type is "pointer", the PKI portal shall populate HTTP response as follows:

– the HTTP status code shall be 200;

– the HTTP header Content-Type shall be "application/vnd.wap.cert-response";

– the HTTP header Content-Length shall be the length of the HTTP payload in octets;

– the HTTP payload shall contain the Base64 encoded CertResponse structure and optionally surrounded by
"—– BEGIN CERTIFICATE RESPONSE —–" and "—– END CERTIFICATE RESPONSE —–" tags;

– the PKI portal may add additional HTTP headers to the HTTP response.

If response format type is "chain", the PKI portal shall populate HTTP response as follows:

– the HTTP status code shall be 200;

– the HTTP header Content-Type shall be "application/pkix-pkipath";

– the HTTP header Content-Length shall be the length of the HTTP payload in octets;

– the HTTP payload shall contain the Base64 encoded PkiPath structure;

– the PKI portal may add additional HTTP headers to the HTTP response.

The PKI portal shall send the HTTP response to the UE. The UE shall check that the HTTP response is valid, and extract the Base64 encoded subscriber certificate, pointer to the subscriber certificate, or certificate chain for further processing.

An example flow of a successful subscriber certificate enrolment procedure can be found in clause E.3.

6.2.2 WIM specific authentication code for key generation

The UE may be equipped with a WIM which may require an authentication code from WIM provider in order to generate a key onboard WIM as specified in OMA ECMAScript [19] and OMA WPKI [20] specifications. In this case, the UE shall request the authentication code from PKI portal using a HTTP GET request. If the PKI portal can acquire authentication code, it is returned to the UE in the corresponding HTTP response.

The UE populates the HTTP GET request as follows:

– the HTTP version shall be 1.1 which is specified in RFC 7230 [30];

– the base of the Request-URI is extracted from the full PKI portal URI and appended with "/wim-auth-code" (e.g. if the full PKI portal URI is "http://pki-portal.operator.com/enrol" then the Request-URI shall be "/enrol/wim-auth-code");

– the Request-URI shall contain an URI parameter "request" that shall be set to the return value received from the WIM;

NOTE 1: If an authentication code is required, the WIM will return "error:AuthReq:cardSerialNumber:Challenge". The cardSerialNumber and the Challenge are in a hexadecimal format as specified in OMA ECMAScript specification [19].

– the UE may add additional URI parameters to the Request-URI;

– the UE may add additional HTTP headers to the HTTP GET request.

The UE sends the HTTP GET request to the PKI portal. The PKI portal acknowledges that this is an authentication code because the Request-URI contains the "/wim-auth-code" and the URI parameter "request". The PKI portal extracts the authentication code derivation parameters from the URI parameter "request", and derives the authentication code.

NOTE 2: The actual derivation of the authentication code is outside the scope.

Upon successful authentication code derivation, the PKI portal shall return the authentication code to the UE in a HTTP response:

– the HTTP status code shall be 200;

– the HTTP header Content-Type shall be "text/plain";

– the HTTP header Content-Length shall be the length of the HTTP payload in octets;

– the HTTP payload shall contain the authentication code in a hexadecimal format;

– the PKI portal may add additional HTTP headers to the HTTP response.

Upon receiving the authentication code from the PKI portal, the UE shall use it to authenticate the procedure of generating the key onboard the WIM.

6.2.3 WIM specific authentication code for proof of key origin

The UE may be equipped with a WIM which may require an authentication code from WIM provider in order to generate a proof of key origin onboard WIM as specified in OMA ECMAScript [19] and OMA WPKI [20] specifications. In this case, the UE shall request the authentication code from PKI portal using a HTTP GET request. If the PKI portal can acquire authentication code, it is returned to the UE in the corresponding HTTP response.

The procedure to obtain the authentication code for the generation of proof of key origin onboard WIM is the same as for the key generation, and is described in clause D.2.1.

Upon receiving the authentication code from the PKI portal, the UE shall use it to authenticate the procedure generating the proof of key origin onboard the WIM.

6.2.4 Error situations

Subscriber certificate enrolment may not be successful for multiple reasons. The error cases are indicated by using 4xx and 5xx HTTP Status Codes as defined in RFC 7231 [31]. The 4xx status code indicates that the UE seems to have erred, and the 5xx status code indicates that the PKI portal is aware that it has erred. Possible error situations during subscriber certificate enrolment and their mappings to HTTP Status Codes are described in table 6.2.4-1.

NOTE: On the table 6.2.4-1, the "Description" column describes the error situation in PKI portal. The "PKI portal error" column describes the typical reason for the error.

An example flow of a failure in subscriber certificate enrolment procedure can be found in clause E.4.

Table 6.2.4-1: HTTP Status Codes used for enrolment error

HTTP Status Code

HTTP Error

UE should repeat the request

Description

PKI portal error

400

Bad Request

No

Request could not be understood

PKCS#10 request was missing, or malformed

401

Unauthorized

Yes

Request requires authentication (cf. clause 5.2)

Authentication pending, cf. clause 5.2

402

Payment Required

No

Reserved for future use

403

Forbidden

No

PKI portal understood the request, but is refusing to fulfil it

PKCS#10 request was valid, but subscriber is not allowed to enrol this particular type of certificates or PKCS#10 request contained unacceptable parameters

404

Not Found

No

PKI portal has not found anything matching the Request‑URI

The Request-URI was malformed and PKI portal cannot fulfil the enrolment request

405 to 406

*

No

Not used by PKI portal

407

Proxy Authentication Required

Yes

PKI portal uses Authentication Proxy and UE shall authenticate itself with the proxy

Authentication Proxy authentication pending, cf. clause 5.2

408 to 417

*

No

PKI portal should not use these status codes

500

Internal Server Error

No

PKI portal encountered an unexpected error

PKI portal is mis-configured

501

Not Implemented

No

PKI portal does not support the required functionality

The server does not contain PKI portal service

502

Bad Gateway

No

Gateway/Proxy received an invalid response from PKI portal

PKI portal is behind a gateway/proxy and sent an invalid response to the gateway/proxy

503

Service Unavailable

Yes

PKI portal service is currently unavailable

PKI portal is temporarily unavailable, UE may repeat the request after delay indicated by "Retry-After" header

504

Gateway Timeout

No

Gateway/Proxy did not receive a timely response from the upstream server

PKI portal is behind a gateway/proxy and did not send a response to the gateway/proxy in time, or was not reachable by the gateway/proxy

505

HTTP Version Not Supported

No

PKI portal does not support the HTTP protocol version that was used in the request line

UE should use HTTP/1.1 version with PKI portal

6.3 CA certificate delivery

The root certificate delivery procedure contains the following request:

– a CA certificate delivery request;

and the corresponding response:

– the CA certificate.

6.3.1 CA certificate delivery procedure

The UE shall populate the HTTP GET request as follows:

– the HTTP version shall be 1.1 which is specified in RFC 7230 [30];

– the base of the Request-URI is extracted from the full PKI portal URI (e.g. if the full PKI portal URI is "http://pki-portal.operator.com/getcertificate" then the Request-URI shall be "/getcertificate".

NOTE 1: In case a proxy is used between the UE and the PKI portal, then the full Request-URI will be used in the HTTP Post request.

– the Request-URI shall contain an URI parameter "in" that shall be the Base64 encoding of the DER encoded Issuer field of the X.509 certificate;

– the Request-URI may contain an URI parameter "ki" that shall be the Base64 encoding of the DER encoded the Key Identifier of the X.509 certificate;

NOTE 2: Key Identifier of the CA certificate can be obtained from the Authority Key Identifier extension of the subscriber certificate.

– the UE may add additional URI parameters to the Request-URI;

– the UE may add additional HTTP headers to the HTTP GET request.

The UE sends the HTTP GET request to the PKI portal. The PKI portal checks that the HTTP request is valid, and extracts the "in" parameter and optionally "ki" parameter from the Request-URI. If the PKI portal can verify that the Issuer field parameter is valid, and that the UE may set the CA certificate as a root certificate (i.e. trusted CA certificate), it will then send the CA certificate back to the UE in the corresponding HTTP response.

The PKI portal shall populate the HTTP response as follows:

– the HTTP status code shall be 200;

– the HTTP header Content-Type shall be "application/x-x509-ca-cert";

– the HTTP header Content-Length shall be the length of the HTTP payload in octets;

– the HTTP payload shall contain the Base64 encoded CA certificate structure and optionally surrounded by "‑‑‑‑‑ BEGIN CERTIFICATE —–" and "—– END CERTIFICATE —–" tags;

– the PKI portal may add additional HTTP headers to the HTTP response.

The PKI portal shall send the HTTP response to the UE. The UE shall check that the HTTP response is valid, and extract the Base64 encoded CA certificate for further processing. UE shall validate and match the received CA certificate against the parameters supplied in the corresponding request.

An example flow of CA certificate procedure can be found in clause E.5.

6.3.2 Error situations

CA certificate delivery may not be successful for multiple reasons. The error cases are indicates by using 4xx and 5xx HTTP Status Codes as defined in RFC 7231 [31]. The 4xx status code indicates that the UE seems to have erred, and the 5xx status codes indicate that the PKI portal is aware that it has erred. Possible error situations during CA certificate delivery and their mappings to HTTP Status Codes are described in table 6.3.2-1.

NOTE: On the table 6.3.2-1, the "Description" column describes the error situation in PKI portal. The "PKI portal error" column describes the typical reason for the error.

An example flow of a failure in CA certificate delivery procedure can be found in clause E.6.

Table 6.3.2-1: HTTP Status Codes for CA certificate delivery error

HTTP Status Code

HTTP Error

UE should repeat the request

Description

PKI portal error

400

Bad Request

No

Request could not be understood

Request could not be understood

401

Unauthorized

Yes

Request requires authentication (cf. clause 5.2)

Authentication pending, cf. clause 5.2

402

Payment Required

No

Reserved for future use

403

Forbidden

No

PKI portal understood the request, but is refusing to fulfil it

CA certificate delivery request was understood but PKI portal refuses to deliver the CA certificate

404

Not Found

No

PKI portal has not found anything matching the Request-URI

PKI portal does not have the requested CA certificate

405 to 406

*

No

Not used by PKI portal

407

Proxy Authentication Required

Yes

PKI portal uses Authentication Proxy and UE shall authenticate itself with the proxy

Authentication Proxy authentication pending, cf. clause 5.2

408 to 417

*

No

PKI portal should not use these status codes

500

Internal Server Error

No

PKI portal encountered an unexpected error

PKI portal is mis-configured

501

Not Implemented

No

PKI portal does not support the required functionality

The server does not contain PKI portal service

502

Bad Gateway

No

Gateway/Proxy received an invalid response from PKI portal

PKI portal is behind a gateway/proxy and sent an invalid response to the gateway/proxy

503

Service Unavailable

Yes

PKI portal service is currently unavailable

PKI portal is temporarily unavailable, UE may repeat the request after delay indicated by "Retry-After" header

504

Gateway Timeout

No

Gateway/Proxy did not receive a timely response from the upstream server

PKI portal is behind a gateway/proxy and did not send a response to the gateway/proxy in time, or was not reachable by the gateway/proxy

505

HTTP Version Not Supported

No

PKI portal does not support the HTTP protocol version that was used in the request line.

UE should use HTTP/1.1 version with PKI portal