1Password User Guide

  1. Requirements
  2. Installing 1Password
  3. Registering 1Password

3-Minute Expert Guide



        Frequently Asked Questions

          Knowledge Base

            Contact Us

    Agile Keychain Design

    The goal of the Agile keychain is to build on the successes of the OS X keychain while increasing the flexibility and portability of the keychain design. Additional flexibility is needed to enable new features beyond the scope of the OS X keychain, as well as to make it easier to integrate with other platforms like iPhone OS, Linux, and Windows.

    The specific needs for which the Agile keychain was created are documented in the History of 1Password’s OS X Keychain Integration. This document will cover the requirements of the Agile keychain and detail how its design meets them.


    The design of the new Agile keychain must support the following:

    Design Decisions

    The following design decisions were made with the goal of fulfilling the above requirements.

    AES Encryption Using OpenSSL

    As always, we did not want to write a single line of encryption code. The Agile keychain therefore uses the OpenSSL library for all of its encryption and key generation needs.

    OpenSSL is open source, used on the majority of servers in the world, shipped on every Mac, and actively supported by a huge community. It is also compliant with the FIPS 140-1 and FIPS 140-2 Federal Information Processing Standards.

    OpenSSL is used to encrypt all confidential information with AES (Advanced Encryption Standard) using 128-bit encryption keys and performed in Cipher Block Chaining (CBC) mode along with a randomized Initialization Vector.

    The Agile keychain uses 128-bit keys instead of 256-bit keys because they are long enough to be very secure and short enough to allow devices like the iPhone and web browsers to quickly decrypt their contents. The extra computation required for 256-bit encryption was simply not justifiable given the astronomical nature of a 128-bit key. From the National Institute of Standards and Technology web page, AES: Questions and Answers:

    What is the chance that someone could use the “DES Cracker”-like hardware to crack an AES key?

    In the late 1990s, specialized “DES Cracker” machines were built that could recover a DES key after a few hours. In other words, by trying possible key values, the hardware could determine which key was used to encrypt a message.

    Assuming that one could build a machine that could recover a DES key in a second (i.e., try 255 keys per second), it would take that machine approximately 149 thousand billion (149 trillion) years to crack a 128-bit AES key. To put that into perspective, the universe is believed to be fewer than 20 billion years old.

    We felt that adding an extra 128 bits, i.e., multiplying 149 trillion years by an extra 3.4 x 1038, was not worth the performance cost that would be incurred. At 128 bits, it is much more likely that an attacker would focus on finding a weakness in the underlying system instead of attacking the mathematics of the AES algorithm.

    Encryption Key Generation

    The most important component of encryption, which is often overlooked, is how the encryption keys are generated. This needs to be done in a way that ensures the mathematics of the AES algorithm cannot be avoided while also stymying brute force attacks.

    The Agile keychain uses the standard PBKDF2 (Password-Based Key Derivation Function) algorithm to generate encryption keys from your password. PBKDF2 is also published by the Internet Engineering Task Force in RFC 2898.

    Of course, we wanted to avoid writing this code in the Agile keychain and elected to use the OpenSSL function PKCS5_PBKDF2_HMAC_SHA1 to generate the keys. Key generation is simply too important a step to not rely directly on the experts. In order to thwart would-be attackers and strengthen the key, we elected to use 1000 iterations in the PBKDF2 algorithm.

    Why is it so important to strengthen the encryption key? There are tools available that specialize in cracking password hashcodes. The Lighting Hash Cracker, for example, is able to test 608 million passwords per second. If a naive key generation algorithm that simply hashed the password once were used to generate the key, attackers could use a system like this to quickly brute force the password. By using 1000 iterations in the PBKDF2 function, the brute force attack is effectively 1000 times more difficult.

    Hierarchy of Encryption Keys

    In order to allow you to change your password without needing to decrypt and re-encrypt the entire Agile keychain, an encryption key hierarchy was created. Instead of encrypting data with the password directly, a random password of 1024 bytes is used. This password is generated by /dev/random and is stored in the encryptionKeys.js file, encrypted using the user-provided password.

    By using such a huge key generated by /dev/random, your password can be changed by simply decrypting and re-encrypting the keys stored in encryptionKeys.js. Additionally, you can use different passwords on different devices. For example, the master password you use on your computer might be difficult to type on an iPhone, so it is useful to be able to create a different one on the iPhone.

    The other advantage of this setup is that it allows multiple security levels to be defined. Each time a new security level is created, we simply generate another key to encrypt items that use that level of security. One example of this is on the iPhone, where a simple PIN can be used to protect less important items, while the master password is required for more sensitive items.

    File System Storage

    Every item in the Agile keychain is stored as a separate file. By using individual files, syncing of the Agile keychain can be performed using any of the many file syncing solutions available on Mac OS X. In fact, many sync solutions like Dropbox can sync files between Mac, Windows, and Linux.

    Individual Entry Contents

    The Agile keychain is nearly identical to the OS X keychain in terms of what is kept encrypted and what is left open in plain text. The distinction is an important trade-off between security and convenience. The more that is encrypted, the less a would-be thief can access, but it is also necessary to leave enough open to allow applications to freely access certain items without needing to decrypt every single entry each time. The OS X keychain nicely balances security and convenience, so the Agile keychain follows suit.

    Here is an example entry from the Agile keychain:

     "title" : "dave @ AWS login",
     "keyID" : "7291B8B58CB641BA931217C73696C5C5",
     "locationKey" : "perfora.net",
     "encrypted" : "...",
     "typeName" : "webforms.WebForm",
     "openContents" : {
       "folder" : "A90D66D1A4E34481BDF03DDEA9F511AC",
       "createdAt" : 1216012929,
       "passwordStrength" : 100,
       "updatedAt" : 1216012929,
       "usernameHash" : "...",
       "passwordHash" : "..."
     "location" : "https://webmailcluster.perfora.net:443/xml/webmail/Login",
     "uuid" : "0A522DFCAE6442D991145BC76E55D343",
     "folderUuid" : "A90D66D1A4E34481BDF03DDEA9F511AC"

    As you can see, not all the information is encrypted. Most notably, the name/title of each entry (i.e. dave @ AWS login) and the location/URL are open. Having these open allows 1Password to organize your data and display it without suffering the performance hit of needing to decrypt every single item. All the truly confidential information is stored in the encrypted section of the file.

    The above file format is based on JSON (JavaScript Object Notation). It is a lightweight notation for structuring data without the overhead associated with formats like XML. As a side benefit, these JSON files can be loaded directly into a web browser. The name of the file is based on the UUID (Universally Unique Identifier) of the item. This guarantees the filename is unique and will stay the same even when items are renamed.


    The design decisions made when developing the Agile keychain provide the following benefits: