2

NSS STI-AS and STI-VS REST interface

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.

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”

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.

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.

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”

}

}

*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)}}"
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>”

}

}
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”]

}

}

}

 

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”

Endpoint

Description

Response

POST
/stir/v1/verification

This REST endpoint is responsible for processing a verification request with a STIR/SHAKEN ID Header. The operation will send back an object with the verification results.

403 - Forbidden for requests from hosts that are not in SBC/trusted host lists
Or
{ result: VerificationStatus } - Where VerificationStatus is an INTEGER whose value indicates the status of the verify request.

 

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

{

"verificationRequest":{

"from":{ "tn":"12155551212"},

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

"time":1443208345,

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

}

}

Parameter

Description

verificationRequest

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, ‘verificationRequest’

from

This is a JSON object with a single child element, ‘tn’ - This is where the ANI will be added. Can only be 1 ANI.

to

This is a JSON object with a single child element, ‘tn’ - This is where the DNIS will be added. The child element here is a string array as we may have many DNIS.

time

Epoch timestamp of the call. Please note that all certificates should use GMT, so the epoch time should likewise reflect this.

identity

This is the identity header from the call.

Error Case Number

Error Case (“reasondesc”)

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 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 not ‘shaken’.

200

438

Invalid Identity Header

No-TN-Validation

E6

Missing ‘info’ parameter in the ‘identity’.

200

436

Bad identity info

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’ claim in the PASSporT header. %1 - “ppt”, ”typ”, ”alg”, ”x5u”

200

436

Bad identity info

No-TN-Validation

E10

‘x5u’ from PASSporT header doesn’t 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 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”, “origid”, “iat”

200

438

Invalid Identity Header

No-TN-Validation

E15

‘iat’ from PASSporT payload is not fresh.

200

403

Stale Date

No-TN-Validation

E16

‘%1’ claim from PASSporT payload doesn’t match 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

curl https://local.sansay.com:3333/stir/v1/verification -k -X POST
  -H 'Content-Type: application/json'
  -d '{"verificationRequest":{"from":{"tn":"12155551212"}, "to":{"tn":["12355551212"]}, "time":1443208345, "identity":"eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0IiwicHB0Ijoic2hha2VuIiwieDV1IjoiaHR0cDovL2NlcnQtYXV0aC5wb2Muc3lzLmNvbWNhc3QubmV0L2V4YW1wbGUuY2VydCJ9eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6IisxMjE1NTU1MTIxMyJ9LCJpYXQiOiIxNDcxMzc1NDE4Iiwib3JpZyI6eyJ0biI64oCdKzEyMTU1NTUxMjEyIn0sIm9yaWdpZCI6IjEyM2U0NTY3LWU4OWItMTJkMy1hNDU2LTQyNjY1NTQ0MDAwMCJ9._28kAwRWnheXyA6nY4MvmK5JKHZH9hSYkWI4g75mnq9Tj2lW4WPm0PlvudoGaj7wM5XujZUTb_3MA4modoDtCA;info=<https://cert.example2.net/example.cert>"}}'
HTTP/1.1 200 OK

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

Content-Type: application/json

Content-Length: …

{

"verificationResponse": { “verstat”: “TN-Validation-Passed” }

}
HTTP/1.1 200 OK

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

Content-Type: application/json

Content-Length: …

{

"verificationResponse": {

“reasoncode”: 436,

“reasontext”: “Bad Identity Info”,

“reasondesc”: “Invalid ‘info’ URI”,

“verstat”: “No-TN-Validation”

}

}
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”]

}

}

} 

3 replies

null
    • Jeff_Anderson
    • 3 yrs ago
    • Reported - view

    I see this in one place for verification:

    /stir/v1/verification

    But in the curl section I see this:

    curl https://local.sansay.com:3333/stir/v1/url -k -X POST

    Which one is correct?

      • Carlos_Tena
      • 3 yrs ago
      • Reported - view

      Jeff Anderson The correct URL is 

      https://local.sansay.com:3333/stir/v1/verification 

      It has been corrected in the article.

    • Glen_Gerhard
    • 3 yrs ago
    • Reported - view

    Can this be downloaded as a pdf?