It's also possible to generate keys using openssl only: openssl genrsa -out private.pem 2048 openssl rsa -in private.pem -pubout -out public.pem. However, JWT and SAML tokens can use a public/private key pair in the form of a X.509 certificate for signing. Signing XML with XML Digital Signature without introducing obscure security holes is very difficult when compared to the simplicity of signing JSON. Mkjwk simple JSON Web Key generator.

This guide will walk you through the steps of implementing Public Key Client Validation. We include sample cURL commands and HTTP requests, then at the end we'll detail the steps in Java.

Public key client validation quickstart

To get started quickly, you can follow the Java example at the bottom of the page. It shows how Client Validation can be implemented, along with links to the Twilio Java helper library that supports this feature.

Steps to send a Request

  1. Generate an RSA Key Pair: Create a valid key pair. (This only has to be done once.)
  2. Submit the Public Key: Submit the public key to the Twilio via the Credentials Endpoint. (This is a one time requirement as well.)
  3. Hash the Canonical Request: Every outgoing request needs to be hashed and signed. (This functionality is implemented in the Java helper library and can be seen below.)
  4. Generate JWT: Once the hash is created, it needs to be embedded in the JWT payload and signed with the private key. (This is also handled by the Java helper library.)
  5. Attach JWT to the request header: The last step is to add the JWT to the request header.

1. Generate an RSA Keypair

A private key is used to sign your requests. It is is verified by the public key which you provide to Twilio.

Note: When you generate the private key, be sure to save and protect it as this is the only means to verify your application's identity.

We recommend generating the RSA key pair using the OpenSSL toolkit.

For Windows Systems

Install and use Cygwin to run the OpenSSL RSA keypair commands below.

For Mac and Linux/Unix-based Systems

You can run the OpenSSL commands to generate an RSA Keypair.

Generate a Private Key

Note: Twilio will only accept keys which have a bit length of 2048 with an exponent of 65537.

Generating a Public Key

Example Public Key FormatIf properly generated, the RSA public key should look like the example public key below:

Be sure to include the full header and footer when submitting the key: * '-----BEGIN PUBLIC KEY-----' AND * '-----END PUBLIC KEY-----'

2. Submit the Public Key to Twilio

Sample Requests cURL

Note: Line breaks in the PEM format of the key need to be removed when making the cURL request.

Sample Response

3. Hash the Canonical Request

The following section describes how the request needs to be canonicalized, hashed and attached to the request.

_Note: The Java helper library implements this functionality and will do the work for you. An end-to-end example is on the bottom of this page. _

This approach is loosely based on the approach Amazon is using to sign AWS API requests.

Canonical request pseudocode

Hashing Example

Example HTTP Request

Canonicalize the HTTP Method

The HTTP method is canonicalized by doing the following operations:

  1. Uppercase
  2. Trim

In the Example Request, this results in:

Canonicalize the Resource Path

To canonicalize the resource path:

  1. Remove redundant path elements, for example:
    • '/foobar/./barfoo' becomes '/foobar/barfoo' AND
    • '/foobar/../barfoo' becomes '/barfoo'
  2. URL-encode the remaining path using the UTF-8 character set in accordance with RFC 3986 with the following caveats:
    • ' ' (space) should always be '%20'
    • '*' (asterisk) should always be '%2A'
    • '%7E' should always be '~' (tilde)
  3. Empty string path should always result in ‘/’

In the Example Request, this results in:

Canonicalize the Query String

The query-string is canonicalized by the following operations:

  1. Remove the query-string from the URI (not-including the ‘?’)
  2. Construct a collection of key/value pairs by splitting the query string on ‘&’ASCII Sort the combined “key=value” strings (not just the ‘keys’)
  3. URL encode each key and value following the Resource Path (RFC 3986) with our caveats from above
  4. Concatenate each key/value pair like this: {key}={value}
    • If the key has no accompanying value, should result in ‘{key}=’Join all key/value pairs with a ‘&’ in between

In the example request, this results in the empty string.

If a request contains the following query parameter,

The canonicalized query string would be the following:

Canonicalize the Headers

The headers are canonicalized by the following operations:

  1. Filter the complete list of headers against the ‘hrh’ (hashed request headers) value in the enclosing JWT
  2. Lower-case and trim each header key
  3. Trim each header value and reduce continuous whitespace into a since space
  4. Sort header values that correspond to the same key
  5. Combine the key/values like this: “{key}:{values}n”
  6. ASCII sort
  7. Note that because each header line is terminated with a ‘n’. When the entire canonical request is combined, there should be a blank-line between the canonical-headers and the canonical-hashed-headers

In the Example Request, this results in:

Canonicalize the Hashed Headers

The hashed-headers are canonicalized by the following operations:

Generate
  1. Split on ‘;’ (semi-colon)
  2. Lowercase and trim
  3. 1ASCII Sort
  4. Join with ‘;” (semi-colon)

In the Example Request assume the want to include ‘Host’ and ‘Authorization’ in the list of hashed-headers, this results in:

Encode the Request Body

If the request body is empty, omit hashing it.

To encode the request body:

Generate Public Private Key Pair For Jwt
  1. Hash the request body using SHA-256
  2. Hex-encode the resulting hash

In the Example Request, this results in:

Final Canonical Request

In the example below, the first blank line is due to not having any query parameters. The second blank line is due to every canonicalized header being terminated with a ‘n’.

Canonical Request Hash

When the final canonical request string is created it must be hashed in a similar manner to the request body.

To encode the canonical request:

  1. Hash the request body using SHA-256
  2. Hex-encode the resulting hash

In the Example Request, this results in:

C# Generate Jwt

4. Generate the JWT

Once you have created the hash, you can generate a JWT with the hash embedded.

Every JWT assertion is composed of three components, the header, the payload, and the signature.

  • The header specifies the algorithm used for the JWT signature.
  • The payload contain the hash and additional metadata
  • The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way.

To construct the JWT assertion, these three components must be base64 encoded and concatenated using a “.” separator:

Note: For additional details on JWT go to: https://jwt.io/introduction/

Let’s have a closer look at the different parts of the JWT Assertion:

Header

The header consists of four parts: the content type, type of the token, the hashing algorithm being used, and the reference to the public key Twilio should used validate the message.

FieldValue(s)RequiredDescription
ctytwilio-pkrv;v=1yesContentType = Twilio Public Key Request Validation - Version 1
typJWTNo (Default: ‘JWT’)Media Type = JSON Web Token, other values rejected
algRS256yesAlgorithm = RSASSA-PKCS-v1_5 using SHA-256 hash algorithm. This is the only algorithm supported at the moment.
kidCredentialSidyesKey ID = Identifier of the public key credential associated with the private key used to sign the JWT

Example header:

Payload

The second part of the token is the payload, which contains the claims. Claims are statements about an entity and additional metadata.

FieldValue(s)RequiredDescription
issAPIKeySidyesIssuer = APIKey Sid used to match against request credentials
subAccountSidyesSubject = AccountSid
expexpiration timeyesToken Expiry Time: token received after exp +- clock skew will be rejected. Max exp - nbf is 300 seconds
nbfnot before timeNo(Default: ‘now’) Not Before Time
hrhlist of headers to hashyesA ‘;’ (semicolon) delimited list of lowercase headers to include in the request hash calculation. At a minimum you must include ‘Host’ and ‘Authorization’
rqhrequest hashyesPlease refer to ‘3. Create Hash of the Canonical Request’ above.

Example Payload:

Signature

To create the signature part you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that.

Signature Creation Example

Public Key

To validate the signature Twilio needs the public key. This public key needs to be uploaded to Twilio.The public key must be:

  • Algorithm: RSA
  • Modulus::bitLength: 2048
  • Format: X.509

Public key to successfully validate the Example JWT (below):

Private Key

The request has to be signed with a private key. The private key must match the public key uploaded to Twilio.

There are no limitations on the private key (as opposed to the public key, enumerated above) other than it needs to match the public key. It can be either PKCS#1 or PKCS#8 (whichever the signing library supports).

Private key used to sign the Example JWT:

Example JWT

The following JWT is composed of the example blocks from above. The JWT is signed with the private key above. This JWT can be validated with the public key above.

5. Attach JWT to the Request Header

The JTW needs to be added to the request via the Twilio-Client-Validation header.

Client Validation Java Example

The functionality is currently only supported in the latest Java helper library.

The following example covers all five steps of making a successful Client Validation request. This sample is also available on Github.

Notes:

Standard API Keys are not permitted to manage Accounts (e.g. create sub accounts) and other API Keys. If you require this functionality please refer to this page for additional details.

It may take a few minutes after Enforcing Public Key Client Validation from Settings for it to take effect.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

While Encrypting a File with a Password from the Command Line using OpenSSLis very useful in its own right, the real power of the OpenSSL library is itsability to support the use of public key cryptograph for encrypting orvalidating data in an unattended manner (where the password is not required toencrypt) is done with public keys.

The Commands to Run

Generate a 2048 bit RSA Key

You can generate a public and private RSA key pair like this:

openssl genrsa -des3 -out private.pem 2048

That generates a 2048-bit RSA key pair, encrypts them with a password you provideand writes them to a file. You need to next extract the public key file. You willuse this, for instance, on your web server to encrypt content so that it canonly be read with the private key.

Export the RSA Public Key to a File

This is a command that is

openssl rsa -in private.pem -outform PEM -pubout -out public.pem

The -pubout flag is really important. Be sure to include it.

Jwt Generate Key

Next open the public.pem and ensure that it starts with-----BEGIN PUBLIC KEY-----. This is how you know that this file is thepublic key of the pair and not a private key.

To check the file from the command line you can use the less command, like this:

less public.pem

Do Not Run This, it Exports the Private Key

A previous version of the post gave this example in error.

openssl rsa -in private.pem -out private_unencrypted.pem -outform PEM

The error is that the -pubout was dropped from the end of the command.That changes the meaning of the command from that of exporting the public keyto exporting the private key outside of its encrypted wrapper. Inspecting theoutput file, in this case private_unencrypted.pem clearly shows that the keyis a RSA private key as it starts with -----BEGIN RSA PRIVATE KEY-----.

Visually Inspect Your Key Files

It is important to visually inspect you private and public key files to makesure that they are what you expect. OpenSSL will clearly explain the nature ofthe key block with a -----BEGIN RSA PRIVATE KEY----- or -----BEGIN PUBLIC KEY-----.

You can use less to inspect each of your two files in turn:

  • less private.pem to verify that it starts with a -----BEGIN RSA PRIVATE KEY-----
  • less public.pem to verify that it starts with a -----BEGIN PUBLIC KEY-----

The next section shows a full example of what each key file should look like.

The Generated Key Files

The generated files are base64-encoded encryption keys in plain text format.If you select a password for your private key, its file will be encrypted withyour password. Be sure to remember this password or the key pair becomes useless.

The private.pem file looks something like this:

Generate Public Private Key Pair For Jwt Online

The public key, public.pem, file looks like:

Protecting Your Keys

Depending on the nature of the information you will protect, it’s important tokeep the private key backed up and secret. The public key can be distributedanywhere or embedded in your web application scripts, such as in your PHP,Ruby, or other scripts. Again, backup your keys!

Remember, if the key goes away the data encrypted to it is gone. Keeping aprinted copy of the key material in a sealed envelope in a bank safety depositbox is a good way to protect important keys against loss due to fire or harddrive failure.

Oh, and one last thing.

If you, dear reader, were planning any funny business with the private key that I have just published here. Know that they were made especially for this series of blog posts. I do not use them for anything else.

Found an issue?

Rietta plans, develops, and maintains applications.

Learn more about our services or drop us your email and we'll e-mail you back.

Other Blog Articles Published by Rietta.com

Coments are closed
Scroll to top