Generate Certificate

This command is used to generate X.509v3 certificates. A number of approaches are available using ctcert. These approaches and the minimum options required are listed below.

To generate new keys and self sign

ctcert c -k  -l<label>[options ...]

To generate new keys and sign with a CA key

ctcert c  -c<label> -k -l<label> [options...]

To use existing keys and self sign

ctcert c -l<label> [options...]

To use existing keys and sign with a CA key

ctcert c -c<label> -l<label> [options...]

One of the above combinations of options -c, -k, -l is mandatory. All other options allow finer control over ctcert's default actions. A detailed description of each option is provided below.

When the -l<label> option is present without the -k (generate new key pair) option, <label> is the label for an existing PKCS #10 certificate request or an existing public key. ctcert first searches for a certificate request with a matching label and uses it to generate the certificate. If a certificate request does not exist, ctcert searches for a public key with a matching label and uses it to generate a certificate. Otherwise, ctcert reports an error.

Import Certificate or Certificate Request

This command is used to import a new certificate or certificate request object onto the HSM. The object to be imported is PEM-encoded and contained in a text file. To verify the object is PEM-encoded, the first line in the text file should contain one of the following strings.

“----BEGIN CERTIFICATE----“
“----BEGIN CERTIFICATE REQUEST----“

The -l<label> option specifies the label for the newly-imported certificate or certificate request object.

List Certificates, Certificate Requests, and Keys

This command will list the existing certificates, certificate requests and keys on the specified token.

Generate Certificate Request

This command generates a certificate request from an existing or newly-generated key pair. For an existing key pair, the -l<label> option specifies the label of the public key. The private key is identified by CKA_ID attribute, which should be the same for key pairs. This is the default behavior for keys generated by ProtectToolkit-C. If the public key contains a value for the CKA_SUBJECT attribute, then it will be used for the certificate request object’s subject-distinguished name. If this attribute does not exist, ctcert will prompt the user for this information.

If a new key pair is being generated, the -l<label> option specifies the label for the new key pair and ctcert will prompt for the certificate request object's subject-distinguished name. The new certificate request object's label will also be set to <label>.

Set Trusted Certificate

This command will set the CKA_TRUSTED attribute on the specified certificate on the token.

The SO is the only user who can set this attribute. The user will be prompted for the token SO PIN.

--cert-begin=<YYYYMMDDhhmmss[Z]>

Specifies the begin time (notBefore) for a Certificate. Including the Z sets the time as GMT. Otherwise, local time is assumed and is converted to GMT.

This option is only valid for the Generate Certificate Command (c), and must be used with either the -b<YYYYMMDDhhmmss[Z]> or -d<integer[h|d|m|y]> option.

--ca-label=<label>

Specifies a label identifying a CA (private) key used to sign a newly-generated certificate.

The <label> can be a label for a certificate associated with the CA key, or the label of the private key itself.

This option is only valid for the Generate Certificate Command (c).

--curve-name=<label>

Specifies which curve to use. Valid values:

>brainpoolP160r1

>brainpoolP160t1

>brainpoolP192r1

>brainpoolP192t1

>brainpoolP224r1

>brainpoolP224t1

>brainpoolP256r1

>brainpoolP256t1

>brainpoolP320r1

>brainpoolP320t1

>brainpoolP384r1

>brainpoolP384t1

>brainpoolP512r1

>brainpoolP512t1

>c2tnb191v1

>c2tnb191v1e

>curve25519

>ed25519

>P-192 (also known as prime192v1 and secp192r1)

>P-224 (also known as secp224r1)

>P-224K1 (also known as secp224k1)

>P-256 (also known as prime256v1 and secp256r1)

>P-384 (also known as secp384r1)

>P-521 (also known as secp521r1)

>secp256k1

>or any valid ECC Domain Parameter object label

If -tec is specified, the -C parameter must be included in the command, or ctcert will exit with an error message. All hashing mechanisms are supported.

--cert-duration=<integer[h|d|m|y]>
Specifies the duration of a Certificate. Must specify one of: h - hours, d - days, m - months, y - years.

May be used with the -b<YYYYMMDDhhmmss[Z]> option.

If the -b option is not included, the duration will begin at the moment of creation.

This option is only valid for the Generate Certificate Command (c).

--cert-end=<YYYYMMDDhhmmss[Z]>

Specifies the end time (notAfter) for a Certificate. Including the Z sets the time as GMT. Otherwise, local time is assumed and is converted to GMT.

This option is only valid for the Generate Certificate Command (c), and must be used with the -b<YYYYMMDDhhmmss[Z]> option.

--import-file=<name>

Specifies a text file containing a PEM encoding of a certificate or certificate request object.

This option is only valid with the Import Command (i), Export Command (x) or Generate Certificate Request Command (r).

--help

Display usage information.

--ca-slot=<slot>

Specifies the slot containing the CA signing key identified by the -c<label> option. If the -i<slot> option is not present, the CA key is assumed to be in the slot identified by the -s<slot> option. If -s is not present then the CA key is assumed to exist in slot 0.

If the CA signing key has the CKA_SIGN attribute set to FALSE and the CKA_SIGN_LOCAL_ATTRIBUTE set to TRUE, the CA signing key must reside in the same slot as the certificate it is signing.

This option is only valid with the -c option.

--key-gen

Specifies that a new key pair be generated. The l<label> option specifies the label for the new keys. A key pair with the same label must not already exist.

NOTE   -k is a mandatory parameter when generating a certificate with new keys.

--label=<label>

This option specifies a label for a new or existing certificate request or public key object. Refer to the description of each command for relevant details.

--P

This option will sign the newly created certificate using an RSA-PSS mechanism. This option is only valid if the key used to sign the certificate is RSA.

--slot=<slot>

Specifies the slot:

>in which a new key pair and a certificate or certificate request will be generated

>into which a certificate or certificate request will be imported

>from which keys, certificates, and certificate requests will be listed

>that contains the certificate or certificate request to be exported

--sig-hash-alg=<sign_alg>

Specifies the RSA or DSA hashing algorithm for certificate request or certificate generation. Valid mechanisms are:

NOTE   ECDSA is used for a certificate and EC is used for a key pair.

--type=<type>

Use with the -k option to specify the key type that should be generated. The valid key types are rsa, rsax931, ec, and dsa. The default is rsa.

If -tec is specified, the -C parameter must be included in the command, or ctcert will exit with an error message. All hashing mechanisms are supported.

--attribute-file=<name>

Specifies a text file containing certain certificate attributes and extensions. For details on supported attributes and extensions and the format of this file refer to Certificate Attribute File.

This option is only valid with the Generate Certificate command (c).

This tag defines the certificate’s label and is different from the label specified by the l<label> option. This latter label refers to the key pair for which the certificate is being generated. If this tag is missing in the certificate attribute file, then the certificate label will default to the one specified with the -l<label> option.

The label can be any string of ASCII characters. If the label contains multiple words, white space between the words is maintained. If a new line is encountered between words it is replaced by a space. The following example demonstrates how to use this tag:

label { Test Certificate }

This tag defines the certificate’s serial number. To ensure uniqueness, it is only used if the signing key does not have the usage count attribute defined. If this attribute is defined, the current value of the usage count is used as the certificate’s serial number. If the usage count attribute is not defined and the serial number is not defined in the certificate attribute file, then ctcert will prompt the user for this information.

The following example illustrates the correct use of this tag:

serialnumber { 999999 }

NOTE   The maximum value of a certificate serial number is 99999999.

These tags define the issuer and subject distinguished names and are defined by a set of name/value pairs. The format for an issuer or subject distinguished name is:

issuer | subject

CN=<string> ,

OU=<string> ,

O=<string> ,

C= <string>

}

The meaning of each name component in each name/value pair is as follows:

CN - Common Name

OU - Organizational Unit Name

O - Organization Name

C - Country Name

The following example illustrates a well-formed issuer-distinguished name:

issuer  { CN=any string ,
 OU=Testing ,
 O=SafeNet , 
C=CA 
}

NOTE   White space is ignored except when it appears between multiple words that constitute the value component of a name/value pair. In the above example, the space between any string in the common name component is preserved.

For the subject-distinguished name tag, two special strings can be assigned to the CN (Common Name) component. These special strings are serialno and unique.

When the serialno string is used, ctcert will replace the serialno string with the HSM's serial number. This can be used to distinguish certificates that belong to specific HSMs.

When the unique string is used, ctcert appends the current value of the signing key’s usage count to the HSM serial number and replaces the unique string with this value. Thus the unique string will be replaced with a string of the form nnnn-xx, where nnnn is the HSM serial number and xx is the signing key’s usage count.

This tag identifies a certificate policies extension that defines the policy under which this certificate was issued. The format of a certificate policy extension entry is:

certificatepolicies {

oid=oid_string ,

[critical | noncritical  , ]

[unotice=”<string>” , ]

[cps=”<string>” ]

}

The certificate policy is identified by an object identifier (OID) and may contain one of the policy qualifiers cps or unotice. The cps qualifier string is the URI of the Certification Practice Statement that relates to this policy, and the unotice qualifier is a string that is included in the certificate as a user notice that relates to the certificate policy. Both the cps and unotice strings are composed of printable ASCII characters. An object identifier (OID) is defined by a series of numerical labels separated by periods. For example, the OID that identifies a key usage extension within an X.509v3 certificate is written as:

id-ce-keyusage OBJECT IDENTIFIER ::= { 2.5.29.15 }

The critical / noncritical keywords indicate whether this certificate policy extension is critical or not. By default, the certificate policy extension is marked noncritical. Multiple certificate policy extensions may be defined in the certificate attribute/extension file.

The following example illustrates a well-formed certificatepolicies extension:

certificatepolicies
{
oid=1.2.3.45.6.8 ,
unotice=Test string,
critical
}

Generate new DSA keys with label “Test” and self sign. This command will prompt for the subject distinguished name.

ctcert  c  -k  -lTest  -tdsa

Generate new RSA keys with label “Test” and key size 512 bites,  sign with a key that has the label “CA Key”.

ctcert  c  -c”CA Key”  -k  -lTest -z512

Generate a new ECDSA certificate, a EC key pair, and self-sign using the P-192 curve:

ctcert c  -tec -CP-192 -lecdsaCert1 -k

NOTE   Use ECDSA for a certificate and EC for a key pair.

Use existing keys with label “Test” and use certificate attribute file.

ctcert  c  -lTest  -x certificate_file.txt

Use existing keys with label “Test” and sign with a key with that has the label “CA Key”.

ctcert  c  -c”CA Key”  -lTest

Use existing certificate request with a label “Test Cert” and sign with a key that has the label “CA Key”.

ctcert  c  -c”CA Key”  -l”Test Cert” 

To create a new certificate request with the label “User” and generate new keys (RSA is default)

ctcert  r  -k  -lUser

To export a previously generated certificate request as a PEM object and store this in the file name mycert.txt.

ctcert x  -lUser -fmycert.txt