Stir/Shaken APIs

by

STIR/SHAKEN is a framework of interconnected standards. STIR/SHAKEN are acronyms for the Secure Telephone Identity Revisited (STIR) and Signature-based Handling of Asserted Information Using toKENs (SHAKEN) standards.

As every CodeB Node contains a gateway connecting the Stir/Shaken world with the CBAN Antifraud system we offer a couple of public Stir/Shaken APIs in our Antifraud Namespace on: http://coin.codeb.io/antifraud.asmx

Test Certificates

Certificates for testing any Stir/Shaken are hard to get and complicated to generate. For that reason we offer two API’s to generate self-signed Stir/Shaken Certificates. Those are

TestCertStirShakenB64 on http://coin.codeb.io/antifraud.asmx?op=TestCertStirShakenB64

This function returns a JSON Token containing the certificate and the private key.

TestCertStirShakenP12 on http://coin.codeb.io/antifraud.asmx?op=TestCertStirShakenP12

This function returns a JSON Token containing a PFX/P12 password protected package containing certificate and key.

Generate Stir/Shaken Token

With CreateSelfSignedStirShakenToken you can generate a Stir/Shaken Test Token without having to own a certificate at all. It creates internally a one time certificate to sign the token. The returned Token can be validated with the function ValidateStirShakenToken.

If you own a certificate and private key you can use the function CreateStirShakenToken to generate a Token. Depending on the availability of the public part of the certificate it can be validated with ValidateStirShakenToken.

Validate Stir/Shaken Token

Validation of exiting Tokens might be the most important function for most users. To be able to validate a Token the public certificate of the signer has to be downloaded.

Note: As many Stir/Shaken participants do not have their public certificates downloadable worldwide this function might fail to validate those Tokens!

The validation function ValidateStirShakenToken is available at http://coin.codeb.io/antifraud.asmx?op=ValidateStirShakenToken

Simple REST API

Additionally to the above web services we offer also simple REST APIs. For example to integrate Stir/Shaken in popular systems such as Asterisk, FreePBX, etc.

Out simple RESTful-compliant STIR/SHAKEN Token Request API can be accessed via HTTPS using an API Key. If you have a registered identity on our platform you can obtain this API Key fully automatically. For testing purposes just request one from: info@codeb.io.

Note: When using an API Key for testing the signing certificate will be a self-signed test certificate!

All results of the above API are returned as JSON.

Below, please find the endpoints and examples:

Endpoint: http://portal.codeb.io/sign/shaken?

Method: GET

Parameters:

  • ToNumber: Any correctly formatted telephone number.
  • FromNumber: Any correctly formatted telephone number.
  • Attestation: A, B or C

Headers:

  • x-api-key: Your API key.

Sample Request Without Attestation Level: (do not forget to transmit your API Key)

http://portal.codeb.io/sign/shaken?ToNumber=4954138594554&FromNumber=35679567034

Sample Request With Attestation Level: (do not forget to transmit your API Key)

http://portal.codeb.io/sign/shaken?ToNumber=4954138594554&FromNumber=35679567034&Attestation=A

Response:

{
"RequestGuid":"d4e51bb945cf4e879123306082ce5cf2",
"AccountGuid":"548c4f762f7949469150ed5e8eabb33a",
"ToNumber":"4954138594554",
"FromNumber":"35679567034",
"IPAddress":"195.158.111.88",
"IsDNC":"false","IsDisconnected":"false",
"CallerIDToUse":"35679567034",
"Identity":"eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9wb3J0YWwuY29kZWIuaW8vd2ViMy9jcnQvUW1UVFpjVVFhOWpkUU5aUXZ5TEtDM3E1cmVNdzFwcEh0SjhtbTY2cThXQmhDMSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyI0OTU0MTM4NTk0NTU0Il19LCJpYXQiOjE2NzE0OTE4NjMsIm9yaWciOnsidG4iOiIzNTY3OTU2NzAzNCJ9LCJvcmlnaWQiOiJkNGU1MWJiOTQ1Y2Y0ZTg3OTEyMzMwNjA4MmNlNWNmMiJ9.zF_RPWhGwoZtNxCEjcCT5x4pzuP7zsvQ6caqZ8SU9Oz-sVO7ECNhQBjL7kKA4_JgRvoXxQK57XBSSxLj_CfH8w;info=<https://portal.codeb.io/web3/crt/QmTTZcUQa9jdQNZQvyLKC3q5reMw1ppHtJ8mm66q8WBhC1>;alg=ES256;ppt=shaken",
"CAID":"a6fe902cb5934c65b64fac8a56928996",
"AttestationLevel":"A",
"RequestedAt":"2022-12-20T00:17:44Z",
"CompletedAt":"2022-12-20T00:17:44Z",
"ProcessingTime":"15.0123",
"ReturnCode":200,
"ReturnStatus":"Success"
}

What do the response values mean?

  • RequestGuid: a unique identifier assigned to this request. 
  • AccountGuid: a unique identifier assigned to your account.
  • ToNumber: The phone number sent in the ‘ToNumber’ parameter.
  • FromNumber: The phone number sent in the ‘FromNumber’ parameter.
  • IPAddress: The IP address where the request originated from.
  • Identity: The token assigned to the phone call.
  • CAID: The unique identifier assigned to this token.
  • AttestationLevel: The attestation level associated with the FromNumber.
  • RequestedAt: When we received the request to provide a token.
  • CompletedAt: When the request finished processing.
  • ProcessingTime: How much time, in milliseconds, this request required.

Important: If a validation returns attestation “A” or “B” AND the Salt and/or Pepper have been defined the anonymous CBAN Hash is being calculated and published in the CBAN System.

Questions? Just contact info@codeb.io