メニュー

Expand
ページを評価:

Encrypting your Stored Media

This feature is only available in Twilio Enterprise Edition. For further information contact the Twilio sales team.

概要

This guide explains how to encrypt Twilio Video Recordings and Compositions.

Note: Once you activate encryption, only you will be able to decipher. No one at Twilio --including Twilio support-- will be able to decrypt your content.

Use this feature when you need to ensure that your recorded media is encrypted end-to-end, and you are willing to accept the additional work of decrypting and post-processing your audio/video recordings yourself.

目次

Encrypted Recordings Vs Encrypted Compositions

Video Recordings and Video Compositions have separated encryption settings. This means that encryption can be activated independently on them. However, composing Recordings requires access to their raw media. As a result:

If you encrypt your Recordings, you will not be able to compose them.

If you need to compose your Recordings, you must store them unencrypted. However, those Recordings are only needed temporarily: as soon as the Composition is created they can be deleted permanently and irrevocably using Twilio's Video Recordings API.

How Encryption works

Twilio Video uses the standard WebRTC security architecture to guarantee that the live audio/video communication is cryptographically protected point-to-point.

When you enable Recording in your Group Rooms, audio/video is decrypted in memory before being stored securely in Twilio's cloud. Once stored, you can only access the decrypted recordings using your Twilio account credentials (your Account SID/Token or an API Key/API Key Secret).

When you enable encryption in your Video Recordings or Compositions, Twilio adds an additional layer of security: All the media files are encrypted as they are written to disk using the AES 128-bit symmetric encryption algorithm. Once encrypted, only a user who has the private key can decrypt the recordings.

Programmable Video uses an encryption mechanism provided by Amazon clients called “envelope encryption”. Here is how it works:

  • First, you create a public cryptography key pair. You provide to Twilio the public key, but you keep the private key secret and safe.
  • For each encrypted Recording or Composition, a one-time-use 128-bit envelope symmetric cryptographic key is generated and fed to an AES/CBC/PKCS5Padding cipher that encrypts the envelope payload (i.e the media content), and generates the protected file.
  • The envelope symmetric key is then cyphered itself with the provided public key and stored as part of the envelope. After that, the symmetric key is discarded and cannot be recovered by Twilio never again.

Only a user with the private key can decrypt the media content as the original AES symmetric key cannot be recovered. This mechanism guarantees that unencrypted media files are never persisted, and that Twilio cannot decrypt the envelope once it is generated.

Enabling Encryption in your Twilio account

Step 1: Generate a RSA key pair

First, generate an RSA PKCS#1 key pair. There are many different ways to do this, but the simplest one is to use 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 should be similar to 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. If you loose your private key you will never be able to decrypt any of the files stored using on 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 must 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 in the Runtime Public Keys management page. Press the button Create new Public key:

On the popup that opens, provide a friendly name for your public key. Then, copy the content of the public_key.pem file generated in step 1 and paste it into the PUBLIC KEY field. Press Create to create the Twilio Public Key:

The Twilio Public Key resource has an associated unique SID identifier with the form CRxx. Make note of this Public Key SID because you will need it later:

Step 3: Enabling Encryption in your Account

Enabling Encrypted Recordings

You have two options to enable encrypted Recordings:

Enabling Encrypted Recordings using the Twilio's Console

  • Open the Twilio's Console in your account or project.
  • Navigate to Programmable Video > Recordings > Settings.
  • Enable Encryption and specify the public key you uploaded in step 2.
  • Save your settings.
  • All recordings created thereafter will be encrypted.

Enabling Encryption using the Recording Settings API

Check the Recording Settings API documentation for detailed information on how to enable programmatically encrypted recordings.

Enabling Encrypted Compositions

You have two options to enable encrypted Compositions:

Enabling Encrypted Compositions using the Twilio's Console

  • Open the Twilio's Console in your account or project.
  • Navigate to Programmable Video > Compositions > Settings.
  • Enable Encryption and specify the public key you uploaded in step 2.
  • Save your settings.
  • All compositions created thereafter will be encrypted.

Enabling Encryption using the Composition Settings API

Check the Composition Settings API documentation for detailed information on how to enable programmatically encrypted compositions.

Decrypting your Recordings and Compositions

We suggest two decrypting alternatives:

  • Alternative 1: To use a Java utility program. See step 4 for instructions.
  • Alternative 2: To do it step by step using command line tools. See step 5 for instructions.

Step 4: Decrypting using a Java utility program

Here we provide instructions on how to write a Java program performing the decryption.

Step 4.1: Install Java Cryptography Extensions

If you are using Oracle's JRE, and due to legal restrictions, you need to install separately the JCE (Java Cryptography extensions). For doing so, just download the JCE, uncompress it and follow the instructions provided in the included README.txt file.

Step 4.2: Convert your private key to PKCS #8 format

JCE requires your private key to be in PKCS #8 format, for converting it, you just need to execute the following:

openssl pkcs8 -in private_key.pem -topk8 -nocrypt -out private_key_pkcs8.pem

In the above:

  • private_key.pem is the filename of the private key you generated in Step 1.
  • private_key_pkcs8.pem is the filename of your PKCS #8 private key.

Step 4.3: Decrypt using the Java utility program

The Java decrypting utility can be cloned from this GitHub project. After cloning, execute the following Maven command at its root folder:

mvn clean package

Once the compilation is completed, do the following:

java -jar target/twilio-media-decrypter.jar SKxx:API_SECRET SidToDecrypt private_key_pkcs8.pem decrypted-filename

In the above:

  • Replace SKxx with your Twilio API Key SID.
  • Replace SK_SECRET with the corresponding Twilio API Key Secret.
  • Replace SidToDecrypt with the SID of the Recording (e.g. RTXXXX) or Composition (e.g. CJXXXX) you want to decrypt.
  • private_key_pkcs8.pem is the filename of the PKCS #8 key you generated in step 4.2
  • decrypted-filename is the name of the file where you want to store your decrypted media data. You may wish to add the appropriate extension so that your media player recognizes it (e.g. .mkv for video recordings, .mka for audio recordings, .mp4 or .webm for Compositions, etc.)

Remember that this Java utility is provided for tutorial purposes and is not intended to be used in production applications.

Step 5: Decrypting using Command Line Tools

Step 5.1: Obtain the encrypted media URL

You can retrieve the media data of a specific Recording or Composition by fetching its /Media subresource. Any request to this resource will return a URL where the corresponding media file can be downloaded, you just need to do the following:

For Recordings

curl 'https://video.twilio.com/v1/Recordings/RTxx/Media' \
  -u 'SKxx:SK_SECRET'

For Compositions

curl 'https://video.twilio.com/v1/Compositions/CJxx/Media' \
  -u 'SKxx:SK_SECRET'

In the above:

  • Replace RTxx or CJxx with the corresponding Recording or Composition SID.
  • Replace SKxx with your Twilio API Key SID.
  • Replace SK_SECRET with the corresponding Twilio API Key Secret.

In both cases, as part of the answer to the request you will receive a redirect to a URL with the following structure:

https://com-twilio-video-recording.s3.amazonaws.com/ACxx/RTyy.mkv?X-Amz-Security-Token=zz

We call this the encrypted media URL.

Step 5.2: Download the encrypted file and collect its headers

Execute the following command replacing:

  • encrypted-media-url with the encrypted media URL obtained in step 5.1.
  • encrypted-filename with the filename where you want to store the encrypted data.

wget -S encrypted-media-url -O encrypted-filename

When a media file is cryptographically protected, a request to the encrypted media URL returns the encrypted file, along with an initialization vector and the encrypted one-time symmetric master key at the HTTP headers x-amz-meta-x-amz-iv and x-amz-meta-x-amz-key. To obtain both take a look to the output of the command above:

Resolving com-twilio-us1-video-recording.s3.amazonaws.com... 52.216.64.96
Connecting to com-twilio-us1-video-recording.s3.amazonaws.com|52.216.64.96|:443... connected.
HTTP request sent, awaiting response...
  HTTP/1.1 200 OK
  x-amz-id-2: 8x0XN6KDeLuhHLIe8fa58OdD3+xVyNgv2og/gpMOFpSqWc5JGV+aDpc7fJSCS9yGkwRtey+9lk8=
  x-amz-request-id: 5B3FBF0985E71EEC
  Date: Fri, 24 Nov 2017 14:11:30 GMT
  Last-Modified: Thu, 23 Nov 2017 16:47:17 GMT
  ETag: "d9e5869fc33019fc7fb055c0b705e105"
  x-amz-meta-x-amz-key: 0ZY1jiGSu/FlI4l1OnNFeWvWFXUOEQ2apv3/OtMFlwLO83bHlB44gbZe2SW6wOBs8UTsxC7bEnY+Gn2tdzp7ltzrKtBu7cfMzOxshABFiiJbCSBmOzUHs3OkU30Wi3Hq953SJJO+4W0DAINfhGiDlWxgIbjHegamneJ983DDpm+AyKa77jq5T+4LxJdOv5bqU4ioZKetv/OA987JZaetPVTr55uSmqr8SbsX9xmaIKjo7V6ivutwcCKWX9bvf1qxUu/ZohTmouL2MOocojNMMx5ovTX3QXLCGUwx6pOS83zqHNxmFhU2EHENCs5KNYL6GjhOwmoGyeQPS+pe8bPRFg==
  x-amz-meta-x-amz-unencrypted-content-length: 746518
  x-amz-meta-x-amz-matdesc: {}
  x-amz-meta-x-amz-iv: EmKjzVpvXC9rE6DJ00Xv7Q==
  Accept-Ranges: bytes
  Content-Type: application/octet-stream
  Content-Length: 746528
  Server: AmazonS3
Length: 746528 (729K) [application/octet-stream]
Saving to: 'encrypted-filename'

encrypted-filename               100%[=======================================================================>] 729.03K   789KB/s    in 0.9s    

2017-11-24 15:11:33 (789 KB/s) - 'encrypted-filename' saved [746528/746528]

As you can see, both headers x-amz-meta-x-amz-key and x-amz-meta-x-amz-iv are provided. Write down their values: you will need them.

Step 5.3: Obtain the AES encryption key and the initialization vector

The encrypted envelope symmetric key in x-amz-meta-x-amz-key is base64-encoded. We need first to decode it. For it, replace in, the command below, 0ZY1jiGSu ... with the value of the x-amz-meta-x-amz-key obtained in step 5.2

base64 -D <<< '0ZY1jiGSu ...' >> key.bin.enc

Now, we can decrypt the public key. For this, and assuming the private_key.pem file you created in step 1 is on the local folder, execute:

openssl rsautl -decrypt -inkey private_key.pem -in key.bin.enc -out key.bin

Now, we need to do the same steps with the initialization vector. Execute the following replacing the value of the x-amz-meta-x-amz-iv you obtained in step 5.2:

base64 -D <<< 'EmKjzVpvXC9rE6DJ00Xv7Q==' >> iv.bin

Now, the unencrypted AES key and the initialization vector are respectively in the key.bin and iv.bin files in your local folder.

Step 5.4: Decrypt your media files

Once the previous steps have been completed, you just need to execute the following for decrypting your encrypted file:

openssl enc -d -aes-256-cbc -in encrypted-filename -out decrypted-filename -K $(hexdump -v -e '/1 "%02X"' < key.bin) -iv $(hexdump -v -e '/1 "%02X"' < iv.bin)

In the above:

  • encrypted-file-name is the name of the file where you stored your encrypted media file in step 5.2
  • decrypted-filename is the name of the file where you want to store your decrypted media data. You may wish to add the appropriate extension so that your media player recognizes it (e.g. .mkv for video recordings, .mka for audio recordings, .mp4 or .webm for Compositions, etc.)
Luis Lopez
ページを評価:

ヘルプが必要ですか?

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

        
        
        

        フィードバックくださりありがとうございます!

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

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        ステップ1

        Get link

        Get a free personal referral link here

        ステップ2:

        Give $10

        Your user signs up and upgrade using link

        ステップ3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more