Process Digital Certificates with CA ACF2

After you enter the ACF command, use these subcommands to create, display, export digital certificates, create certificate requests, associate certificates with key rings, or disassociate certificates from key rings. These subcommands are common to all settings. A detailed description of each subcommand follows.
acf2src
After you enter the ACF command, use these subcommands to create, display, export digital certificates, create certificate requests, associate certificates with key rings, or disassociate certificates from key rings. These subcommands are common to all settings. A detailed description of each subcommand follows.
2
CHKCERT Subcommand
The CHKCERT subcommand is used to display information about an X.509 certificate in a CERTDATA Profile record or a z/OS data set, including whether it is registered with CA ACF2. The certificate can be in DER-encoded or base-64-encoded form (PEM). It can also be a PKCS #12 certificate, which includes the private key that is associated with the certificate.
The CHKCERT subcommand can be issued in any mode of the ACF command. This subcommand has the following syntax:
CHKcert {logonid Label(label) |logonid.suffix | DSname(data-set-name)} [Password(password)] [Nolist] [Dump] [Chain]
Parameter Descriptions
  • logonid Label(
    label
    )
    Indicates the CA ACF2 user whose label is used to specify which CERTDATA record containing the certificate is displayed. For every one apostrophe that is desired in the Label value, two consecutive apostrophes must be specified. For example, the Label value, Frank's Certificate, should be specified as, Frank”s Certificate. If a single apostrophe is specified in the Label value, the value is considered invalid.
  • logonid.suffix
    Indicates the CA ACF2 record id of the CERTDATA record containing the certificate that is displayed.
  • DSname(data-set-name)
    Indicates the name of the data set containing the certificate to be checked. If the data set name is enclosed in single quotes, it is considered fully qualified and is used as specified. Otherwise, the user's prefix, as specified by the TSO PROFILE PREFIX command (or defaulted from the DFT-PFX field of the logonid record), is added to the front of the data set name.
  • Password(
    password
    )
    The password that is associated with a PKCS #12 certificate. This value must be the same password that was specified when the certificate was exported. If you specify PASSWORD without a value and you are in an environment where CA ACF2 can prompt you, you are prompted for the password in a non-display field.
  • Nolist
    Indicates that the CA ACF2 CERTDATA profile record should not be listed, even if the certificate is registered with CA ACF2.
  • Dump
    Indicates to display a hex dump of the certificate before listing the contents of the certificate.
  • Chain
    Instructs the command to display the certificate information for each certificate in the chain from the specified certificate to the highest CA signing certificate in the database. The parameter also applies if the DSNAME was specified instead of the record id. In that case, each certificate in the chain in the input data set is displayed.
    Summary information follows the display. The summary indicates:
    • the number of certificates in the chain
    • an indication if the chain is complete or incomplete,
    • an indication if the chain contains expired or non-trusted certificates.
    If CHKCERT is run against a certificate in the database, the key rings that are common between all certificates in the chain are listed.
    Chain Information:
    • Chain contains two certificates
    • Chain is COMPLETE
    • Chain contains EXPIRED certificates
    • Chain contains NOTRUST certificates
    • Chain contains common ring - PKISRVD.CARING
    • Chain contains common ring - TESTING.RING1
    If CHKCERT is run using the DSNAME parameter, thes message is added to the summary when any certificate that is contained in the data set is not present in the CA ACF2 database.
    • Chain contains certificates not in the database
Examples
The following displays information about the certificate in the FRANK01.MYCERT data set.
CHKCERT DSN('frank01.mycert')
Because the certificate is registered with CA ACF2 and the User Profile Directory has been rebuilt, the CERTDATA profile record is listed.
Data set name: FRANK01.MYCERT Certificate ID: 4gjDxdnjweTjyNeBmZKiQMPB Serial number: 02 Issuer's distinguished name: CN=Blue Lock Company Certificate Authority OU=Auditing Department O=Blue Lock Company C=US Subject's distinguished name: CN=Frank Schwinger OU=Sales Department O=Blue Lock Company C=US Not valid before: 2002/02/02 00:00:00 UTC Not valid after: 2003/12/31 00:00:00 UTC Private Key Type: RSA Private key bit size: 1024 Signature Algorithm: sha-1WithRSAEncryption This certificate is registered with <acf> The CERTDATA record key is FRANK01.MYCERT CERTDATA / FRANK01.MYCERT LAST CHANGED BY ADMIN01 ON 06/23/09-11:23 ISSUERDN(CN=Blue Lock Company Certificate Authority.OU=Auditing Department.O=Blue Lock Company.C=US) KEYSIZE(1,024) LABEL(Frank01 Cert) SERIAL#(02) SUBJDN(CN=Frank Schwinger.OU=Sales Department.O=Blue Lock Company.C=US) TRUST Certificate is not connected to any keyrings
The following examples show the CHKCERT command. Use this command to display a certificate that is contained in a data set or a certificate that is contained in a CA ACF2 User Profile CERTDATA record:
CHKCERT DSN('frank01.mycert') NOLIST CHKCERT frank01.cert DUMP CHKCERT certauth label(Audit CA)
While only a few common attributes usually appear in distinguished names, there are many possible attributes. Attributes that are not recognized by CA ACF2 are displayed in the notation that is recommended by Internet RFC 1779,
A string representation of distinguished names
. For example, the last attribute of the subject's distinguished name is listed as OID.2.5.4.20==#3535352031323132.
CONNECT Subcommand
The CONNECT subcommand is used to associate certificate information with a key ring. When specifying the CERTDATA parameter, the connection is a two-way connection. The KEYRING record contains the record id of the CERTDATA record and the CERTDATA record contains the record id of the KEYRING record. When displaying the key ring record, the record ids of all of the connected certificates are shown. When displaying the certificate, all of the connected key rings are displayed.
When specifying the USER parameter, the connection is a logical connection. Displaying the key ring indicates that all of the users certificates are connected but do not display the individual record ids. Displaying the users certificate records does not indicate that the certificate is connected to this key ring.
The CONNECT subcommand has the following syntax:
CONnect Certdata(userid1.suffix)|USER(userid1) Keyring(userid2.suffix) [Ringname(ringname)] [Label(label)] [Usage({PERSONAL|CERTAUTH|SITE})] [DEFAULT]
Parameter Descriptions
  • CERTDATA(userid1.suffix)
    Specifies the record key of a CERTDATA record to associate with a key ring. The userid1 is a one- to eight-character userid associated with the CERTDATA record. The suffix is one- to eight-characters used to make the record key unique. The suffix is separated from the userid by a period. If LABEL is specified in addition to suffix, then both suffix and the label must refer to the same CERTDATA record.
  • KEYRING(userid2.suffix)
    Specifies the record key of a KEYRING record to which the certificate information is to be associated. The userid2 is a one- to eight-character userid associated with the KEYRING record. The suffix is one- to eight-characters used to make the record key unique. The suffix is separated from the userid by a period, and
    cannot
    be specified when the RINGNAME parameter is used.
  • RINGNAME(
    ringname
    )
    Specifies the ring name of a KEYRING record to which the certificate information is to be associated. The ringname can be up to 237 characters in length.
  • LABEL(
    label
    )
    Specifies the label of a CERTDATA record to associate with a key ring. The label can be up to 32 characters in length. This value can contain blanks and mixed-case characters.
    For every one apostrophe that is desired in the Label value, two consecutive apostrophes must be specified. For example, the Label value, Frank's Certificate, should be specified as, Frank”s Certificate. If a single apostrophe is specified in the Label value, the value is considered invalid.
  • USAGE({PERSONAL|CERTAUTH|SITE})
    Specifies how the certificate is to be used in the key ring. If USAGE is omitted, the usage that is associated with the certificate that is being connected is used. If the private key of the certificate is extracted, USAGE(PERSONAL) must be specified.
    • PERSONAL
      Specifies that the certificate is to be used as a user certificate.
    • CERTAUTH
      Specifies that the certificate is to be used as a certificate authority certificate.
    • SITE
      Specifies that the certificate is to be used as a site certificate.
  • USER(
    userid
    )
    Specifies a userid whose certificate is ALL be associated with the specified key ring. This behavior is similar to the way the ALLCA keyword connects all CERTAUTH certificates to a key ring.
    Certificates must be trusted to be logically connected to the keyring using the USER parameter.
  • DEFAULT
    Specifies that the certificate is to be the default certificate for the key ring. A key ring can have only one default certificate.
    Example
    acf connect certdata(user02.cert1) keyring(user01.ring) usage(site) default acf connect certdata(user02) label(user02 certificate) keyring(user01) ringname(user01 key ring) acf connect user(user01) keyring(user01) ringname(user01 key
EXPORT Subcommand
The EXPORT subcommand is used to export an X.509 digital certificate from the CA ACF2 database and put it into a z/OS data set. The data set can be used to insert the certificate in another system. Conversely, the data set can be downloaded to a personal computer and installed in a web browser. If you send the exported certificate to others that receive messages from you signed with your private key, they can use the public key in the exported certificate to validate those messages. They cannot forge messages from you because they do not have your private key. Your private key can be exported using the PKCS12DER or PKCS12B64 format options. Using these options generates a PKCS #12 certificate package containing the user certificate, its private key, and all certificate-authority certificates necessary to complete the chain of certificates from user certificate to root certificate-authority certificate.
Message ACF68068 is displayed for each certificate that is added into the package in the data set.
The EXPORT command can be issued in any mode of the ACF command. This command has the following syntax:
Export {logonid|logonid.suffix} DSname(data-set-name) [Label(label)] [Format(CERTDER|CERTB64|PKCS12DER|PKCS12B64|PKCS7DER|PKCS7B64)] [Password(password)]
Parameter Descriptions
  • logonid|logonid.suffix
    The record key of the certificate to be exported. This value can be a one- to eight-character logonid or a logonid, a dot, and a one to-eight-character suffix. If LABEL is specified in addition to suffix, then both suffix and the label must refer to the same CERTDATA record.
  • DSname(data-set-name)
    The name of the data set into which the certificate is exported. The data set must not already exist. If the data set name is enclosed in single quotes, it is considered fully qualified and is used as specified. Otherwise, the user's prefix, as specified by the TSO PROFILE PREFIX command (or defaulted from the DFT-PFX field of the logonid record) is added to the front of the data set name.
  • Label(
    label
    )
    The label of the certificate to be exported. Logonid must also be specified to indicate which logonid the label is associated with.
    For every one apostrophe that is desired in the Label value, two consecutive apostrophes must be specified. For example, the Label value, Frank's Certificate, should be specified as, Frank”s Certificate. If a single apostrophe is specified in the Label value, the value is considered invalid.
  • Password(
    password
    )
    A password that is used to encrypt the private key and certificates in a PKCS #12 package. This password does not conform to normal CA ACF2 password syntax and can be mixed case and up to 255 bytes in length. If password is specified, a PKCS #12 package is generated with the user certificate, private key, and CA certificates. If format is not specified, format defaults to PKCS12B64. CA ACF2 only supports PKCS #12 certificates that adhere to the PKCS #12 v1.0 standard that is published by RSA. These certificates are defined with a 3 in the version number of the PKCS #12 certificate package.
    If PASSWORD is specified without a value and you are in an environment where CA ACF2 can prompt you, you are prompted for the password in a non-display field. Because you cannot see the value being entered and the value is being used to encrypt the PKCS 12 package,
    CA ACF2
    prompts twice for the password and compares the two values before using the password for encryption.
  • Format(CERTDER)
    Indicates that the exported certificate should be encoded using the X.509 Distinguished Encoding Rules (DER). This form is the standard for an X.509 certificate. This file is binary, so if it is being transferred using FTP, use the BINARY or IMAGE mode.
  • Format(CERTB64)
    Indicates that the exported certificate should be encoded using base-64 encoding. This encoding is applied to the standard X.509 certificate. Doing so makes it possible to ship the certificate through systems, such as E-mail systems, that cannot handle binary files. This file is in text format, so if it is being transferred using FTP, use the ASCII or TEXT mode. If no format is specified, format(CERTB64) is the default.
  • Format(PKCS12DER)
    Specifies a DER-encoded PKCS#12 certificate package containing the user certificate, its private key, and all certificate-authority certificates necessary to complete the chain of certificates from user to root certificate-authority certificate. If this option is selected, a PASSWORD must also be supplied. Format PKCS12DER must be used to import a PKCS#12 certificate package on Windows, because Windows cannot directly import a PKCS12B64 format PKCS#12 package.
  • Format(PKCS12B64)
    Specifies a DER-encoded then base-64 encoded PKCS #12 certificate package containing the user certificate, its private key, and all certificate-authority certificates necessary to complete the chain of certificates from user to root certificate-authority certificate. If this option is selected, a PASSWORD must also be supplied. If a password has been specified but no format is specified, format (PKCS12B64) is the default.
  • Format(PKCS7DER)
    Specifies a DER encoded PKCS 7 certificate package. This parameter exports a certificate (without the private key) and its CA chain. If a certificate in the chain cannot be found under the CERTAUTH ID or the certificate is expired, an informational message is issued and an incomplete PKCS 7 package is created. CA ACF2 can still process the incomplete package, but it may not be useful to OEM products.
  • Format(PKCS7B64)
    Specifies a base-64 encoded PKCS 7 certificate package. This parameter exports a certificate (without the private key) and its CA chain. If a certificate in the chain cannot be found under the CERTAUTH ID or the certificate is expired, an informational message is issued and an incomplete PKCS 7 package is created. CA ACF2 can still process the incomplete package, but it may not be useful to OEM products.
Examples
The following example exports the certificate with a record key of FRANK01.CERT into a data set named FRANK01.MYCERT, using base-64 encoding.
EXPORT FRANK01.CERT DSNAME(MYCERT)
The following example exports the certificate belonging to user FRANK01, with a label of “Frank01 Cert,” into a data set named PUBLIC.TESTCERT, using DER encoding.
EXPORT FRANK01 LABEL(Frank01 Cert) DSNAME('PUBLIC.TESTCERT') FORMAT(CERTDER)
The following example exports the certificate with a record key of CQLRG.TESTCERT into a data set named CQLRG.TESTCERT.CER, using base-64 encoding.
EXPORT CQLRG.TESTCERT DSNAME(TESTCERT.CER) FORMAT(CERTB64)
The following example exports the certificate and private key with a logonid of FRANK01 and a Label of “Frank01 Cert” into a data set named FRANK01.CERT.P12, using base-64 encoding. This PKCS #12 package also contains the CA certificates that are in the signing chain.
EXPORT FRANK01 DSNAME('FRANK01.CERT.P12') LABEL(Frank01 Cert) PASSWORD(This is my secret and you don't know it)
GENCERT Subcommand
The GENCERT subcommand is used to generate a digital certificate and insert a CERTDATA profile record into the CA ACF2 infostorage database.
The GENCERT subcommand can be issued in any mode of the ACF command. This subcommand has the following syntax:
GENCert { logonid | logonid.suffix | CERTAUTH | CERTAUTH.suffix | SITECERT | SITECERT.suffix } [Label(label)] [DSname(data-set-name)] [SUbjsdn([CN=common-name] [T=title] [OU=organizational-unit-name] [O=organization-name] [L=locality] [{S=state-or-province | SP=state-or-province | ST=state-or-province}] [C=country])] [SIZe({key-size|2048|192})] [PCICC|ICSF|DSA|NISTECC|BPECC] [ACtive({date-or-date-time|current-date-000000| current-date-time})] [Expire({date-or-date-time|current-date-000000| current-date-time})] [SIGnwith({ CERTAUTH Label(label-name) | CERTAUTH.suffix | SITECERT Label(label-name) | SITECERT.suffix) | Label(label-name)})] [HASHALG(SHA1|SHA256)] [Keyusage([HANDSHAKE][DATAENCRYPT] [DOCSIGN][CERTSIGN][KEYAGREE])] [ALtname([IP=numeric-ip-address] [DOMAIN=internet-domain-name] [EMAIL=email-address] [URI=universal-resource-identifier])] [Fromicsf(PKDS label)] [PKDSLBL({PKDS label|*})] [SIGATTR(RSAPSS)]
Parameter Description
  • logonid
    |CERTAUTH|SITECERT
    The logonid specifies the user who is associated with the certificate. The value may be a one- to eight-character logonid, or a logonid, a dot, and a one- to eight-character suffix. The .suffix and label are optional. If the CERTDATA record is the first for this logonid, the GENCERT can be issued without the suffix, but subsequent CERTDATA records with the same logonid must have a unique qualifier/suffix, regardless of the label value. If a suffix is not supplied on the GENCERT for subsequent records with the same logonid, CA ACF2 generates one with the form AUTOnnn.
    Using CERTAUTH in place of a logonid designates the certificate as a Certification Authority certificate.
    Using SITECERT in place of a logonid designates the certificate as a site certificate.
  • Label(
    label
    )
    Specifies a 1-character to 32-character label that the new certificate has. The label can contain blanks and mixed-case characters. If a label is not specified, the label field defaults to the uppercase version of the logonid or logonid.suffix that was specified.
    For every one apostrophe that is desired in the Label value, two consecutive apostrophes must be specified. For example, the Label value, Frank's Certificate, should be specified as, Frank”s Certificate. If a single apostrophe is specified in the Label value, the value is considered invalid.
  • DSname(data-set-name)
    Specifies the data set that contains a PKCS #10 certificate request, as generated by the GENREQ subcommand of the ACF command, or by other certificate management software. If the data set name is enclosed in single quotes, it is considered fully qualified and is used as specified. Otherwise, the user's prefix, as specified by the TSO PROFILE PREFIX command (or defaulted from the DFT-PFX field of the logonid record) is added to the front of the data set name.
    DSNAME is optional. If specified, GENCERT does not generate a public/private key pair. If specified, SIGNWITH must also be specified because the PKCS #10 request does not contain a private key. If SUBJSDN is also specified, the subject's distinguished name is generated from the SUBJSDN that was entered on the command.
    If DSNAME is specified and extensions are present in the PKCS #10 request, and they are not overridden by the other GENCERT keywords, they are copied to the new certificate.
    DSNAME cannot be specified with the SIZE or the FROMICSF parameters.
  • SUbjsdn(…attributes…)
    Specifies the subject’s distinguished name. The attributes can consist of the following fields. Except as otherwise noted, valid characters for the values of the attributes are any printable ASCII character and the characters in Latin-1 Supplemental character set. CA ACF2 assumes that the 1047 code page is being used. Values containing spaces must be enclosed in single quotes. Any apostrophes should be doubled. For example, a common name of John T. O'Reiley would be specified as CN='John T. O”Reiley'. Also, unless otherwise specified, each attribute can only be specified once.
    1. A space is the only valid delimiter between specified attributes.
    2. The maximum length for this parameter for a self-signed certificate is 1007.
    3. The maximum length for this parameter for a non self-signed certificate is 1024.
    4. The maximum length for each attribute of this parameter is 64. Multiple blanks are not removed and are included in the lengths.
    5. If the DSNAME keyword is also present, the subject's distinguished name from the SUBJSDN keyword is used instead of the subject's distinguished name from the PKCS #10 certificate request. If DSNAME and SUBJSDN are not specified, the subject's distinguished name is generated with CN='ACF2 USER:
      logonid
      '.
    • CN=
      common
      -
      name
      Specifies the subject's regular name. For example, Sam Smith would be specified as CN='Sam Smith'. An '*' wildcard character may be used as the leftmost byte of the CN attribute, as in CN='*.example.com'.
    • T=
      title
      Specifies the person's job title. For example, T='Software Developer'.
    • OU=
      organizational
      -
      unit
      -
      name
      Specifies the department or group. This value can be specified multiple times to indicate a hierarchy. For example, OU=Accounting,OU='Accounts Payable'.
    • O=
      organization
      -
      name
      Specifies the name of the company. For example, O='Blue Lock Company'.
    • L=
      locality
      Specifies the city. For example, L='Tom”s River'.
    • S=
      state
      -
      or
      -
      province, SP=state
      -
      or
      -
      province, ST=state
      -
      or
      -
      province
      Specifies the state or province. All three keywords mean the same thing. When the distinguished name is displayed, state or province is displayed using 'ST='. State or province must be expressed using the same abbreviations that are used in mail addresses, for example, ST=IL for Illinois.
    • C=
      country
      Specifies the country. This value must be specified using the two-character ISO 3166 country code. For example, C=US for the United States of America, or C=VA for Vatican City.
  • SIZe({key-size|192-4096})
    Specifies the size of the private key to be generated, in bits. When SIZE is not specified, the default is 1024 for RSA and DSA keys and 192 for NISTECC and BPECC keys.
    Valid key sizes for NISTECC are 192, 224, 256, 384, and 521 bits. Valid key sizes for BPECC keys are 160, 192, 224, 256, 320, 384, and 512 bits. The maximum key size depends on the private key type.
    ICSF has a limit of 1024. GENCERT requests that specify ICSF with no SIZE parameter receives the following error message:
    CA ACF2 Version 16.0:
    ? gencert r16.icsfcert su(cn='r16 cert with ICSF & default 2048 keysize') ICSF ACF0A217 Key size of certificate requires PCI Cryptographic Coprocessor. Specify PCICC instead of ICSF.
    CA ACF2 Version 15.0:
    CERTDATA / R15.ICSFCERT LAST CHANGED BY MASTER ON 11/16/15-12:44 CERTNSER(0000000000000001) ICSF ISSUERDN(CN=r15 cert with ICSF & default 1024 keysize) KEYSIZE(1,024) LABEL(R15.ICSFCERT) SERIAL#(00) SUBJDN(CN=r15 cert with ICSF & default 1024 keysize) TRUST Specify PCICC instead of ICSF.
    *
    RSA keys generated using software can be limited by the KEYSIZE parameter of the GSO OPTS record.
    Private Key Type
    Maximum Key Size
    BPECC key
    512 bits
    NISTECC key
    521 bits
    ICSF RSA key
    1024 bits
    DSA key
    2048 bits
    Non-ICSF RSA key
    4096 bits*
    PCI-class cryptographic coprocessor RSA key
    4096 bits
    You can achieve comparable key strengths with shorter ECC keys when compared to longer RSA keys. The following table displays the comparable strength of each key:
    RSA Key Size
    NISTECC Key Size
    BPECC Key Size
    1024 bits
    192 bits
    160 bits or 192 bits
    2048 bits
    224 bits
    224 bits
    3072 bits
    256 bits
    256 bits or 320 bits
    7680 bits
    384 bits
    384 bits
    15360 bits
    521 bits
    512 bits
    Currently, the standard key sizes for RSA keys are as follows:
    • 512-Specifies a low-strength key
    • 1024-Specifies a medium-strength key
    • 2048-Specifies a high-strength key
    • 4096-Specifies a very high-strength key
  • ICSF
    Indicates that the public or private key is placed in the ICSF PKDS. If the DSNAME parameter was also specified and an existing certificate is to be replaced, the existing private key is moved from the Infostorage database to ICSF. ICSF must be active and configured for PKA operations. If it is not, an error message is displayed when attempting to insert or use the private key. Non-ICSF private keys are stored in a CERTKEYX record that is associated with the CERTDATA record. CERTKEYX records are managed internally by CA ACF2.
  • ACtive({date-or-date-time})
    Indicates the date and time that the certificate becomes active, for example, 04/30/01-154403. If no time is specified, it defaults to 000000. If no date is specified, it defaults to the current day and time. The specified year must be from 1950 to 2049. If an expire date is not also specified, the active year that is specified must be from 1950 to 2048, because the expire date defaults to the active day and time plus one year. Valid date formats include: YY/MM/DD, MM/DD/YY, DD/MM/YY, and DD/MM/YYYY
  • PCICC
    Specifies that the key pair should be generated using the PCI Cryptographic Coprocessor and the private key should be stored in ICSF. An RSA key is stored as an RSA Chinese Remainder Theorem (CRT) key token. An ECC key is stored as an ECC key token. If DSNAME is also specified, the public key of the new certificate is placed in the ICSF PKDS. If a PCI cryptographic coprocessor is not present and operational, or if ICSF is not active or configured for PKA operations, an error message is displayed and processing terminates.
    ICSF must be at the HCR7780 level or higher for ICSF to generate ECC private keys.
  • DSA
    Specifies that the key pair is generated using the Digital Signature Algorithm instead of the RSA algorithm. The DSA algorithm creates key pairs that can be used for signing data while the RSA algorithm creates key pairs that can be used to sign and encrypt data. This parameter cannot be used with the ICSF or PCICC parameters. When specifying the DSA parameter, the SIZE parameter can be as high as 2048.
  • BPECC
    Specifies that the key pair is generated with the elliptic curve algorithm (ECC) in accordance with the standard that is proposed by the ECC Brainpool working group of the Internet Engineering Task Force (IETF). The key is generated using ICSF PKCS #11 functions so the ICSF subsystem must be operational and configured for PKCS #11 operation. ICSF must be at least at the HCR7770 level. The private key is placed in the CA ACF2 database.
    The default key size for BPECC certificates is 192.
    This parameter cannot be specified with the ICSF, DSA, NISTECC, or DSNAME parameters.
  • NISTECC
    Specifies that the key pair is generated with the elliptic curve algorithm (ECC) in accordance with the standard that is proposed by the National Institute of Standards and Technology (NIST). The key is generated using ICSF PKCS #11 functions so the ICSF subsystem must be operational and must configure for the PKCS #11 operation. ICSF must be at least at the HCR7770 level. The private key is placed in the CA ACF2 database.
    The default key SIZE NISTECC certificate is 192.
    This parameter cannot be specified with the ICSF, DSA, BPECC, or DSNAME parameters.
  • FROMICSF(PKDS label)
    Specifies that the public key for this certificate is obtained from ICFS using the specified PKDS label. The private key of the source certificate, if one exists, is not associated with the new certificate. FROMICSF cannot be specified with the DSNAME or SIZE parameters. SIGNWITH must be specified when FROMICSF is specified.
  • PKDSLBL({PKDS label|*})
    Specifies the PKDS label of the record that is created in the ICSF Public Key Data Set (PKDS). The field is used with the ICSF or PCICC keywords. If PKDSLBL is specified without the ICSF or PCICC keywords, the command acts as if PCICC was specified.
    The PKDS label is optional and may be specified as * if the PKDS label should be taken from the LABEL keyword. In either case, the PKDS label must conform to ICSF label syntax rules. The allowed characters are alphanumeric, national (@, #, $), or period (.). The first character must be alphabetic or national. The field can be up to 64 characters and is converted to uppercase.
    If GENCERT is issued without the DSNAME parameter, the following occurs:
    If ICSF is also specified, an RSA private key is stored in the ICSF PKDS as an ICSF RSA Modulus-Exponent key token. For PCICC, an RSA private key is stored as an ICSF RSA Chinese Remainder Theorem (CRT) key token and an ECC private key is stored as an ECC key token. The PKDS label must be unique. If PKDSLBL is not specified, the PKDS label is generated in the format IRR.DIGTCERT.userid.cvtsname.ebcdic-stck-value, where userid is the owning user ID, cvtsname is the system name, which is taken from the CVT, and ebcdic-stck-value is an EBCDIC version of the current store clock value.
    If GENCERT is issued with a DSNAME parameter, the following occurs:
    A key pair is not generated because the public key is taken from the certificate request.
    If the certificate being generated does not have an associated private key, the following occurs:
    If the PKDSLBL was specified and ICSF or PCICC where specified, an RSA public key is stored as an ICSF RSA Modulus-Exponent (ME) key token. An ECC key is stored as an ECC key token. If PKDSLBL is specified and ICSF and PCICC are not specified, the command acts as if PCICC was specified.
    ICSF must be at the HCR7780 level or higher for ICSF to generate ECC private keys.
  • SIGATTR(RSAPSS)
    Indicates the signature to be generated is in the RSASSA-PSS format. The format must be SIGATTR(RSAPSS). Any other value will be an error.
    When requesting am RSASSA-PSS signature, the key size must be in the range of 2048-4096.
    • If the key size is 2048 to 3071, the signature generated is sha256rsapss.
    • If the key size is 3072 to 4095, the signature generated is sha384rsapss.
    • If the key size is 4096, the default signature value is sha512rsapss.
    The signature size is based on the key size of the signing certificate,
    not
    the certificate being generated. For example, if the certificate being generated has a key size of 2048 and the key size of the signer is 3072, the new certificate will generate a sha384rsapss signature.
    • You may override the signature to sha256rsapss by specifying HASHALG(SHA256).
    • The PSS signature will not be propagated if SIGATTR is not specified.
  • HASHALG(SHA1|SHA256)
    Overrides the signing algorithm to be used. SHA1 and SHA256 are the possible values. The HASHALG parameter is only valid when overriding the signing algorithm for RSA signed certificates. The parameter is not valid when signing with DSA or ECC keys.
    The following table indicates the default signing algorithm that is used when HASHALG is not specified. These values meet the current standards for selecting a signature algorithm and we
    do not
    recommend overriding the value. This option is provided for compatibility with other applications that may not support the current signature algorithms.
    The selection of a signature algorithm is based on the key size of the signing certificate, not the key size of the certificate being generated.
    Signing AlgorithmUsed
    Keysize (in bit) of Signing Certificate
    RSA
    NISTECC
    BPECC
    SHA-1
    Less than 2048
    SHA-256
    2048 or more
    192, 224
    160, 192, 224
    SHA-256
    256
    256, 320
    SHA-384
    384
    384
    SHA-512
    521
    512
  • Expire({date-or-date-time})
    Indicates the date and time that the certificate expires, for example, MM/DD/YY. If no time is specified, it defaults to 235959. If no date is specified, it defaults to the active day and time plus one year. The specified year must be from 1950 to 2049.
    The maximum value that can be specified for a certificate expiration date is December 31, 2049 when using CA ACF2. Other platforms may have maximum expiration date values that are less than the maximum value that can be set by CA ACF2. Use caution when setting an expiration date far into the future. If you pass such a certificate to another platform, ensure that the expiration date falls in the guidelines of the other platform.
    Valid date formats include:
    YY/MM/DD, MM/DD/YY, DD/MM/YY, and DD/MM/YYYY.
    SIGnwith({CERTAUTH
    Label
    (label
    -
    name)
    |SITECERT
    Label
    (label
    -
    name)
    }),
    SIGnwith({CERTAUTH
    .suffix
    |SITECERT
    .suffix
    }), SIGnwith(Label
    (label
    -
    name
    ))
    Specifies the certificate that is used to sign the new certificate. If SIGNWITH is not specified, a self-signed certificate is generated.
    If SIGNWITH contains CERTAUTH or SITECERT, a suffix or Label value is used to specify which CERTAUTH or SITECERT certificate is used to sign the certificate.
    If CERTAUTH or SITECERT is not specified, Label must be specified and the label identifies the user certificate that signs the new certificate. The user id that is associated with the label is the user generating the certificate. This option cannot be specified if the certificate being generated is for a CERTAUTH or SITECERT id. For every one apostrophe that is desired in the Label value, two consecutive apostrophes must be specified. For example, the Label value, Frank's Certificate, should be specified as, Frank”s Certificate. If a single apostrophe is specified in the Label value, the value is considered invalid.
  • Keyusage
    Specifies the values of the keyUsage certificate extension. The default for certificate authority certificates is CERTSIGN. CERTSIGN is always set for certificate authority certificates even if not specified. No default exists for non-certificate authority certificates.
    • HANDSHAKE-Sets the digitalSignature and keyEncipherment bits in the keyUsage extension. This value allows identification and key exchange during security handshakes such as SSL. When the key pair is generated using the DSA, NISTECC, or BPECC key word, only digitalSignature is set for this usage. algorithm, only the digitalSignature bit is set because the keys cannot be used for encryption.
    • DATAENCRYPT-Sets the dataEncipherment bit in the keyUsage extension. This value allows the certificate to be used for data encryption. This usage is not valid when the key pair is generated using the DSA, NISTECC, or BPECC key word.
    • DOCSIGN-Sets the nonRepudiation bit in the keyUsage extension. This value allows the certificate to be used in a legally binding signature.
    • CERTSIGN- Sets the keyCertSign and cRLSign bits in the keyUsage extension. This value lets the certificate sign other digital certificates and CRLs.
    • KEYAGREE-Sets the keyAgreement bit in the keyUsage extension. KEYAGREE is only valid for NISTECC and BPECC keys.
      When KEYUSAGE is specified and the target ID is CERTAUTH and keyUsage is present in the PKCS #10 request that is specified in the DSNAME keyword, the request fails if the certSign bit is turned off in the PKCS #10 request. Otherwise, the keyUsage extension is generated as indicated by the KEYUSAGE parameter. In addition, the certSign and cRLSign bits are turned on if not already specified in the KEYUSAGE parameter.
      When KEYUSAGE is specified and the target ID is CERTAUTH but keyUsage is not specified in a PKCS #10 request, the extensions are generated as indicated by the KEYUSAGE parameter. In addition, the certSign and cRLSign bits are turned on if not already specified in the KEYUSAGE parameter.
      When KEYUSAGE is specified and the target ID is not CERTAUTH, the keyUsage extension is generated using the attributes that are specified in the KEYUSAGE parameter.
      When KEYUSAGE is not specified and the target id is CERTAUTH and keyUsage is present in the PKCS #10 request that is specified in the DSNAME keyword, the request fails if the certSign bit is turned off in the PKCS #10 request. Otherwise, the extension is generated using the attributes that are specified in the keyUsage extension in the PKCS #10 request.
      When KEYUSAGE is not specified and the target id is CERTAUTH and the DSNAME keyword is not specified, the keyUsage extension is generated by turning on the certSign and cRLSign bits.
      When KEYUSAGE is not specified and the target id is not CERTAUTH, the extension is generated using the attributes that are specified in the keyUsage extension in the PKCS #10 request, if present. If the keyUsage extension is not present in the PKCS #10 request or the DSNAME keyword was not specified, the keyUsage extension is not created.
      A certificate with no keyUsage other than keyAgreement cannot be used for signing.
  • ALtname
    Specifies the values for the subjectAltName extension. One or more of the values might be specified. The parameter is optional and there is no default. If necessary, the entered values are converted to ASCII.
    • IP=
      numeric
      -
      ip
      -
      address
      Specifies a string containing a fully qualified numeric-ip-address in IPv4 dotted decimal format, IPv6 format, or IPv4 compatible IPv6 address. An IPv4 address is four decimal numbers from 0 through 255 separated by periods. For example: 141.202.1.255
      An IPv6 address has eight parts that are divided by colons with each part a hexadecimal number between 0 and FFFF. For example: 1080:23B4:324:4:3BCD:26:39F4:332
      An IPv4 compatible IPv6 address is a combination of the two, six parts of the IPv6 followed by the IPv4 address. For example: 0:0:0:0:0:FFFF:141.202.1.255
      The maximum field size is 45 bytes.
    • DOMAIN=
      internet
      -
      domain
      -
      name
      Specifies a fully qualified internet domain name, such as http://ca.com. The validity of this value is not checked. The maximum field size is 255 bytes.
    • EMAIL=
      email
      -
      address
      Specifies a fully qualified e-mail address such as [email protected] The maximum field size is 255 bytes.
    • URI=
      universal
      -
      resource
      -
      identifier
      Specifies a universal resource identifier such as http://ca.com. The validity of this field is not checked. The maximum field size is 255 bytes.
      1. The ACF2 GENCERT command supports the ALtname parameter which specifies the IP, DOMAIN, EMAIL, or URI values for the subjectAltName extension. One or more of the values can be specified however multiple entries of the same type are not supported, for example, two DOMAIN or two IP values cannot be specified but one DOMAIN, one IP, one EMAIL and one URI value can be specified in the ALTNAME parameter.
      2. The correct separator character to use within the ALTNAME parameters IP, DOMAIN, EMAIL, or URI of GENCERT is a blank.
  • Certificate Extensions
    When a certificate is generated, certain extensions are created. If a PKCS #10 request is passed as input to GENCERT using the DSNAME parameter, certain extensions are copied from the PKCS #10 request. The logic for the keyUsage extension was listed previously under the KEYUSAGE parameter. The following logic is for the other extension settings:
    • subjectKeyIdentifer
      When DSNAME is specified, the subjectKeyIdentifier is copied from the PKCS #10 request, if it is present.
      If DSNAME is not specified or if the PKCS #10 request does not contain a subjectKeyIdentifer, this extension is created according to Public Key Infrastructure Standards.
    • authorityKeyIdentifier
      If SIGNWITH is specified, this extension is created using the subjectKeyIdentifier value in the SIGNWITH certificate.
      If SIGNWITH is not specified or the SIGNWITH certificate does not contain a subjectKeyIdentifier extension, the authorityKeyIdentifier extension is not created.
    • basicConstraints
      When the target ID is CERTAUTH, and basicConstraints is present in the PKCS #10 request, the command fails if the cA Boolean value is false. Otherwise the extension is generated by turning on the cA bit. Pathlength is not included.
      When the target ID is CERTAUTH and basicConstraints is not present in the PKCS #10 request, the extension is generated by turning on the cA bit. Pathlength is not included.
      When the target ID is not CERTAUTH, and basicConstraints is coded in the PKCS #10 request, basicConstraints is generated using the values set in the PKCS #10 request including the pathLength. If basicConstraints was not present in a PKCS #10 request, the extension is not generated.
    • subjectAltName
      When ALTNAME is specified the subjectAltName extension is generated using the ALTNAME values.
      When ALTNAME is not specified and subjectAltName is present in a PKCS #10 request, the subjectAltName extension is generated using the values present in the PKCS #10 request. If subjectAltName is not present in a PKCS #10 request, the subjectAltName extension is not generated.
    • issuerAltName
      When SIGNWITH is specified, the extension is generated using the subjectAltName value of the signing certificate if the extension is present. Otherwise the extension is not created.
      When SIGNWITH is not specified, the issuerAltName extension is not created.
GENCERT Examples
Generate a self-signed certificate authority certificate from a PKCS #10 request.
gencert certauth.bluelock Subj(CN='Blue Lock Company Certificate Authority' OU='Auditing Department' O='Blue Lock Company' C=US) label(Audit CA) expire(12/31/2020)
This command generates a self-signed certificate authority certificate. A label, Audit CA, was specified for the record and an expiration date of 12/31/2020. Be sure to place an expiration date on your CERTAUTH certificates. The default is one year from the day you create the record. If the expiration date of the CERTAUTH certificate is not more than a year away, subsequent certificates that are signed with the certificate might get warning messages. The subject's distinguished name and the issuer's distinguished name are generated using the inputted SUBJSDN value. Because the certificate is self-signed, the TRUST flag is automatically set and the serial number is 00.
The resulting CERTDATA record would look like as follows:
CERTDATA / CERTAUTH.BLUELOCK LAST CHANGED BY FRANK01 ON 02/02/02-10:34 ISSUERDN(CN=Blue Lock Company Certificate Authority.OU=Auditing Department O=Blue Lock Company.C=US) CERTNSER(0000000000000001) KEYSIZE(1,024) LABEL(Audit CA) SERIAL#(00) SUBJDN(CN=Blue Lock Company Certificate Authority.OU=Auditing Department.O=Blue Lock Company.C=US) TRUST Certificate is not connected to any key rings
Generate a SITECERT certificate for the company's web server.
gencert sitecert.blcweb Subj(CN='Blue Lock Web Server Certificate' OU='Auditing Department'O='Blue Lock Company' C=US) label(BL Web Server) signwith(certauth Label(Audit CA)) expire(12/31/2020)
This command generated a certificate that is signed by the CERTAUTH certificate we simply created. The serial number and issuer's distinguished name were taken from the signing certificate. We expect the web server to be in place for quite some time so a generous expiration date was also supplied. The resulting CERTDATA record would look as follows:
CERTDATA / SITECERT.BLCWEB LAST CHANGED BY FRANK01 ON 02/02/02-11:08 ISSUERDN(CN=Blue Lock Company Certificate Authority.OU=Auditing Department.O=Blue Lock Company.C=US) KEYSIZE(1,024)LABEL(BL Web Server) SERIAL#(01) SUBJDN(CN=Blue Lock Web Server Certificate.OU=Auditing Department.O=Blue Lock Company.C=US)TRUST Certificate is not connected to any key rings
Generate a user certificate, signed with a certificate authority certificate.
gencert frank01.cert Subj(cn='Frank Schwinger' OU='Sales Department' O='Blue Lock Company' C=US) label(Frank01 Cert) signwith(certauth Label(Audit CA)) expire(12/31/2003)
This user certificate is also signed with the Audit CA CERTAUTH certificate. This certificate was given a less generous expiration date. We can renew Frank's certificate if he is still with the company next year. The certificate is trusted because the signing certificate is trusted.
CERTDATA / FRANK01.CERT LAST CHANGED BY CUNKE01 ON 02/02/02-11:23 ISSUERDN(CN=Blue Lock Company Certificate Authority.OU=Auditing Department.O=Blue Lock Company.C=US) KEYSIZE(1,024) LABEL(Frank01 Cert) SERIAL#(02) SUBJDN(CN=Frank Schwinger.OU=Sales Department. O=Blue Lock Company.C=US) TRUST Certificate is not connected to any key rings
GENREQ Subcommand
Use the GENREQ command to generate a certificate request to a Certification Authority to create a new signed certificate. GENREQ processing extracts the subject's distinguished name and public key from an existing certificate, packages it in PKCS #10 format, signs it with the certificate's private key, base-64 encodes the result, and writes it to a data set. This certificate request is then sent to a Certification Authority, which then creates (and signs) a new certificate with the same distinguished name and public key.
For NISTECC or BPECC certificates, the certificate request is signed using ICSF PKCS #11 operation. ICSF must be active, must be configured for P11 operations, and must be at least at the HCR7770 level. Also, when keyAgreement is the only key usage, the certificate cannot be used for signing. Therefore, you cannot use GENREQ to create a certificate request based on the certificate.
The GENREQ command can be issued in any mode of the ACF command. Issuing the command against a certificate adds the GENREQ option to the CERTDATA record. Issuing a GENREQ command indicates that you are attempting to renew the specified certificate. During the renewal process, a signed certificate is eventually inserted on top of the original certificate. If you have not re-inserted the signed certificate, the product prevents deletion of the original certificate. Retaining the original certificate prevents the loss of a private key when the product inserts the new certificate over the original certificate. Losing the key prematurely would render the new certificate useless.
You can forcibly remove the original certificate by using the FORCE keyword as part of a DELETE command.
The GENREQ subcommand has the following syntax:
GENReq {logonid|logonid.suffix} DSname(dataset_name) [Label(label)]
  • logonid
    |
    logonid
    .
    suffix
    Specifies the record key of the certificate to use to obtain the distinguished name and public key for the request (if Label is not also specified). This value is a one- to eight-character logonid, or a logonid, a dot, and a one- to eight-character suffix.
    If Label is also specified, logonid, rather than logonid.suffix, must be specified and indicates the logonid with which the label is associated.
  • DSname(
    dataset_name
    )
    Specifies the name of the data set into which the certificate request is written. The data set must not already exist. A data set name that is enclosed in single quotation marks is considered fully qualified and is used as specified. Otherwise, the user's prefix, as specified by the TSO PROFILE PREFIX command (or defaulted from the DFT-PFX field of the logonid record) is added to the front of the data set name.
  • Label(
    label
    )
    Specifies the label of the certificate that is used to obtain the distinguished name and public key for the request. Logonid must also be specified to indicate the logonid with which the label is associated.
    For every one apostrophe that you want in the Label value, you must specify two consecutive apostrophes. For example, the Label value Frank's Certificate should be specified as Frank”s Certificate. A value that contains a single apostrophe is considered invalid.
    Example: Generate a Certificate Request Based On a Logonid and Suffix
This example command, issued by user FRANK01, generates a certificate request (based on the FRANK01.CERT certificate) and writes it to a data set named FRANK01.TESTREQ.REQ:
genreq frank01.cert dsn(TESTREQ.REQ)
Example: Generate a Certificate Request Based On a Logonid and Label
This example command shows how to use a label to indicate which one of Frank's certificates is used in the GENREQ request:
genreq frank01 label(Frank01 Cert) dsn('joseph01.testreq2.req')
Example: Sample Generated Certificate Request
This example shows a sample generated request:
Server: CA-SAF REL 1.3 Subject's distinguished name: CN=Frank Schwinger OU=Sales Department O=Blue Lock Company C=US -----BEGIN NEW CERTIFICATE REQUEST----- MIIBkwI4AsBf9R0wGwYJKoZIhvcNAQkBFg5kbWFnZWVAbWliLmNvbTEVMBMGA1UE AxMMRGVubmlzIE1hZ2VlMQwwCgYDVQQFEwMwMDExDDAKBgNVBAogA01JQjELMAkG A1UEBjCBnTANBgkqhkiG9w0BAQEFAAOBiwAwgYcCgYEA6SSBPS7HrK1WAOaU3QeN g+F85qvzyPh+VZLhihFR6IdX149OtAIhQFG+479EnpW2prJyjFr2Xd19jV4QxCHZ q8RYeVzU0+lrJPPRHLQGYUdx/lYvGv/LzwZOiWn+OwRdTqkxKTPr/IH0weIXW0Xg j2rhi1YQK8xpm7IpdwEw+eECAQOgADqxBgkqhkiG9w0BAQQDgYEALsTCqYSqfLXH 9aZ8lx1tj0pBcsSIgqKf9BF2KxM2i9PfTxuqnuLt3dQcM/MBJp0oKvFlNaUfevkt 4eoljTkZZ+WBq4s9Lwx7c/K6O9CMGG59j2VvhxRBIbhhzQN1SoOX/tf50y6kQmMP cnUi93gpQIaopR/zQvjJhUN7TZAwUJE -----END NEW CERTIFICATE REQUEST-----
INSERT Subcommand
The INSERT subcommand is used to add certificates into the CA ACF2 database. The certificates come from a data set that contains an X.509 certificate, a PKCS #7 chain of certificates, or a PKCS #12 chain of certificates with a private key. Message ACF6D074 is issued listing the record id of each certificate that is inserted by the command.
The INSERT subcommand has the following syntax:
Insert {logonid|logonid.suffix| CERTAUTH|CERTAUTH.suffix| SITECERT| SITECERT.suffix } [Active(date)] DSname(data set name) [Expire(date)] [Label(label)] [Password(password)] [HITRUST|TRUST|NOTRUST] [ICSF|PCICC] [PKDSLBL({PKDS label|*})]
Parameter Descriptions
  • logonid|logonid.suffix|CERTAUTH|CERTAUTH.suffix|SITECERT|SITECERT.suffix
    Specifies the record key that is used to save the certificate in the database. If a suffix is not specified, the label parameter must also be specified.
  • Active(
    date
    )
    Specifies an optional activation date in the format mm/dd/yy. This date is not the same as the not-before validity date in the certificate itself. The active date gives the security administrator the ability to specify when the profile record associating the user to the certificate becomes active. The date must fall in the range of the certificate's not-before and not-after validity dates and must be earlier than the CERTDATA record expiration date, if one exists.
  • DSname(
    data-set-name
    )
    Specifies the z/OS data set that contains the digital certificate that is inserted into a CERTDATA profile record. The data set must be defined as physical sequential (DSORG=PS) and variable blocked (RECFM=VB) and must be cataloged. If the data set name is enclosed in single quotes, it is considered fully qualified and is used as specified. Otherwise, the user's prefix, as specified by the TSO PROFILE PREFIX command (or defaulted from the DFT PFX field of the logonid record), is added to the front of the data set name.
    All of the Certificate Authority certificates that are contained in a PKCS 7 or PKCS 12 certificate package are inserted in addition to the end-entity certificate specified on the insert command. PKCS 7 and PKCS 12 certificate packages generally contain an end-entity user certificate and a chain of Certificate Authority certificates. When a certificate is inserted from a data set, each of the CA certificates is added to the database from the highest CA certificate in the chain to the lowest certificate in the chain. The trust status of the first CA certificate added takes the value that is specified on the Insert command. The other CA certificates that are added take the trust value of the signing certificate. If a certificate is expired or its validity period is not completely within the validity period of its signing certificate, or if the signing certificate of the certificate is not in the PKCS 7 or PKCS 12 package or not in CA ACF2, then the certificate is added with a trust status of NOTRUST. If the CA certificate is already known to CA ACF2, the certificate retains it is trust status. A label of AUTOxxx is generated for each CA certificate added where
    xxx
    is an available number from 1 through 999.
    If an error occurs during the addition of certificates from a PKCS 7 or PKCS 12 certificate package, any CERTAUTH certificates already added are not removed.
    Certificates containing critical extensions that are not supported cannot be inserted into CA ACF2. Noncritical extensions are ignored. The critical extensions that are supported by CA ACF2 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
  • Expire(
    date
    )
    Specifies an optional expiration date in the format mm/dd/yy. This date is not the same as the not-after validity date in the certificate itself. The expire date gives the security administrator the ability to specify when the profile record associating the user to the certificate expires. The date must fall in the range of the certificate's not-before and not-after validity dates and must be later than the CERTDATA record activation date, if one exists.
  • Label(
    label
    )
    Specifies a 32 character label to be associated with the certificate. The label can contain blanks and mixed-case characters. If a label is not specified, the label field defaults to the uppercase version of the logonid that was specified.
  • Password(
    password
    )
    Specifies the password that is used to decrypt the PKCS #12 certification package. This password does not conform to normal CA ACF2 password syntax and may be mixed case and up to 255 bytes in length. CA ACF2 only supports PKCS #12 certificates that adhere to the PKCS #12 v1.0 standard that is published by RSA. These certificates are defined with a 3 in the version number of the PKCS #12 certificate package. This password must be the same as the password that was specified when the certificate was exported. A password can only be specified with a PKCS #12 certificate.
    The PASSWORD value is only valid when dealing with PKCS 12 packages. If you specify PASSWORD without a value and you are in an environment where CA ACF2 can prompt you, you are prompted for the password in a non-display field. For special processing of the password when exporting a certificate package to a data set, see the Export subcommand.
  • HITRUST|TRUST|NOTRUST
    Specifies a trust status for the certificate.
    • HITRUST
      Indicates that the certificate is both highly trusted and trusted. Any certificate usage applying to trusted certificates applies to highly trusted certificates. However, only Certification Authority certificates (CERTAUTH) can be highly trusted.
    • TRUST
      Indicates that the certificate is trusted. For example, that the certificate is valid for the user, site, or certificate authority, and the private key has not been compromised.
      The following behavior applies when no trust status has been specified:
      • If the certificate’s signature can be verified and 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 that of the certificate authority. The default trust status for self-signed certificates is TRUST. If the certificate being added or generated has expired or has an invalid validity date range, or the certificate cannot be verified, then 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 is set to TRUST.
        If no trust status has been specified and the certificate was signed by another certificate, by default, the status is set to TRUST only if the following conditions are met:
        - The signing certificate can be located in the database.
        - The signing certificate is a Certification Authority (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.
      Otherwise, the certificate is inserted as not trusted (NOTRUST) and an informational message is issued stating the reason why. However, if the signing certificate's signature is invalid, the certificate is not inserted.
      • USER certificate -- TRUST indicates that the certificate can be used to authenticate a userid.
      • SITECERT certificate -- TRUST indicates that the certificate can be used without authenticating it.
      • CERTAUTH certificate -- TRUST indicates that the certificate can be used to authenticate other certificates.
      • NOTRUST indicates that the certificate is not trusted. If NOTRUST is specified or set by default, when the CERTDATA record is displayed, no trust value is displayed; the trust field remains blank.
        insert CERTAUTH.CERT4 dsname('Mylid.cacert) NOTRUST CERTDATA / CERTAUTH.CERT4 LAST CHANGED BY FRANK01 ON 01/16/09 11:34 CERTID(0000000000000000.CN=this is a CA.OU=acf2) LABEL(CERTAUTH.CERT4) SUBJDN(CN=this is a CA.OU=acf2)
  • PKCS7 and PKCS 12
    On an insert of PKCS 7 certificate packages, if there is more than one certificate in the package, the second through last certificate are considered to be CA certificates. On an insert of PKCS 12 certificate packages, any certificate that does not have a “local key id” is considered to be a certificate authority certificate.
    The certificate authority certificates are sorted to determine the hierarchy. They are then inserted under the CERTAUTH id from the top CA to the lowest CA so that each certificate in the package can be verified using its previously inserted signing certificate. The end-entity certificate is then inserted. The CA certificates that are inserted have a record id and label in the CERTAUTH.AUTOnnn format, where the nnn is a number from 0 through 1000. The highest level CA certificate does not necessarily have an AUTOnnn number less that the other CA certificates being inserted. The following rules apply to the CA certificates added from a PKCS 7 or PKCS 12 chain. If rules conflict the first one that matches applies.
    • If the certificate is already inserted and has HITRUST status, the certificate retains the HITRUST status.
    • The trust status that is specified on the command applies to the top-level CA certificate. This parameter sets up the TRUST status so that subsequent inserts of the other CA certificates and end-entity certificate can inherit the status from its signing certificate. The HITRUST status is ignored if the recorded is for an id other then CERTAUTH.
    • When no trust status is specified for all lower CA’s in the certificate chain, the trust status is as follows:
      • If the certificate has one or more of the following inconsistencies, the certificate is added with NOTRUST status.
      • The certificate is expired.
      • The validity period does not fall within the signer’s validity period.
      • The issuer of the certificate is missing from the package and is not already in the CA ACF2 database.
      • The certificate has an unknown signature algorithm.
      • If no inconsistencies are detected, the certificate is added and inherits the trust status of its signing certificate.
      • HITRUST is inherited from the parent only if the target logonid on the insert command is CERTAUTH. In all other cases, the trust status changes to TRUST.
      • If an error occurs during an insert from a PKCS 7 or PKCS 12 certificate package, there is no back-out processing. Any certificates added are not removed.
  • ICSF
    Specifies the private key for the certificate is placed in ICSF. If ICSF is specified and a private key exists for the certificate in the CA ACF2 database, the private key is moved from the CA ACF2 database into ICSF.
    Non-ICSF private keys are stored in a CERTKEYX record that is associated with the CERTDATA record. CERTKEYX records are managed internally by CA ACF2.
  • PCICC
    Indicates that the public or private key is placed in the ICSF PKDS. The PKDS label that is associated with the key is listed under the CHKCERT command. If PCICC is specified and a private key exists in the CA ACF2 database, the private key is moved from the CA ACF2 database into ICSF.
  • PKDSLBL({PKDS label|*})
    Specifies the PKDS label of the record that is created in the ICSF Public Key Data Set (PKDS). The field is used with the ICSF or PCICC keywords. If PKDSLBL is specified without the ICSF or PCICC keywords the command acts as if PCICC was specified.
    The PKDS label is optional and may be specified as * if the PKDS label should be taken from the LABEL keyword. In either case, the PKDS label must conform to ICSF label syntax rules. The allowed characters are alphanumeric or national. The field can be up to 64 characters and is converted to uppercase.
    A key pair is not generated because the key is taken from the certificate in the data set.
    If the dataset contains a PKCS 12 package, the private key is placed into the ICSF PKDS. The format is 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 into the ICSF PKDS in RSA public key format. If this insert results in an error that indicates we are attempting to insert a record with the same PKDS label as a record that already exists in the PKDS, the existing record is read. If that record contains a private key and the public key we are attempting to insert is public key that corresponds to the private key, an error is not returned. The CA ACF2 record being inserted is updated to indicate that a private key exists for the record.
P11TOKEN Subcommand
PKCS #11 is a cryptographic token interface standard from RSA Laboratories of RSA Security Inc. This subcommand specifies an application programming interface to devices, called tokens, that hold cryptographic information and perform cryptographic functions. z/OS 1.9 supports PKCS #11 with its Integrated Cryptographic Service Facility (ICSF). CA ACF2 supports PKCS # on z/OS 1.9 systems and higher through ICSF services.
On z/OS, PKCS #11 tokens are virtual smart cards that contain certificates, public keys, and private keys. Conceptually, PKCS #11 tokens are similar to key rings. CA ACF2 introduces the new P11TOKEN command that allows you to define and manage certain objects within a PKCS #11 token.
The following functions are available under the P11TOKEN command:
  • ADD
    Creates an empty token.
  • DELETE
    Removes objects from the token and deletes the token.
  • BIND
    Connects a CA ACF2 certificate, its public key, and possibly its private key to an existing token.
  • LIST
    Displays information about the objects that are contained in the token.
  • UNBIND
    Removes a certificate and its keys from an existing token.
  • IMPORT
    Copies a certificate and its keys from an existing token into the CA ACF2 database.
Applications use the R_datalib callable service to obtain certificates and keys from CA ACF2. The applications must be authorized to extract this information from PKCS #11 tokens and CA ACF2 key rings. For more information, see the
z/OS Security Server RACF Callable Services Guide
.
Resources are in the CRYPTOZ class control access to tokens. For information about the resources that are required to access tokens, see "Controlling Access to Tokens" in the
z/OS Cryptographic Services ICSF Writing PKCS #11 Applications Guide
.
PKCS #11 tokens are managed by ICSF. When CA ACF2 binds a certificate to a token by invoking the ICSF Services, the certificate and its keys are copied into the token. Any change to the certificate or keys in the token is not reflected in the CA ACF2 copy of the same certificate simply as a change made to the certificate in CA ACF2 is not reflected in the token copy. If a certificate is deleted from either CA ACF2 or a token, the corresponding certificate is not deleted.
ICSF only returns the tokens to callers who are authorized to the tokens. For this reason, scoped security officers may receive a "token not found" message instead of a "not authorized" message, when the token is not within their scope.
ADD Function
The following ADD function creates a PKCS #11 token in ICSF. The token-name specified must not already exist.
Add Token(token-name)
Parameter Descriptions
  • Token(
    token-name
    )
    A token-name can be up to 32 bytes. Alphanumeric, national characters (@ x'5B', # x'7B' or $ x'7C') and periods x'4B' are allowed. The first character must be alphabetic or national. Lowercase letters are folded into uppercase.
    Authorization to create and access PKCS #11 tokens is controlled by resources in the CRYPTOZ class. The resources are in the format of SO.token-name and USER.token-name. Token names should be generated with an eye toward the rules that protect them. Consider masking when generating the token names. A token in the format of user.token (WEBSRV.TOKEN1) might be easier to write rules for than a free form token (A.TOKEN.FOR.BOB).
Example
acf p11token add token(websrv.token) Token name: WEBSRV.TOKEN Sequence Labels Attributes -------- ---------------------------- ----------------------- No objects exist for this token
BIND Function
The following BIND function connects a certificate to a PKCS #11 token. The token-name specified must already exist. The certificate must exist in CA ACF2 before the BIND command.
Bind Token(token-name) Certdata(logonid|logonid.suffix)[label(label)] [Usage(PERSONAL|SITE|CERTAUTH)][DEFault]
Parameter Descriptions
  • Token(
    token-name
    )
    A token-name can be up to 32 bytes. Alphanumeric, national characters (@ x'5B', # x'7B' or $ x'7C') and periods x'4B' are allowed. The first character must be alphabetic or national. Lowercase letters are folded into uppercase.
  • Certdata(
    logonid
    |
    logonid.suffix
    )
    Identifies the certificate in CA ACF2 to be bound to the PKCS #11 token. If logonid is specified, label may need to be specified too.
  • Label(
    label
    )
    The 32 character label of the certificate in CA ACF2. Label may be used with CERTDATA to identify the certificate in CA ACF2 that is bound to the PKCS #11 token.
  • Usage({PERSONAL|CERTAUTH|SITE})
    Specifies how the certificate is to be used in the PKCS #11. If USAGE is omitted, the usage that is associated with the certificate that is being connected is used.
    • PERSONAL
      Specifies that the certificate is to be used as a user certificate.
    • CERTAUTH
      Specifies that the certificate is to be used as a certificate authority certificate.
    • SITE
      Specifies that the certificate is to be used as a site certificate.
    The Usage parameter affects the authority that is required in the CRYPTOZ class to bind and use a certificate in a PKCS #11 token. For information about the resources that are required to access tokens, see "Controlling Access to Tokens" section in the
    z/OS Cryptographic Services ICSF Writing PKCS #11 Applications Guide
    .
  • DEFAULT
    Indicates that the certificate is the default certificate in the token. Only one certificate may be the default certificate in a token. If default is specified and other certificate is found with the default attribute, the default attribute is removed and the specified certificate becomes the default.
Example
acf p11token bind token(websrv.token) cert(test.bind) Token name: MY.TOKEN Sequence Labels Attributes -------- ------------------------------------- ----------------------------- 00000001 TKDS:Websrver Certificate Usage(Personal) Default(No) ACF2:Websrver Certificate PubKey(Yes) PvtKey(Yes) ACF2USER(WEBSRV)
DELETE FUNCTION
The following DELETE function deletes a PKCS #11 token in ICSF. The token-name specified must already exist.
DELete Token(token-name)[FORCE]
Parameter Descriptions
  • Token(
    token-name
    )
    A token-name can be up to 32 bytes. Alphanumeric, national characters (@ x'5B', # x'7B' or $ x'7C') and periods x'4B' are allowed. The first character must be alphabetic or national. Lowercase letters are folded into uppercase.
  • FORCE
    Force must be specified if any object in the token (certificates or private keys) is not defined to CA ACF2. This parameter prevents the inadvertent deletion of objects that are not defined in CA ACF2.
Example
acf p11token delete token(websrv.token) ACF68109 PKCS 11 token WEBSRV.TOKEN deleted
IMPORT Function
Copy a certificate and its private key, if present, from a PKCS #11 token to the CA ACF2 database. IMPORT processes the certificate and private key the same way INSERT processes certificates and private keys regarding re-adding a certificate or renewing a certificate. The trust status is determined in the same way. The SEQNUM parameter identifies the certificate within the token and the CERTDATA and LABEL parameters indicate the CA ACF2 record that is created.
Import has the following syntax:
IMport Token(token-name) Seqnum(sequence #) Certdata(logonid | logonid.suffix) [Label(label)][ICSF][PCICC][Pkdslbl(pkds-label)]
Parameter Descriptions
  • Token(token-name)
    A token-name can be up to 32 bytes. Alphanumeric, national characters (@ x'5B', # x'7B' or $ x'7C') and periods x'4B' are allowed. The first character must be alphabetic or national. Lowercase letters are folded into uppercase. The token must exist.
  • Seqnum(sequence-number)
    Indicates the sequence number of the certificate in the PKCS #11 token that is inserted into the CA-ACF2 database. The sequence number can be found in the output of a P11TOKEN LIST command. SEQNUM must be specified on the IMPORT command.
  • Certdata(logonid | logonid.suffix)
    Indicates the record id that the certificate is inserted under. The suffix is optional unless a CERTDATA record already exists without a suffix. CERTDATA must be specified.
  • Label(label)
    The 32-character label of the certificate being inserted. If not specified, the label defaults to the record id.
  • ICSF
    Specifies the RSA private key (or public key if the private key is not in the PKCS #11 token) for the certificate is placed in ICSF using the RSA Modulus-Exponent (ME) key token format. The PKDS label that is associated with the key is listed under the CHKCERT command.
    Non-ICSF private keys are stored in a CERTKEYX record that is associated with the CERTDATA record. CERTKEYX records are managed internally by CA ACF2. ICSF can only be specified for RSA certificates with a key size 1024 bits or less.
  • PCICC
    Indicates that RSA private key (or public key if the private key is not in the PKCS #11 token) for the certificate is placed in ICSF using the RSA Chinese Remainder Theorem key token format. If the key pair is an ECC key pair, the key is placed in ICSF using the ECC key token format. The PKDS label that is associated with the key is listed under the CHKCERT command. PCICC can only be specified for RSA or ECC certificates. ICSF must be running at the HCR7780 level for ECC keys to be saved in the ICSF PKDS.
  • PKDSLBL({PKDS label|*})
    Specifies the PKDS label of the record that is created in the ICSF Public Key Data Set (PKDS). The field is used with the ICSF or PCICC keywords. The PKDS label is optional and may be specified as * if the PKDS label should be taken from the LABEL keyword. In either case, the PKDS label must conform to ICSF label syntax rules. The allowed characters are alphanumeric or national. The field can be up to 64 characters and is converted to uppercase.
    The PKDS label must be unique. If PKDSLBL is not specified, the PKDS label is generated in the format IRR.DIGTCERT.userid.cvtsname.ebcdicstck-value. Where userid is the owning user ID, cvtsname is the system name, which is taken from the CVT, and ebcdic-stck-value is an EBCDIC version of the current store clock value.
    If PKDSLBL is specified and ICSF and PCICC are not specified, the import acts as if PCICC was specified.
Example
acf p11token import token(websrv.token) seq(1) certdata(websrv.server) label(Webserver Certificate) CERTDATA / WEBSRV.SERVER LAST CHANGED BY AAABB01 ON 06/23/07-13:58 ISSUERDN(CN=Test Certificate Authority.O=CA Technologies) KEYSIZE(1,024) LABEL(Websrver Certificate) SERIAL#(04) SUBJDN(CN=uswebsv1.ca.com.O=CA TECHNOLOGIES) TRUST Certificate is not connected to any key rings
LIST Function
Lists the contents of a PKCS #11 token. The token-name specified must already exist. The List function displays the following data:
  • certificate sequence number, the TKDS label
  • CA ACF2 label if the certificate exists in the CA ACF2 database
  • usage that is defined in the token
  • a default indicator
  • indicators that public and private key objects exist within the token
  • logonid that is associated with the certificate if it exists in CA ACF2.
LIST has the following syntax:
List Token(token-name)|Mtoken(token-mask)
Parameter Descriptions
  • Token(
    token-name
    )
    A token-name can be up to 32 bytes. Alphanumeric, national characters (@ x'5B', # x'7B' or $ x'7C') and periods x'4B' are allowed. The first character must be alphabetic or national. Lowercase letters are folded into uppercase.
  • Mtoken(
    token-mask
    )
    Specifies a token-name mask using standard CA ACF2 masking characters.
Example
acf p11token list token(websrv.token) Token name: WEBSRV.TOKEN Sequence Labels Attributes -------- ------------------------------------- ----------------------------- 00000001 TKDS:Websrver Certificate Usage(Personal) Default(No) ACF2:Websrver Certificate PubKey(Yes) PvtKey(Yes) ACF2USER(WEBSRV)
UNBIND Function
Remove a certificate and its keys from the PKCS #11 token. The certificate can be identified by either the sequence number value or the CA ACF2 logonid and label. The certificate to be removed from the token can be identified by either SEQNUM or the combination of CERTDATA and LABEL. If any certificate-related objects exist in the token but not the CA ACF2 database, the FORCE parameter must be used. This parameter prevents the inadvertent deletion of objects that are not in the CA ACF2 database.
Unbind has the following syntax:
Unbind Token(token-name) Seqnum(sequence #) Certdata(logonid | logonid.suffix) [Label(label)][Force]
Parameter Descriptions
  • Token(
    token-name
    )
    A token-name can be up to 32 bytes. Alphanumeric, national characters (@ x'5B', # x'7B' or $ x'7C') and periods x'4B' are allowed. The first character must be alphabetic or national. Lowercase letters are folded into uppercase. The token must exist.
  • Seqnum(
    sequence-number
    )
    Indicates the sequence number of the certificate in the PKCS #11 token that is removed from the token. The sequence number can be found in the output of a P11TOKEN LIST command.
  • Certdata(logonid|logonid.suffix)
    CERTDATA can be used instead of SEQNUM to identify the certificate to be removed from the PKCS #11 token. If the logonid option is used without a suffix, LABEL is required identify the correct certificate.
  • Label(
    label
    )
    The 32-character label of the certificate being removed.
  • FORCE
    Force must be specified if any object in the token (certificates or private keys) is not defined to CA ACF2. This prevents the inadvertent deletion of objects that are not defined in CA ACF2.
Example
acf p11token unbind token(websrv.token) seq(1) Token name: WEBSRV.TOKEN Sequence Labels Attributes -------- ------------------------------------- ----------------------------- No objects exist for this token
REKEY Subcommand
The REKEY subcommand is used to create a certificate from an existing certificate with a new public/private key pair. The REKEY command is the first step of a rekey rollover process to retire the use of an existing private key. The REKEY subcommand also copies the subject's distinguished name, key usage, and subject alternate name from the existing certificate. The new certificate is self-signed and saved under the same logonid or CERTAUTH or SITECERT.
REKEY processing prevents the downgrade from an ICSF/PCICC private key to a private key stored in the security product database. If none of the following keywords are specified on the REKEY command, REKEY uses what is on the original certificate:
  • ICSF
  • PCICC
  • NISTECC
  • BPECC
REKEYing from NISTECC or BPECC certificate to non-ECC certificate is not allowed. REKEYing from a non-ECC certificate to a NISTECC or BPECC certificate is not allowed. If going from NISTECC to NISTECC or from BPECC to BPECC, nothing needs to be specified. Specify NISTECC to go from BPECC to NISTECC. Specify BPECC to go from NISTECC to BPECC.
REKey {logonid|logonid.suffix|CERTAUTH|CERTAUTH.suffix|SITECERT|SITECERT.suffix} [Label(existing-certificate-label)] [WITHLbl(new-certificate-label)] [WITHSfx(new-certificate-suffix)] [SIZe({key-size})] [ICSF|PCICC|DSA|NISTECC|BPECC] [ACtive({date-or-date-time|current-date-000000|current-date-time})] [Expire({date-or-date-time|current-date-000000|current-date-time})] [PKDSLBL({PKDS label|*})] [SIGATTR(RSAPSS)]
Parameter Descriptions
  • logonid
    |logonid.suffix|CERTAUTH|SITECERT
    The logonid specifies the user who is associated with the certificate. It may be a one- to eight-character logonid, or a logonid, a dot, and a one- to eight-character suffix. If label is specified, logonid, rather than logonid.suffix, must be specified, and indicates the logonid with which the label is associated.
  • Label(
    label
    )
    Specifies a 1-character to 32-character label of the existing certificate. The label can contain blanks and mixed-case characters.
    For every one apostrophe that is desired in the Label value, two consecutive apostrophes must be specified. For example, the Label value, Frank's Certificate, should be specified as, Frank”s Certificate. If a single apostrophe is specified in the Label value, the value is considered invalid.
  • WITHLbl(
    label
    )
    Specifies a 1-character to 32-character label for the new certificate. The WITHLBL value can contain blanks and mixed-case characters. It must be unique to the logonid with which the new certificate is associated. If WITHLBL is not specified, the label field of the new certificate defaults to the uppercase version of the logonid or logonid.suffix that was specified.
    For every one apostrophe that is desired in the WITHLBL value, two consecutive apostrophes must be specified. For example, the WITHLBL value, Frank's Certificate, should be specified as, Frank”s Certificate. If a single apostrophe is specified in the WITHLBL value, the value is considered invalid.
  • WITHSufx(record suffix)
    Specifies a 1-character to 8-character suffix of the new certificate. The new suffix can contain mixed-case characters, but it is folded to uppercase. The new suffix must be unique to the logonid with which the new certificate is associated. The suffix is appended to the record key with a dot (.) preceding the suffix. If a suffix is not specified, the suffix is in the format of AUTOnnn, where
    nnn
    is a number from 001 to 999.
  • SIZe({key-size})
    Specifies the size of the private key to be generated, in bits. If SIZE is not specified, the original certificate's key size is used.
    Valid key sizes for NISTECC are 192, 224, 256, 384, and 521 bits.
    Valid key sizes for BPECC keys are 160, 192, 224, 256, 320, 384, and 512 bits. The maximum key size depends on the private key type.
    RSA keys generated using software can be limited by the KEYSIZE parameter of the GSO OPTS record.
    Private Key Type
    Maximum Key Size
    BPECC key
    512 bits
    NISTECC key
    521 bits
    ICSF RSA key
    1024 bits
    DSA key
    2048 bits
    Non-ICSF RSA key
    4096 bits*
    PCI-class cryptographic coprocessor RSA key
    4096 bits
    You can achieve comparable key strengths with shorter ECC keys when compared to longer RSA keys. The following table displays the comparable strength of each key:
    RSA Key Size
    NISTECC Key Size
    BPECC Key Size
    1024 bits
    192 bits
    160 bits or 192 bits
    2048 bits
    224 bits
    224 bits
    3072 bits
    256 bits
    256 bits or 320 bits
    7680 bits
    384 bits
    384 bits
    15360 bits
    521 bits
    512 bits
    Currently, the standard key sizes for RSA keys are as follows:
    • 512-Specifies a low-strength key
    • 1024-Specifies a medium-strength key
    • 2048-Specifies a high-strength key
    • 4096-Specifies a very high-strength key
  • ICSF
    Indicates that the generated private key is placed in the ICSF PKDS as an ICSF RSA Modulus-Exponent key token.
  • PCICC
    Specifies that the key pair should be generated using the PCI Cryptographic Coprocessor and that the private key should be stored in ICSF. When PCICC is not specified, the key pair is generated using software. PCICC cannot be used with the ICSF parameter. If a PCI cryptographic coprocessor is not present or operational, or if ICSF is not active or configured for PKA operations, an error message displays and processing terminates.
    If ICSF and PCICC are not specified, the key pair is generated using software and stored in the CA ACF2 database.
    If ICSF and PCICC are not specified and the algorithm that is used to create the key pair for the original certificate is DSA, the new key pair is generated using the Digital Signature Algorithm instead of the RSA algorithm.
    If ICSF is also specified, the private key is stored in the ICSF PKDS as an ICSF RSA Modulus-Exponent key token. For PCICC, the private key is stored as an ICSF RSA Chinese Remainder Theorem (CRT) key token. The PKDS label must be unique. If PKDSLBL is not specified, the PKDS label is generated in the format IRR.DIGTCERT.userid.cvtsname.ebcdic-stck-value, where userid is the owning user ID, cvtsname is the system name, which is taken from the CT, and ebcdic-stck-value is an EBCDIC version of the current store clock value.
    If the algorithm used to create the original key pair is DSA, PKDSLBL cannot be specified, an error message displays.
  • BPECC
    Specifies that the key pair is generated with the elliptic curve algorithm (ECC) in accordance with the standard that is proposed by the ECC Brainpool working group of the Internet Engineering Task Force (IETF). The key is generated using ICSF PKCS #11 functions so the ICSF subsystem must be operational and configured for PKCS #11 operation. ICSF must be at least at the HCR7770 level. The private key is placed in the CA ACF2 database.
    This parameter cannot be specified with the PCICC, ICSF, DSA, NISTECC, or DSNAME parameters. REKEYing from a non-ECC certificate to a BPECC certificate is not allowed.
  • NISTECC
    Specifies that the key pair is generated with the elliptic curve algorithm (ECC) in accordance with the standard that is proposed by the National Institute of Standards and Technology (NIST). The key is generated using ICSF PKCS #11 functions. Therefore, the ICSF subsystem must be operational and must be configured for the PKCS #11 operation. ICSF must be at least at the HCR7770 level. The private key is placed in the CA ACF2 database.
    This parameter cannot be specified with the PCICC, ICSF, DSA, BPECC, or DSNAME parameters. REKEYing from a non-ECC certificate to a NISTECC certificate is not allowed.
  • PKDSLBL({PKDS label|*})
    Specifies the PKDS label of the record that is created in the ICSF Public Key Data Set (PKDS). The field is used with the ICSF or PCICC keywords. If PKDSLBL is specified without the ICSF or PCICC keywords and if the original certificate does not specify ICSF or PCICC keywords, an error message displays.
    The PKDS label is optional and may be specified as * if the PKDS label should be taken from the WITHLBL keyword. In either case, the PKDS label must conform to ICSF label syntax rules. The allowed characters are alphanumeric, national (@, #, $) or period (.). The first character must be alphabetic or national. The field can be up to 64 characters and is folded to uppercase.
  • SIGATTR(RSAPSS)
    Indicates the signature to be generated is in the RSASSA-PSS format. The format must be SIGATTR(RSAPSS). Any other value will be an error. When requesting an RSASSA-PSS signature, the key size must bein the range of 2048-4096.
    • If the key size is 2048 to 3071, the signature generated is sha256rsapss.
    • If the key size is 3072 to 4095, the signature generated is sha384rsapss.
    • If the key size is 4096, the default signature value is sha512rsapss.
    The signature size is based on the key size of the signing certificate, not the certificate being generated. For example, if the certificate being generated has a key size of 2048 and the key size of the signer is 3072, the new certificate will generate a sha384rsapss signature.
    You may override the signature to sha256rsapss by specifying HASHALG(SHA256).
    The PSS signature will not be propagated if you do not specify SIGATTR
  • ACtive({date-or-date-time})
    Indicates the date and time that the certificate becomes active, for example, 04/30/01-154403. If no time is specified, it defaults to 000000. If no date is specified, it defaults to the current day and time. The specified year must be from 1950 to 2049. If an expire date is not also specified, the active year that is specified must be from 1950 to 2048, because the expire date defaults to the active day and time plus one year.
    Valid date formats include: YY/MM/DD, MM/DD/YY, DD/MM/YY, and DD/MM/YYYY.
  • Expire({date-or-date-time})
    Indicates the date and time that the certificate expires, for example, MM/DD/YY. If no time is specified, it defaults to 000000. If no date is specified, it defaults to the active day and time plus one year. The specified year must be from 1950 to 2049.
    Valid date formats include: YY/MM/DD, MM/DD/YY, DD/MM/YY, and DD/MM/YYYY.
Example
REKEY CERTAUTH.LOCALCA WITHLBL(Local CA 2004) SIZE(1024) EXPIRE(12/31/14) REKEY CERTAUTH LABEL(Local CA) WITHLBL(Local CA 2004) EXPIRE(12/31/19) REKEY CERTAUTH LABEL(Local CA) WITHLBL(Local CA 2004) WITHSUFX(LOCAL04) EXPIRE(12/31/19)
REMOVE Subcommand
The REMOVE subcommand is used to disassociate a certificate from a key ring. The REMOVE subcommand has the following syntax:
REMove Certdata(userid1.suffix)|USER(userid1) Keyring(userid2.suffix)
Parameter Descriptions
  • CERTDATA(userid1.suffix)
    Specifies the record key of a CERTDATA record to remove from a key ring. The userid1 is a one- to eight-character userid associated with the CERTDATA record. The suffix is one- to eight-characters used to make the record key unique. The suffix is separated from the userid by a period. If LABEL is specified in addition to suffix, then both suffix and the label must refer to the same CERTDATA record.
  • USER(userid)
    Removes the connection to the certificates connected with a corresponding CONNECT command that is issued with the USER parameter. This value does not remove certificates for the USER connected with the CERTDATA parameter.
  • KEYRING(userid2.suffix)
    Specifies the record key of a KEYRING record from which to remove the certificate. The userid2 is a one- to eight-character userid associated with the KEYRING record. The suffix is one- to eight-characters used to make the record key unique. The suffix is separated from the userid by a period, and
    cannot
    be specified when RINGNAME is used.
  • RINGNAME(
    ringname
    )
    Specifies the ring name of a KEYRING record from which to remove the certificate. The ringname can be up to 237 characters in length.
  • LABEL(
    label
    )
    Specifies the label of a CERTDATA record from which to disassociate a key ring. The label can be up to 32 characters in length. The label can contain blanks and mixed-case characters.
    For every one apostrophe that is desired in the Label value, two consecutive apostrophes must be specified. For example, the Label value, Frank's Certificate, should be specified as, Frank”s Certificate. If a single apostrophe is specified in the Label value, the value is considered invalid.
Example
acf remove certdata(user02.cert1) keyring(user01.ring) acf remove certdata(user02) label(user02 certificate) keyring(user01) ringname(user01 key ring) acf remove user(user01) keyring(user01) ringname(user01 keyring)
RENEW Subcommand
The RENEW subcommand allows you to renew a certificate in a single step. The certificate must exist in the CA ACF2 database and must have a private key. The private key of certificate signing the renewed certificate must also be in the CA ACF2 database.
If SIGNWITH is not specified, the RENEW subcommand finds the original signing certificate, and signs the renewed certificate with the original signing certificate if the original signing certificate has a private key.
RENEW {logonid|logonid.suffix|CERTAUTH|CERTAUTH.suffix|SITECERT| SITECERT.suffix } [Label(label)] [SUbjsdn([CN=common-name] [T=title] [OU=organizational-unit-name] [O=organization-name] [L=locality] [{S=state-or-province | SP=state-or-province | ST=state-or-province}] [C=country])] [ICSF] [ACtive({date-or-date-time}] [PCICC] [PKDSLBL({PKDS label|*})] [Expire({date-or-date-time})] [SIGnwith({CERTAUTH Label(label-name)|SITECERT Label(label-name)})] [Keyusage([HANDSHAKE][DATAENCRYPT] [DOCSIGN][CERTSIGN][KEYAGREE])] [ALtname([IP=numeric-ip-address] [DOMAIN=internet-domain-name] [EMAIL=email-address] [URI=universal-resource-identifier])] SIGATTR(RSAPSS)
When to Use RENEW or REKEY
RENEW is used to alter the validity period of the certificate. If you have a certificate expiring and you want to continue to use the certificate for a longer time frame, use RENEW. RENEW can also be used to alter the attributes of the certificate at the time of renewal. You can alter the certificate’s distinguished name or can add and remove an ALTNAME value.
  1. RENEW does not change the public/private key pair.
  2. You cannot increase the size of the keys or change from RSA to DSA.
  3. REKEY should be used when there is a potential that the public/private key pair has been compromised. It is also used when company standards dictate that a particular key size or type is no longer appropriate.
Parameter Descriptions
  • logonid
    |CERTAUTH|SITECERT
    The logonid specifies the user who is associated with the certificate. It may be a one- to eight-character logonid, or a logonid, a dot, and a one- to eight-character suffix. The .suffix and label are optional. If the CERTDATA record is the first for this logonid, the GENCERT can be issued without the suffix, but subsequent CERTDATA records with the same logonid must have a unique qualifier/suffix, regardless of the label value. If a suffix is not supplied on the GENCERT for subsequent records with the same logonid, CA ACF2 generates one with the form AUTOnnn.
    Using CERTAUTH in place of a logonid designates the certificate as a Certification Authority certificate.
    Using SITECERT in place of a logonid designates the certificate as a site certificate.
  • Label(
    label
    )
    Specifies a 1-character to 32-character label for the new certificate. The label can contain blanks and mixed-case characters. If a label is not specified, the label field defaults to the uppercase version of the logonid or logonid.suffix that was specified.
    For every one apostrophe that is desired in the Label value, two consecutive apostrophes must be specified. For example, the Label value, Frank's Certificate, should be specified as, Frank”s Certificate. If a single apostrophe is specified in the Label value, the value is considered invalid.
  • SUbjsdn(…attributes…)
    Specifies the subject’s distinguished name. The attributes can consist of the following fields. Except as otherwise noted, valid characters for the values of the attributes are any printable ASCII character and the characters in Latin-1 Supplemental character set. CA ACF2 assumes that the 1047 code page is being used. Values containing spaces must be enclosed in single quotes. Any apostrophes should be doubled. For example, a common name of John T. O'Reiley would be specified as CN='John T. O”Reiley'. Also, unless otherwise specified, each attribute can only be specified once.
    1. A space is the only valid delimiter between specified attributes.
    2. The maximum length for this parameter for a self-signed certificate is 1007.
    3. The maximum length for this parameter for a non self-signed certificate is 1024.
    4. The maximum length for each attribute of this parameter is 64. Multiple blanks are not removed and are included in the lengths.
    5. If the DSNAME keyword is also present, the subject's distinguished name from the SUBJSDN keyword is used instead of the subject's distinguished name from the PKCS #10 certificate request. If DSNAME and SUBJSDN are not specified, the subject's distinguished name is generated with CN='ACF2 USER:
      logonid
      '.
    • CN=
      common
      -
      name
      Specifies the subject's regular name. For example, Sam Smith would be specified as CN='Sam Smith'. An '*' wildcard character may be used as the leftmost byte of the CN attribute, as in CN='*.example.com'.
    • T=
      title
      Specifies the person's job title. For example, T='Software Developer'.
    • OU=
      organizational
      -
      unit
      -
      name
      Specifies the department or group. This value can be specified multiple times to indicate a hierarchy. For example, OU=Accounting,OU='Accounts Payable'.
    • O=
      organization
      -
      name
      Specifies the name of the company. For example, O='Blue Lock Company'.
    • L=
      locality
      Specifies the city. For example, L='Tom”s River'.
    • S=
      state
      -
      or
      -
      province, SP=state
      -
      or
      -
      province, ST=state
      -
      or
      -
      province
      Specifies the state or province. All three keywords mean the same thing. When the distinguished name is displayed, state or province is displayed using 'ST='. State or province must be expressed using the same abbreviations that are used in mail addresses, for example, ST=IL for Illinois.
    • C=
      country
      Specifies the country. This value must be specified using the two-character ISO 3166 country code. For example, C=US for the United States of America, or C=VA for Vatican City.
  • ICSF
    Indicates that the public or private key is placed in the ICSF PKDS. If the DSNAME parameter was also specified and an existing certificate is to be replaced, the existing private key is moved from the Infostorage database to ICSF. ICSF must be active and configured for PKA operations. If it is not, an error message is displayed when attempting to insert or use the private key. Non-ICSF private keys are stored in a CERTKEYX record that is associated with the CERTDATA record. CERTKEYX records are managed internally by CA ACF2.
  • ACtive({date-or-date-time})
    Indicates the date and time that the certificate becomes active, for example, 04/30/01-154403. If no time is specified, it defaults to 000000. If no date is specified, it defaults to the current day and time. The specified year must be from 1950 to 2049. If an expire date is not specified, the active year that is specified must be from 1950 to 2048. This requirement is because the expire date defaults to the active day and time plus one year. Valid date formats include: YY/MM/DD, MM/DD/YY, DD/MM/YY, and DD/MM/YYYY
  • PCICC
    Specifies that the key pair should be generated using the PCI Cryptographic Coprocessor and that the private key should be stored in ICSF as an ICSF RSA Chinese Remainder Theorem (CRT) key token, if the DSNAME parameter is not specified. When PCICC is not specified, the key pair is generated using software. If the DSNAME parameter is specified, PCICC can be used with the PKDSLBL field to specify that the public key of the new certificate is to be placed in the ICSF PKDS as an RSA Modulus-Exponent key token. If a PCI cryptographic coprocessor is not present or operational, or if ICSF is inactive or configured for PKA operations, an error message displays. Processing terminates.
  • PKDSLBL({PKDS label|*})
    Specifies the PKDS label of the record that is created in the ICSF Public Key Data Set (PKDS). The field is used with the ICSF or PCICC keywords. If PKDSLBL is specified without the ICSF or PCICC keywords, an error message is displayed.
    The PKDS label is optional and may be specified as * if the PKDS label should be taken from the LABEL keyword. In either case, the PKDS label must conform to ICSF label syntax rules. The allowed characters are alphanumeric, national (@, #, $), or period (.). The first character must be alphabetic or national. The field can be up to 64 characters and is converted to uppercase.
    If GENCERT is issued without the DSNAME parameter, the following occurs:
    If ICSF is also specified, the private key is stored in the ICSF PKDS as an ICSF RSA Modulus-Exponent key token. For PCICC, the private key is stored as an ICSF RSA Chinese Remainder Theorem (CRT) key token. The PKDS label must be unique. If PKDSLBL is not specified, the PKDS label is generated in the format IRR.DIGTCERT.userid.cvtsname.ebcdic-stck-value, where userid is the owning user ID, cvtsname is the system name, which is taken from the CVT, and ebcdic-stck-value is an EBCDIC version of the current store clock value.
    If GENCERT is issued with a DSNAME parameter, the following occurs:
    A key pair is not generated because the public key is taken from the certificate request.
    If the certificate being generated does not have an associated private key, the following occurs. If the PKDSLBL was specified and ICSF or PCICC where specified, the public key is stored as an ICSF RSA Modulus-Exponent (ME) key token. If PKDSLBL is specified and ICSF and PCICC are not specified, an error message is issued and the certificate is not generated.
  • Expire({date-or-date-time})
    Indicates the date and time that the certificate expires, for example, MM/DD/YY. If no time is specified, it defaults to 235959. If no date is specified, it defaults to the active day and time plus one year. The specified year must be from 1950 to 2049.
    The maximum value that can be specified for a certificate expiration date is December 31, 2049 when using CA ACF2. Other platforms may have maximum expiration date values that are less than the maximum value that can be set by CA ACF2. Use caution when setting an expiration date far into the future. If you pass such a certificate to another platform, ensure that the expiration date falls in the guidelines of the other platform.
    Valid date formats include: YY/MM/DD, MM/DD/YY, DD/MM/YY, and DD/MM/YYYY.
  • SIGnwith({CERTAUTH
    Label
    (label
    -
    name)
    |SITECERT
    Label
    (label
    -
    name)
    }), SIGnwith({CERTAUTH
    .suffix
    |SITECERT
    .suffix
    }), SIGnwith(Label
    (label
    -
    name
    ))
    Specifies the certificate that is used to sign the new certificate. If SIGNWITH is not specified, a self-signed certificate is generated.
    If SIGNWITH contains CERTAUTH or SITECERT, a suffix or Label value is used to specify which CERTAUTH or SITECERT certificate is used to sign the certificate.
    If CERTAUTH or SITECERT is not specified, Label must be specified and the label identifies the user certificate who signs the new certificate. The user id that is associated with the label is the user generating the certificate. This option cannot be specified if the certificate being generated is for a CERTAUTH or SITECERT id.
    For every one apostrophe that is desired in the Label value, two consecutive apostrophes must be specified. For example, the Label value, Frank's Certificate, should be specified as, Frank”s Certificate. If a single apostrophe is specified in the Label value, the value is considered invalid.
  • Keyusage
    Specifies the values of the keyUsage certificate extension. The default for certificate authority certificates is CERTSIGN. CERTSIGN is always set for certificate authority certificates even if not specified. No default exists for non-certificate authority certificates.
    • HANDSHAKE
      Sets the digitalSignature and keyEncipherment bits in the keyUsage extension. This value allows identification and key exchange during security handshakes such as SSL. When the key pair is generated using the DSA algorithm, only the digitalSignature bit is set because the keys cannot be used for encryption.
    • DATAENCRYPT
      Sets the dataEncipherment bit in the keyUsage extension. This value allows the certificate to be used for data encryption. When the key pair is generated using the DSA algorithm, you may not use the DATAENCRYPT keyword in the Keyusage parameter.
    • DOCSIGN
      Sets the nonRepudiation bit in the keyUsage extension. This value allows the certificate to be used in a legally binding signature.
    • CERTSIGN
      Sets the keyCertSign and cRLSign bits in the keyUsage extension. This value lets the certificate sign other digital certificates and CRLs.
      When KEYUSAGE is specified and the target ID is CERTAUTH and keyUsage is present in the PKCS #10 request that is specified in the DSNAME keyword, the request fails if the certSign bit is turned off in the PKCS #10 request. Otherwise, the keyUsage extension is generated as indicated by the KEYUSAGE parameter. In addition, the certSign and cRLSign bits are turned on if not already specified in the KEYUSAGE parameter.
      When KEYUSAGE is specified and the target ID is CERTAUTH but keyUsage is not specified in a PKCS #10 request, the extensions are generated as indicated by the KEYUSAGE parameter. In addition, the certSign and cRLSign bits are turned on if not already specified in the KEYUSAGE parameter.
      When KEYUSAGE is specified and the target ID is not CERTAUTH, the keyUsage extension is generated using the attributes that are specified in the KEYUSAGE parameter.
      When KEYUSAGE is not specified and the target id is CERTAUTH and keyUsage is present in the PKCS #10 request that is specified in the DSNAME keyword, the request fails if the certSign bit is turned off in the PKCS #10 request. Otherwise, the extension is generated using the attributes that are specified in the keyUsage extension in the PKCS #10 request.
      When KEYUSAGE is not specified and the target id is CERTAUTH and the DSNAME keyword is not specified, the keyUsage extension is generated by turning on the certSign and cRLSign bits.
      When KEYUSAGE is not specified and the target id is not CERTAUTH, the extension is generated using the attributes that are specified in the keyUsage extension in the PKCS #10 request, if present. If the keyUsage extension is not present in the PKCS #10 request or the DSNAME keyword was not specified, the keyUsage extension is not created.
  • ALtname
    Specifies the values for the subjectAltName extension. One or more of the values might be specified. The parameter is optional and there is no default. If necessary, the entered values are converted to ASCII.
    • IP=
      numeric
      -
      ip
      -
      address
      Specifies a string containing a fully qualified numeric-ip-address in IPv4 dotted decimal format, IPv6 format, or IPv4 compatible IPv6 address. An IPv4 address is four decimal numbers from 0 through 255 separated by periods. For example: 141.202.1.255
      An IPv6 address has eight parts that are divided by colons with each part a hexadecimal number between 0 and FFFF. For example: 1080:23B4:324:4:3BCD:26:39F4:332
      An IPv4 compatible IPv6 address is a combination of the two, six parts of the IPv6 followed by the IPv4 address. For example: 0:0:0:0:0:FFFF:141.202.1.255
      The maximum field size is 45 bytes.
    • DOMAIN=
      internet
      -
      domain
      -
      name
      Specifies a fully qualified internet domain name, such as http://ca.com. The validity of this value is not checked. The maximum field size is 255 bytes.
    • EMAIL=
      email
      -
      address
      Specifies a fully qualified e-mail address such as [email protected] The maximum field size is 255 bytes.
    • URI=
      universal
      -
      resource
      -
      identifier
      Specifies a universal resource identifier such as http://ca.com. The validity of this field is not checked. The maximum field size is 255 bytes.
      1. The ACF2 GENCERT command supports the ALtname parameter which specifies the IP, DOMAIN, EMAIL, or URI values for the subjectAltName extension. One or more of the values can be specified however multiple entries of the same type are not supported, for example, two DOMAIN or two IP values cannot be specified but one DOMAIN, one IP, one EMAIL and one URI value can be specified in the ALTNAME parameter.
      2. The correct separator character to use within the ALTNAME parameters IP, DOMAIN, EMAIL, or URI of GENCERT is a blank.
  • SIGATTR(RSAPSS)
    Indicates the signature to be generated is in the RSASSA-PSS format. The format must be SIGATTR(RSAPSS). Any other value will be an error. When requesting an RSASSA-PSS signature, the key size must bein the range of 2048-4096.
    • If the key size is 2048 to 3071, the signature generated is sha256rsapss.
    • If the key size is 3072 to 4095, the signature generated is sha384rsapss.
    • If the key size is 4096, the default signature value is sha512rsapss.
    The signature size is based on the key size of the signing certificate, not the certificate being generated. For example, if the certificate being generated has a key size of 2048 and the key size of the signer is 3072, the new certificate will generate a sha384rsapss signature.
    You may override the signature to sha256rsapss by specifying HASHALG(SHA256).
    The PSS signature will not be propagated if you do not specify SIGATTR.
Example
Renew User.cert1 Renew CERTAUTH.MYCA expire(12/31/2030) Renew user.cert1 expire(12/31/2011) altname([email protected]) signwith(certauth.mynewca)
ROLLOVER Subcommand
The ROLLOVER subcommand is the final step in the rekey - rollover process. ROLLOVER specifies the old certificate that is superseded by the new certificate. The ROLLOVER subcommand performs the following actions:
  • Deletes the private key of the old certificate (as specified by the LABEL keyword), so that it can no longer be used to sign or encrypt and documents or certificates.
  • Replaces the old certificate with the new certificate (as specified by the NEWLABEL keyword) in every key ring to which the old certificate is connected.
  • Copies the serial number base from the old certificate to the new certificate.
When the rollover is complete, the new certificate is used as if it were the old certificate. The old certificate is still available to verify signatures and decrypt data but can no longer be used to sign or encrypt.
This command has the following format:
ROllover{logonid|logonid.suffix|CERTAUTH|CERTAUTH.suffix| SITECERT| SITECERT.suffix} [Label(old_certificate_label)] [NEWLabel(new_certificate_label)|NEWSufx(new_certificate_suffix)] [Force]
  • logonid
    |
    logonid.suffix
    |CERTAUTH|SITECERT
    Specifies the user who is associated with the certificate (in the form of a one- to eight-character logonid, or a logonid, a dot, and a one- to eight-character suffix). If label is specified, logonid, rather than logonid.suffix, must be specified and indicates the logonid with which the label is associated.
  • Label(
    label
    )
    Specifies a 1-character to 32-character label of the old (source) certificate that has its private key deleted. The label can contain blanks and mixed-case characters.
    For every one apostrophe that you want in the Label value, you must specify two consecutive apostrophes. For example, the value Frank's Certificate should be specified as Frank”s Certificate. A value that contains a single apostrophe is considered invalid.
  • NEWLabel(
    label
    )
    Specifies a 1-character to 32-character label of the new (target) certificate that replaces the old certificate in all the key rings that had the old certificate connected. The NEWLABEL value can contain blanks and mixed-case characters. However, the value must be unique to the logonid with which the new certificate is associated. If a NEWLABEL is not specified, NEWSUFX must be specified.
    For every one apostrophe that you want in the NEWLABEL value, you must specify two consecutive apostrophes. For example, the value Frank's Certificate should be specified as Frank”s Certificate. A value that contains a single apostrophe is considered invalid.
  • NEWSufx(record suffix)
    Specifies a 1-character to 8-character suffix of the new (target) certificate. The new suffix can be used in place of the NEWLABEL field.
  • FORCE
    Specifies to perform the rollover unconditionally, bypassing the following checks:
    1. The values of LABEL and NEWLABEL must be different. If NEWSUFX is specified instead of NEWLABEL, the label of the new certificate must be different from the LABEL value.
    2. The certificates that are identified by LABEL and NEWLABEL (or NEWSUFX) must both have private keys that are associated with them.
    3. The certificate that is identified by NEWLABEL (or NEWSUFX) must have never been the target of a previously issued ROLLOVER subcommand and never used to sign other certificates.
    4. The certificate that is identified by NEWLABEL (or NEWSUFX) must not have the GENREQ indicator that is assigned on the CERTDATA record.
      If both LABEL and NEWLABEL are the same, and the FORCE keyword is used, the product deletes the private key of the certificate.
Example: Replace a Certificate by using a Logonid-Suffix Combination and Label for the New Certificate
This example replaces a certificate by using a logonid-suffix combination and label for the new certificate:
ROLLOVER CERTAUTH.LOCALCA NEWLABEL(Local CA 2014)
Example: Replace a Certificate by using a Logonid and Labels for the Old and New Certificates
This example replaces a certificate by using a logonid and labels for the old and new certificates:
ROLLOVER CERTAUTH LABEL(Local CA) NEWLABEL(Local CA 2014)