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.

Fieldtype	Typename	Datatype	Example
cardtype	Card Type	string	MasterCard
cardnumber	Card Number	string	1234 5678 9012 3456
expirydate	Expiry Date	string	01/10
ccv	CCV Number	string	637
pin	PIN-code	secret	1234

Database (database)

For accessing a database.

Fieldtype	Typename	Datatype	Example
hostname	Hostname	hostname	db.company.com
protocol	Protocol	protocol	MySQL
database	Database	string	productdata
username	Username	userid	admin
password	Password	secret	v3EyHnzx

Door Lock (door)

For opening doors requiring a PIN code.

Fieldtype	Typename	Datatype	Example
location	Location	string	Front entrance at work
pin	PIN Number	secret	1234

E-mail (email)

For email-accounts.

Fieldtype	Typename	Datatype	Example
email	E-mail address	email	mail@company.com
hostname	Hostname	hostname	mail.company.com
username	Username	userid	mail
password	Password	secret	DPkyHo2G
protocol	Protocol	string	IMAP

FTP (ftp)

For accessing an FTP server.

Fieldtype	Typename	Datatype	Example
hostname	Hostname	hostname	ftp.company.com
port	Port	integer	21
username	Username	userid	ftpuser
password	Password	secret	TuFNnL7A

Generic (generic)

For storing generic accounts for which no account type exists.

Fieldtype	Typename	Datatype	Example
hostname	Hostname	hostname	service.company.com
username	Username	userid	user
password	Password	secret	k3LutMFy

Instant Messaging (im)

For instant messaging services

Fieldtype	Typename	Datatype	Example
hostname	Hostname	hostname	talk.google.com
protocol	Protocol	string	Google Talk
username	Username	userid	user@gmail.com
password	Password	secret	23KRuJVb

Phone (phone)

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

Fieldtype	Typename	Datatype	Example
phonenumber	Phone Number	string	12 34 56 78
pin	PIN Code	secret	1234
puk	PUK Code	secret	12345678
imei	IMEI	string	123456789012345

Product Key (productkey)

Code to install software applications and games

Fieldtype	Typename	Datatype	Example
product	Product	string	ExpensiveSoft 3000 Plus
productkey	Product Key	secret	8356-1947-7534-2994

Remote Desktop (remotedesktop)

For accessing a remote desktop

Fieldtype	Typename	Datatype	Example
hostname	Hostname	hostname	desktop.company.com
protocol	Protocol	string	VNC
username	Username	userid	user
password	Password	secret	aG9xJohH

Shell (shell)

For accessing a shell

Fieldtype	Typename	Datatype	Example
hostname	Hostname	hostname	shell.company.com
protocol	Protocol	string	SSH
username	Username	userid	root
password	Password	secret	2eQoLrhm

Website (web)

For websites

Fieldtype	Typename	Datatype	Example
url	Address	url	http://www.slashdot.org/
username	Username	userid	user
password	Password	secret	ujBRAc7C

This revision is from 2010-04-04 07:10

erikg / Revelation

Revelation File Format 1.0 Specification DRAFT

XML format

Root element

Attributes

Example

Accounts

Attributes

Child elements

Example

Account fields

Attributes

Example

Field datatypes

Document Type Definition

Encryption

Key derivation

Compression

Padding

Encryption

File header

Recommended account types

Creditcard (creditcard)

Database (database)

Door Lock (door)

E-mail (email)

FTP (ftp)

Generic (generic)

Instant Messaging (im)

Phone (phone)

Product Key (productkey)

Remote Desktop (remotedesktop)

Shell (shell)

Website (web)