V (Normative)  HTTP Profiling |R15|  Word‑p. 961

V.1  Scope

The present annex defines the HTTP messages and data types sent over reference points specified in the present document.

V.2  Ms reference point

V.2.1  General

For the Ms reference point HTTP 1.1 as specified in RFC 2616 shall be used.

The Ms reference point is used to request signing of an Identity header field or request verification of a signed identity in an Identity header field.

HTTP POST method is used for the verification request.

HTTP 200 (OK) is used when the server has succesfully processed the verification request.

HTTP POST method is used for the signing request.

HTTP 200 (OK) is used when the server has succesfully processed the signing request.

HTTP POST method is used for the diversion signing request.

HTTP 200 (OK) is used when the server has succesfully processed the diversion signing request.

Figure V.2.1-1: Usage of the Ms reference point

V.2.2  Resource structure

API resources are defined with respect to a "server root". The server root is a URI:

• {hostname}:{port}/{RoutingPath},

The resource URI structure is:

Figure V.2.2-1: Resource structure for the resource exposed over the Ms reference point

Table V.2.2-1: Variables for the server root

Variable

Description

Presence

---

hostname

Host name used to reach the resource.

M

port

Port where the resource is reached

M

RoutingPath

Path identifying the resource

M

---

V.2.3  Request requirements  Word‑p. 962

V.2.3.1  General

V.2.3.2  Request header requirements

Table V.2.3.2-1 lists reqest header field requirements.

Table V.2.3.2-1: Header fields included in the requests

Header field name

Description

Presence

---

Content-Type

Describes the format of the request body. Shall be set to "application/json"

M

Accept

Describes the supported format of the response body. Shall be set to "application/json" if present

O

---

V.2.4  Response requirements  Word‑p. 963

V.2.4.1  General

V.2.4.2  Response header requirements

Table V.2.4.2-1: Header fields included in the responses

Header field name

Description

Presence

---

Content-Type

Describes the format of the response body. Shall be set to "application/json"

M

---

V.2.4.3  Error response requirements

V.2.4.3.1  General

If the server cannot process the request, the server provides an HTTP error response. The error response contains JSON object specifying the error type.

The server provides a service error when the server is unable to process the request.

The server provides a policy error when the server is able to process the request, but not able to complete the service execution due to a policy restriction.

V.2.4.3.2  Service errors  Word‑p. 964

Table V.2.4.3.2-1: Service failure descriptions

Exception ID

Exception text

HTTP status code

Exception variables

Description

---

-

Error: Missing request body.

400

-

The request could not be processed due to missing request body.

-

Error: Missing mandatory parameter.

400

-

The request could not be processed due to missing parameters.

-

Error: Requested response body type is not supported.

406

-

The request could not be processed due to a not supported message body format.

-

Error: Requested resource not found.

404

-

The request could not be processed due to no resource available related to the Request-URI

-

Error: Unsupported request body type.

415

-

The request could not be processed due to not supported message body.

-

Error: Invalid parameter value.

400

-

The request could not be processed due to invalid parameter value.

-

Error: Failed to parse message body.

400

-

The request could not be processed due to failure to parse the message body.

-

Error: Missing mandatory Content-Length headers

411

-

The request could not be processed due to a missing Content-Length header.

---

V.2.4.3.3  Policy errors

Table V.2.4.3.3-1: Policy failure descriptions

Exception ID

Exception text

HTTP status code

Exception variables

Description

---

-

Method not allowed

405

-

The resource was invoked with unsupported operation

-

Internal server error.

500

-

The request failed due to internal error

---

V.2.5  signing

V.2.5.1  General

To get an asserted identity signed the client sends an HTTP POST request towards the signing server containing a PASSporT SHAKEN object, specified in RFC 8588. The received signingResponse contains for successful requests the signed Identity header field value in a JSON object. Unsuccesful requests are responded with an HTTP 4xx or 5xx response.

V.2.5.2  Data types

Table V.2.5.2-1 specifies the data types included in the signing request. The signing request contains either the claims included in a PASSporT SHAKEN JSON Web Token, specified in RFC 8588, or a PASSporT div JSON Web Token specified in draft-ietf-stir-passport-divert [265].

Table V.2.5.2-1: Data types for the signingRequest

Parameter

Type; Value

Presence

Description

---

attest

string; "A", "B" or "C"

O

Identifying the relation between the service provider attesting the identity and the subscriber. Specified in RFC 8588.

dest

array of identity claim JSON objects representing destination identities; tn or uri

M

Identifying the called user taken from the To header field for a PASSporT SHAKEN Token, and from the Request-URI for a PASSporT div Token. Specified in RFC 8225.

div

identity claim JSON object, tn or uri. A hi element should be included.

O

Identifying the diverting user, taken from the corresponding Identity header field as pecified in draft-ietf-stir-passport-divert [265].

iat

integer; time and date of issuance of the PASSporT token

M

Time since 1 January 1970 in Numeric Date format as specified in RFC 7519.

orig

identity claim JSON object; tn or uri

M

Identifying the calling user. Specified in RFC 8225.

origid

String; UUID

O

Specified in RFC 8588

---

Table V.2.5.2-2 further specifies the data types contained in the signing request parameters.

Table V.2.5.2-2: Data types for the signingRequest parameters

Parameter

Type; Value

Presence

Description

---

hi

string. An "index" header field parameter as specified in RFC 7044

O

The "index" header field parameter is included in the entry identifying the diverting user in the History-Info header field.

tn

string; allowed characters as for local-number-digits and global-number-digits defined in RFC 3966 [22]

M

The number needs to be canonicalized by the server following the procedure in RFC 8224.

uri

string; A SIP URI as specified in RFC 3261 following the generic guidelines in RFC 3986.

O

Used if the "orig" or "dest" is given in a SIP URI.

---

Table V.2.5.2-3 specifies the data types included in the signing response.

Table V.2.5.2-3: Data types for the signingResponse

Parameter

Type; Value

Presence

Description

---

identityHeader

string; Identity header field value as specified in RFC 8224

M

This string cannot be NULL

---

V.2.6  verification  Word‑p. 966

V.2.6.1  General

To get a received identity verified the client sends an HTTP POST request towards the verifications server containing a PASSporT object, including an identity claim with the contents of the received Identity header field signing the originating identity and optionally all the Identity header fields signing diverting identities. The received verificationResponse contains the outcome of the verification in a verstat claim with values as specified for the verstat tel URI parameter in subclause 7.2A.20. Unsuccesful requests are responded with an HTTP 4xx or 5xx response.

V.2.6.2  Data types

Table V.2.6.2-1 specifies the data types included in the verification request.

Table V.2.6.2-1: Data types for the verificationRequest

Parameter

Type; Value

Presence

Description

---

identityHeader

string; Identity header field value for the originating identity as specified in RFC 8224

M

This string cannot be NULL

IdentityHeaders

array of string; Identity header field values as specified in RFC 8224. One identityHeader claim per received Identity header field is sent

O

Identity headers containing the div claims to be verified.

to

String; identity claim JSON object; tn or uri

M

The destination identity taken from the To header field. Used when no div claim is included.

dest

string; identity claim JSON object; tn or uri

O

The destination identity taken from the R-URI in the incoming request. Used when div claim is included.

time

integer; Numeric date format defined in RFC 7519

M

Time based on the Date header field in the incoming request.

from

string; identity claim JSON object; tn or uri

M

The asserted identity, taken from the P-Asserted-Identity or the From header field of the incoming request

---

Table V.2.6.2-2 specifies the data types included in the verification response.

Table V.2.6.2-2: Data types for the verificationResponse

Parameter

Type; Value

Presence

Description

---

divResult

array of one or more [div, verstatValue] tuples

O

Parameter informing of the result of the verification of diverting identities. For each verified identity the verstat parameter is added to the verified identity.

verstatValue

string; set to a value defined in table 7.2A.20.3-1

M

Parameter informing of the result of the verification of originating identity. To be used in the verstat parameter added to the verified identity.

---

---