Entrust Authority™

Command Line Utility

Release notes

Release 6.1
June 2007

Document issue: 1.0
Document release: June 2007

Welcome to Entrust Authority Command Line Utility Release 6.1.

This document provides information about Command Line Utility. Browse through the topics below to find out about features, limitations, platform and operating system requirements, and known issues for this release.

Command Line Utility overview  [top]

The Command Line Utility 6.1 is for users who regularly use Microsoft Windows® Command Prompt or UNIX prompt, or for users who develop automated tasks with batch files or shell scripts.

The program allows users to perform secure operations, decrypt operations, user operations, and view help information. It also gives users the ability to create a Personal Address Book (PAB) and manipulate recipient lists.

System requirements  [top]

Microsoft Windows®

To use all the features of this product, your computer must meet or exceed the following platform and operating system requirements:

UNIX

This Entrust Toolkit product is supported on the following UNIX platforms with one of the compiler/operating system configurations listed:

Note:
This product is FIPS 140-1 level 2 compliant and has received CC EASL-3 certification.

Platforms no longer supported

The following platforms are not supported in this release:

Compatibility support

This release of the Toolkit supports the following Entrust products:

Documentation requirements

To view the PDF documentation, ensure that you have Adobe® Acrobat® Reader 4.0 or later installed on your computer.

Installing this release  [top]

The Command Line Utility is available for download from TrustedCare as a stand-alone product.

To install this release, perform the following tasks.

Microsoft Windows®

  1. Uninstall the previous version of this Toolkit by running the UNWISE.EXE file located in the root directory.
  2. Browse to the Software Downloads page on the Entrust TrustedCare Online Web site.
  3. Under Entrust Authority Toolkits, find the 6.1 download entry for "Entrust Command Line Utility ) ".
  4. Download the executable file to a temporary directory.
  5. Run entcmd-6_1-win.EXE. By default, the Toolkit installs under c:\Program Files\EntrustToolkit\ENTCMD.

UNIX

  1. Copy the package to your chosen directory, for example,
    /local/entrust/&agt;
  2. Decompress and untar the package using the command
    zcat | tar xvf -.
  3. Use the commands chown and chgrp with flag -R to change the owner and group attributes of the directory recursively if necessary.
  4. Check that the permissions of the directory and its contents match your requirements.
Note:
Install the documentation separately. Documentation is available from the Entrust TrustedCare Web site.

Backwards compatibility with Entrust/Entelligence™ Command line syntax  [top]

This section describes the migration of the previous syntax available with the Entrust/Entelligence Command Line syntax, to the new syntax available in this release of the Command Line Utility. The previous syntax for all existing commands is supported for backwards compatibility.

Securing operations

Existing Syntax New Syntax
-p -ascii
-c -compress
-d -delete
-e -encrypt
-f -overwrite
-s -sign
-t -timestamp
-l <encryption_algorithm> -algorith algorithm-name
<profile_name> -epf profile-path
-a <archive_filename> -directory output-directory
-n -offline
-r <recipient_list_name> -list recipient-list-name
  -dn dn
-o <output_directory> -output output-file-name
Filename(s) Filename(s)

Decryption operations

Existing Syntax New Syntax
-d -delete
-f -overwrite
-v -verbose
  -timestamp
<profile_name> -epf profile-path
-offline -offline
-o <output_directory> -directory output-directory

User operations

Backwards compatibility is not applicable for any of the User operations. This is a new feature available for the first time in this release of the Command Line Utility.

Address Book operations

Existing Syntax New Syntax
  -add
  -base search-base
  -delete
  -dir
  -directory export-directory
  -dn dn
<profilename> -epf profile-path
-x -export
  -file dn-file-path
  -key keyfile-path
  -list recipientlist-name
  -name common-name
-n -offline
  -pab
  -replace
  -returnattribute attribute-name
  -searchbase
  -searchforattribute attribute-name
  -searchstring search-for-string
  -shared
  -shared shared-recipientlist file
  -show

New features  [top]

Note: This release addresses the security issue detailed in Entrust Security Bulletin E06-005.

Updated OS support.
This release adds support for Solaris 10, HP-UX 11i, and AIX 5.3.
4096-bit key length support for algorithms
This release supports 4096-bit encryption and signature key lengths. Using key lengths of this size provides you with enhanced security over a longer period. For example, NIST is formally recommending the use of 2048-bit keys for any document that is to be kept for more than 7 years in every civilian US Federal agency.
SHA-256 handling algorithm support
This release supports the use of the SHA-2 (SHA-256) hashing algorithm within Security Manager. This algorithm provides you with enhanced security over a longer time period. For example, any signature generated using RSA-2048-bit algorithm should also use SHA-256 as a minimum key length.
Enhanced certificate path validation
The Toolkit supports enhanced certificate path validation in order to be compliant with NIST's Public Key Interoperability Test Suite. For the associated press release, see http://www.entrust.com/news/2004/archive2004_05_12_04.htm?entsrc=eds70_theme. For more information on this feature, refer to http://csrc.nist.gov/pki/testing/x509paths.html.
Subordinate CA key and policy update
When you have a hierarchy of Certification Authorities (CAs), you may need to update the CA keys for a subordinate CA. The reasons for updating a subordinate CAs keys are the same as for updating the root CA’s keys—for instance when the CA is nearing the end of its private key usage period, or if the subordinate CA key has been compromised. Also, you may want to update the subordinate CA key to update the subordinate CA policy.
However, the process for updating a subordinate CA is different from that for the root CA. For instance, it is not necessary to create link certificates, since the root of trust is in the root CA. Instead, Security Manager creates cross-certificates for the subordinate signed by its immediate superior in the hierarchy. Because it is an offline process, it is similar to the subordinate CA initialization process.
This release adds support for updating subordinate CA keys and policies. For example, the Toolkit supports the Entrust Authority Security Manager 7.x subordinate CA key roll functionality. For more information on subordinate CA key and policy management and how to set up your applications, refer to the Security Manager documentation.
Support for cross-domain clients
The Toolkit now supports cross-domain clients. This type of configuration allows Entrust client applications to retrieve end-user and CA data from multiple domains in an Active Directory environment.
Ability to set CRL usability after expiration
When operating online, CRLs are trusted up until their expiry date. The Toolkit then attempts to retrieve a new one, but if it cannot find one, the CRL is still usable for another 24 hours or 100% of the CRL lifetime, whichever is less. In this release, a new client setting named CRLGracePeriod is added to control this 100% value. Add this setting to the entrust.ini file and set it to a value between 0 and 100%.
Support for public certificates on tokens
You can now write certificates to the public area of a token (smart card). To configure the Toolkit for this feature, add a ReadableTokenCerts=1 setting to the entrust.ini file. You can also configure this feature using a boolean client-side setting on the Security Manager Administration called Public Token Certs.
Multi-byte character support for roaming usernames
The Toolkit now supports multi-byte characters for roaming usernames.
Support for token secure key transfer
This release supports the new client policy (id-nsn-cs-entrustProtectKeyTransfer) which when true enforces that private key transfers to tokens are protected using encryption. To configure this feature, refer to your Security Manager documentation.
Note
Not all tokens support this operation. Before enabling this feature, check to ensure your tokens do.
As part of this feature, the Toolkit has a new SK error code: SK_CRYPTOKI_KEY_TRANSFER_NOT_SUPPORTED = -72.
Enhanced post-login directory failover capabilities (1-28162950)
This release enhances current directory failover functionality to provide failover capabilities when attempting any directory operation, not just during user login. If the primary directory specified in the entrust.ini file is not available for a directory operation, the application will attempt to connect to the next available directory in the list. For more information about setting up failover, refer to Security Manager documentation.
Ability to disable creation of a token spillover file
This release includes a client-side setting called allowTokenSpilloverFile that you can use to disable *.apf file generation. The benefit of this feature is that information that is normally kept in the *.apf file is written to the token. This allows you to use the token on any machine without copying the *.apf file. For more information on using this setting, refer to the "Using smartcards section" of the Entrust Desktop Solutions 7.0 Administration Guide.
Triple-DES EPF protection support
This release allows you to encrypt the EPF using the Triple-DES algorithm. To enable this algorithm, add the client setting "Algorithm for profile protection" to the master.certspec file. For more information, refer to the "Setting up your users' policy certificates" section of the Entrust Desktop Solutions 7.0 Administration Guide.
Enhanced wildcard character support
ENTCMD now supports wildcards for signing and encryption operations on files. For example, rather than specifying each file in a directory to be processed, you can now simply use *.* to process all files.
Forced password change for token users (1-21673105)
If an administrator sets the password expiry policy in the client-side settings on the PKI, token users will receive a "password expired" error message on first login. This feature allows administrators to force a new or recovered token user to reset their password on initial login.
Kerberos authentication to the directory
The following entrust.ini settings control the authentication method:

[Directory Connection Settings]
AuthMethod=
AuthMethodFallback=

The existing authentication method AuthMethod=WinAuth will now attempt to negotiate Kerberos or NTLM authentication with the directory instead of using NTLM only. If AuthMethod=WinAuth and AuthMethodFallBack=1 are both specified in the entrust.ini file, and if authentication with Kerberos and NTLM has failed, anonymous binding to the directory will be attempted.  By default, AuthMethodFallback is set to "0" and fallback will not happen.
Performance enhancements for certificate path validation
For these enhancements to take effect, CA certificate and cross-certificate caching, CRL and ARL caching, and user certificate caching must be enabled.

After searching the directory for particular CA certificates or cross-certificates, any certificates that are found are cached. Subsequent requests for these same certificates will only result in a directory search if a given period of time has expired. This period of time is controlled by the following new entrust.ini setting:

[Entrust Settings]
CrossCertCACacheLifeTime=

The value for this setting is a period of time, specified in seconds. If not specified, the default value is 7200 seconds (2 hours). A non-zero positive value will override the default value.

The following entrust.ini setting controls the maximum number of CA certificates and cross-certificates that are written to the cross-certificate cache (.xcc) file:

[Entrust Settings]
CrossCertCACacheSize=

If not specified, the default value is 100. If the specified value is greater than 100, it will override the default value. This setting does not impact the size of the memory cache.

Fixed in this release  [top]

The following known issues and limitations have been resolved for this release of Command Line Utility.

Internal certificate validation source order change
When validating a certificate that is imported to the user's address book, the validation will return the result as valid without going through X500 certificate path validation process.
User login and user creation fail if the certificate path contains CA certificates or cross-certificates with no keyUsage extension present.
This issue is fixed in this release.
User creation with a critical extended key usage extension fails
Creating a user whose certificate specification included a critical extended key usage extension failed with the error message "(-11526) Certificate returned by CA did not verify". This issue is fixed in this release.
Certificate validation with critical extended key usage extension fails
When a certificate contained a critical extended key usage extension, validating the certificate failed with the error message "(-265) The certificate contains an unknown critical extension type". This issue is fixed in this release.
Logging readability improvements
The error message "-1570 Attribute was not found." is no longer logged at normal logging levels. Some duplicate logs related to certificate validation were eliminated. These changes improve the readability of the logs.
Revocation reason inconsistency in with multiple cross certified CAs
In an environment with multiple cross-certified CAs, validation of a revoked certificate did not always return the same error. The error changed depending on the CA to which the logged in user belonged. The error returned was not necessarily related to the actual status of the revoked certificate. With this fix, the error indicates the actual status of the certificate.
Time lag adjustment
The time difference allowed between a client and a CA is now set to 2 hours and 5 minutes, instead of 2 hours.
Slow CRL caching
If user certificates do not have a cRLDistributionPoint extension or the first name in the cRLDistributionPoint extension is pointing to a large combined CRL, CRL caching will be slow.

To speed up CRL caching, a new binary CRL cache file format is now supported. The following entrust.ini settings control which CRL cache file format is used:

[Entrust Settings]
MaxCrlCacheSize=
DisableCrlCacheThreshold=

MaxCrlCacheSize specifies the maximum size of a CRL, in kilobytes, that will be stored in the old CRL cache file format. Any CRL larger than the specified value will be stored in the new CRL cache file format. Each CRL stored using the new format is stored as a separate file in the same directory as the other Entrust support files. If MaxCrlCacheSize is set to 0, all CRLs are stored in the new CRL cache file format. If MaxCrlCacheSize is not specified, the default value is 50 kilobytes.

If DisableCrlCacheThreshold is set to 1, use of the new CRL cache file format is disabled, and all CRLs are stored in the old CRL cache file format. Note that th new CRL cache file format is disabled regardless of the value of MaxCrlCacheSize.

The old format CRL cache files are named <Profile Path>\profileName.crl and <Profile Path>\profileName.arl. CRLs that are stored using the new CRL cache file format are stored in separate files named (<Profile Path>\profileName.crl1, <Profile Path>\profileName.crl2 ... <Profile Path>\profileName.crl(N)), where (N) is the number of CRLs larger than MaxCrlCacheSize.

Note: The size comparison for a CRL is approximate. A CRL up to 1 Kb smaller than the MaxCrlCacheSize may be stored in the new CRL cache file format.
Protected key transfer improvements
This release contains improvements for protected key transfer. When using a FIPS-compliant token and a PKCS #11 driver that supports the mechanisms required for protected key transfer, decryption private keys are protected using encryption while they are being transferred from Entrust client software to the token. FIPS mode can be enabled with tokens, provided that the tokens are FIPS compliant and that the PKCS #11 driver supports the mechanisms required for protected key transfer.
Login delays
Users with a Root of Trust that had its keys rolled over multiple times, or a Root of Trust that was cross-certified with many CAs or subordinate CAs, suffered a delay when logging in to Entrust. This release fixes this problem by optimizing how caches are used.
Subordinate CA validation fix for CRL Distribution Point (CDP) with LDAP URI
This fix provides a subordinate CA validation fix when deploying a CRL Distribution Point (CDP) with LDAP URI specifiers, and makes Authority Revocation List CDP/Issuing Distribution Point matching more flexible.
Revoked cross cert causes validation errors
Formerly, if a cross-certificate was revoked or expired and a new cross-certificate was re-issued to the same target CA (with same CA name and CA key) by a host CA, users from the host CA domain could validate the certificates issued by the target CA. This release fixes this problem.
Multiple path certificate validation
When validating a certificate, if more than one path exists to the target certificate, an attempt will be made to validate each path until a valid path is found.
Client-side cert validation parameters
The values of three client-side settings are now used when validating a certificate. They are "Do not process policy mappings", "Require Policy", and "Do not process any Policy". Prior to this patch these settings were assumed to be false, and so certificates that are deemed untrusted with this patch may have been trusted without it. Data may have been encrypted and signatures may have been verified based on this false assumption. Other Entrust products, and earlier versions of this product, are not affected by this issue.
Search filter in referrals failed
Previously, you could not return search filters in the referrals. This release resolves this issue.
Original password was not added to the password history list
In previous releases, the password used when creating the user's EPF was not added to the password history list. The original password is now included in the password history.
User signing or verification key expiry date was not checked in offline mode
Previously, user signing or verification key expiry dates were not checked during offline login, nor during signing operations in offline mode. This allowed users to login offline and sign data with expired signing or verification keys.
Entrust Toolkits now check signing or verification key expiry dates during offline login and during each signing operation. If offline login or offline signing is attempted with an expired key or certificate, the Toolkit prevents the operation and generates an error indicating the operation failed due to expired credentials.
Enhancements to cross-certification functionality for hereditary or subordinate CAs
This release contains multiple enhances to the cross-certification capabilities for hereditary and subordinate CAs. Among the issues resolved were:
The application crashed when attempting to verify version one CRLs (1-25095664)
This issue is resolved in this release.
The [Protected] section of the profile was not written to the token during a recovery operation (1-22901775)
This release writes the [Protected] section to the token during recovery.
Both token user's key pairs were updated unnecessarily with automatic key roll (1-27446301)
For token users with automatic key roll, when either the signing or encryption key expired, both key pairs were updated. In this release, only the expired key pair is updated.
Attempting to perform a DN change on a roaming user with a PAB in the directory failed (1-29949901)
This release resolves this issue.
The password was reset when invoking a create profile function on a token user set for profile recovery
The password was reset to an unknown value when invoking a create profile function on a token user set for profile recovery. This release resolves this issue.
Toolkit applications hung when updating a user profile update following a CA key update
This release resolves this issue.
LDAP failures caused Toolkit applications to hang
LDAP failures could cause Toolkit applications to hang, due to the use of blocking sockets for LDAP connections. LDAP connections now use non-blocking sockets.
A memory leak allowed the certificate cache to grow too large resulting in an application crash
This release fixes the leak and allows restricting the certificate cache size using the CertificateCacheSize parameter in the entrust.ini file.
Inconsistent handling of token key history
If, during a key update, the smart card reported insufficient memory, the Toolkit removes the keys from the key history until enough memory is available to complete the key update. The last key written is the first one removed.
In previous releases, keys were written to the card in random order, and therefore removed randomly. This release modifies the algorithm to write the key history to the card in chronological order - from most recent to oldest. Should keys be removed to free up memory, the oldest keys are removed first.
Token key length limitations rendered the card unusable
When an Entrust user is recovered to a smart card, the user's key history is retrieved from the CA and put in the smart card and also into the user's key spillover file (*.apf file). All keys are put into the spillover file. As for the smart card, the most recent key is put in, as well as whatever earlier keys fit.
Previously, the Toolkit did not consider whether or not the particular smart card being used could support a given key length before trying to put a key on the card. In the case that an unsupported key length was being put on the card, a silent fatal error occurred that rendered the card unusable. This release resolves this issue.
DN change failed for users accessed using a directory referral
This release resolves this issue.
Specifying an incorrect PIN during create or recover operation resulted in an incorrect error
When a create or recover operation occurred to a cryptoki token, and the PIN was specified incorrectly, the returned error code was SK_UNBLOCK_PIN_REQUIRED. This was not the correct error. In this release, the correct error code, SK_PASSWORD_INCORRECT, is returned.
Token users ended up performing all SHA-1 hash operations on the device
A cryptoki token user would use the token device to perform all hashing operations, if the device supported the operation. For example, CKM_SHA_1, the PKCS #11 mechanism for SHA-1, is supported on almost every token device, so a token user would end up performing all SHA-1 hash operations on the device. All hashing is now done in software.
Incorrect revocation reason returned for revoked users on a subordinate CA
Querying the revocation reason for revoked users on a subordinate CA incorrectly returned "(-3809) Certificate was revoked for an unspecified reason." In this release the specific revocation reason is returned, such as "(-3806) Certificate was revoked because it was superseded".
Old private signing key was not removed from the smart card during user recovery (1-18805607)
In this release, all old data is removed from the card during profile recovery.

Known issues  [top]

This section describes the known issues in this release of Command Line Utility.

Network time synchronization
Install network time synchronization software (for example, a product that implements Network Time Protocol) on machines that you plan on developing and deploying applications based on Entrust Toolkit libraries.
Failure to ensure that server or client-based machines are running with the local time synchronized with the PKI and with the correct timezone can result in errors when logging in or performing key management and other operations. Correct functioning of certificate validity checks, revocation checks, and key management protocols are all dependent on the PKI and clients all having synchronized time. An inconsistent time setting can result in components not trusting each other when they should be doing so. Note that if an inconsistent time setting is present, it will not result in components of a PKI accidentally trusting one another when they should not.

Limitations  [top]

This section describes the limitations for this release:

Working Offline
Working offline means using the Command Line Utility while you are not connected to the Directory. The Command Line Utility uses the Directory when verifying digital signatures, and ensures that you do not encrypt for recipients whose certificates are no longer valid. (For example, a person's certificate may no longer be valid, or in Entrust terms "revoked" if they have left the organization, changed their name, or if their certificates are no longer trusted.) If you choose to work offline, Entrust will not be able to connect to the Directory to make the proper security checks.
To minimize the possibility of encrypting for revoked recipients, you should always be connected to the Directory.
If you choose to work offline you will only be able to secure files for:
Once your network connection has been re-established, make sure you re-verify the signatures that you verified while you were working offline.

Deprecated features  [top]

This section describes any features that were removed in this or a previous release.

Support for PKCS #11 version 1 removed
The Toolkit no longer supports the PKCS #11 version 1 standard, only PKCS #11 version 2.
Deprecation of support for signing using MD2 algorithm
Release 6.0 no longer supports signing with the MD2 algorithm. However, you can still verify MD2 signatures for backwards compatibility with other applications. Entrust recommends updating your applications to use another, more secure signature algorithm.

File locations  [top]

The following table provides a list of the subdirectories and the files installed with your Utility.

File locations and descriptions
Directory
   File Name 		Description
ENTCMD Root installation directory (typically C:\Program Files\ EntrustToolki)
   commands.txt List of all the available commands and their syntax.
   license.txt License Agreement.
    entcmd.exe Program executable for running commands.
    entcmdrs.dll Library file for this utility.
    entcmd_relnotes.html Release notes.
   INSTALL.LOG Log file containing information on the installation procedure. If you experience issues installing this Toolkit, refer to this file for error information.
   UNWISE.EXE Uninstaller executable.

© 2007 Entrust. All rights reserved.

Published in Canada.

Entrust is a trademark or a registered trademark of Entrust, Inc. in certain countries. All Entrust product names and logos are trademarks or registered trademarks of Entrust, Inc. in certain countries. All other company and product names and logos are trademarks or registered trademarks of their respective owners in certain countries.

The information is subject to change as Entrust reserves the right to, without notice, make changes to its products as progress in engineering or manufacturing methods or circumstances may warrant.