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.
expand_all_trusted_files()

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, i.e. files that we need to hash, and directories that we needed to list.

Raises: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:ManifestError – One of the found URIs is in an unsupported format.