Digital Certificate Support

An X.509 Digital Certificate provides a secure method for identifying a user, typically through a Web-based application. As an alternative to requesting userid and password information, a z/OS Web server can authenticate users based on their digital certificates. Digital certificates provide a means of authentication by using public-key cryptography and a trusted third party, which is known as a Certification Authority. A digital certificate is generated by the Certification Authority. The certificate is identified uniquely by its serial number and by the associated distinguished name of the Certification Authority ("issuer's distinguished name").
acf2src
An X.509 Digital Certificate provides a secure method for identifying a user, typically through a Web-based application. As an alternative to requesting userid and password information, a z/OS Web server can authenticate users based on their digital certificates. Digital certificates provide a means of authentication by using public-key cryptography and a trusted third party, which is known as a Certification Authority. A digital certificate is generated by the Certification Authority. The certificate is identified uniquely by its serial number and by the associated distinguished name of the Certification Authority ("issuer's distinguished name").
If MVS resources are accessed, the certificate is presented to
ACF2
. Using the certificate serial number and the issuer's distinguished name,
ACF2
associates the certificate with an MVS userid. An MVS security environment is then created for that user. By using authenticated certificates, passwords are not sent through the network.
ACF2
provides complete functionality to generate, install, and maintain digital certificates, key rings, and digital certificate mappings, including the following options for more information, see Process Digital Certificates with CA ACF2:
  • Generate a digital certificate and a public/private key pair
  • Create a PKCS #12 certificate package
  • Create a PKCS #10 certificate request
  • Export a digital certificate or certificate package and private key from CA ACF2 to a z/OS dataset
  • Display a certificate that is in a z/OS dataset and determine if it is associated with a CA ACF2 user
  • Display a certificate that is registered with CA ACF2
  • Automatically register a digital certificate with CA ACF2
  • Associate a CA ACF2 user with a digital certificate
  • Change, display, and delete information about a digital certificate for a CA ACF2 user
  • Create, change, display, and delete a key ring
  • Add and remove a certificate from a key ring
  • Assign a CA ACF2 user to a group of certificates using user ID mapping
  • Assign a CA ACF2 user to a group of certificates based on system ID, application ID, or application-defined variables
  • Change, delete, and display a CA ACF2 user ID mapping
The following table summarizes all of the
ACF2
commands that can be issued to generate, install, and maintain digital certificates, key rings, and digital certificate mappings.
CA ACF2 Commands
  • CHKCERT
    • Function:
      CA ACF2 displays information about an X.509 certificate in CERTDATA profile record or a z/OS data set (including whether it is registered with CA ACF2).
    • ACF Setting/Component
      ACF COMMON SUBCOMMAND
    • Syntax:
      CHKcert {
      logonid
      Label(
      label
      )|logonid.suffix|DSname(
      data-set-name
      )} [Password(
      password
      )] [Nolist] [Dump] [Chain]
    • Command Input
      CHKCERT DSN('frank01.mycert')
    • Command Output:
      None
  • CONNECT
    • Function:
      CA ACF2 associates a certificate with a key ring.
    • ACF Setting/Component:
      ACF COMMON SUBCOMMAND
    • Syntax:
      CONnect Certdata (
      userid1.suffix
      ) |USER(
      userid1
      ) Keyring(
      userid2.suffix
      ) [(
      ringname
      )] [Label(label)] [Usage(PERSONAL |CERTAUTH|SITE)] [DEFAULT]
    • Command Input:
      acf connect certdata(user02.cert1) keyring(user01.ring) usage(site) default
    • Command Output:
      None
  • EXPORT
    • Function:
      CA ACF2 exports an X.509 digital certificate from the CA ACF2 database and puts it into a z/OS data set.
    • ACF Setting/Component:
      ACF COMMON SUBCOMMAND
    • Syntax:
      Export {
      logonid|logonid.suffix
      } DSname(
      data-set-name
      ) [Label(
      label
      )] [Format(CERTDER|CERTB64|PKCS12DER|PKCS12B64|PKCS7DER|PKCS7B64)] [Password(
      password
      )]
    • Command Input:
      EXPORT FRANK01.CERT DSNAME(MYCERT)
    • Command Output:
      None
  • GENCERT
    • Function:
      CA ACF2 generates a digital certificate and inserts a CERTDATA profile record into the CA ACF2 infostorage database.
    • ACF Setting/Component:
      ACF COMMON SUBCOMMAND
    • 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
      |1024|192})] [PCICC|ICSF|DSA|NISTECC|BPECC] [ACtive({
      date-or-date-time
      )] [Expire({
      date-or-date-time
      )] [SIGnwith({CERTAUTH Label(
      label-name
      )|SITECERT Label(
      label-name
      )|CERTAUTH.
      suffix
      |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
      |*})]
    • Command Input:
      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)
    • Command Output:
      None
  • GENREQ
    • Function:
      CA ACF2 generates a certificate request (PKCS #10) to be sent to a Certification Authority.
    • ACF Setting/Component:
      ACF COMMON SUBCOMMAND
    • Syntax:
      GENReq {
      logonid|logonid.suffix
      } DSname(
      data-set-name
      ) [Label(
      label
      )]
    • Command Input:
      genreq frank01 label(Frank01 Cert) dsn('joseph01.testreq2.req')
    • Command Output:
      None
  • P11token
    • Function:
      Manage PKCS 11 tokens
    • ACF Setting/Component:
      ACF COMMON SUBCOMMAND
    • Syntax:
      P11token Add Token(
      token-name
      ) P11token DELete Token(token-name) [Force] P11token List Token(
      token-name
      )|Mtoken(
      token-mask
      ) P11token Bind Token(
      token-name
      )|Certdata(
      logonid
      |
      logonid.suffix
      ) [Label(
      label
      )] [Usage(PERSONAL|CERTAUTH|SITE)] [DEFault] P11token Unbind Token(
      token-name
      ) Certdata(
      logonid | logonid.suffix
      ) [Label(
      label
      )] Seqnum(
      sequence #
      ) P11token IMport Token(
      token-name
      ) Seqnum(
      sequence-#
      ) Certdata(
      logonid
      |
      logonid.suffix
      ) [Label(
      label
      )][ICSF][PCICC][Pkdslbl(
      pkds-label
      )]
    • Command Input:
      Add Token(websrv.token)
    • Command Output:
      Token name: WEBSRV.TOKEN Sequence Labels Attributes -------- ---------------------------- ----------------------- No objects exist for this token
  • REKEY
    • Function:
      CA ACF2 generates a new certificate with a new key pair using the contents of an existing certificate.
    • ACF Setting/Component:
      ACF COMMON SUBCOMMAND
    • Syntax:
      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
      })] [PCICC|ICSF|NISTECC|BPECC] [ACtive({
      date-or-date-time
      )] [Expire({
      date-or-date-time
      )] [PKDSLBL({PKDS
      label
      |*})]
    • Command Input:
      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)
    • Command Output:
      None
  • REMOVE
    • Function:
      CA ACF2 disassociates a certificate from a key ring.
    • ACF Setting/Component:
      ACF COMMON SUBCOMMAND
    • Syntax:
      REMove Certdata(
      userid1.suffix
      )|(USER(
      userid1
      ) Keyring(
      userid2.suffix
      ) [Ringname(
      ringname
      )] [Label(
      label
      )]
    • Command Input:
      acf remove certdata(user02.cert1) keyring(user01.ring)
    • Command Output:
      None
  • RENEW
    • Function:
      Renew an existing digital certificate.
    • ACF Setting/Component:
      ACF COMMON SUBCOMMAND
    • Syntax:
      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|PCICC] [ACtive({
      date-or-date-time
      )] [Expire({
      date-or-date-time
      )] [SIGnwith({CERTAUTH Label(
      label-name
      )| SITECERT Label(
      label-name
      )| CERTAUTH.suffix|SITECERT.
      suffix
      )| Label(
      label-name
      )}] [Keyusage([HANDSHAKE] [DATAENCRYPT][DOCSIGN] [CERTSIGN])] ALtname([IP=
      numeric-ip-address
      ] [DOMAIN=
      internet-domain-name
      ] [EMAIL=
      email-address
      ] [URI=
      universal resource-identifier
      ]) [PKDSLBL({PKDS
      label
      |*})]
    • Command Input:
      Renew User.cert1 Renew CERTAUTH.MYCA expire(12/31/2030) Renew user.cert1 expire(12/31/2011) altname ([email protected]) signwith(certauth.mynewca)
    • Command Output:
      None
  • ROLLOVER
    • Function:
      CA ACF2 rolls over a certificate by removing the old private key, reconnecting the new certificate to the old key rings and updates the serial number base.
    • ACF Setting/Component:
      ACF COMMON SUBCOMMAND
    • Syntax:
      ROllover{
      logonid
      |
      logonid.suffix
      |CERTAUTH|CERTAUTH.
      suffix
      |SITECERT|SITECERT.
      suffix
      } [Label(
      old-certificate-label
      )] [NEWLabel(
      new-certificate-label
      )] [NEWSufx(
      new-certificate-suffix
      )] [Force]
    • Command Input:
      ROLLOVER CERTAUTH.LOCALCA NEWLABEL(Local CA 2014)
    • Command Output:
      None
  • INSERT
    • Function:
      CA ACF2 reads an X.509 digital certificate from a z/OS data set and inserts it, with data from the command input line, into a CERTDATA profile record, which associates a user with a certificate.
    • ACF Setting/Component:
      PROFILE USER RECORD(CERTDATA)
    • 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
      |*})]
    • Command Input:
      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)
    • Command Output:
      None
  • CHANGE
    • Function:
      CA ACF2 accepts data from the command input line and, thus, changes the CERTDATA profile record, which associates a user with a certificate.
    • ACF Setting/Component:
      PROFILE
      USER RECORD (CERTDATA)
    • Syntax:
      CHAnge {
      logonid.suffix
      | CERTAUTH.
      suffix
      |SITECERT.
      suffix
      }{[Active(
      date
      )] [Expire(
      date
      )] [NEWLABEL(
      label
      )] [HITRUST|TRUST|NOTRUST]} CHAnge{
      logonid
      |lCERTAUTH|SITECERT|} ISSUERDN(
      dn
      ) SERIAL#(
      serial-number
      ) {[Active(
      date
      )] [Expire(
      date
      )] [NEWLABEL(
      label
      )] [HITRUST|TRUST|NOTRUST]}
    • Command Input:
      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
    • Command Output:
      None
  • DELETE
    • Function:
      CA ACF2 deletes the CERTDATA profile record, which associates a user with a certificate.
    • ACF Setting/Component:
      PROFILE
      USER RECORD (CERTDATA)
    • Syntax:
      DELete {
      logonid
      LABEL(
      label
      )|
      logonid.suffix
      |CERTAUTH LABEL(
      label
      )|CERTAUTH.
      suffix
      | SITECERT LABEL(
      label
      )|SITECERT.
      suffix
      }[FORCE] DELete
      userid
      ISSUERDN(
      dn
      ) SERIAL#(
      serial-number
      )[FORCE]
    • Command Input:
      delete frank01.mycert ACF6D073 CERTDATA / FRANK01.MYCERT RECORD DELETED PROFILE
    • Command Output:
      None
    The FORCE parameter should only be specified when deleting a certificate that was unintentionally GENREQed. Doing so bypasses an ACF0A223 error. Caution should be taken when specifying this parameter as deleting a GENREQed certificate deletes the private key associated with the certificate, rendering the signed certificate from a 3rd party CA useless.
  • LIST
    • Function:
      CA ACF2 displays the CERTDATA profile record, which associates a user with a certificate.
    • ACF Setting/Component:
      PROFILE
      USER RECORD(CERTDATA)
    • Syntax:
      List {
      logonid
      LABEL(
      label
      )|
      logonid.suffix
      |CERTAUTH LABEL(
      label
      )|CERTAUTH.suffix| SITECERT LABEL(
      label
      )|SITECERT.
      suffix
      } List
      userid
      ISSUERDN(
      dn
      ) SERIAL#(
      serial-number
      )
    • Command Input:
      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
    • Command Output:
      None
  • INSERT
    • Function:
      CA ACF2 inserts a KEYRING profile record, which associates one or more certificates with a single user (logonid).
    • ACF Setting/Component:
      PROFILE USER RECORD (KEYRING)
    • Syntax:
      Insert {
      recid
      |
      recid.suffix
      } ALLCA|NOALLCA CACHAIN|NOCACHAIN [Default(
      userid.suffix
      )] Ringname(
      ringname
      )
    • Command Input:
      None
    • Command Output:
      None
  • CHANGE
    • Function:
      CA ACF2 accepts data from the command input line and, thus, changes the KEYRING profile record, which associates one or more certificates with a single user (logonid).
    • ACF Setting/Component:
      PROFILE USER RECORD (KEYRING)
    • Syntax:
      CHAnge {recid|recid.suffix } [Default(userid.suffix)] [NEWNAME(ringname)]
    • Command Input:
      None
    • Command Output:
      None
  • DELETE
    • Function:
      CA ACF2 deletes the KEYRING profile record, which associates one or more certificates with a single user (logonid).
    • ACF Setting/Component:
      PROFILE USER RECORD (KEYRING)
    • Syntax:
      DELete {
      recid
      |
      recid.suffix
      }
    • Command Input:
      None
    • Command Output:
      None
  • LIST
    • Function:
      CA ACF2 displays the KEYRING profile record, which associates one or more certificates with a single user (logonid).
    • ACF Setting/Component:
      PROFILE USER RECORD(KEYRING)
    • Syntax:
      List {
      recid
      |
      recid.suffix
      }
    • Command Input:
      None
    • Command Output:
      None
  • INSERT
    • Function:
      CA ACF2 inserts a CERTMAP GSO record, which defines the IDN (issuer's distinguished name) or SDN (subject's distinguished name) filters used to assign a specific logonid to a group of certificates.
    • ACF Setting/Component:
      CONTROL GSO RECORD (CERTMAP)
    • Syntax:
      Insert CERTMAP.recid [SDNFILTR(
      subject's-dist-name-filter
      )] [IDNFILTR(
      issuer's-dist-name-filter
      )] [DSNAME(
      data-set-name
      )] [CRITERIA(
      criteria-name-template
      )] [LABEL(
      label
      )] [TRUST|NOTRUST] [USERID(
      userid-to-map-to
      ) [MULTIID|NOMULTIID]
    • Command Input:
      SET CONTROL(GSO) INSERT CERTMAP.lvl1 SDNFILTR(OU=LVL1.OU=SUPPORT.OU=ACF2.O=CA, Inc) USER(tech01) SYSA / CERTMAP.LVL1 LAST CHANGED BY SSDRCM ON 02/15/02 - 20:04 SDNFILTR('OU=LVL1.OU=SUPPORT.OU=ACF2.O=CA, Inc') USER(TECH01) NOTRUST
    • Command Output:
      None
  • CHANGE
    • Function:
      CA ACF2 accepts data from the command input line and, thus, changes the CERTMAP GSO record, which defines the IDN (issuer's distinguished name) or SDN (subject's distinguished name) filters used to assign a specific logonid to a group of certificates.
    • ACF Setting/Component:
      CONTROL GSO RECORD (CERTMAP)
    • Syntax:
      CHAnge CERTMAP.recid [SDNFILTR(
      subject's-dist-name-filter
      )] [IDNFILTR(
      issuer's-dist-name-filter
      )] [CRITERIA(
      criteria-name-template
      )] [LABEL(
      label
      )] [TRUST|NOTRUST] [USERID(
      userid-to-map-to
      )] [MULTIID|NOMULTIID]
    • Command Input:
      Change certmap.internet trust Change certmap label(A1) trust
    • Command Output:
      None
  • DELETE
    • Function:
      CA ACF2 deletes the CERTMAP GSO record, which defines the IDN (issuer's distinguished name) or SDN (subject's distinguished name) filters used to assign a specific logonid to a group of certificates.
    • ACF Setting/Component:
      CONTROL GSO RECORD (CERTMAP)
    • Syntax:
      DELete CERTMAP.
      recid
    • Command Input:
      None
    • Command Output:
      None
  • LIST
    • Function:
      CA ACF2 displays the CERTMAP GSO record, which defines the IDN (issuer's distinguished name) or SDN (subject's distinguished name) filters used to assign a specific logonid to a group of certificates.
    • ACF Setting/Component:
      CONTROL GSO RECORD (CERTMAP)
    • Syntax:
      List CERTMAP.
      recid
    • Command Input:
      None
    • Command Output:
      None
  • SHOW
    • Function:
      CA ACF2 displays information that is contained in CERTMAP records as laid out in the internal CERTMAP table.
    • ACF Setting/Component:
      ACF COMMON SUBCOMMAND
    • Syntax:
      SHow CERTMAP
    • Command Input:
      SHOW CERTMAP
    • Command Output:
      None
  • INSERT
    • Function:
      CA ACF2 inserts a CRITMAP GSO record, which is used with the CRITERIA parameter of the CERTMAP GSO record, to assign a specific logonid to a group of certificates based on the system ID, application ID, or application-defined variables specified in the CRITMAP GSO record.
    • ACF Setting/Component:
      CONTROL
      GSO RECORD (CRITMAP)
    • Syntax:
      Insert CRITMAP.
      recid
      [APPLID(
      application-name
      )] [SYSTEMID(
      sysid
      )] [APPLVAR(
      site-variable-list
      )] USERID(
      userid-to-map-to
      )
    • Command Input:
      Insert CRITMAP.BANK APPLID(WEBBANK) USERID(WEBBANK)
    • Command Output:
      None
  • CHANGE
    • Function:
      CA ACF2 accepts data from the command input line and, thus, changes the CRITMAP GSO record, which is used with the CRITERIA parameter of the CERTMAP GSO record, to assign a specific logonid to a group of certificates based on the system ID, application ID, or application-defined variables specified in the CRITMAP GSO record.
    • ACF Setting/Component:
      CONTROL
      GSO RECORD (CRITMAP)
    • Syntax:
      CHAnge CRITMAP.recid [APPLID(
      application-name
      )] [SYSTEMID(
      sysid
      )] [APPLVAR(
      site-variable-list
      )] USERID(
      userid-to-map-to
      )
    • Command Input:
      None
    • Command Output:
      None
  • DELETE
    • Function:
      CA ACF2 deletes the CRITMAP GSO record, which is used with the CRITERIA parameter of the CERTMAP GSO record, to assign a specific logonid to a group of certificates based on the system ID, application ID, or application-defined variables specified in the CRITMAP GSO record.
    • ACF Setting/Component:
      CONTROL GSO RECORD (CRITMAP)
    • Syntax:
      DELete CRITMAP.
      recid
    • Command Input:
      None
    • Command Output:
      None
  • LIST
    • Function:
      CA ACF2 displays the CRITMAP GSO record, which is used with the CRITERIA parameter of the CERTMAP GSO record, to assign a specific logonid to a group of certificates based on the system ID, application ID, or application-defined variables specified in the CRITMAP GSO record.
    • ACF Setting/Component:
      CONTROL GSO RECORD (CRITMAP)
    • Syntax:
      List CRITMAP.
      recid
    • Command Input:
      None
    • Command Output:
      None
  • SHOW
    • Function:
      CA ACF2 displays information that is contained in CRITMAP records as laid out in the internal CRITMAP table.
    • ACF Setting/Component:
      ACF COMMON SUBCOMMAND
    • Syntax:
      SHow CRITMAP
    • Command Input:
      SHOW CRITMAP
    • Command Output:
      None