Add a Certificate to an ACID

Digital Certificates › General Rules › Add a Certificate to an ACID

Add a Certificate to an ACID

When you add a digital certificate, the DIGICERT and DCDSN keywords are required. All other keywords are optional.

To add a certificate to an ACID, enter the following command:

TSS ADDTO(acid|CERTAUTH|CERTSITE) DIGICERT(name)
                                DCDSN(dataset_name)
                                [CERTNSER(nnnnnnnnnnnnnnnn)]
                                [START(sdate)]
                                [FOR(ddd)|UNTIL(date)]
                                [LABLCERT(label name)]
                                [LABLPKDS(PKDS-label|*]
                                [TRUST|NOTRUST|HITRUST]
                                [ICSF|PCICC|DSA]
                                [PKCSPASS('PKCSPASS PASSWORD')]

acid

Specifies a user ACID.

CERTAUTH

Specifies an ACID in which your installation can maintain certificates that were generated by a third party certificate authority (CA). This ACID is predefined in CA Top Secret. You cannot add a keyring to this ACID.

CERTSITE

Specifies an ACID in which your installation can maintain site‑generated certificates. This ACID is pre‑defined in CA Top Secret. You cannot add a keyring to this ACID.

DIGICERT

Specifies a case-sensitive character ID that identifies the certificate with the user ACID.

Range: 1 to 8

DCDSN

Specifies the MVS data set containing the digital certificate. The data set must be defined as physical sequential (DSORG=PS) and variable blocked data set (RECFM=VB). The data set name is entered as a fully qualified name without enclosed quotes (LREC=84).

The certificate contained in the data set must be BER‑encoded, PKCS‑7 BER‑encoded, or Privacy Enhanced Mail (PEM)‑encoded. PEM certificates must be transported to MVS as TEXT; the other formats must be transported as BINARY.

In addition to the end-entity certificate specified on the ADD command, the product adds all certificate authority (CA) certificates contained in a PKCS 7 or PKCS 12 certificate package. These certificate packages generally contain an end-entity user certificate and a chain of CA certificates. The trust status of the first added CA certificate takes the value specified on the Insert command. The other added CA certificates take the trust value of the signing certificate.

For PKCS 7 and PKCS 12 certificate package, a certificate that meets any of the following criteria is added with a trust status of NOTRUST:

The certificate is expired or has a validity period that is not completely within the validity period of its signing certificate.
The signing certificate of the certificate is not in a PKCS 7 or PKCS 12 package or not in CA Top Secret.

If a CA certificate is already known to CA Top Secret, the certificate retains its trust status. Each added CA certificate receives a label of AUTOxxxx, where xxxx is an available number between 1 and 9999.

Note: If an error occurs during the addition of certificates from a PKCS 7 or PKCS 12 certificate package, the product does not remove any CERTAUTH certificates that were already added.

Certificates containing unsupported critical extensions cannot be inserted into CA Top Secret. Noncritical extensions are ignored. Supported critical extensions are as follows:

keyUsage - 2.5.29.15
basicConstraints - 2.5.29.19
subjectAltname - 2.5.29.17
issuerAltname - 2.5.29.18
certificatePolicies - 2.5.29.32
policyMappings -2.5.29.33
policyConstraints - 2.5.29.36
nameConstraints - 2.5.29.30
extKeyUsage - 2.5.29.37
subjectKeyIdentifier - 2.5.29.14
authorityKeyIdentifier - 2.5.29.35
hostIdMapping - 1.3.18.0.2.18.1

Ranges: The data set must be cataloged and can be up to 44 characters long. The length of the serial number and certificate authority distinguished name must be less than 246.

CERTNSER

Specifies the hex value of the next serial number used by this certificate to sign another certificate. Every byte must be specified, including leading zeros.

Size: 16 bytes

START

Specifies an optional activation date. This date is not the same as the activation date defined in the certificate itself. The web server validates that date. This date gives the security administrator the ability to specify when the certificate will become active on MVS.

FOR|UNTIL

Specifies an optional expiration date. This date is not the same as the expiration date defined in the certificate. The web server validates that date. This date gives the security administrator the ability to specify when the certificate will expire on MVS.

LABLCERT

Specifies the label to be associated with the certificate being added to the user. Spaces are allowed if you use single quotation marks. This label is used as an identifier (instead of the serial number and issuer's distinguished name) and must be unique for the individual user. If you do not specify a label, the label field defaults to the value specified within the DIGICERT keyword.
Range: Up to 32 characters

HITRUST|TRUST|NOTRUST

Specifies a trust status for the certificate:

HITRUST: Specifies that the certificate is highly trusted and trusted. Any certificate usage applying to trusted certificates applies to highly trusted certificates. However, only certificate authority certificates (CERTAUTH) can be highly trusted.
TRUST: Specifies that the certificate is trusted, which means the certificate is valid for the user, site, or certificate authority, and the private key has not been compromised. Trusted user certificates can be used to authenticate a user ID. Trusted CERTSITE certificates can be used without authentication. Trusted CERTAUTH certificates can be used to authenticate other certificates
NOTRUST: Specifies that the certificate is not trusted.

If a trust status is not specified, the product determines status as follows:

If the certificate’s signature can be verified, the certificate has not expired, and the certificate’s validity dates fall within the range of the signing certificate, the trust status is set to the trust status of the certificate authority.
The default trust status for self-signed certificates is TRUST.
If the certificate has expired, has an invalid validity date range, or cannot be verified, the trust status is set to NOTRUST.
If the trust status is coming from the signing certificate and the signing certificate has HITRUST, the status of the new certificate becomes TRUST.
If the certificate was signed by another certificate, the status is set to TRUST if the following conditions are met:
- The signing certificate can be located in the database.
- The signing certificate is a certificate authority certificate (CERTAUTH).
- The signing certificate is not expired.
- The signing certificate's signature is valid.
- The validity dates of the certificate being added fall within the range of the signing certificate's validity dates.

If the product cannot determine status through other methods, the certificate is inserted as not trusted (NOTRUST) with a message that explains the reasons.

Note: If the signing certificate's signature is invalid, the certificate is not inserted.

LABLPKDS(PKDS_label|*)

(Optional) Specifies the PKDS label of the record created in the ICSF Public Key Data Set (PKDS). The field can be used with the ICSF, PCICC, NISTECC, or BPECC, but many of these keywords cannot be used together (see individual keyword descriptions for details). If neither ICSF or PCICC is specified, a PCICC key is generated by the hardware and saved in CRT format in the ICSF PKDS. If NISTECC or BPECC is specified, an ECC key is generated; otherwise, an RSA key is generated.

Specify (*) to take the value from the LABLCERT keyword. In that case, LABLCERT is specified alongside LABLPKDS(*).

The PKDS label must conform to ICSF label syntax rules. The first character must be alphabetic or national. The field is folded to uppercase.

A key pair is not generated because the key is taken from the certificate in the data set. If the data set contains a PKCS 12 package, the private key is placed in the ICSF PKDS (with the format being determined by the ICSF or PCICC keywords). If ICSF is also specified, the private key is stored in the ICSF PKDS as an ICSF RSA Modulus-Exponent (ME) key token. If PCICC is specified, the private key is stored as an ICSF RSA Chinese Remainder Theorem (CRT) key token. If the private key has a bit size greater than 1024, PCICC must be specified.

If the data set contains a single certificate or a PKCS 7 chain, the public key is placed in the ICSF PKDS in RSA public key format. If this insertion results in an error (from attempting to insert a record with the same PKDS label as a record that already exists in the PKDS), the product reads the existing record. If that record contains a private key, and the public key being inserted corresponds to the private key, the CA Top Secret record is updated to indicate that a private key exists for the record.

Valid characters: Alphanumeric characters, national (@,#,$) characters, or a period(.).

Limits: Up to 64 characters

ICSF

Specifies to store the private key in the ICSF data facility. The IBM ICSF feature provides an interface to the cryptographic hardware on z/OS. You must have cryptographic hardware installed and enabled on your system. If ICSF, PCICC, or LABLPKDS is not specified with ADD, the key is stored in the security file as a non-ICSF key.

Note: ICSF is valid to create only RSA keys with a length up to 1024 bytes.

PCICC

(Optional) Specifies that the key pair is generated using the PCI Cryptographic Coprocessor and that the private key is stored in ICSF. When PCICC is not specified, the key pair is generated using software. PCICC cannot be used with the DSA, DSN, or ICSF parameters.

If a PCI cryptographic coprocessor is not present or operational or if ICSF is not active or configured for PKA operations, an error message is displayed and processing terminates. If ICSF, PCICC, or LABLPKDS is not specified, the key pair is generated using software and stored in the security file as a non-ICSF key.

PKCSPASS

Specifies the password used to decrypt the PKCS #12 certification package. This password must conform to PKCS 12 standards and must be the same as the password that was specified when the certificate was exported. The password may be mixed case and up to 255 bytes.

Note: A password can be specified only with a PKCS #12 certificate. The product supports only PKCS #12 certificates that adhere to the PKCS #12 v1.0 standard published by RSA. These certificates are defined with a 3 in the version number of the PKCS #12 certificate package.

Example: Use DCDSN to Add a Certificate

This example uses DCDSN:

TSS ADD(USER01) DIGICERT(DIGI0001)
                DCDSN(USER01.CERTIF.001)

Example: Use START to Add a Certificate

This example uses START:

TSS ADD(USER01) DIGICERT(DIGI0001) 
                DCDSN(USER01.CERTIF.001)
                START(10/01/03)

Example: Use FOR|UNTIL to Add a Certificate

These examples use FOR and UNTIL:

TSS ADD(USER01) DIGICERT(DIGI0001)
                DCDSN(USER01.CERTIF.001)
                FOR(30)

TSS ADD(USER01) DIGICERT(DIGI0001)
                DCDSN(USER01.CERTIF.001)
                UNTIL(10/01/03)

Example: Use LABLCERT to Add a Certificate

This example uses LABLCERT:

TSS ADD(USER01) DIGICERT(DIGI0001)
                LABLCERT('label for digicert 001')
                TRUST|NOTRUST | HITRUST

Example: Use TRUST|NOTRUST|HITRUST to Add a Certificate

These examples use TRUST, NOTRUST, and HITRUST:

TSS ADD(USER01) DIGICERT(DIGI0001)
                DCDSN(USER01.CERTIF.001)
                TRUST

TSS ADD(USER01) DIGICERT(DIGI0001)
                DCDSN(USER01.CERTIF.001)
                NOTRUST

TSS ADD(CERTAUTH) DIGICERT(DIGI0001)
                  DCDSN(USER01.CERTIF.001)
                 *HITRUST

Example: Use ICSF to Add a Certificate

This example uses ICSF:

TSS ADD(USER01) DIGICERT(DIGI0001)
                DCDSN(USER04.CERTIF.001)
                ICSF