cpacfinfo - Obtain CPACF cryptographic information

6.18 LPAR mode z/VM guest KVM guest

Use the cpacfinfo command to display the functions and instructions that are available with the Central Processor Assist for Cryptographic Function (CPACF). The command also displays firmware authentication information in form of a hash when running on IBM® z17 ™.

Prerequisites

The cpacfinfo command reads entries in sysfs that supply the instruction information. If your kernel level does not contain these sysfs entries, a warning is issued and the command exits.

The firmware authentication information was introduced with the Message Security Assist (MSA) facility level 13 on IBM z17 . Earlier hardware does not show firmware authentication information.

cpacfinfo syntax

Where:

-m or --msa

shows which MSA levels are available and how many functions of the ones introduced by this level are available. Use with the -f option to list all functions under the corresponding MSA level. Use with the -i option to provide only specific instructions. Use the -a and -n options to filter the displayed functions. Ignores the -q option.

-f or --functions

shows all functions of all available instructions sorted by instruction. The default is to show enabled functions. Use with the -a and -n options to filter the functions. Specify both -a and -n to list all functions. The cpacfinfo command shows functions that are not known as UNKNOWN.

-i or --instructions <INS>

lists the specified instructions. To limit the list, supply the instructions you are interested in. Separate multiple instructions by commas. Use together with the -a option to list available instructions, the -n option to list unavailable instructions, or both to list all instructions.

Possible values for instructions are:

km
kmc
kimd
klmd
kmac
pckmo
kmf
kmctr
kmo
pcc
prno
kma
kdsa

-a or --available

shows available functions.

-n or --not-available

shows unavailable functions. Depending on the hardware, not all MSA levels might be available which can be checked with the -m option. In such cases it might not be obvious which functions of which instructions are available. This option together with the -a option shows all possible functions.

--format human|json

specifies the output format, either human (default) or json. The value json creates JSON output format. Can be used with -m. Options -a, -n, -f, -q, or -i have no effect on the output.

The value human creates a human-readable output format.

-q or --quiet

suppresses the firmware authentication information, if it is available. On machines that do not supply this information, this option is ignored.

-h or --help

displays help information for the command. The short form -h displays a help summary. Use the long form --help to obtain more information. To view the command man page, enter man cpacfinfo.

-v or --version

displays version information for cpacfinfo.

Examples

To show available instructions and firmware authentication codes:

# cpacfinfo 
 Cipher Message (KM)
   Format: 0; Hash length: 32; IFCL version: 24
   Hash:
     47 bb 52 ba a7 4e b0 a0 13 e5 f6 7e 04 f5 68 d5
     5c d1 d0 b3 ae ad 20 da 32 7a 17 0a 04 64 0c af

Cipher Message with Chaining (KMC)
...

To show available functions of all instructions sorted by instruction:

# cpacfinfo -f 
 Cipher Message (KM)
   Format: 0; Hash length: 32; IFCL version: 24
   Hash:
      47 bb 52 ba a7 4e b0 a0 13 e5 f6 7e 04 f5 68 d5
      5c d1 d0 b3 ae ad 20 da 32 7a 17 0a 04 64 0c af

        (  0) [ AVAILABLE] KM-Query
        (  1) [ AVAILABLE] KM-DEA
        (  2) [ AVAILABLE] KM-TDEA-128
        (  3) [ AVAILABLE] KM-TDEA-192
        (  9) [ AVAILABLE] KM-Encrypted-DEA
        ( 10) [ AVAILABLE] KM-Encrypted-TDEA-128
        ( 11) [ AVAILABLE] KM-Encrypted-TDEA-192
        ( 18) [ AVAILABLE] KM-AES-128
        ( 19) [ AVAILABLE] KM-AES-192
        ( 20) [ AVAILABLE] KM-AES-256
        ( 26) [ AVAILABLE] KM-Encrypted-AES-128
        ( 27) [ AVAILABLE] KM-Encrypted-AES-192
        ( 28) [ AVAILABLE] KM-Encrypted-AES-256
        ( 50) [ AVAILABLE] KM-XTS-AES-128
        ( 52) [ AVAILABLE] KM-XTS-AES-256
        ( 58) [ AVAILABLE] KM-XTS-Encrypted-AES-128
        ( 60) [ AVAILABLE] KM-XTS-Encrypted-AES-256
        ( 82) [ AVAILABLE] KM-FULL-XTS-AES-128
        ( 84) [ AVAILABLE] KM-FULL-XTS-AES-256
        ( 90) [ AVAILABLE] KM-FULL-XTS-Encrypted-AES-128
        ( 92) [ AVAILABLE] KM-FULL-XTS-Encrypted-AES-256
        (127) [ AVAILABLE] KM-Query-Authentication-Information

Cipher Message with Chaining (KMC)
...

To show only the available functions per instruction, issue:
```
# cpacfinfo -f -a
```
Short options can be chained using one hyphen:
```
# cpacfinfo -fa
```
If you want to chain the -i option, it must be specified last:
```
# cpacfinfo -fani km
```
To show only the unavailable functions per instruction, issue:
```
# cpacfinfo -f -n
```
To display multiple instructions, for example, km, kmf, and kmac, issue:
```
# cpacfinfo -i km,kmf,kmac
```

To show which MSA levels are available, issue:

# cpacfinfo -m
MSA    STFLE bit [  17 ] : AVAILABLE ( 16 / 16 functions available )
MSA  1                   : AVAILABLE (  5 / 5  functions available )
MSA  2                   : AVAILABLE (  6 / 6  functions available )
MSA  3 STFLE bit [  76 ] : AVAILABLE ( 22 / 22 functions available )
MSA  4 STFLE bit [  77 ] : AVAILABLE ( 67 / 67 functions available )
MSA  5 STFLE bit [  57 ] : AVAILABLE (  2 / 2  functions available )
MSA  6                   : AVAILABLE ( 12 / 12 functions available )
MSA  7                   : AVAILABLE (  2 / 2  functions available )
MSA  8 STFLE bit [ 146 ] : AVAILABLE (  7 / 7  functions available )
MSA  9 STFLE bit [ 155 ] : AVAILABLE ( 28 / 28 functions available )
MSA 10                   : AVAILABLE (  6 / 6  functions available )
MSA 11                   : AVAILABLE ( 10 / 10 functions available )
MSA 12 STFLE bit [  86 ] : AVAILABLE (  0 / 0  functions available )
MSA 13                   : AVAILABLE ( 13 / 13 functions available )

The information in parenthesis shows how many functions are available on that level.

To suppress the MSA 13 firmware authentication information, issue:

# cpacfinfo -q
Cipher Message (KM)
Cipher Message with Chaining (KMC)
Compute Intermediate Message Digest (KIMD)
Compute Last Message Digest (KLMD)
Compute Message Authentication Code (KMAC)
Perform Cryptographic Key Management Operation (PCKMO)
Cipher Message with Cipher Feedback (KMF)
Cipher Message with Counter (KMCTR)
Cipher Message with Output Feedback (KMO)
Perform Cryptographic Computation (PCC)
Perform Random Number Operation (PRNO)
Cipher Message with Authentication (KMA)
Compute Digital Signature Authentication (KDSA)

Hardware earlier than IBM z17 show this output by default.