Skip to content

elements.md

Latest commit

 

History

History
162 lines (114 loc) · 7.64 KB

elements.md

File metadata and controls

162 lines (114 loc) · 7.64 KB
Raw

Elements

An element is a description of something attestable.

The element consists of a set of its identifier, the compulsory description and a set of optional structures.

Compulsory Fields

The compulsory fields are described below. The field itemid is generated by Jane and is a UUID4; this field should not be specified when adding a new element.

Field Type Description
itemid UUID4 Internally generated identifier
name String A short name for the element
description String A longer, more descriptive description
endpoints Map of name to Endpoint Where the element's trust agents are reached; see below
tags String List A set of freeform tags used for classification

Each Endpoint has:

Field Type Description
endpoint String URL of the trust agent, e.g. http://192.0.2.10:8530
protocol PROTOCOL The protocol the trust agent speaks, e.g. A10HTTPRESTv2 (tarzan) or RATSD

An element may have several endpoints, e.g. tarzan and ratsd; each attestation names the one to use. jp creates elements from a provisioning file (see the Quick start); they can also be created in the Web UI or over REST.

Element type and relationships

Since 1.5.6 (#118), for documentation as attestation targets become more varied. Both fields are optional and independent of the tags.

Field Type Description
elementtype String What the element is. A free string; by convention physical-machine or virtual-machine. jp takes it from elementtype: in the provisioning file's element: section
relationships List of Relationship This element's relationships to other elements, a set (no duplicates)

Each Relationship has:

Field Type Description
relationshiptype String hosted-on (a VM runs on the target element) or runs-on (software runs on the target element)
itemid UUID4 The target element

A relationship is stored on its source element: a VM is hosted-on its host. The only checks are that both elements exist, the type is one of the two above, and an element is not related to itself; there are no other rules (e.g. hosted-on is not limited to VMs).

Relationships are changed only through these REST endpoints. PUT /element (which jp update uses) keeps the stored relationships, whatever the request carries, and a new element starts with none.

Request Body Result
GET /element/<itemid>/relationships {"itemid", "relationships": [...], "length", "relatedfrom": [{"itemid", "name", "relationshiptype"}]}: this element's relationships, and other elements' relationships to it
POST /element/<itemid>/relationships {"relationshiptype": "hosted-on", "itemid": "<target>"} 201; 400 unknown type or self-relationship, 404 an element does not exist, 409 already present
DELETE /element/<itemid>/relationships/<relationshiptype>/<target> 200; 404 element or relationship not found

For example, with REST authentication on:

curl -X POST -H "Authorization: Bearer $JANE_API_KEY" -H "Content-Type: application/json" \
     -d '{"relationshiptype": "hosted-on", "itemid": "<host itemid>"}' \
     http://jane:8520/element/<vm itemid>/relationships

Additions and removals are logged. The Web UI shows the type on the element's card and page, and a Relationships tab with the element's relationships and the elements related to it (display only); x3270 shows them on the element screen. A relationship to an element that has since been deleted is shown as "(missing)". Claims keep a snapshot of the element, so its type and relationships at the time are part of each claim.

Optional Fields

There are a number of individual structures to describe particular properties, eg: of TPMs, UEFI records etc. Not all combinations are valid together, but this very much depends upon the nature of the element in question.

Host Machine

The following fields are part of the host entry; jp fills them in (collecthostinfo)

Field Type Description
os String The operating system of the host machine
arch String The CPU architecture of the host machine
hostname String The hostname
machineid String A unique identifier of a machine, typically /etc/machine-id as found in Debian and Ubuntu distributions

SSHKEY

The following fields are part of the sshkey entry

Field Type Description
key String The location of the private SSH key
timeout Integer The connection timeout limit in seconds
username String The username to log into the given account

UEFI

The following fields are part of the uefi entry

Field Type Description
eventlog String The location of the UEFI eventlog

Note: the location specified here may be overridden by the behaviour of the trust agent

Linux IMA

The following fields are part of the ima entry

Field Type Description
asciilog String The location of the Linux IMA log

Note: the location specified here may be overridden by the behaviour of the trust agent

Intel TXT

The following fields are part of the txt entry

Field Type Description
log String The location of the Intel TXT log

Note: the location specified here may be overridden by the behaviour of the trust agent

TPM 2.0

The following fields are part of the tpm2 entry

Field Type Description
device String The location of the TPM2.0 device, eg: /dev/tpmrm0
ekcerthandle String The NV index of the EK certificate, read by tpm2/getcert: normally 0x01C00002 (RSA 2048; ECC P-256: 0x01C0000A), the default if empty. Before 1.5.6 the examples wrongly gave 0x1C000002, which tarzan refuses as not an NV index: correct it with jp update
ek TPMKey The structure describing the TPM 2.0 Endorsement Key
ak TPMKey The structure describing an attestation key
pcrnaming String The register naming scheme for this TPM's PCRs, e.g. linux-uefi (optional; default tcg-pcclient-uefi; since 1.5.6)

The TPMKey structure is defined:

Field Type Description
handle String The persistent handle of the key in the TPM, e.g. 0x810100AA
public String The key's public area: a marshalled TPM2B_PUBLIC, base64 (written by jp); used by rules such as tpm2_validSignature and by credential activation
name String The key's TPM name, hex (written by jp)

Go Definition

The definition of the element structure can be found at https://github.com/iolivergithub/jane/blob/main/janeserver/structures/elements.go

Example

An element as jp registers it (keys shortened):

{ "itemid": "57c5a486-64ce-4563-b281-a743429c1617",
  "name": "Debian13VM",
  "description": "Debian 13 VM",
  "endpoints": {
    "tarzan": { "endpoint": "http://192.0.2.10:8530", "protocol": "A10HTTPRESTv2" }
  },
  "tags": [ "linux", "x86", "tpm2", "uefi" ],
  "tpm2": { "device": "/dev/tpmrm0",
            "ekcerthandle": "0x01C00002",
            "ek": { "handle": "0x810100EE", "public": "AToAAQALAAMAsg...", "name": "000bd126c6e1..." },
            "ak": { "handle": "0x810100AA", "public": "ARgAAQALAAUAcg...", "name": "000bbaff812d..." } },
  "uefi": { "eventlog": "/sys/kernel/security/tpm0/binary_bios_measurements" },
  "ima": { "asciilog": "/sys/kernel/security/ima/ascii_runtime_measurements" },
  "host": { "os": "linux", "arch": "amd64", "hostname": "debian13vm", "machineid": "39086971960e422aa636cb8bc7f1ad72" }
}