“Secure Storage” in this context means that data can be optionally encrypted for privacy, but whether or not encrypted, any alteration of stored data can be reliably detected. In cryptographic terms, this provides authenticated encryption with associated data (AEAD).

SQRL clients require both offline and online storage security:

• SQRL's primary need for secure storage is for long-term offline storage of the user's master identity and identity unlock keys. Any time these extremely sensitive keys are exported from a SQRL client — even when jumping between devices as a QR code — they are encrypted under a random key derived by SQRL's deliberately memory and time consuming, attack resistant PBKDF (password based key derivation function).
• To enforce key privacy we need to use strong encryption. And to verify successful decryption, verify the user's provided passphrase and detect any tampering, we employ strong message authentication.
• To provide additional security, SQRL clients also employ online security to maintain their users' internally stored keys in encrypted form, decrypting them briefly on-the-fly only during the moment they are needed. Therefore, the plaintext form of SQRL's sensitive keys exist only transiently.

SQRL v1 obtains both robust data encryption and decryption verification (wrong password, error and tamper detection) through its use of the industry standard AES-GCM “authenticated encryption” (AE). Unlike earlier authenticated encryption schemes which either applied a MAC (message authentication code) to the encrypted data, or applied encryption to data that already had a MAC authentication, the AES-GCM performs both operations at once and does not require the use of separate keys for each aspect of the operation.

AES-GCM has been adopted by NIST (National Institute of Standards and Technology). It is present in the IPsec (IP Security) specification and participates in the TLSv1.2 security suites, where it is supported by Firefox and Chrome and recent releases of OpenSSL.

Because all of SQRL's other cryptography is in the public domain, GRC has produced and provides a reference implementation of AES-GCM whose source code is released without any usage restrictions of any kind into the public domain. It was written in platform-neutral 'C' and should be easily compiled for use with SQRL. Included in the source distribution are NIST's six files of algorithm validation test vectors, a PERL utility to compile them into a single binary, and a test harness (gcmtest.c) which validates GRC's implementation against NIST's 47,250 individual test vectors.

Note: After this work was finished the reference LibSodium cryptographic library has added AES-GCM to its suite of security tools. Since SQRL uses LibSodium for several other functions, using the AES-GCM functions from LibSodium now makes the most sense.

Consequently, the individual blocks contained within SQRL's secure storage system are encrypted and authenticated with AES-GCM using a 256-bit key derived from SQRL's EnScrypt algorithm.

SQRL's S⁴ system uses NULL initialization vectors (IV) for its type 2 and type 3 blocks. AES-GCM, like many block cipher modes using a keyed symmetric cipher, employs an initialization vector nonce. To provide guaranteed privacy, this nonce does not need to be secret, nor even random, but it does need to never repeat under the same key. For its type 2 and type 3 blocks, SQRL's S⁴ storage system meets this requirement using an implied and fixed initialization vector of all zeros (NULL) because those blocks' AES-GCM encryption keys are never reused when the block is changed and re-encrypted. As detailed below, The type 1 and 2 blocks are keyed by SQRL's Scrypt-based EnScrypt function, which has its own 16-byte random salt. This results in the use of a unique encryption key every time the block is encrypted. The type 3 block is keyed by the identity master key (IMK) which is also derived from a random process and is never reused. The type 1 block does use a randomly obtained IV to allow re-encryption under a new IV after user-interface plaintext settings have been changed and a new matching authentication tag must be created.

The trend, exemplified by XML and JSON data structure description languages, reduces information storage density and efficiency in favor of embedding structural descriptive flexibility. Bundling an application's data description metadata into the data can simplify dissimilar system inter-operation by allowing the data to effectively describe itself. And in today's world of terabyte storage and gigabit communications, the cost of embedding inter-operation metadata is offset by interconnection robustness.

But an excess of metadata makes little sense for SQRL's offline static data storage where long term storage robustness and retrievability are the overriding priority. SQRL exports long-term statically encrypted secrets in future-proof printed paper form,so fewer bits means that each bit can be larger. Fewer characters means that each character can be larger. Few bits means there's more room for stronger error correction with its larger overhead, etc.

However, notwithstanding the previous, today's storage format must also provide for future change and expansion. The following format, while simple and minimal, addresses and meets all of these needs.

SQRL's Secure Storage System (S⁴) Encrypted Key Sample

SQRL's Secure Storage System (S⁴) incorporates the following features:

• An S⁴ database is identified by its first eight-byte signature 'sqrldata' appearing in string-sequence with 's' being the file's first byte.
• Although S⁴ is nominally a binary representation, it may be necessary to convey the file over a binary-hostile medium. In this case the standard eight-byte signature will be converted to all uppercase 'SQRLDATA' and the balance of the database will be encoded into 6-bit base64url format for representation, storage or transmission over a binary-intolerant channel.
• When a SQRL client encounters a database beginning with uppercase 'SQRLDATA' it must immediately lowercase the 8-byte header and pass the balance of the database through a base64url decoder to restore the database to binary. Processing may then proceed normally.
• To aid in the exchange of SQRL data during development — posting on forums, etc. — base64url-illegal line ending and whitespace characters — CR, LF, TAB and SPACE — should be silently ignored for line wrap tolerance.
• Strings are stored in their natural order, first byte first, and multibyte numerical values are stored in ‘little endian’ order, with their least significant byte first. This is the reverse of the so-called ‘network byte order’, but this is not a network protocol, it is a storage format and the order is not important as long as it is clearly specified. All Intel and AMD systems are all natively (pardon the pun) little endian, and ARM-based systems are configurable, with many mobile systems choosing little endian mode for inherent Intel compatibility.
• All numeric values are simple, unsigned, binary.
• Each block begins with a 2-byte length specifier which includes the length byte's two bytes. Similarly, lengths would typically fit within a single byte, but two bytes allows for ample future growth.
• The second datum in each block, following its length bytes, is a two-byte block type. As shown above and described below, only three block types are defined by the version 1 S⁴ specification. So, again, plenty of accommodation for growth.
• This simple, lean, and efficient structure allows SQRL to use a minimal-size credential storage file format while supporting virtually any degree of future expansion in block size, block type, and block count . . . all while maintaining backward compatibility to the original lean v1 specification.

The final version of this page will specify the v1 design of GRC's S⁴ for its reference SQRL client. All SQRL clients wishing to interchange SQRL identities must fully comply with this simple and straightforward specification. Though this specification is not complex, the following easily enforced characteristics provide significant future growth and backward compatibility:

• This specification fully describes three block types and any unknown block type should be ignored. This allows future clients to incorporate additional features and capabilities in a backward compatible fashion. Older clients, unaware of other block types, will simply ignore them.
• The currently defined layout of existing block types must be honored. SQRL clients wishing to store additional non-standard data in SQRL identities must define and create additional block types. S⁴ clients will ignore any data they do not explicitly expect.
• Future clients may incorporate support for new PBKDF or Authenticated Encryption modes, thus augmenting or replacing the v1 use of EnScrypt, SHA256-Scrypt, AES-256-GCM, by defining new block types and providing whatever data they require.
• The type 2 and 3 blocks use an implied NULL initialization vector (IV) nonce. This is cryptographically safe because the application of the type 2 and 3 blocks precludes the same data ever being encrypted by the same key. Since this is not true for the type 1 block, its plaintext header region does incorporate an initialization vector (IV) nonce.
• All blocks are terminated by a 16-byte verification tag. This authentication tag is generated by the AES-GCM authenticated encryption and must always be the last field of any block.

SQRL's eight-byte ‘sqrldata’ file signature indicates that S⁴ format blocks follow and the alphabetic case of the signature indicates whether the balance of the file is straight binary or 6-bit base64url encoded. The eight-byte header stands alone and does not participate in the authenticated encryption of the blocks that follow.

To enhance interoperability between SQRL clients by different authors on different platforms, SQRL standardizes the following three block types which are understood by GRC's reference client:

Type 1: Password PBKDF spec., plaintext data and encrypted identity keys. Type 2: RescueCode PBKDF spec. and encrypted identity unlock key. Type 3: Encrypted previous identity unlock keys.

SQRL keeps two classes of secrets—user access password and emergency RescueCode—so we define one data structure to contain the data required by each secret class:

• Type 1 - User access password authenticated & encrypted data
  The type 1 S⁴ block supplies the EnScrypt parameters to convert a user-supplied “local access passcode” into a 256-bit symmetric key, and also contains both the plaintext and encrypted data managed by that password.

  {length = 125} – inclusive length of entire outer block2 bytes

  {type = 1} – user access password protected data2 bytes

  {pt length = 45} – inclusive length of entire inner block2 bytes

  {aes-gcm iv} – initialization vector for auth/encrypt12 bytes

  {scrypt random salt} – update for password change16 bytes

  {scrypt log(n-factor)} – memory consumption factor1 byte 

  {scrypt iteration count} – time consumption factor4 bytes

  {option flags} – 16 binary flags2 bytes

  {hint length} – number of chars in hint1 byte 

  {pw verify sec} – seconds to run PW EnScrypt1 byte 

  {idle timeout min} – idle minutes before wiping PW2 bytes

  {encrypted identity master key (IMK)}32 bytes

  {encrypted identity lock key (ILK)}32 bytes

  {verification tag} – 16 bytes

  Notes:

  • Immediately following the type 1 block's two-byte length and two-byte type specifier is the two-byte “plaintext length” (pt length) of the unencrypted (plaintext) but authenticated data for this block. This is the length of the so-called “additional authenticated data” (aad) of the block's AES-GCM cipher. The length specification spans from the first byte of the block (the first byte of the whole block's length specification) up to, but not including, the beginning of the block's encrypted data (shown in red above).
  • The 12-byte (96-bit) AES-GCM nonce appears next, immediately following the two-byte plaintext length. Note that ‘96 bits’ is the natural length of aes-gcm IV nonces. These 96 bits are chosen randomly every time the block is re-encrypted since the encryption key will typically not be changing and it is crucial that IV nonces are never reused with the same key and differing data under AES-GCM. Since we might only be updating the plaintext user interface data with a short and fast password hint decryption, we would have no opportunity to establish a new key. So a unique nonce will be used with the same quickly-decrypted key.
  • Immediately following the AES-GCM IV nonce are the EnScrypt encryption parameters, the user's user-interface preferences and other non-critical information. Although it CAN be read without any authentication, all S⁴ data is authenticated and it MUST be marked and regarded as untrusted until it has been authenticated under the user's local access password. In other words, prior to using any of the unencrypted data obtained here for any purpose important to security, the client MUST obtain the user's password and authenticate this data. Similarly, in order for any change made in this data to authenticate, the user's password will be required in order for an updated verification tag to be calculated. So saving any changed settings may require the user's password or hint.
  • Future versions of the SQRL S⁴ specification may define additional plaintext to be appended to the end of the v1-specified plaintext, but individual clients may not arbitrarily store their own data there. That need may easily be fulfilled by creating, for example, a type 4 block for their own use.
  • Encrypted data immediately follows the length-defined end of the inner plaintext block, extending to the end of the outer block (excluding the final 16-byte verification tag). The outer block's overall length is specified at the top of the block. As before, future extensions of this specification may append additional encrypted data to the end of this list, but individual clients are not permitted to do so.
  • Operational Note: This SQRL identity database very efficiently (in 6 bytes) bundles the GRC SQRL client user's user-interface preferences, including the time required to process a full password input. When this identity is imported into a compatible client running on a platform having a different processing speed ‑ either a different PC or a mobile device ‑ that SQRL client will obtain that user's preferred password processing time. Although different environments (for example, mobile) might suggest a differing security posture and password processing overhead, the client can note when a large difference exists between the processing time of the origin device ‑ as revealed in the bundled time specification ‑ and the current platform. The client can offer to immediately re-encrypt the user's just entered password to re-normalize all future password processing time.
  Cross-Client Options & Flags

  The type 1 secure storage block includes a set of operational options and settings which allow users to customize the SQRL client's operation to their preferences. These options are stored with the user's identity so that they are changed when the client's logon identity is changed, and so that they may follow the user from platform to platform and from device to device. If SQRL clients standardize upon these options, user convenience will be enhanced:

  • hint length (characters)
    This one-byte value specifies the number of characters used in password hints. The default is 4 characters. A value of zero disables hinting and causes the SQRL client to prompt its user for their full access password whenever it's required.
  • password verify (seconds)
    This one-byte value specifies the length of time SQRL's EnScrypt function will run in order to deeply hash the user's password to generate the Identity Master Key's (IMK) symmetric key. SQRL clients are suggested to deefault this value to five seconds with one second as a minimum. It should not be possible for the user to circumvent at least one second of iterative hashing on any platform.
  • idle timeout (minutes)
    This two-byte value specifies the length of idle system time the hinting system is allowed to retain an abbreviated password before it is erased and the full password must be re-entered. This non-zero value, coupled with the 0x80 idle enable bit, are both required to enable idle timeout.
  • option flags (default value: 0x01F3)
    This two-byte value contains a set of individual single-bit flags corresponding to options offered by SQRL's user-interface. The individual bits have the following meaning:

  0x0001		Check for updates: This requests, and gives the SQRL client permission, to briefly check-in with its publisher to see whether any updates to this software have been made available. Note that GRC's client uses a low overhead DNS query to check for newer versions.
  0x0002		Update autonomously: This requests, and gives the SQRL client permission, to automatically replace itself with the latest version when it discovers that a newer version is available.
  0x0004		Request SQRL only login: This adds the “option=sqrlonly” string to every client transaction. The presence or lack of presence of this option string in any properly signed client transaction is used to push an update of a server-stored flag that, when set, will subsequently disable all traditional non-SQRL account logon authentication such as username and password.
  0x0008		Request no SQRL bypass: This adds the “option=hardlock” string to every client transaction. The presence or lack of presence of this option string in any properly signed client transaction is used to push an update of a server-stored flag that, when set, will subsequently disable all “out of band” (non-SQRL) account identity recovery options such as “what was your favorite pet's name.”
  0x0010		Warn of possible MITM attack: When set, this bit instructs the SQRL client to notify its user when the web server indicates that an IP address mismatch exists between the entity that requested the initial logon web page containing the SQRL link URL (and probably encoded into the SQRL link URL's “nut”) and the IP address from which the SQRL client's query was received for this reply.
  0x0020		Discard password hint data upon blanking, suspend, etc.: When set, this bit instructs the SQRL client to wash any existing local password and hint data from RAM upon notification that the system is going to sleep in any way such that it cannot be used. This would include sleeping, hibernating, screen blanking, etc.
  0x0040		Discard password hint data upon user switching: When set, this bit instructs the SQRL client to wash any existing local password and hint data from RAM upon notification that the current user is being switched.
  0x0080		Discard password hint data after system idle: When set, this bit instructs the SQRL client to wash any existing local password and hint data from RAM when the system has been user-idle (no mouse or keyboard activity) for the number of minutes specified by the two-byte idle timeout.
  0x0100		Warn of non-CPS authentication: When set, this bit instructs the SQRL client to notify its user whenever a non-CPS authentication is attempted. Since CPS provides extremely strong protection against website spoofing—which is a particularly significant concern for SQRL due to its high degree of automation and presumed automatic provision of security—this flag must default to enabled.

• Type 2 - Rescue code encrypted data
  The type 2 S⁴ block supplies the EnScrypt parameters to convert a user-supplied “emergency rescue code” into a 256-bit symmetric key for use in decrypting the block's embedded encrypted emergency rescue code.

  {length = 73}2 bytes

  {type = 2} – emergency rescue code data2 bytes

  {scrypt random salt}16 bytes

  {scrypt log(n-factor)}1 byte 

  {scrypt iteration count}4 bytes

  {encrypted identity unlock key}32 bytes

  {verification tag} – 16 bytes

  Notes:

  • The type 2 block's unencrypted data, from and including the first byte of the block length up to but not including the first byte of the encrypted identity unlock key, is the unencrypted (plaintext) authenticated data for this block. Therefore, the length of the “additional authenticated data” (aad) of the block's AES-GCM cipher is 25 bytes. As with all of the S⁴'s blocks, the AES-GCM initialization vector (IV) is null (all zeroes).

• Type 3 - Encrypted previous identity unlock keys
  Since the type 3 S⁴ block contains from one to four of the most recently replaced identity unlock keys (PIUKs), the presence of this block type in any SQRL identity is optional. It will only be present when a identity has been rekeyed at least once. When present, this block is encrypted under the current identity's Identity Master Key (IMK). The IMK may be obtained either by decrypting the type 1 block with the user's identity passphrase, or by decrypting the type 2 block with the user's identity RescueCode then “EnHashing” the obtained Identity Unlock Key (IUK) to derive the Identity Master Key (IMK).

  SQRL is designed to use extremely long-lived, hopefully perpetual, identity keying where the need to rekey any identity is vanishingly rare. Add to this the fact that authenticating to any site that recognizes a user through one of their previous identity keys autonomously updates that site to the users current key. This will tend to automatically keep websites' identity information current. These facts argue for a modest number of previous keys being sufficient to make the entire rekeying process transparent to all reasonable SQRL users (and even any who are unreasonable).

  As shown below, the overall size (length) of the type 3 block will be 54, 86, 118 or 150 bytes depending upon whether it contains one, two, three or four previous identity unlock keys.

  {length = 54, 86, 118 or 150}2 bytes

  {type = 3} – previous identity unlock keys2 bytes

  {edition >= 1} – count of all previous keys2 bytes

  {encrypted previous IUK}32 bytes

  {encrypted next older IUK (if present)}32 bytes

  {encrypted next older IUK (if present)}32 bytes

  {encrypted oldest previous IUK (if present)}32 bytes

  {verification tag} – 16 bytes

  Notes:

  • The type 3 block's unencrypted 6 bytes of header data is the unencrypted (plaintext) “additional authenticated data” (aad) for this block. Therefore, the length of the “additional authenticated data” (aad) of the block's AES-GCM cipher is 6 bytes. As with all of the S⁴ blocks, the AES-GCM initialization vector (IV) is null (all zeroes).
  • This block contains from one to four most recently retired (previous) identity unlock keys (PIUKs). The up to four key slots are treated as an MRU (most recently used) list with the most recently retired keys placed at the top of the list and earlier keys “pushed” down, with the oldest key lost as it is replaced in the last position.
  • The “edition” field is a monotonically incrementing 2-byte counter, incremented once with every identity rekeying. Being in the additional authenticated data header, it is not encrypted. Although this provides an indication of the identity's rekeying history, this information will be of no use to an attacker, whereas it will be extremely useful for the identity's owner, since it will allow them to clearly distinguish among same-name identities of differing editions. SQRL's paper identity printouts will also be able to display this edition number. If the edition were part of the block's encrypted data, the identity's passphrase would be required to view it, which would be inconvenient for its intended purposes.

Since no identity should logically contain more than one instance of each block type, no client should ever generate an identity having more than one Type 1, 2 and 3 block. Any client encountering an identity containing more than one of either type should reject the entire identity as suspicious and invalid. Clients wishing to tolerate aberrant identities may choose which one of the duplicated block types to honor. • Some observers have suggested that peripheral features of the underlying SQRL protocol, such as the use of GRC's proposed EnScrypt PBKDF should remain separate. This S⁴ database format provides for the addition of any other type of password authentication by leaving all other block types open and available. And the compact representation of this database leaves ample room for future parallel authentication or alternatives.

• If SQRL should evolve in the direction of a form-fill application, that private and probably encrypted data could occupy currently undefined block types without duplicating any of SQRL's existing data. A future encrypted and authenticate block could implicitly infer the use of, for example, the encryption parameters obtained from the existing type 1 block.

• 2017/05/31 : Updated the option flags, restoring them & adding the no-CPS warning flag.
• 2016/04/22 : Updated to make the type 3 block both optional and variable length.
• 2016/04/21 : Added the “edition” field to the new Type 3 block.
• 2016/01/23 : Improved final design specification for v1.
  • Added the new Type 3 block, keyed by the identity's master key (IMK) to contain from zero to four previous identity unlock keys (PIUK).
• 2015/10/07 : Proposed final design specification for v1.
  • Added three additional previous identity unlock keys (PIUK) to the type 1 block, and made it non-expandable by individual clients. This greatly simplifies implementation and allows for a total of five SQRL identity keys, the current one and up to four previous identity keys, to be carried within any SQRL identity.
• 2014/05/23 : Complete redesign made as a consequence of first actual implementation.
• 2014/06/06 : Switched from patented OCB AE mode to unencumbered AES-GCM.
• 2014/06/21 : Removed the variable-length count, length, and type parameters. All parameters are now two bytes long making implementation much simpler and cleaner.
• 2014/06/26 :
  • Removed the optional previous identity master key from the type 1 block since it can always be derived from its associated identity unlock key.
  • Made the storage allocation for the previous identity unlock key mandatory. When no previous identity is defined, the key will be null (all zeroes).
  • Removed the block count from the header. It served no real purpose and could not be changed without invalidating any blocks that included it in their additional authenticated data (aad).
  • For type 1 blocks, the plaintext sub-block length was moved to the top of the plaintext region along with the AES-GCM IV, and the length now reflects the entire length of the plaintext segment.