This series of posts is almost complete. We’ve created, imported, and exported AES keys and used them to encrypt and decrypt files, all inside a standard web browser using the new Web Cryptography API. All that’s left is to put it all together into a single web page. That’s what we’ll do now.
The page and code discussed in here are available on Github, and as a live page you can immediately try out.
I’m going to put together the simplest page I can think of. The top part will cover generating, importing, and exporting keys. The middle part will allow selection of a file on your computer and buttons to encrypt or decrypt that file, and the bottom part will have links to the results of the operations you’ve already done. Here’s a picture of the page:
As of now, this page works in the current version of Google Chrome, provided you turn on the “Enable Experimental Web Platform Features” flag, and in the current Firefox nightly build. It doesn’t work in Internet Explorer 11 because that implements an older version of the API and uses a vendor prefix for it. However, it should be fairly straightforward to modify this to work there.
Let’s take a look at the HTML:
<!DOCTYPE html>
<html>
<head>
<title>Symmetric Encryption</title>
<script src="crypto.js"></script>
</head>
<body>
<h1>Symmetric Encryption</h1>
<section id="key-management">
<input type="text" size="32" id="aes-key"/>
<button id="generate-key">Generate Random AES Key</button>
</section>
<section id="encrypt-and-decrypt">
<input type="file" id="source-file"/>
<button id="encrypt">Encrypt File</button>
<button id="decrypt">Decrypt File</button>
</section>
<section id="results">
Download results:
<ul id="download-links">
</ul>
</section>
</body>
</html>
It’s pretty simple. The head loads the JavaScript that does all the work. The key-management section allows you to enter a hex encoded key, or click a button to generate a random one. The encrypt-and-decrypt section is where you select a file to operate on and click a button to perform the operation, and the results section contains a list of links to download the results of each operation.
The JavaScript is where all the work happens. We don’t want to set up any click handlers until the page is ready, so the content of crypto.js is all wrapped in a function that runs when the page is ready:
document.addEventListener("DOMContentLoaded", function() {
"use strict";
if (!window.crypto || !window.crypto.subtle) {
alert("Your current browser does not support the Web Cryptography API! This page will not work.");
return;
}
// rest of code goes here
});If the browser doesn’t support web.crypto.subtle this shows the user a message and does nothing else. Otherwise, it continues by attaching listeners to each button:
document.getElementById("generate-key").addEventListener("click", generateAKey);
document.getElementById("encrypt").addEventListener("click", encryptTheFile);
document.getElementById("decrypt").addEventListener("click", decryptTheFile);
And all the work happens in the three listeners. First, the one that generates a new key on demand:
function generateAKey() {
window.crypto.subtle.generateKey(
{name: "AES-CBC", length: 128}, // Algorithm using this key
true, // Allow it to be exported
["encrypt", "decrypt"] // Can use for these purposes
).
then(function(aesKey) {
window.crypto.subtle.exportKey('raw', aesKey).
then(function(aesKeyBuffer) {
document.getElementById("aes-key").value = arrayBufferToHexString(aesKeyBuffer);
}).
catch(function(err) {
alert("Key export failed: " + err.message);
});
}).
catch(function(err) {
alert("Key generation failed: " + err.message);
});
}We’ve seen code like this in the previous posts. The only new thing here is that once a key is generated it’s exported, converted to a hex string, and that string placed in the input box for use by future operations. Each operation uses the value in that input box instead of a saved key object so that the user can put new keys in at any time. Exporting the key and later importing it to use it is inefficient, but not a big deal.
Actually encrypting the file is quite a bit longer:
function encryptTheFile() {
var sourceFile = document.getElementById("source-file").files[0];
var aesKeyBytes = hexStringToByteArray(document.getElementById("aes-key").value);
var aesKey; // To be created below
var reader = new FileReader();
reader.onload = function() {
var iv = window.crypto.getRandomValues(new Uint8Array(16));
window.crypto.subtle.encrypt(
{name: "AES-CBC", iv: iv},
aesKey,
new Uint8Array(reader.result)
).
then(function(result) {
var blob = new Blob([iv, new Uint8Array(result)], {type: "application/octet-stream"});
var blobUrl = URL.createObjectURL(blob);
document.getElementById("download-links").insertAdjacentHTML(
'beforeEnd',
'<li><a href="' + blobUrl + '" download="' + sourceFile.name + '.encrypted">Encryption of ' + sourceFile.name + '</a></li>'
);
}).
catch(function(err) {
alert("Encryption failed: " + err.message);
});
};
window.crypto.subtle.importKey(
"raw",
aesKeyBytes,
{name: "AES-CBC", length: 128},
true,
["encrypt", "decrypt"]
).
then(function(importedKey) {
aesKey = importedKey;
reader.readAsArrayBuffer(sourceFile);
}).
catch(function(err) {
alert("Key import and file read failed: " + err.message);
});
}
Let’s take this code a step at a time. First we create the variables that will be used in each further step: the sourceFile (from the file selector input box), the aesKey (that will be imported from the aesKeyBytes pulled out of the input box in the page), and the FileReader object reader.
Next we tell what should happen when the file has been read in. That’s identical to what we did in the last post except for inserting a list element in the web page with a link to the blobUrl we create. The steps are: create a random initialization vector iv, encrypt the data that was read in with the aesKey and the iv, then create a blob with the iv followed by the encrypted data and build a URL for that blob. The only problem here is that we haven’t seen any value assigned to aesKey yet.
We need to import the bytes for the AES key into aesKey, and that’s the last step in the code, though it runs before the file has been read. Once the imported key is ready, we kick off the FileReader reader. When it’s done, the handler described in the last paragraph takes over and finishes the job. The use of a callback when reading a file means that the steps are defined out of the order they will actually run. If the FileReader object was a Promise, it might be clearer.
The decryption code is much like the code above, except it pulls the iv out of the beginning of the encrypted file instead of creating a new random one. Again, this was covered in more detail in the last post:
function decryptTheFile() {
var sourceFile = document.getElementById("source-file").files[0];
var aesKeyBytes = hexStringToByteArray(document.getElementById("aes-key").value);
var aesKey; // To be created below
var reader = new FileReader();
reader.onload = function() {
var iv = new Uint8Array(reader.result.slice(0, 16));
window.crypto.subtle.decrypt(
{name: "AES-CBC", iv: iv},
aesKey,
new Uint8Array(reader.result.slice(16))
).
then(function(result) {
var blob = new Blob([new Uint8Array(result)], {type: "application/octet-stream"});
var blobUrl = URL.createObjectURL(blob);
document.getElementById("download-links").insertAdjacentHTML(
'beforeEnd',
'<li><a href="' + blobUrl + '" download="' + sourceFile.name + '.decrypted">Decryption of ' + sourceFile.name + '</a></li>'
);
}).
catch(function(err) {
alert("Decryption failed: " + err.message);
});
};
window.crypto.subtle.importKey(
"raw",
aesKeyBytes,
{name: "AES-CBC", length: 128},
true,
["encrypt", "decrypt"]
).
then(function(importedKey) {
aesKey = importedKey;
reader.readAsArrayBuffer(sourceFile);
}).
catch(function(err) {
alert("Key import and file read failed: " + err.message);
});
}There’s nothing here that wasn’t seen just above or in the prior blog post.
All that’s left are a couple of utility functions to convert between hex encoded strings and arrays of bytes. We saw them two posts ago, but here they are again for completeness:
function arrayBufferToHexString(arrayBuffer) {
var byteArray = new Uint8Array(arrayBuffer);
var hexString = "";
var nextHexByte;
for (var i=0; i<byteArray.byteLength; i++) {
nextHexByte = byteArray[i].toString(16); // Integer to base 16
if (nextHexByte.length < 2) {
nextHexByte = "0" + nextHexByte; // Otherwise 10 becomes just a instead of 0a
}
hexString += nextHexByte;
}
return hexString;
}
function hexStringToByteArray(hexString) {
if (hexString.length % 2 !== 0) {
throw Error("Must have an even number of hex digits to convert to bytes");
}
var numBytes = hexString.length / 2;
var byteArray = new Uint8Array(numBytes);
for (var i=0; i<numBytes; i++) {
byteArray[i] = parseInt(hexString.substr(i*2, 2), 16);
}
return byteArray;
}The entire example is available on GitHub. I hope you find it a useful starting point for using this new API. It worked well for me, encrypting or decrypting a 100MB file in about a second.
Of course, speed doesn’t help if it’s wrong, so I used OpenSSL to check the results. It was kind of a pain because OpenSSL wants the IV as a command line parameter and only the rest of the encrypted payload as its input. But I did managed to do that and it worked. Here are the steps.
My original file is called original, the key from the web page is 9ad96448523485f6f2936c9259eca6e3, and the encrypted version from the web page is called original.encrypted. Here’s the file listing:
-rw-r--r-- 1 charles domain users 105235836 Jul 14 15:13 original
-rw-r--r-- 1 charles domain users 105235856 Jul 14 15:32 original.encryptedNote that the encrypted file is 20 bytes longer than the original one. That’s due to adding a 16 byte initialization vector, and padding it to be a multiple of 16 bytes long. To use OpenSSL I need to separate the IV from the rest of the ciphertext first, using the intuitive command:
head -c 16 original.encrypted | od -t x1
That x1 instead of just x (for hex) is vital! I left it off at first and got the bytes scrambled because it processed 16-bit words instead of separate bytes. This shows the IV in hex as:
0000000 99 3f 00 6e 1c 30 64 72 5c 7b 35 fe 96 a9 44 25
The IV is just the actual digits starting with 99, with the spaces removed. Now we need to get the raw ciphertext (with the IV stripped from the start):
tail -c 105235840 original.encrypted > raw_ciphertext
That magic number 105235840 is just the size of original.encrypted less 16 bytes for the leading IV. Finally we can use OpenSSL. I’ve stretched out over two lines for a bit more clarity:
openssl enc -aes-128-cbc -d -K 9ad96448523485f6f2936c9259eca6e3 \
-iv 993f006e1c3064725c7b35fe96a94425 -in raw_ciphertext -out plaintext
The resulting plaintext is identical to original, checked with cmp original plaintext.
This ends the series of posts on Symmetric Encryption in the browser. Next time I’ll start looking at using public key cryptography with this API. The basic operations don’t look too hard, but compatibility with existing standard file structures may be really tough. We’ll see.
Charles Engelke's Blog 