s390-tools/rust/pvimg/schema/INFO_JSON_OUTPUT.md

pvimg info JSON Output Documentation

This document describes the JSON output format for the pvimg info command when using --format=json, --format=json:minify or --format=json:pretty.

Overview

The pvimg info command outputs information about IBM Secure Execution (SE) images in JSON format. The output conforms to the JSON schema defined in info-v1.schema.json.

Getting the JSON Schema

To retrieve the JSON schema programmatically, use:

pvimg info --print-schema json

This outputs the complete JSON schema that can be used for validation and documentation purposes.

Output Structure

The JSON output has the following top-level structure:

{
  "meta": {
    "api_level": 1,
    "version": "2.x.x",
    "host": "hostname",
    "time_epoch": 1234567890,
    "time": "YYYY-MM-DD HH:MM:SS+ZZZZ"
  },
  "data": {
    // SE header data (see below)
  }
}

Top-Level Fields

• meta (object, required): Metadata about the s390-tools version and execution environment.
  • api_level (integer, required): API level version, currently always 1.
  • version (string, required): Version of s390-tools.
  • host (string, required): Hostname where the command was executed.
  • time_epoch (integer, required): Unix timestamp (seconds since epoch) when the command was executed.
  • time (string, required): Human-readable timestamp in format 'YYYY-MM-DD HH:MM:SS+ZZZZ'.
• data (object, required): Contains the Secure Execution header information.

SE Header Data Types

The data object can represent three different states of the SE header:

1. Decrypted SE Header (with --hdr-key and --show-secrets)
2. Encrypted SE Header (Verified) (with --hdr-key)
3. Encrypted SE Header (Not Verified) (without --hdr-key)

Common Fields

All three types share these common fields:

Field	Type	Description
kind	string	Type of header: "decrypted_se_hdr" or "se_hdr"
verified	boolean	Whether the SE header integrity and authenticity verified with the header protection key
magic_hex	string	Magic number identifying SE header (hex)
version	string	SE header version (e.g., "V1")
sehs	integer	SE header size in bytes
iv_hex	string	Initialization vector (hex)
nks	integer	Number of key slots
sea	integer	Encrypted area size in bytes
nep	integer	Number of (encrypted) component pages
pcf_hex	string	Plaintext control flags (hex)
cust_pub_key	object	Customer public key
pld_hex	string	PLD (Page content List Digest) hash (hex)
ald_hex	string	ALD (Address List Digest) hash (hex)
tld_hex	string	TLD (Tweak List Digest) hash (hex)
keyslots	array	Array of key slot objects
tag_hex	string	SE header authentication tag (hex)

Customer Public Key Object

{
  "coord_hex": "string"  // EC public key coordinates (hex)
}

Key Slot Object

{
  "phkh_hex": "string",  // Hash of the public target key (hex)
  "wrpk_hex": "string",  // Wrapped SE header protection key (hex)
  "kst_hex": "string"    // Key slot authentication tag (hex)
}

1. Decrypted SE Header

When using --hdr-key with --show-secrets, the output includes decrypted secrets:

{
  "meta": {
    "api_level": 1,
    "version": "2.x.x",
    "host": "hostname",
    "time_epoch": 1234567890,
    "time": "2026-01-15 10:30:45+0100"
  },
  "data": {
    "kind": "decrypted_se_hdr",
    "verified": true,
    "magic_hex": "49424d5365634578",
    "version": "V1",
    "sehs": 640,
    "iv_hex": "...",
    "nks": 1,
    "sea": 128,
    "nep": 4,
    "pcf_hex": "00000000000000e0",
    "cust_pub_key": {
      "coord_hex": "..."
    },
    "pld_hex": "...",
    "ald_hex": "...",
    "tld_hex": "...",
    "keyslots": [
      {
        "phkh_hex": "...",
        "wrpk_hex": "...",
        "kst_hex": "..."
      }
    ],
    "tag_hex": "...",
    "psw": {
      "mask_hex": "...",
      "addr_hex": "..."
    },
    "scf_hex": "...",
    "cck_hex": "...",
    "xts_hex": "..."
  }
}

Additional fields for decrypted headers:

Field	Type	Description
psw	object	Program Status Word with mask_hex and addr_hex
scf_hex	string	Secret control flags (hex)
cck_hex	string	Customer communication key (CCK) (hex)
xts_hex	string	Components encryption key (hex)

Note: The cipher_data_b64 field is NOT present in decrypted headers.

2. Encrypted SE Header (Verified)

When using --hdr-key without --show-secrets:

{
  "meta": {
    "api_level": 1,
    "version": "2.x.x",
    "host": "hostname",
    "time_epoch": 1234567890,
    "time": "2026-01-15 10:30:45+0100"
  },
  "data": {
    "kind": "se_hdr",
    "verified": true,
    "magic_hex": "49424d5365634578",
    "version": "V1",
    "sehs": 640,
    "iv_hex": "...",
    "nks": 1,
    "sea": 128,
    "nep": 4,
    "pcf_hex": "00000000000000e0",
    "cust_pub_key": {
      "coord_hex": "..."
    },
    "pld_hex": "...",
    "ald_hex": "...",
    "tld_hex": "...",
    "keyslots": [
      {
        "phkh_hex": "...",
        "wrpk_hex": "...",
        "kst_hex": "..."
      }
    ],
    "tag_hex": "...",
    "cipher_data_b64": "..."
  }
}

Additional field:

Field	Type	Description
cipher_data_b64	string	Base64-encoded encrypted header data

3. Encrypted SE Header (Not Verified)

When NOT using --hdr-key:

{
  "meta": {
    "api_level": 1,
    "version": "2.x.x",
    "host": "hostname",
    "time_epoch": 1234567890,
    "time": "2026-01-15 10:30:45+0100"
  },
  "data": {
    "kind": "se_hdr",
    "verified": false,
    "magic_hex": "49424d5365634578",
    "version": "V1",
    "sehs": 640,
    "iv_hex": "...",
    "nks": 1,
    "sea": 128,
    "nep": 4,
    "pcf_hex": "00000000000000e0",
    "cust_pub_key": {
      "coord_hex": "..."
    },
    "pld_hex": "...",
    "ald_hex": "...",
    "tld_hex": "...",
    "keyslots": [
      {
        "phkh_hex": "...",
        "wrpk_hex": "...",
        "kst_hex": "..."
      }
    ],
    "tag_hex": "...",
    "cipher_data_b64": "..."
  }
}

Warning: When verified is false, the data has NOT been verified and should not be trusted without proper authentication.

Field Details

Hex String Format

All fields ending in _hex contain hexadecimal strings (characters 0-9, a-f, A-F) without the 0x prefix.

Base64 String Format

The cipher_data_b64 field contains standard Base64-encoded data (characters A-Z, a-z, 0-9, +, /, with optional padding =).

Plaintext Control Flags (PCF)

The pcf_hex field is a hexadecimal string representing control flags. These flags control various SE features, e.g.:

• Dumping support
• CCK extension secret requirement
• CCK update support
• PCKMO key encryption functions (DEA, TDEA, AES, ECC)
• PCKMO HMAC support
• Backup target keys support
• Image component encryption

Refer to the IBM Secure Execution documentation for detailed flag meanings.

Secret Control Flags (SCF)

The scf_hex field (only in decrypted headers) contains secret control flags that are encrypted in the SE header.

Usage Examples

Basic Info (No Authentication)

pvimg info se-image.img --format=json

Output will have verified: false and include cipher_data_b64.

Verified Info

pvimg info se-image.img --format=json --hdr-key header.key

Output will have verified: true and include cipher_data_b64.

Decrypted Info with Secrets

pvimg info se-image.img --format=json --hdr-key header.key --show-secrets

Output will have verified: true, kind: "decrypted_se_hdr", and include decrypted fields (psw, scf_hex, cck_hex, xts_hex) instead of cipher_data_b64.

Pretty-Printed JSON

pvimg info se-image.img --format=json:pretty --hdr-key header.key

Outputs formatted JSON with indentation for better readability.

Get JSON Schema

pvimg info --print-schema json > info-schema.json

Saves the JSON schema to a file for validation purposes.

Validation

The output can be validated against the JSON schema using standard JSON schema validators:

# Get the schema
pvimg info --print-schema json > schema.json

# Generate output
pvimg info se-image.img --format=json > output.json

# Validate (using a JSON schema validator tool)
check-jsonschema -i output.json schema.json

Security Considerations

1. Verification Required: Always use --hdr-key to verify the SE header authenticity. Without verification (verified: false), the data cannot be trusted.

2. Secrets Protection: The --show-secrets option exposes sensitive cryptographic material. Only use this option in secure environments and never share the output containing secrets.

3. Key Protection: The header key file specified with --hdr-key must be kept secure. It was used for the image creation with pvimg create --hdr-key <HDR_KEY>.

Version History

• API Level 1: Initial JSON output format for SE header V1

See Also

• info-v1.schema.json - JSON Schema definition
• pvimg info --help - Command-line help
• man pvimg-info - Manual page
• IBM Secure Execution documentation