System Administration Commands ikecert(1M)
NAME
ikecert - manipulates the machine's on-filesystem public-key
certificate databasesSYNOPSIS
ikecert certlocal
[-a | -e | -h | -k | -l | -r | -U | -C | -L]
[[-p] -T PKCS#11 token identifier]
[option_specific_arguments]...
ikecert certdb [-a | -e | -h | -l | -r | -U | -C | -L]
[[-p] -T PKCS#11 token identifier]
[option_specific_arguments]...
ikecert certrldb [-a | -e | -h | -l | -r]
[option_specific_arguments]...
ikecert tokens
DESCRIPTION
The ikecert command manipulates the machine's on-filesystem
public-key certificate databases. See the "Files" section,
below.ikecert has three subcommands, one for each of the three
major repositories, plus one for listing available hardware tokens:o certlocal deals with the private-key repository,
o certdb deals with the public-key repository, and:
o certrldb deals with the certificate revocation list (CRL) repository.o tokens shows the available PKCS#11 tokens for a
given PKCS#11 library.
The only supported PKCS#11 library and hardware is the Sun
Cryptographic Accelerator 4000. OPTIONSExcept for tokens, each subcommand requires one option, pos-
sibly followed by one or more option-specific arguments.
SunOS 5.11 Last change: 10 Jun 2009 1
System Administration Commands ikecert(1M)
The tokens subcommand lists all available tokens in thePKCS#11 library specified in /etc/inet/ike/config.
The following options are supported:-a
certlocal When specified with the certlocal subcommand, thisoption installs (adds) a private key into the Inter-
net Key Exchange (IKE) local ID database. The key data is read from standard input, and is in eitherSolaris-only format or unencrypted PKCS#8 DER for-
mat. Key format is automatically detected. PKCS#8
key files in PEM format and files in password pro-
tected, encrypted format are not recognized, but can be converted appropriately using tools available in OpenSSL.This option cannot be used with PKCS#11 hardware
objects when the corresponding public certificate is not already present in the IKE database. When importing both a public certificate and a private key, the public portion must be imported first using the certdb subcommand. certdb When specified with the certdb subcommand, this option reads a certificate from standard input andadds it to the IKE certificate database. The certi-
ficate must be a X.509 certificate in PEM Base64 or ASN.1 BER encoding. The certificate adopts the name of its identity.This option can import a certificate into a PKCS#11
hardware key store one of two ways: Either a match-
ing public key object and an existing private keyobject were created using the certlocal -kc option,
or if a PKCS#11 token is explicitly specified using
the -T option.
certrldb When specified with the certrldb subcommand, this option installs (adds) a CRL into the IKE database. The CRL reads from standard input.SunOS 5.11 Last change: 10 Jun 2009 2
System Administration Commands ikecert(1M)
-e [-f pkcs8] slot
certlocal When specified with the certlocal subcommand, this option extracts a private key from the IKE local IDdatabase. The key data are written to standard out-
put. The slot specifies which private key to extract. Private keys are only extracted in binary/ber format.Use this option with extreme caution. See the "Secu-
rity" section, below.This option will not work with PKCS#11 hardware
objects.When used in conjunction with "-f pkcs8", the
private key is extracted in unencrypted PKCS#8 for-
mat.-e [-f output-format] certspec
certdb When specified with the certdb subcommand, thisoption extracts a certificate from the IKE certifi-
cate database which matches the certspec and writesit to standard output. The output-format option
specifies the encoding format. Valid options are PEM and BER. This extracts the first matching identity. The default output format is PEM. certrldb When specified with the certrldb subcommand, this option extracts a CRL from the IKE database. The key data are written to standard output. The certspec specifies which CRL that is extracted. The first one that matches in the database is extracted. See NOTES, below, for details on certspec patterns.-kc -m keysize -t keytype -D dname -A altname[ ... ]
[-S validity start_time][-F validity end_time]
[-T PKCS#11 token identifier]
SunOS 5.11 Last change: 10 Jun 2009 3
System Administration Commands ikecert(1M)
certlocal When specified with the certlocal subcommand, this option generates a IKE public/private key pair andadds it into the local ID database. It also gen-
erates a certificate request and sends that to stan-
dard output. For details on the above options seefor details on the dname argument and see ALTERNA-
TIVE NAMES for details on the altname argument(s) to
this command.If -T is specified, the hardware token will generate
the pair of keys.If -p is specified with -T, the PKCS#11 token pin is
stored in the clear on-disk, with root-protected
file permissions. If not specified, one must unlockthe token with ikeadm(1M) once in.iked(1M) is run-
ning.-ks -m keysize -t keytype -D dname -A altname[ ... ]
[-S validity start_time][-F validity end_time]
[-f output-format][[-p] -T PKCS#11 token identifier]
certlocalWhen specified with the certlocal subcommand, gen-
erates a public/private key pair and adds it into the local ID database. This option also generates aself-signed certificate and installs it into the
certificate database. See NOTES, below, for details on the dname and altname arguments to this command.If -T is specified, the hardware token will generate
the pair of keys, and the self-signed certificate
will also be stored in the hardware.-l [-v] [slot]
certlocal When specified with the certlocal subcommand, this option lists private keys in the local ID database.The -v option switches output to a verbose mode
where the entire certificate is printed.SunOS 5.11 Last change: 10 Jun 2009 4
System Administration Commands ikecert(1M)
Use the -voption with extreme caution. See the
"Security" section, below. The -v option will not
work with PKCS#11 hardware objects.
-l [-v] [certspec]
certdb When specified with the certdb subcommand, this option lists certificates in the IKE certificate database matching the certspec, if any pattern is given. The list displays the identity string of the certificates, as well as, the private key if in thekey database. The -v switches the output to a ver-
bose mode where the entire certificate is printed. If the matching ceritifcate is on a hardware token, the token ID is also listed. certrldb When specified with the certrldb subcommand, this option lists the CRLs in the IKE database along with any certificates that reside in the database and match the Issuer Name. certspec can be used tospecify to list a specific CRL. The -v option
switches the output to a verbose mode where the entire certificate is printed. See NOTES, below, for details oncertspec patterns.-r slot
certlocal When specified with the certlocal subcommand, deletes the local ID in the specified slot. If there is a corresponding public key, it is not be deleted. If this slot is deemed as "corrupted" or otherwise unrecognizable, it is deleted as well.If this is invoked on a PKCS#11 hardware object, it
will also delete the PKCS#11 public key and private
key objects. If the public key object was alreadydeleted by certdb -r, that is not a problem.
SunOS 5.11 Last change: 10 Jun 2009 5
System Administration Commands ikecert(1M)
-r certspec
certdbRemoves certificates from the IKE certificate data-
base. Certificates matching the specified certifi-
cate pattern are deleted. Any private keys in thecertlocal database corresponding to these certifi-
cates are not deleted. This removes the first match-
ing identity. If the pattern specifies a slot and the slot is deemed as "corrupted" or otherwise unrecognizable, it is deleted as well.If this is invoked on a PKCS#11 hardware object, it
will also delete the certificate and the PKCS#11
public key object. If the public key object wasalready deleted by certlocal -r, that is not a prob-
lem. certrldb When specified with the certrldb subcommand, this option deletes the CRL with the given certspec.-U slot
certlocal When specified with the certlocal subcommand and the-T flag, this option unlinks a PKCS#11 private key
object from the IKE database. There will be noattempt to access the hardware keystore or to vali-
date or remove the on-token private key object. The
object is simply disassociated from the IKE data-
base. certdbWhen specified with the certdb subcommand and the -T
flag, this option unlinks a PKCS#11 certificate
object from the IKE database. There will be noattempt to access the hardware keystore or to vali-
date or remove the on-token certificate or public
key objects. The objects are simply disassociatedSunOS 5.11 Last change: 10 Jun 2009 6
System Administration Commands ikecert(1M)
from the IKE database.-C certspec
certlocal When specified with the certlocal subcommand, this option copies both the private key and its corresponding certificate and the public key fromthe on-disk keystore to the hardware keystore speci-
fied by its PKCS#11 token. This subcommand attempts
to create each of these components, even if one partfails. In all cases, the original on-disk private
key and public certificate are still retained and must be deleted separately. Some hardware keystores,such as FIPS-140 compliant devices, may not support
migration of private key objects in this manner. certdb When specified with the certdb subcommand, this option copies the certificate matching the givencertspec and corresponding public key from the on-
disk keystore to the hardware keystore specified byits PKCS#11 token. The original public certificate
is still retained and must be deleted separately, if desired.If -p is specified, the PKCS#11 token pin is stored
in the clear on-disk, with root-protected file per-
missions. If not specified, one must unlock the token with ikeadm(1M) once in.iked(1M) is running.-L pattern
certlocal When specified with the certlocal subcommand, thisoption links an existing on-token private key object
to the IKE database. The object itself remains onthe token. This option simply lets the IKE infras-
tructure know that the object exists, as if it hadbeen originally created on-token with the Solaris
IKE utilities.SunOS 5.11 Last change: 10 Jun 2009 7
System Administration Commands ikecert(1M)
certdb When specified with the certdb subcommand, thisoption links an existing on-token certificate object
to the IKE database. The object itself remains onthe token. This option simply lets the IKE infras-
tructure know that the object exists, as if it hadbeen originally created on-token with the Solaris
IKE utilities.If -p is specified, the PKCS#11 token pin is stored
in the clear on-disk, with root-protected file per-
missions. If not specified, one must unlock the token with ikeadm(1M) once in.iked(1M) is running.PARAMETERS
The following parameters are supported: certspecSpecifies the pattern matching of certificate specifica-
tions. Valid certspecs are the Subject Name, Issuer Name, and Subject Alternative Names. These can be specified as certificates that match the given certspec values and that do not match other certspec values. To signify a certspec value that is not supposed to be present in a certificate, place an ! in front of the tag. Valid certspecs are:SUBJECT= ISSUER= SLOT= Example:"ISSUER=C=US, O=SUN" IP=1.2.3.4 !DNS=example.com Example:"C=US, O=CALIFORNIA" IP=5.4.2.1 DNS=example.com Valid arguments to the alternative names are as follows: IP= DNS= EMAIL= URI= DN= RID= SunOS 5.11 Last change: 10 Jun 2009 8
System Administration Commands ikecert(1M)
Valid Slot numbers can be specified without the keyword tag. Alternative name can also be issued with keyword tags.-A
Subject Alternative Names the certificate. The argumentthat follows the -A option should be in the form of
tag=value. Valid tags are IP, DNS, EMAIL, URI, DN, and RID (See example below).-D
X.509 distinguished name for the certificate subject. It typically has the form of: C=country, O=organization, OU=organizational unit, CN=common name. Valid tags are: C, O, OU, and CN.-f
Encoding output format. pem for PEM Base64 or ber forASN.1 BER. If -f is not specified, pem is assumed.
-F validity end_time
Finish certificate validity time. If the -F flag is not
specified, the validity end time is calculated at four years from the validity start time. See NOTES for an explanation for the validity date and time syntax.-m
Key size. It can be 512, 1024, 2048, 3072, or 4096. Usethe following command to determine the key sizes sup-
ported by the Solaris Cryptographic Framework:% cryptoadm list -vm
The mechanisms displayed by the preceding command aredescribed in pkcs11_softtoken(5). If your system has
hardware acceleration, the mechanisms supported by the hardware will be listed in a separate section for each provider. Mechanisms can be any of:CKM_RSA_PKCS_KEY_PAIR_GEN
CKM_DSA_KEY_PAIR_GEN
SunOS 5.11 Last change: 10 Jun 2009 9
System Administration Commands ikecert(1M)
CKM_DH_PKCS_KEY_PAIR_GEN
Note -
Some hardware does not support all key sizes. Forexample, the Sun Cryptographic Accelerator 4000's key-
store (when using the -T option, below), supports only
up to 2048-bit keys for RSA and 1024-bit keys for DSA.
-S validity start_time
Start certificate validity time. If the -S flag is not
specified, the current date and time is used for thevalidity start time. See NOTES, below, for an explana-
tion for the validity date and time syntax.-t
Key type. It can be rsa-sha1, rsa-md5, or dsa-sha1.
-T
PKCS#11 token identifier for hardware key storage. This
specifies a hardware device instance in conformance tothe PKCS#11 standard. A PKCS#11 library must be speci-
fied in /etc/inet/ike/config. (See ike.config(4).)A token identifier is a 32-character space-filled
string. If the token given is less than 32 characters long, it will be automatically padded with spaces.If there is more than one PKCS#11 library on a system,
keep in mind that only one can be specified at a time in /etc/inet/ike/config. There can be multiple tokens (eachwith individual key storage) for a single PKCS#11
library instance. SECURITYThis command can save private keys of a public-private key
pair into a file. Any exposure of a private key may lead to compromise if the key is somehow obtained by an adversary.The PKCS#11 hardware object functionality can address some
of the shortcomings of on-disk private keys. Because IKE is
a system service, user intervention at boot is notSunOS 5.11 Last change: 10 Jun 2009 10
System Administration Commands ikecert(1M)
desireable. The token's PIN, however, is still needed. ThePINfor the PKCS#11 token, therefore, is stored where nor-
mally the on-disk cryptographic keys would reside. This
design decision is deemed acceptable because, with ahardware key store, possession of the key is still unavail-
able, only use of the key is an issue if the host iscompromised. Beyond the PIN, the security of ikecert then
reduces to the security of the PKCS#11 implementation. The
PKCS#11 implementation should be scrutinized also.
Refer to the afterword by Matt Blaze in Bruce Schneier's Applied Cryptography: Protocols, Algorithms, and Source Code in C for additional information.EXAMPLES
Example 1 Generating a Self-Signed Certificate
The following is an example of a self-signed certificate:
example# ikecert certlocal -ks -m 512 -t rsa-md5 -D "C=US, O=SUN" -A
IP=1.2.3.4 Generating, please wait... Certificate generated. Certificate added to database.-----BEGIN X509 CERTIFICATE-----
MIIBRDCB76ADAgECAgEBMA0GCSqGSIb3DQEBBAUAMBsxCzAJBgNVBAYTAlVTMQww CgYDVQQKEwNTVU4wHhcNMDEwMzE0MDEzMDM1WhcNMDUwMzE0MDEzMDM1WjAbMQsw CQYDVQQGEwJVUzEMMAoGA1UEChMDU1VOMFowDQYJKoZIhvcNAQEBBQADSQAwRgJB APDhqpKgjgRoRUr6twTMTtSuNsReEnFoReVer!ztpXpQK6ybYlRH18JIqU/uCV/r 26R/cVXTy5qc5NbMwA40KzcCASOjIDAeMAsGA1UdDwQEAwIFoDAPBgNVHREECDAG hwQBAgMEMA0GCSqGSIb3DQEBBAUAA0EApTRD23KzN95GMvPD71hwwClukslKLVg8 f1xm9ZsHLPJLRxHFwsqqjAad4j4wwwriiUmGAHLTGB0lJMl8xsgxag==-----END X509 CERTIFICATE-----
Example 2 Generating a CA RequestGenerating a CA request appears the same as the self-signed
certificate. The only differences between the two is theoption -c instead of -s, and the certificate data is a CA
request.example# ikecert certlocal -kc -m 512 -t rsa-md5 \
-D "C=US, O=SUN" -A IP=1.2.3.4
SunOS 5.11 Last change: 10 Jun 2009 11
System Administration Commands ikecert(1M)
Example 3 A CA Request Using a Hardware Key Store The following example illustrates the specification of atoken using the -T option.
example# # ikecert certlocal -kc -m 1024 -t rsa-md5 -T vca0-keystore \
-D "C=US, O=SUN" -A IP=1.2.3.4
EXIT STATUS The following exit values are returned: 0 Successful completion.non-zero
An error occurred. Writes an appropriate error message to standard error. FILES /etc/inet/secret/ike.privatekeys/* Private keys. A private key must have a matchingpublic-key certificate with the same filename in
/etc/inet/ike/publickeys/. /etc/inet/ike/publickeys/*Public-key certificates. The names are only important
with regard to matching private key names. /etc/inet/ike/crls/* Public key certificate revocation lists. /etc/inet/ike/configConsulted for the pathname of a PKCS#11 library.
ATTRIBUTES
SunOS 5.11 Last change: 10 Jun 2009 12
System Administration Commands ikecert(1M)
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWcs ||_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
SEE ALSO
ikeadm(1M), in.iked(1M), getdate(3C), ike.config(4), attri-
butes(5), pkcs11_softtoken(5)
Schneier, Bruce. Applied Cryptography: Protocols, Algo-
rithms, and Source Code in C. Second Edition. John Wiley & Sons. New York, NY. 1996.RSA Labs, PKCS#11 v2.11: Cryptographic Token Interface Stan-
dards, November 2001. NOTES The following is the validity date and time syntax when the-F or -S flags are used:
For relative dates, the syntax is as follows:{+,-}[Ns][Nm][Nh][Nd][Nw][NM][Ny]
where: N represents an integer s represents secondsSunOS 5.11 Last change: 10 Jun 2009 13
System Administration Commands ikecert(1M)
m represents minutes h represents hours d represents days w represents weeks M represents months y represents years These parameters can be given in any order. For example,"+3d12h" is three and a half days from now, and "-3y2M" is
three years and 2 months ago. All parameters with fixed values can be added up in absolute seconds. Months and years, which have variable numbers of seconds, are calculated using calendar time. Months and years, which are not of fixed length, are defined such that adding a year or month means the same day next year ormonth. For instance, if it is Jan 26, 2005 and the certifi-
cate should expire 3 years and 1 month from today, the expiration (end validity time) date will be Feb 26, 2008. Overflows are dealt with accordingly. For example, one month from Jan 31, 2005 is March 3, 2005, since February has only 28 days. For absolute dates, the syntax of the date formats included in the file /etc/datemsk are accepted (See getdate(3C) fordetails). Any date string prepended with a "+" or "-" is
SunOS 5.11 Last change: 10 Jun 2009 14
System Administration Commands ikecert(1M)
treated as a time relative to the current time, while others are treated as absolute dates. Sanity checking is also done to ensure that the end validity date is greater than the start validity date. For example, the following command would create a certificate with start date 1 day and 2 hours ago and an end date of Jan 22nd, 2007 at 12:00:00 local time.# ikecert certlocal -ks -t rsa-sha1 -m 1024 \
-D "CN=mycert, O=Sun, C=US" \
-S -1d2h -F "01/22/2007 12:00:00"
As in.iked(1M) can run only in the global zone andexclusive-IP zones, this command is not useful in shared-IP
zones.SunOS 5.11 Last change: 10 Jun 2009 15