diff --git a/zconf/zcrypt/lszcrypt.8 b/zconf/zcrypt/lszcrypt.8 index e1de2e9d..536a3e33 100644 --- a/zconf/zcrypt/lszcrypt.8 +++ b/zconf/zcrypt/lszcrypt.8 @@ -1,6 +1,6 @@ .\" lszcrypt.8 .\" -.\" Copyright IBM Corp. 2019, 2022 +.\" Copyright IBM Corp. 2019, 2023 .\" s390-tools is free software; you can redistribute it and/or modify .\" it under the terms of the MIT license. See LICENSE for details. .\" @@ -10,7 +10,7 @@ .\" nroff -man lszcrypt.8 .\" to process this source .\" -.TH LSZCRYPT 8 "FEB 2022" "s390-tools" +.TH LSZCRYPT 8 "MAY 2023" "s390-tools" .SH NAME lszcrypt \- display zcrypt device and configuration information .SH SYNOPSIS @@ -24,7 +24,7 @@ lszcrypt \- display zcrypt device and configuration information .TP .B lszcrypt .B -c - + .TP .B lszcrypt -b .TP @@ -41,43 +41,60 @@ lszcrypt \- display zcrypt device and configuration information .SH DESCRIPTION The .B lszcrypt -command is used to display information about cryptographic devices managed by -zcrypt and the AP bus attributes of zcrypt. Displayed information depends on the -kernel version. +command is used to display information about cryptographic devices +managed by zcrypt and the AP bus attributes of zcrypt. Displayed +information depends on the kernel version. .B lszcrypt requires that sysfs is mounted. .P The following information can be displayed for each cryptographic device: card ID, domain ID, card type (symbolic), mode, online status, -hardware card type (numeric), installed function facilities, card capability, -hardware queue depth, request count, number of requests in hardware queue, and -the number of outstanding requests. -The following AP bus attributes can be displayed: AP domain, Max AP domain, -configuration timer, poll thread status, poll timeout, and AP interrupt -status. +hardware card type (numeric), installed function facilities, card +capability, hardware queue depth, request count, number of requests in +hardware queue, and the number of outstanding requests. The following +AP bus attributes can be displayed: AP domain, Max AP domain, +configuration timer, poll thread status, poll timeout, and AP +interrupt status. .SH OPTIONS .TP 8 .B -V, --verbose -The verbose level for cryptographic device information. -With this verbose level additional information like hardware card type, -hardware queue depth, pending requests count, installed function -facilities and driver binding is displayed. +The verbose level for cryptographic device information. With this +verbose level additional information like hardware card type, hardware +queue depth, pending requests count, installed function facilities and +driver binding is displayed. .TP 8 .B -Specifies a cryptographic device to display. A cryptographic device can be -either a card device or a queue device. If no devices are specified information -about all available devices is displayed. +Specifies a cryptographic device to display. A cryptographic device +can be either a card device or a queue device. If no devices are +specified information about all available devices is displayed. Please note that the card device representation and the queue device are both in hexadecimal notation. .TP 8 .B -b, --bus Displays the AP bus attributes and exits. + +There is also a list of AP bus features shown here: +.RS +.IP "o" 3 +APSC - Extended TAPQ (Test AP Queue) support. +.IP "o" +APXA - Support for more than 16 domains per card. +.IP "o" +QACT - QACT support for toleration of new unknown crypto cards. +.IP "o" +RC8A - Firmware reports 0x8A instead of 0x42 on some error conditions. +.IP "o" +APSB - AP bus has Secure Execution AP pass-through support. +.RE .TP 8 -.B -c, --capability -Shows the capabilities of a cryptographic card device of hardware type 6 or -higher. The card device id value may be given as decimal or hex value (with -a leading 0x). The capabilities of a cryptographic card device depend on -the card type and the installed function facilities. A cryptographic card +.B -c, --capability +Shows the capabilities of a cryptographic card or queue device of +hardware type 6 or higher. A card device id value may be given as +decimal or hex value (with a leading 0x), a queue device needs to be +given as xy.abcd (as it is displayed by lszcrypt). + +The capabilities of a cryptographic card device depend on the card +type and the installed function facilities. A cryptographic card device can provide one or more of the following capabilities: .RS .IP "o" 3 @@ -94,14 +111,25 @@ Long RNG .RS 8 The CCA Secure Key capability may be limited by a hypervisor -layer. The remarks 'full function set' or 'restricted function set' may -reflect this. For details about these limitations please check the +layer. The remarks 'full function set' or 'restricted function set' +may reflect this. For details about these limitations please check the hypervisor documentation. .RE + +.RS 8 +The capabilities of a cryptographic queue device may vary depending +on some state or environment. However if a queue device is given here, +and the runtime environment is a KVM guest in Secure Execution mode +with AP pass-through support, then the AP queue bind state and AP +queue association state is shown here. Furthermore the state(s) and +mkvp(s) (Master Key Verification Pattern) of the current master WK +(Wrapping Key - EP11 mode) or current master AES, APKA and ASYM (CCA +mode) are shown here. +.RE .TP 8 .B -d, --domains -Shows the usage and control domains of the cryptographic devices. -The displayed domains of the cryptographic device depends on the initial +Shows the usage and control domains of the cryptographic devices. The +displayed domains of the cryptographic device depends on the initial cryptographic configuration. .RS .IP "o" 3 @@ -140,18 +168,20 @@ Here is an explanation of the columns displayed. Please note that some of the columns show up in verbose mode only. .TP .B CARD.DOM -The crypto card number in hexadecimal for a crypto card line or -the crypto card number and the domain id both in hex separated by a single +The crypto card number in hexadecimal for a crypto card line or the +crypto card number and the domain id both in hex separated by a single dot for a queue line. .TP .B TYPE and HWTYPE -The HWTYPE is a numeric value showing which type of hardware the zcrypt -device driver presumes that this crypto card is. The currently known values -are 7=CEX3C, 8=CEX3A, 10=CEX4, 11=CEX5, 12=CEX6, 13=CEX7 and 14=CEX8. +The HWTYPE is a numeric value showing which type of hardware the +zcrypt device driver presumes that this crypto card is. The currently +known values are 7=CEX3C, 8=CEX3A, 10=CEX4, 11=CEX5, 12=CEX6, 13=CEX7 +and 14=CEX8. .br -The TYPE is a human readable value showing the hardware type and the basic -function type (A=Accelerator, C=CCA Coprocessor, P=EP11 Coprocessor). So -for example CEX6P means a CEX6 card in EP11 Coprocessor mode. +The TYPE is a human readable value showing the hardware type and the +basic function type (A=Accelerator, C=CCA Coprocessor, P=EP11 +Coprocessor). So for example CEX6P means a CEX6 card in EP11 +Coprocessor mode. .TP .B MODE A crypto card can be configured to run into one of 3 modes: @@ -170,13 +200,13 @@ online/offline state is kept by the zcrypt device driver and can be switched on or off with the help of the chzcrypt application. .br A crypto card can also be 'configured' or 'deconfigured'. This state -may be adjusted on the HMC or SE. The chzcrypt application can also -trigger this state with the --config-on and --config-off options. +may be adjusted on the HMC. The chzcrypt application can also trigger +this state with the --config-on and --config-off options. .br lszcrypt shows 'online' when a card or queue is available for cryptographic operations. 'offline' is displayed when a card or queue is switched to (software) offline. If a card is 'deconfigured' via -HMC, SE or chzcrypt the field shows 'deconfig'. +HMC or chzcrypt the field shows 'deconfig'. .br A crypto card may also reach a 'checkstopped' state. lszcrypt shows this as 'chkstop'. @@ -184,21 +214,22 @@ this as 'chkstop'. If a queue is not bound to a device driver there is no detailed information available and thus the status shows only '-'. .br -If a queue is bound to the vfio-ap device driver it is up to this driver -to give some status information and what exactly this means. So lszcrypt -shows the text retrieved from the underlying sysfs attribute here. +If a queue is bound to the vfio-ap device driver it is up to this +driver to give some status information and what exactly this means. So +lszcrypt shows the text retrieved from the underlying sysfs attribute +here. .TP .B REQUESTS -This is the counter value of successful processed requests on card or queue -level. Successful here means the request was processed without any failure -in the whole processing chain. +This is the counter value of successful processed requests on card or +queue level. Successful here means the request was processed without +any failure in the whole processing chain. .TP .B PENDING -The underlying firmware and hardware layer usually provide some queuing -space for requests. When this queue is already filled up, the zcrypt device -driver maintains a software queue of pending requests. The sum of these -both values is displayed here and shows the amount of requests waiting for -processing on card or queue level. +The underlying firmware and hardware layer usually provide some +queuing space for requests. When this queue is already filled up, the +zcrypt device driver maintains a software queue of pending +requests. The sum of these both values is displayed here and shows the +amount of requests waiting for processing on card or queue level. .TP .B FUNCTIONS This column shows firmware and hardware function details: @@ -224,48 +255,64 @@ F - Full function support (opposed to restricted function support, see below). .br R - Restricted function support. The F and R flag both reflect if a hypervisor is somehow restricting this crypto resource in a virtual -environment. Dependent on the hypervisor configuration the crypto requests -may be filtered by the hypervisor to allow only a subset of functions -within the virtual runtime environment. For example a shared CCA -Coprocessor may be restricted by the hypervisor to allow only clear key -operations within the guests. +environment. Dependent on the hypervisor configuration the crypto +requests may be filtered by the hypervisor to allow only a subset of +functions within the virtual runtime environment. For example a shared +CCA Coprocessor may be restricted by the hypervisor to allow only +clear key operations within the guests. .TP .B DRIVER .br Shows which card or queue device driver currently handles this crypto resource. Currently known drivers are cex4card/cex4queue (CEX4-CEX8 hardware), cex2card/cex2cqueue (CEX2C and CEX3C hardware), -cex2acard/cex2aqueue (CEX2A and CEX3A hardware) and vfio_ap (queue reserved -for use by kvm hypervisor for kvm guests and not accessible to host -applications). It is also valid to have no driver handling a queue which is -shown as a -no-driver- entry. +cex2acard/cex2aqueue (CEX2A and CEX3A hardware) and vfio_ap (queue +reserved for use by KVM hypervisor for KVM guests and not accessible +to host applications). It is also valid to have no driver handling a +queue which is shown as a -no-driver- entry. +.TP +.B SESTAT +.br +Shows the state of the BS bits associated with every AP queue within a +Secure Execution guest when AP Pass-through support is available: +.br +usable - AP queue is usable for crypto load. +.br +bound - AP queue is bound but not yet associated. +.br +unbound - AP queue is unbound and needs to get bound to this Secure +Execution guest. +.br +illicit - AP queue is not available for this Secure Execution guest. .SH NOTES -Use only one of the mode filtering options --accelonly, --ccaonly, --ep11only. -Same with card/queue filtering: Use only one of --cardonly, --queueonly. -However, one of the mode filtering options and one of the card/queue filtering -can be combined. +Use only one of the mode filtering options --accelonly, --ccaonly, +--ep11only. Same with card/queue filtering: Use only one of +--cardonly, --queueonly. However, one of the mode filtering options +and one of the card/queue filtering can be combined. .SH EXAMPLES .TP .B lszcrypt -Displays the card/domain ID, card type (short name), mode (long name), online -status and request count of all available cryptographic devices. +Displays the card/domain ID, card type (short name), mode (long name), +online status and request count of all available cryptographic +devices. .TP .B lszcrypt 1 3 5 -Displays the card/domain ID, card type, mode, online status and request count -for cryptographic devices 1, 3, and 5. +Displays the card/domain ID, card type, mode, online status and +request count for cryptographic devices 1, 3, and 5. .TP .B lszcrypt -V 3 7 11 -Displays the card/domain ID, card type, mode, online status, request count, -number of requests in the hardware queue, number of outstanding requests and -installed function facilities for cryptographic devices 3, 7 and 17 (0x11). +Displays the card/domain ID, card type, mode, online status, request +count, number of requests in the hardware queue, number of outstanding +requests and installed function facilities for cryptographic devices +3, 7 and 17 (0x11). .TP .B lszcrypt 10.0038 -Displays information of the cryptographic device '10.0038' respectively card -id 16 (0x10) with domain 56 (0x38). +Displays information of the cryptographic device '10.0038' +respectively card id 16 (0x10) with domain 56 (0x38). .TP .B lszcrypt .0038 -Displays information of all available queue devices (potentially multiple -adapters) with domain 56 (0x38). +Displays information of all available queue devices (potentially +multiple adapters) with domain 56 (0x38). .TP .B lszcrypt -b Displays AP bus information. diff --git a/zconf/zcrypt/lszcrypt.c b/zconf/zcrypt/lszcrypt.c index 43a3c39b..09de77e0 100644 --- a/zconf/zcrypt/lszcrypt.c +++ b/zconf/zcrypt/lszcrypt.c @@ -1,7 +1,7 @@ /** * lszcrypt - Display zcrypt devices and configuration settings * - * Copyright IBM Corp. 2008, 2022 + * Copyright IBM Corp. 2008, 2023 * * s390-tools is free software; you can redistribute it and/or modify * it under the terms of the MIT license. See LICENSE for details. @@ -55,7 +55,7 @@ static struct lszcrypt_l { #define MASK_COPRO 0x10000000 #define MASK_ACCEL 0x08000000 #define MASK_EP11 0x04000000 -#define MASK_HSL 0x01000000 +#define MASK_HSL 0x01000000 /* * Classification @@ -85,6 +85,8 @@ static struct fac_bits_s { { 0x00400000, 'R' }, /* bit 9, restricted function set */ }; +#define EXTRACT_BS_BITS(f) (((f) & 0x0000c000UL) >> 14) + /* * Program configuration */ @@ -95,7 +97,7 @@ static const struct util_prg prg = { { .owner = "IBM Corp.", .pub_first = 2008, - .pub_last = 2020, + .pub_last = 2023, }, UTIL_PRG_COPYRIGHT_END } @@ -169,8 +171,9 @@ static struct util_opt opt_vec[] = { static void show_bus(void) { long domain, max_domain, config_time, value; - unsigned long long poll_timeout; const char *poll_thread, *ap_interrupts; + unsigned long long poll_timeout; + char features[256]; char *ap; /* check if ap driver is available */ @@ -178,6 +181,10 @@ static void show_bus(void) if (!util_path_is_dir(ap)) errx(EXIT_FAILURE, "Crypto device driver not available."); + if (util_path_is_readable("%s/features", ap)) + util_file_read_line(features, sizeof(features), "%s/features", ap); + else + features[0] = '\0'; util_file_read_l(&domain, 10, "%s/ap_domain", ap); util_file_read_l(&max_domain, 10, "%s/ap_max_domain_id", ap); util_file_read_l(&config_time, 10, "%s/config_time", ap); @@ -192,6 +199,8 @@ static void show_bus(void) ap_interrupts = "enabled"; else ap_interrupts = "disabled"; + if (features[0]) + printf("features: %s\n", features); printf("ap_domain=0x%lx\n", domain); printf("ap_max_domain_id=0x%lx\n", max_domain); if (util_path_is_reg_file("%s/ap_interrupts", ap)) @@ -374,23 +383,15 @@ next: } /* - * Show capability + * Show card capability */ -static void show_capability(const char *id_str) +static void show_card_capability(int id) { unsigned long func_val; - long hwtype, id, max_msg_size; - char *p, *ap, *dev, card[16], cbuf[256]; + long hwtype, max_msg_size; + char *dev, card[16], cbuf[256]; - /* check if ap driver is available */ - ap = util_path_sysfs("bus/ap"); - if (!util_path_is_dir(ap)) - errx(EXIT_FAILURE, "Crypto device driver not available."); - - id = strtol(id_str, &p, 0); - if (id < 0 || id > 255 || p == id_str || *p != '\0') - errx(EXIT_FAILURE, "Error - '%s' is an invalid cryptographic device id.", id_str); - snprintf(card, sizeof(card), "card%02lx", id); + snprintf(card, sizeof(card), "card%02x", id); dev = util_path_sysfs("devices/ap/%s", card); if (!util_path_is_dir(dev)) errx(EXIT_FAILURE, "Error - cryptographic device %s does not exist.", card); @@ -464,6 +465,78 @@ static void show_capability(const char *id_str) card, hwtype); break; } + + free(dev); +} + +/* + * Show queue capability + */ +static void show_queue_capability(int id, int dom) +{ + char *dev, card[16], queue[16], buf[256]; + + snprintf(card, sizeof(card), "card%02x", id); + snprintf(queue, sizeof(queue), "%02x.%04x", id, dom); + dev = util_path_sysfs("devices/ap/%s/%s", card, queue); + if (!util_path_is_dir(dev)) + errx(EXIT_FAILURE, "Error - cryptographic queue device %02x.%04x does not exist.", + id, dom); + + printf("queue %02x.%04x capabilities:\n", id, dom); + + if (util_path_is_reg_file("%s/se_bind", dev)) { + util_file_read_line(buf, sizeof(buf), "%s/se_bind", dev); + printf("SE bind state: %s\n", buf); + } + if (util_path_is_reg_file("%s/se_associate", dev)) { + util_file_read_line(buf, sizeof(buf), "%s/se_associate", dev); + printf("SE association state: %s\n", buf); + } + if (util_path_is_reg_file("%s/mkvps", dev)) { + char *mkvps = util_path_sysfs("devices/ap/%s/%s/mkvps", card, queue); + FILE *f = fopen(mkvps, "r"); + + if (!f) + errx(EXIT_FAILURE, "Error - failed to open sysfs file %s.", + mkvps); + while (fgets(buf, sizeof(buf), f)) { + if (strstr(buf, "WK CUR") || + strstr(buf, "AES CUR") || + strstr(buf, "APKA CUR") || + strstr(buf, "ASYM CUR")) + printf("MK %s", buf); /* no newline here */ + } + fclose(f); + free(mkvps); + } + + free(dev); +} + +/* + * Show capability + */ +static void show_capability(const char *id_str) +{ + char *p, *ap; + int id, dom; + + /* check if ap driver is available */ + ap = util_path_sysfs("bus/ap"); + if (!util_path_is_dir(ap)) + errx(EXIT_FAILURE, "Crypto device driver not available."); + + if (sscanf(id_str, "%x.%x", &id, &dom) == 2) { + show_queue_capability(id, dom); + } else { + id = strtol(id_str, &p, 0); + if (id < 0 || id > 255 || p == id_str || *p != '\0') + errx(EXIT_FAILURE, + "Error - '%s' is an invalid cryptographic device id.", + id_str); + show_card_capability(id); + } } /* @@ -601,11 +674,33 @@ static void read_subdev_rec_verbose(struct util_rec *rec, const char *grp_dev, util_file_read_l(&depth, 10, "%s/depth", grp_dev); util_rec_set(rec, "depth", "%02d", depth + 1); - util_file_read_ul(&facility, 16, "%s/ap_functions", grp_dev); + if (util_path_is_readable("%s/%s/ap_functions", grp_dev, sub_dev)) + util_file_read_ul(&facility, 16, "%s/%s/ap_functions", grp_dev, sub_dev); + else + util_file_read_ul(&facility, 16, "%s/ap_functions", grp_dev); for (i = 0; i < MAX_FAC_BITS; i++) buf[i] = facility & fac_bits[i].mask ? fac_bits[i].c : '-'; buf[i] = '\0'; util_rec_set(rec, "facility", buf); + + if (ap_bus_has_SB_support()) { + switch (EXTRACT_BS_BITS(facility)) { + case 0: + util_rec_set(rec, "sestat", "usable"); + break; + case 1: + util_rec_set(rec, "sestat", "bound"); + break; + case 2: + util_rec_set(rec, "sestat", "unbound"); + break; + case 3: + util_rec_set(rec, "sestat", "illicit"); + break; + default: + util_rec_set(rec, "sestat", "-"); + } + } } /* @@ -750,6 +845,9 @@ static void read_rec_verbose(struct util_rec *rec, const char *grp_dev) i = read_driver(grp_dev, NULL, buf, sizeof(buf)); util_rec_set(rec, "driver", i > 0 ? buf : "-no-driver-"); + + if (ap_bus_has_SB_support()) + util_rec_set(rec, "sestat", "-"); } /* @@ -818,6 +916,8 @@ static void define_rec_verbose(struct util_rec *rec) util_rec_def(rec, "depth", UTIL_REC_ALIGN_RIGHT, 6, "QDEPTH"); util_rec_def(rec, "facility", UTIL_REC_ALIGN_LEFT, 10, "FUNCTIONS"); util_rec_def(rec, "driver", UTIL_REC_ALIGN_LEFT, 11, "DRIVER"); + if (ap_bus_has_SB_support()) + util_rec_def(rec, "sestat", UTIL_REC_ALIGN_LEFT, 11, "SESTAT"); } /* diff --git a/zconf/zcrypt/misc.c b/zconf/zcrypt/misc.c index 4296cb1c..05913d61 100644 --- a/zconf/zcrypt/misc.c +++ b/zconf/zcrypt/misc.c @@ -1,16 +1,20 @@ /* * Misc - Local helper functions * - * Copyright IBM Corp. 2016, 2017 + * Copyright IBM Corp. 2016, 2023 * * s390-tools is free software; you can redistribute it and/or modify * it under the terms of the MIT license. See LICENSE for details. */ #include +#include #include +#include "lib/util_base.h" +#include "lib/util_file.h" #include "lib/util_panic.h" +#include "lib/util_path.h" #include "misc.h" /** @@ -35,3 +39,35 @@ bool misc_regex_match(const char *str, const char *regex) regfree(&preg); return rc == 0 ? true : false; } + +/** + * Test if AP bus has SB support available. + * + * @returns true Yes, SB support is available + * false No + */ +bool ap_bus_has_SB_support(void) +{ + static int sb_support = -1; + + if (sb_support < 0) { + char *ap, buf[256]; + + ap = util_path_sysfs("bus/ap"); + if (!util_path_is_dir(ap)) { + sb_support = 0; + } else { + if (!util_path_is_readable("%s/features", ap)) { + sb_support = 0; + } else { + util_file_read_line(buf, sizeof(buf), + "%s/features", ap); + if (strstr(buf, "APSB")) + sb_support = 1; + } + } + free(ap); + } + + return sb_support > 0 ? true : false; +} diff --git a/zconf/zcrypt/misc.h b/zconf/zcrypt/misc.h index 502a687e..92cf453a 100644 --- a/zconf/zcrypt/misc.h +++ b/zconf/zcrypt/misc.h @@ -1,7 +1,7 @@ /* * misc - Local helper functions * - * Copyright IBM Corp. 2016, 2017 + * Copyright IBM Corp. 2016, 2023 * * s390-tools is free software; you can redistribute it and/or modify * it under the terms of the MIT license. See LICENSE for details. @@ -13,5 +13,6 @@ #include bool misc_regex_match(const char *str, const char *regex); +bool ap_bus_has_SB_support(void); #endif /* MISC_H */