SecretAgent API and CLI Support

  • Downloads
  • History 6.x
  • History 5.x
  • Knowledgebase
Description
Date
Notes
 
 
SA7CLI 7.0.1 README File
5/05/14
The README file (in text format) that is provided with release 7.0.1 of the software

SA6CLI 6.3.1 README file
4/02/15
The README file for release 6.3.1 of the sa6 executable
 
 
SA6CLI 6.2.4 man page
3/06/12
A man page for release 6.2.4 of the sa6 executable
SA6CLI 6.2.4 README File
3/06/12
The README file for release 6.2.4 of the sa6 executable
 
 

SA5CLI 5.9.1 man page
9/15/05
A man page for release 5.9.1 of the sa5 executable
 
 
SA5CLI 5.7.1 README File
10/28/03
The README file for release 5.7.1 of the sa5 executable
 
 
SecretAgent 6.2.4

Bug fixes:

  • sign operations no longer crash when presented with a '.' private key specification
  • all signatures employing SHA-2 are now correctly validated
  • CertOpenStore() calls now specify the READONLY flag to prevent some rare deadlock conditions

Documentation update:

  • inclusion of '--format 5' information: '--format 5' specifies the use of algorithms that provide backwards compatibility with SecretAgent version 5.x (more precisely 5.6 and above); the same can be accomplished with '--digest 4' and '--kdf 0'
SecretAgent 6.2.2

Operational changes:

  • the standard KDF for NSA Suite B ECC DH key exchange is now the default for both SecretAgent and CMS output formats ('--kdf')
  • added '--resumable' to permit the resumption of some interrupted decrypt operations
  • transitioned to the use of AES-256 for the proptection of PKCS#8 (.prv) files
  • added SHA-224 support for CMS
  • added supports for DAS URL redirection with DAS v2.0 and above

Changes in text output:

  • key exchange algorithm IDs are now output when inspecting ciphertext archives
  • certificate inspection now supports more extension types
  • verbose mode includes timing information for DAS operations

Bug fixes:

  • '--recurse' with '--decrypt' now properly builds a subtree in the destination path
  • the decryption process for mixed ECC and DSA/DH recipients has been corrected
  • PKCS#12 files generated by Oracle Wallet and Windows 7 that 'include all properties' can now be successfully imported
  • the OCSP 'No Revocation Checking' extension is now properly displayed
  • archive recipients can again be successfully replaced
  • temporary working files are removed and a proper error message is generated if the user attempts to use a DSA certificate to create a CMS archive
SecretAgent 6.1.3

Operational change:

  • the first cipher specified as allowed in 'sa6so.cfg' becomes the default cipher
SecretAgent 6.1.2

Operational changes:

  • using '-w 4' with OCSP verification will output the OCSP request as well as the server's response

Changes in text output:

  • the software identification lines now include the date of compliation

Bug fixes:

  • OCSP responses containing any of the following are now handled properly:
      - more than one response
      - an error code from the server
      - keyHash as the responderID value
SecretAgent 6.1.0.9

Operational changes:

  • improved performance
  • the software distribution now includes both 32- and 64-bit executables
  • added '--no-threads' to disable thread use during cryptographic operations
  • added '--smime-body' to allow the specification of a message body when creating S/MIME CMS archives
  • OCSP is now supported in '--val-cert': use '--ocsp-server <url>' with ' --ocsp-cert <file>' to perform an OCSP revocation check after other checks to confirm that the certificate is valid
  • added '--output-certs' to save recipient certificates during decrypt, verify, inspect, and OCSP operations
  • added the '--force' ('-f') option to decryption to output plaintext regardless of integrity check failures
  • added proxy server support for DAS transactions: '--proxy-server', '--proxy-port', '--proxy-user', '--proxy-pin'
  • added support for SHA-224, SHA-256, SHA-384, and SHA-512 when creating .sa5 and .p7m archives (for both integrity checking and signature purposes)
  • added support for the creation and decryption of '.spe' PBE-protected archives for which the new modes AES-192-CTR ('--cipher 14') and AES-256-CTR ('--cipher 16') are available
  • the 'sa6so.cfg' administrative configuration filefile may now specify one or more DAS server URLs

Changes in tText output:

  • use of '--output-certs' causes the location and filename of each saved certificate to be displayed
  • during certificates inspection an otherName principalName in a subjectAltName extension is now decoded into UTF-8 rather than displayed in HEX
  • '--val-cert' operations that request OCSP checking will disply the OCSP response

Bug fixes:

  • error detection/reporting now works properly when decrypting a raw CMS archive ('--format 2') with MIME processing enabled ('--format 1' or '.p7m' files with no format specification)
  • PKCS #11 token certificates without CKA_ID attributes are now handled properly
  • PKCS #11 key generation now works properly if the '--gen-key-type' argument includes the '.kyp' file extension
  • PKCS #11 key generation now obeys the '--encoding' argument
  • plaintext that is a multiple of 16 bytes is now truncated to the correct length when decrypting raw CMS archives ('--format 2')
  • archived credentials in Microsoft Windows CAPI/CNG can now be used
  • S/MIME messages generated by Outlook 2010 using the subject key identifier method of specifying recipients can be decrypted
  • '.spe' is now recognized as a valid file extension for self-decrypting archives
  • forward slashes are now accepted in path- and filenames on Windows
  • certificate inspection now properly displays otherName principalName attributes as UTF-8
  • the command line PBE-protected archive reader now properly errors if the user fails to provide a password
SecretAgent 6.0.33

Operational changes:

  • a new '--das-check' command checks DAS COI membership

Changes in text output:

  • filename displays now use backslashes ('\') on Windows and forward slashes ('/') on UNIX

Bug fixes:

  • CNG decryption (Windows Vista Only) now checks to see if a certificate/private key pair matches the recipientInfo PDU instead of always attempting to unwrap
  • internal MIME headers in S/MIME messages are now produced that Thunderbird 2.0.0.17 can successfully parse and display
  • the validatation of detached signatures on S/MIME messages that contain multiple blank lines of varying length has been corrected
  • decryption/verification of S/MIME messages with an internal multipart/alternative MIME message body (a mix of HTML and Text) no longer causes a crash
SecretAgent 6.0.32

Operational changes (UNIX only):

  • improved entropy gathering for random number generation
  • support added for the use of CACs with the libcoolkeys PKCS#11 libary

Changes in text output:

  • '--print-info' now properly displays 'sha224RSA' (instead of 'unknown') when displaying certificates with SHA224-based RSA signatures

Bug fixes:

  • a temporary '.ba0' file is no longer left on disk when a CMS signature operation fails
  • Base64-encoded CMS archives are now properly decrypted
  • encryption now succeeds when a folder is specified as the output location ('-o folder/')
  • inspection of a certificate containing an empty alternative name extension no longer causes a crash
  • ECDSA signatures are now properly encoded in CMS archives
SecretAgent 6.0.31

Operational changes:

  • CRLs which contain a FreshestCRL extension are no longer rejected unless the security policy file ('sa6so.cfg') explicitly specifies that they be rejected

Changes in text output:

  • ' --print-policy' now states whether CRLs which contain a FreshestCRL extension are considered valid or not

Bug fixes:

  • crashes no longer occur when using ActivIdentity's Linux client for smartcard access
SecretAgent 6.0.30

Operational changes:

  • the ' client-auth' switch has been renamed 'das-auth'
  • the 'dasuser' switch is now 'das-user'
  • decrypt operations on multiple files continues after the occurence of an input file error
  • a new 'das-list' switch explicitly specifies the URIs to be dereferenced to reach an appropriate DAS server (rather than using the URIs embedded in the COI certificate)
  • a COI name (together with a 'das-list') may be specified in a certificate's SAN otherName field using OID 1.3.6.1.4.1.31623.1.1
  • a new 'das-timeout' switch specifies the timeout value to use for DAS connection attempts

Changes in text output:

  • using '--verbosity 4' will output additional DAS connection information
  • the "Extensions:" section label is no longer output when inspecting a certificate that contains no extensions
  • changes to the display of extensions during certificate inspection:
    • spacing is improved; in particular, SAN output is better aligned
    • SAN otherName values that SecretAgent doesn't understand are now preceeded by '0x' to indicate that the values are HEX-encoded
    • SAN ediPartyName and registerID now display properly

Bug fixes:

  • 'Broken Pipe' is no longer erroneaously reported when the software is unable to connect to a DAS server
SecretAgent 6.0.29

Operational changes:

  • the new command line syntax supports long switches; to use the old command line syntax, set SA5PROCESSING=1 in the environment
  • the '--format' option now supports all output formats so that it is no longer necessary to specify output format by file extension
  • signing certificates may be supplied by a filename argument referencing a PKCS #7 PDU
  • '--verify' always outputs the certificate in the specified file and never uses it for validation
  • superencryption is again supported
  • option arguments containing environment variables read from a configuration file are automatically expanded
  • the sa6so.cfg security policy file may be located in more common folders (see man page)

Archive changes:

  • one or more recipientInfo blobs, each of which represents the intersection of two or more communities of interest (COI), may be included in an archive header; to use such a blob for decryption, the user must have access to all of the private keys for the COIs being "intersected"
  • NIST/RFC 3394 AES key wrapping is now used in PBE-protected archives (i.e., self-decrypting archives or "SDAs")
  • new message attributes are now supported: security label, priority, color
  • a new '--output-all' option causes the '$$msg$message$txt.tmp' message body and '$$msg$audits$bin.tmp' archive history files (included in an archive by the SecretAgent 6 GUI) to be output during decryption if they are present

Key management changes:

  • support has been added for SHA-224 per FIPS 180-2 (as amended by the change notice of 25 Feb 2004)
  • the executable now enforces NIST FIPS 186-3 draft and SP 800-57 recommendations for key size and message digest choices for ECC operations
  • one may now specify a PKCS #12 password that differs from the PKCS #8 password used to protect the key being exported
  • '--import-p12' now supports the installation of credentials onto a PKCS #11 token
  • '--gen-key' now accepts a complete DN and supports key generation on a PKCS #11 device; when PKCS #11 is used to generate a certificate request, the subsequent '--install-cert' command will properly load its certificate onto that same device

Performance changes:

  • CMS processing supports STDIN/STDOUT, no longer creates temporary disk files, and is much faster overall due to complete reliance on in-memory operations

Changes in text output:

  • archive inspection will now report:
    • security label info
    • COI intersection info that might be contained in a recipientInfo blob
  • the display of SAN Othername values has been modified to align with Microsoft's
  • error messages supggesting the use of a particular command line option have been updated to the new command line syntax

Bug fixes:

  • a persistent entropy value is now properly stored in .secretagent.random or in the Windows registry
  • compression is properly applied when encrypting from STDIN using the SA5 archive format
  • SDA key recovery now works with passwords more than 16 bytes in length; an SDA employing RSA-based key recovery may be decrypted with the recovery agent's private RSA key by specifying '-d store' rather than '-d'
SecretAgent 5.9.5
  • modified to support PKCS#11 tokens that do not properly return errors when unsupported mechanisms are passed to C_DecryptInit().
SecretAgent 5.9.4
  • rather than aborting, a warning is now issued when -k is not specified and a READONLY file is encountered during autoencrypting/autodecrypting
  • already encrypted/signed files are now skipped when encrypting/signing folders and the user is told to use the -Y option to override this behavior
  • supports the iKey via CAPI in the same manner as does the Windows GUI
  • accepts 'sa5so.cfg' entries that appear at the end of the file without a following newline
  • index creation now records only the names of the certificate and CRL files rather than their complete paths; when loading such files it is assumed that they reside in the same folder as the corresponding index file ('caindex', resp. 'crlindex')
SecretAgent 5.9.3
  • reads sa5.cfg from RANDDIR/SA5HOME rather than current working directory
  • dereferences environment variables found in configuration files; for example, if a -@ $HOME/user.cfg is a line in a configuration file (say sa5.cfg) the command line will now expand the embedded environment variable $HOME into /home/tj
  • supports either ST= or SP= in configuration files to provide state/province information to be included in distinguished names when generating self-signed certificates or certificate requests
  • supports reading from a pipe and from the console when -Z1 is specified
  • now warns the user that CMS does not support compression when -L1 or -L2 is combined with -C1
  • now overwrites filenames during zap operations: files are renamed 26 times using the lowercase letters of the alphabet prior to removal
  • now removes empty directories/folders during zap operations: folders are renamed 26 times using the lowercase letters of the alphabet prior to removal from the file system
  • now inserts correct OIDs for AES-192 and AES-256 into CMS archives
SecretAgent 5.9.2
  • no longer aborts decrypt operations when the -d argument specifies a path containing a file with a single character filename
SecretAgent 5.9.1
  • improves the hash value displayed when using -H
  • adds support for Entrust profiles; requires the following Entrust libraries (available separately from Entrust):
      Windows: entapi32.dll, enterr.dll, and etfile32.dll (Entrust Authority PKCS#7 Toolkit for C 6.0 SP4 patch 96312 or higher)

      Solaris: libEntrust.so, libentapi.so (Entrust Authority PKCS#7 Toolkit for C 6.0 SP4 or higher)
  • to access an Entrust profile, you must use the sa5cli_e.exe/sa5_e versions of sa5cli.exe/sa5 with the following syntax:
      sa5_e -w1 -s entrust.ini,my.epf test.txt
      sa5_e -w1 -d entrust.ini,my.epf test.txt.sa5
  • improves PKCS#11 support for devices that do not enforce the CKA_ID of certificates to match the CKA_ID of private keys
  • now accepts .p7b or .p7c files for -d and -s operations both as individual files and within specified key history paths
  • outputs .p7c files in addition to certificate files when importing PKCS#12 files
  • improves the command line syntax checking and error messages
  • supports zapping files larger than 2GB on UNIX-based systems
  • now outputs .p7c files and certificate files when inspecting PKCS#11 devices
SecretAgent 5.9.0
  • supports DAS server-mediated decryption
  • permits the replacement of recipient certificates in an encrypted archive by combining -e and -d options
  • creates valid PKCS#7 files when the input files are base64 encoded
  • separates the date/time and reason code fields when inspecting CRLs
SecretAgent 5.8.0
  • supports the -F1 option during key generation
  • provides additional options in the sa5so.cfg file
  • includes support for using PKCS#11 devices for private key operations on Windows, Linux, and Solaris:
      Usage: -d label,library or -s <certfile>,label,library.

      For example:
        sa5cli -w1 -d green,c:\windows\system32\p11lib.dll file.sa5
        sa5 -w1 -e. -s green.cer,green,/usr/local/p11lib.so a.txt
  • supports using Microsoft Windows' CAPI for private key operations:
      Usage: -d CAPI or -s <certfile>,CAPI

      For example:
        sa5cli -w1 -d CAPI file.sa5
        sa5cli -w1 -e. -s user.cer,CAPI a.txt
      will look for the sa5so.cfg first in the root or Windows System folder and then in the folder in which the command line executable resides
  • allows decryption of files when only the private key file exists
  • allows users to specify an output path when decrypting
  • marks decrypted files with permissions such that only the decrypting user can read the files (UNIX only)
  • supports operations on folders (-e, -d, -z) whereby users can specify a folder to encrypt, decrypt, or zap
  • applies proper date/time to files when decrypting on UNIX systems
  • removes whitespace from DN components during key generation
  • conforms to RFC 3280 when performing path validation and successfully passes NIST's PKITS test suite
  • supports CMS sign only operations with ECC keys
  • allows users to use/create private keys without password protection by including -Q
  • supports overwriting read only files during auto-encryption with -k
  • allows users to specify output paths without the trailing slash
  • properly disables validity checking when the -n option is used -e
  • allows users to specify an output filename when supplying the -L2 option to -e and there is only 1 input file
  • supports zapping entire folders with optional recursion (-z -A)
  • obeys sa5so.cfg settings preventing the creation of separate archives; includes a sample sa5so.cfg that lists all available ciphers; supports multiple key recovery agents via the sa5so.cfg file
  • properly handles files larger than 4GB on Solaris systems
  • adds key history support for by allowing users to specify a private key path with -d
  • supports PKCS#7 files (.p7b, .p7c) as arguments to -e
  • changes the way -R works: CRL checking is still enabled, but will no longer fail if it cannot locate a CRL for a particular issuer; to require CRLs at all levels, add USECRLS=1 to the sa5so.cfg file
  • allows -I and -R to use the same folder: their respective index files have been renamed 'caindex' and 'crlindex' allowing them to reside in the same directory
  • adds support for using 'stdin' and 'stdout' to make the command line behave as a UNIX-like filter (supported on all platforms)
  • supports an additional -w flag (-w3) that will output just the filenames that are contained in an encrypted archive
  • supports combining the zap operation with encrypt or decrypt operations to remove plaintext/ciphertext in one operation
SecretAgent 5.7.1.4
  • provides improved zap performance on UNIX systems
SecretAgent 5.7.1.3
  • includes a new flag to the -i option: -i2 will cause an error to occur if the user says no when prompted to overwrite a file
SecretAgent 5.7.1.2
  • allows a PKCS #7 file to be supplied to -e as a recipient certificate: the first acceptable certificate in the PKCS #7 file is used and all other certificates in the file are ignored
  • corrects a defect in the base64 encoding of output files: output is now padded to ensure it is a multiple of 4 bytes.
SecretAgent 5.7.1
  • supports either filename or filename.cer in the -e operation
  • properly includes the subject key identifier extension as the hash of the public key rather than the .kyp filename
  • checks certificates supplied to the -e operation for proper key usage and validity; use -n to revert to old behavior
  • discards inappropriate certificates when creating PKCS#12 files
  • applies the -l switch correctly
  • adds support for reading the password from the SA5PWD environment variable
  • can create PKCS#12 files from base64 encoded certificates
  • displays embedded extensions when inspecting CRLs or certificate requests
  • includes the ability to inspect a SecretAgent archive (-w1 filename.sa5)
  • correctly prompts for passwords on UNIX systems
  • supports the creation of CMS (RFC 3369) formatted archives
  • adds the ability to create a certificate request from an existing certificate and private key (-x -s)
  • supports PKCS#12 files with 1 or more private keys
  • supports PKCS#12 files with CRLs
  • provides improved zap information
  • masks passwords when decrypting self-decrypting archives
  • no longer prompts for a password when the -g option is specified without the -o option
  • displays informative messages when a user attempts to perform an operation prohibited by the sa5so.cfg file
  • provides improved error messages and reporting
  • supports PKCS#12 files with either .p12 or .pfx extensions
  • supports naming self-decrypting archives with either .exe or ._xe
  • supports enveloped signatures
  • supports multiple output platforms for self-decrypting archives
  • supports prompting before overwriting files (-i)
SecretAgent 5.6.0
  • Utilizes ISC's FIPS 140-1 Level 1 Validated CDK7
  • displays the SHA-1 fingerprint of certificates when inspecting
  • adds the -H option to hash files
SecretAgent 5.5.1
  • improves command line argument checking
  • correctly determines that file.cer.sa5 is an encrypted file rather than a certificate during decryption
  • correctly returns a non-zero value when failing to create a PKCS#7 file
  • because the first certificate in the input file could not be located
  • deprecates the -v option for decrypt and verify or verify only; use -s
  • instead
  • correctly uses sa5cli when displaying the help information on Windows systems
  • outputs signature algorithm information when inspecting certificate
  • requests
  • exits gracefully when a user attempts to create a self-decrypting archive without a password
  • no longer writes/overwrites the certificate file prior to checking for the existence of the private key file during key generation
  • displays proper signature algorithm with inspecting ECC US-B type certificates
Installing on SA 6.2.4 and CSPid on 64-bit CentOS 6.4

Assuming a clean, out-of-the-box CentOS setup (using only VMware's easy install default options), the following command will properly install the support library required by SecretAgent CLI 6.2.4:

# yum install libstdc++.i686

NOTE: All SA6API packages support the same command line syntax as the identically numbered release of the SA6CLI. For example, if you need documentation on the syntax supported by the sa5cli() entry point in each of the linkable libraries distributed with SA6API 6.2.4, consult the 6.2.4 SA6CLI man page.