The documentation for ICSF and securing access to keys is hard to follow. There is a lot of it, but is not easily consumed. The security model has evolved over time, and I found the definitions confusing.
There are two orthogonal aspects of ICSF security
- Giving permission for a userid to use CSFKGUP utility, the ICSF ISPF panels, or the ICSF API. For example they can use list, but not define.
- Give permissions to groups of keys. You can define keys with names like DSENCR* have more controls that ANYONE*.
There are different levels of granularity for ICSF security.
- The default is no security – you need to define profiles to protect ICSF resources
- There is on|off security. If you have any security you can do anything
- Then there is granular security. You can control down to the operation type.
This blog post is about setting up security to protect keys.
“Required” definitions
You should define the profile below to give you granular controls.
RDEFINE XFACILIT CSF.CKDS.TOKEN.CHECK.LABEL.FAIL
SETROPTS RACLIST(XFACILIT) REFRESH
If the profile CSF.CKDS.TOKEN.CHECK.LABEL.FAIL is defined, a userid needs the appropriate access to the CSFKEYS profile:
- READ authority to read a label from the CKDS,
- UPDATE authority if creating a label,
- CONTROL authority if writing to or deleting a label.
A userid will also need access to the ICSF commands or APIs to be able to use the key.
If the CSF.CKDS.TOKEN.CHECK.LABEL.FAIL profile is not defined, and the userid has at least read access to a profile for the key, the userid can create, write or delete a label. If there is no profile for the key the userid has access to the key.
If you define the profile RDEFINE XFACILIT CSF.CKDS.TOKEN.CHECK.LABEL.WARN instead of CSF.CKDS.TOKEN.CHECK.LABEL.FAIL, and the userid has at least read access to a profile, the userid can create, write or delete a label. In addition it produces a warning message.
This feels like the same as RDEFINE XFACILIT CSF.CKDS.TOKEN.CHECK.LABEL.FAIL WARNING, so I do not see why RDEFINE XFACILIT CSF.CKDS.TOKEN.CHECK.LABEL.WARN is needed.
“Required” access control for exporting keys.
If you want to control who can export AES and DES keys you can enable this by defining a profile
RDEFINE XFACILIT CSF.XCSFKEY.ENABLE.AES
RDEFINE XFACILIT CSF.XCSFKEY.ENABLE.DES
SETROPTS RACLIST(XFACILIT) REFRESH
This turns on the checking system wide, you do not need to give any userid access to it.
To protect the export of all keys,
RDEFINE XCSFKEY * UACC(NONE)
PERMIT * CLASS(XCSFKEY) ID(SECADMN) ACCESS(UPDATE)
SETROPTS RACLIST(XFCSFKEY) REFRESH
You can generate individual or generic profiles for specific keys.
This security model feels broken, as I can read a key from the CKDS (encrypted with the hardware keys) write it to a file. Send the file to a remote system, and if they remote system has the same hardware keys, write the key to the CKDS. I still need access to read and write the key – but I do not use the XCSFKEY profile.
Defining profiles
The easy bits
You can define a standard security resource, such as
RDEFINE CSFKEY COLINSKEY ... PERMIT COLINSKEY CLASS(CSFKEY) ID(...) ACCESS(...)
Where COLINSKEY is the label of an entry in the CKDS or the PKDS. This can be a CIPHER key or a KEK key.
If there is no matching profile, there are no restrictions, so you may want to define a default
RDEFINE CSFKEY * UACC(NONE) AUDIT(ALL) warning
Where AUDIT(ALL) says report every time it is used, and WARNING reports if there is a security violation and gives access anyway. You can then use the information to create more specific profile. Once you have configured security you can remove the warning option, and protect your resources.
You need to specify access:
- READ to be able to read the profile
- UPDATE authority if creating a label,
- CONTROL authority if writing to or deleting a label.
But see “Required” definitions and the CSF.CKDS.TOKEN.CHECK.LABEL.FAIL to enable the granular access. Without the CSF.CKDS.TOKEN.CHECK.LABEL.FAIL profile, if a userid has at least read access to the CSFKEY profile, it can do anything with it. If there is no profile for the key, any userid can do anything with the key.
Which profile is used?
There are different ways of using a key (especially with APIs)
- Use the label character string of a key in the CKDS. You can pass a label into an API request. The label name is used in the security checks.
- You can read the token from the CKDS using the label, and pass the token (a long string of internal format data) to an API request. ICSF compares the token with the CKDS and if it locates a record with the same key value – it uses the label of the record in the security checks.
- You can get the token from elsewhere, for example read a data set. The same checks are done as in 2. above.
- If a record with the same key value was not found in the CKDS, (so you are using a key which your CKDS does not know about)
- If the profile CSF.CKDS.TOKEN.CHECK.LABEL.WARN or CSF.CKDS.TOKEN.CHECK.LABEL.FAIL in class(XFACILIT) is defined, and profile CSF.CKDS.TOKEN.CHECK.DEFAULT.LABEL in class(XFACILIT) is defined, then check the userid’s permission to profile CSF-CKDS-DEFAULT in class(CSFKEYS). See here.
What access do I need to the profile?
If you have CONTROL access to CSFBRCK CLASS(CSFSERV), and CONTROL access to the key’s profile SECKEY2 CL(CSFKEYS) you can delete the key SECKEY2.
If you have ALTER (more powerful than CONTROL) access to CSFBRCK CLASS(CSFSERV), the CSFKEYS profile is ignored you can delete any key.
You might want to give administrator only CONTROL access to the commands and APIs.
ColinPaice 