Using the SA4 Command Line Interface (PRELIMINARY DRAFT)

Size: px

Start display at page:

Download "Using the SA4 Command Line Interface (PRELIMINARY DRAFT)"

Martha Simon
6 years ago
Views:

1 Using the SA4 Command Line Interface (PRELIMINARY DRAFT) This chapter describes the SecretAgent 4 command line interface. The options and usage are identical for Windows/MS-DOS and UNIX versions of SecretAgent. You should read the README file, if one is provided, for last minute information on SecretAgent 4 that might not be covered in this document. WARNINGS: At this point SA4 is nearly five years old and the default 512-bit public key size it used for DSA and RSA key generation is no longer considered safe. We recommend that you always explicitly specify a key size of at least 1024 bits when generating new key pairs. As will become apparent, much of the current document has been copied from the SA3 README file and is significantly out of date. For current command line usage information, consult the accompanying sample shell scripts. Command Line Syntax The following output is produced by the command line sa4 h on a Solaris 2.x platform. It describes the application s basic command line syntax. SecretAgent(r) Version 4.16 for SunOS 5.x/SPARC Copyright(c) Information Security Corp. All rights reserved. Copyright(c) Digital Signature. All rights reserved. Basic functions: (order of options is irrelevant) help: sa4 -h -? keygen: sa4 -g [-Z#] [-T#] [-kpkf] [-Kprv] -uid -ppwd encrypt: sa4 [-e] [-T#] [-C#] [-E#] [-F#] [-kpkf] [-uid -ppwd] -rids file(s) decrypt: sa4 [-d] [-T#] [-kpkf] [-Kprv] -uid -ppwd file zap: sa4 -z file(s) (WARNING: this is non-interactive!) Common options: (replace # with integer; * indicates default value) -k<pkf> public key file -K<prv> private key file -o<path> output directory (decryption) or path\filename (encryption) -p<pwd> password phrase -q overwrite without warning -r<ids> recip. list (':' delimited) -u<id> user id -v verbose -f silent -R delete RAND file -V report version number -C# compression algorithm -F# format (printable encoding) 1 none 8 *LZSS 1 none (binary) 3 hex 3 RLE 2 *base64 (PEM/MIME/SDNS) -E# encryption algorithm -Z# key type 3 *DES-CBC 2 *DSA RSA DES3-CBC 8 EA2-CBC 3 DSA RSA T2 use encrypted private key file (default for RSA keys) -T4 use Fortezza (implies Skipjack encryption) NOTE: Some ciphers and key size options are not available on all platforms. Run the sa4 h command to see what is available in the particular build you have or contact ISC for specific details.

2 Chapter 5 SecretAgent User s Guide A more complete synopsis is provided below: /****************************************************************************\ Command line processing Principal Options -a ascii files (for cross-platform use; not yet implemented) -d decrypt -e encrypt -f quiet; no copyright message -g generate code -h help -i integrity check -k<pkfile> specify public key file [otherwise it's DEFAULT.PKF] -o<path> specify path/filename -p<pwd> specify password -q quiet (overwrite without prompt) -r<ids> specify recipient list (semi-colon delimited; encrypt only) -s sign-only --reserved -t test (does nothing at all at the moment!) -u<id> specify user ID (for key generation, signing and decrypting) -v verbose -w wipe (zap) --reserved -x extract a specified public key (requires -o option for output) -z zap -? help Certificate handling (rss): -A add cert -c certificate file -G generate certificate request -S generate certificate -H verify cert -K<prvfile> private key file -N X.500 common name -Q# cert request type (1=Certco,2=Verisign) -U X.500 uid + load config file Key Recovery (mjm): -Dx extract KRF (used by requestor) -Dp process KRF (used by key recovery agent) Encryption Options -C# compression algorithm 1 none 3 run-length encoding (RLE) 8 LZSS for general binary files [default] -E# encryption algorithm 1 none 3 *DES-CBC // single DES in software 6 DES3-CBC // triple DES (EDE-CBC) 7 Skipjack // requires Fortezza card 8 EA2-CBC // AT&T proprietary exportable algorithm 9 Assure DES-CBC // single DES on Cordant hardware 10 Assure DES3-CBC // triple DES on Cordant hardware 11 Armor DES-CBC // single DES on Fischer Armor hardware 12 Armor DES3-CBC // triple DES on Fischer Armor hardware -F# format (printable encoding) 1 none // ciphertext left in binary form 2 *base64 // PEM-MIME/SDNS/MSP encoding 3 hexadecimal (2 hex digits/byte) Key Generation/Encryption/Decryption Options -T# token 2 Issue 5 June 1998

3 SecretAgent User s Guide Chapter 5 1 *none (use SHA-1 hashed password phrase) 2 private key on disk 4 Fortezza Key Generation Options -Z# math (ring/field; for key generation only) 1 SA2-compatible 512-bit DSA p/q/g 2 *DSA 512-bit 3 DSA 1024-bit 4 RSA 512-bit (e = F3) 5 RSA 768-bit (e = F3) (unused?) 6 RSA 1024-bit (e = F3) 7 Fortezza Miscellaneous Options/Commands -I import public keys -L list keys -P pause before exit -R unlink existing RAND file before running (if combined with encryption; otherwise reseed rand file and exit) -V report internal version number -X export public keys (does not yet support Fortezza certificates) \****************************************************************************/ Issue 5 June

4 Chapter 5 SecretAgent User s Guide Command Line Processing When SecretAgent starts up, it first reads and processes the options provided in its configuration file, if one exists in the installation directory. It then processes the option string in the SA4 environment variable (if one is set in your environment) and finally the current command line string (including a response file, if one is specified). The SA4 configuration file containing a set of options and/or a recipient list is normally named sa.cfg but may be renamed and explicitly specified by using the '+' command line switch. The response file ('@') switch allows you to supply prewritten file lists as well. These options are described in the following two sections; they are especially useful when SecretAgent is to be invoked from a batch file or from within another executable program. Setting a SecretAgent Environment Variable In addition to editing your AUTOEXEC.BAT,.profile,.login,.cshrc or other user settings file to add the SecretAgent directory to your PATH, you may want to create an SA4 environment variable. The SA4 environment variable may be used to configure SecretAgent with commonly used options and/or to override the various default options. For example, the environment variable setting: SA4=-kalt.pkf -E6 causes SecretAgent to default to searching the file ALT.PKF for public keys ( -kalt.pkf ) and to use triple DES ( -E6 ) when encrypting. These environment variable settings remain in effect unless overridden by options placed on the current command line. Under Windows, rebooting your computer (or logging off and then back on) may be necessary for changes to your system environment to take effect. Configuration Files A single configuration file containing multiple option strings may be used during a SecretAgent session. Just precede the name of the file with a '+' and list it after all other options on the sa4 command line (but before any filenames). For example, suppose the file sa4.cfg contains the following lines of text: -C1 -E6 -F2 Then the (Windows shell) command line: C>sa -rbclinton +SA4.cfg c:\wp\*.doc will encrypt all.doc files in the directory C:\WP for user BClinton using no compression (-C1), triple DES (-E6) and base64 printable encoding (-F2). (Of course, the -F2 option is redundant since that is the default value.) White space is ignored in configuration files, so the file sa4.cfg in the above example could just as well have contained the single line: -C1 -E6 -F2 Similarly if you have a file of recipient IDs, say recips.lst, containing the lines: -r BClinton -r AGore -r G. Washington 4 Issue 5 June 1998

5 SecretAgent User s Guide Chapter 5 The (Windows shell) command: C>sa -C1 -E6 -F2 +recips.lst c:\wp\*.doc will encrypt all matching.doc files for the three users. (Note that the double quotes around the third -r argument is required as the user ID G. Washington contains an embedded space.) Of course, the encryption options and recipients can be stored together in a configuration file. For example, if we have a file, say usual.cfg, containing the lines: -C1 -E6 -F2 -r BClinton;AGore;G. Washington The command: C>sa +usual.cfg c:\wp\*.doc would have the same effect as the preceding command. The upshot of all this is that the configuration file is read and processed just as if the options it contained were all listed on the command line. Do not try to specify a configuration file by using the '+' switch in your SA4 environment variable; it will not work. Configuration files may only be used on the actual sa4 command line. Response Files Response files, or file specification lists, allow you to do the same thing with DOS filespecs that configuration files allow you to do with command line options. A single response file may be used by preceding its name with '@' character and listing it *last* on the SA command line in place of the normal list of input filenames. For example, if we have a file, say FILES.LST, containing the lines: C:\wp\*.doc C:\excel\*.xls The command: C>sa will encrypt for user BClinton all files matching the two filespecs using the default processing options. Configuration and response files may both be used on the same command line: C>sa NOTE: Command line options may not be included in response files. All SA options must either be placed in the SA4 environment variable, on the command line, or in a configuration file. At present, only a single configuration file and/or a single response file may be used for a given session.! WARNING: Do not try to specify a response file by using switch in your SA4 environment variable; it will not work. The response file, if any, must appear at the end of the actual command line. Issue 5 June

6 Chapter 5 SecretAgent User s Guide Testing the Encryption Modules The presence of the -t switch in the environment variable or on the command line triggers SecretAgent s built-in NBS Maintenance No.4 for the DES module and a similar test of the EA2 encryption module. The command line: Sa4 -t instructs SecretAgent to test its encryption modules, report the results, and exit to DOS. Testing Program Integrity (Windows only) Key Generation The presence of the -i switch in the SA environment variable or on the command line triggers SecretAgent's built-in integrity test. This test may be used to detect alterations to the executable program file SA.EXE due to tampering or virus infection. The integrity test works by calculating a message digest for the file SA.EXE using the Secure Hash Algorithm specified in FIPS This calculated hash is compared with an embedded message digest generated during software development. If the two message digests agree, the program probably has not been modified and SecretAgent issues the message: Program integrity OK If the messages differ, the following error message is displayed: Program is altered In this case, you should suspect a disk read error, tampering by another user, or a virus infection. To generate a new public/private key pair, you use the -g command line switch and provide the following information: 1. The type and size of key pair you wish to create (DSA or RSA) 2. Your user ID 3. Your password. This information is specified on the command line by using the -Z, -u and -p command line switches respectively. The possible type/size pairs and their corresponding -Z arguments are given in the following table: type Size -Z argument DSA [default] DSA RSA RSA For example, the command line: C>sa -g -Z2 -ubclinton -phillary would generate a new 512-bit DSA key pair (-Z2) for user BClinton with a password of Hillary. The public key would be placed in the default public key file DEFAULT.PKF. 6 Issue 5 June 1998

7 SecretAgent User s Guide Chapter 5 Encryption Signing NOTE: That user IDs or password phrases containing one or more spaces must be surrounded by double quotes and should be separated from the preceding switch by at least one space. Thus the command line: C>sa -g -u BClinton -p Hillary has the same effect as the preceding one (since -Z2 is the default). Use the -k option to designate an alternate public key file. The command line: C>sa -g -Z6 -knew.pkf -ubclinton -phillary would generate a new 1024-bit RSA key (-Z6) and place the public key in the file NEW.PKF. NOTE: Password phrases (and usually token PINs) are case sensitive. If you do not supply a password, SecretAgent will prompt you for the password of your choice. To encrypt one or more files, you must specify the recipients (as a semicolon delimited list of user IDs) and supply the filespecs. For example: C>sa -rbclinton;agore *.doc would encrypt all.doc files in the current directory in such a way that only users BClinton and AGore could decrypt them. NOTE: The public keys for all recipients must be present in the active public key file--in this example the default DEFAULT.PKF. You may use the -k option to designate an alternate public key file. If you type the command line: C>sa -kwhthouse.pkf -rbclinton;agore *.doc SecretAgent will search the public key file WHTHOUSE.PKF for the specified recipients public keys. To override the default encryption processing options, see the section entitled Command Line Syntax on page 5-6. If you wish to include your digital signature on each of the input files in the ciphertext archive, you must specify your user id and password phrase (or PIN) using the -u and -p options respectively when encrypting. For example, BClinton could use the following command to send an encrypted and signed memo to AGore : C>sa -kwhthouse.pkf -ragore -ubclinton -phillary memo.doc You will be prompted for your password if you do not supply it. Issue 5 June

8 Chapter 5 SecretAgent User s Guide Decryption To decrypt a SecretAgent.SA ciphertext archive, you must supply your user ID and your password phrase or PIN. Be sure to enter your password phrase in exactly the same manner as you did when you generated your public key. For example, Al might decrypt a MEMO.SA file he receives using the command line: C>sa -uagore -p I m the VP memo.sa This assumes the public key of AGore (and, if the archive contains digital signatures, that of the sender) are in the file DEFAULT.PKF. An alternate public key file may be specified using the -k option as illustrated above. 8 Issue 5 June 1998

User s Guide. PolicyAgent and Key Recovery for SecretAgent 5.8 and SpyProof! 1.2

User s Guide. PolicyAgent and Key Recovery for SecretAgent 5.8 and SpyProof! 1.2 User s Guide PolicyAgent and Key Recovery for SecretAgent 5.8 and SpyProof! 1.2 Information in this document is subject to change without notice and does not represent a commitment on the part of Information