Qana : manual
Qana is a Java application that encrypts files, text and archives (hierarchically structured sets of files) with a 256-bit symmetric-key cipher based on established cryptographic algorithms: the scrypt password-based key-derivation function and the Fortuna cryptographically secure pseudo-random number generator, for which there is a choice of either AES-256 or Salsa20 as the underlying cipher.
Qana has the following features:
Qana can perform the following functions:
Qana is made available under two licences:
uk.blankaspect.qana package (including resources) may
be used under the terms of version 3 of the GNU General Public License.
Like all fields of study, cryptography has its own jargon, which, when it is employed carefully, provides a concise and unambiguous way of referring to what are often complex concepts. Several specialist terms are used in this document and in the Qana application itself; this section provides brief definitions of the some of the more basic ones.
The more advanced terms are explained by means of external links, mostly to articles in Wikipedia. (If you are unfamiliar with cryptography, Wikipedia has many informative articles on the subject, and the present author thanks all the people that have contributed to them.)
Some of the terms below are compounds of the word text. In cryptography, text is commonly used to refer to data of any kind. It originated in a time when most of what was encrypted was text.
[ I am breaking with convention by writing this part of the manual in the first person because I thought it would sound awkward if it were written in the third person with repeated references to "the author". ]
Designing a successful cryptographic algorithm requires a high level of technical knowledge and expertise in areas of advanced mathematics. (Introductions to cryptography abound with cautionary tales of how tortuously clever ciphers devised by non-experts invariably turn out to be easy to crack.) I'm not a cryptographer and I don't have the ability to design secure cryptographic algorithms, so I wrote the encryption engine of the Qana application by implementing established algorithms that are in the public domain.
The core cryptographic algorithms that are implemented in Qana — the scrypt key-derivation function, and the AES-256 and Salsa20 ciphers on which the Fortuna cryptographically secure pseudo-random number generator is based — are well-regarded: no successful practical attack on any of them of them has been published, and the known weaknesses of the AES cipher are not currently significant. However, owing to advances in technology and the effort that is expended on cryptanalysis by corporations and the agencies of nation states, it is possible that the algorithms will eventually be broken; if this happens, Qana will be one of the smaller casualties.
Although the cryptographic algorithms themselves are considered to be secure, there are likely to be weaknesses in their implementation in Qana that make them vulnerable to side-channel attacks. There may also be weaknesses in the structure of Qana's encrypted output; for example, it's possible that information about the encryption key could leak from encrypted metadata.
Users of a piece of software can often assess its functional quality just by using it: if it does what is expected of it without error or undesirable side effects and with acceptable speed, it's probably fit for purpose. In contrast, the quality of cryptographic software can be accurately assessed only by those with expert knowledge. The deficiencies of such software may remain hidden until a user discovers that someone has breached its purported security, at which point it may be too late to choose better software.
A necessary (but not sufficient) way to test the security of Qana is to publish it and hope that, if anyone finds weaknesses in it, he or she will take the trouble to report the problems to me. The obvious defect with this approach is that, like Blanche Dubois, it depends on the kindness of strangers. A large class of cryptanalysts will want to keep news of their success in breaking an encryption system to themselves and their employers; others may be induced to try to break a cipher only by the offer of a prize for succeeding. The remaining altruists are likely to be motivated to spend their time analysing encryption software in proportion to its popularity. As a result, the adoption of new encryption software may never reach critical mass: the software isn't subjected to cryptanalysis because it's not popular, it's not popular because it's not trusted, and it's not trusted because it hasn't been subjected to cryptanalysis.
At this early stage in the public life of the Qana application, I can recommend only that you investigate other, more established encryption software as an alternative to Qana. (For example, GnuPG and graphical front ends for it are available for various platforms.) In terms of security, the one advantage that Qana might have over established alternatives is that, because of its unpopularity, anyone considering attacking it would probably conclude that the benefit of cracking it would be outweighed by the cost of trying, which is a tenuous and risky kind of security to offer.
What, then, is the value of a piece of encryption software that was written by someone without expert knowledge of cryptography? The short answer may be not much. On the other hand, it may be that Qana provides reliable encryption of a relatively high strength, assuming that the core cryptographic algorithms have been implemented correctly and that there are no significant weaknesses in the structure of Qana's encrypted output. I am confident that the first of these assumptions is valid (the implementations of the algorithms pass unit tests with standard test vectors), but my lack of relevant expertise doesn't allow me to be confident of the second assumption. Leaving aside the questionable functional value of Qana, the source code may at least provide reference implementations of the key cryptographic algorithms, and it may serve as a framework on which other people can build a better encryption application.
The program is named after a village in southern Lebanon that has had the misfortune to have been attacked twice by the Israel Defense Forces (IDF) in separate incidents ten years apart. In April 1996, the IDF shelled a United Nations compound near Qana, killing 106 of the civilians that had taken refuge there. Then, in July 2006, the IDF bombed a building near the village, killing 28 of the civilians that were sheltering inside it. The number of people injured in the two attacks was about the same as the number of people killed. In 2004, the present author chose the name Qana for a predecessor of the current cryptographic application after reading about the 1996 shelling of the village in Robert Fisk's book, Pity the nation: Lebanon at war (3rd ed., Oxford University Press, 2001; ISBN 0192801309). As a name for a piece of software, Qana has the virtue of being short and distinctive.
This section assumes that you have some experience of building and running a Java application.
A Java Development Kit (JDK) that supports Java 17, such as Eclipse Temurin from Adoptium, is required to build Qana.
The src directory of the repository contains all the source code and
resources that constitute the application; there are no external dependencies. The
directory conforms to the Maven standard directory layout: the source code is in
src/main/java and the resources are in src/main/resources.
The supplied Kotlin-DSL-based Gradle
build script, build.gradle.kts, modifies the compileJava and
jar tasks (provided by the java plug-in) to compile the
application and to create an executable JAR file for it.
The supplied Kotlin-DSL-based Gradle build script, build.gradle.kts,
defines two tasks that may be used to run Qana:
compileJava task.
jar task.
Both tasks extend the JavaExec task.
To prevent a new instance of the application from being run each time a file that is associated with Qana is opened from, for example, a file browser, only one instance of Qana may be run at any one time. When Qana starts up, it checks whether another instance of the program is running; if it finds one, it terminates after informing the the other instance of any files that should be opened.
Qana may be run indirectly by associating file types with its JAR file and opening a file of one of those types. File associations can be created on Windows with the Options > Manage file associations command. You can use the same command to remove the file association when you no longer want it.
When it starts up, Qana is configured with configuration properties that are read from two sources: the command line of the Java launcher and a configuration file whose location may be explicitly specified. If the same property is specified on the command line and in a configuration file, the value from the configuration file takes precedence.
The recommended method of setting the properties in a configuration file is with the Options > Preferences command. For command-line properties, which must be edited manually, the form of the property values is given in an appendix, and it can also be inferred by generating a configuration file with the desired values and inspecting the contents of the file.
When Qana is run, configuration properties may be passed to the java
launcher on the command line as system properties; eg,
-Dapp.general.mainWindowLocation="100, 0". Qana's
command-line configuration properties all have the prefix app. . A list of
all the properties that are recognised by Qana is given in an appendix.
System properties can be added to the two supplied Gradle
tasks, runMain and runJar, with the
systemProperties(Map<String, ?>) method.
One particular property, app.configDir, is used to specify the directory that contains a configuration file, as described below.
The configuration file is named qana-config.xml. Qana doesn't require
a configuration file: it uses a default value for any configuration property that is
missing from the source(s) of configuration. Similarly, if it finds a property value to
be invalid, Qana will display a message to this effect and use the default value of the
property. If the configuration file contains a property that was specified on the
command line, the value from the configuration file is used.
If the configuration has changed when you exit the application normally (ie, using the File > Exit command or an equivalent), Qana will save its configuration to a configuration file. If a configuration file was read on startup, it will overwrite that file; otherwise, it will write a configuration file to the default directory described above, unless the value of the app.configDir property was an empty string.
A configuration file can be written explicitly with the Save configuration command within the Preferences dialog.
When it starts up, Qana is informed of the location of the configuration file with the app.configDir property. The value of the property may contain special constructs for system properties, environment variables and the user's home directory.
The app.configDir property may be set in two ways:
java launcher, or
qana-properties.xml that resides in the same directory as
the qana.jar JAR file.
The qana-properties.xml file is a legacy from the time when Qana was
distributed as a JAR file with an installer; the properties file was written by the
installer. If you create a properties file, it should have the following form, with the
example pathname replaced by the actual pathname:
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> <properties> <entry key="app.configDir">/home/slothrop/.blankaspect/qana</entry> </properties>
If the app.configDir property is set both on the command line and in the properties file, the value in the properties file takes precedence.
The existence and value of the app.configDir property determines the locations that are searched for a configuration file:
$PWD on Linux/UNIX systems, depends on the system and the way in
which Qana was run.
$HOME/.blankaspect/qana, where $HOME is the
environment variable that denotes the user's home directory. On Windows
systems, the default directory is %APPDATA%\blankaspect\qana, where
%APPDATA% is an environment variable.
Keys are an important aspect of Qana — important enough to warrant their own section in this manual.
Qana uses two kinds of cryptographic key:
When the term key is used by itself in this document, it generally means user key, though its meaning in any particular case should be clear from the context.
A user key is effectively an alias for a passphrase that is chosen by a user to encrypt a file, text or an archive. The key is a 256-bit number that is generated from a passphrase with a cryptographic hash function, which has the property that it is highly improbable that the same key will be generated from two different passphrases. Sometimes in this document, when the distinction is unimportant, key (in the sense of user key) is used as though it were synonymous with passphrase.
User keys are not used directly to encrypt data; their purpose is to produce content-encryption keys, which, as their name suggests, are the keys for the stream ciphers that are used for encrypting data. (A content-encryption key is actually the seed for a cryptographically secure pseudo-random number generator that generates the stream cipher.)
The key-derivation function (KDF) is one of the cryptographic cornerstones of Qana. (The other cornerstone is the Fortuna PRNG. In this metaphor, Qana is a building with only two corners.) Qana uses the KDF for two purposes:
The KDF is a one-way function that combines a key (a passphrase) and salt (a 256-bit random number) to give a 2048-bit output, which is either stored in the key database for verifying a passphrase or reduced to a 256-bit CEK. The function is deliberately made computationally intensive in the expectation that its large resource requirements — lots of memory, logic blocks or CPU time — will make a brute-force attack on the key too costly.
When a CEK is used for encryption, the salt and the values of the KDF parameters that were used to generate the CEK are stored as cleartext with the encrypted output so that they can be used to initialise the KDF for decryption. Given the same combination of user key and salt, the KDF will always generate the same value, but, because the salt is random, it is almost impossible for the same 256-bit CEK to be generated more than once, which prevents an attacker from gaining information about a user key or a CEK from multiple instances of ciphertext that are known to have been encrypted with the same user key.
Qana uses the scrypt function as its KDF. The time and memory demands of the function can be configured with a set of parameters, making the key more secure at the cost of a larger memory requirement and/or a longer computation time. A user key has two sets of these parameters, one for each of the KDF's two purposes: one set of parameters is used for generating the value that it stored in a database for verifying the passphrase of the key; the other set is used for generating CEKs. You can configure the two sets of parameters independently of each other.
The implementation of scrypt in Qana is a reference implementation; it's not optimised, either for speed or for reduced memory requirements.
In Qana's implementation of the scrypt function, its resource requirements — memory usage and the number of processor operations (CPU time) — are controlled by four parameters. Three of the parameters are part of the scrypt specification; the fourth parameter allows the modification of a value that is fixed in the scrypt algorithm.
A fifth parameter, the maximum number of threads used by the KDF, affects the performance of the scrypt function but not its result. It is not included in the set of KDF parameters that is stored with the encrypted output of Qana for generating the CEK on decryption.
The scrypt algorithm and its parameters are described fully in the specification of scrypt, though the following description of the parameters should suffice for users of Qana.
A salt is an initialisation vector for the key-derivation function: a random input to the function whose purpose is to prevent the leakage of information from multiple uses of the same key by ensuring that the KDF produces a different derived key every time it is applied to the same input key. To achieve this, the salt must be unique.
The 256-bit salts that are used as inputs to the KDF are generated by a Fortuna PRNG similar to the one used to generate the stream cipher but with an entropy input that is intended to make the generation of salts truly random. If the quality of the entropy is sufficiently high, the salts will be uniformly distributed and are almost certain to be unique. (By an extension of the birthday problem in which a "year" has 2256 ≈ 1077 days, it can be seen that the probability that a PRNG will generate identical 256-bit values in the remaining lifetime of the Earth is vanishingly small.)
Because a salt is required only to be unique, there is no need to keep it secret, so salts are stored as cleartext in both the key database and the output from Qana's encryption operations.
As has been mentioned, the key-derivation function is intentionally costly in terms of memory usage and processor operations (CPU time). With the ability to configure the KDF, you can trade off the cost of verifying a user key or generating a content-encryption key against the strength of the key that is being verified or generated: you can have a stronger key if you're willing to wait a bit longer and/or use more memory each time its passphrase is verified or a CEK is generated from it. You can vary this trade-off between different keys — and also between key verification and CEK generation for the same key, since each user key has separate KDF parameters for the two uses of the KDF. (Some variation is redundant. It is possible, for example, to create multiple keys that all have the same passphrase but that differ from one another in their KDF parameters — slow and fast variants, perhaps. No benefit would be gained from such variation, however, because a set of keys with a common passphrase is only as strong as its weakest element.)
At the risk of stating the obvious, you can't strengthen the encryption of some data unless you re-encrypt the data with a stronger key, which is impossible if an adversary already has a copy of the ciphertext, so the principal aim when choosing KDF parameters for CEK generation should be to achieve the strongest CEKs that are likely to be needed over the expected lifetime of the ciphertext that is encrypted with those keys. (A similar aim applies to the choice of KDF parameters for passphrase verification.) This aim should be moderated by considering the costs of the KDF, as discussed below.
The two costs of the KDF — memory usage and CPU time — are constrained in different ways. The time that the function takes to run will vary between systems, but the constraint is essentially a human one: how long would it be acceptable for a user on the slowest system to wait for a key to be verified or a CEK to be generated? The memory usage of the KDF, on the other hand, has an absolute bound: the required amount of memory is either available on a given system or it isn't. You should bear these constraints in mind when choosing KDF parameters, and give consideration to the range of systems on which the KDF will run. Whilst it may be annoying when decrypting a file to have to wait a few seconds for a CEK to be generated on a slow system, it could be disastrous if there were not enough memory to generate the CEK.
In this context, it is worth noting the differences between the two uses of a KDF — key verification and CEK generation. Key verification is really just a convenience; if you can't verify a persistent key against a passphrase because your system doesn't have enough memory to run the KDF, it's no big deal: you can just create a temporary key with the same passphrase and minimal KDF parameter values for verification, and you can use the temporary key for encryption and decryption. In contrast, the KDF parameters that are used to generate a CEK become an immutable property of the ciphertext that was encrypted by the CEK: if you can't generate the CEK because your system doesn't have enough memory to run the KDF, you won't be able to decrypt the ciphertext. It is critical, therefore, that you choose KDF parameters for CEK generation that will allow the ciphertext that is encrypted by those CEKs to be decrypted on all the expected target systems.
You may be able to increase the amount of memory that is available to a Java virtual
machine from the default value with a command-line option of the Java launcher. For
example, the maximum heap size can be specified for the HotSpot JVM by using the -Xmx option on the
command line of the java tool.
You can try out sets of KDF parameters with the Generate a test key command that can be found in the KDF parameters dialog and the parameter panel of the Preferences dialog. The command gives an indication of the time it takes for the KDF to run, and it will display an error message if there's not enough memory for the KDF.
There are two levels of cipher in Qana's encryption system. At the upper level, encryption and decryption are performed with a stream cipher, which consists of a keystream of pseudo-random data that is combined with plaintext (for encryption) or ciphertext (for decryption) with an exclusive-OR (XOR) operation. The keystream is generated by a Fortuna pseudo-random number generator from an underlying cipher — referred to here as the base cipher. Qana provides a choice of two such base ciphers: an AES-256 block cipher running in counter mode or a Salsa20 cipher. (Salsa20 is a stream cipher that operates intrinsically on blocks of data in a counter mode.) There is scope for ambiguity in the use of the term cipher in this document because of the two levels of cipher, but, for practical purposes, you need consider only the base cipher, with its two possible flavours.
Ciphertext that is generated by one kind of base cipher cannot be decrypted by the other kind, so a means of identifying the cipher is stored with the ciphertext.
The cipher that is used for an encryption operation is determined from a combination of two properties of a user key — its preferred cipher and allowed ciphers — and a global default cipher. The default cipher is selected with Encryption > Default cipher command.
To avoid the need to specify a cipher explicitly for every encryption operation, a user key may have a preferred cipher that will be used automatically when encrypting with the key. A preferred cipher is optional; if a key has no preferred cipher, a default cipher will be used as long as it is in the set of a key's allowed ciphers.
A preferred cipher may be selected when a key is created, and it can be edited subsequently with the Encryption > Edit keys command.
If you don't specify a preferred cipher for a key, the default cipher will be used for encryption. In this case, you might want to restrict the ciphers that can be used; to do so, you can specify a set of allowed ciphers to which the default cipher must belong. An error message will be displayed if you try to encrypt with a default cipher that isn't allowed by the key. A key may have an empty set of allowed ciphers if it will be used only for decryption.
The set of allowed ciphers is specified when a key is created, and it can be edited subsequently with the Encryption > Edit keys command.
In terms of performance, there is not much to choose between the AES-256 and Salsa20 ciphers in their Qana implementations: in a comparative test that was performed on only one system, AES-256 took about 3% longer than Salsa20 to encrypt a set of files. (This should not be taken as a measure of the relative performance of the two ciphers when they are used normally, not as the base cipher of a PRNG.)
From the perspective of security, AES-256 is the safer choice: implementations of the Fortuna PRNG commonly use an AES cipher running in counter mode whereas Salsa20 is not being used as it was intended. The author knows of no cryptanalysis of the use of the Salsa20 cipher in an implementation of Fortuna. With this in mind, it is recommended that AES-256 be used as the base cipher.
The choice of AES-256 and Salsa20 as the base ciphers of the Fortuna PRNG in Qana is discussed in an appendix.
A user key associates a name with a passphrase and some properties:
When you perform a cryptographic operation in Qana, you must provide a passphrase that will be used to encrypt or decrypt the data. If you are performing multiple encryptions or decryptions with the same passphrase, it would be tiresome and error-prone to have to enter the passphrase every time, so Qana allows you to select a key that is associated with the passphrase. You must enter the passphrase to verify the key when you first select it during a Qana session; thereafter, whenever the key is required in the same session, you can select it without having to enter its passphrase.
There are two kinds of user key with differing lifespans:
$" followed by a numeric
index). You can convert a temporary key into a persistent key by renaming it in the
dialog that is displayed by the Encryption
> Edit keys command.
The main purpose of a persistent key is to verify the passphrase with which it is associated. To achieve this securely, the passphrase itself is not stored in the key database. Instead, the passphrase is combined with a random salt using the same key-derivation function (KDF) that is used to derive content-encryption keys, though the two uses of the KDF may have different parameters. The output value of the function is stored in the key database along with the salt and the parameters of the KDFs. The passphrase of a key is verified by applying the KDF to the candidate passphrase and the stored salt, and then checking that the output from the function matches the stored value. You can adjust the strength of a persistent key by changing its KDF parameters.
Because the KDF is a one-way function (a function that is computationally hard to invert), it is not feasible to obtain the passphrase from the derived value and the salt. While this makes the passphrase secure, it also means that you won't be able to recover a passphrase from a persistent key, so, after you've created a key that you are going to use for encryption, it is recommended that you check its passphrase by a procedure such as encrypting some text with the key that you've just created, then decrypting the ciphertext by creating a new (temporary) key with the same passphrase.
A temporary key may be useful if you want to encrypt or decrypt without the need to name a key or store it in the key database. (If you are using the key only for decryption, there's no need to specify KDF parameters because the required parameters will have been stored with the ciphertext.) If you use a temporary key for encryption, you should be careful to enter the passphrase correctly. Because of the risk of entering the wrong passphrase, an optional warning, controlled by the crypto.warnTemporaryKey configuration property, is displayed when encrypting with a temporary key.
A passphrase is a string of characters that is transformed into a user key. Qana uses a symmetric-key cipher, so the same passphrase is used for encryption and decryption. Because of this, the security of the cipher relies on keeping the passphrase secret.
A passphrase may contain any character from the Unicode Basic Multilingual Plane except control characters or surrogates. The maximum length of a passphrase is 1024 characters. (These constraints are imposed by the user interface, not by the implementations of the cryptographic algorithms.)
The design of Qana's encryption system — the choice of cryptographic algorithms and the structure of the ciphertext and key database — was aimed at reducing weaknesses to the point that the most feasible attack on Qana-encrypted ciphertext would be an attack on its passphrase, which can always be mounted against a secret-key cipher. If this aim has been achieved, the passphrase is the weak spot in Qana's system. Potential weaknesses lie in several areas, which are discussed in the following subsections.
Two common attacks on secret passphrases are dictionary attacks and brute-force attacks.
You can defend against a dictionary attack by avoiding passphrases that consist of unmodified words or words with predictable modifications (eg, replacing occurrences of the letter O with zero or appending a digit). You should also avoid predictable sequences of letters or digits.
A brute-force attack, on the other hand, will always succeed, given enough computing resources; the aim is to choose a passphrase for which an exhaustive search would be impracticable. A passphrase is transformed by a cryptographic hash function and key-derivation function into the 256-bit key of a stream cipher, so it should ideally provide at least 256 bits of entropy for the key. As a guide, if each character of a passphrase were selected randomly from the 95 printable ASCII characters with a uniform distribution (ie, each of the 95 characters is equally likely to be selected), the passphrase would need to be at least 39 characters long to provide the optimal entropy. This is a best-case example for the specified set of characters; in practice, the set will probably contain fewer characters, and they won't be evenly distributed, so a memorable passphrase of the same length will be more predictable than this and will therefore contain less entropy.
A brute-force attack on a strong passphrase is unlikely to succeed, so attackers may look for other ways to obtain it. One well-known approach is to capture a passphrase as it is entered by the user, which may be achieved by installing software or hardware on a target computer or device to record and report keystrokes, mouse movement and button actions, clipboard activity or screenshots. To thwart keyloggers, Qana allows you to enter a passphrase by pasting text into the field of a passphrase dialog. (A Paste command is available from the dialog's context menu.) The system clipboard is cleared after each Paste command, though this will not provide a defence against the logging of clipboard activity.
A passphrase with a high degree of entropy may not be easily memorable, so there may be a temptation to store it in some form; for example, by embedding it in a text file or writing it down. The security risks presented by different methods of storing passphrases will vary according to circumstances and will usually be obvious in any case.
An inherent problem with symmetric-key ciphers like Qana's is the need for the encrypter and decrypter to share the key (or its equivalent, such as a passphrase) if the encryption and decryption of data is not done by the same person. The method of sharing the passphrase should be at least as secure as the passphrase itself. A discussion of secure ways to share a passphrase is beyond the scope of this manual except for the suggestion that a public-key cryptographic system could be used.
A user key — either a persistent key or a temporary key — can be selected to be the global key with the Encryption > Set global key command. The global key has no significance by itself, but the Encryption > Automatically use global key option can be set so that the global key is used automatically whenever there is a need to specify a user key for an encryption or decryption operation. This may be particularly useful when encrypting or decrypting multiple files with drag-and-drop.
If a global key exists, its name is displayed in a field of the status panel of the main window.
A global key can be cleared with the Encryption > Clear global key command.
Every open document may have a user key associated with it — either a persistent key or a temporary key. This key, known as a document key, is set when an encryption or decryption operation is first performed on a document. It can also be set explicitly with the Archive > Set key command or Text > Set key command according to the kind of document. When a document key is set, it will be used automatically for subsequent encryption or decryption operations on the document until it is cleared or a new key is explicitly set.
If a global key exists and has been set to be used automatically, it will take precedence over a document key.
If a document key exists for the current document, its name is displayed in a field of the status panel of the main window.
A document key can be cleared with the Archive > Clear key command or Text > Clear key command according to the kind of document.
The key database is a file whose pathname is specified with the crypto.keyDatabase configuration property. The file is read when Qana starts up, and it is updated when the program exits if any persistent keys have been created or any existing keys changed.
If the specified database file does not exist when the program starts up, a warning is displayed. This will happen after Qana is installed for the first time because the crypto.keyDatabase configuration property has a default value. When the program exits, a key database will be created at the location specified by the configuration property if the file does not exist.
Qana supports two kinds of document: archive documents and text documents. Each kind document has an associated view.
In Qana, an archive consists of a set of encrypted files and a database — a file containing information about the files in the archive. The archive is managed through an archive document, which is displayed as an archive view in a tab of the main window. The view has the form of a table in which the rows are the files in the archive and the columns are attributes of those files.
An archive is hierarchical in the sense that its component files may have a directory
structure that is recreated when the files are extracted from the archive, like the
contents of a Zip file. Unlike a Zip file, however, the files in a Qana archive are not
stored together in a single file; they are stored as separate files in a single
directory, along with the database file. Each file in the archive is encrypted with its
own content-encryption key (CEK) and given a unique name of 64 hexadecimal-digit
characters to hide its identity. The name, CEK and original pathname of each file are
stored, with some additional information about the file, in the archive database, which
is encrypted with a user key and stored in the same directory
as the contents of the archive. The filename suffix of the database is user-defined and
defaults to .qarc. It is configured with the file.filenameSuffix.archive property.
An archive document has commands for adding files to the archive, extracting files from the archive, validating files in the archive and deleting files from the archive. The management of files in the archive should be performed with these commands, not directly on the files themselves.
An archive document is accessed with a single passphrase, which is used to encrypt the database file. The content-encryption key of each file in the archive is randomly generated and stored in the database. The database also contains, for each file, a random salt that is used in the generation of the name of the encrypted file. To maximise the security of files in the archive, it is necessary to have a high-quality entropy input for the PRNG that generates the CEKs and salts.
Although a text file can be encrypted as a general file, there is also provision in Qana for editing and encrypting text as a text document, without the need to store it as a file — and without the ability to store it as a file. A text document is displayed as a text view in a tab of the main window. The view is a text area with some basic editing commands including Undo/Redo.
A text document is intended to be used for the rapid composition, encryption and
decryption of text such as e-mail or IM messages.
The text content of a document can be transferred between Qana and other applications
through the system clipboard using copy-and-paste. If the general.clearClipboardOnExit configuration
property is set to true, the clipboard is cleared when Qana exits to
prevent the accidental escape of text that has been copied to the clipboard.
The text that is currently displayed in a text view may be encrypted with the Text > Encrypt text command. On encryption, the ciphertext replaces the plaintext in the text view. The ciphertext can be copied from the Qana document and pasted into another document — the body of an e-mail message, for example. Conversely, Qana-encrypted ciphertext may be copied from a source and pasted into a text view, then decrypted.
Encrypted text is encoded as Base64, which may be wrapped as a simple XML document if the Text > Wrap encrypted text in XML option is selected. (Technical note: The Base64 data may contain only characters from the 65-character Base64 alphabet, whitespace and line breaks, and the end of the data must be padded.)
When a text document is encrypted, the ciphertext may optionally be enclosed in a simple XML document. The XML wrapper serves two purposes: it identifies its contents as Qana-encrypted text (which may or may not be desirable), and it delimits the ciphertext so that the Text > Decrypt text command can find it within some enclosing text.
The XML document consists of a single element — the document element — whose
name is qanaText and whose only content is character data that is
Base64-encoded ciphertext. The element has a version attribute whose value is
the version number of the document's format.
The Text > Wrap encrypted text in XML
option affects the behaviour of the Decrypt command as well
as the output of the Encrypt command. If the XML wrapper
option is not selected, the Decrypt command expects its
input to be Base64-encoded ciphertext. If the XML wrapper option is selected, the Decrypt command does not expect a well-formed XML document as
input; instead, it searches the input text for the first <qanaText>
start tag and the </qanaText> end tag that follows it, and it
processes the text between the two tags as though it were an XML element whose text
content is Base64-encoded ciphertext. The relaxed form of the input to the Decrypt command allows XML-wrapped ciphertext to be included
within arbitrary text — embedded in the body of an e-mail message, for instance.
Qana uses a tabbed document interface to display multiple documents. This kind of interface has a single tabbed window in which only one document — referred to as the current document — is visible at any one time. Each open document has its own view in a tab of the main window: either an archive view or a text view according to the kind of document. A maximum of 64 documents may be open simultaneously.
You can select a document by clicking on its tab, or you can select a document from the alphabetically ordered list that is displayed by clicking on the down-arrow button at the right of the tab bar. You can move between documents by pressing Ctrl+PageUp and Ctrl+PageDown.
The main window can be moved and resized in a platform-dependent manner (for example, it may be possible to change the size by dragging a corner of the window).
The location and size of the main window can be saved between Qana sessions according to preferences for, respectively, saving the main window location and saving the main window size. If the size of the main window is not saved, the window is sized to fit the larger of an archive view and a text view, whose sizes are determined indirectly by several configuration properties. The size of an archive view is determined by its number of viewable rows and the sum of the widths of its visible columns; the size of a text view is specified by the text.view.size property and the text view font.
Information about the files in an archive is displayed in a table of between one and four columns: Path, Size, Timestamp and Hash value. The Path column shows the pathname of the file in the archive; any directories in the pathname will be created when the file is extracted. The Size and Timestamp columns show those attributes of the original file. The Hash value column shows a cryptographic hash value of the file, which is also the name of the encrypted file in the archive directory.
Several of the archive commands apply only to files whose rows are selected in the table. The number of selected files is displayed in a field of the status panel. The selection of multiple groups of contiguous rows is allowed. None of the cells in the table is editable.
The up/down arrow in the column header indicates the sort key — the column that determines the order of the rows of the table — and whether the rows are arranged in ascending or descending order. You can change the sort key and toggle between ascending and descending order by clicking on the appropriate column header.
The initial widths of the four columns and the presence of all columns except the Path column are configured with the archive.view.columnWidth properties. You can set the initial column widths to the current widths with the Set from current view command in the Archive view tab of the Preferences dialog. You can change the widths of the columns by dragging the separators of the column headers, and you can change the order of the columns by dragging the column headers left or right; any changes will apply only to the view in which they are made.
Above the table of archive contents is a panel with a folder icon near its left edge. This is the archive directory panel in which the pathname of the directory that contains the files of the archive is displayed. The panel has its own drag-and-drop behaviour and a context menu containing a single command for setting the archive directory.
A text view is a multi-line text area in which you can type text and perform the standard editing functions of cut, copy and paste. A simple undo/redo facility is available. The text view does not support any presentational attributes (eg, bold or italic font styles).
The initial dimensions of the text area are specified by the text.view.size configuration property. If the initial dimensions of the archive view are greater than those of the text view, the initial dimensions of the text view will be increased to those of the archive view.
The foreground (text) and background colours of the text view can be configured with several colour properties. The font that is used in the text view can also be configured.
At the bottom of the main window, below the tabbed document panel, is a status panel comprising five fields, some of which may be empty. The fields have the following contents:
Qana has a standard dialog box for selecting a user key for encryption or decryption. Most of the dialog is taken up by a list of available keys. Each item in the list consists of the name or generic designation of a key and an icon that indicates the kind of key or its status.
The first item in the list is always New, which creates a new temporary key. If you select New, you will have to enter a passphrase and properties for the new key — two sets of KDF parameters, a preferred cipher and a set of allowed ciphers — in the dialogs that follow. A temporary key will be created with a generic name, and it will be available for selection the next time a key-selection dialog is displayed.
Any temporary keys that are in existence are listed immediately below the New
item. Temporary keys have a generic name consisting of the prefix
"$" followed by a numeric index. If you select a temporary key,
you will not have to verify its passphrase because you will have entered the passphrase
when the key was created.
Any remaining keys in the list are persistent keys. A tick next to the name of the key indicates that the passphrase of the key has been verified during the current Qana session. If you select a persistent key whose passphrase has not yet been verified, you will have to enter the passphrase in the dialog that follows.
Qana has a standard dialog box for entering the passphrase of a user key when creating or verifying the key. The dialog consists mainly of a single field in which you enter the passphrase. When the dialog is displayed, the characters that you enter in the passphrase field are hidden; you can make them visible by issuing the Show command from the button adjacent to the field or from the dialog's context menu. The text of the button changes to Hide when the contents of the passphrase field are visible.
The dialog has a Paste command, which can be issued through the dialog's context menu or by pressing Ctrl+V when the passphrase field has keyboard focus. The command pastes text from the system clipboard into the passphrase field, then clears the clipboard.
The passphrase field will accept any character from the Unicode Basic Multilingual Plane except control characters or surrogates. The maximum length of a passphrase is 1024 characters.
If your system supports the dragging and dropping of files (for example, from a file manager such as GNOME Nautilus or Windows Explorer), there are several areas of Qana's main window and dialog boxes that you can drag and drop files or directories onto.
You can drag and drop multiple files onto all areas of the main window except for the archive directory panel of an archive view, which has special drag-and-drop behaviour for setting the archive directory. The action that results from dragging and dropping files onto the main window depends on the filename suffix of each file and on some configuration properties:
.qarc, the file is opened as an archive
document.
.qana, the file is either
decrypted or validated according to the value of the general.encryptedFileDragAndDropAction
configuration property.
If the drag-and-drop action is to encrypt or decrypt the file and the file.selectEncryptDecryptOutputFile.dragAndDrop
configuration property is set to true, a dialog box is displayed in which
you can select the output file; otherwise, the output file will be in the same directory
as the input file and its name will be derived from that of the input file.
Dialog boxes are displayed in response to some of Qana's commands. Some of the dialogs contain non-standard graphical components or standard components that have unusual features.
A spinner is a graphical component for editing a numerical value. It consists of a text field adjacent to a pair of small buttons. The value in the text field may be edited manually, or it may be incremented and decremented by one of the following methods:
Using the last two methods, the amount by which the value is incremented or decremented can be modified by holding down the Ctrl, Shift or Ctrl+Shift keys, which correspond to increments of 10, 100 and 1000 respectively.
A pathname field is a text field that is intended to hold the pathname of a file or directory. The browse button (…) adjacent to the field brings up a file-selection dialog whose selection will be displayed in the field if the dialog is accepted.
The pathname in the field may contain special constructs for system properties, environment variables and the user's home directory.
You can transfer a file or directory to a pathname field by drag-and-drop or by copy-and-paste from a file manager.
Qana provides several cryptographic functions, each of which has a complementary pair of commands for encryption and decryption:
This section describes the various functions, some aspects of which are described in more detail in other sections.
A file can be encrypted with the File > Encrypt file command. A file that has been encrypted in this way can be decrypted with the File > Decrypt file command. The integrity of an encrypted file can be checked with the File > Validate file command. All three commands appear in the main context menu as well as the main menu.
By default, an encrypted file is given the name of the input file with a user-defined
suffix, which defaults to .qana. (For example, a file named
mySecretDiary.odt would be encrypted as
mySecretDiary.odt.qana.) The filename suffix is configured with the file.filenameSuffix.encrypted property.
Multiple files can be encrypted and decrypted by dragging and dropping them onto the main window.
Although a text file can be encrypted as a general file, there is also provision for encrypting text as a text document, without the need to store it as a file. A text document is created with the Text > New text command, which opens a new text view in a tab of the main window. The view is a text area with some basic editing facilities including Undo/Redo.
Text can be transferred between the Qana document and other applications through the system clipboard using copy-and-paste. If the general.clearClipboardOnExit configuration property is set to true, the clipboard is cleared when Qana exits to prevent the accidental escape of plaintext that has been copied to the clipboard.
The text of a text document can be encrypted with the Text > Encrypt text command, and encrypted text can be decrypted with the Text > Decrypt text command. Encrypted text is encoded as Base64, which will be wrapped as a simple XML document if the Text > Wrap encrypted text in XML option is selected.
When text is encrypted, the current time is included in the ciphertext. When the ciphertext is decrypted, the timestamp is displayed in a field of the status panel below the text view.
More details on the encryption of text can be found in the sections on text documents, Edit menu commands and Text menu commands.
An archive denotes a collection of encrypted files that is managed through an archive document.
An archive document is created with the File > New archive command, which opens a new archive view in a tab of the main window. Before you can add files to the archive, you must specify the archive directory — the directory in which the contents of the archive and the database will be stored. The archive directory is shown in the panel below the document tab in the main window. You can specify the archive directory by the following methods:
You can change the archive directory only while the archive is empty.
You can open an existing archive with the File > Open archive command, which brings up a file-selection dialog in which you can choose the archive database file to open. Alternatively, you can drag and drop an archive database file onto the main window. (An archive database is recognised by having the filename suffix that is specified by the file.filenameSuffix.archive configuration property.)
A key-selection dialog will be displayed in which you can choose the key that will be used to decrypt the archive database. If the database is successfully decrypted, it will be opened as an archive document in a tab of the main window.
When an archive is opened, the directory containing the database file will be set as the archive directory and the existence of all the files in the database will be checked. The entry of any file that cannot be found in the archive directory will be deleted from the database and an error message displayed to this effect, followed by a list of missing files. If you then save the archive, the missing files will become permanently inaccessible because their encryption keys, which were randomly generated and stored in the database, will be lost forever. If the files are missing temporarily from the archive directory (eg, because you are splitting an archive), it important that you make a backup copy of the archive database file before you save it with the entries for the missing files deleted.
To add files to the archive, issue the Archive > Add files command, which will bring up a dialog box in which you can select the files that you want to add. Within the dialog, you can select files by the following methods:
All three methods allow you to select directories as well as files. If you select a directory, all the files below the directory (ie, all the files in the directory itself and, recursively, in any of its subdirectories) will be selected, and the files will be added to the archive with a pathname that begins with the selected directory.
You can remove selected files from the Input files list box with the Remove command (Shift+Delete).
To allow you to check the pathname that a file will have when it is added to the archive, you can toggle the list of files between system pathnames and archive pathnames using the System/Archive button to the lower right of the Input files list box. The other kind of pathname is displayed as a tooltip when the mouse cursor hovers over the file in the Input files list box.
If you try to add a file that has the same archive pathname as a file that is already in the archive, you will be asked whether you want to replace the existing file. Such a conflict may arise even within the set of files in the Input files list box because, while each file in the list must have a unique system pathname, it is possible to select multiple files that have the same archive pathname.
The Archive > Extract files command decrypts the selected files and writes them to a specified directory. When you issue the command, a dialog box is displayed in which you can choose the directory to which the decrypted files will be written. Each decrypted file will be written to the chosen directory with the pathname that it has in the archive, including any directory structure.
The Archive > Validate files command validates the selected files by reading and decrypting them but without writing any output. The command can be used to check the integrity of files in the archive.
The Archive > Delete files command deletes the selected files from the archive. Each selected file is deleted in two respects: the file's entry is removed from the archive database and the encrypted file is deleted from the file system. Unless you are deleting an entire archive, it is recommended that you use this command to delete files from an archive rather than deleting the files directly from the file system.
The practice of concealing data in an image is an example of steganography. In Qana, a general file or the content of a text document can be encrypted and concealed in an image file in a single operation.
The operation to conceal data in an image has two inputs, a payload and a carrier, from which a single output file is generated:
Within Qana, a carrier image is represented by an RGB colour model in which a pixel consists of three colour components, R(ed), G(reen) and B(lue), each of which is an 8-bit value. The encrypted payload is concealed in the image by replacing some low-order bits of the RGB components with bits of the payload. The replacements are spread evenly throughout the image. If the carrier is an image file, the maximum number of low-order bits that will be replaced by the payload is selectable, between one and four; if the carrier is autogenerated, the maximum is fixed at two bits. The more bits of the RGB components that are replaced by the payload, the greater is the visible difference between the input (carrier) and output images.
If the carrier is an image file, the dimensions of the image in pixels and the maximum number of replacement bits per RGB component will determine the maximum size of the payload that can be concealed in the carrier.
An autogenerated carrier image has an aspect ratio of 4:3, and both of the dimensions are divisble by 16. The minimum dimensions of an image are 128 × 96 pixels. Within these constraints, the dimensions of an autogenerated image are calculated to accommodate the encrypted payload in no more than two low-order bits of each RGB component. The two low-order bits of all RGB components of an autogenerated image are randomised to give a uniform level of noise throughout the image.
Autogenerated carrier images have a generic form consisting of overlaid polygons. The edges of the polygons may be linear or one of two kinds of cubic curve according to the value of the general.carrierImageKind configuration property.
For steganography to be successful, the existence of concealed data should not be suspected by an adversary. In this respect, the form of concealment offered by Qana has two significant weaknesses:
You can conceal a file in an image with the File > Conceal file in image command, which brings up a dialog in which you can select the input files, output file and some additional parameters of the concealment operation.
The Payload file field specifies the plaintext file that is to be encrypted and concealed.
The Carrier file and Autogenerated carrier radio buttons select the kind of carrier — the image in which the encrypted payload is to be concealed. If the Carrier file button is selected, the adjacent field specifies the file; otherwise, the image is automatically generated.
The Output file field specifes the image file that will contain the concealed data.
If you choose a carrier file rather than an autogenerated carrier, the three components at the bottom of the dialog will be enabled:
The Maximum number of bits drop-down list allows you to select the maximum number of low-order bits of the RGB components of the image that will be replaced by the payload.
If the Set timestamp check box is enabled, the timestamp of the output file will be set to the timestamp of the carrier file.
If the Add random bits check box is enabled, all the low-order bits of RGB components of the image that are not replaced by bits from the payload will be randomised. (The number of bits of each RGB component that will be randomised is the the value that is selected from the Maximum number of bits drop-down list). The purpose of the randomisation is to disguise the presence of the payload by adding noise uniformly to all the pixels of an image, as though dither had been applied.
The format of the carrier file is restricted to the image formats that are supported by the particular Java runtime environment, which will typically include GIF, JPEG, and PNG formats. An error message will be displayed if the format of the carrier file is not supported.
If the Conceal file dialog is accepted with the Conceal command and there is no automatic use of a global key, a key-selection dialog will be displayed for you to select the key that will be used to encrypt the payload.
A file that has been concealed in an image can be recovered with the File > Recover file from image command, which brings up a dialog in which you can select the input file and output file.
If the Recover file dialog is accepted with the Recover command and there is no automatic use of a global key, a key-selection dialog will be displayed for you to select the key that will be used to decrypt the concealed ciphertext.
You can conceal the content of a text document in an image with the Text > Conceal text in image command, which brings up a dialog similar to the one that is displayed for concealing a file except that there is no Payload file field since the payload is implicit.
If the Conceal text dialog is accepted with the Conceal command and there is no automatic use of a global key, a key-selection dialog will be displayed for you to select the key that will be used to encrypt the text.
Text that has been concealed in an image can be recovered with the Text > Recover text from image command, which brings up a dialog in which you can select the input file.
If the Recover text dialog is accepted with the Recover command, a new text document will be created for the recovered text. If there is no automatic use of a global key, a key-selection dialog will be displayed for you to select the key that will be used to decrypt the concealed ciphertext.
Qana provides a facility for splitting a large file into a set of smaller, encrypted files for secure storage or transmission, and for recombining the set of files into the original file. The files that result from the splitting operation are referred to as file parts. Each file part is encrypted with the same user key but a different content-encryption key and written to a specified directory with a generic filename. The name of each file part is a unique string of 40 randomly generated hexadecimal-digit characters that must not be changed or the set of file parts will be inconsistent. The timestamp of each file part is set to that of the original file.
When a file is split, the lengths of the sections into which it is divided are randomly selected from a specified range. The lengths of the output files (ie, the file parts) cannot be controlled directly because the plaintext is compressed before encryption.
When file parts are recombined, they must all be in the same directory. If the directory contains additional files that have the generic name of a file part (40 hexadecimal-digit characters), you must be able to identify the set of file parts that you want to recombine by the name of its first file, the number of its parts or its timestamp.
You can split a file with the File > Split file command, which brings up a Split file dialog.
The Input file field specifies the file that will be split.
The Output directory field specifies the directory to which the file parts will be written.
The output directory should not already contain any files that have the generic name of a file part unless, when you come to recombine the parts, you are able to select the set of file parts by the name of its first file, the number of its parts or its timestamp. If the output directory already contains files that have the generic name of a file part, you will be asked whether you want to delete them before the file is split.
The File-part length spinners specify the lower and upper bounds of the lengths of the sections into which the input file is divided. The button to the right of each spinner cycles through the following units of the spinner's value:
| B | bytes | |
| KiB | kibibytes | 1 KiB = 210 bytes = 1024 bytes |
| MiB | mebibytes | 1 MiB = 220 bytes = 1048576 bytes |
To the right of the File-part length spinners is a button that links and unlinks the lower and upper bounds of the length range. When the bounds are linked, changing the value of one bound automatically changes the value of the other bound; when the bounds are unlinked, they can be changed independently of one another.
If the Split file dialog is accepted with the Split command and there is no automatic use of a global key, a key-selection dialog will be displayed for you to select the key that will be used to encrypt the file parts.
You can recombine the parts of a split file with the File > Join files command, which brings up a Join file dialog.
The Input directory field specifies the directory in which the file parts are located. All the file parts must be in this directory.
The Output file field specifies the file that will be created by joining the input file parts together.
If the Join files dialog is accepted with the Join command and there is no automatic use of a global key, a key-selection dialog will be displayed for you to select the key that will be used to decrypt the file parts. If the input directory contains more than one set of file parts, a further dialog is displayed for you to select the set of file parts that you wish to recombine. The dialog contains a list of the available sets, each of which has three fields: the filename of the first file part of the set, the number of file parts in the set, and the timestamp of the first file part.
Qana's main commands are accessible from its main menu. Some of the commands are also accessible from context menus that are activated in a system-dependent manner (eg, by pressing or releasing the right mouse button) while the mouse cursor is over the main window.
The items in the Edit menu differ according to whether the current document is an archive document or a text document.
The New archive command (Ctrl+N) creates a new archive document.
The command is disabled if the maximum number of documents are open in the application.
The Open archive command (Ctrl+O) brings up a file-selection dialog in which you can choose the archive document that you want to open.
The command is disabled if the maximum number of documents are open in the application.
The Revert archive command reads the current archive document again from the file system, replacing the modified document in Qana. Any changes that you have made to the current document will be lost.
The command is disabled if the current document has not changed from when it was last opened or saved.
The Close document command (Ctrl+W) closes the current document. If the document is an archive document and has unsaved changes, you will be prompted to save the document before it is closed. If the document is a non-empty text document, you will be asked to confirm its closure.
The Close all documents command closes all open documents. You will be prompted to save any archive documents that have unsaved changes and asked to confirm the closure of any non-empty text documents.
The Save archive command (Ctrl+S) writes the current archive document to a file. If the document has no key (eg, because it is a new document or its key has been cleared) and there is no automatic use of a global key, a key-selection dialog will be displayed.
The command is disabled if the current document has not changed from when it was last opened or saved.
The Save archive as command writes the current archive document to a file. The command brings up a file-selection dialog in which you can select the pathname of the file to which the document will be written. A warning is displayed if the selected file already exists. If the document has no key (eg, because it is a new document or its key has been cleared) and there is no automatic use of a global key, a key-selection dialog will be displayed for you to select the key that will be used to encrypt the archive database.
After the archive document is written to the selected file, the document's archive directory will be set to the parent directory of the file. If this is different from the original archive directory, the database and contents of the archive will be inconsistent unless the contents have been copied or moved to the new directory.
The Encrypt file command encrypts a general file. If the
file.selectEncryptDecryptOutputFile.menuCommand
configuration property is true, an Encrypt
file dialog is displayed in which the input file and output file can be selected;
otherwise, a file-selection dialog is displayed for selecting the input file, and the
output file will have the default pathname, described below. The output file will also
have the default pathname if the Output file field of the
Encrypt file dialog is empty.
The default output pathname is the pathname of the input file with the filename suffix
specified by the file.filenameSuffix.encrypted configuration
property appended to it. The default filename suffix is .qana .
If there is no automatic use of a global key, a key-selection dialog will be displayed for you to select the key that will be used to encrypt the file.
The Decrypt file command decrypts a file that was encrypted
with the Encrypt file command. If the file.selectEncryptDecryptOutputFile.menuCommand
configuration property is true, an Decrypt
file dialog is displayed in which the input file and output file can be selected;
otherwise, a file-selection dialog is displayed for selecting the input file, and the
output file will have the default pathname, described below. The output file will also
have the default pathname if the Output file field of the
Decrypt file dialog is empty.
If the name of the input file has the suffix specified by the file.filenameSuffix.encrypted configuration
property (.qana by default), the default output pathname will be the input
pathname with the filename suffix removed; otherwise, it will be the input pathname with
a numerical suffix appended to the filename stem.
If there is no automatic use of a global key, a key-selection dialog will be displayed for you to select the key that will be used to decrypt the file.
The Validate file command decrypts a file but without writing the plaintext to an output file. It can be used to check that a file was encrypted with a particular key or to check the integrity of an encrypted file. A file-selection dialog will be displayed for selecting the file that is to be validated, and, if there is no automatic use of a global key, a key-selection dialog will be displayed for you to select the key that will be used to decrypt the file. If the file is successfully validated, a message is displayed to that effect; otherwise, an error message is displayed.
The Conceal file in image command encrypts a file and conceals it in an image — either a specified image file or an automatically generated image. More information can be found elsewhere in the manual on the general subject of concealing data in an image and on the specific operation of concealing a file.
The Recover file from image command extracts and decrypts a file that was concealed in an image with the File > Conceal file in image command. More information can be found elsewhere in the manual on the general subject of concealing data in an image and on the specific operation of recovering a concealed file.
The Split file command splits a file into a set of encrypted files. More information can be found elsewhere in the manual on the general subject of splitting and recombining a file and on the specific operation of splitting a file.
The Join files command recombines into a single file a set of encrypted files that were split with the File > Split file command. More information can be found elsewhere in the manual on the general subject of splitting and recombining a file and on the specific operation of recombining a split file.
The Erase files command (Ctrl+Shift+X) erases files by overwriting them with random data and renaming them with a long random filename before removing them from the file system. The number of times that a file is overwritten is specified by the file.erasureNumPasses configuration property.
The erasure of files by overwriting may not be possible in some cases (for example, on copy-on-write file systems such as ZFS). Before relying on the Erase files command, it is recommended that you read about data erasure and the problems associated with it.
When you issue the Erase files command, a dialog is displayed in which you can select the files and directories that you want to erase. Within the dialog, the files and directories that will be erased are shown in the list box. You can add a file or directory to the list with the Add command, or you can use drag-and-drop or copy-and-paste to transfer multiple files or directories from a file manager. You can remove an item from the list with the Remove command (Shift+Delete). If you select a directory, the directory itself and all of its contents will be added to the list. A directory will be erased only if it is empty; that is, if it is already empty or all of its contents are erased too.
The Exit command terminates the application. Before the program shuts down, you will be prompted to save any open archive documents that have unsaved changes.
The Select all command (Ctrl+A) selects all the files in the current archive.
The Invert selection command inverts the selection of files in the current archive: files that are selected will be unselected and those that are not selected will be selected.
The edits that you make to a text document can be undone and redone with the complementary Undo and Redo commands (Ctrl+Z and Ctrl+Y respectively). The edits to a document are stored in a list whose length is limited by the general.maxEditListLength configuration property.
The Undo command reverses the last change to the current document. If an edit is undone with the Undo command, it can subsequently be restored with the Redo command provided that no other edits have been made since it was undone.
The Clear edit history command clears the history of edits to the current text document. The command may be used to make more memory available if a "Not enough memory" error occurs.
These commands behave in the standard way: the Cut and Copy commands both copy the selected text from the current document to the system clipboard, and the Cut command then deletes the selected text. The Paste command inserts text from the system clipboard into the current document at the caret (text cursor).
The Copy all command (Ctrl+Shift+C) copies the entire contents of the current document to the system clipboard.
The Paste all command (Ctrl+Shift+V) replaces the entire contents of the current document with text from the system clipboard.
The Clear command (Ctrl+Shift+Delete) deletes the entire contents of the current document.
The Select all command (Ctrl+A) selects all the text in the current document.
The selected text within a text document can be processed with a word-wrapping algorithm that performs two operations on the text:
For the first operation, the end of a sentence is defined by an end-of-sentence pattern, a regular expression that is specified by the text.wrap.endOfSentencePattern configuration property. If the end-of-sentence pattern is empty, no operation is performed. If the pattern is not empty, it is implicitly extended by one or more spaces, and the text is searched for the extended pattern. For each match of the extended pattern, the spaces that follow the end of a sentence are replaced by the number of spaces specified by text.wrap.numSpacesBetweenSentences configuration property.
For the second operation, the text is deemed to be composed of one or more paragraphs, where successive paragraphs are blocks of text that are separated by two consecutive line ends (ie, a line end followed by a blank line). The text within a paragraph is deemed to be composed of words, where a word is one or more consecutive non-space characters, and words are separated by one or more spaces. For each paragraph, the wrapping algorithm tries to fit as many words as possible on a line, up to a specified line length and breaking a line only between words.
The Wrap text command (Ctrl+R) brings up a dialog in which you can specify the line length and indent that will be applied by the word-wrapping algorithm.
The line length is specified in the Line length combo box of the Wrap text dialog. The value of the line length that initially appears in the combo box is specified by the text.wrap.defaultLineLength configuration property. If the Line length combo box is empty or the line length is zero, each paragraph of the text is unwrapped onto a single line.
Each line of wrapped text may be indented by a number of spaces, as specified in the Indent combo box of the Wrap text dialog. The indent specifier consists of either a single argument or two arguments, separated by a comma:
The arguments may be either absolute or relative values; a relative value is either (a) the current indent of the first line of the paragraph with an optional offset, or (b) for the second argument, the indent of the first line of the paragraph after the first argument is applied, with an offset.
The following tables describe the arguments of an indent specifier:
| First argument | |
|---|---|
| n denotes a decimal number between 0 and 999 inclusive, and [+|−] denotes either a plus or minus character. | |
| n | Absolute indent |
| $ | The current indent of the first line |
| $[+|−]n | Relative to the current indent of the first line |
| Second argument | |
|---|---|
| n denotes a decimal number between 0 and 999 inclusive, and [+|−] denotes either a plus or minus character. | |
| n | Absolute indent |
| $ | The current indent of the first line |
| $[+|−]n | Relative to the current indent of the first line |
| [+|−]n | Relative to the indent of the first line after the first argument is applied |
If the Wrap text dialog is accepted with the Wrap text command, the two operations described above are performed on the selected text, which is replaced by the processed text.
The Choose archive directory command (Ctrl+Alt+D) brings up a file-selection dialog in which you can choose the directory of the current archive. More information can be found elsewhere in the manual on the general subject of managing an archive.
The command is disabled if the current archive is not empty.
The Add files command (F5) brings up a dialog in which you can select files to add to the current archive. More information can be found elsewhere in the manual on the general subject of managing an archive and on the specific operation of adding files to an archive.
The command is disabled if the archive directory has not been set for the current archive.
The Extract files command (F8) brings up a dialog in which you can select an output directory. If the dialog is accepted, the files that are selected in the current archive are decrypted and written to the specified directory. More information can be found elsewhere in the manual on the general subject of managing an archive and on the specific operation of extracting files from an archive.
The command is disabled if no files are selected in the current archive view.
The Validate files command validates the selected files in an archive by decrypting them without writing the decrypted files. More information can be found elsewhere in the manual on the general subject of managing an archive and on the specific operation of validating files in an archive.
The command is disabled if no files are selected in the current archive view.
The Delete files command (Ctrl+Shift+Delete) deletes the selected files from an archive. More information can be found elsewhere in the manual on the general subject of managing an archive and on the specific operation of deleting files from an archive.
The command is disabled if no files are selected in the current archive view.
The Display list of files command (Ctrl+Alt+L) brings up a dialog in which a list of the selected files is displayed. The items in the list are the archive pathnames of the files. The list can be copied to the system clipboard.
The command is disabled if no files are selected in the current archive view.
The Display map of files command (Ctrl+Alt+M) brings up a dialog in which a map of the selected files is displayed. The map entry for each file consists of its archive pathname and its hash value (the name of the encrypted file in the archive directory), separated by a tab character (U+0009). The map can be copied to the system clipboard.
The command is disabled if no files are selected in the current archive view.
The Set key command (Ctrl+K) brings up a key-selection dialog in which you can select the document key for the current archive document.
The Clear key command (Ctrl+Shift+K) clears the document key of the current archive document.
The command is disabled if the current document does not have a document key.
The New text command (Ctrl+T) creates a new text document.
The command is disabled if the maximum number of documents are open in the application.
The Encrypt text command (F5) encrypts the content of the current text document and replaces it with the ciphertext. The ciphertext will be wrapped as a simple XML document if the Text > Wrap encrypted text in XML option is selected. More information can be found elsewhere in the manual on the general subject of encrypting text.
The Decrypt text command (F8) decrypts the content of the current text document on the assumption that it was encrypted with the Text > Encrypt text command. If the Text > Wrap encrypted text in XML option is selected, the ciphertext is assumed to have an XML wrapper. If the text is successfully decrypted, the content of the current document is replaced with the plaintext. More information can be found elsewhere in the manual on the general subject of encrypting text.
The Wrap encrypted text in XML option (Ctrl+F9) affects both the encryption and decryption of text. It determines
The Conceal text in image command encrypts the content of the current text document and conceals it in an image — either a specified image file or an automatically generated image. More information can be found elsewhere in the manual on the general subject of concealing data in an image and on the specific operation of concealing text.
The Recover text from image command extracts and decrypts text that was concealed in an image with the Text > Conceal text in image command. If the text is successfully recovered, a new document will be created for it. More information can be found elsewhere in the manual on the general subject of concealing data in an image and on the specific operation of recovering concealed text.
The command is disabled if the maximum number of documents are open in the application.
The Set key command (Ctrl+K) brings up a key-selection dialog in which you can select the document key for the current text document.
The Clear key command (Ctrl+Shift+K) clears the document key of the current text document.
The command is disabled if the current document does not have a document key.
The Set global key command (Ctrl+G) brings up a key-selection dialog in which you can select the global key. Use of the global key is controlled by the Encryption > Automatically use global key option.
The Clear global key command (Ctrl+Shift+G) clears the global key.
The command is disabled if no global key has been set.
The Automatically use global key option (Ctrl+H) controls the use of a global key, if one is set. If this option is selected, the global key is used automatically whenever there is a need to specify a user key for an encryption or decryption operation, which may be useful when encrypting or decrypting multiple files with drag-and-drop.
The Default cipher menu item brings up a submenu from which you can select the cipher that will be used by default as the base cipher for an encryption operation if the selected user key does not have a preferred cipher.
The name of the current default cipher is displayed in a field of the status panel, from where it can be changed by clicking on the field.
The Edit keys command brings up a dialog in which you can edit the user keys. On the left of the dialog is a list box similar to that of a key-selection dialog: the list contains the names of temporary keys followed by persistent keys.
On the right of the dialog are boxes in which the properties of the selected key — the two sets of KDF parameters, the allowed ciphers and the preferred cipher — are displayed.
Also on the right of the dialog is a panel containing a Name field and four buttons. The buttons issue commands for
editing the keys; a description of their function is shown as a tooltip when the mouse
cursor hovers over the button. The Name field is used to
provide the name of a key for the Add and Rename commands. The name of a persistent key may not contain the $
character, which is reserved for use in the names of temporary keys.
If you issue a command that applies to an existing key, the key must be verified before the command can proceed. If the key has not already been verified, a passphrase dialog is displayed when the command is issued.
The Add command adds a new key to the list. The name of the new key is specified in the Name field.
The Rename command renames the selected key. The new name of the key is specified in the Name field. If you rename a temporary key, it becomes a persistent key.
The Edit properties command brings up a dialog in which you can edit the properties of the selected key (the two sets of KDF parameters, the allowed ciphers and the preferred cipher). The KDF properties dialog has a command for generating a test key with the selected parameter set and displaying the time taken to generate the key. The Edit properties command can also be issued by double-clicking on a key in the list box.
The Delete command deletes the selected key from the list.
The Show entropy metrics command (Ctrl+M) brings up a dialog that displays measurements relating to the entropy accumulator of the Fortuna PRNG. The dialog is described in the section on entropy metrics.
Qana has a facility for generating garbage: meaningless random data that has the form of Qana's encrypted output — a file, text or an image. You can use the garbage to confound an adversary by mixing it with genuine ciphertext, which you can attempt to pass off as garbage if confronted about your cryptographic activity. (Indeed, the mere ability to generate garbage may be enough to enable you to claim plausibly that some ciphertext is garbage.) Conversely, an attacker that intercepts some pseudo-ciphertext may devote resources to trying to decrypt it in the belief that it's the real thing.
The Generate garbage command brings up a dialog in which you can select the form of garbage that you want to generate (file, text or image) and the length of the random data. In the case of the file and image, you will need to specify the output file. You may either specify the length explicitly or choose a range from which a random length will be selected with the Randomise command. (The units KiB and MiB that are used in the length ranges are described in this table.)
If text output is selected, a new text document is created and the spurious ciphertext is set as its content. The text is wrapped in XML according to the Text > Wrap encrypted text in XML option.
The form of an automatically generated image is described in the section on concealing data in an image.
The Show full pathnames option controls whether the full pathname of the current archive document or only its filename is displayed in the title bar of the main window.
The Manage file associations command provides, on Windows, a means of adding or removing associations between the Qana application and files with the filename suffixes of Qana-encrypted files and Qana archives. A file association will allow you, for example, to open an archive in Qana by double-clicking on its filename in Windows Explorer. If Qana is already running, the file will be opened in it; otherwise, the file will be opened in a new instance of Qana.
The command creates file associations by modifying entries in the Windows Registry, which it does by generating and executing a Windows PowerShell script. You may execute the script automatically after it is generated, or you can write a script file that you can use outside Qana. In order to run the script, you must have PowerShell 2.0 or later installed on your system.
The command is enabled only if the application is run on Windows.
The command brings up a dialog box that controls the content of the PowerShell script
and the way in which it is used. At the top of the dialog is a drop-down list from
which you can select the action that you want to perform: Add creates new file
associations or modifies existing ones; Remove removes file associations that
were created with the Add option. (If you add file associations, you will
probably want to remove them before you change the the filename suffixes of Qana-encrypted files
or Qana archives or
before you uninstall Qana.) The same script is used for both adding and removing file
associations; the difference in behaviour is achieved by adding a switch (the argument
-remove) to the command line when the script is used to remove file
associations.
Below the Action drop-down list are fields in which you specify the locations of three files that are required to create the file associations. The fields are disabled if the selected action is Remove because the locations of the files aren't required when removing file associations, but the content of the fields is always included in the script in case you want to retain a single script for dual purposes.
The pathnames of the three files may contain special constructs
for system properties and environment variables. If a specified system property exists,
the construct that denotes the property key (eg, ${java.home}) will be
replaced by the property value. Environment variables, however, will not be expanded
but will be converted to their Windows form (eg, ${JAVA_HOME} will be
converted to %JAVA_HOME%) before they are included in the script. The
environment variables will be set in Registry values and expanded by the operating
system.
Environment variables of the form %name% may appear in a pathname,
but they don't have a special significance in Qana and are treated as literal text.
If a pathname contains environment variables of this form, you should ensure that the
Files must exist check box is not selected to avoid an
error when the pathnames are resolved.
To add file associations, the files whose locations you must specify are:
javaw.exe (no console) or java.exe (console). The
corresponding Default command sets the pathname to that
of the file bin\javaw.exe in the directory specified by the
java.home system property, which is the Java installation directory that
is associated with the current Qana application. If you install another version of
Java, the Java launcher might be at a different location; if so, you will need to
update the file association accordingly.
app.ico, which can be
found in the uk.blankaspect.qana.images package of the application's
resources, is provided for this purpose, but you may choose any suitable icon file to
associate with Qana files.
The Files must exist check box below the pathname fields should be selected if you want Qana to check that the three files exist before it generates a script. You should not select the check box if any of the pathnames contain Windows-form environment variables, but environment variables in the form of special constructs will be expanded when a pathname is resolved.
The Script life cycle drop-down list controls what
happens to the PowerShell script after it is generated. For all options, a script file
named qanaAssociations.ps1 is written to a subdirectory of the
system's temporary directory, which is typically AppData\Local\Temp
within the user's home directory. The subdirectory has the prefix
qana_ , and the full pathname is displayed when the script file is written.
After the file has been written, it may be executed and optionally deleted after
execution, according to selection from the Script life
cycle drop-down list. If you don't want to preserve the script, the default
option of Write, execute and delete will add or remove file associations without
leaving a residue on the file system.
When you select OK, the pathnames are validated if the action is Add and the Files must exist check box is selected. If there is no error, a further dialog box is displayed in which the progress of script operations is reported, along with any error messages from Qana or the operating system. The pathname of the script file appears in the first message. When the script operations have finished, you can copy the contents of the text area to the system clipboard with the dialog's Copy command.
The Preferences command brings up a tabbed dialog box in which the configuration properties of Qana can be edited. The properties on the various tabbed pages are described below.
Yes, pathnames are displayed in a reduced
"UNIX style" in some parts of the GUI. A pathname is converted from its
platform-specific form in two steps:
~.
\ on Windows systems) is replaced
by /.
No.
Yes, all the text in a text field will be
automatically selected when the field gains keyboard focus, regardless of how
the focus is transferred.
Yes.
Yes, the location of the main window on the screen
will be saved to the configuration file when you exit the application. The next
time that Qana is run, its main window will be positioned at the previously
saved location.
No.
Yes, the width and height of the main window will be
saved to the configuration file when you exit the application. The next time
that Qana is run, the dimensions of its main window will be set to the
previously saved values.
No, the width and height of the main window will be
determined by the larger of the archive view and the text view for each
dimension. The dimensions of the views are themselves determined by the
properties in the Archive view and Text view tabs of the Preferences dialog.
No.
Yes, the system clipboard is cleared when Qana exits.
Clearing the clipboard will prevent the escape of plaintext from the Qana
application through this route. (For example, plaintext may have been copied to
the clipboard when editing a text document.) The clipboard is cleared by
putting an empty string on it.
Yes.
Decrypt,
the file will be decrypted; if you select Validate, the file will
be validated.
Decrypt.
Linear.
awt.useSystemAAFontSettings.
Default.
This is the target pattern of the regular expression that is used by the text-wrapping algorithm to search for the ends of sentences within the text that is being wrapped. The consecutive space characters (U+0020) that follow the end of a sentence are replaced by the number of spaces specified by the text.wrap.numSpacesBetweenSentences property.
The default pattern is
(?:(?:\p{L}|\p{N}|['"»“)\]>%])[.!?])|(?:(?:\p{L}|\p{N})[.!?]['"»“)\]>%])
A simplified English translation of this pattern is:
'"»“)]>% ,
.!? , and
.qana.
.qarc.
true; the default
value for Drag-and-drop is false.
Yes, the pathnames of the current directories from
the principal file-selection dialogs are saved when Qana exits.
No.
~/.blankaspect/qana/qana.keys under Linux, where ~
denotes the user's home directory, or
%APPDATA%\blankaspect\qana\qana.keys under Windows, where
%APPDATA% is a system environment variable.
Yes, a warning will be displayed whenever a
temporary key is used for encryption.
Yes.
fortunaSeed.dat. If the directory field is left
empty, no seed file is read or written.
~/.blankaspect/qana under Linux, where ~ denotes
the user's home directory, or
%APPDATA%\blankaspect\qana under Windows, where
%APPDATA% is a system environment variable.
Yes, a warning is displayed if the pseudo-random
number generator (PRNG) is not seeded when Qana starts up. The PRNG may not
be seeded for one of several reasons:
Yes.
Some of the configuration properties will take effect when the Preferences dialog is accepted (by closing it with OK); other properties (eg, the look-and-feel and fonts) will not take effect until the next time that Qana is run.
The configuration file is normally saved automatically when Qana exits, if the configuration has changed. The Save configuration command in the Preferences dialog can be used to save a configuration file explicitly.
In information theory, entropy is a measure of unpredictability. The term is used here in the specific context of the unpredictability of the output of the Fortuna pseudo-random number generator, which is used by Qana for various purposes (eg, for generating keystreams for its cipher and cryptographic salts).
The sequence of numbers generated by a pseudo-random number generator (PRNG) is called pseudo-random rather than random because it is deterministic: the sequence is fully determined by its initial state, which, in the case of the Fortuna PRNG, is its seed. Given the same seed, the PRNG will always generate the same sequence of numbers. This reproducibility is a desirable property in some circumstances; for example, in Qana, where a content-encryption key (CEK) is used as the seed for the PRNG that generates the keystream of a cipher, it is essential that the same CEK always generate the same sequence of numbers for the keystream so that the CEK that was used to encrypt some plaintext will also decrypt the ciphertext.
However, there are other parts of the encryption system in which something close to true randomness is required. To achieve this, Fortuna has an entropy accumulator, which collects truly random data — entropy — from several sources, and reseeds the number generator with it when a sufficient quantity of random data has been collected. The entropy is collected in 32 pools. The random data that arrives from the various sources is distributed evenly among the pools, but the rate at which the entropy is extracted from the pools to reseed the generator decreases exponentially across the set of pools. This means that higher-numbered pools will accumulate more entropy than lower-numbered pools because entropy will be extracted from them less frequently to reseed the generator.
Qana has a single instance of a Fortuna PRNG with an entropy accumulator. The status of the entropy accumulator is shown in the first field of the status panel of the main window, where a green tick indicates that there is enough entropy to reseed the PRNG. For maximum security when encrypting data, it is recommended that you do so only when a tick is showing. (If you do not use a seed file, it is particularly important that you wait for the tick to appear before encrypting after Qana starts up.) Depending on the configuration of the entropy sources, this may mean waiting for enough entropy to be extracted from the system timer, or you may have to generate the entropy yourself by pressing keys or moving the mouse.
The entropy accumulator has three possible sources:
| Keyboard | The random data is the interval between successive key presses, measured by a high-resolution timer. Entropy is generated whenever a key is pressed. |
| Mouse | The random data is a combination of the x and y coordinates of the mouse cursor. Entropy is generated whenever the mouse is moved or dragged and a specified interval has elapsed since the position of the mouse cursor was last sampled. |
| Timer | The random data is the value of a high-resolution timer. Entropy is generated when the value of the timer is repeatedly sampled at a specified regular interval. It is assumed that there will be small, random irregularities in the actual sampling interval owing to variations in scheduling. |
The low-order bits of the sampled value are used in all three cases. The number of bits can be specified separately for each source with a set of configuration properties; if the number of bits is zero, the source is disabled.
For the two sources that are sampled at intervals (mouse and timer), the interval between samples can be specified separately for each source with a set of configuration properties.
Two of the entropy sources — keyboard and timer — depend on the high-resolution timer of the Java virtual machine (JVM), which has nanosecond precision but not necessarily nanosecond resolution. The time value that is used by the two entropy sources is the value of the high-resolution timer divided by the value of the entropy.timerDivisor configuration property. The divisor can be adjusted so that the resolution and precision of the time value are equal in order to maximise the entropy of its low-order bits. For example, if the JVM's high-resolution time source is based on a 10 MHz hardware timer (ie, a resolution of 100 nanoseconds), a divisor of 100 will reduce the precision of the time value to the resolution. If the frequency of the underlying hardware timer is not known, it may be possible to tune the divisor by observing the entropy metrics, which give an indication of the quality of the entropy of the timer bits.
Qana can display some measurements relating to the supposedly random data that is supplied to the entropy pools of the Fortuna PRNG, along with the status of the 32 entropy pools. The metrics are intended to give a visual indication of the quality of the entropy sources, and may be useful for assessing the effect of changes to the entropy-related configuration properties. The metrics are reset when any of the configuration properties are changed.
The entropy metrics are displayed with the Encryption > Show entropy metrics command, which brings up a dialog box that contains one or two titled panels: if any entropy sources are enabled, there is an Entropy sources panel and an Entropy pools panel; otherwise, there is only an Entropy pools panel.
The Entropy sources panel contains a tabbed panel that has a tab for each entropy source that is enabled. Within each tabbed page are two further panels:
As more entropy accumulates, the relative frequencies of all the plotted values should tend towards their expected values (the mid-lines of the plots) if the entropy is of a high quality. Patterns or anomalous regions (eg, prominent spikes) in any of the plots may indicate that the entropy from particular bits of the source are of a low quality, especially if they reappear in the same place after the entropy metrics are reset. If you consider the entropy from a particular source to be of insufficient quality, you could try different bits of the source, or you could disable the source altogether.
The Entropy pools panel contains a plot of the entropy content of the each of the entropy pools of the PRNG. The heights of the bars are plotted on a logarithmic scale. The bars are green when there is enough entropy to reseed the PRNG and red otherwise. The numerical value of the amount of entropy in each pool is displayed in a tooltip when the mouse cursor hovers over the plot.
The display of entropy metrics is not updated automatically; to update the display, you will need to issue the Update command (Ctrl+Space).
The Clear command (Ctrl+Delete) resets the measurements for all the entropy sources.
When Qana starts up, it seeds the PRNG with low-order bits from the high-resolution timer, which it samples several times over a short interval, using the entropy.timerDivisor configuration property to divide the values from the timer. It is quite possible that the resulting seed has low entropy — particularly if your system has no high-resolution time source. You can risk using the PRNG immediately or, if you're patient, you can wait until enough entropy has accumulated to reseed the PRNG, generating the entropy yourself if the timer source is not enabled. However, there is another option: a seed file may be used to provide some initial entropy for the PRNG, allowing you to perform encryption securely as soon as Qana has started up.
A seed file is a small file of random data that is stored at a location known to Qana. When the application starts up, it reads the file, extracts the random data from it and adds the data to the first pool of the entropy accumulator to allow the PRNG to be reseeded. If the generator was successfully reseeded, the seed file is replaced with new random data from the PRNG; otherwise, the seed file is deleted. When Qana exits, the seed file is replaced with fresh data from the PRNG, which will be used when the program is next run.
The seed file has a fixed name, fortunaSeed.dat, and its directory is
specified with the entropy.seedFileDirectory configuration
property. If the pathname of the directory is an empty string, the use of a seed file
is disabled.
If the PRNG is not reseeded when Qana starts up, a warning is displayed. (The generator might not have been reseeded because the use of a seed file is disabled or the seed file could not be found.) The warnings are controlled with the entropy.warnNotSeeded configuration property. You will probably want to suppress warnings if you have chosen not to use a seed file.
Where indicated elsewhere in this document, pathname parameters and properties in Qana can contain special constructs for system properties, environment variables and the user's home directory. The special constructs are expanded when the pathname is used.
user.home)
and environment variables (eg, PATH) are referenced by enclosing them
between ${ and }; that is, they must have the form
${<name>}. A Java system property takes precedence over an
environment variable with the same name.
${user.home}/projects
${HOME}/projects
sys. to it.
${sys.user.home}/projects
env. to it.
${env.HOME}/projects
~ in a pathname is expanded into the user's home directory
using the user.home system property, which is usually equivalent to the
environment variable $HOME on Linux/UNIX systems or
%USERPROFILE% on Windows systems.
~/projects
The table below lists the configuration properties of Qana. Apart from the app.configDir property, which, for obvious reasons, cannot be used within a configuration file, all properties can be used in the two configuration locations: command-line properties and configuration file.
When used in a -D command-line property, app. must be prefixed
to the property key (eg, app.general.mainWindowLocation).
Any commas (,) or backslash characters (\) in the name of a
font must be escaped by prefixing a \ character to them.
In the table below, the initial character of an italicised component of a property value denotes its data type according to the following convention:
| b | integer (binary representation) |
| i | integer (decimal representation) |
| p | platform-specific pathname, which may contain special constructs |
| s | string |
| Property key | Property value |
|---|---|
| configDir | pPathname |
| appearance.lookAndFeel | sName |
| appearance.statusTextColour | iRed, iGreen, iBlue |
| appearance.textAntialiasing | default | none | normal | subpixelHRgb | subpixelHBgr | subpixelVRgb | subpixelVBgr |
| archive.view.columnWidth.hashValue | iWidth |
| archive.view.columnWidth.path | iWidth |
| archive.view.columnWidth.size | iWidth |
| archive.view.columnWidth.timestamp | iWidth |
| archive.view.numRows | iNumRows |
| crypto.autoUseGlobalKey | false | true |
| crypto.kdfParameters.generation | iNumRounds, iCost, iNumBlocks, iNumParallelBlocks, iNumThreads |
| crypto.kdfParameters.verification | iNumRounds, iCost, iNumBlocks, iNumParallelBlocks, iNumThreads |
| crypto.keyDatabase | pPathname |
| crypto.prngDefaultCipher | aes256 | salsa20 |
| crypto.warnTemporaryKey | false | true |
| crypto.wrapCiphertextInXml | false | true |
| entropy.seedFileDirectory | pPathname |
| entropy.source.bitMask.keyboard | bBitMask |
| entropy.source.bitMask.mouse | bBitMask |
| entropy.source.bitMask.timer | bBitMask |
| entropy.source.interval.mouse | iMilliseconds |
| entropy.source.interval.timer | iMilliseconds |
| entropy.timerDivisor | iDivisor |
| entropy.warnNotSeeded | false | true |
| file.erasureNumPasses | iNumPasses |
| file.filenameSuffix.archive | sSuffix |
| file.filenameSuffix.encrypted | sSuffix |
| file.saveFileSelectionPathnames | false | true |
| file.selectEncryptDecryptOutputFile.dragAndDrop | false | true |
| file.selectEncryptDecryptOutputFile.menuCommand | false | true |
| font.comboBox | sName, plain | bold | italic | boldItalic, iSize |
| font.main | sName, plain | bold | italic | boldItalic, iSize |
| font.textField | sName, plain | bold | italic | boldItalic, iSize |
| font.textView | sName, plain | bold | italic | boldItalic, iSize |
| general.carrierImageKind | linear | cubic1 | cubic2 |
| general.clearClipboardOnExit | false | true |
| general.encryptedFileDragAndDropAction | decrypt | validate |
| general.mainWindowLocation | iX, iY |
| general.mainWindowSize | iWidth, iHeight |
| general.maxEditListLength | iLength |
| general.selectTextOnFocusGained | false | true |
| general.showFullPathnames | false | true |
| general.showUnixPathnames | false | true |
| split.filePartLengthLowerBound | iValue (B | KiB | MiB) |
| split.filePartLengthUpperBound | iValue (B | KiB | MiB) |
| text.view.colour.background | iRed, iGreen, iBlue |
| text.view.colour.selectionBackground | iRed, iGreen, iBlue |
| text.view.colour.selectionText | iRed, iGreen, iBlue |
| text.view.colour.text | iRed, iGreen, iBlue |
| text.view.size | iNumColumns, iNumRows |
| text.wrap.defaultLineLength | iLength |
| text.wrap.endOfSentencePattern | sPattern |
| text.wrap.numSpacesBetweenSentences | iNumSpaces |
For a cipher to be considered for the Qana implementation of the Fortuna PRNG, it had to be a 256-bit block cipher that could run in counter mode (or, like Salsa20, be functionally equivalent to such a cipher), with an open specification and unencumbered by patents or other restrictions on use. In addition to satisfying the basic requirements, the two chosen ciphers, AES-256 and Salsa20, are well-regarded, and all published attacks on them are currently infeasible. (To date, the best key-recovery attack on AES-256 is about four times faster than brute force, which effectively reduces its security to that of a 254-bit cipher.)
The ciphers were also chosen for their algorithmic diversity: the Rijndael (AES) and Salsa20 algorithms belong to different classes, and the author of Qana (who is not a cryptographer) expects that a successful attack on one class of algorithm would not extend to the other class.
AES is the cipher that is commonly used for the Fortuna PRNG; Salsa20, on the other hand, is not used in its intended way in Qana. According to its specification, Salsa20 should have a key that may be fixed over multiple uses of the cipher, and a nonce (initialisation vector) that is unique for each use of the cipher with a given key. In Qana, the Salsa20 cipher is used with a constant nonce, and a random key that — assuming a high-quality entropy source — is unique for each use of the cipher and is changed periodically during a single use of the cipher through feedback from the PRNG. Salsa20 was used as the base cipher for the PRNG in the belief that the uniqueness requirement is satisfied just as well by a unique key as by a unique nonce. However, the author of Qana is not competent to pronounce on the security of the use of the Salsa20 cipher for a Fortuna PRNG, nor does he know of any cryptanalysis of such a use of Salsa20.
