Defining SAF JWT support for Debug Profile Service

This section provides a few sample RACF commands that creates a new signed SAF Identify Token (IDT) in the JSON Web Token (JWT) format with application ID (APPLID) EQAAPPL. For more information on the security requirement, see Adding support for Authentication Service API.

Note:

To configure your z/OS environment for Cryptographic Service Facility (ICSF), see Cryptographic Services ICSF: System Programmer's Guide.
For ICSF to start, the task ICSF or CSF must be active.
Create Token Data Set (TKDS) for PCKS#11 support.
In a Sysplex, you should create RACF database and configure ICSF to share TKDS data sets across member LPARs. For detailed information, see Running in a Sysplex Environment.

(Optional) create a CRYPTOZ class profile with the value ** and set UACC to NONE.
```
RDEFINE CRYPTOZ SO.** UACC(NONE)
RDEFINE CRYPTOZ USER.** UACC(NONE)
RDEFINE CRYPTOZ CLEARKEY.** UACC(NONE)
```
This setup ensures that ICSF generates meaningful error messages and simplifies error identification.
Create a z/OS PKCS#11 token.Identify Token Support (ITS) uses confidential data stored in the ICSF PKCS#11 token. Access to the PKCS#11 token within ICSF is regulated by the CRYPTOZ class.
Note: Remember the tokenname value as you will need to use it in steps 3 and 4.
1. Activate the CRYPTOZ class.
```
SETROPTS GENERIC(CRYPTOZ) 
SETROPTS CLASSACT(CRYPTOZ) RACLIST(CRYPTOZ) 
SETROPTS RACLIST(CRYPTOZ) REFRESH
```
2. Replace #crypto with valid user IDs or RACF group names of the cryptographic administrators to create the PKCS#11 token that holds the private key.
3. Replace #tokename with the desired name or default it to JWTTOK.EQAAPPL token name.
```
RDEFINE CRYPTOZ SO.#tokenname UACC(NONE) DATA('CREATE PKCS#11 TOKEN')
PERMIT SO.#tokenname CLASS(CRYPTOZ) ACCESS(CONTROL) ID(#crypto) 
RDEFINE CRYPTOZ CLEARKEY.#tokenname UACC(NONE) DATA('CREATE PKCS#11 KEY') 
PERMIT CLEARKEY.#tokenname CLASS(CRYPTOZ) ACCESS(READ) ID(#crypto) 
```
4. Implement the CRYPTOZ changes.
```
SETROPTS RACLIST(CRYPTOZ) REFRESH
```
5. Create PKCS#11 token.
```
RACDCERT ADDTOKEN(#tokenname)
```
Define a new IDTDATA class profile to define the applications and users that uses Identify Token Support.For more information, see Activating and using the IDTA parameter in RACROUTE REQUEST=VERIFY and initACEE.
1. Activate the IDTDATA class.
```
SETROPTS GENERIC(IDTDATA) 
SETROPTS CLASSACT(IDTDATA) RACLIST(IDTDATA) 
SETROPTS RACLIST(IDTDATA) REFRESH
```
2. Create a generic SAF JWT provider by name EQAAPPL.
  - The profile format is <Identity Token (IDT) type>.<application ID>.<user ID>.<IDT issuer name> where Identity Token (IDT) is JWT, Application ID is EQAAPPL, User ID is a filter where an asterisk (*) is a pass-through that allows all user IDs to generate and validate a SAF JWT or define a valid user ID to limit the users, and IDT issue name is SAF.
  - SIGTOKEN specifies the PKCS#11 token for generating and validating identity token signatures. Replace #tokename with the desired name.
  - SIGALG is the type of algorithm used to generates identity token signatures.
  - ANYAPPL specifies whether the IDT can be used by any application name.
  - IDTTIMEOUT specifies the number of minutes that the identity token is valid.
```
RDEFINE IDTDATA JWT.EQAAPPL.*.SAF IDTPARMS(SIGTOKEN(#tokenname) SIGALG(HS512) ANYAPPL(YES) IDTTIMEOUT(30)) UACC(NONE) DATA('Debug Profile Service')
```
3. Implement the IDTDATA changes.
```
SETROPTS RACLIST(IDTDATA) REFRESH
```

Create private key for PKCS#11 token.Use the sample program EQAW.SEQASAMP(EQAPKCS1) to complete this step. The cryptographic administrator can customize and submit the EQAPKCS1 member.

//EQAPKCS1 JOB <job parameters>
//*********************************************************************
//* Licensed materials - Property of IBM                              *
//*                                                                   *
//* 5724-T07: IBM z/OS Debugger                                       *
//* Copyright IBM Corp. 2024, 2024 All Rights Reserved                *
//*                                                                   *
//* US Government Users Restricted Rights - Use, duplication or       *
//* disclosure restricted by GSA ADP Schedule Contract with IBM Corp. *
//*                                                                   *
//* This JCL creates a private key for a PKCS#11 token.               *
//*                                                                   *
//*                                                                   *
//* CAUTIONS:                                                         *
//* A) This job contains case sensitive path statements.              *
//* B) This is neither a JCL procedure nor a complete job.            *
//*    Before using this JCL, you will have to make the following     *
//*    modifications:                                                 *
//*                                                                   *
//* 1) Add the job parameters to meet your system requirements.       *
//*                                                                   *
//* 2) Provide, in variable BASE, the home directory of the           *
//*    product install (default is /usr/lpp/IBM/debug).               *
//*                                                                   *
//* 3) Provide, in variable TOKEN, the PKCS#11 token name defined     *
//*    during security setup (default is JWTTOK.EQAAPPL).             *
//*                                                                   *
//* 4) Provide, in variable KEYTYPE, the type of private key that     *
//*    must be created. Valid values are CLEAR and SECURE (default    *
//*    is CLEAR).                                                     *
//*                                                                   *
//* 5) Provide, in variable KEYSIZE, the size of the private key,     *
//*    in bits. The value must be a multiple of 8 and minimum 128     *
//*    (default is 256).                                              *
//*                                                                   *
//* 6) If hlq.SCSFMOD0 is not in LINKLIST, provide in variable HLQ    *
//*    the high level qualifier used during the installation of ICSF. *
//*                                                                   *
//* Note(s):                                                          *
//*                                                                   *
//* 1. THE USER ID THAT RUNS THIS JOB MUST HAVE SUFFICIENT ICSF       *
//*    AUTHORITY.                                                     *
//*                                                                   *
//* 2. KEYTYPE=SECURE requires that the Crypto Express Coprocessor    *
//*    is in EP11 mode.                                               *
//*                                                                   *
//* 3. For security, the KEYSIZE value should be at least half of     *
//*    the size of the hash used by the signing algorithm defined     *
//*    during the security setup. For example. if SIGALG(HS512) was   *
//*    used during security setup, KEYSIZE should be at least 256.    *
//*    See IDTPARMS SIGALG keyword in RACF PKCS#11 definition.        *
//*                                                                   *
//* 4. This job should complete with a return code 0.                 *
//*                                                                   *
//*********************************************************************
//         EXPORT SYMLIST=*
//*
//         SET BASE='/usr/lpp/IBM/debug'
//         SET TOKEN=JWTTOK.EQAAPPL
//         SET KEYTYPE=CLEAR
//         SET KEYSIZE=256
//         SET HLQ=CSF
//*
//USS      EXEC PGM=BPXBATCH,REGION=0M,TIME=NOLIMIT
//STDPARM  DD *,SYMBOLS=JCLONLY
SH &BASE./bin/eqa.csfpgsk.rex
-NAME=&TOKEN
-SIZE=&KEYSIZE
-TYPE=&KEYTYPE
-DEBUG
//STDENV   DD *,SYMBOLS=JCLONLY
STEPLIB=&HLQ..SCSFMOD0
//STDOUT   DD SYSOUT=*
//STDERR   DD SYSOUT=*
//*

Verify the security settings:
- RLIST APPL EQAAPPL
- RLIST CRYPTOZ SO.JWTTOK.EQAAPPL ALL
- RLIST CRYPTOZ CLEARKEY.JWTTOK.EQAAPPL ALL
- RACDCERT LISTTOKEN(JWTTOK.EQAAPPL)
- RLIST IDTDATA JWT.EQAAPPL.*.SAF ALL IDTPARMS