s390

s390 — plugin for operations with s390

Functions

gboolean bd_s390_init ()
void bd_s390_close ()
GQuark bd_s390_error_quark ()
gboolean bd_s390_dasd_format ()
gboolean bd_s390_dasd_needs_format ()
gchar * bd_s390_sanitize_dev_input ()
gboolean bd_s390_dasd_online ()
gboolean bd_s390_dasd_is_ldl ()
gboolean bd_s390_dasd_is_fba ()
gchar * bd_s390_zfcp_sanitize_wwpn_input ()
gchar * bd_s390_zfcp_sanitize_lun_input ()
gboolean bd_s390_zfcp_online ()
gboolean bd_s390_zfcp_scsi_offline ()
gboolean bd_s390_zfcp_offline ()
gboolean bd_s390_zkey_generate ()
BDS390ZkeyInfo * bd_s390_zkey_info_copy ()
void bd_s390_zkey_info_free ()
BDS390ZkeyInfo ** bd_s390_zkey_list ()
gboolean bd_s390_zkey_remove ()
gboolean bd_s390_zkey_cryptsetup_setvp ()
gboolean bd_s390_zkey_cryptsetup_validate ()
gboolean bd_s390_is_tech_avail ()

Types and Values

enum BDS390Error
#define BD_S390_ERROR
  BDS390ZkeyInfo
enum BDS390Tech
enum BDS390TechMode

Includes

#include <s390.h>

Description

A plugin for operations with s390 devices.

Functions

bd_s390_init ()

gboolean
bd_s390_init (void);

Initializes the plugin. **This function is called automatically by the library's initialization functions.**

bd_s390_close ()

void
bd_s390_close (void);

Cleans up after the plugin. **This function is called automatically by the library's functions that unload it.**

bd_s390_error_quark ()

GQuark
bd_s390_error_quark (void);

[skip]

bd_s390_dasd_format ()

gboolean
bd_s390_dasd_format (const gchar *dasd,
                     const BDExtraArg **extra,
                     GError **error);

Parameters

dasd

dasd to format

  

extra

extra options for the formatting (right now passed to the 'dasdfmt' utility).

[nullable][array zero-terminated=1]

error

place to store error (if any).

[out][optional]

Returns

whether dasdfmt was successful or not

Tech category: BD_S390_TECH_DASD-BD_S390_TECH_MODE_MODIFY

bd_s390_dasd_needs_format ()

gboolean
bd_s390_dasd_needs_format (const gchar *dasd,
                           GError **error);

Parameters

dasd

dasd to check, given as device number

  

error

place to store error (if any).

[out][optional]

Returns

whether a dasd needs dasdfmt run against it

Tech category: BD_S390_TECH_DASD-BD_S390_TECH_MODE_QUERY

bd_s390_sanitize_dev_input ()

gchar *
bd_s390_sanitize_dev_input (const gchar *dev,
                            GError **error);

Parameters

dev

a DASD or zFCP device number

  

error

place to store error (if any).

[out][optional]

Returns

a synthesized dasd or zfcp device number

Tech category: always available.

[transfer full]

bd_s390_dasd_online ()

gboolean
bd_s390_dasd_online (const gchar *dasd,
                     GError **error);

Parameters

dasd

dasd to switch online, given as device number

  

error

place to store error (if any).

[out][optional]

Returns

whether a dasd was successfully switched online

Tech category: BD_S390_TECH_DASD-BD_S390_TECH_MODE_MODIFY

bd_s390_dasd_is_ldl ()

gboolean
bd_s390_dasd_is_ldl (const gchar *dasd,
                     GError **error);

Parameters

dasd

dasd to check, whether it is LDL formatted

  

error

place to store error (if any).

[out][optional]

Returns

whether a dasd is LDL formatted

Tech category: BD_S390_TECH_DASD-BD_S390_TECH_MODE_QUERY

bd_s390_dasd_is_fba ()

gboolean
bd_s390_dasd_is_fba (const gchar *dasd,
                     GError **error);

Parameters

dasd

dasd to check, whether it is FBA

  

error

place to store error (if any).

[out][optional]

Returns

whether a dasd is FBA

Tech category: BD_S390_TECH_DASD-BD_S390_TECH_MODE_QUERY

bd_s390_zfcp_sanitize_wwpn_input ()

gchar *
bd_s390_zfcp_sanitize_wwpn_input (const gchar *wwpn,
                                  GError **error);

Parameters

wwpn

a zFCP WWPN identifier

  

error

place to store error (if any).

[out][optional]

Returns

a synthesized zFCP WWPN

Tech category: always available.

[transfer full]

bd_s390_zfcp_sanitize_lun_input ()

gchar *
bd_s390_zfcp_sanitize_lun_input (const gchar *lun,
                                 GError **error);

Parameters

lun

a zFCP LUN identifier

  

error

place to store error (if any).

[out][optional]

Returns

a synthesized zFCP LUN

Tech category: always available.

[transfer full]

bd_s390_zfcp_online ()

gboolean
bd_s390_zfcp_online (const gchar *devno,
                     const gchar *wwpn,
                     const gchar *lun,
                     GError **error);

Parameters

devno

zfcp device number

  

wwpn

zfcp WWPN (World Wide Port Number)

  

lun

zfcp LUN (Logical Unit Number)

  

error

place to store error (if any).

[out][optional]

Returns

whether a zFCP device was successfully switched online

Tech category: BD_S390_TECH_ZFCP-BD_S390_TECH_MODE_MODIFY

bd_s390_zfcp_scsi_offline ()

gboolean
bd_s390_zfcp_scsi_offline (const gchar *devno,
                           const gchar *wwpn,
                           const gchar *lun,
                           GError **error);

Parameters

devno

zfcp device number

  

wwpn

zfcp WWPN (World Wide Port Number)

  

lun

zfcp LUN (Logical Unit Number)

  

error

place to store error (if any).

[out][optional]

Returns

whether a LUN was successfully removed from its associated WWPN

This function looks through /proc/scsi/scsi and manually removes LUNs from associated WWPNs. zFCP devices are SCSI devices accessible over FCP protocol. In z/OS the IODF (I/O definition file) contains basic information about the I/O config, but WWPN and LUN configuration is done at the OS level, hence this function becomes necessary when switching the device offline. This particular sequence of actions is for some reason unnecessary when switching the device online. Chalk it up to s390x being s390x.

Tech category: BD_S390_TECH_ZFCP-BD_S390_TECH_MODE_MODIFY

bd_s390_zfcp_offline ()

gboolean
bd_s390_zfcp_offline (const gchar *devno,
                      const gchar *wwpn,
                      const gchar *lun,
                      GError **error);

Parameters

devno

zfcp device number

  

wwpn

zfcp WWPN (World Wide Port Number)

  

lun

zfcp LUN (Logical Unit Number)

  

error

place to store error (if any).

[out][optional]

Returns

whether a zfcp device was successfully switched offline

Tech category: BD_S390_TECH_ZFCP-BD_S390_TECH_MODE_MODIFY

bd_s390_zkey_generate ()

gboolean
bd_s390_zkey_generate (const gchar *name,
                       const gchar *key_type,
                       guint64 keybits,
                       const gchar **volumes,
                       const gchar **apqns,
                       guint64 sector_size,
                       gboolean dummy_passphrase,
                       const BDExtraArg **extra,
                       GError **error);

Generates a new secure key for pervasive encryption using the 'zkey' utility and stores it in the secure key repository. The key is generated as an XTS key with the 'LUKS2' volume type.

Parameters

name

name of the secure key to generate in the secure key repository

  

key_type

type of the secure key to generate (e.g. "CCA-AESCIPHER") or NULL for the zkey default.

[nullable]

keybits

size of the key in bits or 0 for the zkey default

  

volumes

list of volumes to associate with the key, each given in the "volume:dmname" format, or NULL.

[nullable][array zero-terminated=1]

apqns

list of cryptographic adapters (APQNs) to associate with the key, each given in the "card.domain" format, or NULL.

[nullable][array zero-terminated=1]

sector_size

sector size in bytes to use with dm-crypt or 0 for the system default

  

dummy_passphrase

whether to generate and associate a dummy passphrase with the key

  

extra

extra options for the key generation (right now passed to the 'zkey' utility).

[nullable][array zero-terminated=1]

error

place to store error (if any).

[out][optional]

Returns

whether the secure key was successfully generated or not

Tech category: BD_S390_TECH_PAES-BD_S390_TECH_MODE_CREATE

bd_s390_zkey_info_copy ()

BDS390ZkeyInfo *
bd_s390_zkey_info_copy (BDS390ZkeyInfo *info);

Creates a new copy of info .

[skip]

Parameters

info

BDS390ZkeyInfo to copy.

[nullable]

bd_s390_zkey_info_free ()

void
bd_s390_zkey_info_free (BDS390ZkeyInfo *info);

Frees info .

[skip]

Parameters

info

BDS390ZkeyInfo to free.

[nullable]

bd_s390_zkey_list ()

BDS390ZkeyInfo **
bd_s390_zkey_list (const gchar *name,
                   GError **error);

Lists the secure keys stored in the secure key repository using the 'zkey' utility. If name is given, only the information about the matching key is returned.

Parameters

name

name of a single secure key to get information about or NULL to list all keys.

[nullable]

error

place to store error (if any).

[out][optional]

Returns

information about the secure keys in the repository (an empty list if there are none) or NULL in case of error

Tech category: BD_S390_TECH_PAES-BD_S390_TECH_MODE_QUERY.

[array zero-terminated=1][transfer full]

bd_s390_zkey_remove ()

gboolean
bd_s390_zkey_remove (const gchar *name,
                     GError **error);

Removes the secure key name from the secure key repository using the 'zkey' utility.

Parameters

name

name of the secure key to remove from the secure key repository

  

error

place to store error (if any).

[out][optional]

Returns

whether the secure key was successfully removed or not

Tech category: BD_S390_TECH_PAES-BD_S390_TECH_MODE_MODIFY

bd_s390_zkey_cryptsetup_setvp ()

gboolean
bd_s390_zkey_cryptsetup_setvp (const gchar *device,
                               const gchar *key_file,
                               const BDExtraArg **extra,
                               GError **error);

Sets the verification pattern of the secure key in the metadata of the LUKS2 volume device using the 'zkey-cryptsetup' utility. The verification pattern is used to identify the secure key associated with the volume. Setting the verification pattern requires unlocking a keyslot of device , so the LUKS passphrase needs to be provided in key_file (this is a passphrase file, not the secure key file).

Parameters

device

LUKS2 device to set the verification pattern on

  

key_file

path to a file containing the LUKS passphrase used to unlock a keyslot of device

 

extra

extra options for setting the verification pattern (right now passed to the 'zkey-cryptsetup' utility).

[nullable][array zero-terminated=1]

error

place to store error (if any).

[out][optional]

Returns

whether the verification pattern was successfully set or not

Tech category: BD_S390_TECH_PAES-BD_S390_TECH_MODE_MODIFY

bd_s390_zkey_cryptsetup_validate ()

gboolean
bd_s390_zkey_cryptsetup_validate (const gchar *device,
                                  const gchar *key_file,
                                  const BDExtraArg **extra,
                                  GError **error);

Validates that the LUKS2 volume device is correctly set up for pervasive encryption using the 'zkey-cryptsetup' utility. Validation requires unlocking a keyslot of device , so the LUKS passphrase needs to be provided in key_file (this is a passphrase file, not the secure key file).

Parameters

device

LUKS2 device to validate

  

key_file

path to a file containing the LUKS passphrase used to unlock a keyslot of device

 

extra

extra options for the validation (right now passed to the 'zkey-cryptsetup' utility).

[nullable][array zero-terminated=1]

error

place to store error (if any).

[out][optional]

Returns

whether the LUKS2 volume device is correctly set up for pervasive encryption or not

Tech category: BD_S390_TECH_PAES-BD_S390_TECH_MODE_QUERY

bd_s390_is_tech_avail ()

gboolean
bd_s390_is_tech_avail (BDS390Tech tech,
                       guint64 mode,
                       GError **error);

Parameters

tech

the queried tech

  

mode

a bit mask of queried modes of operation (BDS390TechMode) for tech

 

error

place to store error (details about why the tech -mode combination is not available).

[out][optional]

Returns

whether the tech -mode combination is available -- supported by the plugin implementation and having all the runtime dependencies available

Types and Values

enum BDS390Error

Members

BD_S390_ERROR_TECH_UNAVAIL

    

BD_S390_ERROR_DEVICE

    

BD_S390_ERROR_FORMAT_FAILED

    

BD_S390_ERROR_DASDFMT

    

BD_S390_ERROR_IO

    

BD_S390_ERROR_ZKEY

    

BD_S390_ERROR

#define             BD_S390_ERROR

BDS390ZkeyInfo

typedef struct {
    gchar *name;
    gchar *description;
    guint64 secure_key_size;
    guint64 clear_key_size;
    gboolean xts;
    gchar *key_type;
    gchar **volumes;
    gchar **apqns;
    gchar *key_file_name;
    guint64 sector_size;
    gchar *volume_type;
    gchar *dummy_passphrase;
} BDS390ZkeyInfo;

Members

gchar *name;

name of the secure key in the secure key repository;

  

gchar *description;

user provided description of the key or NULL if none was set;.

[nullable]

guint64 secure_key_size;

size of the secure key in bytes;

  

guint64 clear_key_size;

size of the effective (clear) key in bits;

  

gboolean xts;

whether the key is an XTS type key or not;

  

gchar *key_type;

type of the secure key (e.g. "CCA-AESCIPHER");

  

gchar **volumes;

volumes associated with the key, each in the "volume:dmname" format;.

[array zero-terminated=1]

gchar **apqns;

cryptographic adapters (APQNs) associated with the key, each in the "card.domain" format;.

[array zero-terminated=1]

gchar *key_file_name;

full path to the file holding the secure key;

  

guint64 sector_size;

sector size in bytes to use with dm-crypt or 0 for the system default;

  

gchar *volume_type;

volume type the key is to be used with (e.g. "LUKS2");

  

gchar *dummy_passphrase;

path to the dummy passphrase file associated with the key or NULL if none is set;.

[nullable]

enum BDS390Tech

Members

BD_S390_TECH_DASD

    

BD_S390_TECH_ZFCP

    

BD_S390_TECH_PAES

    

enum BDS390TechMode

Members

BD_S390_TECH_MODE_MODIFY

    

BD_S390_TECH_MODE_QUERY

    

BD_S390_TECH_MODE_CREATE

    
Generated by GTK-Doc V1.37.0