1、 ATIS-1000082 ATIS Standard on Technical Report on SHAKEN APIs for a Centralized Signing and Signature Validation Server Alliance for Telecommunications Industry Solutions Approved May 2018 Abstract This document provides a Technical Report on a SHAKEN APIs used to support a Centralized Signing and
2、Signature Validation Server. These APIs provide a means for multiple and/or disparate network elements to use an HTTP-based RESTful interface to access SHAKEN Signing and Signature Validation servers. ATIS-1000082 ii Foreword The Alliance for Telecommunication Industry Solutions (ATIS) serves the pu
3、blic through improved understanding between providers, customers, and manufacturers. The Packet Technologies and Systems Committee (PTSC) develops and recommends standards and technical reports related to services, architectures, and signaling, in addition to related subjects under consideration in
4、other North American and international standards bodies. PTSC coordinates and develops standards and technical reports relevant to telecommunications networks in the U.S., reviews and prepares contributions on such matters for submission to U.S. International Telecommunication Union Telecommunicatio
5、n Sector (ITU-T) and U.S. ITU Radiocommunication Sector (ITU-R) Study Groups or other standards organizations, and reviews for acceptability or per contra the positions of other countries in related standards development and takes or recommends appropriate actions. The SIP Forum is an IP communicati
6、ons industry association that engages in numerous activities that promote and advance SIP-based technology, such as the development of industry recommendations, the SIPit, SIPconnect-IT, and RTCWeb-it interoperability testing events, special workshops, educational seminars, and general promotion of
7、SIP in the industry. The SIP Forum is also the producer of the annual SIP Network Operators Conference (SIPNOC), focused on the technical requirements of the service provider community. One of the Forums notable technical activities is the development of the SIPconnect Technical Recommendation a sta
8、ndards-based SIP trunking recommendation for direct IP peering and interoperability between IP Private Branch Exchanges (PBXs) and SIP-based service provider networks. Other important Forum initiatives include work in Video Relay Service (VRS) interoperability, security, Network-to-Network Interoper
9、ability (NNI), and SIP and IPv6. Suggestions for improvement of this document are welcome. They should be sent to the Alliance for Telecommunications Industry Solutions, PTSC, 1200 G Street NW, Suite 500, Washington, DC 20005, and/or to the SIP Forum, 733 Turnpike Street, Suite 192, North Andover, M
10、A, 01845. The mandatory requirements are designated by the word shall and recommendations by the word should. Where both a mandatory requirement and a recommendation are specified for the same criterion, the recommendation represents a goal currently identifiable as having distinct compatibility or
11、performance advantages. The word may denotes an optional capability that could augment the standard. The standard is fully functional without the incorporation of this optional capability. The ATIS/SIP Forum IP-NNI Task Force under the ATIS Packet Technologies and Systems Committee (PTSC) and the SI
12、P Forum Technical Working Group (TWG) was responsible for the development of this document. ATIS-1000082 iii Table of Contents 1 Introduction . 1 2 Normative References . 1 3 Definitions, Acronyms, some networks may be IMS-based, and some may not. Furthermore, service providers may determine that th
13、e STI-AS and/or STI-VS functions are better suited to be invoked at points other than the network core, such as at the network edge. The use of SIP as the STI-AS/STI-VS access protocol may not be suitable when initiating authentication and/or verification requests from locations other than an IMS co
14、re. Because of the potential need for a service provider to initiate authentication and verification in multiple networks and/or from different network elements within their infrastructure, it would be beneficial to share a centralized authentication and verification service, calling upon these serv
15、ices from various points within a service providers infrastructure. This technical report describes a means of decomposing the STI-AS and STI-VS functions and exposing a HyperText Transfer Protocol (HTTP)-based RESTful API that can be used to request SHAKEN authentication and verification services.
16、The API can be used by diverse network elements within a service providers network to make SHAKEN authentication and verification requests of shared, centralized Signing and Signature Validation servers. As shown in Figure 4.2, the overall STI-AS functionality is decomposed into two parts: a Signing
17、 server function and an authenticator function. Likewise, the STI-VS is decomposed into a Signature Validation server function and a verifier function. The HTTP-based API is used between the authenticator and Signing server functions and between the verifier and Signature Validation server functions
18、. Figure 4.2 depicts a combined Signing and Signature Validation Server function, but this is optional. The authenticator and verifier functions initiate the signing and validation requests via the API described in this document. The authenticator and verifier functions may be integrated into other
19、network elements or may be developed as stand-alone functions. For example, a stand-alone authenticator function in an implementation of the SHAKEN reference architecture would receive SIP INVITE messages from the CSCF and formulate and send an HTTP signing request to the Signing server per the API
20、described in this document. The Signing server performs the signing/authentication functions and formulates an API response containing an Identity header that the authenticator adds to the SIP INVITE message returned to the CSCF. Alternatively, the authenticator function could be integrated into the
21、 CSCF, whereby the CSCF would directly support the new API. ATIS-1000082 4 Figure 4.2 SHAKEN STI-AS/STI-VS with Centralized Signing info=” 8.1.4.3 Response Sample (Failure) HTTP/1.1 400 Bad Request X-RequestID: AA97B177-9383-4934-8543-0F91A7A02836 Content-Type: application/json Content-Length: “requ
22、estError”: “serviceException”: ATIS-1000082 13 “messageId”: “SVC4001” “text”: “Error: Missing mandatory parameter %1”, “variables”: “iat” 8.1.4.4 HTTP Response Codes Response code Service/Policy Exception Reason /Description 200 N/A Successful signing. 400 SVC4000 Missing JSON body in the request. 4
23、00 SVC4001 Missing mandatory parameter. 406 SVC4002 Not supported body type is specified in Accept HTTP header. 415 SVC4004 Received unsupported message body type in Content-Type HTTP header. 400 SVC4005 Invalid parameter value. 400 SVC4006 Failed to parse JSON body. 411 SVC4007 Missing mandatory Co
24、ntent-Length header. 405 POL4050 Method Not Allowed: Invalid HTTP method used (all methods except POST will be rejected for the specific resource URL). 500 POL5000 The POST request failed due to internal signing server problem. 8.2 Verification API 8.2.1 Functional Behavior The Verification API is u
25、sed to verify the signature provided in the Identity header field and to determine that the signing service credentials demonstrate authority over the call originating identity. Upon receipt of a SIP INVITE containing a SIP Identity header field parameter, the Verifier builds a verificationRequest a
26、s follows: 1. The “from” parameter is populated using the PAI field if present, otherwise using the From header field in the SIP Invite. 2. The “to” parameter is populated with the To header field from the SIP Invite. 3. The “time” parameter value is populated with the RFC7519 encoded Date header fi
27、eld from the SIP Invite. 4. The “identity” parameter value is populated using the Identity header field in the SIP Invite. 5. The Verifier then sends the HTTP Post to request verification. Upon receipt of the verificationRequest, the SHAKEN Verification Service performs the following steps. Each ste
28、p is associated with the appropriate error case(s) specified in the section “Mapping of verification failure cases to the returned SIP header parameters”. The error case numbers En per each step is specified in parentheses. 1. Validate the incoming verification request parameters in terms of paramet
29、ers type and format (E1 and E2). 2. Validate the “time” parameter value in terms of “freshness”: a request with a “time” value which is different by more than one minute from the current time will be rejected (E3). 3. Parse the “identity” parameter value: a. full form of PASSporT is required by SHAK
30、EN: “identity-digest” parameter of Identity header has to be parsed to validate the full form format three data portions delimited with dot (“.”). If the expected format is not matched reject request on the Invalid PASSporT form (E4). ATIS-1000082 14 b. If “ppt” parameter is specified and its value
31、is not “shaken” reject request (E5). c. If “info” parameter is not specified reject request (E6). d. If the URI specified in “info” parameter is not syntactically valid reject request (E7). 4. Decode “identity-digest” parameter value to extract from the first portion (PASSporT header) “ppt”, “typ”,
32、”alg” and “x5u” claims: a. If one of the mentioned claims is missing - reject request (E9). b. If extracted “typ” value is not equal to “passport” reject request (E11). c. If extracted “alg” value is not equal to “ES256” reject request (E12). d. If extracted “x5u” value is not equal to the URI speci
33、fied in the “info” parameter of Identity header reject request (E10). e. If extracted “ppt” is not equal to “shaken” reject request (E13). 5. Decode “identity-digest” parameter value to extract from the second portion (PASSporT payload) “dest”, “orig”, “attest”, “origid” and “iat” claims: a. On miss
34、ing mandatory claims reject request (E14). b. Validate the extracted from payload “iat” claim value in terms of “freshness” relative to “time” value: request with “expired” “iat” will be rejected reject request (E15). c. On invalid “attest” claim reject request (E19). d. Normalize to the canonical f
35、orm the received in the “verificationRequest” “from” and “to” telephone numbers (remove visual separators and leading “+”) and compare them with ones extracted from the “orig” and “dest” claims of PASSporT payload. If they are not identical reject request (E16). 6. Dereference “info” parameter URI t
36、o a resource that contains the public key of the certificate used by signing service to sign a request. If there is a failure to dereference the URI due to timeout or a non-existent resource, the request is rejected (E8). 7. Validate the issuing CA. On the failure to authenticate the CA (for example
37、 not valid, no root CA) request will be rejected (E17). 8. Validate the signature of “identity” digest parameter. On failure, reject the request (E18). 8.2.2 Call Flow ATIS-1000082 15 8.2.3 Request (POST) The used resource is: http:/serverRoot/stir/v1/verification. Name Description serverRoot Server
38、 base URL: hostname+port+base path. Hostname contains the Global FQDN of Verification Service. 8.2.3.1 Request Body Parameter Data Type Required? Brief description Verification Request verificationRequest Yes Contains the JSON structure of the verification request (PASSporT payload claims + identity
39、 header). 8.2.3.2 Request Sample POST /stir/v1/verification HTTP/1.1 Host: Accept: application/json X-InstanceID : de305d54-75b4-431b-adb2-eb6b9e546014 X-RequestID: AA97B177-9383-4934-8543-0F91A7A02836 Content-Type: application/json Content-Length: “verificationRequest”: “from”: “tn”: “12155551212”
40、 , “to”: “tn”: “12355551212” , “time”: 1443208345, “identity”: “eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwicHB0Ijoic2hha2VuIiwieDV1IjoiaHR0cDov L2NlcnQtYXV0aC5wb2Muc3lzLmNvbWNhc3QubmV0L2V4YW1wbGUuY2VydCJ9eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6IisxMjE1NTU1MTIxMyJ9LCJpYXQiOiIxNDcxMzc1NDE4Iiwib3JpZyI6eyJ
41、0biI64oCdKzEyMTU1NTUxMjEyIn0sIm9yaWdpZCI6IjEyM2U0NTY3LWU4OWItMTJkMy1hNDU2LTQyNjY1NTQ0MDAwMCJ9._28kAwRWnheXyA6nY4MvmK5JKHZH9hSYkWI4g75mnq9Tj2lW4WPm0PlvudoGaj7wM5XujZUTb_3MA4modoDtCA;info=” 8.2.4 Response 8.2.4.1 Response Body Response body is returned as JSON object (Content-Type: application/son). A
42、TIS-1000082 16 Parameter Data Type Required? Brief description Verification Response verificationResponse Yes Contains the JSON structure of the verification response. 8.2.4.2 Mapping of Verification Failure Cases to the Returned SIP Reason Header Field Parameters Error Case Number Error Case (“reas
43、ondesc”) HTTP Status Code “reasoncode” “reasontext” “verstat” E1 Missing mandatory parameters in the verification request (“from”, “to”, “time”, “identity”). 400 with service exception - - No-TN-Validation E2 Received invalid parameters (invalid “from”/“to” tn format, “time” value). 400 with service
44、 exception - - No-TN-Validation E3 Received iat value is not fresh. 200 403 Stale Date No-TN-Validation E4 Identity header in compact form instead of required by SHAKEN spec full form. 200 438 Invalid Identity Header No-TN-Validation E5 Identity header is received with ppt parameter value that is no
45、t shaken. 200 438 Invalid Identity Header No-TN-Validation E6 Missing info parameter in the identity. 200 436 Bad identityInfo No-TN-Validation E7 Invalid info URI. 200 436 Bad identity Info No-TN-Validation E8 Failed to dereference info URI. 200 436 Bad identity Info No-TN-Validation E9 Missing %1
46、claim in the PASSporT header. %1 - “ppt”, ”typ”, ”alg”, ”x5u” 200 436 Bad identity Info No-TN-Validation E10 x5u from PASSporT header doesnt match the info parameter of identity header value. 200 436 Bad identity Info No-TN-Validation E11 typ from PASSporT header is not passport. 200 437 Unsupported
47、 credential No-TN-Validation E12 alg from PASSporT header is not ES256. 200 437 Unsupported credential No-TN-Validation E13 ppt from PASSporT header is not shaken. 200 438 Invalid Identity Header No-TN-Validation E14 Missing %1 mandatory claim in PASSporT payload %1 - “dest”, “orig”, “attest”, “orig
48、id”, “iat” 200 438 Invalid Identity Header No-TN-Validation ATIS-1000082 17 Error Case Number Error Case (“reasondesc”) HTTP Status Code “reasoncode” “reasontext” “verstat” E15 iat from PASSporT payload is not fresh. 200 403 Stale Date No-TN-Validation E16 %1 claim from PASSporT payload doesnt match
49、 the received in the verification request claim. %1 - “orig”, “dest” 200 438 Invalid Identity Header No-TN-Validation E17 Failed to authenticate CA. 200 437 Unsupported credential TN-Validation-Failed E18 Signature validation failed. 200 438 Invalid Identity Header TN-Validation-Failed E19 attest claim in PASSporT payload is not valid. 200 438 Invalid Identity Header No-TN-Validation 8.2.4.3 Response Sample (Success + Successful Validation) HTTP/1.1 200 OK X
