Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

メニュー

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Voice Recording Encryption

Voice Recording Encryption is a feature that provides additional security on your Twilio Programmable Voice Recordings. It allows you to encrypt your recordings with a public key.

Once you activate the Voice Recording Encryption feature, only you will be able to decrypt the recordings. There is no one at Twilio, including Twilio support, that will be able to decrypt your recordings. Therefore, testing of this feature should only be done on test accounts with non-production recordings.

How Voice Recording Encryption works

Today, by default, all Programmable Voice Recordings are encrypted at rest while stored in Twilio's cloud storage. With Voice Recording Encryption enabled, your recordings are encrypted with your public key as soon as the call ends, while the recording is within the Twilio infrastructure, and before it is in cloud storage. The recording remains in this encrypted state until you retrieve it, ensuring that the recording can only be accessed by you, the holder of the corresponding private key.

The Voice Recording Encryption feature is implemented using hybrid encryption. The following are the summarized set of steps of encryption / decryption for each recording.

Twilio Encryption Steps
  1. Twilio generates a random Content Encryption Key (CEK) for each recording.
  2. Twilio encrypts the recording content with the generated CEK using the AES256-GCM cipher.
  3. Twilio encrypts the CEK with the customer's public key using the RSAES-OAEP-SHA256-MGF1 cipher.
Customer Decryption Steps
  1. Customer retrieves the Content Encryption Key (CEK) and Initial Vector (IV) encryption values for the recording.
  2. Customer decrypts the CEK using their private key.
  3. Customer decrypts the recording content using the CEK, along with the IV encryption value.

Detailed decryption steps and code samples can be found here.

料金設定

Voice Recording Encryption is included with the Twilio Enterprise Edition.
For customers not enrolled in the Twilio Enterprise Edition, pricing for this feature is $.015 for each encrypted recording minute. If you are interested in an unlimited usage, fixed monthly price option, please contact our sales team.

Configuring Voice Recording Encryption

Step 1: Generate a RSA key pair

First, generate an RSA public/private key pair. There are many different ways to do this, we recommend using openssl. Once you have openssl installed, you can generate a 2048 length private key with this command:

$ openssl genrsa -out private_key.pem 2048

The generated file private_key.pem contains your private key, which will look something like this:

$ cat private_key.pem

-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEAtePBUk3IM45Jj8eFFrmwzjr/2seEtMknl5OD7VDBipazsq5v
MBnIYcE+EuzDiFC5XXww9rncFRZC0I3hLUejUTkJNZjMDQzVFkGXo9+A4MsXRZqK
OOYhCNAr2C1acpHKK6bEqGhRW2F2R0dSndbEKOCpPKD70ZF2aZyQdb//9104ROdh
bvsycQD7ZGQ8V5SoUo6kPBjQv1sbi99LN6uQm+trUDHkBhbpeKU836YPpIH1ZAqG
h2sSzRHN0eXdOPYNdu649ZuOSz0kIUN22e8R39suRhu6VbrC2kvVz2Su+tSPMWlp
gKjMboVKrsWUH9B1fQM9ajixc8fc892ZoGBqaQIDAQABAoIBAQCd5BlbEr4pUui0
cOQs+ABs5XZYOj4OmVdPEvTAuwtm/K78+sL2JEt34EG8N978o+ZlKntukaRkgbB6
Tc8ceUViKnq+Fed7pJoM+d9il4/Okz2eZCp8ffhLKDoHLEeJkNjIz7mC3xtQkegU
s+sZrOcW/P6r7KrsHrOFti0IqiTOWps1M6gIUKFWcIRIh/6SyN0gmdDxmfGD9o4W
CePswAS0fmwMZPCwQ9GazC8iVL+CvrF92UNfmNQSUiuR0GynOlsMnDu2GvSim3yO
9lqWAo1yyEBVU8x6pS1wFTdsXQ7Ch2Ei9ZU+XE6SL5lq3jSc8WqIGmLvZ+zw5eAR
8J73+fkBAoGBAO12zPHKgvN5nHRTrO3gNVcl92201umLHllf2elOjlE98/qtNsuX
R96LILDv4rgSjwH0+eVQW2g2B5o3D6KPvXdEvUmaRIXDValqr1UzED1DFWLs1MQK
HO30rJSpfWpTD3B56zvMb620avIBv3+Oe6kmjImn7Db/nyuEZrs49sE5AoGBAMQW
bAXgbG5GDUMVvJfrWwiXz3Ip7yv2j6xz5MtU58gytVV2ZnesLSCfpKrUpalPDWsX
04ZBuZ7bqZR4UpGQnGlYePtttKMdI4Vbo+tPK8gNN8ELu+8Fgmr0UNv3BWmcSRzo
AfiWWIHZS6iAkPoaYWQtCtf3WU0wnt/beiP/NWKxAoGAafCUYlLMtT7OE/+4qK9c
XLLtfh4tuyd7tLfUigen6orPLEjWp2GoiJpdTVLYPPLapi7axflhrk5ceeqSqR2j
k3AxWoLeiyaoMtsLueD8H7ir8+Rgz80LNwXvcKtk7mh7/NwHnDgKot5Yz/sDqi6w
8Lfn/wnRkn/cTRfWlTRGsdECgYEAuXjP4lsdlMyT3MFhqnzGlYEqibyaaoYD7cWN
Qrpjplw4YsbkMwvbf4EhOyh6LYQFmCdoPxRJ47W4WCPbTa5wE8DIZmGlO6fjIk/E
41z2d3nxI5rav0IB0vKWzQiAyR03lqzouF5VBzUmuBIrjzWGqz9jg1WF1VpI3Er3
47aQo3ECgYBQ7UZ3IP1+unprNsvVDT4CbjsoAypstmQhfgxYiNPY0wB7rvTOWT3q
3vwOBwVBjfvkG8yYglYgHc0xGOrqL6DxhMUFTxBe0iDvBX0QM1tpp4apsKdHvuuQ
h1icaQZp8WKxBOzVilj3DLoHJEyIrsWWMnDHazV4fxbxijpj4uwJCw==
-----END RSA PRIVATE KEY-----

Note: It is your responsibility to keep your private key safe. Losing your private key means that you will not be able to decrypt any of the files that were encrypted with the corresponding public key.

You can obtain the public key executing the following:

$ openssl rsa -in private_key.pem -pubout -out public_key.pem

The file public_key.pem contains the public key. It should look like this:

$ cat public_key.pem

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtePBUk3IM45Jj8eFFrmw
zjr/2seEtMknl5OD7VDBipazsq5vMBnIYcE+EuzDiFC5XXww9rncFRZC0I3hLUej
UTkJNZjMDQzVFkGXo9+A4MsXRZqKOOYhCNAr2C1acpHKK6bEqGhRW2F2R0dSndbE
KOCpPKD70ZF2aZyQdb//9104ROdhbvsycQD7ZGQ8V5SoUo6kPBjQv1sbi99LN6uQ
m+trUDHkBhbpeKU836YPpIH1ZAqGh2sSzRHN0eXdOPYNdu649ZuOSz0kIUN22e8R
39suRhu6VbrC2kvVz2Su+tSPMWlpgKjMboVKrsWUH9B1fQM9ajixc8fc892ZoGBq
aQIDAQAB
-----END PUBLIC KEY-----

In the next step, you will configure Twilio with this public key.

Step 2: Create a Twilio Public Key resource

Once you have the RSA public key, you should create a Twilio Public Key resource that contains your public key. You can do this with the Public Key Resource REST API or, in the Twilio Console.

To configure the public key in the Console, navigate to the Runtime >> Credentials page in the Console and click the button 'Create new Credential'.

Console Runtime - Add New Credential.png

Provide a friendly name for your public key. Then, copy the full contents of the public_key.pem file (including the BEGIN PUBLIC KEY and END PUBLIC KEY lines) generated in step 1 and paste it into the PUBLIC KEY field. Press Create to create the Twilio Public Key:

Once you submit the Twilio Public Key resource, the public key itself will no longer be retrievable from Twilio. All future references to this particular public key will be the via an associated unique SID identifier, with the form `CRxx`.

Step 3: Enable Voice Recording Encryption in the Console

You can enable Voice Recording Encryption at a project or subaccount level via the Console.

  • Navigate to Programmable Voice > Settings in the Console.
  • Enable the feature and specify the public key you uploaded in step 2.
  • Save your settings.
  • All recordings created thereafter on this account will be encrypted with the configured public key.

Voice Recording Encryption - Console Enablement.png

Decrypting Your Recordings

Step 4: Retrieve recording specific encryption details

  • Obtain public_key_sid, encrypted_cek, iv parameters within EncryptionDetails json via a GET on the recording resource or via a RecordingStatusCallback.

Parameter | Description
----------- | --------------------------------------------------------------------------------------------- | --------------- EncryptionDetails |JSON object that includes relevant encryption details if the recording was encrypted via Voice Recording Encryption feature and null otherwise. The encryption properties include :
type: The type of encryption -- currently only value supported is rsa-aes
public_key_sid: A 34 character string that uniquely identifies the public key resource used as part of recording encryption
encrypted_cek: Encrypted content encryption key used as part of recording encryption (base64 encoded)
iv: Randomly generated Initial Vector used as part of recording encryption. (base 64 encoded)

GET on the Recording Resource

Any recording encrypted via Voice Recording Encryption will contain additional encryption properties on the recording resource. See request/response example below to query the recording resource metadata:

curl -X GET 'https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings/REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json' 
{
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "api_version": "2010-04-01",
  "call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "conference_sid": "CFXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "channels": 1,
  "date_created": "Fri, 14 Oct 2016 21:56:34 +0000",
  "date_updated": "Fri, 14 Oct 2016 21:56:38 +0000",
  "start_time": "Fri, 14 Oct 2016 21:56:34 +0000",
  "price": "-0.0025",
  "price_unit": "USD",
  "duration": "4",
  "sid": "REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "source": "StartConferenceRecordingAPI",
  "status": "completed",
  "error_code": null,
  "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings/REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json",
  "subresource_uris": {
    "add_on_results": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings/REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AddOnResults.json",
    "transcriptions": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings/REXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Transcriptions.json"
  },
  "encryption_details": {
    "type": "rsa-aes",
    "encryption_public_key_sid": "CRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "encryption_cek": "OV4h6zrsxMIW7h0Zfqwfn6TI2GCNl54KALlg8wn8YB8KYZhXt6HlgvBWAmQTlfYVeLWydMiCewY0YkDDT1xmNe5huEo9vjuKBS5OmYK4CZkSx1NVv3XOGrZHpd2Pl/5WJHVhUK//AUO87uh5qnUP2E0KoLh1nyCLeGcEkXU0RfpPn/6nxjof/n6m6OzZOyeIRK4Oed5+rEtjqFDfqT0EVKjs6JAxv+f0DCc1xYRHl2yV8bahUPVKs+bHYdy4PVszFKa76M/Uae4jFA9Lv233JqWcxj+K2UoghuGhAFbV/JQIIswY2CBYI8JlVSifSqNEl9vvsTJ8bkVMm3MKbG2P7Q==",
    "iv": "8I2hhNIYNTrwxfHk"
  }
}

RecordingStatusCallback

RecordingStatusCallback is the reliable way to receive Webhooks for completed or failed recordings. Please see this RecordingStatusCallback support article for more details.

Subscribe to 'failed' RecordingStatusCallbackEvent to receive callbacks in recording encryption failure scenarios, described further below.

Below is an example of a RecordingStatusCallback Webhook with encryption parameters:

"RecordingSource": "OutboundAPI"
"EncryptionDetails": "{"type":"rsa-aes","public_key_sid":"CR201607f4ca45a533cdca8d9a828c2a87","encrypted_cek":"ZriXxBEXSywEohXQZV53KGvyzAO1HpKRxCuMo/pcKiT7C+bWKfelZuX0eW1jb7iGcESrOqwvLo4v4GVRPDdJKsaO6R/AVTDcA+he5syPDBgg20ECilAhC/9/CNxfbIuQD+rRKmx0O7SOJJyazbc4zlv+4ClWwDm6g/8z0ekpYs/tNrlQenbxU/Un9uLeeBaJtFKeK5YSUea5n3Kce22iaPZMy3WUGBg+JfOHrccvCjDjX5QQ21I3rcdpgb5nwpzf3MQwmExhW8SJtmQ1cL4jDeKojM255HhhcgOYDwcyrTfY7svUkqNrEKei1q5ZFdBl+SjjKfSdE0BgEvTceZZYrQ==","iv":"7MiadYE7QDgVSRm9"}"
"RecordingSid": "REb719a56ceca43b2d06967983570e658a"
"RecordingUrl": "https://api.twilio.com/2010-04-01/Accounts/AC18d5c6f2003e8710de63b2f9c412b145/Recordings/REb719a56ceca43b2d06967983570e658a"
"RecordingStatus": "completed"
"RecordingChannels": "1"
"ErrorCode": "0"
"CallSid": "CA5987df4d600665d67f53e1bd4cec76d6"
"RecordingStartTime": "Tue, 28 May 2019 02:18:02 +0000"
"AccountSid": "AC18d5c6f2003e8710de63b2f9c412b145"
"RecordingDuration": "5"

Step 5: Decrypt using private key and encryption parameters

  1. Retrieve customer private key corresponding to public_key_sid and use it to decrypt base64 encoded encrypted_cek via RSAES-OAEP-SHA256-MGF1.
  2. Initialize a AES256-GCM SecretKey object with decrypted CEK and base 64 encoded iv
  3. Decrypt encrypted recording using the SecretKey

Here are decrypting code samples in:

Failure scenarios

Voice Recording Encryption is enabled but Twilio is unable to determine or retrieve the public key configured for recording encryption

  • In this scenario, the most recently added retrievable public key on the account will be used for encryption, if one exists.
  • The public_key_sid within EncryptionDetails will represent the sid of the public key actually used for encryption, not necessarily the one configured.
  • A notification to the account will be sent (viewable from the Debugger in the Console) which indicates that an alternative public key was used.

Twilio is unable to encrypt the recording because there aren't any public keys on the account or an intermittent system issue occurred

  • Recording file is deleted and will not be available for access.
  • Recording resource metadata will have a Status of failed, ErrorCode of 16104 and EncryptionDetails will be null.
  • A RecordingStatusCallback will be sent (if configured via RecordingStatusCallbackEvent) with a Status of failed, ErrorCode of 16104, and EncryptionDetails will be null and not included in the callback.
  • A notification to the account will be sent (viewable from the Debugger in the Console) which indicates a failure was due to inaccessibility of public keys or an internal system error.
Vineet Agarwal Craig Dennis David Prothero Andrew Baker
Rate this page:

ヘルプが必要ですか?

誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。