The AxCrypt Command Line

This section is for system administrators, programmers and other advanced users.

AxCrypt may be called by other programs, or manually, by specifying command-line arguments. The general syntax is:

AxCrypt [-i [.ext] | p | u | x ] | [-l] | [-V n] [-v n] [-b tag] [-f] [-c] [-g] [-n filename] [-m] [-e] [-a | -k "passphrase"] [-K folder | filename] [-O path2exe] [-z | d | o | w | s | q | h | J file(s)] [-t [tag]] | file(s)

Except for -i -p -u -x, the options are interpreted sequentially and may occur multiple times if it makes sense.

The options and their meanings

-i [.ext] Install Set all registry values to default. Set the extension to associate with AxCrypt - default is .axx.
-p Psp test Test for the need to install psapi.dll. Only relevant on NT. If return code is 0, no need. This is an installation helper function only.
-u Uninstall Clear all registry values.
-x eXit End the resident server process, if loaded.
-l License Start the license manager dialog.
-b tag Batch id Define a tag, or batch id, to be used with subsequent pass phrases. These pass phrases will only be used when the same tag is specified in future calls to AxCrypt. The batch id is a decimal non-zero positive 32-bit signed integer. Odd values are reserved for internal use. If no -b option is given, saved pass phrases are 'global'. All tagged pass phrases are saved until cleared with -t.
-f Toggle Fast mode Will modify certain operations to execute fast, rather than safe and/or secure. There is no guaranteed effect. Initially off.
-c Toggle Copy-only flag Causes subsequent -d and -z to retain the originals. May be combined with -f for fast copy without wiping of temporaries. Initially off.
-g Toggle ignore encrypted flag If set, attempted encryption of already encrypted files will do nothing. Initially off.
-n Output Name Defines a file name to be used as output instead of default for the next -z or -d.
-m Toggle recurse flag If set, causes subsequent wild card file names to search into sub-directories. Initially off.
-e Encryption pass phrase definition Subsequent -a or -k options on this invocation define the default encryption key instead of one of possibly many decryption keys. The -b option may be used to define pass phrases with limited context.
-a Add pass phrase Prompt for a pass phrase using the AxCrypt standard safe dialogues. -b and -e may be used as modifiers.
-k "pass phrase" Cache pass phrase Cache the given pass phrase, quotes are recommended. The pass phrase is case-sensitive. -b and -e may be used as modifiers. Note that there are restrictions for what passphrases may be used in the AxCrypt dialogs - these are not enforced here! See below for allowed characters in passphrases.
-O "Path2Exe" Set Open Executable Modify a subsequent -o (Open for edit) to use the specified executable instead of the automatic association by extension.
-z encrypt Encrypt (and if useful compress) the given file(s) with either the current default encryption key, or with one that is prompted for. The originals are wiped. -b, -c, -g, -f and -n may be used as modifiers.
-J self-decrypt encrypt Encrypt (and if useful compress) and copy the given file(s) with either the current default encryption key, or with one that is prompted for to a self-decrypting executable archive. -b, -g and -n may be used as modifier. Default is to ignore files that already are self-decrypting.
-K make Key-file Generate and store a Key-file in the given folder, or directly to the given full path-name.
-d Decrypt Decompress and decrypt the given file(s) with either a cached key, or with one that is prompted for. -b, -c, -f and -n may be used as modifiers.
-o Open Open the given file(s) with the appropriate application after temporary decryption and decompression. If they are modified after application exit, they are re-encrypted with the same pass phrase. -b may be used as modifier.
-v n override wipe passes Sets an override of the number of passes for wipe for the remainder of the command line. See -V for more info.
-V n wipe passes Sets the global persistent default number of wipe passes when overwriting, 1-7. Default if not set is 1. The full set of 7 passes will overwrite in the following sequence: random, ones, zeroes, random, zeroes, ones, random. If less are specified only the last n passes are performed. Thus, -V 3 corresponds to the DoD 5220.22-M standard for sanitizing data on fixed hard disks.
-w Wipe Wipe the given files and delete. Show a confirmation warning first.
-s wipe Silent Wipe the given files and delete, but do not ask for confirmation.
-q Query pass phrase cache Return exit code 0 if all files given have pass phrases in the cache already. -b may be used as modifier.
-h Anonymous rename Renames the given file(s) to anonymous names. The original names will be restored on decryption.
-t Clear pass phrase cache Clear the internal pass phrase cache. If -b is given, only pass phrases associated with that tag are affected, otherwise all are removed, tagged and un-tagged alike.

If no options are given but just file(s), they are opened as with -o. Otherwise the most recent -z, -d, -c, -o, -w, -s or -h determines the operation performed on the file.

The first time AxCrypt is started, a server process is initiated which will run until terminated. It's within this process that the pass phrase cache is kept, in a secure manner.

All operations are 'waitable', and will return a non-zero exit code on error.

The 'flag' options are important to specify before the operations they intend to modify, parameters are parsed and executed sequentially as the appear on the command line. Only operating system restrictions on command line lengths limit the number of operations on a single line. If any operation returns an error, the rest of the command line is ignored, and that error is returned as exit code.

Standard wild cards are accepted for all file specifications, except for Open. If the recursion flag is enabled, sub-directories will be searched too.

If you need to do several operations, and keep them together, without affecting the "global" pass phrase cache, use the -b option with an arbitrary tag as described above. Deriving one from the time of day may be appropriate for example. The -b option is valid over multiple calls to the server process, as long as it's not restarted.

Allowed passphrase characters

To minimize the risk of a user entering a passphrase on one system, where it gets difficult to generate the same characters on another system with a different keyboard, certain characters from the ANSI set have been excluded. Also note that currently the passphrase dialog as such does not allow Unicode characters. The following are the legal characters:

<space>
!"#$%&'()*+,-./0123456789:;<=>?@
ABCDEFGHIJKLMNOPQRSTUVWXYZ [\] _abcdefghijklmnopqrstuvwxyz {|}
€ŠŒŽšœžŸ¡ ¢£¤¥§±¼½¾¿ ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏ ÐÑÒÓÔÕÖØÙÚÛÜÝ Þßàáâãäåæçèéêëìíîïð ñòóôõöøùúûüýþÿ

The full key is derived from the passphrase concatenated with the key-file (if any). From this it follows, that you can always create a key-file that contains all the necessary characters that make up a passphrase. In the key-file, there are no restrictions on the contents - it is interpreted as a binary sequence of bytes. If you use this for passphrase data, you must be aware of character encoding issues - a key-file stored in Unicode UTF-16 encoding will probably not work as expected...

Examples

As the command line is made for programmatic access, the usage is not really intuitive so here follows some examples which can be executed as a sequence, which assume that AxCrypt is installed in a typical standard location and that the current directory contains a file named secrets.txt (test this with non-vital data please):

@ECHO ON REM Encrypt secrets.txt with the given passphrase, but do not remember this passphrase
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" -b 2 -e -k "A Secret Phrase" -z secrets.txt

REM Decrypt secrets.txt, but prompt for the passphrase
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" -b 2 -d secrets-txt.axx

REM Clear the passphrase cache of the default phrase (and all other cached phrases) for batch id '2'
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" -b 2 -t

REM Load the passphrase cache with a default encryption phrase using the standard dialog
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" -e -a

REM Encrypt secrets.txt with the default encryption phrase just entered
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" -z secrets.txt

REM Decrypt secrets-txt.axx
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" -d secrets-txt.axx

REM Clear the passphrase cache of the default phrase (and all other cached phrases)
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" -t

REM Encrypt to a self-decrypting copy of the original and clear the cache
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" -b 2 -e -k "A Secret Phrase" -J secrets.txt

REM Encrypt and copy to a regular encrypted file, but keep the passphrase in the global cache
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" -e -k "Another Secret" -c -z secrets.txt

REM Shred the original with an interactive warning
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" -w secrets.txt

REM Shred the self-decryping file with no interactive warning
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" -s secrets-txt.exe

REM Open the file file with notepad or whatever is used for .txt-files
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" secrets-txt.axx

REM Decrypt back to secrets.txt, using the cached phrase
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" -d secrets-txt.axx

REM Clear the passphrase cache again
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" -t

REM Encrypt all files in the current and sub-directories, and do it fast but just deleting originals etc (i.e. faster)
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" -b 2 -e -k "A Third phrase" -m -f -z *.txt

REM Rename all just encrypted files to anonymous names
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" -m -h *.axx

REM Decrypt them all again, and clear the cache (batch id 2)
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" -b 2 -m -f -d *.axx -t

REM Request that the resident process ends itself, and exits
"%ProgramFiles%\Axon Data\AxCrypt\1.6.1\AxCrypt" -x

Please note that for the passphrase cache to work as implied above, you need to check the appropriate options for keeping the passphrase in the cache when the interactive dialog is displayed. Also please note that you may need to use Alt-Tab to find the passphrase dialog when this is run from a command line window due to Windows design constraints.