/****************************************************************************\ SecretAgent 5 Command Line Interface Package, Release 5.2.8 for Windows AT&T Business Markets Division Copyright(c) 1999-2001 Information Security Corp. All rights reserved. SecretAgent is a trademark of Information Security Corp. This document was last modified on: 11 June 2001 \****************************************************************************/ SA5CLICOM.dll SA5CLI.DLL, SA5CLI.EXE, CDK1B.DLL, THE TEST PROGRAMS, AND THIS DOCUMENTATION ARE PROPRIETARY. THEY ARE FURNISHED UNDER A LICENSE OR NON-DISCLOSURE AGREEMENT. PLEASE TREAT THEM AS CONFIDENTIAL. Preliminary Notes on the SA5CLI Package --------------------------------------- This README file contains information on the SecretAgent 5 Command Line Interface Package (SA5CLI). SA5CLI provides the applications developer with a command line interface to most of the cryptographic functions provided by SecretAgent 5 for Windows. SA5CLI.EXE is a stand-alone 32-bit Windows executable supporting the UNIX-like command line syntax described below. SA5CLI.DLL is a Windows DLL version exporting functions that support the same command line syntax and provide error reporting. (SA5CLI.DLL depends on CDK1B.DLL, the main cryptographic DLL in SecretAgent 5 for Windows.) SA5CLICOM.dll is a Windows COM object exporting the same functions as SA5CLI.DLL (it depends on SA5CLI.DLL and CDK1B.DLL). WARNING: This package should not be expanded into the same directory as the SecretAgent 5 GUI. The version of CDK1B.DLL shipped with this package is likely to be newer (and possibly incompatible) with the version required for any given shipping release of the commercial GUI package. Information in this document is subject to change without notice and does not represent a commitment on the part of AT&T Business Markets Division, Information Security Corp. or Digital Signature. 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. Table of Contents ----------------- 1. Files in the SA5CLI Distribution 2. Functions Exported from SA5CLI.DLL 3. Command Line Syntax 4. SA5CLI Return Values 5. SA5CLICOM Installation and Use 6. Security Officer (sa5so.cfg) 7. UNIX Man Page (Applies to Windows) 8. Known Bugs and Limitations. 9. Contact Information 1. Files in the SA5CLI Distribution ----------------------------------- CDK1B.DLL the SecretAgent 5 cryptographic engine README.TXT this document SA5CLI.EXE a complete, stand-alone, build of the 32-bit SecretAgent 5 application for Windows SA5CLI.H a header file containing declarations of the functions exported from SA5CLI.DLL SA5CLI.DLL the "high-level" DLL for command line parsing, it exports the functions listed in SA5CLI.H but depends on CDK1B.DLL for its cryptographic functions SA5CLI.LIB an VC++ 6.0 import library for the DLL, if you need it (alternatively, you can link explicitly using the LoadLibrary/GetProcAddress/FreeLibrary WINAPI calls) SA5CLICOM.DLL a COM library exporting the same functions as SA5CLI.DLL SA5SO.CFG a sample Security Officer settings file COMVBTEST a Visual Basic 6 sample project using the SA5CLICOM.DLL TEST5.BAT a test command script to illustrate the use of SA5CLI.EXE; runs the same tests as TEST5CLI.EXE. TEST5CLI.CPP a test program with sample code to show how the functions in SA5CLI.DLL may be called TEST5CLI.EXE the Windows test executable that illustrates how to call the sa5cli() entry point in SA5CLI.DLL in order to generate keys and encrypt and decrypt a specified file TEST5CLI.DS* a Microsoft Visual Studio 6.0 workspace/project that may be used to rebuild the sample test program. *.KYP a collection of parameter definition files used to generate asymmetric key pairs and self-signed certificates NOTE: You must have both SA5CLI.DLL and CDK1B.DLL in the same directory as your application (e.g., TEST5CLI.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 either SA5CLI.DLL or SA5CLI.EXE. 2. Functions Exported from SA5CLI.DLL ------------------------------------- The prototypes (from SA5CLI.H) are: int __cdecl sa5version(void); int __cdecl sa5cli(const char *cmdline); void __cdecl sa5err(LPSTR str); int __cdecl sa5inspect(const char *filename, char *info); sa5version() returns the version number of the library (multiplied by 100), currently 528 for this release. sa5cli() provides the command line interface into CDK1B.DLL; see the next section for details. sa5err() will (hopefully) return the error message string associated with the last error encountered by sa5cli(). sa5inspect() returns in a null-termated ASCII text string the following information for a .SA5 archive: filename cipher/mode (if encrypted) format (binary or base64-encoded) originator (given by a DN following a prefix of "FROM: ") recipients (given by a DN following a prefix of "TO: ") If called with a NULL second argument, it will return the number of bytes required for the output string (including it's null terminator). It is expected that the caller will make this call, then allocate a buffer of sufficient size, and call the function again. OTOH, the sufficiently daring programmer (with some knowledge of the expected number of recipients in the archive) can try providing a sufficiently large output buffer on a first pass. Good luck! 3. Command Line Syntax ---------------------- The command line as understood by sa5cli() (as well as SA5CLI.EXE) is essentially the same as the SecretAgent DOS/UNIX command line described in the following manual page. (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 indicated, you would simply make the function call 'sa5cli()' or execute the command 'sa5cli .' For example, the UNIX command: sa5 -eann,bob,r1+r2 -oarchive.sa5 plain1.txt plain2.txt would be invoked in a Windows application linked to SA5CLI.DLL as: sa5cli("-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 NOTE: Under Windows, the UNIX inspect command 'sa5 -V archive.sa5' would become either sa5cli("-V archive.sa5"), if you desire output to stdout, or sa5inspect("archive.sa5",outbuf) if you want the information returned in the caller-supplied output buffer "outbuf." All SA5 certificate, CRL, and private key files should be interoperable between the DOS, Windows and UNIX platforms. 4. SA5CLI Return Values ----------------------- sa5cli() will return 0 on success; a non-zero return value indicates an error whose nature can be determine by calling sa5err() and interpreting the returned error description string. Numeric return codes will be documented in a future revision of this file. sa5err() will return precisely what the sa5cli.exe file would display to the screen given the same command line. Therefore, even on success it is sometimes useful to call sa5err() to retrieve information from the command line (-O for example will give the current Security Officer settings). 5. SA5CLICOM Installation and Use --------------------------------- The SA5CLICOM object must be registered before you can use it in your projects. The command to register the DLL is: regsvr32 SA5CLICOM.DLL Notes: CDK1B.DLL and SA5CLI.DLL must be in the path in order for registration to occur. If you are writing an installation package providing the /s command line option to regsvr32 will prevent it from displaying dialogs. Where ever you register the COM object is where Windows will look for all three files (CDK1B.DLL, SA5CLI.DLL, and SA5CLICOM.DLL). Please see sections 3 and 4 as the information contained therein is applicable to the SA5CLICOM object. SA5CLICOM contains the following properties: sa5version sa5version returns a number containing the version of the SA5CLI.DLL file. This can be used to make sure you have the right version of the SA5CLI.DLL. sa5err sa5err returns a string containing the output that SA5CLI.EXE would produce given the command line provided to sa5cli. sa5cli(string) sa5cli takes a command line as string (e.g. "-w2 -R -O") and returns an error code as a number (zero is success, non-zero is failure). You can call sa5err for more information. sa5inspect(string) sa5inspect takes a filename as string ("Archive.SA5") which should be a SecretAgent 5 archive (.sa5) file and returns a string containing the header information (cipher type, encoding, compression, originator, recipients). 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 seperate from the Windows Security Officer program and files. Therefore, a Security Officer who wishes to restrict both the the SecretAgent 5 for Windows and SA5CLI.EXE programs will need to configure two Security Officer files. On UNIX the same mechanism is used for both the SecretAgent 5 command line and Java Graphical versions. The SA5SO.CFG file MUST be located in the Windows System Folder (usually C:\Windows\System or C:\WINNT\System32) on Windows operating systems. The SA5SO.CFG file MUST be located in / for UNIX operating systems. A sample SA5SO.CFG file is provided with the distribution and contains documentation on its configuration. 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 seperate file archives . Prevent users from signing and encrypting files (Encrypt only or sign only is fine) . Prevent users from zapping files 7. UNIX Man Page ---------------- NAME sa5 - SecretAgent 5 Release 5.2.8 SYNOPSIS sa5 [options] [source_files] DESCRIPTION sa5 is a program for encrypting and decrypting disk files and generating asymmetric (RSA, DSA, ECDSA) key pairs, PKCS#10 certificate requests and self-signed X.509 certificates. OPTIONS The following options are supported by sa5. 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. -@ Optional configuration file, principally used to specify X.509 distinguished name components for generating self-signed certificates and PKCS#10 (RFC 2314) certificate requests using the -g option. (DO NOT specify the special configuration file 'sa5.cfg' using a '-@' option since that will cause it to be processed twice.) See the sections USAGE and CONFIGURATION FILES below. -a Specifies one or more partial "KR agent recovery files" during the final decryption stage of a key recovery process. See KEY RECOVERY below. -b Specifies a folder or path where CRLs are located (this is an optional parameter to the -v command and requires that an index file be built beforehand using -c). -c Builds either a CA or CRL index file (an index file is a file mapping Subject DNs to filenames). If followed by -b it builds a CRL index file in the path provided by -b. If followed by -y it builds a CA index file in the path provided by -y. This command must be run each time a certificate or CRL is added or removed from the path. This command must be executed at least once before using -v to do certificate chain verification. -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. -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). -h Display usage help message. -i Issuer certificate file which can be used with '-d' option to validate a purported signer's certificate during the signature validation process. -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. See Examples. -o Output path or file. Used to specify the output format for ciphertext archives during encryption, the output path for plaintext files during decryption, the names of the archive header and partial key recovery files during key recovery, and the name of the self-signed certificate or PKCS#10 certificate request file to be created during key generation. -O Display the current Security Officer restrictions. -p Password (for key generation, signing and decrypting). Only required for password-protected private key files. -q Overwrite existing output files without warning. -r Reseed (or initialize the seed) for the pseudorandom number supply. -R Reseed (or initialize the seed) for the pseudorandom number supply using system state information. -s Sign with private key -t Type of key to generate (required by -g). See SUPPORTED KEY TYPES below for details. -v Certificate against which to verify a signature or subject certificate. Use with '-d' to identify and authenticate the purported signer during decryption or alone with a .cer file for certificate validation. -w# Verbosity level 0 minimal progress and diagnostic output 1 terse progress and diagnostic messages 2 more detailed progress and diagnostic messages -y Specifies a path containing CA certificates to use in certificate chain validation. Providing this option to the -v command causes the verify to validate the entire certificate chain looking for CA certificates in the path provided by -y. This command requires an index file to be built with the -c command beforehand. -z Zap specified file(s) (secure erasure compliant with the obsolete DoD Magnetic Remanance Guidelines) -C# Compression algorithm (applied to plaintext prior to encryption) 0 *none 1 LZSS -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)) -E# Symmetric encryption cipher 1 DES-ECB (FIPS 46-2, FIPS 81, ANSI X3.92, X3.106) 2 DES-CBC (FIPS 46-2, FIPS 81, ANSI X3.92, X3.106) 3 TDES-ECB (FIPS 46-3, ANSI X9.52) 4 TDES-CBC (FIPS 46-3, ANSI X9.52) 5 EA2-ECB (AT&T proprietary exportable cipher) 6 EA2-CBC (AT&T proprietary exportable cipher) 7 DESX-ECB 8 DESX-CBC (DES-XEX3-CBC in draft-simpson-desx-02.txt) 11 AES-ECB (draft FIPS) 12 *AES-CBC NOTE: When creating an "encrypt-in-place" '.saa' file, the cipher used is DESX-CBC. For "self-extracting" '.exe' files it's RC2. In these cases, any explicit '-E' option is ignored. Otherwise, for '.sa5' files, the default cipher is AES-CBC but a '-E' option can be used to change it. -F# Output format 0 *none (binary) 1 ASCII (base64-encoded) -V 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.) As usual, options may be separated from their arguments by one or more spaces. Options without arguments may be grouped behind a single dash. Most of these options are explained below. HINT: You may run 'sa5' without command line arguments to display an up-to-date list of the supported options. The current output looks as follows: Usage: sa5 [options] [files] Basic functions: (order of options is irrelevant) help: sa5 -h keygen: sa5 -g -p [-t] [options] encrypt: sa5 -e [-s -p] [options] file... decrypt: sa5 -d -p [-v] [options] file inspect: sa5 -V (shows format/cipher/mode of .sa5 archives randomize: sa5 -r (may be combined with -g, -e, or -d) randomize: sa5 -R (uses system state as seed, may be combined with -g, -e, or -d) zap: sa5 -z file... (WARNING: this is non-interactive!) Certificate and CRL functions: inspect certificate (and optionally verify against issuer): sa5 [-v] build CA index file: sa5 -c -y build CRL index file: sa5 -c -b verify entire chain (with optional CRL checking); requires index file(s): sa5 -v -y [-b] Security Officer functions: display Security Officer policy: sa5 -w2 -O Simple options: -q overwrite without warning Options taking a string argument: -a key recovery agent file -o output directory (decrypt) or path\filename (encrypt) -t key type (dsa-*,rsa-*,us-*; dsa-1024 is the default) Options taking a numeric argument: (supply integer for #; * indicates default) -C# compression algorithm -F# format (printable encoding) 0 *none 0 *none (binary) 1 LZSS 1 ASCII -E# encryption algorithm -w# verbosity level 1 DES-ECB 0 *none 2 DES-CBC 1 errors 3 TDES-ECB 2 warnings, errors, running times 4 TDES-CBC 5 EA2-ECB 6 EA2-CBC 7 DESX-ECB 8 DESX-CBC 11 AES-ECB (128-bit) 12 *AES-CBC (128-bit) -D# message digest (for certificate functions) 1 MD2 3 MD5 4 *SHA-1 For examples, see 'sa5.txt' or 'readme.txt'. USAGE Generating a key pair, with self-signed certificate or certificate request. Generate an asymmetric key pair with a command of the form: sa5 -g -t -o [-D#] [-p] where is your common name, is the name of a .kyp file without the .kyp suffix. 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. (To specify the X.509 DN components for the certificate, see CONFIGURATION FILES below.) Add "-p" if you want to password protect (i.e., RC4-encrypt) the .prv private key file. For example, the command sa5 -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 sa5 -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: The default message digest function used to form a self-signed certificate -- and a certificate request file if one is created -- is SHA-1. Use the '-D' option to change it. Also by default raw binary PKCS#10 certificate request files are created; specify '-F1' to obtain a base64 encoded output file if that is required by your CA or by the mechanism by which you will transmit it to the CA. Importing a PKCS#12 File Import a PKCS#12 file with a command of the form: sa5 -g -p Ann.p12 where is the path and base name of the seperate files in the PKCS#12 file. For example, the command sa5 -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 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: sa5 [-v] where is a .cer file (*with* its .cer suffix). Include the optional "-v" 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 certicate chain; just invoke a new sa5 instance for each link in the chain. Alternately, an entire certificate chain can be validated at once (with or without CRL checking) using a command of the form: sa5 -v -y [-b] 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 '-b' 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: sa5 -c -y For example, the command sa5 -w1 -c -y/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: sa5 -c -b For example, the command sa5 -w1 -c -b/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, seperate directories are required for CA certificates and CRLs, if you are using the latter type of files! Encrypting Encrypt one or more files with a command of the form: sa5 -e [-C#] [-E#] [-F#] [-o] \ [-s [-p]] where is a comma delimited list of one or more .cer certificate files (*without* the .cer suffix). (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.) The optional output filename must have one of the following suffices (if no output filename is provided or a path ending in '/' (UNIX) '\' (WINDOWS) is provided each file that is to be encrypted is encrypted into a seperate 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 (Under MS Windows, SA5 supports the auto-encrypt '.saa' and self-extracting '.exe' file formats and they are also provided under Unix for compatibility. For most purpose, however, you'll want to use the .sa5 suffix.) For '.sa5' output files, you can add '-C', '-E' and '-F' options to modify the compression algorithm, symmetric cipher, and output format, respectively. Add "-s [-p]" to sign the plaintext files, where is the name of your .prv private key file *without* the .prv suffix. The -p option is only required if your private key file is password-protected. 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 before an encryption run, just invoke sa5 on each recipient .cer file (supplying the appropriate issuer certificate) before encrypting. Simple shell scripts can be written for this purpose as long as the issuer-subject correspondences, or entire certificate chains, are known. Signing without encrypting To sign *without* encrypting, specify an empty recipient list with a period ('-e.') as in the command (providing -o causes all signatures to be stored in the , excluding the -o creates a seperate signature file for each file): sa5 -e. [-o] -s [-p] Verifying a signature Verify the signature on one or more signed (but not encrypted) archives with a command of the form: sa5 -v [-i] where is the purported signer's certificate file *without* its .cer suffix. Include "-i" to also validate the .cer certificate file. 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 a error message and will not be able to validate the signature without also decrypting the archive in the manner decribed next. Decrypting Decrypt a file with a command of the form: sa5 -d [-p] [-v [-i]] "-p" is only required if your private key file .prv is password protected. If the file is signed and you want to validate the signature, add "-v", where is the name of purported signer's .cer certificate file. (This .cer file will be created if it doesn't already exist as long as the archive's signature(s) validate against the copy of the originator's certificate included in the archive itself. This is one way to get a certificate from a previously unknown individual -- just have them send you a signed message. Of course, such certificates should be validated as described above as soon as they are received.) Include "-i" if you also wish to validate the signer's certificate against a known issuer certificate. (This capability is most useful if all your end-user certificates are all subordinate to a single, common root CA. Otherwise you will somehow have to keep track of the PKI hierarchy and explicitly validate each certificate back along the chain to its root using separate invocations of sa5 for each link in the chain above the subject's immediate issuer.) Erasing a sensitive file Zap (or securely erase) one or more files with a command of the form: sa5 -z 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. 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: mmddHHMMyyyy 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=050100002000 // May 1, 2000 00:00:00 GMT NA=050100002002 // 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 directy, 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. 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) EXAMPLES All sa5 functions assume that a writable random number file named '.random' exists (or can be created) in the user's home directory. It should not be readable by others, though its disclosure should not be a serious security problem. Note: On Windows the random file is called random.bin and can be a shared file. Per user random information is stored in the HKEY_CURRENT_USER section of the Windows Registry. (The pseudorandom number generator is reseeded with system state information one or more times during every sa5 invocation, so your '.random' file needs to be readable and writable whenever you run sa5. Because of the additional entropy gleaned from your system before each random number is generated, it is probably not very important that you physically protect '.random', but why take unnecessary chances?) 1. Initialize (or reseed) the random number supply and set appropriate permissions on '.random' (UNIX): ls -al ~/.random chmod 600 ~/.random sa5 -r qwertyuiopasdfghjkl ls -al ~/.random Here it is assumed that '~/' is interpreted by your shell (csh?) as a reference to your home directory. If you are not running csh and '~/' doesn't work, try '//' or '$HOME/' instead. Under Windows your do not need to change the permissions on random.bin. The following command will seed the randome number supply on Windows: sa5cli -r qwertyuiopasdfghjkl Note: The argument of '-r' should be an single alphanumeric string as the shell may filter other characters. The file '.random' should always be exactly 20 bytes in length. If it is ever corrupted, simply delete and recreate it. 2. Generate a dsa-1024 key pair called ann: sa5 -@ann.cfg -gann -tdsa-1024 -oAnn.cer The public key (actually a self-signed certificate) is put into a file named 'Ann.cer' and the private key is output to 'Ann.prv'. This private key file is *NOT* encrypted since no password was specified on the command line. NOTE: In this example, the initial DN fields for Ann's certificate are read from the file 'ann.cfg'. 3. Same as above, but with a password-protected private key file and a base64-encoded PKCS#10 certificate request file: sa5 -@ann.cfg -gann -pannp -tdsa-1024 -F1 -oAnn.crq Ann can now email the file 'Ann.crq' to her CA as a request to issue a certificate containing her new public key. 4. 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': sa5 -ebob -oarchive.sa5 plain1.txt plain2.txt Note that it is important to explicitly specify the '.sa5' filename suffix here so that sa5 knowns exactly which output archive format to generate. (Add '-F1' to produce an ASCII (base64-encoded) ciphertext archive.) 5. Same as above, but with recipients ann, bob, and a split (key recovery) key r1+r2. sa5 -eann,bob,r1+r2 -oarchive.sa5 plain1.txt plain2.txt Note that only non-RSA keys of exactly the same size and type can be combined in this manner. 6. Same, but with a self-decrypting Windows executable '.exe' output file: sa5 -eann,bob,r1+r2 -oarchive.exe plain1.txt plain2.txt NOTE: The output ciphertext file format is inferred from the specified extension on the output filename. 7. Same as above, but with a separate encrypted file for each input file: sa5 -eann,bob,r1+r2 plain1.txt plain2.txt 8. Decrypt 'archive.sa5' with the private key 'ann.prv' which is protected by the password 'annp': sa5 -dann -pannp archive.sa5 9. Same as above, but putting the plaintext output in the directory '~/plaintext': sa5 -dann -pannp -o~/plaintext archive.sa5 See the tsa5 shell script for additional sample command lines, especially those illustrating the key recovery process. 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. 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: sa5 -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: sa5 -dkra1 -pkra1p -oarch1.sar arch.sah while agent 2 runs: sa5 -dkra2 -pkra2p -oarch2.sar 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: sa5 -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. ENVIRONMENT AND SPECIAL FILES A state vector for the pseudorandom number generator is maintained in a file named 'random.bin' in the application's startup directory. Under Windows, you may relocate this file by creating a RANDDIR environment variable and setting it to the directory in which you want sa5 to maintain its 'random.bin' file. However, note that on Windows sa5 looks in RANDDIR for its KYP files so the RANDDIR should be a shared folder that all users use. On UNIX .random is stored in the user's home directory and the environment variable SA5HOME is used to indicate the path where the KYP files are located. 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. NOTES 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 will 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. LIMITATIONS Some file systems do not support file sizes greater than or equal to 2GB (2^31 bytes). Use such files with caution. While SA5 has been tested with the certificates issued by most of today's popular certificate authorities (VeriSign, GTE, XCERT, Baltimore, etc.), key revocation lists (CKLs) are not currently supported. 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. 8. Known Bugs, Limitations, Common Problems, Hints -------------------------------------------------- The file temp.$$$ is sometimes used as a temporary file but may not be removed at program termination. Attempting to generate a key without providing the newly mandatory '-o' switch and an appropriate filename argument may not generate a error message and may leave an empty '.prv' file. This is an OEM release... please report any other problems to us. While all of the documented functions have been tested to some extent, more testing needs to be done. In addition, the error detection and recovery mechanisms and the text of warnings and error messages all need to be improved. The most common problems that developers encounter when using the SecretAgent 5 command line executable or DLLs is the failure to properly initialize the pseudorandom number generator. An easy solution to this is to always include the -R option. The -R option will add system state information to the random file and will prevent error 21 from occuring. Another 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 execeptions to this are the -v 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. When dealing with quoted arguments there are two special requirements: When providing quoted arguments to options only use one set of quotes. So sa5 -w2 -R -e"long path\ann,long path\bob" file1.txt is OK, but sa5 -w2 -R -e"long path\ann","long path\bob" file1.txt is not. Finally, there is a special requirement on Windows regarding the SA5CLI.DLL and SA5CLICOM.DLL files. These DLLs cannot handle quoted arguments with a space between the option and the argument. So sa5 -w2 -R -e"long path\ann" file1.txt is OK, but sa5 -w2 -R -e "long path\ann" file1.txt is not. 9. 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