Tech-invite3GPPspaceIETFspace
21222324252627282931323334353637384‑5x

Content for  TS 24.229  Word version:  18.4.0

Top   Top   Up   Prev   Next
1…   3…   4…   4.5…   5…   5.1.1.4…   5.1.2…   5.1.4…   5.2…   5.2.3…   5.2.6…   5.2.7…   5.3…   5.4…   5.4.1.2.2…   5.4.1.3…   5.4.2   5.4.3…   5.4.3.3…   5.4.4…   5.5…   5.7…   5.7.2…   5.8…   5.11…   6…   6.6…   7…   7.2A…   7.2A.6…   7.3…   7.9A…   8…   A…   A.2…   A.2.1.4…   A.2.1.4.7…   A.2.1.4.8…   A.2.1.4.10A…   A.2.1.4.12…   A.2.2…   A.2.2.4…   A.2.2.4.7…   A.2.2.4.8…   A.2.2.4.10A…   A.2.2.4.12…   A.3…   A.3.3…   B…   C…   E…   F…   H…   I…   K…   L…   L.2A…   M…   N…   O…   Q…   R…   S…   U…   U.2A…   V…   W…

 

V (Normative)  HTTP Profiling |R15|p. 986

V.1  Scopep. 986

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

V.2  Ms reference pointp. 986

V.2.1  Generalp. 986

The Ms reference point is used to request signing of an Identity header field or request verification of a signed assertion in an Identity header field.
HTTP POST method is used for the verification request.
HTTP 200 (OK) is used when the AS for verification has successfully processed the verification request.
HTTP POST method is used for the signing request.
HTTP 200 (OK) is used when the AS for signing has successfully processed the signing request.
HTTP POST method is used for the diversion signing request.
HTTP 200 (OK) is used when the AS for signing has successfully processed the diversion signing request.
HTTP POST method is used for the Resource-Priority header field signing request.
HTTP 200 (OK) is used when the AS for signing has successfully processed the Resource-Priority header field signing request.
HTTP POST method is used for the Resource-Priority and Priority header fields signing request.
HTTP 200 (OK) is used when the AS for signing has successfully processed the Resource-Priority and Priority header field signing request.
Reproduction of 3GPP TS 24.229, Fig. V.2.1-1: Usage of the Ms reference point
Up

V.2.2  Resource structurep. 987

API resources are defined with respect to a "server root". The server root is a URI:
  • {hostname}:{port}/{RoutingPath},
The resource URI structure is:
Reproduction of 3GPP TS 24.229, Fig. V.2.2-1: Resource structure for the resource exposed over the Ms reference point
Up
Variable Description Presence
hostnameHost name used to reach the resource.M
portPort where the resource is reachedM
RoutingPathPath identifying the resourceM
Up

V.2.3  Request requirementsp. 988

V.2.3.1  Generalp. 988

V.2.3.2  Request header requirementsp. 988

Table V.2.3.2-1 lists request header field requirements.
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
The JSON object in a request starts with the name of the request.
For the signingRequest, the JSON object starts with:
{
   "signingRequest": {
For the verificationRequest, the JSON object starts with:
{
   "verificationRequest": {
Up

V.2.4  Response requirementsp. 988

V.2.4.1  Generalp. 988

V.2.4.2  Response header requirementsp. 988

Header field name Description Presence
Content-Type Describes the format of the response body. Shall be set to "application/json" M
The JSON object in a response starts with the name of the response.
For the signingResponse, the JSON object starts with:
{
   "signingResponse": {
For the verificationResponse, the JSON object starts with:
{
   "verificationResponse": {
Up

V.2.4.3  Error response requirementsp. 989

V.2.4.3.1  Generalp. 989
If the server cannot process the request, the server provides an HTTP error response. The error response contains a 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 errorsp. 989
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 headers411-The request could not be processed due to a missing Content-Length header.
Up
V.2.4.3.3  Policy errorsp. 990
Exception ID Exception text HTTP status code Exception variables Description
-Method not allowed405-The resource was invoked with unsupported operation
-Internal server error.500-The request failed due to internal error
Up

V.2.5  signingp. 990

V.2.5.1  Generalp. 990

To construct a PASSporT SHAKEN object specified in RFC 8588, a PASSporT rph object specified in RFC 8443 and RFC 9027, or a PASSporT div object, specified in RFC 8946, the client sends an HTTP POST request to the AS for signing containing the SIP request information plus any additional claim information to be signed by the target PASSporT type. If the request was successfully processed, then the received signingResponse contains an Identity header field value populated with a signed PASSporT of the requested type along with the appropriate Identity header field parameters.
Unsuccessful requests are responded with an HTTP 4xx or 5xx response.
Up

V.2.5.2  Data typesp. 990

Table V.2.5.2-1 specifies the data types included in the signing request. The signing request contains the claims included in:
  • a PASSporT SHAKEN JSON Web Token, specified in RFC 8588;
  • a PASSporT div JSON Web Token specified in RFC 8946]; or
  • a PASSporT rph JSON Web Token specified in RFC 8443] and RFC 9027.
Parameter Type; Value Presence Description
ppt string; set to the value of the "ppt" parameter in the protected header of the PASSporT to be created O This parameter is included to inform the AS for signing the type of PASSporT that is to be constructed and signed.
attest string; "A", "B" or "C" O Identifying the relation between the service provider attesting the identity and the subscriber. Specified in RFC 8588.
destarray of identity claim JSON objects representing destination identities; tn or uriM Identifying the called user taken from the To header field for a "shaken" or "rph" PASSporT as specified in RFC 8224, and from the Request-URI after retargeting for a "div" PASSporT as specified in RFC 8946.
dividentity claim JSON object, tn or uri. A hi element should be included.O Identifying the diverting user; i.e., the user identified in the Request-URI before retargeting, taken from the History-Info header field as pecified in RFC 8946.
iatinteger; time and date of issuance of the PASSporT tokenM Time since 1 January 1970 in Numeric Date format as specified in RFC 7519.
origidentity claim JSON object; tn or uriM Identifying the calling user. Specified in RFC 8225.
origidString; UUIDO Specified in RFC 8588
rpharray of strings that correspond to the r-values indicated in the SIP Resource-Priority header fieldO Contains assertion of the priority level of the user to be used for a given communication session as specified in RFC 8443 and RFC 9027.
sph string "psap-callback" O Contains header field value "psap-callback" of the SIP Priority header field as specified in RFC 9027
The signing request provides the following two options for identifying the PASSporT type to be constructed:
  • the PASSporT type is indicated by invoking the signing resource associated with that PASSporT type, as defined in subclause V.2.2; or
  • the PASSporT type is identified by including a ppt parameter when invoking the /signing resource defined in subclause V.2.2.
Table V.2.5.2-1a indicates representative signingRequest parameter inclusion rules per PASSporT type.
PASSporT Type Parameter
attest dest div iat orig origid rph sph
shakenMMXMMMXX
divXMMMMXXX
rphXMXMMXMO
NOTE:
"M" means "mandatory", "O" means "optional", and "X" means "not applicable".
Table V.2.5.2-2 further specifies the data types contained in the signing request 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 3966M The number needs to be in canonical form according to Section 8.3 of 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.
NOTE:
The TAS is expected to provide a valid globally routable number.
Table V.2.5.2-3 specifies the data types included in the signing response.
Parameter Type; Value Presence Description
identityHeader string; Identity header field value as specified in RFC 8224MThis string cannot be NULL
Up

V.2.6  verificationp. 992

V.2.6.1  Generalp. 992

To verify one or more received PASSporTs, the client sends a verification request in the form of an HTTP POST request to the AS for verification containing the Identity header field(s) populated with the PASSporT object(s) to be verified. The verification request also contains the following information:
  • the originating identity and optionally all the diverting identities; and/or
  • the Resource-Priority header field value and optionally the header field value "psap-callback" of the Priority header field.
The 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 and in a verstatPriority claim with values as specified for the Priority-Verstat header field in subclause 7.2.21. The verificationResponse can optionally contain the claims of PASSporT(s) that passed verification.
The verificationResponse can also contain verification results information for each verified PASSporT, as follows:
  • if verification passed, then verificationResponse contains the validated claims of the PASSporT;
  • if verification failed, then verificationResponse contains information describing the reason for the failure.
Unsuccessful requests are responded with an HTTP 4xx or 5xx response.
Up

V.2.6.2  Data typesp. 992

Table V.2.6.2-1 specifies the data types included in the verification request.
Parameter Type; Value Presence Description
identityHeader string; Identity header field value for the originating identity as specified in RFC 8224 and RFC 8588M This parameter contains the "shaken" Identity header field value to be verified (see NOTE 1).
identityHeaders array of string; Identity header field values as specified in RFC 8224 , RFC 8443, RFC 8946, RFC 9027. One identityHeader claim per received Identity header field is sent.O This array contains the "div" and "rph" Identity header field values to be verified (see NOTE 2).
tostring; identity claim JSON object; tn or uriMThe destination identity taken from the To header field. Used when no div claim is included.
deststring; identity claim JSON object; tn or uriOThe destination identity taken from the Request-URI in the incoming request.
time integer; Numeric date format defined in RFC 7519MTime based on the Date header field in the incoming request.
fromstring; identity claim JSON object; tn or uriMThe asserted identity, taken from the P-Asserted-Identity or the From header field of the incoming request
protectedHeadersarray of string; header field(s)OContains the SIP header field(s) protected by claims in the PASSporT(s) of the identityHeaders array.
NOTE 1:
For "shaken" PASSporT verification, an identityHeader parameter containing a "shaken" Identity header field shall be included in the verification request.
NOTE 2:
For "rph" PASSporT verification, an identityHeaders parameter containing an "rph" Identity header field shall be included in the verification request. If the identityHeader parameter contains a "shaken" Identity header field, and/or the identityHeaders parameter contains an "rph" Identity header field, then all "div" Identity header field(s) received in an INVITE request shall be included in the identityHeaders parameter of the verification request. If "rph" PASSporT verification is not to be performed, and if the INVITE request does not contain any "div" Identity header fields, then the identityHeaders parameter shall not be included in the verification request.
Invocation of the verification request results in the verification of the Identity header fields in the identityHeader and identityHeaders parameters. In addition, a verification request invocation can verify the integrity of SIP header fields protected by the "div" and "rph" PASSporTs. When verification of SIP header field integrity is required, the protected SIP header field(s) information shall be conveyed in the protectedHeaders parameter.
The dest parameter is included when the verification request includes a div claim, and when the verification service is required to distinguish between a legitimately retargeted request and a maliciously replayed request.
Table V.2.6.2-1a indicates representative inclusion rules for the verification request identityHeader and identityHeaders parameters for the different combinations of PASSporT types to be verified.
PASSporT type(s) to be verified Parameter
identityHeader identityHeaders
shakenMX
shaken, divMM
rphXM
rph, divXM
shaken, rphMM
shaken, rph, divMM
NOTE:
"M" means "mandatory" and "X" means "not applicable".
Table V.2.6.2-2 specifies the data types included in the verification response.
Parameter Type; Value Presence Description
divResultarray of one or more [div, verstatValue] tuplesOParameter 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 OParameter informing of the result of the verification of originating identity. To be used in the verstat parameter added to the verified identity. The parameter is mandatory if the request contained a PASSporT SHAKEN JSON Web Token.
verstatPriority string; set to a value defined in Table 7.2.21-1 O Parameter informing of the result of the verification of the Resource-Priority header field and optionally the header field value "psap-callback" of the Priority header field.
verifyResults array of one or more verifyResult, as defined in Table V.2.6.2-3O Each array entry contains the verification results of a PASSporT contained in the request.
Table V.2.6.2-3 specifies the mandatory data types of the verifyResult parameter included in the verification response.
Parameter Type; Value Presence Description
verifyResultstructured data type containing [ppt, status, validClaims, reasonCode, reasonText, passport] tupleMContains the verification results of a single Identity header field contained in the identityHeader parameter or an entry of the identityHeaders array of the verification request.The ppt and status parameters are always present. The inclusion of the other parameters in the tuple depends on the value of the status parameter.
pptstring, set to the value of the ppt parameter in the protected header of the PASSporT.MIdentifies the type of PASSporT associated with this array entry.
statusString, set to the value pass, fail or none.MIdentifies the verification result of the PASSporT associated with this array entry.
Each verifyResult entry of the verifyResults array conveys the verification results of an Identity header field contained in the identityHeader parameter or contained in an entry of the identityHeaders array of the verification request.
Additional verifyResult parameters are returned based on the value of the status parameter as follows:
  • a status parameter with a value of "fail" returns the parameters shown in Table V.2.6.2-4;
  • a status parameter with a value of "pass" returns the parameter shown in Table V.2.6.2-5; and
  • a status parameter with a value of "none" returns no additional parameters.
A status parameter with a value of "none" indicates that the PASSporT type is not supported.
Table V.2.6.2-4 specifies the optional data types of the verifyResult parameter included in the verification response.
Parameter Type; Value Presence Description
reasonCodeintegerO Identifies the 4xx failure reason code of the failing PASSporT, as defined in RFC 8224.
reasonTextstringO Identifies the failure text associated with the 4xx failure reason code, as specified in RFC 8224.
passportstringOContains the failing PASSporT
NOTE:
These parameters are optional since they are included only when the verifyResult "status" parameter has a value of "fail".
Table V.2.6.2-5 specifies the additional data types included in the verification response when the status parameter contains a value of "pass".
Parameter Type; Value Presence Description
validClaimsJSON objectOThe validClaims parameter contains the payload of the verified PASSporT.
The validClaims parameter can be used:
  • to verify the integrity of SIP header field information associated with the validated claims, where a mismatch results in a verification failure; or
  • to ensure that SIP header field contents contain the information authorized by the validated claims, where a mismatch is resolved by updating the SIP header field to match the validated claims.
Up

Up   Top   ToC