ikecert(1M) System Administration Commands ikecert(1M)NAMEikecert - manipulates the machine's on-filesystem public-key certifi‐
cate databases
SYNOPSISikecert 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 reposi‐
tories, 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 Crypto‐
graphic Accelerator 4000.
OPTIONS
Except for tokens, each subcommand requires one option, possibly fol‐
lowed by one or more option-specific arguments.
The tokens subcommand lists all available tokens in the PKCS#11 library
specified in /etc/inet/ike/config.
The following options are supported:
-a
certlocal
When specified with the certlocal subcommand, this option
installs (adds) a private key into the Internet Key Exchange
(IKE) local ID database. The key data is read from standard
input, and is in either Solaris-only format or unencrypted
PKCS#8 DER format. Key format is automatically detected. PKCS#8
key files in PEM format and files in password protected,
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 and adds it to the IKE certifi‐
cate database. The certificate 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 matching public key object
and an existing private key object were created using the cert‐
local -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.
-e [-f pkcs8] slot
certlocal
When specified with the certlocal subcommand, this option
extracts a private key from the IKE local ID database. The key
data are written to standard output. 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 "Security" sec‐
tion, 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 format.
-e [-f output-format] certspec
certdb
When specified with the certdb subcommand, this option extracts
a certificate from the IKE certificate database which matches
the certspec and writes it to standard output. The output-for‐
mat 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]
certlocal
When specified with the certlocal subcommand, this option gen‐
erates a IKE public/private key pair and adds it into the local
ID database. It also generates a certificate request and sends
that to standard output. For details on the above options see
for details on the dname argument and see ALTERNATIVE 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 unlock the token with ikeadm(1M) once
in.iked(1M) is running.
-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]
certlocal
When specified with the certlocal subcommand, generates a pub‐
lic/private key pair and adds it into the local ID database.
This option also generates a self-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.
Use the -voption with extreme caution. See the "Security" sec‐
tion, 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 cert‐
spec, if any pattern is given. The list displays the identity
string of the certificates, as well as, the private key if in
the key database. The -v switches the output to a verbose 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 to specify to list a specific CRL. The -v option
switches the output to a verbose mode where the entire certifi‐
cate is printed. See NOTES, below, for details oncertspec pat‐
terns.
-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 "cor‐
rupted" 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 already deleted by certdb -r, that is not
a problem.
-r certspec
certdb
Removes certificates from the IKE certificate database. Cer‐
tificates matching the specified certificate pattern are
deleted. Any private keys in the certlocal database correspond‐
ing to these certificates are not deleted. This removes the
first matching identity.
If the pattern specifies a slot and the slot is deemed as "cor‐
rupted" 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 was already deleted by certlocal -r, that
is not a problem.
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 no attempt to access the hardware key‐
store or to validate or remove the on-token private key object.
The object is simply disassociated from the IKE database.
certdb
When specified with the certdb subcommand and the -T flag, this
option unlinks a PKCS#11 certificate object from the IKE data‐
base. There will be no attempt to access the hardware keystore
or to validate or remove the on-token certificate or public key
objects. The objects are simply disassociated 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 from the on-disk keystore to the hardware
keystore specified by its PKCS#11 token. This subcommand
attempts to create each of these components, even if one part
fails. In all cases, the original on-disk private key and pub‐
lic certificate are still retained and must be deleted sepa‐
rately. 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 given certspec and corresponding
public key from the on-disk keystore to the hardware keystore
specified by its 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 permissions. 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, this option links
an existing on-token private key object to the IKE database.
The object itself remains on the token. This option simply lets
the IKE infrastructure know that the object exists, as if it
had been originally created on-token with the Solaris IKE util‐
ities.
certdb
When specified with the certdb subcommand, this option links an
existing on-token certificate object to the IKE database. The
object itself remains on the token. This option simply lets the
IKE infrastructure know that the object exists, as if it had
been originally created on-token with the Solaris IKE utili‐
ties.
If -p is specified, the PKCS#11 token pin is stored in the
clear on-disk, with root-protected file permissions. If not
specified, one must unlock the token with ikeadm(1M) once
in.iked(1M) is running.
PARAMETERS
The following parameters are supported:
certspec
Specifies the pattern matching of certificate specifications. Valid
certspecs are the Subject Name, Issuer Name, and Subject Alterna‐
tive Names.
These can be specified as certificates that match the given cert‐
spec values and that do not match other certspec values. To signify
a certspec value that is not supposed to be present in a certifi‐
cate, place an ! in front of the tag.
Valid certspecs are:
<Subject Names>
SUBJECT=<Subject Names>
ISSUER=<Issuer Names>
SLOT=<Slot Number in the certificate database>
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=<IPv4 address>
DNS=<Domain Name Server address>
EMAIL=<email (RFC 822) address>
URI=<Uniform Resource Indicator value>
DN=<LDAP Directory Name value>
RID=<Registered Identifier value>
Valid Slot numbers can be specified without the keyword tag. Alter‐
native name can also be issued with keyword tags.
-A
Subject Alternative Names the certificate. The argument that fol‐
lows 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 for ASN.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. Use the follow‐
ing command to determine the key sizes supported by the Solaris
Cryptographic Framework:
% cryptoadm list -vm
The mechanisms displayed by the preceding command are described 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
CKM_DH_PKCS_KEY_PAIR_GEN
Note -
Some hardware does not support all key sizes. For example, the
Sun Cryptographic Accelerator 4000's keystore (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 the validity start time. See
NOTES, below, for an explanation 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 to the PKCS#11 standard. A
PKCS#11 library must be specified 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 automati‐
cally 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 (each with individual key storage) for
a single PKCS#11 library instance.
SECURITY
This 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 not desireable. The token's PIN, however,
is still needed. The PINfor the PKCS#11 token, therefore, is stored
where normally the on-disk cryptographic keys would reside. This design
decision is deemed acceptable because, with a hardware key store, pos‐
session of the key is still unavailable, only use of the key is an
issue if the host is compromised. Beyond the PIN, the security of ike‐
cert 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 Cryp‐
tography: 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 Request
Generating a CA request appears the same as the self-signed certifi‐
cate. The only differences between the two is the option -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
Example 3 A CA Request Using a Hardware Key Store
The following example illustrates the specification of a token 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 matching public-key cer‐
tificate 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/config
Consulted for the pathname of a PKCS#11 library.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWcsu │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Evolving │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOikeadm(1M), in.iked(1M), getdate(3C), ike.config(4), attributes(5),
pkcs11_softtoken(5)
Schneier, Bruce. Applied Cryptography: Protocols, Algorithms, and
Source Code in C. Second Edition. John Wiley & Sons. New York, NY.
1996.
RSA Labs, PKCS#11 v2.11: Cryptographic Token Interface Standards, No‐
vember 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 seconds
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 calcu‐
lated 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 or month. For instance, if it is Jan 26, 2005 and the cer‐
tificate 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) for details). Any date
string prepended with a "+" or "-" is treated as a time relative to the
current time, while others are treated as absolute dates. Sanity check‐
ing is also done to ensure that the end validity date is greater than
the start validity date. For example, the following command would cre‐
ate 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 and exclusive-IP zones,
this command is not useful in shared-IP zones.
SunOS 5.10 10 Jun 2009 ikecert(1M)
