/****************************************************************************\ SecretAgent 5 Command Line Interface Package, Release 5.7.1 Copyright(c) 1991-2002 Information Security Corp. All rights reserved. SecretAgent is a trademark of Information Security Corp. Protected by U.S. Patents No. 5,274,707 and 5,373,560 This document was last modified on: 27 AUG 2003 \****************************************************************************/ SA5CLI.EXE, CDKMT.DLL, ALL KYP FILES, SELF32.EXE, AND THIS DOCUMENTATION ARE PROPRIETARY. THEY ARE FURNISHED UNDER A LICENSE OR NON-DISCLOSURE AGREEMENT. PLEASE TREAT THEM AS CONFIDENTIAL. NO FILES INCLUDED WITH THIS PACKAGE MAY BE REDISTRIBUTED BY YOU. IF YOU NEED TO REDISTRIBUTE THESE FILES WITH YOUR APPLICATION PLEASE CONTACT AN INFORMATION SECURITY CORPORATION ("ISC") SALES REPRESENTIVE TO OBTAIN A REDISTRIBUTION LICENSE. Introductory Notes on the SA5CLI Package --------------------------------------- This README file contains information on the SecretAgent 5 Command Line Interface. If you wish to use this package on UNIX you will need to obtain the appropriate files for your UNIX platform from Information Security Corporation. Please contact your sales representative for these files. SA5CLI.EXE is a stand-alone 32-bit Windows executable supporting the UNIX-like command line syntax described below. WARNING: This package should not be expanded into the same directory as the SecretAgent 5 GUI because some files contained in this package may conflict with files in the GUI version. Information in this document is subject to change without notice and does not represent a commitment on the part of Information Security Corp. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of the agreement. The purchaser may make one copy of the software for backup purposes. No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose other than the purchaser's personal use without the prior written permission of Information Security Corp. SecretAgent is commercial computer software and, together with any related documentation, is subject to the restrictions on U.S. Government use as set forth below. RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software Clause at DFARS 52.227-7013. "Contractor/manufacturer" is Information Security Corporation, 1141 Lake Cook Road, Suite D, Deerfield, IL 60015, U.S.A. LIMITATION OF REMEDIES: ISC's entire liability and your sole and exclusive remedy under this license and related to your use of the Software shall be: 1. The replacement of any CD-ROM not meeting ISC's limited warranty and which is returned to ISC or an authorized ISC dealer with a copy of your receipt; or 2. If ISC or the authorized dealer is unable to deliver a replacement CD-ROM which is free from defects in material or workmanship for the stated purpose, you may terminate this license agreement by returning the Software within ninety (90) days, and your money will be refunded. IN NO EVENT WILL ISC BE LIABLE FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS, LOST SAVINGS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE SUCH SOFTWARE EVEN IF ISC OR AN AUTHORIZED ISC DEALER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY. Table of Contents ----------------- 1. Files in the SA5CLI Distribution 2. Command Line Syntax 3. Using the Command Line Interface 4. Configuration Files 5. Supported Key Types 6. Security Officer (sa5so.cfg) 7. Key Recovery 8. Environment and Special Files 9. Known Bugs and Limitations. 10. Contact Information 1. Files in the SA5CLI Distribution ----------------------------------- CDKMT.DLL ISC's Cryptographic Development Kit README.TXT this document SA5CLI.EXE a complete, stand-alone, build of the 32-bit SecretAgent 5 application for Windows SA5SO.CFG a sample Security Officer settings file SELF32.EXE the self-extracting stub that is prepended to self-extracting archives TEST5.BAT a test command script to illustrate the use of SA5CLI.EXE; runs the same tests as TEST5CLI.EXE. *.KYP a collection of parameter definition files used to generate asymmetric key pairs and self-signed certificates NOTE: You must have CDKMT.DLL in the same directory as SA5CLI.EXE or in the Windows search path for it to work correctly. If you are generating keys, the appropriate .KYP file(s) must also be available to SA5CLI.EXE. 2. Command Line Syntax ---------------------- The command line as understood by SA5CLI.EXE is essentially the same as the SecretAgent DOS/UNIX command line. (The only differences are in certain file naming conventions, the interpretation of the '-w' option, and in the operation of a few other functions, such as '-z', which are clearly platform-dependent.) Of course, where a command of the form 'sa5 ' is used in UNIX, you would simply execute the command 'sa5cli .' For example, the UNIX command: sa5 -eann,bob,r1+r2 -oarchive.sa5 plain1.txt plain2.txt One could achieve the same effect by invoking SA5CLI.EXE (in a command window or by spawning it from Windows application) as follows: sa5cli -eann,bob,r1+r2 -oarchive.sa5 plain1.txt plain2.txt All SA5 certificate, CRL, and private key files should be interoperable between the DOS, Windows and UNIX platforms. Most options take a (required) string argument which should be double quoted if it contains embedded white space. Lists are delimited by commas ',' and numeric arguments are denoted by a pound sign '#'; only those digits listed below for each such option will be accepted. NOTE: Options are processed in the order in which they are specified, with configuration files being processed as soon as the '-@' option is encountered. Some options (such as -w) take effect immediately and may be listed more than once on the command line. For example, if the first line of your configuration file contains the option '-w2' and you run the command: sa5 -@sa5.cfg -w0 -gann -tdsa-1024 verbosity level 2 will be used while processing the remainder of the .cfg file, but then set back to level 0 for the rest of the command line. 3. Using the Command Line Interface ----------------------------------- Displaying the online help The online help can be displayed using the following command: sa5cli -h Generating a key pair, with self-signed certificate or certificate request. Generate an asymmetric key pair with a command of the form: sa5cli [-w#] [-q] [-r] -g -t -o \ [-D#] [-F#] [-p] OPTIONS: REQUIRED: -g Generate a key pair (and self-signed certificate), PKCS#10 (RFC 2314) certificate request file, or import a PKCS#12 file. A self-signed certificate is generated when the -o filename ends with ".cer". A PKCS#10 certificate request file is generated when the -o filename ends with ".crq". A PKCS#12 file is imported when no -o is provided and there is a filename ending with ".p12" on the command line. -t Type of key to generate. is the name of a .kyp file without the .kyp suffix. See SUPPORTED KEY TYPES below for details. -o Output file. Used to specify the name of the self-signed certificate or PKCS#10 certificate request file to be created during key generation. If has a '.cer' extension, a (self-signed) certificate file by that name will be created. If has a '.crq' extension, a PKCS#10 certificate request file is created instead. In either case, a private key file with the same filename as the '-o' argument, but with a '.prv' extension, is generated. OPTIONAL: -w# Verbosity level *0 no output 1 terse progress and diagnostic messages 2 more detailed progress and diagnostic messages -q Overwrite existing output files without warning. -r Reseed the pseudorandom number supply. -D# Message digest used in self-signed certificate and PKCS#10 (RFC 2314) certificate request files 1 MD2 (RFC 1319) 3 MD5 (RFC 1321) 4 *SHA-1 (FIPS 180-1, ANSI X9.30(2)) Other Message Digests are not supported for key generation -F# Output format 0 *none (binary) 1 ASCII (base64-encoded) -p Password (for key generation, signing and decrypting.) Only required for password-protected private key files. Examples: sa5cli -w1 -g"Bill Clinton" -ptesttest -tdsa-1024 -oBill.crq will create a PKCS#10 certificate request file 'Bill.crq' and a private key file 'Bill.prv'. The command sa5cli -w1 -g"Bill Clinton" -ptesttest -tdsa-1024 -oBill.cer will create a self-signed certificate file 'Bill.cer' and a private key file 'Bill.prv'. NOTE: To specify the X.509 DN components for the certificate, see CONFIGURATION FILES below. Encrypting Encrypt one or more files with a command of the form: sa5cli [-w#] [-q] [-r] -e [-C#] [-E#] [-F#] \ [-o] [-s [-p]] OPTIONS: REQUIRED: -e Encrypt for the specified recipients. is a comma-separated list of one or more certificate file names without their .cer suffixes. If the -e is followed by '.' (-e.) then a sign only operation is assumed. If the -o option is provided to the -e command (with recipients) with a filename of ".exe" a self-extracting archive will be created. If the -o option is provided to the -e command (with recipients) with a filename of ".sa5" a multiple file archive will be created. If no -o option is provided to the -e command (with recipients) then each file listed on the command line will be put in its own archive with the filename of file.sa5 (a.b becomes a.b.sa5). are the names of one or more files that are to be encrypted. OPTIONAL: -w# Verbosity level *0 no output 1 terse progress and diagnostic messages 2 more detailed progress and diagnostic messages -q Overwrite existing output files without warning. -r Reseed the pseudorandom number supply. -C# Compression algorithm (applied to plaintext prior to encryption) 0 *none 1 LZSS -E# Symmetric encryption cipher 2 DES-CBC (FIPS 46-2, FIPS 81, ANSI X3.92, X3.106) 4 TDES-CBC (FIPS 46-3, ANSI X9.52) 6 EA2-CBC (AT&T proprietary exportable cipher) 8 DESX-CBC (DES-XEX3-CBC in draft-simpson-desx-02.txt) 12 *AES-128-CBC (FIPS 197, 128-bit AES) 14 AES-192-CBC (FIPS 197, 192-bit AES) 16 AES-256-CBC (FIPS 197, 256-bit AES) -F# Output format 0 *none (binary) 1 ASCII (base64-encoded) -o Output file. Used to specify the output format for ciphertext archives during encryption. must have one of the following suffices (if no output filename is provided or a path ending in '\' (WINDOWS) is provided each file that is to be encrypted is encrypted into a separate file of same name with the extension .sa5. In the case where an output path is provided to the -o option each archive will be placed in the output path, otherwise each archive will be placed next to the plaintext file): .sa5 encrypt with specified cipher ('-E12' by default) into a multiple file archive. .saa encrypt with DESX-CBC (i.e., '-E8'; any other cipher is illegal in this case and is ignored) .exe RC4-encrypt to an MS Windows executable -s Sign with private key where is the name of your .prv private key file *without* the .prv suffix. -p Password (for key generation, signing and decrypting.) Only required for password-protected private key files. NOTE: The complete recipient list can be distributed among the arguments of more than one '-e' option, allowing one set of standard recipients to be specified in a configuration file and another to be specified on-the-fly on the sa5 command line. EXAMPLES: 1. Encrypt the files 'plain1.txt' and 'plain2.txt' for the recipient bob (whose public key is in a file named 'bob.cer'), and put the output in 'archive.sa5': sa5cli -ebob -oarchive.sa5 plain1.txt plain2.txt Note that it is important to explicitly specify the '.sa5' filename suffix here so that sa5 knows exactly which output archive format to generate. (Add '-F1' to produce an ASCII (base64-encoded) ciphertext archive.) 2. Same, but with recipients ann and bob and with a self-decrypting Windows executable '.exe' output file: sa5cli -eann,bob -oarchive.exe plain1.txt plain2.txt NOTE: The output ciphertext file format is inferred from the specified extension on the output filename. 3. Same as above, but with a separate encrypted file for each input file: sa5cli -eann,bob plain1.txt plain2.txt NOTE: To implement a shared secret, key recovery scheme, several (non-RSA) certificate files of exactly the SAME KEY SIZE AND TYPE can be combined with a plus sign '+' and treated as a single virtual recipient. For further information, see the KEY RECOVERY section below. WARNING: Unlike SecretAgent 5 for Windows, this command does not validate each recipient's certificate prior to its use in wrapping the random symmetric session key applied to the plaintext. To perform certificate validation see below. Decrypting Decrypt a file with a command of the form: sa5cli [-w#] [-q] [-r] -d [-p] \ [-s] [-o] OPTIONS: REQUIRED: -d Decrypt using specified private key name (without its .prv suffix) possibly with signature validation. Use a period '.' for when decrypting a self-extracting archive or validating a signed-only message. is the name of the file that is to be decrypted. OPTIONAL: -w# Verbosity level *0 no output 1 terse progress and diagnostic messages 2 more detailed progress and diagnostic messages -q Overwrite existing output files without warning. -r Reseed the pseudorandom number supply. -p Password (for key generation, signing and decrypting.) Only required for password-protected private key files. -s Issuer certificate file which can be used with '-d' option to validate a purported signer's certificate during the signature validation process. If the issuer_cert file is not found it is considered to be the output filename of the signing certificate. You can then validate or store the signer's certificate later. -o Output path. Used to specify the output path for plaintext files during decryption. EXAMPLES: 1. Decrypt 'archive.sa5' with the private key 'ann.prv' which is protected by the password 'annp': sa5cli -dann -pannp archive.sa5 2. Same as above, but putting the plaintext output in the directory '~/plaintext': sa5cli -dann -pannp -o~/plaintext archive.sa5 Signing without encrypting To sign *without* encrypting, specify an empty recipient list with a period ('-e.') as in the command of the form: sa5cli [-w#] [-q] [-r] -e. [-o] \ -s [-p] [-F#] OPTIONS: REQUIRED: -e. If the -e is followed by '.' (-e.) then a sign only operation is assumed. -s Sign with private key where is the name of your .prv private key file *without* the .prv suffix. is the names of one or more files that are to be encrypted. OPTIONAL: -w# Verbosity level *0 no output 1 terse progress and diagnostic messages 2 more detailed progress and diagnostic messages -q Overwrite existing output files without warning. -r Reseed the pseudorandom number supply. -o Causes all signatures to be stored in the file. Excluding the -o creates a separate signature file for each file. -p Password (for key generation, signing and decrypting.) Only required for password-protected private key files. -F# Output format 0 *none (binary) 1 ASCII (base64-encoded) Verifying a signature Verify the signature on one or more signed (but not encrypted) archives with a command of the form: sa5cli -d. -s OPTIONS: REQUIRED: -s either the issuer certificate of the signer or the name of the file to which the signer's certificate should be stored. are the names of the files that are to be verified. OPTIONAL: -w# Verbosity level *0 no output 1 terse progress and diagnostic messages 2 more detailed progress and diagnostic messages NOTE: If you do not known whether a signed file is encrypted or not, try "decrypting with a null recipient" by specifying '-d.' on sa5 the command line. If the file *is* encrypted, you will get an error message and will not be able to validate the signature without also decrypting the archive. Inspecting an encrypted archive Inspect an encrypted archive with a command of the form: sa5cli OPTIONS: REQUIRED: sa5 will report on the format and cipher/mode used to create the .sa5 archive as well as return the originator and all recipient DNs. (Only a single filename can be supplied.) OPTIONAL: -w# Verbosity level *0 no output 1 terse progress and diagnostic messages 2 more detailed progress and diagnostic messages Erasing a sensitive file Zap (or securely erase) one or more files with a command of the form: sa5cli -z OPTIONS: REQUIRED: -z Zap specified file(s) (secure erasure compliant with the obsolete DoD Magnetic Remanance Guidelines) are the names of the files that are to be zapped. OPTIONAL: -w# Verbosity level *0 no output 1 terse progress and diagnostic messages 2 more detailed progress and diagnostic messages The specified files will be overwritten according to the (obsolete!) DoD Magnetic Remanance Guidelines and then unlinked. WARNING: This operation is non-interactive; the specified files will be immediately and irretrievably wiped from your hard disk. Inspecting and/or validating a certificate Display the subject and issuer distinguished names (DNs) and validity period of a certificate with a command of the form: sa5cli [-s -I [-R]] OPTIONS: REQUIRED: where is a .cer file (*with* its .cer suffix). Simply providing will cause the certificate to be inspected. OPTIONAL: -w# Verbosity level *0 no output 1 terse progress and diagnostic messages 2 more detailed progress and diagnostic messages -s Include the optional "-s" to validate the subject certificate against the issuer's certificate; denotes the CA's certificate file *without* its .cer suffix. Such commands can be strung together to validate an entire certificate chain; just invoke a new sa5 instance for each link in the chain. -I Include the optional "-I" to validate the entire certificate path using certificates stored in CApath. This option requires that the steps described below to generate an index file have occurred. -R Include the optional "-R" to validate the entire certificate path using CRLs stored in CRLpath. This option requires that the steps described below to generate an index file have occurred and that -I has been provided. Alternately, an entire certificate chain can be validated at once (with or without CRL checking) using a command of the form: sa5cli -I [-R] where is the file containing the certificate to be validated and is a directory containing all issuer certificates in the chain above the subject (along with a CA index file). If the '-R' option is included, valid CRLs for each issuer in the chain must be found in the specified directory (along with a CRL index file). To build a CA index file, use a command of the form: sa5cli -I For example, the command sa5cli -w1 -I/usr/local/sa5/CACerts will create a file called 'index' in '/usr/local/sa5/CACerts'. To build a CRL index file, use a command of the form: sa5cli -R For example, the command sa5cli -w1 -R/usr/local/sa5/CRLs will create a file called 'index' in '/usr/local/sa5/CRLs'. In each case, all the certificate files (resp. CRL files) in the specified directory are parsed and used to generate an index file of the appropriate type. IMPORTANT NOTE: As the index files are called 'index' in both cases, and these files are required for validation, separate directories are required for CA certificates and CRLs, if you are using the latter type of files! Importing a PKCS#12 file Import a PKCS#12 file with a command of the form: sa5cli -g -p Ann.p12 where is the path and base name of the separate files in the PKCS#12 file. For example, the command sa5cli -g"D:\Certs\Mine\Ann" -ptesttest Ann.p12 will create (assuming Ann.p12 contains an end user certificate, a private key, an intermediate issuer certificate and a CA root certificate): "D:\Certs\Mine\Ann.cer" - Ann's Certificate "D:\Certs\Mine\Ann.prv" - Ann's Private Key "D:\Certs\Mine\Ann1.cer" - Intermediate Issuer Certificate "D:\Certs\Mine\Ann2.cer" - CA Root Certificate Exporting a PKCS#12 file Export a PKCS#12 file with a command of the form: sa5cli -x -s -p where is the name of the PKCS#12 file to create (it must end with '.p12'), is the path and base name of the seperate filesto place in the PKCS#12 file, is the private key password and the password used to protect the PKCS#12 file, and is a list of one or more additional certificates you want to place in the PKCS#12 file (say the certificate's chain). For example, the command sa5cli -xAnn.p12 -s"D:\Certs\Mine\Ann" -ptesttest will create a PKCS#12 file containing Ann.cer and Ann.prv. Exporting a PKCS#7 file Export a PKCS#7 file with a command of the form: sa5cli -x where is the name of the PKCS#7 file to create (it must end with '.p7b') and is a list of one or more certificates to store in the PKCS#7 file. For example, the command sa5cli -xAnn.p7b cert1.cer cert2.cer cert3.cer will create a PKCS#7 file containing cert1.cer, cert2.cer, and cert3.cer. Hashing a file Hash a file with a command of the form: sa5cli -H[D] OPTIONS: REQUIRED: where is the file to hash OPTIONAL: -w# Verbosity level *0 no output 1 terse progress and diagnostic messages 2 more detailed progress and diagnostic messages -D# or -HD hash function to use to hash the file 1 MD2 3 MD5 4 *SHA-1 5 SHA-256 6 SHA-384 7 SHA-512 4. CONFIGURATION FILES ----------------------------------- Command line options and/or distinguished name fields and a validity period for certificates may be placed one-per-line in a separate file and specified on the command line with the '-@' option. See the file 'tsa5.cfg' supplied as an example. The following (modified) X.509 tags are only recognized in such a configuration file: CN= common name (if not specified, the '-g' argument is used) T= title O= organization OU= organizational unit OU2= organizational unit 2 L= locality SP= state or province C= county EM= email address Certificate validity dates may also be specified using lines of the following form for the NotBefore and NotAfter data: NB=NotBefore NA=NotAfter where NotBefore and NotAfter are strings of exactly 12 digits in the following format: yyyymmddHHMM WARNING: You must specify the date/time with precisely 12 digits: 2 each for the month, day, hour, and minute, and 4 for the year. (Seconds are set to 0 and cannot currently be changed.) No sanity check is currently performed on the input values. If no validity period is specified, the following default values are used: NB=200005010000 // May 1, 2000 00:00:00 GMT NA=200205010000 // May 1, 2002 00:00:00 GMT Any line in the configuration file starting with a pound sign '#' is ignored as a comment. WARNING: If it exists in the current directory, the special configuration file 'sa5.cfg' is read automatically upon start up by sa5. Do not specify this configuration file using a '-@' option since that will cause it to be processed twice. 5. SUPPORTED KEY TYPES ----------------------------------- The following KYP (key type parameter) files are currently provided with SA5 and may be used as arguments (without the .kyp suffix) with its '-t' suboption for the '-g' key generation operation. dsa-512.kyp 512-bit DSA (FIPS 186, ANSI X9.30(1)) dsa-768.kyp 768-bit DSA (FIPS 186, ANSI X9.30(1)) dsa-1024.kyp 1024-bit DSA (FIPS 186, ANSI X9.30(1)) dsa-2048.kyp 2048-bit DSA (FIPS 186-1, ANSI X9.30(1)) rsa-512.kyp 512-bit RSA (PKCS#1, ANSI X9.31) rsa-768.kyp 768-bit RSA (PKCS#1, ANSI X9.31) rsa-1024.kyp 1024-bit RSA (PKCS#1, ANSI X9.31) rsa-2048.kyp 2048-bit RSA (PKCS#1, ANSI X9.31) us-b-163.kyp NIST EC parameters over GF(2^163) us-b-233.kyp NIST EC parameters over GF(2^233) us-b-283.kyp NIST EC parameters over GF(2^283) us-b-409.kyp NIST EC parameters over GF(2^409) us-b-571.kyp NIST EC parameters over GF(2^571) us-p-192.kyp 192-bit NIST EC parameters over GF(p) us-p-224.kyp 224-bit NIST EC parameters over GF(p) us-p-256.kyp 256-bit NIST EC parameters over GF(p) us-p-384.kyp 384-bit NIST EC parameters over GF(p) us-p-521.kyp 521-bit NIST EC parameters over GF(p) 6. Security Officer (sa5so.cfg) ------------------------------- Beginning with version 5.2.8 the SecretAgent 5 command line allows a Security Officer to change the behavior of the command line program by restricting or enforcing certain policies. This mechanism is completely separate from the Windows Security Officer program and files. Therefore, a Security Officer who wishes to restrict both the SecretAgent 5 for Windows and SA5CLI.EXE programs will need to configure two Security Officer files. The SA5SO.CFG file MUST be located in the Windows System Folder (usually C:\Windows\System or C:\WINNT\System32) on Windows operating systems. A sample SA5SO.CFG file is provided with the distribution and contains documentation on its configuration. To display the current Security Officer restrictions use the command: sa5cli -w2 -O With the SA5SO.CFG the Security Officer may specify: . Key recovery groups and/or agents . Trusted CA path . CRL path, . Require CRL usage . Allowable encodings . Allowable compression schemes . Allowable ciphers, . Restrict the generation of self-signed certificates . Restrict the use of self-signed certificates . Restrict the use of self-extracting archives . Restrict the use of multiple file archives . Restrict the use of separate file archives . Prevent users from signing and encrypting files (Encrypt only or sign only is fine) . Prevent users from zapping files 7. KEY RECOVERY ----------------------------------- The simplest key recovery scheme just uses a key recovery agent's public key as an additional ("virtual") recipient for all messages. In this situation the message can be decrypted by the agent just as any other recipient would decrypt it. A more complex scheme is to use an additional recipient key that is split between two or more agents. If the agent public keys are in 'kra1.cer' and 'kra2.cer' and the keys have the same key type (discrete log or elliptic curve; split RSA keys are not supported!) such as dsa-1024, then the user can simply specify 'kra1+kra2' as a recipient. In this situation, decryption would require the cooperation of both agents according to the following protocol: 1. A security officer intercepts the message, say 'archive.sa5' -- '.saa' and '.exe' files will also work --and extracts its header into a '.sah' file: sa5cli -oarch.sah archive.sa5 (Anyone may perform this non-cryptographic operation; a password is not required. The '.sah' file contains only the public key wrapped session keys from the '.sa5' archive which is not sensitive information in and of itself, hence an '.sah' file may be transmitted in the clear over any insecure channel.) 2. Each key recovery agent is sent the (.sah) header file to which they apply their private key and password to produce a partial recovery (.sar) file. To do this, agent 1 runs a command like: sa5cli -dkra1 -pkra1p arch.sah while agent 2 runs: sa5cli -dkra2 -pkra2p arch.sah (Each '.sar' file contains a partially unwrapped session key that alone can't be used to decrypt the original ciphertext archive. However, when combined, the '.sar' files corresponding to a complete set of split keys can be used to decrypt the archive, so the '.sar' files should *not* be transmitted in the clear over an insecure channel.) 3. The individual key recovery agents *securely* transmit their '.sar' files back to the security administrator who combines them to finally decrypt the original ciphertext archive: sa5cli -aarch1.sar,arch2.sar archive.sa5 As with decryption by an ordinary recipient, all plaintext files are recovered with their original filenames intact. For auditing purposes, the key recovery agents should probably be required to encrypt *and sign* their '.sar' files when transmitting them back to the security officer. If he stores them in a secure database, the security officer can later provide proof that these agents did indeed participate in this message recovery operation. NOTES: Any number of (non-RSA) keys of the same size and type can be combined for key recovery purposes into a single virtual recipient. To enforce key recovery, place a '-e' option with one or more (split or individual) key recovery agent keys in a configuration file and insist that your users include that '.cfg' file on every sa5 command line along with their own second '-e' option specifying ordinary recipients. (The special configuration file 'sa5.cfg' is ideally suited for use in this way.) DISCUSSION: What we're offering here should really be referred to as "message recovery." We're just allowing the security officer to recover the random session key used to encrypt a particular archive. We do not believe in key escrow schemes and at no time does our approach require the "recovery" of a user's private key. Each message must be recovered independently and the recovery of one message does not compromise the security of any other message encrypted for the same set of recipients and/or key recovery agents. 8. ENVIRONMENT AND SPECIAL FILES -------------------------------------------------- Upon startup, the program attempts to read a file named 'sa5.cfg' in the current directory. If it exists, it is processed before all other command line arguments; no warning is issued if it doesn't exist. Additional configuration files may be explicitly specified by using the '-@' option. The environment variable RANDDIR is used by SA5CLI to determine when the .KYP and SELF32.EXE files are located. If this is not set then SA5CLI assumes these reside in the current directory. 9. Known Bugs, Limitations, Common Problems, Hints -------------------------------------------------- A common problem is the addition of .cer or .prv to the -e, -s, -g, etc. options. These options will automatically append the proper extension to the arguments given. The only exceptions to this are the -s option when doing chain validation which requires the full filename, the -@ which requires the full filename of the config file, and -o which requires the full filename of the output file in order to determine the output file type. For encryption, the specified output filename suffix ('.sa5', '.saa', or '.exe') is used to determine the ciphertext file format. If '.exe' is specified, sa5 will use the supplied 'self32.exe' stub to create an RC4-encrypted self-extracting *Windows* executable (with a key of at most 320 bits based on the supplied password). The ability to create RC4-encrypted self-extracting executables targeted for other platforms may be supplied in a future release. Simple filenames specified on the command line are assumed to be in the current directory. Use full or relative pathnames to access files in other locations. Some file systems do not support file sizes greater than or equal to 2GB (2^31 bytes). Use such files with caution. The current executable contains no directory storage or retrieval functions. A compatible, but independent, Java-based LDAP browser application is available from ISC if you need the ability to search a directory and retrieve certificates for use with SA5/UNIX. When dealing with quoted arguments there are two special requirements: When providing quoted arguments to options only use one set of quotes. So sa5cli -w2 -R -e"long path\ann,long path\bob" file1.txt is OK, but sa5cli -w2 -R -e"long path\ann","long path\bob" file1.txt is not. Finally, it is imperative that the SA5HOME (RANDDIR on Windows) environment variable is set to point to the location of the SecretAgent 5 CLI installation. This enables an administrator to install the SecretAgent 5 CLI, add it to the PATH and have all users be able to use it. If these environment variables are not set then SecretAgent 5 CLI assumes the files are in the current directory. 13. Contact Information ---------------------- Information Security Corporation Administrative & Marketing Office 1141 Lake Cook Road, Suite D Deerfield, IL 60015 Phone: 847-405-0500 Fax: 857-405-0506 Research & Development Office 1011 Lake Street, Suite 212 Oak Park, IL 60301 Phone: 708-445-1704 Fax: 708-445-9705