NSS STI-AS and STI-VS REST interface

updated 2 mths ago
3replies

Overview

In addition to traditional SIP INVITE/300 interface NSS provides a REST interface for STI-AS signing and STI-VS verification in compliance with ATIS-1000082 standards.

STI-AS

HTTP spec

The following headers are expected to be sent in all HTTP requests:

Header Name	Mandatory?	Description
X-RequestID	N	The X-RequestID transaction ID should be included in order to make possible the transaction traceability in case of troubleshooting and fault analysis. If received, it will not be validated explicitly by server. If not received, it will be automatically generated by STI-AS/VS service on request receipt. Received/Generated transaction ID will be returned back in the corresponding HTTP response in “X-RequestID” header.
X-InstanceID	N	For auditing purposes, each component calling the API should identify itself by sending its identity (e.g., VNFC name/UUID, VM name/UUID ...) in "XInstanceID" header.
Content-Type	Y	Determines the format of the request body. Valid value is: “application/json”. Requests with other types will be rejected with “415 Unsupported Media type” HTTP status code.
Accept	N	If specified, has to contain “application/json” content type, otherwise HTTP request will be rejected with “406 Not Acceptable” HTTP Status Code. If not specified, will be default handled as “application/json”.

The following headers are expected to be sent in all HTTP responses:

Header Name	Mandatory?	Description
X-RequestID	Y	Received/Generated X-RequestID transaction ID will be returned in the corresponding HTTP response.
Content-Type	Y	Determines the format of the response body. Valid value is: “application/json”

API

Endpoint	Description
POST /stir/v1/signing	This REST endpoint is responsible for processing a signing request to produce a STIR/SHAKEN identity header. The operation will send back an object with the signing results.

Parameters

Parameter	Description
signingRequest	This is the JSON object’s root element. When sending the request, it will require that the data being sent is a JSON string with the root element, signingRequest
attest	SHAKEN extension to PASSporT. Indicator identifying the service provider that is vouching for the call as well as clearly indicating what information the service provider is attesting to. SHAKEN spec requires “attest” key value be set to uppercase characters “A”, “B”, or “C”. In Sansay’s Implementation of the NSS, Attestation is configured for each ANI via the GUI or REST/SOAP
orig	Represents the asserted identity of the originator of the personal communications signaling.
dest	Represents the called party. Array containing one or more identities of TNs.
iat	“Issued At Claim”: Should be set to the date and time of issuance of the PASSporT Token. The time value should be in the Numeric Date format defined in RFC 7519: number of seconds elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970 not including leap seconds
origid	The unique origination identifier (“origid”) is defined as part of SHAKEN extension to PASSporT. This unique origination identifier should be a globally unique string corresponding to a UUID (RFC 4122). NOT CURRENTLY USED - THIS IS NOT CURRENTLY NEEDED.

HTTP Signing Response Codes

Code	Service/Policy Exception	Reason / Description
200	N/A	Successful signing.
400	SVC4000	Missing JSON body in the request.
400	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 Content-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.

The POST request will require that you send valid parameters as follows:

{

"signingRequest":{

"attest":"A",

"orig":{ "tn":"12155551212"},

"dest":{"tn":["12355551212"] },

"iat":1443208345,

“origid”:”SOME_UNIQUE_STRING”

}

}

Examples

Request

*NOTE: Curl requests going to the NSS should include the ‘--insecure’ or ‘-k’ flag unless the NSS has a correctly configured SSL certificate with a matching domain name.

curl https://nss.sansay.com:3334/stir/v1/signing -k -X POST
  -H 'Content-Type: application/json'
  -H 'Accept: application/json'
  -H 'X-RequestID: 12345678'
  -d "{\"signingRequest\":{\"orig\":{\"tn\":\"12155551212\"},\"dest\":{\"tn\":[\"12355551212\"]},\"iat\":$(date +%s)}}"

Response Sample (Success)

HTTP/1.1 200 OK

X-RequestID: AA97B177-9383-4934-8543-0F91A7A02836

Content-Type: application/json

Content-Length: …

{

"signingResponse": {

"identity":“eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwicHB0Ijoic2hha2VuIiwieDV1IjoiaHR0cDovL2NlcnQtYXV0aC5wb2Muc3lzLmNvbWNhc3QubmV0L2V4YW1wbGUuY2VydCJ9eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6IisxMjE1NTU1MTIxMyJ9LCJpYXQiOiIxNDcxMzc1NDE4Iiwib3JpZyI6eyJ0biI64oCdKzEyMTU1NTUxMjEyIn0sIm9yaWdpZCI6IjEyM2U0NTY3LWU4OWItMTJkMy1hNDU2LTQyNjY1NTQ0MDAwMCJ9._28kAwRWnheXyA6nY4MvmK5JKHZH9hSYkWI4g75mnq9Tj2lW4WPm0PlvudoGaj7wM5XujZUTb_3MA4modoDtCA;info=<https://cert.example2.net/example.cert>”

}

}

Response Sample (Failure)

HTTP/1.1 400 Bad Request

X-RequestID: AA97B177-9383-4934-8543-0F91A7A02836

Content-Type: application/json

Content-Length: …

{

“requestError”: {

“serviceException”: {

“messageId”: “SVC4001”

            “text”: “Error: Missing mandatory parameter ‘%1’”,

“variables”: [“iat”]

}

}

}

STI-VS

HTTP Spec