GENCERT Function—Generate a Certificate

Valid on z/OS, z/VSE, and z/VM.
ctsfz
Valid on z/OS, z/VSE, and z/VM.
Use the GENCERT command function to generate a digital certificate and insert a CERTDATA profile record into the CA Top Secret info storage database.
You must specify a DIGICERT name as part of all GENCERT functions, because the DIGICERT keyword indicates the name used in the digital certificate.
Administrators must have:
  • MISC4(CERTGEN) for users within their scope
  • MISC4(CERTSITE) for CERTSITE ACID
  • MISC4(CERTAUTH) for CERTAUTH ACID
  • Administrators without the above authorities can issue the GENCERT command if they have:
    • UPDATE access to TSSCMD.CERTUSER.GENCERT in the CASECAUT resource class when the certificate is associated with a user ACID
    • UPDATE access to TSSCMD.CERTSITE.GENCERT in the CASECAUT resource class when generating a site certificate
    • UPDATE access to TSSCMD.CERTAUTH.GENCERT in the CASECAUT resource class when generating a certificate-authority certificate
This command function has the following format:
TSS GENCERT (CERTAUTH|CERTSITE|
acid
] DIGICERT(
8-byte-name
) [DCDSN(
request-data-set-name
)\] [SUBJECTN ('CN=“
common-name
” T=“
title
” OU=“
organizational-unit-name1
,
organizational-unit-name2”
O=“
organizational-name
” EMAIL="
email-address
" L=“
locality
” S=\
state-or-province
|SP=\
state-or-province
|ST=\
state-or-province
C=“
2-digit-only-country-code
”') DNQUALIFIER="
qualifier
" UID=
user_id
STREET="
street_name
" PC="
postal_code
" DC="
domain_component
"] [ALTNAME('IP=
numeric-IP-address
DOMAIN=
internet-domain-name
EMAIL=
email-address
URI=
universal-resource-identifier
')] [ICSF|PCICC|DSA|NISTECC|BPECC] [FROMICSF(
label-name
)] [KEYSIZE(
key-size
)] [KEYUSAGE('HANDSHAKE DATAENCRYPT DOCSIGN CERTSIGN KEYAGREE')] [LABLCERT(
label-name
)] [LABLPKDS(
PKDS-label
|*] [NBDATE(
mm/dd/yy
) NBTIME(
hh:mm:ss
)] [NADATE(
mm/dd/yy
) NATIME(
hh:mm:ss
)] [SIGNALG{SHA1|SHA256)] [SIGNWITH(
acid
,
digicert
)]
  • acid
    Specifies a user ACID.
  • CERTAUTH
    Specifies an ACID in which your site can maintain certificates that were generated by a third-party certificate authority (CA). This ACID is predefined in CA Top Secret. You cannot add a keyring to this ACID.
  • CERTSITE
    Specifies an ACID in which your site can maintain site generated certificates. This ACID is predefined in CA Top Secret. You cannot add a keyring to this ACID.
  • DIGICERT
    Specifies a case-sensitive ID that identifies the certificate with the user ACID. DIGICERT
    must
    be entered as part of all GENCERT commands, because this keyword indicates the name to be used in the digital certificate.
    Range:
    One to eight characters
  • DCDSN(
    request-data-set-name
    )
    Specifies the name of an optional data set that contains the PKCS#10 certificate request data. The data set name can be the output from a TSS GENREQ command. The request data contains the user's generated public key and X.509 distinguished name. The request data must be signed, DER-encoded, and then Base64-encoded according to PKCS#10 standard. The data set must be cataloged.
    If DCDSN is specified, CA Top Secret does not generate a key pair (meaning private and public key) because this data set contains the user's public key.
    Important!
    SIGNWITH must also be specified because the request data set name (in DCDSN) does not contain a private key.
    Range:
    Up to 44 characters
  • SUBJECTN
    Specifies information that generates the subject distinguished name, which helps uniquely identify the user for which the certificate is being created. Specified information can include the following items.
    Note:
    You can use A-Z and 0-9 for all entries except C="
    country
    " (which is a 2-digit character value).
  • CN="
    common-name
    "
    Specifies the subject's regular name. For example, Sam Smith is specified as CN="Sam Smith" in the syntax. You can use a * wildcard character as the leftmost byte (for example, example.com).
  • T="
    title
    "
    Specifies the person's job title.
    Example:
    T="Software Developer"
  • OU="
    organizational-unit-name
    "
    Specifies the department or group. Multiple values can be specified (to indicate a hierarchy).
    Example:
    OU="Accounting",OU="Accounts Payable"
  • O="
    organization-name
    "
    Specifies the name of the company.
    Example:
    O="Blue Lock Company"
  • EMAIL="
    email-address
    "
    Specifies an email address.
  • L="
    locality
    "
    Specifies the name of the city.
    Example:
    L="Tom's River"
  • S=\
    state-or-province
    |SP=\
    state-or-province
    |ST=\
    state-or-province
    Specifies the state or province, which must be expressed by using the same abbreviations that are used in mailing addresses. Choose
    one
    of the available syntax formats.
    Example:
    ST=\IL (for Illinois)
  • C="
    country
    "
    Specifies a two-character value that identifies the country. This value must use the two-character ISO 3166 country code.
    Example:
    C=US (for the United States of America) or C=VA (for Vatican City)
    Note:
    Country codes are available on the ISO 3166 Maintenance Agency website.
  • DNQUALIFIER="
    qualifier"
    Specifies a value to use as the high-level qualifier of the distinguished name (meant to add disambiguating information). DNQUALIFIER is intended for use when merging data from multiple sources (to prevent conflicts between entries).
  • UID=
    user_id
    Identifies the user for which the certificate is being created.
  • STREET="
    street_name
    "
    Identifies the street name that can be part of a mailing address.
    Example:
    STREET=FOSTER (for Foster Avenue)
  • PC=
    "
    postal_code
    "
    Specifies the code (for example, U.S. zip code) that can be part of a mailing address.
  • DC=
    "
    domain_component
    "
    Identifies the domain components of a domain. For example, if the domain is siroe.com, the domain components would be as follows: DC=siroe, DC=com
Notes:
  • Any value that contains blanks must be enclosed in double quotation marks.
  • If DCDSN and SUBJECTN is not specified, SUBJECTN defaults to the ACID name field.
  • The attributes are separated by spaces. No matter how many spaces there are between attributes, they count as one space.
  • Each attribute has a limit of 64 characters.
Range:
  • (Self-signed certificate) Up to 229 characters (if the SDNSIZE(255) control option is specified) or up to 1007 characters (if the SDNSIZE(1024) control option is specified)
  • (Non-self-signed certificate) Up to 255 characters (if the SDNSIZE(255) control option is specified) or up to 1024 characters (if the SDNSIZE(1024) control option is specified)
  • (Certificate added to CERTAUTH) Up to 229 characters (if the SDNSIZE(255) control option is specified) or up to 1007 characters (if SDNSIZE(1024) control option is specified)
ALTNAME
Specifies the appropriate values for the SubjectAltname extension, of which one or more values might be coded. There is no default.
The following values can be used.
Note:
You can have only one ALTNAME specificiation, in which you can specify multiple parameters). When specifying multiple parameters, you must separate parameters with a space; additionally, you must include one single quotation mark at the beginning and end of the parameter list—for example, ALTNAME('IP=201.100.10.9 [email protected]')
IP
Specifies a string containing a fully qualified numeric IP address in:
  • IPv4 dotted decimal format—four decimal numbers between 0 and 255 separated by periods (for example, 141.202.1.255)
  • IPv6 format—eight parts divided by colons with each part a hexadecimal number between 0 and FFFF (for example, 1080:23B4:324:4:3BCD:26:39F4:332)
  • IPv4 compatible IPv6 address—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
Specifies a string containing a fully qualified internet domain name.
Example:
ALTNAME(DOMAIN=CA.COM)
EMAIL
Specifies a string containing a fully qualified email address.
Example:
ALTNAME([email protected])
URI
Specifies the universal resource identifier.
Example:
ALTNAME(URI=WWW.CA.COM)
ICSF|PCICC|NISTECC|BPECC|DSA
(Optional) Specifies whether to use a non-RSA algorithm to generate the key pair and specifies where to store the private key for future use.
Note:
If you do not specify ICSF, PCICC, NISTECC, or BPECC, the key pair is generated by using software (and s