How to Create a Custom File Input (For Use With the HTML5 File APIs)

I’m working on an HTML/JS application that lets users work with local files directly in the browser, and I’m using some new HTML5 APIs to access local files. It works great (in Chrome and Firefox, anyway — see note below), however my UI calls for a custom file input rather than the default (and usually pretty ugly) button-and-path input. Fortunately, customization is easy in this case. The trick is to create your own UI treatment (in my case, just a link), then use the click() function on a hidden file input to bring up the file dialog.

In Firefox, you can use the display:none style as noted in this Mozilla Developer Network documentation, however this won’t work in Chrome or Safari (although FileReader is currently not supported in Safari, you might as well think ahead for when it is). A better way of doing it, therefore, is to use visibility:hidden.

The only problem is that when something is hidden using its visibility property, it’s still actually in the DOM, and space is therefore allocated for it even though you can’t see it. If you want to get your file input completely out of the way, therefore, you can use something like this:

<input type="file" id="fileInput" onchange="handleFiles(this.files)" style="visibility:hidden;position:absolute;top:-50;left:-50"/>

Your file input will still be in the DOM (even though it’s hidden and off-screen), however it won’t take up any visual space.

Here’s the full HTML code:

<a href="javascript:onLoad();">Load a File!</a>
<input type="file" id="fileInput" onchange="handleFiles(this.files)" style="visibility:hidden;position:absolute;top:-50;left:-50"/>

And here’s the JavaScript code:

function onLoad() {

function handleFiles(files) {
    var file = files[0];
    var reader = new FileReader();
    reader.onload = onFileReadComplete;
function onFileReadComplete(event) { 
  // Do something fun with your file contents.

Note that this code is only going to work in current versions of Chrome and Firefox, but is expected to work in future versions of IE (10) and Safari (6).

How to Download Data as a File From JavaScript

I’m currently working on an HTML/JavaScript application that allows you to author content entirely on the client. I want to let users download that content and save it locally, but without bouncing it off a server. After some trial and error, I have it working fairly well using a data URI. Rather than explain it, it’s probably easiest just to show the code:


<a href="javascript:onDownload();">Download</a>

JavaScript code:

function onDownload() {
    document.location = 'data:Application/octet-stream,' +

The only limitation is that I can’t figure out a way to give the downloaded file a name (and have concluded that it’s not currently possible, though I’m happy to be proven wrong). I’ve only tested the code in Safari and Chrome, and in both cases, the file name defaults to "download" (with no extension). All the data is in the file, but it’s not a very intuitive experience for the end user.

I’ll be releasing the application shortly which should demonstrate why downloading data directly from the client can be useful. In the meantime, I’m curious if this is something any of you might use, and if so, if you think the file name issue should be fixed.

Let me know in the comments.

A Summary of the WebKit Developer Tools

I use the WebKit developer tools extensively in both Chrome and Safari, but it occurred to me the other day that I was probably only using a fraction of their capabilities. After researching them more fully, I was pleasantly surprised by how comprehensive they are, so I decided to make a quick list of all the major developer-oriented features of WebKit that I know of. Even if you use the Chrome/WebKit dev tools regularly, there’s a good chance you’ll find one or two things below you haven’t been leveraging.

Continue reading…

Creating a Loading Spinner Animation in CSS and JavaScript

Update (12/20/2011): Now works in Firefox as well as Chrome and Safari.

Since I’m not a very good designer, I usually try to do as much styling, design, and graphics in code as I can. For instance, when I wrote this mobile compass application in HTML, I did all the graphics programmatically using Canvas and CSS.

I’m now working on a project that requires one of those loading spinner animations that Apple seems to have made famous, so naturally, I started looking into ways to create one purely in code and/or CSS (no external assets). Fortunately, I found a great post on the Signal vs. Noise blog demonstrating exactly what I wanted to do. However, I decided to take it one step further, and write some JavaScript to generate both the required CSS and the HTML. The advantage of generating everything dynamically is that you can configure things like the size, color, and the number of bars in the animation at runtime.

Here’s an example of some randomly generated loading spinner animations which are 100% CSS and HTML generated by JavaScript (Chrome and Safari only for now). If you’re interested in the code, here’s the original CSS from Signal vs. Noise, and below is my port to JavaScript (view the source of the demo to see how to use it). It only works in WebKit-based browsers for the time being, but I’ll update it as browser capabilities get better. It works in WebKit-based browser, and in Firefox.

Check out the example.

var Spinner = {
  SPINNER_ID: '_spinner',
  prefix: (navigator.userAgent.indexOf('WebKit') != -1) ? 'webkit' : 'moz',
  getSpinner: function(size, numberOfBars, color) {
    if (document.getElementById(this.SPINNER_ID) == null) {
      var style = document.createElement('style');
      style.setAttribute('id', this.SPINNER_ID);
      style.innerHTML = '@-'+this.prefix+'-keyframes fade {from {opacity: 1;} to {opacity: 0.25;}}';
    var spinner = document.createElement('div'); = size; = size; = 'relative';
    var rotation = 0;
    var rotateBy = 360 / numberOfBars;
    var animationDelay = 0;
    var frameRate = 1 / numberOfBars;
    for (var i = 0; i < numberOfBars; ++i) {
      var bar = document.createElement('div');
      spinner.appendChild(bar); = '12%'; = '26%'; = color; = 'absolute'; = '44.5%'; = '37%'; = '1';'-'+this.prefix+'-border-radius', '50px', null);'-'+this.prefix+'-box-shadow', '0 0 3px rgba(0,0,0,0.2)', null);'-'+this.prefix+'-animation', 'fade 1s linear infinite', null);'-'+this.prefix+'-transform', 'rotate('+rotation+'deg) translate(0, -142%)', null);'-'+this.prefix+'-animation-delay', animationDelay + 's', null);
      rotation += rotateBy;
      animationDelay -= frameRate;
    return spinner;

Loading Data Across Domains with JavaScript

I’m working on a project now that makes heavy use of XHR (XMLHttpRequest) to load data from a server. I’m writing the HTML/JS portion of the application on my local machine, but my server development environment is on a remote server under a different domain. Typically cross-domain XHR request aren’t allowed due to browser security restrictions, however there are two easy work-arounds:

  1. JSONP
  2. Cross-Origin Resource Sharing


JSONP gets around the same origin policy by loading JavaScript from another domain into a dynamically generated <script> tag (script tags are not subject to the same origin policy which is what enables things like ads to be served from different domains). In your request (formed as the src attribute of the script tag), you typically specify a callback function that you have already defined in your application. The JavaScript that gets loaded into the dynamically generated script tag will call the specified function, passing in the requested JSON data.

(Note that JSONP requests are probably best handled by robust frameworks like the jQuery.getJSON() function.)

I’ve used JSONP in the past for things like this prototype client-side news reader, but the project I’m working on now uses XML as well as JSON, so I decided to use a different approach.

Cross-Origin Resource Sharing

Cross-origin resource sharing is similar to cross-domain policy files in the Flash word, but they are done through HTTP headers. The specification defines several different headers, however the only one I’ve needed so far is the response header Access-Control-Allow-Origin. Allowing my server to share resources with my local machine was as easy as adding the following line of PHP code before writing to the output buffer:

header('Access-Control-Allow-Origin: http://seeker.home');

(Seeker is the name of my development machine, named after the excellent Jack McDevitt novel.)

Of course, once I move the client-side portion of my application (the HTML, JS, and CSS files) to my server, I can delete or comment this line out since the application will be served from the same domain from which it needs to request data. In the meantime, however, it’s made local development much easier.

Cross-origin resource sharing is part of the XMLHttpRequest Level 2 specification, and is supported in all modern browsers.

Adding prependChild to Element

If you’ve ever done much DOM scripting, you have almost certainly used the appendChild function on Element. For instance, you might have done something like this:

var hello = document.createElement('p');
hello.innerText = 'Hello, world!';

Nice and easy, but what if you want to prepend the child rather append? You could do this:

var hello = document.createElement('p');
hello.innerText = 'Hello, world!';
var myDiv = document.getElementById('myDiv');
myDiv.insertBefore(hello, myDiv.firstChild);

Or, you could just add a prependChild function to Element, like this:

Element.prototype.prependChild = function(child) { this.insertBefore(child, this.firstChild); };

Just make sure that the code above evaluates early on in your application initialization, and start prepending all you want. (Of course, if you’re using jQuery, prepend is already well in hand.)

My Thoughts on Flash and HTML (as Expressed in an Email to “Tech News Today”)

I’m a big fan of the video and podcast Tech News Today. It’s one of the best technology shows I know of, and I seldom miss an episode. As some of you know, I sent them an email yesterday about our recent announcements around Flash and HTML, and they were kind enough to read some if it on-air. It was way too long for them to read in its entirety, so I figured I’d post the whole thing here.

As someone who has worked on the Flash Platform at Adobe for the last nine years, I just wanted to provide some additional context around yesterday’s announcement. Your coverage was very good, so no complaints, but I feel like it’s worth emphasizing a few things.

Part of Adobe’s story is enabling cross-platform solutions, but since Flash has never been supported on iOS, we weren’t able to deliver on that vision in the context of mobile browsers. With mobile browsers as good as they are now (the ICS browser looks amazing, and mobile Safari has always been awesome), it just makes more sense to use HTML.

In the context of installed applications, however, our story is stronger than ever. We recently released AIR 3 which is an extremely solid option for delivering installed applications through app stores across devices. Installed mobile applications is an area where we have been very successful delivering on our cross-platform vision, so that’s where we’re going to invest. Additionally, I think that model more closely matches the way we use our devices; I think mobile browsers are primarily used for accessing content, and the tendency is to use installed apps for more interactive content like applications and games.

Another point I want to make is in response to Sarah’s comment yesterday about Flash working better on some devices than others. That’s true. Getting Flash to work consistently across all the chipsets that we support (and with all the different drivers out there — some of which are better implemented than others) is a huge amount of work, and requires a lot of engineering resources. At some point, we had to ask ourselves if we wanted to be the kind of company that continues to use resources to pursue something we weren’t convinced made sense just because it’s what we’ve always done, or if we wanted to be more forward thinking. I think we absolutely made the right decision.

It’s also worth pointing out that we’re still investing heavily in Flash in the areas where it makes more sense like installed mobile and desktop applications, and the desktop browser. Specifically, the Stage3D APIs we introduced in AIR 3 are going to provide an in-browser gaming experience like nobody has ever seen (look for videos of Unreal running in the browser), and the new APIs for hardware accelerated video are going to mean higher quality video that uses less CPU and battery. These are areas that HTML5 has not yet fully addressed, so Flash can lead the way. We will continue to use Flash for doing things that HTML can’t, and for the things that HTML can do, we will embrace it.

That brings me to my last point: I think there’s this perception out there that Adobe dislikes HTML, and that yesterday was somehow a bitter concession. As someone inside the company, I can tell you that there are a lot of us who are very excited about what we can do with HTML5. Personally, I’ve been researching and working on HTML projects for quite some time at Adobe, and I’ve been working with a lot of very smart people who are as passionate about it as I am. There are definitely people out there (both inside Adobe and outside) who are passionate just about Flash, but I think it’s more accurate to say that the overwhelming majority of us are simply passionate about the web, and about building awesome experiences. Flash has always been about providing functionality that HTML couldn’t, however now that HTML5 can provide a lot of that functionality, we’re going to have a lot of fun seeing what we can do with it.

So in summary, look for Adobe to continue to push Flash forward in areas that HTML doesn’t yet address, to push HTML forward with contributions to WebKit and tooling, and to provide cross-platform solutions in whatever technology makes the most sense.

If you want to hear it read on-air, it’s at the 45:00 mark in the video below.

Building an Offline Mobile Web Application

If you’re interested in building a mobile web application that works offline and is virtually indistinguishable from a native installed application, this post explains most (if not all) of what you need to know. (To see an example of an offline mobile web application, see the post, Porting an AIR Application to HTML.)

What is an Offline Mobile Web Application?

An offline mobile web application has the following properties:

  • It’s written in HTML, CSS, and JavaScript, and it’s served from a web server.
  • It functions without an internet connection.
  • When users save the application to their home screen, they get a custom icon and start-up image (the image that is displayed briefly on iOS while the app is loading and initializing).
  • The application can be updated over the network just by opening it (as opposed to going through an app store).

The Components of an Offline Mobile Web Application

There are four primary pieces of functionality that offline mobile web applications need:

  1. Configuration. For iOS devices, there are a few tags you can add to your application to make it look and act much more like a native application.
  2. Custom icons and start-up images. To fit in with native applications, offline web applications should specify custom icons and start-up images for iOS.
  3. Caching. Offline web applications use the HTML5 application cache to make themselves available offline.
  4. Updating. Offline mobile web applications need to update the local cache when the application has changed on the server.


On iOS, you can use several different meta tags to make your mobile web application look and feel much more like a native application. For instance, to get rid of the browser chrome when your application is launched from the home screen (in other words, to tell iOS to use a minimal web control rather than full-blow Safari to display your application), use the following tag:

<meta name="apple-mobile-web-app-capable" content="yes" />

To customize the look of the iOS status bar, you can use a meta tag with the "name" attribute set to "apple-mobile-web-app-status-bar-style". In my HTMLCompass example, I wanted the status bar to be as unobtrusive as possible, so I configured it to be black and translucent like this:

<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent"/>

Finally, it’s important to configure Safari’s viewport using a meta tag with the name "viewport". In order to configure the viewport properly for my HTMLCompass example (including preventing the user from zooming in and out of the application), I use the following tag:

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0"/>

For more information on configuring web applications on iOS, see Apple’s document, Configuring Web Applications. For a detailed description of everything you can do with your application’s viewport, see Viewport Settings for Web Applications.

Custom Icons and Start-up Images

Creating custom icons for your application is an important part of making it look like it belongs installed on a device. It’s not strictly necessary, but default icons (or icons derived from screenshots) will not give your application a high-quality, polished look and feel. (Note that I believe this is currently only supported on iOS devices; Android seems to use your "favicon" as your application’s icon, instead.)

Specifying custom icons is as easy as including one or more link tags in the <head> section of your application. The only trick is to make sure that you specify different icons for different screen resolutions. On iOS devices, that currently means icons for pre-retina screens (iPhone 3G and 3GS), retina displays (iPhone 4 and iPhone 4S), and the iPad. Below are the tags referencing the various icons for my HTMLCompass example:

<!-- Home screen icons -->
<link rel="apple-touch-icon" sizes="57x57" href="icons/apple-touch-icon-57x57.png" />
<link rel="apple-touch-icon" sizes="72x72" href="icons/apple-touch-icon-72x72.png" />
<link rel="apple-touch-icon" sizes="114x114" href="icons/apple-touch-icon-114x114.png" />

Specifying start-up images is almost as easy, however in addition to taking different screen resolutions into account, you also have to take into account different orientations for the iPad (iPhones and iPods can’t start applications in landscape mode). Below are tags referencing the three start-up images I created for my HTMLCompass example (note that I didn’t bother making one for the iPhone 3G or 3GS):

<!-- iPad -->
<link rel="apple-touch-startup-image" href="starts/ipad-landscape.jpg" media="screen and (min-device-width: 481px) and (max-device-width: 1024px) and (orientation:landscape)" />
<link rel="apple-touch-startup-image" href="starts/ipad-portrait.jpg" media="screen and (min-device-width: 481px) and (max-device-width: 1024px) and (orientation:portrait)" />
<!-- iPhone (retina) -->
<link rel="apple-touch-startup-image" href="starts/iphone-retina.jpg" media="screen and (max-device-width: 640px)" />

(Note that the size of these images must be exactly correct for them to function as expected.)

There’s a little more to know about configuring and specifying application icons. For instance, iOS automatically makes your icons appear three-dimensional and glossy by applying filters, however if you decide that you’d rather add such effects yourself, it’s possible to specify that your icons are "precomposed." For more information, see Apple’s documentation entitled Configuring Web Applications.


Caching your application so that it’s available for offline use is surprisingly easy. You essentially place a manifest file on your server which lists all the files that you want saved to the application cache. Below is the manifest file for

# Version: 1.04


You then need to reference the manifest file in your application’s <html> tag, like this:

<html manifest="compass.manifest">

That’s essentially it. For more information on the syntax of your manifest file (which supports additional functionality), see the cache manifest syntax section of the WHATWG offline web application specification.

Here are three important tips that will make working with cached web applications smoother:

  1. Don’t forget to configure the MIME type on your web server (as described here). If you don’t map the extension of your manifest file to the MIME type "text/cache-manifest," you will not get the caching behavior you’re expecting.
  2. I recommend adding a version comment to your manifest file (see example above). The version comment has no official use, however just making a change to your manifest file will cause your application to be re-downloaded. For example, if I change my index.html page without changing my manifest file, the local cache on the client will not be updated. After changing my index.html file, I can increment the version number in my manifest file which will cause the change to index.html to be picked up.
  3. Once your application has been cached, the development process becomes more difficult. Specifically, after you make a code change, it will not show up in your browser until you update the cache with the new version. Rather than having to make a change to your manifest file in order to pick up your application changes, the best solution I’ve found is to simply change the reference to your manifest file in your <html> tag so that it points to something nonexistent. For instance, when I’m developing, I change the reference to my manifest file to compass.manifest.TODO. That causes a 404 which causes the application to be reloaded from the server rather than loaded from the cache. (The reason I append "TODO" is so I’ll find it while performing one last check of my code before checking it in.)


Now that you have your application caching, you need to know how to update it. There are four simple steps to updating an offline web application:

  1. Change your manifest file so the browser knows to grab the new version (see previous section).
  2. Listen for an event letting you know that the new version of your application has been downloaded and is ready.
  3. Swap the old version for the new version.
  4. Reload the page (optional).

Telling clients that a new version of your application is ready is as easy as making a change to your manifest file (updating the "version" comment, most likely). In order to be notified of when the new version is downloaded and the cache is ready to be updated, simply listen for the updateready event on the applicationCache like this:

window.applicationCache.addEventListener('updateready', ...);

Inside your event handler, tell the application cache to update itself like this:


Updating your application cache is an asynchronous operation meaning
it happens in the background while the old version of your application loads, renders, and executes. That means even though you have just updated the cache with the new version of your application, the user will still see the old version. You can either do nothing (so that users will see the new version the next time they use the app), or you can programmatically refresh the page with code like this:


To put it all together, my HTMLCompass example has a function called checkForUpdate which looks like this:

function checkForUpdate()
  if (window.applicationCache != undefined && window.applicationCache != null)
    window.applicationCache.addEventListener('updateready', updateApplication);

function updateApplication(event)
  if (window.applicationCache.status != 4) return;
  window.applicationCache.removeEventListener('updateready', updateApplication);

There are several other events thrown by the application cache that you can hook into in order to achieve various functionality. For instance, when your code detects that a new version of your application is available, you may choose to show the user a notification or even a progress bar indicating how much is still left to download. For a full list of application cache events, see the event summary section of the offline web application specification.

Porting an AIR Application to HTML

Check out on your device (see requirements below).

I recently wrote a simple compass application in AIR to demonstrate the use of ANEs (AIR Native Extensions) for accessing sensor data that we don’t have API support for yet. When I heard that iOS 5 brought orientation APIs to mobile Safari, I decided to port the application from AIR to HTML in order to see what the development experience would be like.

The result is Using Canvas, CSS, and about 600 lines of JavaScript (about half of which are purely for drawing and rendering), I was able to build a fairly nice and functional application with the following features:

  • The UI is dynamically drawn using Canvas with no bitmap assets at all which means it scales perfectly to any size screen (you can test this by resizing your browser window; note how the direction and degree text fields change their size and location based on screen size and orientation). I had to write the scaling code myself which I probably could have mostly gotten for free had I used SVG, so that might be my next experiment.
  • Since it works on any size screen, it will also work with any orientation (although for best results, turn orientation lock on).
  • The needle animation is partially hardware accelerated which makes it very smooth on iOS devices, and pretty smooth on Android (though Android did require some extra work). By "partially hardware accelerated," I mean that there’s an animation loop that uses both JavaScript and CSS transformations for animation and easing.
  • Offline support. Once you’ve gone to, the application is saved for offline use which means you can go back to the URL even if you don’t have an internet connection.
  • Home screen support. If you add the application to your device’s home screen, you will get offline support, a custom icon, and start-up images on iOS (the images that display briefly while your application is loading). In fact, the experience is almost indistinguishable from that of a native application.
  • Desktop testing mode. From the beginning, I architected the application so that it would be functional on the desktop as well as mobile devices. Of course, desktop machines typically don’t have a compass or a gyroscope, so you have to click on the compass dial to set north, but enabling desktop mode allowed me to do about 80% of my development on my Mac where the workflow is much smoother than the workflow between a development machine and a mobile device.

Unfortunately, HTMLCompass won’t work on all devices. Since compasses and gyroscopes are relatively new to phones and tablets, comprehensive orientation APIs aren’t widely supported by browsers yet. On iOS devices, support was just added with iOS 5, and on Android, I found I was able to reliably calculate north using the gyroscope APIs in Honeycomb (specifically Android versions 3.1 and 3.2.2). Here are all the devices I successfully tested on:

  • iPhone 4 with iOS 5.
  • iPad 2 with iOS 5.
  • Motorola Xoom with Android 3.2.2.
  • Galaxy Tab 10.1 with Android 3.1.

Below are some miscellaneous observations I jotted down during development. Let me know in the comments if you have any questions or thoughts.

  • I’m definitely not new to JavaScript programming, however after doing so much ActionScript lately, I did miss the expressiveness (strongly typed variables, function return types, etc.) of ActionScript. I also missed the compilation step from the perspective of finding bugs, however from the perspective of productivity/workflow, I didn’t miss compilation at all. In general, I think I’m happy programming in either ActionScript or JavaScript; they have different strengths and weaknesses which, in my mind, largely balance each other out.
  • I initially did the needle rotation entirely in JavaScript and found that I couldn’t get it very smooth at all. Introducing CSS transformations allowed me to offload most of the animation to the GPU which improved performance immensely. The takeaway: do as much movement/animation with CSS as you can. I’m also looking forward to having more access to hardware rendering in the future.
  • On iOS, I use the incoming orientation events as my rendering/animation loop which works really well. On Android (or at least on my Xoom), the alpha values of the DeviceOrientationEvent are too erratic, resulting in very choppy animation. In order to smooth it out, I created a specific rendering loop which allowed me to average the alpha values out over more time. The animation still isn’t as smooth on Android as it is on iOS, but it’s not bad.
  • I built most of the application while testing almost exclusively in Safari (desktop and mobile) which was a mistake. The first time I tested in Chrome and Android, the app wasn’t even close to working. It’s inconvenient to iterate in several browsers at once, but that’s probably the way to go. When I build my next HTML app, I will test in all the target browsers as I’m developing, and where I find differences, I’ll do my best to encapsulate them right then and there. Waiting until you’re "finished" only find out you’re actually only about half finished is a big disappointment. (I have to say that I was surprised by the number or browser inconsistencies I found — even across WebKit-based browsers. I’m definitely looking forward to this gap narrowing in the future.)
  • Ironically, Apple has done a lot more to enable web applications on mobile devices than Google. I expect that web application support will be more of a focus in future versions of Android, but as of right now, I find web application support to be far superior on iOS (as well as the browser itself).
  • Because of the gyroscope built into MacBooks, Chrome on Mac supports the DeviceOrientationEvent. Since MacBooks don’t have compasses, however, the z rotation cannot be tracked which means the alpha value is null.
  • I still haven’t found an HTML/JavaScript editor/IDE that I’m really happy with. Any suggestions?

I learned quite a lot about developing mobile HTML5 applications — most of it through trial and error — so I’m planning on following up this post with several tutorials and how-tos which will hopefully save others from many of the challenges I encountered.

Secure Data Persistence with AIR 3

AIR 3 offers two new capabilities that can make data persistence much more secure than what was possible with previous versions of AIR. If your AIR application persists information like credentials or sensitive relational data that must remain secure, this article is for you.


The new flash.crypto.generateRandomBytes function provides a way to generate far more random data than was previously possible. As you probably already know, functions like Math.random are known as pseudorandom number generators because they rely on relatively small sets of initial data (like timestamps). Bytes generated in such a manner are insufficient for use as encryption keys because if the random number generation algorithm is known (and you should always assume that it is), and the mechanism for seeding it is known and constrained, it isn’t hard for an attacker to guess the encryption key and gain access to your data.

The new generateRandomBytes function uses a much more random (and therefore, much more secure) method for generating random bytes. Rather than implementing our own algorithm, the runtime uses the underlying operating system’s random byte generation function. The table below shows which function is used on each platform:

Operating System Function
Windows CryptGenRandom()
Mac OS X /dev/random
Linux /dev/random
Android /dev/urandom
iOS SecRandomCopyBytes()

The natural question at this point is what makes the operating systems’ random byte generation implementations so secure — or, put another way, how is the OS able to generate random data which is more cryptographically secure than Math.random? The answer is something called an entropy pool. An entropy pool is essentially a collection of randomness. When a process needs random bytes, they can be taken from the entropy pool through one of the functions listed above, and when a process believes it has random data, it can choose to add those bytes to the entropy pool. Processes can obtain random data in several ways:

  • Hardware jitter (deviations caused by things like electromagnetic interference or thermal noise).
  • Mouse movements and/or the time between keystrokes.
  • Unpredictable hardware events like disk head seek times, or network traffic.
  • A hardware random number generator.

(Now is a good time to state that it’s probably more correct to say that an entropy pool contains unguessable data as opposed to truly random data, but in the world of encryption, the two amount to essentially the same thing.)

So now that you have access to unguessable bytes, what can you do with them to make your data more secure? The most obvious use for the new generateRandomBytes function is probably the creation of encryption keys. The database implementation embedded inside of the AIR runtime supports encrypted database files, and the quality of the encryption is largely based on the quality of your encryption key. The generateRandomBytes function gives you a cryptographically secure way to generate an encryption key, and the EncryptedLocalStore API gives you a secure method for storing it (more on this below). Other uses of the generateRandomBytes function include generating session identifiers, GUIDs, and salt to be used in hashes (salt is additional data added to the data you want to hash which makes looking the hash up in rainbow table much less feasible).

Mobile Encrypted Local Store

Update (11/3/2011): If you’re having trouble getting ELS to work in the iOS emulator or in “fast packaging” mode, add the following to your compiler arguments: -swf-version=13

A second feature in AIR 3 which can make data persistence more secure is the introduction of the mobile EncryptedLocalStore (ELS) API. ELS has been available for the desktop profile since 1.0, but AIR 3 is the first version which makes it available on mobile.

ELS provides a secure storage mechanism implemented by the underlying operating system. On Windows, ELS uses DPAPI, and on OS X, ELS uses Keychain services.

The new mobile implementations of ELS require some additional explanation. On iOS, ELS uses Keychain services just as it does on OS X, however Android does not provide a encrypted storage service for the runtime to leverage. Data is therefore "sandboxed" rather than encrypted. In other words, it is stored in a secure, isolated location (inaccessible to other processes), but since the data isn’t actually encrypted, if an attacker has access to the physical device, or if a user has rooted his or her device, it is possible for the data to be compromised. According to the internal ELS specification:

On Android, ELS can guarantee that on a non-rooted device in the hands of an authorized user, ELS data of an AIR application will not be accessible/modifiable by any other application (AIR or native) running on the device.

It’s possible that Android will provide a more secure storage service in the future, and we can simply swap out our implementation, however for the time being, it’s worth noting that the Android implementation lacks the additional step of encryption on top of isolation.

So what kinds of data should mobile developers store with ELS? The same data that you would store in desktop applications. Namely:

  • Encryption keys (the sequence of random bytes obtained through the generateRandomBytes function).
  • Account credentials. If you want to store users’ credentials so they don’t have to enter them every time they use your app, ELS is the correct API to use.
  • Salts for hashes. Once you’ve salted and hashed something like a password, you need to be able to securely persist the salt for future comparisons.


If you just need to generate random numbers for something like a game, you should stick to using Math.random. In fact, on some platforms, the generateRandomBytes function could temporarily block if the entropy pool has been entirely drained which means you don’t want to pull large amounts of data from it in an endless loop. Rather, generateRandomBytes should be reserved for generating unguessable cryptographically secure random data for things like encryption and session keys, GUIDs, and salts for hashes.

Whenever you need to store sensitive information like credentials, encryption keys, or salts, you should always use the EncryptedLocalStore APIs. Since they are now supported everywhere, you can use them in a completely cross-platform manner.

Whether you’re updating an existing application that needs to persist data securely, or building an entirely new one, I strongly recommend that you use the new best practices made possible in AIR 3.