Caution

This is documentation for the development version of the project, aka master branch. If you installed Gramine from packages, documentation for the stable version is available at https://gramine.readthedocs.io/en/stable/.

Python API

Introduction

We expose a Python API for manifest, SIGSTRUCT and SGX token management.

Examples

To render a manifest from a jinja2 template:

from graminelibos import Manifest

with open('some_manifest_template_file', 'r') as f:
    template_string = f.read()

manifest = Manifest.from_template(template_string, {'foo': 123})

with open('some_output_file', 'w') as f:
    manifest.dump(f)

To create a signed SIGSTRUCT file from a manifest:

import datetime
from graminelibos import get_tbssigstruct, sign_with_local_key

today = datetime.date.today()
# Manifest must be ready for signing, e.g. all trusted files must be already expanded.
sigstruct = get_tbssigstruct('path_to_manifest', today, 'optional_path_to_libpal')
sigstruct.sign(sign_with_local_key, 'path_to_private_key')

with open('path_to_sigstruct', 'wb') as f:
    f.write(sigstruct.to_bytes())

To create a SGX token file from a signed SIGSTRUCT file:

from graminelibos import Sigstruct, get_token

with open('path_to_sigstruct', 'rb') as f:
    sigstruct = Sigstruct.from_bytes(f.read())

token = get_token(sigstruct)

with open('path_to_token_file', 'wb') as f:
    f.write(token)

API Reference

class graminelibos.ManifestError

Thrown at errors in manifest parsing and handling.

Contains a string with error description.

class graminelibos.Manifest(manifest_str)

Just a representation of a manifest.

You can access or change specific manifest entries via [] operator (just like a normal python dict).

Parameters:: manifest_str (str) – the manifest in the TOML format.

check()

Check the manifest against builtin schema

Raises:: voluptuous.error.MultipleInvalid – when check fails

expand_all_trusted_files(chroot=None)

Expand all trusted files entries.

Collects all trusted files entries, hashes each of them (skipping these which already had a hash present) and updates sgx.trusted_files manifest entry with the result.

Returns a list of all expanded files, as included in the manifest.

Parameters:: chroot (pathlib.Path or None) – Optional chroot directory. If specified, trusted files are expected to be found inside this directory, not in root of filesystem.
Raises:: graminelibos.ManifestError – There was an error with the format of some trusted files in the manifest or some of them could not be loaded from the filesystem.

classmethod from_template(template, variables=None)

Render template into Manifest.

Creates a manifest from the jinja template given as string. Optional variables may be given as mapping.

Parameters:

template (str) – jinja2 template of the manifest
variables (dict, optional) – Dictionary of variables that are used in the template.

Returns:

instance created from rendered template.

Return type:

Manifest

get_dependencies()

Generate list of files which this manifest depends on.

Collects all trusted files that are not yet expanded (do not have a hash in the entry) and returns them.

Returns:: List of paths to the files this manifest depends on.
Return type:: list(pathlib.Path)
Raises:: graminelibos.ManifestError – One of the found URIs is in an unsupported format.

class graminelibos.manifest.TrustedFile(uri, sha256=None, *, chroot=None)

Represents a single entry in sgx.trusted_files.

Parameters:

uri (str) – URI
sha256 (str or None) – sha256
chroot (pathlib.Path or None) – optional path to chroot, if being measured in chroot dir

Raises:

graminelibos.ManifestError – on invalid URI values, or when chroot is not None and realpath is not absolute

chroot: optional chroot, if the file is to be measured in a subdirectory

ensure_hash()

Ensures that the trusted file carries the sha256 sum.

If not, this method will open the file and measure it.

Returns:: self
Return type:: TrustedFile

expand_directory(*, recursive=True, skip_inaccessible=True)

If this TrustedFile is a directory, iterate over its contents.

If the TrustedFile instance is referring to a regular file, yield self and stop iteration.

Parameters:

recursive (bool) – If False, will iterate only over direct descendants, yielding files and directories; if True, will recursively descend into all directories, yielding only regular files.
skip_inaccessible (bool) – If True (the default), will skip entries that are neither directories nor regular files, or fail os.access(realpath, os.R_OK). If False, will iterate over files that failed access test and will possibly error out on while measuring. This argument applies only while recursing into directory (if the instance is referring to a regular file, it will be yielded regardless).

Yields:

TrustedFile – one object for each entry in the directory

Raises:

graminelibos.ManifestError – On errors in URIs, e.g. when directory does not have / at the end or vice versa, or when directory has sha256 value.

classmethod from_manifest(data, *, chroot=None)

Create an instance from an entry in manifest.

Parameters:

data (str or dict) – what is found in manifest data
chroot (pathlib.Path or None) – optional path to chroot, if being measured in chroot dir

Returns:

a single instance of TrustedFile

Return type:

TrustedFile

Raises:

graminelibos.ManifestError – on errors in data

classmethod from_realpath(realpath, *, chroot=None)

Create an instance from a realpath.

This is used for recursive expansion of directories.

Parameters:

realpath (pathlib.Path) – path to the file
chroot (pathlib.Path or None) – optional path to chroot, if being measured in chroot dir

Returns:

a single instance of TrustedFile

Return type:

TrustedFile

Raises:

ValueError – when chroot is not None and realpath is not inside manifest

realpath: real path to the file on disk, including chroot path if specified

sha256: sha256 of the trusted file as str of hex digits, or None if not measured

to_manifest()

Returns the representation of the current file for manifest.

Returns:: To be included as element in sgx.trusted_files list.
Return type:: str or dict

uri: URI of the trusted file