DocumentationTutorials

create

Creates a new identity. The identity definition must be provided as a JSON file @values.json.

Usage

vhsm nitride identity create @values.json [flags]

Structure @values.json

  • "type": A string platform|firmware|workload|metadata describe the identity type.

  • "name": An arbitrarily string labelling the identity.

  • "values": An array containing key-value pairs specific to the identity type.

Flags

When to use each parameter

  • Use type to categorize the identity such as platform, firmware, workload, or metadata.

  • Use name to uniquely identify the specific instance of the identity.

  • Use values to provide the specific attributes that define trust for that identity:

    • For platform, specify firmware version and root of trust.

    • For firmware, specify the measurement hash.

    • For workload, specify the hash algorithm and expected PCR values.

Note: Choose the parameters and values based on what you want to trust and verify in your environment. For example, use a platform identity to only allow workloads on specific hardware, a firmware identity to require a specific firmware version, and a workload identity to ensure only known-good application images are run.

Type: platform

Use platform for specific CPU types and their PKI validation.

Values

  • "firmware": A semantic version to denote the firmware version.

  • "root_of_trust": A constant pointing to the certificate chain. Available certificate chains:

    • amd-sev-snp-milan-vcek

    • amd-sev-snp-milan-vlek

    • amd-sev-snp-genoa-vcek

    • amd-sev-snp-genoa-vlek

Example JSON: Platform Identity

{
  "type": "platform",
  "name": "amd-sev-snp-milan-vcek",
  "values": {
    "firmware": ">= 1.55.22",
    "root_of_trust": "amd-sev-snp-milan-vcek"
  }
}

Detailed Explanation:

  • "firmware": The minimum firmware version required such as ">= 1.55.22". Use this to ensure only platforms with up-to-date firmware are trusted.

  • "root_of_trust": Trust identifier is "amd-sev-snp-milan-vcek". Use this to specify which hardware root of trust is required for attestation.

Type: Firmware

Use firmware to capture the UEFI, typically the first piece of software measured in a remote attestation.

Values

  • "measurement": A string capturing the hash value of the UEFI binary. In other words, a cryptographic hash (typically SHA-256 or SHA-512) representing the exact firmware version or build that is trusted.

Example JSON: Firmware Identity

{
  "type": "firmware",
  "name": "azure-dc2as-v5",
  "values": {
    "measurement": "122d0d6fcd1b714a7c34f32d0dc9262ab08976cc8e22132b40ef2569f1dcc47b71ba617debed11563389d7a3f8481d99"
  }
}

Detailed Explanation:

  • "measurement": The cryptographic hash of the firmware image or its configuration. For example, "122d0d6fcd1b714a7c34f32d0dc9262ab08976cc8e22132b40ef2569f1dcc47b71ba617debed11563389d7a3f8481d99".Use this to specify the exact firmware version or build that is trusted.The measurement is typically generated using a secure hash algorithm (SHA-256 or SHA-512) and ensures that only devices running the approved firmware can be attested and authorized.

Type: workload

Use workload for specifying TPM or vTPM measurements of the extended Trusted Computing Base within the virtualized Operating System, including kernel and user-space applications.

Values

  • "hash": The hash algorithm string used for the PCR (Platform Configuration Register) values such as "SHA512".

  • "pcrs": An object mapping PCR indices to their expected hash values. Each key is a PCR index such as "0", "1", and the value is the expected hash.

Example JSON: @workload-identity.json

{
  "type": "workload",
  "name": "azure-sev-snp-vtpm-ubuntu-jammy",
  "values": {
    "hash": "SHA512",
    "pcrs": {
      "0": "054cfc271ddcbd79285968a660bf84ad5b0ca308d2355ce4e0934cecb89590ed",
      "1": "c273c7c778afae92ec7227855d4585444bd7818df9134ba6bf75d53ed8017ebf"
    }
  }
}

Detailed Explanation

  • "hash": The hash algorithm used to compute the PCR values (e.g., "SHA512").Specify the hash algorithm that was used to generate the PCR values. This ensures the attestation process uses the correct algorithm for verification.

  • "pcrs": A map of PCR indices to their expected hash values.Use this to specify the expected state of the workload at launch.Each key is a PCR index (such as "0", "1"), and the value is the expected hash for that register. This is critical for verifying the integrity and configuration of the workload, ensuring only known-good application or VM images are trusted and attested.

Type: metadata

Use metadata for attaching custom, user-defined attributes or tags to an identity for advanced policy, grouping, or informational purposes.

Values

  • "attributes": An object containing key-value pairs representing metadata attributes such as environment, owner, project, region, and others.

  • "description": (Optional) A string providing a human-readable description of the metadata or its purpose.

Example JSON: Metadata Identity

{
  "type": "metadata",
  "name": "prod-database-tag",
  "values": {
    "attributes": {
      "environment": "production",
      "owner": "dba-team",
      "region": "us-east-1"
    },
    "description": "Metadata for production database workloads in us-east-1"
  }
}

Detailed Explanation

  • "attributes": An object containing arbitrary key-value pairs that represent metadata tags or properties. Use this to add contextual information to an identity, such as environment, owner, project, or region. This is useful for advanced policy enforcement, grouping, or filtering.

  • "description" (optional): A human-readable string describing the metadata or its intended use. Use this to provide additional context for administrators or automation.

Next Steps

For more information, see registering identities that are critical for enabling secure workload attestation and enforcing policies based on the trustworthiness of the underlying platform, firmware, and workload.

Last updated

Was this helpful?