Configure
Top Secret
Security

Follow these steps to configure iDash to use
Top Secret
security.
ca712
This section assumes you have completed the steps that are documented under ‘Prepare Certificates for External Security’.  Remember, you are loading a minimum of three certificates (more if you do fail over) in your external security product.
  1. CA 7
    Server for iDash Certificate Authority (CA) certificate
  2. CA 7
    Server of iDash Server certificate
  3. iDash
    Server certificate (exported using the keytool utility)
Follow the steps below to configure
iDash
to use
Top Secret
security:
  1. Confirm you have completed the steps that are documented under ‘Prepare Certificates for External Security’.
  2. Create a
    Top Secret
    key ring.
    TSS ADD(User1) KEYRING(
    yourRingName
    ) LABLRING(
    lablring
    )
    User1 should be the user-id that the
    CA 7
    Server for iDash started task runs under.
    KEYRING(yourRingName)
    Specifies the key ring being added to the ACID of the user. An individual ACID can be a member of more than one key ring.
    Limits:
    Up to 8 characters
    Example:
    IDSHRING
    lablring
    Specifies the label to be associated with the key ring being added to the user. This label is used as an identifier of the digital certificate code and must be unique for the key ring. If omitted, it defaults to the KEYRING value.
    Limits:
    Up to 327 characters
    The key ring is created.
  3. Validate that your certificates can be accepted by
    Top Secret
    .
    TSS CHKCERT DCDSN(‘
    your.mvs.cacert.name’
    ) pkcspass(
    exportpassword
    ) TSS CHKCERT DCDSN(‘
    your.mvs.srvcert.name’
    ) pkcspass(
    exportpassword
    ) TSS CHKCERT DCDSN(‘
    your.mvs.idashserver.cacert.name’
    ) pkcspass(
    exportpassword
    )
  4. Add the CA Server for iDash Certificate Authority (CA) certificate to your
    Top Secret
    Database.
    TSS ADD(User1) DIGICERT(
    yourcacertname
    ) LABLCERT(
    yourlabelname
    ) DCDSN('
    your.mvs.cacert.name
    ') TRUST or TSS ADD(CERTAUTH) DIGICERT(
    yourcacertname
    ) LABLCERT(
    yourlabelname
    ) DCDSN('
    your.mvs.cacert.name
    ') TRUST
    DIGICERT(
    yourcacertname
    )
    Specifies a case-sensitive ID that identifies the Digicert CA certificate with the user ACID
    Limits:
    Up to 8 characters
    Example:
    IDASHCA
    LABLCERT(
    yourlabelname
    )
    Specifies a label to be associated with the CA certificate being added to the user If single quotation marks are used, spaces are allowed. This label is used as an identifier and must be unique for the individual user. If you do not specify a label, this value defaults to the value specified for DIGICERT.
    Limits:
    31 case-sensitive characters
    Example:
    IDASHCA
    '
    your.mvs.cacert.name
    '
    Specifies the name of the data set where the CA certificate was loaded
    If you receive this message:
    TSS1573I THE CERTIFICATE <
    yourcacertname
    > SIGNER NOT FOUND. ADDING CERTIFICATE WITH NOTRUST STATUS
    Issue the following command:
    TSS REPLACE(
    User1
    /CERTAUTH) DIGICERT(
    yourcacertname
    ) TRUST
    The
    CA 7
    Server for iDash CA certificate has been added to your
    Top Secret
    database.
  5. Add the
    CA 7
    Server for iDash server certificate to your
    Top Secret
    database.
    TSS ADD(User1) DIGICERT(
    yourservercertname
    ) LABLCERT(yourlabelname) DCDSN('
    your.mvs.srvcert.name
    ') TRUST or TSS ADD(CERTSITE) DIGICERT(
    yourservercertname
    ) LABLCERT(yourlabelname) DCDSN('
    your.mvs.srvcert.name
    ') TRUST
    DIGICERT(
    yourservercertname
    )
    Specifies a case-sensitive ID that identifies the Server certificate with the site
    Limits:
    1 to 8 characters
    Example:
    IDASHSRV
    LABLCERT(
    yourlabelname
    )
    Specifies a label to be associated with the Server certificate being added. If you do not specify a label, this value defaults to the value specified for DIGICERT.
    Limits:
    32 case-sensitive characters
    Example:
    IDASHSRV
    '
    your.mvs.srvcert.name
    '
    Specifies the name of the data set where the Server certificate was loaded
    If you receive this message:
    TSS1573I THE CERTIFICATE <
    yourservercertname
    > SIGNER NOT FOUND. ADDING CERTIFICATE WITH NOTRUST STATUS
    Issue the following command:
    TSS REPLACE(
    User1
    /CERTSITE) DIGICERT(
    yourservercertname
    ) TRUST
    The
    CA 7
    Server for iDash certificate has been added to your
    Top Secret
    database.
  6. Add the iDash server certificate to your
    Top Secret
    database.
    TSS ADD(User1) DIGICERT(
    youridashservercacertname
    ) LABLCERT(yourlabelname) DCDSN('
    your.mvs.srvcert.name
    ') TRUST or TSS ADD(CERTSITE) DIGICERT(
    yourservercertname
    ) LABLCERT(yourlabelname) DCDSN('
    your.mvs.srvcert.name
    ') TRUST
    DIGICERT(
    youridashservercacertname
    )
    Specifies a case-sensitive ID that identifies the Server certificate with the site
    Limits:
    1 to 8 characters
    Example:
    IDASHCL1
    LABLCERT(
    yourlabelname
    )
    Specifies a label to be associated with the Server certificate being added. If you do not specify a label, this value defaults to the value specified for DIGICERT.
    Limits:
    32 case-sensitive characters
    Example:
    IDASHCL1
    '
    your.mvs.idashserver.cacert.name
    '
    Specifies the name of the data set where the
    iDash
    Server certificate was loaded
    .
    If you receive this message:
    TSS1573I THE CERTIFICATE <
    youridashservercacertname
    > SIGNER NOT FOUND. ADDING CERTIFICATE WITH NOTRUST STATUS
    Issue the following command:
    TSS REPLACE(
    User1
    /CERTSITE) DIGICERT(
    youridashservercacertname
    ) TRUST
    The
    iDash
    Server certificate has been added to your
    Top Secret
    database.
    You might have another
    CA 7
    Server for iDash and/or
    iDash
    Server that you have set up for failover. In this case, you must add those certificates to the
    Top Secret
    database. You must provide different DIGICERT names for these failover certificates.
  7. Connect the certificates to your key ring:
    TSS ADD(U
    ser1)
    KEYRING(
    yourRingName
    ) RINGDATA(CERTAUTH, y
    ourcacertname
    ) USAGE(CERTAUTH) TSS ADD(U
    ser1
    ) KEYRING(
    yourRingName)
    RINGDATA(CERTSITE, y
    ourservercertname
    ) USAGE(PERSONAL) DEFAULT TSS ADD(U
    ser1
    ) KEYRING(
    yourRingName)
    RINGDATA(CERTSITE, y
    ouridashservercacertname
    ) USAGE(PERSONAL)
    The KEYRING should match the key ring that is specified on the TSS ADD command.
  8. Grant user permissions for the certificates:
    TSS PER(U
    ser1
    ) IBMFAC(IRR.DIGTCERT.LIST) ACC(READ) TSS PER(U
    ser1
    ) IBMFAC(IRR.DIGTCERT.LISTRING) ACC(READ)
(Optional) Post-Configuration Tasks
Debug Key Ring and Certificate Issues
The following
Top Secret
commands can be useful for identifying errors or failures that are related to your key ring or certificates. Use the following
Top Secret
commands to list the key ring and certificates to verify their existence and proper attributes.
  • To list the key ring for the user:
    TSS LIST(
    ring-owner
    ) DATA(ALL)
  • To list the certificate authority (CA) certificates:
    TSS LIST(User1) DIGICERT(ALL) or TSS LIST(CERTAUTH) DIGICERT(ALL)
  • To list the server certificates:
    TSS LIST(User1) DIGICERT(ALL) or TSS LIST(CERTSITE) DIGICERT(ALL)
Replace an Expired Server Certificate
When a certificate expires, replace your existing certificate with a new one. The steps to replace an existing certificate with a new certificate are similar to the steps that you performed when obtaining and adding the certificates.
Follow these steps:
  1. Obtain one or more new certificates.
  2. Upload the certificates to z/OS.
  3. Delete the existing certificates from the
    Top Secret
    database so you can use the same labels for the new certificates.
    TSS REMOVE(
    owningacid)
    DIGICERT(
    yourservercertname)
    TSS REMOVE(
    owningacid)
    DIGICERT(
    youridashservercacertname)
    TSS REMOVE(
    owningacid)
    DIGICERT(
    yourcacertname)
    Where
    owningacid
    is User1, CERTAUTH, or CERTSITE
  4. Add the new certificates and connect them to your key ring as previously described.