CERTDATA Profile Data Records

The CERTDATA segment of the USER profile identifies an X.509 digital certificate associated with a user. Digital certificates provide a means of authentication through the use of public-key cryptography and a trusted third party, known as a Certification Authority. Each certificate is identified uniquely by its serial number and associated certification authority distinguished name ("issuer's distinguished name").
acf2src
The CERTDATA segment of the USER profile identifies an X.509 digital certificate associated with a user. Digital certificates provide a means of authentication through the use of public-key cryptography and a trusted third party, known as a Certification Authority. Each certificate is identified uniquely by its serial number and associated certification authority distinguished name ("issuer's distinguished name").
As an alternative to requesting userid and password information, a z/OS Web server can authenticate users based on their digital certificates. The Web server performs all certificate authentication. If z/OS resources are accessed, the certificate is presented to CA ACF2. Using the certificate serial number and the issuer's distinguished name, CA ACF2 associates the certificate to a userid. A z/OS security environment is then created for that user. By using authenticated certificates, passwords are not sent through the network.
Certificates are associated to CA ACF2 users through the use of profile records. A user can have more than one certificate, but a single certificate cannot be used by more than one user. Profile records are inserted using the userid as the record key (with or without a specified label. If no label is specified, a label is set by default). The record key can also contain a userid with a distinguished suffix if a user is defined with more than one certificate.
2
2
The following table includes the record ID and fields of the CERTDATA profile data records:
Record ID
Fields
recid
ACTIVE(
date
)
BPECC
CERTNSER(
hex
)
DSA
EXPIRE(
date
)
GENREQ
HITRUST|TRUST|NOTRUST
ICSF
ISSUERDN(
dn
)
KEYSIZE(192-4096)
LABEL(
label
)
NISTECC
PCICC
PKDSLBL({
PKDS label
|
*
})
RETAIN
SERIAL#(
serial_number
)
SUBJDN(
dn
)
  • recid
    (
    Logonid|certauth|sitecert|logonid.suffix|certauth.suffix|sitecert.suffix
    )
    Specifies the userid that is to be associated with the certificate. It might be a one- to eight-character logonid, or a logonid, a period, and a one- to eight-character suffix. If label is also specified, logonid, rather than logonid.suffix, must be specified, and indicates the logonid that the label is associated with.
    Using CERTAUTH in place of a logonid indicates that the certificate is a Certification Authority certificate.
    Using SITECERT in place of a logonid indicates that the certificate is a site certificate.
  • 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. This date gives the security administrator the ability to specify when the profile record associating the user to the certificate becomes active. This 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.
  • BPECC
    Specifies that the key pair has been generated with the elliptic curve algorithm (ECC) in accordance with the standard proposed by the ECC Brainpool working group of the Internet Engineering Task Force (IETF). The key is accessed 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 is not valid on insert or change commands.
  • CERTNSER(
    hex value
    )
    Indicates the next serial number to be used by this certificate when signing another certificate. This field generally should not be modified by hand because you can generate duplicate certificates. All detected duplicate certificates will be unusable on z/OS systems.
  • DSA
    Specifies that the key pair has been generated using the Digital Signature Algorithm instead of the RSA algorithm. The DSA algorithm creates key pairs that can be only used for signing data while the RSA algorithm creates key pairs that can be used to sign data and to encrypt data. This parameter cannot be used in conjunction with the ICSF or PCICC parameters.
  • 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. This date gives the security administrator the ability to specify when the profile record associating the user to the certificate expires. This 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.
  • GENREQ
    Indicates that the CERTDATA record has been the target of a GENREQ command. We recommend not using the CHANGE command to turn on this indicator. DELETE processing and ROLLOVER (NEWLABEL or NEWSUFX) processing will not work against CERTDATA records that have the GENREQ indicator turned on.
    You can bypass the check for GENREQ by specifying the FORCE operand of the DELETE or ROLLOVER command. Turn off the GENREQ indicator in the following situations:
    • You specified GENREQ when REKEY was intended.
    • You specified REKEY when GENREQ was intended.
    To turn off the GENREQ indicator, specify Change NOGENREQ.
    During normal processing, inserting a signed certificate over the GENREQ’d certificate turns off the GENREQ indicator.
  • 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, i.e., that the certificate is valid for the user, site or certificate authority, and the private key has not been compromised.
    • NOTRUST
      Any certificate that is not trusted cannot be returned to an application using the R_datalib callable service.
  • ICSF
    Specifies the private key for the certificate is placed in ICSF. This parameter is not valid on change requests. It is a valid parameter in GENCERT, INSERT and RENEW commands. If ICSF is specified on an INSERT or RENEW command and the certificate is to be renewed and the private key exists in the CA ACF2 database, the private key will be moved from the CA ACF2 database into ICSF.
    Non-ICSF private keys are stored in a CERTKEYX record associated with the CERTDATA record. CERTKEYX records are managed internally by CA ACF2.
  • ISSUERDN(
    dn
    )
    Specifies that the ISSUERDN is the certification authority's distinguished name as extracted from the certificate. This field cannot be altered or displayed. However, it can be used with the SERIAL# operand to list, change, or delete a CERTDATA record.
    Note: ISSUERDN cannot be abbreviated.
  • KEYSIZE(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 is dependent on the private key type.
    Note: *
    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
LABEL(
label
)
Specifies a 32-character label to be associated with the certificate. The label can contain blanks and mixed-case characters. Quotes are not allowed. If a label is not specified, the label field will default to the upper-case version of the logonid that was specified. To change the label in a record, the NEWLABEL operand must be used.
Note: Label cannot be abbreviated.
NISTECC
Specifies that the key pair has been generated with the elliptic curve algorithm (ECC) in accordance with the standard proposed by the National Institute of Standards and Technology (NIST). The key is accessed using ICSF PKCS #11 functions so the ICSF subsystem must be operational and 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.
This parameter is not valid on the insert or change commands.
PCICC
Indicates that PCICC was specified on the GENCERT, INSERT or RENEW command. The public or private key was placed in the ICSF PKDS. The PKDS label associated with the key is listed under the CHKCERT command. If ICSF is specified on an INSERT or RENEW command and the certificate is to be renewed and the private key exists in the CA ACF2 database, the private key will be moved from the CA ACF2 database into ICSF.
PKDSLBL({
PKDS label
|
*
})
Specifies the PKDS label of the record created in the ICSF Public Key Data Set (PKDS). The field is used in conjunction with the ICSF or PCICC keywords.
RETAIN
Specifies that certificates are intentionally retained after the certificate has expired. CERTDATA records with RETAIN on will be excluded from certificate utility (SAFCRRPT) reporting when the EXPIRED parameter is specified.
SERIAL#(serial_number)
Specifies the serial number as extracted from the certificate. This field cannot be altered or displayed. However, it can be used with the ISSUERDN operand on a change or list command to list, change, or delete a CERTDATA record. Note: SERIAL# cannot be abbreviated.
SUBJDN(dn)
Specifies the subject’s distinguished name as extracted from the certificate. You cannot alter this field from the ACF command.
The following provides steps on inserting, changing, activating, viewing, and deleting CERTDATA profile records.
Creating CERTDATA Profile Records
As part of the INSERT command processing, the certificate is read from the z/OS data set. CA ACF2 decodes the certificate to extract the serial number, issuer's distinguished name, and other information and inserts some of this information along with information from the command input into CERTDATA profile data record. This information can be displayed with the LIST command.
To create a CERTDATA profile data record, enter profile administration mode:
set profile(user) div(certdata)
To create a record using record ID:
insert frank01.mycert dsn('frank01.mycert') active(02/02/02) expire(02/02/03) trust CERTDATA / FRANK01.MYCERT LAST CHANGED BY FRANK01 ON 02/02/02-17:24 ACTIVE(02/02/02) CERTID(01.CN=histrust CA cert20) EXPIRE(02/02/03) LABEL(FRANK01.MYCERT) SUBJDN(CN=frank01.mycert) TRUST PROFILE
To create a record using logonid and label:
insert frank01 label(mycert) dsn('frank01.mycert') active(02/02/02) expire(02/02/03) trust CERTDATA / FRANK01.MYCERT LAST CHANGED BY FRANK01 ON 02/02/02-17:24 ACTIVE(02/02/02) CERTID(01.CN=histrust CA cert20) EXPIRE(02/02/03) LABEL(MYCERT) SUBJDN(CN=frank01.mycert) TRUST PROFILE
Certificate Replacement ("Renewal")
As part of the INSERT command processing, a certificate can be replaced without deleting and reinserting it. To replace an existing certificate, make sure that one of the following three cases is satisfied:
Case 1. The certificate being added is a duplicate of the existing certificate (i.e., has the same serial number and issuer's distinguished name) and the labels and record keys of both certificates are the same.
Case 2. The certificate being added is NOT a duplicate of the existing certificate, has the same subject's distinguished name, issuer's distinguished name, and public key as the existing certificate, the end date and time on the certificate being added is later than on that of the existing certificate, and the record keys of both certificates are the same.
Case 3. The certificate being added is NOT a duplicate of the existing certificate, has the same public key as the existing certificate, there is a private key associated with the existing certificate in the database, and the record keys of both certificates are the same.
Changing CERTDATA Profile Records
Issue the following command to enter profile administration mode.
set profile(user) div(certdata)
Issue  the CHANGE command to change
only
the following fields in the CERTDATA profile record:
  • active date - [active(
    date
    )]
  • expire date - [expire(
    date
    )]
  • label - [newlabel(
    label
    )]
  • trust status - [hitrust | trust | notrust]
Issue the following command to change a single record using record ID:
change frank01.mycert active(02/10/02) expire(02/20/03) newlabel(new certificate) notrust CERTDATA / FRANK01.MYCERT LAST CHANGED BY FRANK01 ON 02/02/02-17:24 ACTIVE(02/10/02) CERTID(01.CN=hitrust CA cert20) EXPIRE(02/20/03) LABEL(new certificate) SUBJDN(CN=frank0l.mycert) PROFILE
Issue the following command to change a single record using logonid and label:
change frank01 label(FRANK01.MYCERT) active(02/10/02) expire(02/20/03) newlabel(new certificate) trust CERTDATA / FRANK01 LAST CHANGED BY FRANK01 ON 02/02/02-17:24 ACTIVE(02/10/02) CERTID(01.CN=hitrust CA cert20) EXPIRE(02/20/03) LABEL(new certificate) SUBJDN(CN=frank0l.mycert) TRUST PROFILE
Issue the following command to change a single record using SERIAL # and ISSUERDN:
change userid SERIAL#(serial_number) ISSUERDN(dn) active(date) expire(date) newlabel(label) [hitrust|trust|notrust]
Issue the following command to change multiple records:
change like(frank01.-) active(02/10/02) expire(02/20/03) trust ACF6D071 2 RECORDS CHANGED PROFILE
The label cannot be changed on a multiple (masked) record request.
Activating CERTDATA Profile Records
CERTDATA profile records no longer need to be activated after insertion, modification, generation, or deletion. Each command handles updating the in-core storage used by certificate processing. You may need to activate your CERTDATA records if you have switched your INFOSTG database with F ACF2,SWITCH command. If so, issue the following console commands to activate your CERTDATA profile records:
F ACF2,REBUILD(USR),CLASS(P) F ACF2,OMVS(CERTDATA)
Viewing/Listing CERTDATA Profile Records
Issue the following commands to enter profile administration mode.
set profile(user) div(certdata)
Issue the LIST command as follows to view CERTDATA profile records.
Issue the following command to list a single record using record ID:
list frank01.mycert CERTDATA / FRANK01.MYCERT LAST CHANGED BY FRANK01 ON 02/02/02-17:24 ACTIVE(02/10/02) CERTID(01.CN=hitrust CA cert20) EXPIRE(02/20/03) LABEL(FRANK01.MYCERT) SUBJDN(CN=frank0l.mycert) PROFILE
Issue the following command to list a single record using logonid and label:
list frank01 label(MYCERT) CERTDATA / FRANK01 LAST CHANGED BY FRANK01 ON 02/02/02-17:24 ACTIVE(02/10/02) CERTID(01.CN=hitrust CA) EXPIRE(02/20/03) LABEL(MYCERT) SUBJDN(CN=frank0l) TRUST PROFILE
Issue the following command to list a single record using SERIAL # and ISSUERDN:
list userid SERIAL#(serial_number) ISSUERDN(dn)
Issue the following command to list multiple records:
list like(frank01.-) CERTDATA / FRANK01.MYCERT1 LAST CHANGED BY FRANK01 ON 02/02/02-17:24 ACTIVE(02/10/02) CERTID(01.CN=hitrust CA cert20) EXPIRE(02/20/03) LABEL(FRANK01.MYCERT1) SUBJDN(CN=frank0l.mycert1) TRUST Certificate is not connected to any key rings CERTDATA / FRANK01.MYCERT2 LAST CHANGED BY FRANK01 ON 02/02/02-17:24 ACTIVE(02/10/02) CERTID(01.CN=CA cert2) EXPIRE(02/20/03) LABEL(FRANK01.MYCERT2) SUBJDN(CN= frank0l.mycert2) TRUST Certificate is not connected to any key rings CERTDATA / FRANK01.MYCERT3 LAST CHANGED BY FRANK01 ON 02/02/02-17:24 ACTIVE(02/10/02) CERTID(01.CN=CA cert21) EXPIRE(02/20/03) LABEL(FRANK01.MYCERT3) SUBJDN(CN=frank0l.mycert3) TRUST Certificate is not connected to any key rings PROFILE
Deleting CERTDATA Profile Records
Issue the following command to enter profile administration mode.
set profile(user) div(certdata)
Issue the DELETE command to delete a specific CERTDATA profile record.
Issue the following command to delete a single record using logonid:
delete frank01.mycert ACF6D073 CERTDATA / FRANK01.MYCERT RECORD DELETED PROFILE
Issue the following command to delete a single record using logonid and label:
delete frank01 label(MYCERT) ACF6D073 CERTDATA / FRANK01 RECORD DELETED PROFILE
Issue the following command to delete a single record using SERIAL # and ISSUERDN:
delete userid SERIAL#(serial_number) ISSUERDN(dn)
Issue the following command to delete multiple records:
delete like(userid.-)
If a GENREQ is done on a certificate and a DELETE record_id name is done, the error message ACF0A223 Cannot delete record - RECORD WAS TARGET OF GENREQ COMMAND is issued.
The record cannot be deleted if a RECORD WAS TARGET OF GENREQ COMMAND is issued, you are waiting for a signed certificate to replace the original certificate that you are trying to delete. Deleting the certificate before this activity is completed deletes the private key associated with the original certificate, rendering the inserted certificate useless.
Issue the following command to delete the certificate by issuing the FORCE parameter on the DELETE command:
delete record_id force
Automatic Registration of Digital Certificates
CERTDATA profile records can also be dynamically inserted or deleted through a process known as Automatic Registration of Digital Certificates. An installation-written or vendor-provided CGI program requests automatic registration by invoking a z/OS UNIX callable service. A program of this sort would typically validate a user's digital certificate and then prompt the user for an ID and password, which are then validated by CA ACF2. If the validation is successful, the certificate is presented to CA ACF2 and a CERTDATA profile record is dynamically created and associated with that user.
Dynamically inserted profile records can be distinguished by a record key that contains the word AUTO
nnn
as the suffix, where
nnn
is a numeric value.
A user must be authorized through the SAF FACILITY class before a profile record is dynamically inserted or deleted. The FAC resource rule $KEY values to allow dynamic INSERT and DELETE are as follows:
IRR.DIGTCERT.ADD IRR.DIGTCERT.DELETE
The following is a rule example:
SET RESOURCE(FAC) COMPILE $KEY(IRR) TYPE(FAC) DIGTCERT.ADD UID(userid) ALLOW DIGTCERT.DELETE UID(userid) ALLOW STORE
Ensure that you do not inadvertently allow access to these resources because of masking in your resource rules.