Contents Ftp://ftp.software.ibm.com/software/webserver/appserv/library/v61/ihs/GSK7c_Capi Cmd_User Guide GSK7c Capi Cmd User
User Manual: ftp://ftp.software.ibm.com/software/webserver/appserv/library/v61/ihs/GSK7c_CapiCmd_UserGuide
Open the PDF directly: View PDF .Page Count: 72
IBM Global Security Kit
GSKCapiCmd User’s Guide
GSKit Version 7
Edition 12 March 2007
(C) Copyright International Business Machines Corporation 2005-2007. All
rights reserved.
U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted
by GSA ADP Schedule Contract with IBM Corp.
Note: Before using this information and the product it supports, read the
information in Appendix 3. Notices.
2
Contents
Preface............................................................................................................................4
Chapter 1.
Using The GSKCapiCmd Program........................................................7
GSKCapiCmd command line syntax .........................................................................8
Chapter 2.
Key Database Commands ......................................................................9
Create Key Database..................................................................................................9
Delete Key Database................................................................................................11
Change Password for Key Database ........................................................................12
Stash the Password for Key Database......................................................................14
List Supported Key Databases .................................................................................15
Convert Key Database .............................................................................................15
Display Key Database Password Expiry..................................................................17
Chapter 3.
Certificate Commands .........................................................................19
Create a Self-Signed Certificate...............................................................................19
Add a Certificate ......................................................................................................22
Delete a Certificate ..................................................................................................23
Display Details of a Certificate................................................................................25
Export a Certificate ..................................................................................................26
Receive a Certificate ................................................................................................28
Import a Certificate ..................................................................................................29
Extract a Certificate .................................................................................................31
List Details of Default Certificate............................................................................33
Set Default Certificate..............................................................................................34
List Certificates........................................................................................................35
Modify Certificate....................................................................................................37
Sign a Certificate......................................................................................................38
Chapter 4.
Certificate Request Commands............................................................41
Create a Certificate Request.....................................................................................41
Delete Certificate Request .......................................................................................43
List Certificate Request Details ...............................................................................44
Extract Certificate Request ......................................................................................46
List all Certificate Requests .....................................................................................47
Re-create Certificates Requests ...............................................................................48
Chapter 5.
Random Password Generation.............................................................51
Create a Random Password .....................................................................................51
Chapter 6.
Help Commands...................................................................................53
Chapter 7.
Version Commands..............................................................................54
Chapter 8.
Error Codes and Messages...................................................................55
Appendix 1. CMS Key Database..............................................................................61
Appendix 2. A Simple Example ...............................................................................64
Appendix 3. Notices .................................................................................................70
3
Preface
This manual is intended for network or system security administrators who have installed
GSKit and want to use the GSKCapiCmd program to modify CMS or PKCS11 key databases.
This manual assumes the reader is familiar with the GSKit product range and the functionality
of the CMS key database.
Before continuing to read this manual ensure you have read and understood the following
prerequisite readings. This will ensure that you understand the required concepts and terms
used throughout the manual:
•
•
Appendix 1 of this manual, “CMS Key Databases”.
Appendix 2 of this manual, “A Simple Example”.
Please ensure that you read all of the identified readings before you continue with this
manual.
How this book is organized
This manual contains the following sections:
•
•
•
•
•
•
•
•
•
•
•
Chapter 1, “Using the GSKCapiCmd Program”, on page 6. This chapter contains general
information about the GSKCapiCmd program.
Chapter 2, “Key Database Commands”, on page 8. This chapter looks at the different
commands that are available to the GSKCapiCmd program for CMS key databases.
Chapter 3, “Certificate Commands”, on page 17. This chapter looks at the different
commands that are available to the GSKCapiCmd program for managing certificates.
Chapter 4, “Certificate Request Commands” on page 38. This chapter looks at the different
commands that are available to the GSKCapiCmd program for managing certificate requests.
Chapter 5, “Random Commands”, on page 48.
Chapter 6 “Help Command”, on page 50.
Chapter 7 “Version Command”, on page 51.
Chapter 8 “Error Codes and messages”, on page 52.
Appendix 1, “CMS Key Databases”, on page 58.
Appendix 2, “A Simple Example”, on page 61
Appendix 3, “Notices”, on page 67
Contacting software support
Before contacting IBM Tivoli Software Support with a problem, refer to the IBM Tivoli Software
Support site by clicking the Tivoli support link at the following Web site:
http://www.ibm.com/software/support/ If you need additional help, contact software support by using
the methods described in the IBM Software Support Guide at the following Web site:
http://techsupport.services.ibm.com/guides/handbook.html The guide provides the following
information: Registration and eligibility requirements for receiving support v Telephone numbers,
depending on the country in which you are located v A list of information you should gather before
contacting customer support
Conventions used in this book
The following typeface conventions are used through out this manual:
Bold: Draws emphasis to a key word, indicating that the user needs to take note as the word will be
used at a later stage. In relation to the options of each command a bolded value indicates the default
value for that option.
4
Italic: Non-specific command line options or identifiers.
Symbol conventions
[ ] - Identifies an option that is optional, if an option is not surrounded by this style of brackets the
option is required.
| - Indicates an “OR” relationship between the options on either side of it.
{} – Identifies mutually exclusive set of options.
Operating system differences
This book uses the UNIX convention for specifying environment variables and for directory notation.
When using the Windows command line, replace $variable with %variable% for environment
variables and replace each forward slash (/) with a backslash (\) in directory paths. If you are using the
bash shell on a Windows system, you can use the UNIX conventions.
Acronyms
The following is a list of acronyms that are used throughout this manual.
CA
CMS
FIPS
GSKit
ICC
IE
-
Certificate Authority
Certificate Management System
Federal Information Processing Standards
Global Security Kit
IBM Crypto for C
Internet Explorer
Revision History
Revision Description
On Date
Refer to...
First draft of document
11/08/2004
Anthony Ferguson
Updating document with
additional information
24/08/2004
Anthony Ferguson
Updating the document with 3/11/2004
additional information.
Anthony Ferguson
Corrected a number of error 2/12/2004
in the document after a
review.
Anthony Ferguson
Updated a number of errors
after an @sec review
21/12/2004
Anthony Ferguson
Adding the random
password generation
information
7/1/2005
Anthony Ferguson
Correcting some minor
errors.
24/01/2005
Anthony Ferguson
Adding important warning to 14/02/2005
ensure quotes are used for all
commands
Anthony Ferguson
Addressing atsec comments
28/02/2005
Alex Hennekam
Adding the email and dc
11/08/2005
Anthony Ferguson
5
attributes to the DN tags
Adding the –sernum tag to
25/08/2005
the certificate sign command
Anthony Ferguson
Adding the –expiry action
16/02/2006
Anthony Ferguson
Adding pfx documentation
for certificate import and
export commands
10/04/2006
Anthony Ferguson
Adding additional error
codes to Chapter 8
27/04/2006
Anthony Ferguson
Adding newly supported
SHA algorithms
29/06/2006
Anthony Ferguson
Updating required fields for
DN tags
10/07/2006
Kai Gorman
Adding error codes 232 and
233
24/07/2006
Kai Gorman
Some corrections to
argument lists
12/March/2007
Simon McMahon
6
Chapter 1. Using The GSKCapiCmd Program
GSKCapiCmd is a tool that can be used to manage keys, certificates and certificate
requests within a CMS key database. The tool has all of the functionality that GSKit’s
existing java command line tool has except that GSKCapiCmd supports CMS and
PKCS11 key databases. If you are intending to manage key databases other than CMS
or PKCS11 you will need to use the existing java tool.
GSKCapiCmd can be used to manage all aspects of a CMS key database. The
following chapters go into detail for each of the functions supported by
GSKCapiCmd.
The advantage of using this tool over the existing one is that GSKCapiCmd does not
require java to be installed on the system.
GSKCapiCmd uses some encoding rules, and implements aspects of certain RFC’s
and standards. While it is not strictly necessary for users to have a full understanding
of these items in order to use this utility, those wishing to learn more should examine
the following resources:
http://asn1.elibel.tm.fr/en/standards/index.htm
Basic Encoding Rules (BER)
BER encoding is defined in the specification ITU-T Rec. X.690 (2002).
Distinguished Encoding Rules (DER)
DER encoding is defined in the specification ITU-T Rec. X.690 (2002).
http://www.faqs.org/rfcs
PKCS#10
RFC 2986: PKCS #10: Certification Request Syntax Specification, Version 1.7,
November 2000
X.509
RFC 3280: Internet X.509 Public Key Infrastructure - Certificate and Certificate
Revocation List (CRL), obsoletes RFC 2459, April 2002.
http://www.rsasecurity.com/rsalabs/
PKCS#11
Cryptographic Token Interface Standard
7
PKCS#12
PKCS 12 v1.0: Personal Information Exchange Syntax, RSA Laboratories, June 24,
1999
PKCS#7
PKCS 7 v1.5: Cryptographic Message Syntax, RSA Laboratories, March 1998
CMS
Appendix 1 offers some additional information concerning the format and use of a
CMS keystore, while appendix 2 takes the reader though a simple example of how
CMS keystores can be used to enable SSL communication between a server and client
application.
GSKCapiCmd command line syntax
The syntax for the GSKCapiCmd program is as follows:
gsk7capicmd
where:
object
Is one of the one of the following:
-keydb
Actions acted on a key database.
-cert
Actions acted on a certificate stored within an identified key database.
-certreq
Actions acted on a certificate request stored within an identified key database.
-random
Generates a random string of characters that can be used as a password for other
commands.
-version
Displays version information for GSKCapiCmd
-help
Displays help for the GSKCapiCmd commands.
action
Is the specific action to be taken on the object.
options Are the options associated with the specified object and task
This manual will go into detail for each particular object, its associated actions, and
what options are available in the following chapters.
8
Chapter 2. Key Database Commands
The key database commands are associated with the -keydb object. This object
supports the following actions:
•
•
•
•
•
•
•
Create a Key Database (-create)
Delete a Key Database (-delete)
Change the Password of an existing Key Database (-changepw)
Stash the Password of an existing Key Database (-stashpw)
List the Supported Key Databases (-list)
Convert an old style CMS Key Database to the updated style of CMS Key
Database (-convert)
Display the expiry date associated with a CMS key databases password
(-expiry)
Each of the following sections goes into detail on how to use each of the key database
commands and what options are available for each command.
Create Key Database
The create command creates a new CMS key database. During the creation process
three files are created. The first file is the certificate key database itself. By standard it
is a good idea to name this file with a .kdb extension (key.kdb). This is not required,
but it is a good idea, it makes easy to identify the file as a key database.
The second file created is used to store certificate requests associated with the key
database. This file is created with the same name as given to the key database but with
a .rdb extension. The third file is used to hold the certificate revocation list used by
the key database; this file has become obsolete and is no longer used. This file is
created with the same name as the key database but this time with a .crl extension.
Once the key database has been created it is populated with a number of pre-defined
trusted certificate authority (CA) certificates. There is no way of preventing this from
occurring. The trusted CA certificates are as follows:
Entrust.net Global Secure Server Certification Authority
Entrust.net Global Client Certification Authority
Entrust.net Client Certification Authority
Entrust.net Certification Authority (2048)
Entrust.net Secure Server Certification Authority
VeriSign Class 3 Public Primary Certification Authority
VeriSign Class 2 Public Primary Certification Authority
VeriSign Class 1 Public Primary Certification Authority
VeriSign Class 4 Public Primary Certification Authority - G2
VeriSign Class 3 Public Primary Certification Authority - G2
VeriSign Class 2 Public Primary Certification Authority - G2
VeriSign Class 1 Public Primary Certification Authority - G2
VeriSign Class 4 Public Primary Certification Authority - G3
VeriSign Class 3 Public Primary Certification Authority - G3
VeriSign Class 2 Public Primary Certification Authority - G3
VeriSign Class 1 Public Primary Certification Authority - G3
Thawte Personal Premium CA
Thawte Personal Freemail CA
Thawte Personal Basic CA
9
Thawte Premium Server CA
Thawte Server CA
RSA Secure Server Certification Authority
Any or all of these CA certificates can be removed from the key database. If you want
to remove any of the certificates look at the delete certificate command in this
manual.
The syntax for creating a CMS key database with GSKCapiCmd is as follows:
gsk7capicmd -keydb -create -db [-pw ] [-type ] [-expire
] [-stash] [-fips] [-strong]
Where:
object -keydb
action -create
options
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –create –db “/tmp/key.kdb” –pw “j\!jj”). Note however
when prompted by gsk7capicmd for a value (for example a password) quoting
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
-db
Fully qualified path name of a key database. A good example of a key
database filename might be /home//keydb.db.
-pw
The password for the key database identified by the –db tag above. If
you want to create a key store without a password simply leave the
-pw tag out of the above command.
-type
The type of the key database to be created. At this stage this tool only
supports the creation of CMS key database. If the tag is left off the tool
will assume that a CMS key database is to be created.
-expire
The number of days before the password for the key database is to
expire. If the tag is left off, the key database password will never
expire. If specified the duration must be from 1 to 7300 days (20
years).
-stash
10
Stash the password for the key database after creation. A stash file is
used as an automatic way of providing a password. When accessing a
key database the system will first check for the existence of a stash file.
If one exists the contents of the file will be decrypted and used as input
for the password. When the -stash option is specified during the create
action, the password is stashed into a file with the name as follows:
.sth.
-fips
This disables the use of the BSafe cryptographic library. Only the ICC
component which must be successfully intialized in FIPS* mode will
be used. If the ICC component does not intialize in FIPS mode then the
gsk7capicmd operation will fail.
* When in FIPS mode the ICC component uses algorithms that have been FIPS 140-2
validated.
-strong
Check that the password entered satisfies the minimum requirements
for the passwords strength. The minimum requirements for a password
are as follows:
•
•
•
•
•
The minimum password length is 14 characters.
A password needs to have at least one lower case character, one upper case
character, and one digit or special character ( eg. *$#% etc, a space is
classified as special characters).
Each character should not occur more than three times in a password.
No more than two consecutive characters of the password should be
identical.
All characters mentioned above are in the standard ASCII printable character
set within the range from 0x20 to 0x7E inclusive.
Delete Key Database
The delete key database command simply deletes the identified key database. When
identifying the key database you simply need to specify the file name of the key
database. The request database (.rdb) and certificate revocation list (.crl) files are
removed automatically during the process. If a stash file was created it is not
removed.
If a password was provided for this command it is used to ensure that the user is
actually allowed to delete the key database. If the password is not correct the key
database is not deleted.
The syntax for deleting a key database with GSKCapiCmd is as follows:
gsk7capicmd -keydb -delete -db [-pw ]
Where:
object -keydb
11
action -delete
options
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –create –db “/tmp/key.kdb” –pw “j\!jj”). Note however
when prompted by gsk7capicmd for a value (for example a password) quoting
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
-db
The fully qualified path name of a key database.
-pw
The password for the key database identified by the –db tag above. The
–pw tag is required if the key database was created with a password. It
is an additional check to ensure that the user deleting the key database
is authorized to do so. If the key database does not have a password the
–pw tag is not required.
If a password is provided and it does not patch the password for the
identified key database the key database is not deleted.
Change Password for Key Database
The change password command allows the user to change the password associated
with the specified key database. When changing the password for a key database, all
key records containing encrypted private key information have the private key data reencrypted. The new password is used as input to create the new encryption key used
during the encryption process.
The syntax for changing the password of an existing key database with GSKCapiCmd
is as follows:
gsk7capicmd -keydb -changepw {-db | -crypto -tokenlabel
} [-pw ] -new_pw [-expire ] [-stash]
[-fips] [-strong]
Where:
object -keydb
action -changepw
options
12
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –create –db “/tmp/key.kdb” –pw “j\!jj”). Note however
when prompted by gsk7capicmd for a value (for example a password) quoting
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
-db
The fully qualified path name of a key database.
-crypto
Indicates a PKCS11 cryptographic device operation, where is the path to the module to manage the crypto device.
-tokenlabel
The PKCS11 cryptographic device token label.
-pw
The password for the key database identified by the –db tag above. If
you want to create a key store without a password simply leave the
-pw tag out of the above command.
-new_pw
The new password for the key database.
-expire
The number of days before the new password is to expire. If the tag is
not specified the key databases password never expires. If specified the
duration must be within the range of 1 to 7300 days (20 years).
-stash
Stash the password for the key database. When the –stash the new
password will be stashed in a file with the filename built as follows:
.sth.
-fips
This disables the use of the BSafe cryptographic library. Only the ICC
component which must be successfully intialized in FIPS* mode will
be used. If the ICC component does not intialize in FIPS mode then the
gsk7capicmd operation will fail.
* When in FIPS mode the ICC component uses algorithms that have been FIPS 140-2
validated
-strong
Check that the password entered satisfies the minimum requirements
for the passwords strength. The minimum requirements for a password
are as follows:
13
•
•
•
•
•
The minimum password length is 14 characters.
A password needs to have at least one lower case character, one upper case
character, and one digit or special character (eg. *$#% etc, a space is
classified as special characters).
Each character should not occur more than three times in a password.
No more than two consecutive characters of the password should be
identical.
All characters mentioned above are in the standard ASCII printable character
set within the range from 0x20 to 0x7E inclusive.
Stash the Password for Key Database
The stash password command takes an existing key databases password and stashes it
to a specified file. The reason that a user would want to stash a password for a key
database is to allow the password to be recovered from the file when automatic login
is required. The output of the command is a single file with the name of the key
database with a “.sth” extension.
The syntax for stashing the password of an existing key database with GSKCapiCmd
is as follows:
gsk7capicmd -keydb -stashpw -db [-pw ] [-fips]
Where:
object -keydb
action -stashpw
options
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –create –db “/tmp/key.kdb” –pw “j\!jj”). Note however
when prompted by gsk7capicmd for a value (for example a password) quoting
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
-db
The fully qualified path name of a key database.
-pw
The password for the key database identified by the –db tag above.
-fips
This disables the use of the BSafe cryptographic library. Only the ICC
component which must be successfully intialized in FIPS* mode will
14
be used. If the ICC component does not intialize in FIPS mode then the
gsk7capicmd operation will fail.
* When in FIPS mode the ICC component uses algorithms that have been FIPS 140-2
validated
List Supported Key Databases
The list supported key databases simply lists all of the key database types that the
GSKCapiCmd supports.
Deleted: . At this stage this command
will only indicate that CMS and PKCS11
key databases are supported.
The syntax for listing the key databases supported by GSKCapiCmd is as follows:
Deleted: [-fips]
gsk7capicmd -keydb –list
Where:
object -keydb
action -list
Convert Key Database
The convert key database command converts an old version CMS key database to the
new version of CMS key database. The latest version of CMS is more secure because
it uses more secure algorithms to secure the contents of the key databases during
creation.
This command requires that you assign a name to the new key database that is
different to the existing old key database. This name cannot be the same as the
existing one. This is to ensure that the old key database is not destroyed until the user
destroys it. Once all testing of the new version key database has been completed the
user can remove the old key database and rename the new key database to the old key
databases name if required.
The syntax for converting a key database to the latest CMS version by GSKCapiCmd
is as follows:
gsk7capicmd -keydb –convert –db [-pw ] –new_db
[-new_pw ] [-preserve] [-strong] [-fips]
Where:
object -keydb
action -list
options
15
Deleted: ¶
options¶
¶
-fips¶
This disables the use of the BSafe
cryptographic library. Only the ICC
component which must be successfully
intialized in FIPS* mode will be used. If
the ICC component does not intialize in
FIPS mode then the gsk7capicmd
operation will fail. ¶
¶
* When in FIPS mode the ICC
component uses algorithms that have
been FIPS 140-2 validated¶
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –create –db “/tmp/key.kdb” –pw “j\!jj”). Note however
when prompted by gsk7capicmd for a value (for example a password) quoting
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
-db
The fully qualified path name of a key database.
-pw
The password for the key database identified by the –db tag above.
-new_db
Fully qualified path name of a new key database to be created during
the conversion.
-new_pw
The password for the key database identified by the –new_db tag
above.
-preserve
When this option is specified during the convert command the newly
created key database will not include any new trusted CA certificates,
it will be identical to the old key database.
If you chose not to include this option the following CA certificates
will be added to the newly created key database:
Entrust.net Global Secure Server Certification Authority
Entrust.net Global Client Certification Authority
Entrust.net Client Certification Authority
Entrust.net Certification Authority (2048)
Entrust.net Secure Server Certification Authority
VeriSign Class 3 Public Primary Certification Authority
VeriSign Class 2 Public Primary Certification Authority
VeriSign Class 1 Public Primary Certification Authority
VeriSign Class 4 Public Primary Certification Authority - G2
VeriSign Class 3 Public Primary Certification Authority - G2
VeriSign Class 2 Public Primary Certification Authority - G2
VeriSign Class 1 Public Primary Certification Authority - G2
VeriSign Class 4 Public Primary Certification Authority - G3
VeriSign Class 3 Public Primary Certification Authority - G3
VeriSign Class 2 Public Primary Certification Authority - G3
VeriSign Class 1 Public Primary Certification Authority - G3
Thawte Personal Premium CA
Thawte Personal Freemail CA
Thawte Personal Basic CA
Thawte Premium Server CA
Thawte Server CA
RSA Secure Server Certification Authority
There is no way of adding just a couple of the CA certificates it is all
or none, but you are able to remove any of them at a later stage.
16
-strong
Check that the password entered satisfies the minimum requirements
for the passwords strength. The minimum requirements for a password
are as follows:
•
•
•
•
•
The minimum password length is 14 characters.
A password needs to have at least one lower case character, one upper case
character, and one digit or special character (eg. *$#% etc, a space is
classified as special characters).
Each character should not occur more than three times in a password.
No more than two consecutive characters of the password should be
identical.
All characters mentioned above are in the standard ASCII printable character
set within the range from 0x20 to 0x7E inclusive.
-fips
This disables the use of the BSafe cryptographic library. Only the ICC
component which must be successfully intialized in FIPS* mode will
be used. If the ICC component does not intialize in FIPS mode then the
gsk7capicmd operation will fail.
* When in FIPS mode the ICC component uses algorithms that have been FIPS 140-2
validated
Display Key Database Password Expiry
The expiry key database command simply displays the date that the password
associated with the identified key database will expire. When identifying the key
database you simply need to specify the file name of the key database.
The syntax for displaying the expiry of the password associated with a key database
with GSKCapiCmd is as follows:
gsk7capicmd -keydb -expiry -db [-pw ]
Where:
object -keydb
action -expiry
options
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –expiry –db “/tmp/key.kdb” –pw “j\!jj”). Note however
when prompted by gsk7capicmd for a value (for example a password) quoting
17
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
-db
The fully qualified path name of a key database.
-pw
The password for the key database identified by the –db tag above. The
–pw tag is required if the key database was created with a password. If
the key database does not have a password the –pw tag is not required.
-fips
This disables the use of the BSafe cryptographic library. Only the ICC
component which must be successfully intialized in FIPS* mode will
be used. If the ICC component does not intialize in FIPS mode then the
gsk7capicmd operation will fail.
* When in FIPS mode the ICC component uses algorithms that have been FIPS 140-2
validated
IMPORTANT: An expiry of 0 means that the password associated with the key
database does not expire.
18
Chapter 3. Certificate Commands
The certificate commands are associated with the -cert object. This object supports the
following actions:
•
•
•
•
•
•
•
•
•
•
•
•
•
Create a self signed certificate in a key store (-create)
Add a certificate to a key store (-add)
Delete a certificate from a key store (-delete)
Display the details of a certificate in a key store (-details)
Export a certificate from a key store to another key store (-export)
Receive a certificate into a key store (-receive)
Import a certificate from a key store to another key store (-import)
Extract a certificate from a key store (-extract)
List the details of the default certificate in a key store (-getdefault)
Set the default certificate in a key store (-setdefault)
List the certificates stored in a key store (-list)
Modify a certificate in a key store (-modify)
Sign a certificate (-sign)
Each of the following sections goes into detail on how to use and what options are
available for each of the identified certificate actions.
Create a Self-Signed Certificate
A self-signed certificate provides a certificate that can be used for testing while
waiting for the officially signed certificate to be returned from the CA. Both a private
and public key are created during this process.
The create self-signed certificate command creates a self-signed X509 certificate in
the identified key database. A self-signed certificate has the same issuer name as its
subject name.
The syntax for creating a certificate in an existing key database with GSKCapiCmd is
as follows:
gsk7capicmd -cert -create {-db | -crypto -tokenlabel } [-pw ] -label -dn [-size ] [x509version <1 | 2 | 3>] [-default_cert ] [-expire ] [-secondaryDB
-secondaryDBpw ] [-ca ] [-fips] [-sigalg]
Where:
object -cert
action -create
options
19
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –create –db “/tmp/key.kdb” –pw “j\!jj”). Note however
when prompted by gsk7capicmd for a value (for example a password) quoting
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
-db
Fully qualified path name of a key database to store the self-signed
certificate.
-crypto
Indicates a PKCS11 cryptographic device operation, where is the path to the module to manage the crypto device.
-tokenlabel
The PKCS11 cryptographic device token label.
-pw
The password for the key database identified by the –db or –tokenlabel
tags above.
-label
Label attached to the certificate. The label is used to uniquely identify
the certificate by a human user.
-dn
The X.500 distinguished name that will uniquely identify the
certificate. The input needs to be a quoted string of the following
format (only CN is required):
CN=common name
O=organization
OU=organization unit
L=location
ST=state, province
C=country
DC=domain component
EMAIL=email address
For Example: “CN=weblinux.Raleigh.ibm.com,O=ibm,OU=IBM
HTTP Server,L=RTP,ST=NC,C=US”
Multiple OU are now supported. Simply add additional OU key\value
pairs to the specified distinguished name. If the OU value requires a
comma (‘,’) it will need to escape it with ‘\\’.
20
For Example: “CN=weblinux.Raleigh.ibm.com,O=ibm,OU=IBM
HTTP Server,OU=GSKit\\, Gold Coast,L=RTP,ST=NC,C=US”
-size
The size of the new key pair to be created. Key size from 512 to 4096,
default 1024.
-x509version <1 | 2 | 3>
The version of X.509 certificate to create, default is 3.
-default_cert
Sets the newly created certificate as the default certificate for the key
database. By default the newly created self-signed certificate is not set
as the default (no). A default certificate in a key database is used when
a specific certificate is not specified during the use of the key database.
-expire
Expiration time of the certificate in days, default 365 days. The
duration is 1 to 7300 days (20 years)
-secondaryDB
A CMS key database used to support the PKCS11 device. A PKCS11
device does not normally have a large amount of space available to
store a lot of signer certificates. The signer certificates are used for the
validation of certificates when they are added to the PCKS11 device.
-secondaryDBpw
Password for the secondary CMS key database supporting the PKCS11
device.
-ca
This tag adds the Basic Constraint extension to the self-signed
certificate. The Basic Constraint extension value will be set to true or
false depending on what value is associated with the tag.
-fips
This disables the use of the BSafe cryptographic library. Only the ICC
component which must be successfully intialized in FIPS* mode will
be used. If the ICC component does not intialize in FIPS mode then the
gsk7capicmd operation will fail.
* When in FIPS mode the ICC component uses algorithms that have been FIPS 140-2
validated
-sigalg
The hashing algorithm to be used during the creation of the self signed
certificate. This hashing algorithm is used to create the signature
associated with the newly created self-signed certificate.
1
To avoid possible timezone issues the actual valid-from time for the certificate will be set one day in
the past.
21
Add a Certificate
The add certificate command stores a CA certificate into the identified key database.
The CA certificate is received as a file with the data encoded as either Base64 (ascii)
or binary. It is important to identify the correct format of the file otherwise the
operation will fail.
The syntax for adding a certificate in an existing key database with GSKCapiCmd is
as follows:
gsk7capicmd -cert -add {-db | -crypto
-tokenlabel } [-pw ] -label -file [-format
] [-trust ] [-secondaryDB
-secondaryDBpw ] [-fips]
Where:
object -cert
action -add
options
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –create –db “/tmp/key.kdb” –pw “j\!jj”). Note however
when prompted by gsk7capicmd for a value (for example a password) quoting
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
-db
The fully qualified path name of a key database.
-crypto
Indicates a PKCS11 cryptographic device operation, where is the path to the module to manage the crypto device.
-tokenlabel
The PKCS11 cryptographic device token label.
-pw
The password for the key database identified by the –db or –tokenlabel
tags above.
-label
Label attached to the certificate.
-file
22
Filename of the certificate to add. If it is “.p7”, “.smime” or “.eml”
then it is assumed to be a pkcs7 encoding. The first cert will take the
‘label’ given, all other certs, if present, will be labelled with their
subject name.
-format
Format of a certificate The default is Base64 encoded ascii, additional
information about base64 encoding can be found in rfc2045 and
rfc3548. The binary format is a binary dump of the DER encoded
certificate structure. For additional information refer to ITU-T Rec.
X.690 (2002) | ISO/IEC 8825-1:2002
-trust
Trust status of a CA certificate, where the default is ‘enable’. When a
CA’s certificate trust status is enabled then that CA certificate is
permitted to be involved in a certificate chain validation. If the CA’s
certificate trust status is disabled then it cannot be used to validate any
certificates. For example if certificate “ABC” is signed by the CA
certificate “VeriSign CA” and “VeriSign CA” is not marked as trusted
the validation of “ABC” will fail.
-secondaryDB
A CMS key database used to support the PKCS11 device. A PKCS11
device does not normally have a large amount of space available to
store a lot of signer certificates. The signer certificates are used for the
validation of certificates when they are added to the PCKS11 device.
-secondaryDBpw
Password for the secondary CMS key database supporting the PKCS11
device.
-fips
This disables the use of the BSafe cryptographic library. Only the ICC
component which must be successfully intialized in FIPS* mode will
be used. If the ICC component does not intialize in FIPS mode then the
gsk7capicmd operation will fail.
* When in FIPS mode the ICC component uses algorithms that have been FIPS 140-2
validated
Delete a Certificate
The delete command simply removes the certificate with the identified label. Once the
delete operation is complete, there is no way of recovering the certificate unless you
add the certificate back into the key database.
The syntax for deleting a certificate in an existing key database with GSKCapiCmd is
as follows:
23
gsk7capicmd -cert -delete {-db | -crypto -tokenlabel } [-pw ] -label [-secondaryDB -secondaryDBpw
] [-fips]
Where:
object -cert
action -delete
options
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –create –db “/tmp/key.kdb” –pw “j\!jj”). Note however
when prompted by gsk7capicmd for a value (for example a password) quoting
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
-db
The fully qualified path name of a key database.
-crypto
Indicates a PKCS11 cryptographic device operation, where is the path to the module to manage the crypto device.
-tokenlabel
The PKCS11 cryptographic device token label.
-pw
The password for the key database identified by the –db or –tokenlabel
tags above.
-label
Label attached to the certificate that is to be deleted.
-secondaryDB
A CMS key database used to support the PKCS11 device. A PKCS11
device does not normally have a large amount of space available to
store a lot of signer certificates. The signer certificates are used for the
validation of certificates when they are added to the PCKS11 device.
-secondaryDBpw
Password for the secondary CMS key database supporting the PKCS11
device.
-fips
24
This disables the use of the BSafe cryptographic library. Only the ICC
component which must be successfully intialized in FIPS* mode will
be used. If the ICC component does not intialize in FIPS mode then the
gsk7capicmd operation will fail.
* When in FIPS mode the ICC component uses algorithms that have been FIPS 140-2
validated
Display Details of a Certificate
The display certificate details command displays the different details associated with
the identified certificate. The details displayed include:
•
•
•
•
•
•
•
•
•
The label of the certificate.
The size of the key associated with the certificate.
The X509 version that the certificate was created.
The serial number for the certificate.
The issuer and subject distinguished names.
The certificate’s validity period.
The fingerprint of the certificate.
The signature of the algorithm used during creation of the certificate.
An indication of the certificates trust status.
If more details for the certificate are required use the –showOID option. This option
displays a more detailed listing of the certificates details.
The syntax for displaying the details for a certificate in an existing key database with
GSKCapiCmd is as follows:
gsk7capicmd -cert -details [-showOID] {-db | -crypto tokenlabel } [-pw ] -label [-secondaryDB
-secondaryDBpw ] [-fips]
Where:
object -cert
action -details
options
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –create –db “/tmp/key.kdb” –pw “j\!jj”). Note however
when prompted by gsk7capicmd for a value (for example a password) quoting
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
25
-showOID
Display a more in depth listing of the certificate.
-db
The fully qualified path name of a key database.
-crypto
Indicates a PKCS11 cryptographic device operation, where is the path to the module to manage the crypto device.
-tokenlabel
The PKCS11 cryptographic device token label.
-pw
The password for the key database identified by the –db or –tokenlabel
tags above.
-label
Label attached to the certificate that is to be displayed.
-secondaryDB
A CMS key database used to support the PKCS11 device. A PKCS11
device does not normally have a large amount of space available to
store a lot of signer certificates. The signer certificates are used for the
validation of certificates when they are added to the PCKS11 device.
-secondaryDBpw
Password for the secondary CMS key database supporting the PKCS11
device.
-fips
This disables the use of the BSafe cryptographic library. Only the ICC
component which must be successfully intialized in FIPS* mode will
be used. If the ICC component does not intialize in FIPS mode then the
gsk7capicmd operation will fail.
* When in FIPS mode the ICC component uses algorithms that have been FIPS 140-2
validated
Export a Certificate
The export command exports a single certificate specified by its label from either a
CMS or PKCS12 key database to another CMS or PKCS12 key database. During this
process no key generation occurs. On successful completion the identified certificate
will be in both the source and destination key databases.
The syntax to export a certificate from an existing key database to another key
database with GSKCapiCmd is as follows:
26
gsk7capicmd -cert -export -db [-pw ] -label [-type ] -target [-target_pw ] [-target_type ] [encryption ] [-fips]
Where:
object -cert
action -export
options
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –create –db “/tmp/key.kdb” –pw “j\!jj”). Note however
when prompted by gsk7capicmd for a value (for example a password) quoting
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
-db
The fully qualified filename of a key database containing the certificate
to exported from. If the supplied filename has an extension of either
“.p12” or .pfx” then it is assumed that it is in PKCS12 format. If it is
“.p7”, “.smime” or “.eml” then it is assumed to be a pkcs7 encoding.
-pw
The password for the key database identified by the –db or –tokenlabel
tags above.
-label
Label attached to the certificate that is to be exported.
-type
The type of the key database to be exported from, default cms.
-target
Destination key database or file that the certificate is to be exported to.
If the supplied filename has an extension of either “.p12” or .pfx” then
it is assumed that it is in PKCS12 format. If the target keystore does
not already exist it will be created.
-target_pw
The password of the destination key database or file.
-target_type
The type of the destination key database or file to be exported to,
default cms.
-encryption
27
The strength of encryption used during the export, default strong. This
tag is no longer used as the export restrictions in the USA have been
eased. This tag is simply added to this command line tool for backward
compatibility reasons; it has no effect on the operation, strong is
always used.
-fips
This disables the use of the BSafe cryptographic library. Only the ICC
component which must be successfully intialized in FIPS* mode will
be used. If the ICC component does not intialize in FIPS mode then the
gsk7capicmd operation will fail.
* When in FIPS mode the ICC component uses algorithms that have been FIPS 140-2
validated
Receive a Certificate
The receive certificate command stores a certificate received from a CA that was
requested to sign a certificate request. The certificate being received can be in either
binary or Base64 encoded ascii. Additional information about base64 encoding can be
found in rfc2045 and rfc3548. The binary format is a binary dump of the DER
encoded certificate structure. For additional information refer to ITU-T Rec. X.690
(2002) | ISO/IEC 8825-1:2002. During the receiving of the certificate, the certificate
is matched to its corresponding certificate request. This certificate request is removed
from the key database as it is no longer needed.
If the certificate request is required after receiving the certificate, you will need to use
the recreate certificate request command that can be found in chapter four of this
manual.
The syntax for receiving a certificate to an existing key database with GSKCapiCmd
is as follows:
gsk7capicmd -cert -receive -file [-format ] { -db | crypto -tokenlabel } [-pw ] [-default_cert
] [-fips]
Where:
object -cert
action -receive
options
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –create –db “/tmp/key.kdb” –pw “j\!jj”). Note however
28
when prompted by gsk7capicmd for a value (for example a password) quoting
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
-file
The file name of the certificate that is to be received, this file can be
either binary or base64 encoded.
-db
The fully qualified path name of a key database.
-crypto
Indicates a PKCS11 cryptographic device operation, where is the path to the module to manage the crypto device.
-tokenlabel
The PKCS11 cryptographic device token label.
-pw
The password for the key database identified by the –db or –tokenlabel
tags above.
-default_cert
Sets the newly created certificate as the default certificate for the key
database. By default the newly created self-signed certificate is not set
as the default (no). A default certificate in a key database is used when
a specific certificate is not specified during the use of the key database.
-fips
This disables the use of the BSafe cryptographic library. Only the ICC
component which must be successfully intialized in FIPS* mode will
be used. If the ICC component does not intialize in FIPS mode then the
gsk7capicmd operation will fail.
* When in FIPS mode the ICC component uses algorithms that have been FIPS 140-2
validated
Import a Certificate
The import command imports certificates from either a CMS or PKCS12 key database
to either a CMS, PCKS12 or PCKS11 key database. During this process no key
generation occurs. On successful completion the identified certificates will be in both
the source and destination key databases.
The syntax for importing a certificate from an existing key database to another key
database with GSKCapiCmd is as follows:
gsk7capicmd -cert -import -db [-pw ] [-label ] [-type ] { -target | -crypto -tokenlabel } [secondaryDB -secondaryDBpw ] [-target_pw ] [target_type ] [-new_label ] [-fips]
29
Where:
object -cert
action -import
options
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –create –db “/tmp/key.kdb” –pw “j\!jj”). Note however
when prompted by gsk7capicmd for a value (for example a password) quoting
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
Deleted: OR¶
¶
gsk7capicmd -cert -import -file
[-pw ] -label [-type
] { -target | -crypto
-tokenlabel } [-secondaryDB secondaryDBpw ] [target_pw ] [-target_type ] [-new_label ]
[-fips]¶
¶
-db
The fully qualified path name of a key database that contains the
certificate that is to be imported from. If the supplied filename has an
extension of either “.p12” or .pfx” then it is assumed that it is in
PKCS12 format. If it is “.p7”, “.smime” or “.eml” then it is assumed to
be a pkcs7 encoding.
Deleted: -file ¶
The fully qualified path name of a
PKCS12 file that contains the certificate
that is to be imported from. ¶
¶
-pw
The password for the key database or PKCS11 cryptographic device
identified by either the -db or -crypto tags respectively.
-label
Label attached to the certificate that is to be imported. If the label tag is
missing from the command line the operation will transfer all
certificates from the source key database to the target key database. If a
certificate in the source key database already exists in the target key
database that certificate is not imported.
-type
The type of the key database to be imported from, default cms.
-target
Destination key database to import the certificate into. If the supplied
filename has an extension of either “.p12” or .pfx” then it is assumed
that it is in PKCS12 format.
-crypto
Indicates a PKCS11 cryptographic device operation, where is the path to the module to manage the crypto device.
-tokenlabel
The PKCS11 cryptographic device token label.
30
-secondaryDB
A CMS key database used to support the PKCS11 device. A PKCS11
device does not normally have a large amount of space available to
store a lot of signer certificates. The signer certificates are used for the
validation of certificates when they are added to the PCKS11 device.
-secondaryDBpw
Password for the secondary CMS key database supporting the PKCS11
device.
-target_pw
The password of the destination key database.
-target_type
The type of the destination key database to be imported to, default cms.
-new_label
The label to be used in the destination key database to identify the
imported certificate.
-fips
This disables the use of the BSafe cryptographic library. Only the ICC
component which must be successfully intialized in FIPS* mode will
be used. If the ICC component does not intialize in FIPS mode then the
gsk7capicmd operation will fail.
* When in FIPS mode the ICC component uses algorithms that have been FIPS 140-2
validated
Extract a Certificate
The extract certificate command simply extracts the certificate data from the key
database and places it into the identified file. If the file does not exist it will be
created. If the file already exists an error indicating this will be returned. The data will
be saved as either base64 encoding or binary.
The syntax to extract a certificate from an existing key database with GSKCapiCmd is
as follows:
gsk7capicmd -cert -extract {-db | -crypto -tokenlabel } -pw -label -target [-format ]
[-secondaryDB -secondaryDBpw ] [-fips]
Where:
object -cert
action -extract
options
31
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –create –db “/tmp/key.kdb” –pw “j\!jj”). Note however
when prompted by gsk7capicmd for a value (for example a password) quoting
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
-db
The fully qualified path name of a key database.
-crypto
Indicates a PKCS11 cryptographic device operation, where is the path to the module to manage the crypto device.
-tokenlabel
The PKCS11 cryptographic device token label.
-pw
The password for the key database identified by the –db or –tokenlabel
tags above.
-label
Label attached to the certificate that is to be extracted.
-target
Destination file that the certificate is to be extracted to.
Deleted: key database or
Deleted: exported
-format
Format of a certificate. The default is Base64 encoded ascii, additional
information about base64 encoding can be found in rfc2045 and
rfc3548. The binary format is a binary dump of the DER encoded
certificate structure. For additional information refer to ITU-T Rec.
X.690 (2002) | ISO/IEC 8825-1:2002
-secondaryDB
A CMS key database used to support the PKCS11 device. A PKCS11
device does not normally have a large amount of space available to
store a lot of signer certificates. The signer certificates are used for the
validation of certificates when they are added to the PCKS11 device.
-secondaryDBpw
Password for the secondary CMS key database supporting the PKCS11
device.
-fips
This disables the use of the BSafe cryptographic library. Only the ICC
component which must be successfully intialized in FIPS* mode will
32
be used. If the ICC component does not intialize in FIPS mode then the
gsk7capicmd operation will fail.
* When in FIPS mode the ICC component uses algorithms that have been FIPS 140-2
validated
List Details of Default Certificate
The list default certificate details simply lists the following details for the default
certificate of the identified key database:
•
•
•
•
•
•
•
•
•
The label of the default certificate.
The size of the key associated with the default certificate.
The X509 version that the default certificate was created.
The serial number for the default certificate.
The issuer and subject distinguished names.
The default certificates validity period.
The fingerprint of the default certificate.
The signature of the algorithm used during creation of the default
certificate.
An indication of the default certificate’s trust status.
The syntax for listing the details for the default certificate in an existing key database
with GSKCapiCmd is as follows:
gsk7capicmd -cert -getdefault -db [-pw ] [-fips]
Where:
object -cert
action -getdefault
options
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –create –db “/tmp/key.kdb” –pw “j\!jj”). Note however
when prompted by gsk7capicmd for a value (for example a password) quoting
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
-db
The fully qualified path name of a key database.
-pw
33
The password for the key database identified by the –db tag above.
-fips
This disables the use of the BSafe cryptographic library. Only the ICC
component which must be successfully intialized in FIPS* mode will
be used. If the ICC component does not intialize in FIPS mode then the
gsk7capicmd operation will fail.
* When in FIPS mode the ICC component uses algorithms that have been FIPS 140-2
validated
Set Default Certificate
The set default certificate command sets a certificate to be used as the default
certificate for the identified key database. During this command the current default
certificate, if there is one, has it’s default setting removed. The new certificate is then
set as the default certificate. There can only ever be one default certificate in a key
database.
The syntax for setting the default certificate in an existing key database with
GSKCapiCmd is as follows:
gsk7capicmd -cert -setdefault -db [-pw ] -label [-fips]
Where:
object -cert
action -setdefault
options
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –create –db “/tmp/key.kdb” –pw “j\!jj”). Note however
when prompted by gsk7capicmd for a value (for example a password) quoting
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
-db
The fully qualified path name of a key database.
-pw
The password for the key database identified by the –db tag above.
-label
34
Label that uniquely identifies the certificate that is to be set as the
default certificate in the identified key database.
-fips
This disables the use of the BSafe cryptographic library. Only the ICC
component which must be successfully intialized in FIPS* mode will
be used. If the ICC component does not intialize in FIPS mode then the
gsk7capicmd operation will fail.
* When in FIPS mode the ICC component uses algorithms that have been FIPS 140-2
validated
List Certificates
The list certificate command lists all of the certificates store within the identified key
database. As an example the following certificate list is displayed for a new key
database created with the GSKCapiCmd program. The command used to create this
list is as follows: gsk7capicmd –cert –list –db [-pw ].
Certificates found:
* default, - has private key, ! trusted
Entrust.net Global Secure Server Certification Authority
Entrust.net Global Client Certification Authority
Entrust.net Client Certification Authority
Entrust.net Certification Authority (2048)
Entrust.net Secure Server Certification Authority
VeriSign Class 3 Public Primary Certification Authority
VeriSign Class 2 Public Primary Certification Authority
VeriSign Class 1 Public Primary Certification Authority
VeriSign Class 4 Public Primary Certification Authority - G2
VeriSign Class 3 Public Primary Certification Authority - G2
VeriSign Class 2 Public Primary Certification Authority - G2
VeriSign Class 1 Public Primary Certification Authority - G2
VeriSign Class 4 Public Primary Certification Authority - G3
VeriSign Class 3 Public Primary Certification Authority - G3
VeriSign Class 2 Public Primary Certification Authority - G3
VeriSign Class 1 Public Primary Certification Authority - G3
Thawte Personal Premium CA
Thawte Personal Freemail CA
Thawte Personal Basic CA
Thawte Premium Server CA
Thawte Server CA
RSA Secure Server Certification Authority
The default key is marked with the ‘*’ symbol and all trusted self-signed (root) certs
are listed with a ‘!’ symbol. The ‘-‘ symbol is used to show where a private key is
present.
The syntax to list the certificates in an existing key database with GSKCapiCmd is as
follows:
gsk7capicmd -cert -list [] [-expiry [] {-db
| -crypto -tokenlabel }[-pw ]
[-type ] [-secondaryDB -secondaryDBpw ]
[-fips]
Where:
35
object -cert
action -list
The list command has four special tags that can be associated with it. These
tags are used to identify what type of certificates you are requesting to be
displayed. The tags are not required, by default all certificate stored within the
key database will be displayed. The below lists all of the tags that can be
associated with the list command:
all - List the labels of all certificates in the identified key database, this is the
default for the list command.
personal - List all personal certificates in the identified key database.
CA – List all of the certificate authority (CA) certificates in the identified key
Database.
site – This tag will return error 228 as it is only added for backward
compatibility and potential future enhancements. It is not recommended
to use this tag.
options
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –create –db “/tmp/key.kdb” –pw “j\!jj”). Note however
when prompted by gsk7capicmd for a value (for example a password) quoting
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
-expiry
The expiry tag identifies the number of days from today that a
certificate is valid for. If the certificates validity falls within this time it
is displayed. To list certificates that have already expired, enter the
value 0. If you do not specify this tag it is not applied during the
execution of the command.
-db
The fully qualified path name of a key database. If the supplied
filename has an extension of either “.p12” or .pfx” then it is assumed
that it is in PKCS12 format. If it is “.p7”, “.smime” or “.eml” then it is
assumed to be a pkcs7 encoding.
-crypto
Indicates a PKCS11 cryptographic device operation, where is the path to the module to manage the crypto device.
36
-tokenlabel
The PKCS11 cryptographic device token label.
-pw
The password for the key database identified by the –db or –tokenlabel
tags above.
-type
The type of the key database to be exported from, default cms.
-secondaryDB
A CMS key database used to support the PKCS11 device. A PKCS11
device does not normally have a large amount of space available to
store a lot of signer certificates. The signer certificates are used for the
validation of certificates when they are added to the PCKS11 device.
-secondaryDBpw
Password for the secondary CMS key database supporting the PKCS11
device.
-fips
This disables the use of the BSafe cryptographic library. Only the ICC
component which must be successfully intialized in FIPS* mode will
be used. If the ICC component does not intialize in FIPS mode then the
gsk7capicmd operation will fail.
* When in FIPS mode the ICC component uses algorithms that have been FIPS 140-2
validated
Modify Certificate
The modify certificate command allows a CA’s certificate trust status to be enabled or
disabled. When a CA’s certificate trust status is enabled then that CA certificate is
permitted to be involved in a certificate chain validation. If the CA’s certificate trust
status is disabled then it cannot be used to validate any certificates. For example if
certificate “ABC” is signed by the CA certificate “VeriSign CA” and “VeriSign CA”
is not marked as trusted the validation of “ABC” will fail. You are able to have any
number of trusted CA certificates in the single key database.
The syntax for modifying the trust status of a certificate in an existing key database
with GSKCapiCmd is as follows:
gsk7capicmd -cert -modify -db [-pw ] -label -trust [-fips]
Where:
object -cert
action -modify
37
options
IMPORTANT: On Unix type operating systems it is recommended to always
encapsulate string values associated with all tags in double quotes (“”). You
will also need to escape, using a ‘\’ character, the following characters if they
appear in the string values: ‘!’, ‘\’, ‘”’, ‘`’. This will prevent some command
line shells from interpreting specific characters within these values. (e.g.
gsk7capicmd –keydb –create –db “/tmp/key.kdb” –pw “j\!jj”). Note however
when prompted by gsk7capicmd for a value (for example a password) quoting
the string and adding the escape characters should not be done. This is because
the shell is no longer influencing this input.
-db
The fully qualified path name of a key database.
-pw
The password for the key database identified by the –db tag above.
-label
Label attached to the certificate.
-trust
Trust status of a CA certificate, default is enabled. Trust status of a CA
certificate, default is enable. When a CA’s certificate trust status is
enabled then that CA certificate is permitted to be involved in a
certificate chain validation. If the CA’s certificate trust status is
disabled then it cannot be used to validate any certificates. For example
if certificate “ABC” is signed by the CA certificate “VeriSign CA” and
“VeriSign CA” is not marked as trusted the validation of “ABC” will
fail.
-fips
This disables the use of the BSafe cryptographic library. Only the ICC
component which must be successfully intialized in FIPS* mode will
be used. If the ICC component does not intialize in FIPS mode then the
gsk7capicmd operation will fail.
* When in FIPS mode the ICC component uses algorithms that have been FIPS 140-2
validated
Sign a Certificate
The sign certificate command allows the signing of a certificate request by an existing
certificate stored within a key database. The command accepts a certificate request in
its file format and a label of a certificate stored within the key database that contains
the private key to be used during the signing process. If a certificate is not identified,
the private key of the default certificate in the key database is used during the signing
process.
The syntax for signing a certificate with GSKCapiCmd is as follows:
38
gsk7capicmd -cert -sign {-db 
.