Wiki

Clone wiki

Revelation / FileFormatSpec

Revelation File Format 1.0 Specification DRAFT

This document describes a file format used for storing authentication data. It is primarily intended for use in the Revelation password manager, but it may be useful for other projects as well.

XML format

Account data is represented as XML.

Root element

The root element is revelationdata, which can contain an unlimited number of account elements.

Attributes

  • version (required): which version of this specification the data file conforms to, in this case 1.0. New minor-version releases will be backwards-compatible, while new major-version releases will not.
  • id (required): a randomly generated 128-bit hex-encoded identifier for this particular file. When a file is loaded and then saved this ID must be preserved.

Example

<revelationdata version="1.0" id="722ec5ad92a014c81ec71b06db23faab">
</revelationdata>

Accounts

account is an element containing account data.

Attributes

  • id (required): a randomly generated 32-bit hex-encoded identifier for the account. This ID must be unique within the file, ie it cannot be used by other accounts. Applications must preserve this ID when re-saving the file.
  • type (required): a string defining the type of account (website, shell, etc). A list of recommended types can be found in the Recommended account types section, but applications are free to make up their own.
  • typename (required): a name for the account type (for example Website, Shell, etc). If the application recognizes the type defined in the type attribute it should use its own typename, but this attribute can be used as a fallback if the type is unknown.

Child elements

  • name (required): a 256-char name for the account
  • description (optional): a 256-char description of the account
  • note (optional): an unlimited-length note for the account
  • changed (required): the time when the account was last changed, as an ISO-formatted UTC timestamp

In addititon to these elements it also contains an arbitrary number of field elements, which contains the actual account data. These are described in the Account fields section.

Example

<account id="a1e1fc9a" type="web" typename="Website">
	<name>Example web account</name>
	<description>Just an example</description>
	<note>This account is just an example</note>
	<updated>2006-02-13 18:36:11</updated>
	<field type="url" name="URL" datatype="url">http://www.example.com/<field>
	<field type="username" name="Username" datatype="userid">username<field>
	<field type="password" name="Password" datatype="secret">password<field>
</account>

Account fields

Accounts can contain an arbitrary number of field elements. A field is a piece of data for the account, such as a username or password.

Attributes

  • type (required): a string defining the type of field (such as username, password, url, etc). Some recommended types can be found in the Recommended account types section, but applications are free to make up their own.
  • typename (required): a name for this field type. If the application recognizes the type in the type attribute it should use its own name, otherwise this attribute can be used as a fallback.
  • datatype (required): the datatype for the field. All field contents should be expected to be strings, but this datatype may give a hint as to how the field should be displayed or edited. Unknown datatypes should be handled as normal strings. A list of valid datatypes can be found in the Field datatypes section.

Example

<field type="username" typename="Username" datatype="userid">erikg</field>

Field datatypes

Field data is basically just normal strings, but they have a datatype attribute which can be used as hints for how to display or edit the data. There should be no restrictions on what data a user can enter into a field. The valid datatypes are:

  • string: a normal string, up to 256 characters long
  • integer: an integer number of arbitrary length
  • userid: a user identification token, such as a username or customer number
  • secret: a secret, such as a password, a PIN code, or the answer to a question
  • url: a Uniform Resource Locator, like a website address
  • hostname: a computer hostname
  • email: an email address

Applications are not allowed to make up their own datatypes, but should handle unknown datatypes as string. This is to maintain forwards-compatability with future versions of this specification.

Document Type Definition

The Document Type Definition for the XML is as follows:

<?xml version="1.0" encoding="utf-8" ?>

<!DOCTYPE revelation [
	<!ELEMENT revelationdata	(account*)>
	<!ATTLIST revelationdata	id		ID	#REQUIRED>
	<!ATTLIST revelationdata	version		CDATA	#REQUIRED>

	<!ELEMENT account		(name,description?,note?,updated,field*)>
	<!ATTLIST account		id		ID	#REQUIRED>
	<!ATTLIST account		type		CDATA	#REQUIRED>
	<!ATTLIST account		typename	CDATA	#REQUIRED>

	<!ELEMENT field			(#CDATA)>
	<!ATTLIST field			type		CDATA	#REQUIRED>
	<!ATTLIST field			name		CDATA	#REQUIRED>
	<!ATTLIST field			datatype	CDATA	#REQUIRED>

	<!ELEMENT name			(#CDATA)>
	<!ELEMENT description		(#CDATA)>
	<!ELEMENT note			(#CDATA)>
	<!ELEMENT updated		(#CDATA)>
]>

Encryption

The XML is compressed using bzip2 and then encrypted with an algorithm based on the PKCS #5 (RFC 2898) recommendation, more specifically the PKBDF2 and PBES2 methods, using AES-256 as the cipher and SHA-256 as the hash function. The encrypted data is prepended with a file header, containing a magic string, file versions, and necessary cipher data such as the initialization vector and the password salt.

Key derivation

The user must supply a password, encoded as UTF-8. It is concatenated with a randomly generated 256-bit salt, and then hashed a number of times (10 000 is recommended) using the SHA-256 algoriyhm. A pseudo-code example of this process:

password = get_password()
salt = sha256_digest(random_string(32))
key = password + salt

for i = 0 to 10000
	key = sha256_digest(key)

Compression

The plain XML must be compressed using the bzip2 algorithm. A compression level of 9 is recommended.

Padding

The bzip2-compressed data is right-padded to a multiple of 32 bytes, using a byte value equal to the number of pad-bytes. If the data is already a multiple of 32 bytes long, it must be right-padded with another 32 bytes. A pseudo-code example of this process:

padlen = sizeof(data) % 32

if padlen == 0
	padlen = 32

padchar = char(padlen)

data = data + repeat_string(padchar, padlen)

Encryption

The data is then encrypted with the AES-256 algorithm in cipher block chaining mode, using the previously generated SHA-256 hash as the key (see the Key derivation section) and a randomly generated 32-byte initial vector. Here is a pseudo-code example:

iv = sha256_digest(random_string(32))

data = aes256_encrypt_cbc(data, key, iv)

File header

The encrypted data is prefixed with a 74-byte file header, containing a magic-string, the major and minor version of the file format, the number of iterations, the key salt, and the CBC initial vector. A detailed layout of the header is as follows:

  • Magic string (6 bytes): rvl followed by 0xe0427b, the whole string is 0x72766ce0427b.
  • File version (2 bytes): one byte for each of the major and minor version of the file format, in this case 0x0100. Future minor-version releases will be backwards-compatible, while major-version releases will not.
  • Hash iterations (2 bytes): the number of hash iterations used for the key derivation function (see the Key derivation section). 10 000 or more is recommended.
  • Key salt (32 bytes): the salt used for the key derivation function (see the Key derivation section).
  • CBC initial vector (32 bytes): the initial vector used for the CBC-mode encryption (see the Encryption section).

Recommended account types

Applications are free to create their own account types in accordance with the guidelines in the XML format section. However, the following account types are recommended as a default base set of types.

In addition to the fields described below, all accounts can also store a name, description, and note.

Creditcard (creditcard)

For credit and debit cards, etc.

FieldtypeTypenameDatatypeExample
cardtypeCard TypestringMasterCard
cardnumberCard Numberstring1234 5678 9012 3456
expirydateExpiry Datestring01/10
ccvCCV Numberstring637
pinPIN-codesecret1234

Database (database)

For accessing a database.

FieldtypeTypenameDatatypeExample
hostnameHostnamehostnamedb.company.com
protocolProtocolprotocolMySQL
databaseDatabasestringproductdata
usernameUsernameuseridadmin
passwordPasswordsecretv3EyHnzx

Door Lock (door)

For opening doors requiring a PIN code.

FieldtypeTypenameDatatypeExample
locationLocationstringFront entrance at work
pinPIN Numbersecret1234

E-mail (email)

For email-accounts.

FieldtypeTypenameDatatypeExample
emailE-mail addressemailmail@company.com
hostnameHostnamehostnamemail.company.com
usernameUsernameuseridmail
passwordPasswordsecretDPkyHo2G
protocolProtocolstringIMAP

FTP (ftp)

For accessing an FTP server.

FieldtypeTypenameDatatypeExample
hostnameHostnamehostnameftp.company.com
portPortinteger21
usernameUsernameuseridftpuser
passwordPasswordsecretTuFNnL7A

Generic (generic)

For storing generic accounts for which no account type exists.

FieldtypeTypenameDatatypeExample
hostnameHostnamehostnameservice.company.com
usernameUsernameuseriduser
passwordPasswordsecretk3LutMFy

Instant Messaging (im)

For instant messaging services

FieldtypeTypenameDatatypeExample
hostnameHostnamehostnametalk.google.com
protocolProtocolstringGoogle Talk
usernameUsernameuseriduser@gmail.com
passwordPasswordsecret23KRuJVb

Phone (phone)

For cell-phones, voicemail, phone-services, etc.

FieldtypeTypenameDatatypeExample
phonenumberPhone Numberstring12 34 56 78
pinPIN Codesecret1234
pukPUK Codesecret12345678
imeiIMEIstring123456789012345

Product Key (productkey)

Code to install software applications and games

FieldtypeTypenameDatatypeExample
productProductstringExpensiveSoft 3000 Plus
productkeyProduct Keysecret8356-1947-7534-2994

Remote Desktop (remotedesktop)

For accessing a remote desktop

FieldtypeTypenameDatatypeExample
hostnameHostnamehostnamedesktop.company.com
protocolProtocolstringVNC
usernameUsernameuseriduser
passwordPasswordsecretaG9xJohH

Shell (shell)

For accessing a shell

FieldtypeTypenameDatatypeExample
hostnameHostnamehostnameshell.company.com
protocolProtocolstringSSH
usernameUsernameuseridroot
passwordPasswordsecret2eQoLrhm

Website (web)

For websites

FieldtypeTypenameDatatypeExample
urlAddressurlhttp://www.slashdot.org/
usernameUsernameuseriduser
passwordPasswordsecretujBRAc7C

Updated