An Introduction to

z/OS Cryptographic Key Management

Eysha S. Powers
[email protected]
Enterprise Cryptography
0
What is cryptography?

Cryptography is defined as the practice and study of techniques for secure communication in the presence of
third parties (i.e. adversaries).

• Confidentiality – Preventing the disclosure of information to unauthorized individuals.

• Encrypt: Convert clear text to cipher text
• Decrypt: Convert cipher text to clear text
• Integrity – Maintaining and assuring the accuracy and consistency of data.
• Hash: Translate clear text to a fixed length hash value

Example (32-byte hash):

1025 4AD0 04D2 C7D5 77EA ADA0 E4C8 B76F A290 2F7C D03B F03E B527 A045 E200 238F

• Sign: Hash the clear text and encrypt the hash with a private key
• Verify: Hash the clear text then decrypt the sender’s hash using the sender’s public key and compare the
hash values
• Authentication – Verifying the identity of a party.
• Non-repudiation – Assuring that a party cannot deny that they created a message.

1
What are cryptographic keys?

Symmetric keys are simply a sequence of bits Asymmetric key pairs are generated using
of a precise length (i.e. key size) intended for complex math operations. They typically rely on
use in a cryptographic operation. trap door functions which are easy to compute in
• DES = 56 bits (i.e. 8 bytes) one direction but difficult to compute in the
• TDES = 56, 112, or 168 bits (i.e. 8, 16 or 24 bytes) opposite direction.
• AES = 128, 192, or 256 bits (i.e. 16, 24 or 32 bytes) • RSA = 1024 – 4096 bits
• EC BrainPool = 160, 192, 224, 256, 320, 384, or 512
Where do symmetric key bytes come from? • EC Prime = 192, 224, 256, 384 or 521
• Random number generators
• True random number generation requires:
• An entropy source of randomness to Why does the key length matter?
• Produce true random bytes • Short key lengths, specifically for symmetric
• Pseudo Random number generation requires: keys, can be brute force attacked, especially with
• An entropy source of randomness PLUS
• A deterministic mathematical algorithm to today’s computing speeds
• Produce pseudo random bytes • The NIST standards body recommends symmetric
keys of 24 bytes or larger.
Tip: Invoke /dev/random • Long key lengths, specifically for asymmetric
for random number keys, take much more time to generate
generation from the
z/OS Unix System • ECC key pairs offer stronger encryption than RSA
Services shell. with smaller key sizes
2
How are key values used for encryption
and decryption?

• Provide a key value and clear text to a cryptography algorithm to produce cipher text (i.e. encryption)
• Provide a key value and cipher text to a cryptography algorithm to produce clear text (i.e. decryption)

Encrypt
Clear Text Cipher Text
Decrypt

For symmetric encryption, the encryption key and decryption key are the same!

3
The Anatomy of a Fixed-Length Key Token
Internal AES fixed-length CCA key token (64 bytes)
010000000400C0D1F506FF13A5FFC26AE682510712FCF2327584F83E8289B966
F407117FD08A16825BDEBD86BE4F264700000000000000000100002071548319

Bytes Description
AES = Advanced Encryption
0 X’01’ flag indicating an internal key token Standard
1-3 X’000000’ for ICSF CCA = Common
4 Key token version number (X’04’) Cryptographic Architecture

5 Reserved – must be set to X’00’

6 Flag byte
7 1-byte Longitudinal Redundancy Check (LRC) checksum of a clear key value
8 - 15 Master key verification pattern (MKVP)
AES key values may
16 - 47 Key value, if present be 16, 24 or 32 bytes.
48 - 55 8-byte control vector (For a clear AES key token this value will be hex zeroes.)
56 - 57 2-byte integer specifying the length in bits of the clear key value See the Cryptographic Services
Integrated Cryptographic Service
Facility Application Programmer’s
58 - 59 2-byte integer specifying the length in bytes of the encrypted key value. Guide for additional details

60 - 63 Token validation value (TVV) 4

What happens when a key value is exposed or
compromised?

If the key value was in the clear

• The key value can be used to
decrypt sensitive data

If the key value was encrypted

• The key value cannot be used
to decrypt sensitive data without
the associated key encrypting
key (KEK)

5
What are key encrypting keys (KEKs)?
KEKs are keys that protect (e.g. encrypt, wrap) other keys

Master Keys Operational Keys

Master keys are used only to encipher Operational keys are used in various cryptographic operations (e.g. encryption).
and decipher keys.
Operational keys may be stored in a key store (e.g. data set, file, database) or
Master keys are stored in secure, returned back to the caller.
tamper responding hardware.
Operational keys may be clear, secure or protected.
Master key encrypted keys are
considered secure keys. Symmetric KEKs Asymmetric KEKs

Encrypt symmetric keys with another Encrypt symmetric keys with RSA public
Master keys should be changed symmetric key. keys
periodically.
Use ECC key pairs to derive a symmetric
All master keys are optional. Secure key. Use the derived symmetric key to
keys are only supported when their encrypt another symmetric key.
associated master key is active.

6
Understanding Clear, Secure and Protected Keys
Secure keys have key values that are encrypted by a Master Key
on a tamper-responding CryptoExpress adapter.
Clear Key
Key values are not encrypted.
Crypto operations may be
performed in CPACF or on a
Crypto Express adapter

Protected Key

Key values are encrypted

under a CPACF wrapping
key. Crypto operations are
performed only using CPACF

Secure Key
Note: With z/OS data set
Only protected keys created encryption, protected keys
Key values are encrypted
from secure keys should be under a Master Key. Crypto are implicitly created from
operations are performed only secure keys.
used for Pervasive Encryption. on a Crypto Express adapter
7
How do you generate, maintain and manage Master Keys?

• Using the Trusted Key Entry (TKE) Workstation

• Applicable for initialization of ICSF Key Data Sets Smart Cards
(i.e. key stores) and Crypto Express adapters
• Applicable for master key change operations
• Required for EP11 Master Key management &
PCI-HSM Master Key management
• Separate, priced product Trusted Key Entry (TKE) Workstation Smart Card Readers

• Using the ICSF Master Key Entry Panels

• Applicable for initialization of ICSF Key Data Sets
(i.e. key stores) and Crypto Express adapters
• Applicable for master key change operations
• Included with z/OS and ICSF

• Using the Pass Phrase Initialization (PPINIT) Panel

• Applicable for initialization of ICSF Key Data Sets
(i.e. key stores) and Crypto Express adapters
• NOT applicable for master key change operations
• Included with z/OS and ICSF

8
Special Considerations for Master Keys
• Master Keys are high value keys that must be protected.
• Loading Master Keys on a panel means that the key is viewable to passersby!
• The most secure way to load a Master Key is to use the TKE Workstation with smart cards.
• The P11 Master Key may ONLY be loaded using a TKE Workstation.
• If you plan to use the PPINIT or the Master Key Entry panels to manage Master Keys,
consider how you would save the key material for future re-entry (e.g. new Crypto Express
adapter, disaster recovery).
• For disaster recovery, the same Master Keys must be loaded onto the backup system.

Option Details Pros Cons

Print Screen Use a Print Screen key or tool to Sensitive material can be immediately Cannot use copy / paste to re-
capture the screen printed and stored in envelopes in a enter key material
locked safe. No need to save on a
local machine or USB stick.
Removable Copy and paste key material to a Easy to copy / paste the key material The key material is only as
Storage Media text file that is saved on a secure to the panels for re-entry. secure as the storage media.
storage device (e.g. USB stick).
Other Ideas?
9
How does ICSF generate, maintain and manage
operational keys?
• ICSF provides callable services and utilities to generate and store operational keys into ICSF
Key Data Sets (KDS) and/or return the keys to the caller
• Each KDS is a VSAM data set for persistent objects (e.g. keys, certificates) with programming
interfaces for object management.
• Each record in the KDS contains the object and other information about that object.

ICSF Key Data Sets

ICSF uses keys in cryptographic functions to
Cryptographic Key Data Set
• Protect data CKDS • CCA Symmetric Keys
• Protect other keys • AES, DES and HMAC

• Verify that messages were not altered PKA Key Data Set
• Generate, protect and verify PINs PKDS • CCA Asymmetric Keys
• RSA, ECC and Trusted Blocks
• Distribute keys
• Generate and verify signatures Token Data Set
TKDS • PKCS#11 Keys, Certificates
• All algorithms

10
Anatomy of a Key Record
Common Record Format CKDS
LRECL=2048 Offset Number of Bytes Field Name
Key lookup is performed using a key label
(CKDS, PKDS) or key handle (TKDS).
0 72 Key label or handle
72 8 Reserved
80 1 Version
CKDS
81 1 KDS type (CKDS, PKDS, TKDS)
Key Labels 82 2 Flags
DATASET.MEDICAL.G1.0001 84 4 Record length
88 8 Creation date

DATASET.MEDICAL.G1.0002 96 8 Creation time

104 8 Last update date
112 8 Last update time

The CKDS key material can be an 120 4 Key material length

AES, DES or HMAC key token 124 4 Key material offset
128 4 Metadata length
Note: Common Record Format was introduced in 132 4 Metadata offset
ICSF HCR77A1 for z/OS v1r13 and later
136 4 Reserved
11
 Understanding Key Labels
Every record in the CKDS has an associated key label.
When user applications or z/OS components invoke ICSF callable services (i.e. APIs), the application can specify a key
label as a parameter to identify the key for the callable service to use.
System Authorization Facility (SAF) policies control which users can use which keys (and callable services).
• The CSFKEYS class controls access to cryptographic keys in the ICSF CKDS and PKDS and enables/disables the use
of protected key.
• The CSFSERV class controls access to ICSF callable services and ICSF TSO panel utilities.

Policy-Based Dataset Encryption Example:

1. At data set allocation, DFSMS checks for a SAF
key label in the DATASET class resource that
CKDS
protects the data set and saves the key label
4. ICSF uses the key label specified by
2. At data set open, DFSMS checks that the DFSMS to locate the secure key in the
user is authorized to the CSFKEYS class CKDS
resource that protects the saved key label

DFSMS ICSF 5. ICSF calls the adapter to unwrap

3. DFSMS specifies the saved key
the key value from the Master Key
6. DFSMS sends the label to ICSF to retrieve the
and rewraps the key value under a
data and the protected secure/protected key from the CKDS
CPACF wrapping key to make a
key to CPACF for protected key. ICSF returns the
encryption. protected key to DFSMS.
12
Key Label Naming Conventions & Access Control
The CSFKEYS SAF class controls access to cryptographic keys in the ICSF Key Data Sets (CKDS and PKDS) and
enables/disables the use of protected keys.

With RACF-based SAF protection, CSFKEYS resources can be defined as discrete or generic (i.e. wildcard) profiles. As a
result, KDS key label naming conventions are important.

A key label can consist of up to 64 characters. The first character must be alphabetic or a national character (#, $, @). The
remaining characters can be alphanumeric, a national character (#, $, @), or a period (.).

Naming considerations:
• the LPAR associated with the key Policy-Based Dataset Encryption Example:
• the type of data being encrypted
• the owner associated with the key Key Label:
• the date the key was created
DATASET.<dataset_resource>.ENCRKEY.<seqno>
• the application intended to use the key
• The generic profile to protect the key CSFKEYS Profile:
• A sequence number for the key
RDEFINE CSFKEYS DATASET. <dataset_resource>.ENCRKEY.* UACC(NONE)
Note: <dataset_resource> would be replaced with the DATASET resource and <seqno> would be
replaced with a sequence number.
13
Additional Metadata

The metadata section of the Common Record Format KDS can be

used to store up to 500 bytes of custom installation data.

The Key Dataset Metadata Write (CSFKDMW) and Key Dataset

Metadata Read (CSFKDMR) callable services can be invoked to
read and write metadata.

Example Metadata:
• Key owner’s name
• Key owner’s email address
• Reference to data being encrypted (e.g. dataset name)
• Comments about the key and/or data encrypted by the key

Samples for using CSFKDMW and CSFKDMR are available on the

IBM Crypto Education Community… https://ibm.biz/BdjcFx

Metadata support requires ICSF HCR77B0 or later and a Common Record Format KDS
14
What is the relationship between a key record, a
key token and a key value?
Key Token
Key Record

Key
Value

The key record contains a key

token which contains a key value.

15
How do you create a Common Record Format KDS?

Step 1: Step 2:
Allocate new Key Data Sets. A: If there are no existing keys to convert
• CKDS: SYS1.SAMPLIB(CSFCKD3) then
• PKDS: No change to allocation process
• Initialize new Key Data Sets using the ICSF
• TKDS: SYS1.SAMPLIB(CSFTKD2) panels (all KDS types) or JCL job (TKDS)
B: If there are existing keys to convert to the
new format
CKDS PKDS • Run the KDS Conversion utility from
the ICSF KDS Management panels
(for each KDS type to be converted)

TKDS

See the next slide for CKDS allocation considerations.

16
CKDS Allocation Considerations

The amount of primary space required for the CKDS depends on the number of keys the dataset will
initially contain.
The maximum record size of a
DATA key = 140-byte header +
Primary Space = initial key count * record size 40-byte metadata section + 64-
For example: byte key token + 500 bytes of
metadata = 744 bytes
Initial load of 10K keys, all fixed length tokens.
Primary Space = 10K * 744 = approx. 7.3 MB

The amount of secondary space depends on how many keys will be added.

Secondary Space = future key count * record size

For example, 83K keys added every year for 10 years = 830K keys
Secondary Space = 830K * 744 = approx. 603 MB

17
How do you view the contents of a Key Data Set?

With HCR77C1, ICSF supports a CKDS Browser (ICSF Panel Option 5.5).
Note: Alternative methods include IDCAMS REPRO, PKCS #11 Token (TKDS) Browser and the Key Dataset List
(CSFKDSL) callable service.

18
Additional z/OS Key Stores
• RACF provides the RACDCERT RACF
GENCERT command to generate and
store keys into the RACF database and
ICSF Key Data Sets (PKDS and TKDS). System SSL JCE
RACF also provides the RACDCERT RACF
CONNECT command to add certificates Database
to RACF Keyrings. Includes RACF
keyrings

• SystemSSL provides the gskkyman Key

Database
utility to generate and store certificates Files ICSF
into key database files. SystemSSL can
CCA PKCS #11
also read from RACF Keyrings and
generate and store certificates into Java
Key
PKCS#11 Tokens (TKDS). The CKDS is used Stores
for z/OS Data Set CKDS
Encryption
• JCE provides APIs and utilities to
generate and store keys and certificates TKDS
into ICSF Key Data Sets, RACF PKDS
Keyrings, and Java Key Stores.

19
Key Life Cycle (Simple View)

Start
Compromised

Archived (Restricted)

Pre-Activation Activated Deactivated Destroyed

Key Creation Date Key Validity Start Date Key Validity End Date

Note: Terms in orange

Suspended
refer to the associated
field in the key record
and/or metadata Archived (Permitted
or Restricted) Note: See NIST SP 800-57
for additional state transitions
20
Locating Key Life Cycle Metadata in KDS Records

Tag Meaning
X’0001’ Variable metadata block
X’0002’ Record create date Tag Meaning
X’0003’ Record update date X’0001’ Installation user data
X’0004’ Key material validity start date X’0002’ Service for reference
X’0005’ Key material validity end date X’0003’ Record archive date
X’0006’ Last reference date (YYYYMMDD) X’0004’ Record recall date
X’0007’ Last reference date (first 8 bytes of the X’0005’ Key fingerprint
value returned by store clock extended
X’0006’ Retained key information
instruction)
X’8000’ - X’FFFF’ Installation metadata
X’0008’ Record archive date
X’0009’ Record archive flag Remember…

X’000A’ Record prohibit archive flag Metadata support requires ICSF HCR77B0 or later and a Common Record
Format Key Data Set
X’000B’ Record recall date Key Dataset Metadata Write (CSFKDMW) and Key Dataset Metadata Read
(CSFKDMR) callable services can be invoked to read and write metadata.

21
Is there a way to audit key life cycle transitions?

Key life cycle auditing must be explicitly enabled in the ICSF Installation Options
Data Set (IODS) or the SETICSF OPT operator commands.

ICSF IODS Option SMF Record Type

AUDITKEYLIFECKDS(TOKEN(YES),LABEL(YES)) Type 82 Subtype 40

AUDITKEYLIFEPKDS(TOKEN(YES),LABEL(YES)) Type 82 Subtype 41

AUDITKEYLIFETKDS(TOKENOBJ(YES),SESSIONOBJ(YES)) Type 82 Subtype 42

Let’s take
a look!

22
 SMF Record Type 82 Subtype 40
CCA Symmetric Key Lifecycle Event
Tag Name Description
X’0100’ KEY_EVENT Key event. CCA Symmetric Key Lifecycle Events
X’0101’ KDS_LABEL The label in the KDS
X’0102’ KDS_DSNAME The data set name of the KDS associated with the event.
X’0103’ KEY_NAME The key name from the token. Applies to variable-length CCA tokens only.
X’0105’ KEY_FPRINT One or more key fingerprints.
X’0106’ SERVICE The service associated with the event.
X’0108’ TOK_FMT The format of the token.
X’0109’ KEY_SEC Key security.
X’010A’ KEY_ALG Key algorithm.
X’010B’ KEY_TYPE Key type. Applies to variable-length CCA tokens only.
X’010C’ KEY_CV Key control vector. Applies to fixed-length DES CCA tokens only.
X’010D’ KEY_USAGE_CKDS Key usage fields. Applies to variable-length CCA tokens only.
X’010E’ KEY_LEN The length of the key (in bits). Applies to fixed-length CCA tokens only.
X’010F’ KEY_CP Key crypto period.
X’0118’ KEY_TIV A key token identification value. Applies to fixed-length CCA tokens only.
X’0119’ KEY_COMP_TAG The key is compliant tagged. Applies to fixed-length CCA tokens only.
23
SMF Record Type 82 Subtype 40
CCA Symmetric Key Lifecycle Event

24
How do you control key usage?
System Authorization Facility (SAF) Policies Control Vectors
• The CSFKEYS class controls access to cryptographic A control vector ensures that an operational key can only
keys in the ICSF Key Data Sets (CKDS and PKDS) and be used in cryptographic operations for which it is intended.
enables/disables the use of protected keys. For example, the control vector for a DATA key ensures
• The SYMCPACFWRAP field of the ICSF segment that such a key can be used only in the data encryption and
enables you to specify whether ICSF can rewrap decryption functions.
the encrypted key using the CPACF wrapping key. Control vectors are only supported for fixed-length DES
• The SYMCPACFRET field of the ICSF segment CCA key tokens.
enables you to specify whether ICSF can return
Fixed-length AES CCA key tokens have a zeroed control
the protected-key form of the CCA token to a
vector. These keys can only be created as DATA keys to be
caller.
used for data encryption and decryption. There are no
• The CSF.* resources in the XFACILIT class define rules variants.
for the user of encrypted key tokens that are stored in
Note: Variable-length symmetric key tokens provide key-
the CKDS and PKDS.
management fields (kmf) and key-usage fields (kuf) to
control key usage.

25
Is there a way to audit key usage?

Key usage auditing must be explicitly enabled in the ICSF Installation Options
Data Set (IODS) or using the SETICSF OPT operator commands.

ICSF IODS Option SMF Record Type

AUDITKEYUSGCKDS(TOKEN(YES),LABEL(YES),INTERVAL(n)) Type 82 Subtype 44

AUDITKEYUSGPKDS(TOKEN(YES),LABEL(YES),INTERVAL(n)) Type 82 Subtype 45

AUDITPKCS11USG(TOKENOBJ(YES),SESSIONOBJ(YES),NOKEY(YES), Type 82 Subtype 46 &

INTERVAL(n)) Type 82 Subtype 47

Note: The INTERVAL in which the key usage data is aggregated can be from 1 to 24 hours
Let’s take
in the Installation Options Data Set. However, it can be from 1 second to 24 hours using the a look!
SETICSF OPT operator command.

26
SMF Record Type 82 Subtype 44
CCA Symmetric Key Usage Event
Tag Name Description
X’0101’ KDS_LABEL The label in the KDS
X’0103’ KEY_NAME The key name from the token. Applies to variable-length CCA tokens only.
X’0105’ KEY_FPRINT One or more key fingerprints.
X’0106’ SERVICE The service associated with the event.
X’0108’ TOK_FMT The format of the token.
X’0109’ KEY_SEC Key security.
X’010A’ KEY_ALG Key algorithm.
X’010B’ KEY_TYPE Key type. Applies to variable-length CCA tokens only. Remember that
X’010C’ KEY_CV Key control vector. Applies to fixed-length DES CCA tokens only. fixed-length AES
CCA tokens always
X’010D’ KEY_USAGE_CKDS Key usage fields. Applies to variable-length CCA tokens only. have a zeroed
control vector so
X’010E’ KEY_LEN The length of the key (in bits). Applies to fixed-length CCA tokens only.
neither of these fields
X’0113’ START_TOD Start time of the interval in STCKE format. apply.
X’0114’ END_TOD End time of the interval in STCKE format.
X’0115’ USG_COUNT Number of usages accounted for in this record
X’0116’ KEY_OLD The key is internal, but not wrapped under the current master key.
X’0118’ KEY_TIV A key token identification value. Applies to fixed-length CCA tokens only.
27
X’0119’ KEY_COMP_TAG The key is compliant tagged. Applies to fixed-length CCA tokens only.
SMF Record Type 82 Subtype 44
CCA Symmetric Key Usage Event

An ICSF audit section which is supported with

SMF Record Type 82 Subtype 40 and higher
may contain additional audit information. For
example, the end user RACF user id
associated that used the key.

28
SMF Record Type 82 Subtype 28
High Performance Encrypted Key

Name Description
SMF82HPSK_FLAGS High performance encrypted key flags

Bit 0: Rewrapping not permitted for this symmetric key

Bit 1: Rewrapping was permitted for this symmetric key.
Bit 2: The list of labels is incomplete.
Bit 3: The key identifier was supplied as a key token, not
as a label in the CKDS.
SMF82HPSK_FUNCTION Name of the service that issues this SMF record. The
name is in the form of CSFzzzz.
SMF82HPSK_SYM_LABEL_CNT Number of SYM labels present in this record.
The following is repeated SMF82HPSK_SYM_LABEL_CNT number of times
SMF82HPSK_SYM_LABELS The format of the token.

29
SMF Record Type 82 Subtype 28
High Performance Encrypted Key

30
Is there a way to audit crypto engine usage?
ICSF will provide crypto usage tracking of applications and components that invoke ICSF services in HCR77C1. Crypto
usage tracking can be enabled/disabled at ICSF initialization using the Installation Options Data Set (IODS) or dynamically
using SETICSF OPT operator commands.

ICSF IODS Option SMF Record Type

STATS(ENG,SRV,ALG) Type 82 Subtype 31

ENG: Tracks crypto engine usage. When enabled, ICSF tracks the usage of Crypto Express Adapters, Regional
Cryptographic Servers, CPACF and Software.
SRV: Tracks crypto service usage. When enabled, ICSF tracks the usage of ICSF callable services and User Defined
Extensions (UDX).
ALG: Tracks crypto algorithm usage. When enabled, ICSF tracks the usage of crypto algorithms that are referenced in
cryptographic operations.

Crypto usage data collection is synchronized to the SMF recording interval. Your SMFPRMxx member must contain:
• The collection interval (INTVAL)
• The synchronization value (SYNCVAL) Let’s take a
• The Crypto Usage Statistics Subtype 31 for ICSF Type 82 records (TYPE) look!
31
SMF Record Type 82 Subtype 31 (Fixed Header)
Crypto Usage Statistics

Name Description
SMF82STAT_VER Version number
SMF82STAT_DOMAIN Current domain index
SMF82STAT_LEN Length of this header
SMF82STAT_TRIPL_OFF Offset from SMF82STAT into triplet section
SMF82STAT_TRIPL_LEN Length of triplet section
SMF82STAT_D_INTVAL_STARTE Start time (TOD clock) of the SMF interval in STCKE format.
SMF82STAT_D_INTVAL_ENDE End time (TOD clock) of the SMF records in STCKE format.
SMF82STAT_D_USERID_AS The HOME address space user id
SMF82STAT_D_USERID_TK The task level user id (if present)
SMF82STAT_D_JOBID The job id for the HOME address space.
SMF82STAT_D_JOBNAME The job name for the HOME address space.
SMF82STAT_D_JOBNAME2 The job name of the SECONDARY address space (ICSF caller).
SMF82STAT_D_PLEXNAME The Sysplex member name.

32
SMF Record Type 82 Subtype 31 (Triplets)
Crypto Usage Statistics

Tag Name Description

X‘0201’ SMF82STAT_ENG_CARD Identifier, serial number and usage count
X‘0202’ SMF82STAT_ENG_RCS Identifier, serial number and usage count
X‘0203’ SMF82STAT_ENG_CPACF Usage count
X‘0204’ SMF82STAT_ENG_SOFTW Usage count
X‘0205’ SMF82STAT_SRV Service name and usage count
X‘0206’ SMF82STAT_SRVUDX UDX service name and usage count
X‘0207’ SMF82STAT_ALG Algorithm name and usage count

Generally, crypto usage statistics are intended to help you determine:

• Which jobs/tasks are using the various crypto engines
• Which crypto adapter types are getting the most requests Use the STATSFILTERS(NOTKUSERID)
• If any crypto requests are being handled in software installation options data set keyword to
• What are the peak periods of crypto utilization reduce the number of SMF records in
• Which ICSF services are being invoked by other z/OS components high transaction environments.
• Which jobs / tasks are using out-of-date algorithms or key sizes
33
SMF Record Type 82 Subtype 31
Crypto Usage Statistics

34
What IBM tools are available to manage keys?
Integrated Cryptographic Services Facility (ICSF) Trusted Key Entry (TKE) Workstation

ICSF provides callable services and utilities that TKE securely manages multiple Cryptographic
generate, store, and manage keys, and also perform Coprocessors and keys on various generations
cryptographic operations. of IBM Z from a single point of control.

Supports Master Keys and Supports Master Keys and Operational Keys
Operational Keys
Let’s take a closer look

Enterprise Key Management Foundation (EKMF) Security Key Lifecycle Manager (SKLM)

EKMF securely manages keys and certificates for SKLM v2.7 provides key storage, key serving and key
cryptographic coprocessors, hardware security lifecycle management for IBM and non-IBM storage
modules (HSM), cryptographic software, ATMs, and solutions using the OASIS Key Management
point of sale terminals. Interoperability Protocol (KMIP) and IBM Proprietary
Protocol (IPP).
Supports Operational Keys
Supports Operational Keys for Self Encrypting
Devices (SEDs)

35
z/OS Integrated Cryptographic Services Facility (ICSF)

ICSF works with the hardware cryptographic features and the Security Server (RACF element) to provide
secure, high-speed cryptographic services in the z/OS environment.

• ICSF provides the application programming interfaces by which applications request cryptographic
services.
• ICSF provides panels to load CCA master key values onto secure cryptographic features, allowing the
hardware features to be used by applications.
• ICSF callable services and programs can be used to generate, store, and manage keys that are used in
the cryptographic functions.

Cryptographic Key Data Set Token Data Set

CKDS • CCA Symmetric Keys TKDS • PKCS#11 Keys, Certificates
• AES, DES and HMAC • All algorithms

Public Key Data Set

PKDS • CCA Asymmetric Keys
• RSA, ECC and Trusted Blocks
36
Key Management Features for z/OS ICSF
ISPF Panels Application Programming Interfaces
• Generate, load and view Master Keys • Create symmetric and asymmetric keys
• Panel 1: COPROCESSOR MGMT • CCA Symmetric Keys: CSNBKTB/2 (build key token),
CSNBKGN/2 (generate key token), CSNBRNG/L
• Panel5: UTILITIES (generate random numbers)
• Manage key records in the CKDS • CCA Asymmetric Keys: CSNDPKB (build PKA key token),
• Panel 5.5: CKDS KEYS (i.e. CKDS Browser) CSNDPKG (generate PKA key token)
• Panel 5.5.7 can generate a secure AES DATA key • PKCS #11 Keys: CSFPGSK (generate PKCS #11 secret
and store in the CKDS key), CSFPGKP (generate PKCS #11 key pair)
• Manage Key Records in ICSF Key Data Sets
• Manage key records in the PKDS
• CKDS: CSNBKRC/2 (create), CSNBKRW/2 (write),
• Panel 5.6: PKDS KEYS CSNBKRR/2 (read), CSNBKRD (delete)
• Manage PKCS #11 tokens in the TKDS • PKDS: CSNDKRC (create), CSNDKRW (write),
• Panel 5.7: PKCS11 TOKEN (i.e. TKDS Browser) CSNDKRR/2 (read), CSNDKRD (delete)
• TKDS: CSFPTRC (create, copy), CSFPTRL (list),
• Generate keys in bulk CSFPTRD (delete), CSFPGAV (get attributes), CSFPSAV
• Panel 8: KGUP - Key Generator Utility Program (set attributes)
• General KDS & Metadata: CSFKDSL (kds list),
CSFKDMW (metadata write), CSFKDMR (metadata read)

37
IBM Trusted Key Entry (TKE) Workstation
TKE is an appliance that simplifies the management of IBM Z Host Cryptographic
Modules running in Common Cryptographic Architecture (CCA) or IBM Enterprise
PKCS#11 (EP11) mode, using compliant level management techniques.

IBM Z Server

38
Key Management Features for TKE
Features for Managing Module Scoped and Domain
Scoped Administrative settings on Host Cryptographic
Modules Popular Features
• Featuring: Secure, simplified administrative management • Domain Grouping to broadcast a command to a
of multiple domain host cryptographic modules in
set of domains
complex configurations
• Secure Loading of CCA Master Keys (MKs)
Secure, hardware-based Master Key and Operational • Manage domains higher than 16
key management • Migration Wizards
• Featuring: Compliant level hardware-based key • Enable/disable Access Control Points (ACPs)
management with proper encryption strengths, dual • Loading MKs for inactive LPARs
controls, and security relevant auditing • Loading PIN decimalization tables
Highly secure and efficient movement of administrative • Loading EP11 Master Key
settings from one Host Cryptographic Module to
another
• Providing: Secure, fast, and accurate deployment of new
crypto modules on production, test, or disaster recovery
systems

39
IBM Enterprise Key Management Foundation
(EKMF)
• is used for generating all new
Secure keys by users authenticated with
smart cards or automatically
workstation based on requests. Workstation
utilizes IBM 4765/7

Central Key
• contains keys and metadata for Repository
Central all cryptographic keys produced
by the EKMF workstation.
repository This enables easy backup and
recovery of key material.

• features monitoring capabilities

EKMF and enables planning of future
Browser key handling session to be
executed on the workstation.

EKMF
EKMF Workstation
Note that while this is a mainframe centric view,
Browsers
EKMF supports distributed platforms as well. Custodians
40
Key Management Features for EKMF
Basic key management functions include:
• key generation
• key import
• key export
• key print
• key administration

Key management functions are controlled by key

templates and key policies. Key templates:
• control functions for a key
• predefine key attributes

When generating or entering a key, the key is

automatically distributed to the servers specified in
the key template.
• ICSF Key Data Sets
• RACF Key Rings (i.e. SKLM, z/OS PKI)
• … and more

41
IBM Security Key Lifecycle Manager (SKLM)
IBM Security Key Lifecycle Manager provides centralized key management for
self-encrypting devices.

Self-encrypting devices SKLM v2.7

protect data if you lose

control of the device.
• Data on the truck traveling
between datacenters
• Data at rest within the
datacenter
• Decommissioned storage
devices

42
Key Management Features for SKLM

SKLM for Distributed Systems SKLM for z/OS

SKLM v2.7 supports the IBM Proprietary SKLM for z/OS supports the IBM
Protocol (IPP) and industry-standard Key Proprietary Protocol (IPP) for key
Management Interoperability Protocol distribution with storage devices.
(KMIP) for key distribution with storage SKLM for z/OS can use ICSF through
devices. JCE hwkeytool or RACF GENCERT
commands to push RSA key pairs to the
Features include: ICSF PKDS and AES keys to the ICSF
• Key generation, import and export CKDS.
• Secure storage of key material
• Automatic assignment and rotation Features include:
of keys • Key generation, import and export
• Key serving at the time of use • Secure storage of key material
• Key serving at the time of use

Note: SKLM can not be used to manage z/OS data set encryption keys.

43
 Key Management Activities
SEDs = Self-encrypting devices
Activity ICSF TKE EKMF SKLM
Authorization SAF Authorization (CSFKEYS and CSFSERV) YES YES YES SKLM for z/OS
Tasks
Key Auditing (master keys, operational keys) YES YES OPERATIONAL KEYS YES
Master Key Tasks Master Key Entry YES, PANELS YES, SECURE NO NO
Master Key Change YES, PANELS YES, SECURE NO NO
Master Key Zeroize NO, HMC / SE YES NO NO
Basic KDS Tasks Operational Key Record Creation (and naming) YES NO YES, GUI-BASED SEDs
Operational Key Record Update YES NO YES, GUI-BASED SEDs
Operational Key Record Deletion YES NO YES, GUI-BASED SEDs
Basic Key Tasks Operational Key Generation YES SMALL SCALE YES, GUI-BASED SEDs
Operational Key Import YES SMALL SCALE YES, GUI-BASED SEDs
Operational Key Export YES NO YES, GUI-BASED SEDs
KDS Metadata Operational Key Archival YES NO NON-KDS,GUI-BASED NO
Tasks
Operational Key Restore YES NO NON-KDS,GUI-BASED NO
Operational Key Expiration YES NO NON-KDS,GUI-BASED NO
Maintenance Rekeying encrypted data (operational keys) YES NO NO SEDs
Tasks
Recovery Tasks Disaster Recovery (master keys, operational keys) YES YES OPERATIONAL KEYS SEDs 44
Appendix:
Key Rotation

45
How do you rotate keys?
There are two types of key rotation that you can perform on IBM Z:
• Master Key Rotation
• Operational Key Rotation

Master Keys Operational Keys

Master keys are used only to encipher and Operational keys are used in various
decipher keys. cryptographic operations (e.g. encryption).

Master keys are stored in secure, tamper Operational keys may be stored in a key store
responding hardware. (e.g. data set, file, database) or returned back to
the caller.

Operational keys may be encrypted by a Master

Key to be considered secure keys.

46
How does Master Key Rotation work?
Master key rotation involves re-enciphering secure, operational keys that
reside in Key Data Sets. Re-encipherment occurs in the secure boundary of
the Crypto Express adapter. ICSF synchronizes the changes across members
of the sysplex sharing the same Key Data Set (when applicable).

For each secure key:

• The operational key value is decrypted from under the current Master Key
• The operational key value is encrypted with the new Master Key
After all secure keys have been re-enciphered:
• The current Master Key becomes the old Master Key
• The new Master Key becomes the current Master Key

Using Coordinated Change MK, the master key rotation is non-disruptive.

Master keys can be rotated while crypto workloads are running.

48
 Master Key Rotation Procedure
1. Allocate new Key Data Sets.
Example data set allocation for the CKDS…
2. Generate and load new Master Keys using
TKE or ICSF. (You must load the same MK The current / active key data set containing the existing
on all sysplex members sharing the KDS.) keys could be EYSHA.ICSF.CSF77C1.20180101.CKDSR

3. Initiate the Coordinated Change MK (CCMK) The new key data set to contain the re-enciphered keys
operation using TKE or ICSF could be EYSHA.ICSF.CSF77C1.20190101.CKDSR
Note: CCMK can be run on a single system as well as a
sysplex.

ICSF Master Key

Entry Panel

Trusted Key Entry (TKE) Workstation Let’s take a

closer look

48
Master Key Rotation affects Crypto Express Adapters and Key Tokens
32-byte AES Master Key
AES Master Key Verification
2F44E4823BCD2852 Pattern (MKVP)
1. Load 8D0F3F9EB109A9A9
F506FF13A5FFC26A
E57C507CF7D684C5
ED9A9AD68D0E9B12
Crypto Express6S 2. Initiate Coordinated Change MK

64-byte AES DATA Secure Key Token 3. Re-encipher key

4. Update MKVP CKDS
010000000400C089F506FF13A5FFC26A 5. Store in new F506FF13A5FFC26A AES MKVP
1059E00CA93B5876F0A6B6E45E3835E5 data set
A4AC94D47D52A8781BDDF9BF4CA32F51
00000000000000000100002033FC0DCD
Ciphertext is DATASET.MEDICAL.M1.0001
changed
32-byte AES DATA Clear Key Value
ABC82AE086AE237FEAC3DFD49091E15E DATASET.MEDICAL.M1.0002
E26B98B76784F4227CC32C0B907184A6 Underlying Clear
Key Value is
unaffected 49
 How do you rotate operational keys? Two approaches!
Approaches Policy-Based Data Set Encryption Example Considerations

“Aging Out” • Data sets were encrypted using Operational Key • Not sufficient when a key has been
DATASET.MEDICAL.G1.0001 compromised
• At some interval, the ICSF admin generates • Affects new data only
DATASET.MEDICAL.G1.0002 • Existing data is not re-encrypted
• The security admin updates associated DATASET resources to use • Old keys must remain in the CKDS
key label DATASET.MEDICAL.G1.0002 from that point forward. • More keys to manage
• DATASET.MEDICAL.G1.0001 is still in use by old / existing • Key sequence numbers are
data recommended
• DATASET.MEDICAL.G1.0002 is used for new data
Re-encrypt • Data sets were encrypted using Operational Key • Recommended when a key has been
all data DATASET.MEDICAL.G1.0001 compromised
• At some interval, the ICSF admin generates • Affects all data (new and existing)
DATASET.MEDICAL.G1.0002 • Must identify ALL data encrypted with
• The security admin updates associated DATASET resources to use the old key
key label DATASET.MEDICAL.G1.0002 from that point forward. • Archiving the old key is
• DATASET.MEDICAL.G1.0002 is used for new data recommended over deleting the old
• All data encrypted with DATASET.MEDICAL.G1.0001 must be key
identified and re-encrypted • Crypto-periods may be established to
• DATASET.MEDICAL.G1.0001 would no longer be in use restrict key usage. 50
Operational Key Rotation Procedure –
“Aging Out”

For this example procedure, DATASET.MEDICAL.G1.0001 had been used to

encrypt some data sets.

1. Generate a new operational key, DATASET.MEDICAL.G1.0002

2. Locate all DATASET profiles associated with DATASET.MEDICAL.G1.0001
3. Update the DATASET profiles with the new key label,
DATASET.MEDICAL.G1.0002

All newly allocated datasets will use DATASET.MEDICAL.G1.0002.

Operational key rotation by “Aging out” is non-disruptive. Existing workloads can

continue to run while the key is rotated.
51
Operational Key Rotation affects Encrypted Data - “Aging Out”
DSS Print DSS Print
Output Output
1A3664B4 Hello World Hello World 2 76C8882C
16C8D438 EFE5B833
6A931531 Encrypt Encrypt 5B601736
CCF132D3 18931456
D10869EE 3B84BDE3
6768619D 74EF493F

CKDS
32-byte AES DATA Clear Key Values
ABC82AE086AE237FEAC3DFD49091E15E
DATASET.MEDICAL.G1.0001
E26B98B76784F4227CC32C0B907184A6

BE3D381313C9E9A29E20ED1726F5570E
DATASET.MEDICAL.G1.0002
C10C40CB57F9B124ECD60985D8B3948C

883346BC977EE031D103F4B271253584
DATASET.MEDICAL.G1.0003
4717564BA80718CDCC71AE9BC07E2A2F
52
Operational Key Rotation Procedure –
Re-encrypt All Data
For this example procedure, DATASET.MEDICAL.G1.0001 had been used to encrypt some
data sets.
Part 1 (Same process as “Aging Out”)
1. Generate a new operational key, DATASET.MEDICAL.G1.0002
2. Locate all DATASET profiles associated with DATASET.MEDICAL.G1.0001
3. Update the DATASET profiles with the new key label, DATASET.MEDICAL.G1.0002
Part 2 (Re-encrypt existing data sets)
1. Identify all data sets encrypted with old key label DATASET.MEDICAL.G1.0001
• DASD and Tape
• Migrated and Active
• …
2. Allocate new data sets covered by DATASET profiles associated with
DATASET.MEDICAL.G1.0002
3. Copy the data from the old data sets to the new data sets
• The user performing this operation requires access to DATASET.MEDICAL.G1.0001 and
DATASET.MEDICAL.G1.0002 for the duration of the operation.
4. Delete the old data sets
5. Archive the old key, DATASET.MEDICAL.G1.0001
All data sets that had been encrypted with DATASET.MEDICAL.G1.0001 are now encrypted
with DATASET.MEDICAL.G1.0002.
Operational key rotation by re-encrypting all data is typically disruptive. If you are running Db2
workloads, you can initiate an online reorg to make the re-encryption process non-disruptive.
For other workloads, you will need to stop the workload while the key is being rotated. 53
Operational Key Rotation affects Encrypted Data – Re-encrypt All Data
ISPF Browse /
DSS Print Output
DFSMS Open

Hello World 1A3664B4 76C8882C

16C8D438 EFE5B833
Encrypt 6A931531 Re-encrypt 5B601736
CCF132D3 18931456
D10869EE 3B84BDE3
6768619D 74EF493F
Different key =
different cipher text

CKDS
32-byte AES DATA Clear Key Values
ABC82AE086AE237FEAC3DFD49091E15E
DATASET.MEDICAL.G1.0001
E26B98B76784F4227CC32C0B907184A6

BE3D381313C9E9A29E20ED1726F5570E
DATASET.MEDICAL.G1.0002
C10C40CB57F9B124ECD60985D8B3948C

883346BC977EE031D103F4B271253584
DATASET.MEDICAL.G1.0003
4717564BA80718CDCC71AE9BC07E2A2F
54
 How do you decide which key rotation approach to use?

Choose the key

rotation approach
that meets your
Did your auditor tell security policy,
you to that you compliance
must rotate your requirements and
Is there a regulation keys? Did they operational needs.
or security policy specify which key
that requires the must be rotated?
Was the operational rotation of the key?
key compromised? Does it specify • Rotate the Master
Key or operational
Was the Master • Rotate the which key must be
key as indicated
operational key rotated?
Key compromised by your auditor
(or no longer using the “re- • Rotate the Master
known)? Is there a encrypt all data” Key or operational
new master key approach key as indicated
officer? by your security
policy
• Rotate the Master
Key
55
Questions?

56
Additional Resources

IBM Crypto Education Community

https://www.ibm.com/developerworks/community/groups/community/crypto

Master Key Management Materials

https://ibm.biz/BdiKRz

57