Python SDK API Reference¶

Agentic Workflows¶

WorkflowService ¶

WorkflowService(workflow_uuid, **kwargs)

Opaque Workflow Service API wrapper.

This class provides a convenient interface to submit data to a registered workflow endpoint deployed on a specific Opaque dataplane.

Parameters:

Name	Type	Description	Default
`workflow_uuid`	`uuid.UUID`	The UUID of the workflow to invoke, matching the UUID indicated in the Opaque Web application.	required
`**kwargs`	`WorkflowServiceOptions`	appraiser : Appraiser, optional The appraiser to use appraise attestation documents received from the workflow server, if requested. `If no appraiser is provided, an AttestationAuthorityAppraiser is automatically is created encompassing all underlying appraisers for all supported confidential computing runtimes, each with their default configuration. Note: This parameter will be removed in a future version of the SDK.`	`{}`

submit ¶

submit(inputs, request_timeout_seconds=WORKFLOW_REQUEST_TIMEOUT_SECONDS, **kwargs)

Submits input data to the workflow and returns the response.

Parameters:

Name Type Description Default

inputs

dict

Dictionary of input values required by the workflow. Example:

required

request_timeout_seconds

int

The timeout in seconds for the request. Defaults to 60 seconds.

WORKFLOW_REQUEST_TIMEOUT_SECONDS

**kwargs

WorkflowSubmitOptions

request_report : bool, optional Indicates that an attestation report should be requested from the workflow server and appraised.

By default, this value is False, to avoid the extra latency that
is otherwise incurred.

If the value is True, the resulting response dictonary will
contain a key named `__appraisal__` with an instance of an
Appraisal, containing the result of the appraisal of the
attestation report issued by the workflow server.

Note: This parameter will be removed in a future version of the
SDK.

report_path: str, optional If provided, contains a directory in which to store the attestation report as received from the workflow server.

The report is JWT tokens, and is stored in an individual file
whose name contains a timestamp of when the request was made. If
the directory does not exist, it is created.

Only takes effect if request_report is True.

appraisal_path: str, optional If provided, contains a directory in which to store the log of the appraisal of the attestation reports received from the workflow server.

The log is a plaintext file, and is stored in an individual file
whose name contains a timestamp of when the request was made. If
the directory does not exist, it is created.

Only takes effect if request_report is True.

{}

Returns:

Type	Description
`dict`	Parsed response from the workflow endpoint.

WorkflowServiceOptions ¶

Bases: TypedDict

A typed dictionary that provides typing information for the constructor of class WorkflowService.

WorkflowSubmitOptions ¶

Bases: TypedDict

A typed dictionary that provides typing information for function submit of class WorkflowService.

Attestation¶

Appraiser ¶

Bases: ABC

Abstract class representing functionality to appraise attestation documents generated by a verifier, in the sense of RFC 9334.

appraise `abstractmethod` ¶

appraise(document, data)

Given an attestation document and a set of arbitrary data items, appraises the document to ascertain its trustworthiness and ensures that the document endorses the given data items.

Parameters:

Name	Type	Description	Default
`document`	`bytes`	The attestation document to be appraised.	required

data : list of bytes Data items that the attestation document must endorse.

If you do not have some or all of the relevant reference values,
pass the subset that is available, or otherwise an empty array to
explicitly state the intention to not appraise data endorsements.

Returns:

Type	Description
`Appraisal`	An object indicating whether the appraisal was successful, and a log that describes how the appraisal took place.

Appraisal `dataclass` ¶

Represents the outcome of appraising an attestation document, along with a log of the steps taken during the appraisal process.

Runtime ¶

Bases: str, Enum

Represents a Trusted Execution Environment (TEE) on which the Opaque platform can be deployed. The appraisal policy for a given attestation document is a function of the runtime for which it is generated.

Attestation Authority Appraiser¶

AttestationAuthorityAppraiser ¶

AttestationAuthorityAppraiser(runtimes, appraisers, **kwargs)

Bases: Appraiser

Encapsulates functionality to appraise attestation documents issued in the form of JSON Web Tokens (JWTs) by the Opaque Attestation Authority (AA).

appraise ¶

appraise(document, data)

See the documentation for this method in the base class.

from_appraisers `classmethod` ¶

from_appraisers(appraisers, **kwargs)

Creates a new instance of AttestationAuthorityAppraiser with the given appraisers by allowed runtime.

Parameters:

Name	Type	Description	Default
`appraisers`	`dict[Runtime, Appraiser]`	Map of preconfigured appraisers for each allowed runtime.	required

**kwargs : AttestationAuthorityAppraiserOptions Optional configuration parameters:

max_skew_secs : int
    The number of seconds of leeway allowable during token
    validation where, due to clock skew, the token may appear to be
    issued in the future.

    This value should ideally be no greater than 300s = 5min.

verify_exp : bool, optional
    Specifies whether to treat expired tokens as valid. This is
    useful to verify if old tokens were valid at the time they were
    issued.

    By default, this value is True.

from_runtimes `classmethod` ¶

from_runtimes(runtimes=DEFAULT_RUNTIMES, **kwargs)

Creates a new instance of AttestationAuthorityAppraiser for the given list of allowed runtimes, constructing default appraisers for each.

Parameters:

Name	Type	Description	Default
`runtimes`	`list of Runtime`	List of allowed runtime environments for attestation verification. By default, this parameter contains a list of all runtimes on which the Opaque platform can run. If customization of the appraisers is required (e.g., to set the list of trusted JKUs), use from_appraisers() instead.	`DEFAULT_RUNTIMES`

**kwargs : AttestationAuthorityAppraiserOptions Optional configuration parameters:

max_skew_secs : int
    The number of seconds of leeway allowable during token
    validation where, due to clock skew, the token may appear to be
    issued in the future.

    This value should ideally be no greater than 300s = 5min.

verify_exp : bool, optional
    Specifies whether to treat expired tokens as valid. This is
    useful to verify if old tokens were valid at the time they were
    issued.

    By default, this value is True.

get_unverified_runtime `staticmethod` ¶

get_unverified_runtime(document)

Decodes the given attestation document without verification and extracts the 'runtime' claim.

This function is inteded to be used to read the runtime from an attestation document that was previously successfully appraised and shown to be trustworthy.

Do not call this function on an attestation document whose provenance you do not trust.

Parameters:

Name	Type	Description	Default
`document`	`bytes`	The attestation document to extract the runtime claim from.	required

Returns:

Type	Description
`Runtime`	The runtime claim parsed as a Runtime enum memeber.

AttestationAuthorityAppraiserOptions ¶

Bases: TypedDict

A typed dictionary that provides typing information for the constructor of class AttestationAuthorityAppraiser.

AKS CVM Appraiser¶

CVMAppraiser ¶

CVMAppraiser(**kwargs)

Bases: AASAppraiser

Encapsulates functionality to appraise attestation documents issued in the form of JSON Web Tokens (JWTs) by instances of the Azure Attestation Service (AAS) vouching for the trustworthiness of Confidential VMs (CVMs) in an Azure Kubernetes Service (AKS) node pool.

Note: Should be used when CC Runtime is: - azure/aas/cvm.

Parameters:

Name	Type	Description	Default
`**kwargs`	`CVMAppraiserOptions`	Optional configuration parameters: trusted_jkus : list of str, optional A list of trusted JWKS URLs (i.e., known-good values of the JKU claim). `By default, this parameter contains a list of all known, public, worldwide AAS endpoints.` max_skew_secs : int, optional The number of seconds of leeway allowable during token validation where, due to clock skew, the token may appear to be issued in the future. `This value should ideally be no greater than 300s = 5min.` verify_exp : bool, optional Specifies whether to treat expired tokens as valid. This is useful to verify if old tokens were valid at the time they were issued. `By default, this value is True.`	`{}`

CVMClaims `dataclass` ¶

Hold claims from an AAS JWT token issued to a CVM.

CVMAppraiserOptions ¶

Bases: TypedDict

A typed dictionary that provides typing information for the constructor of class CVMAppraiser.

O-TCB CVM Appraiser¶

OTCBAppraiser ¶

OTCBAppraiser(**kwargs)

Bases: AASAppraiser

OTCBAppraiser encapsulates functionality to appraise attestation documents issued in the form of JSON Web Tokens (JWTs) by instances of the Opaque Attestation Service (OAS) vouching for the trustworthiness of Standard Confidential VMs (CVMs) in an Azure running an OS image containing the Opaque Trusted Computing Base (O-TCB).

Note: Should be used when CC Runtime is one of: - azure/oas/opaque_cvm - azure/oas/opaque_cvm_cgpu

Parameters:

Name	Type	Description	Default
`**kwargs`	`OTCBAppraiserOptions`	Optional configuration parameters: cgpu : bool Indicates whether the O-TCB CVM instance for which the tokens to be validated have a cGPU attached. If so, the tokens to be appraised must have a valid cGPU claim. trusted_oas_jkus : list of str, optional A list of trusted OAS JWKS URLs (i.e., known-good values of the JKU claim for OAS tokens). `By default, this parameter contains a list of all public OAS endpoints.` trusted_aas_kus : list of str, optional A list of trusted AAS JWKS URLs (i.e., known-good values of the JKU claim for AAS tokens). `By default, this parameter contains a list of all known, public, worldwide AAS endpoints.` max_skew_secs : int, optional The number of seconds of leeway allowable during token validation where, due to clock skew, the token may appear to be issued in the future. `This value should ideally be no greater than 300s = 5min.` verify_exp : bool, optional Specifies whether to treat expired tokens as valid. This is useful to verify if old tokens were valid at the time they were issued. `By default, this value is True.`	`{}`

OTCBClaims `dataclass` ¶

Hold claims from an OAS JWT token issued to an O-TCB CVM.

OTCBAppraiserOptions ¶

Bases: TypedDict

A typed dictionary that provides typing information for the constructor of class OTCBAppraiser.

Appraisal Errors¶

AppraisalError ¶

Bases: Exception

Represents an error during the appraisal of an attestation document

UntrustedJKUError ¶

UntrustedJKUError(jku)

Bases: AppraisalError

Indicates that the given JKU is not in the list of trusted JKUs

Constants¶

PUBLIC_OAS_JKUS `module-attribute` ¶

PUBLIC_OAS_JKUS: list[str] = ['https://oas.prod.controlplane.opaque-int.com/.well-known/jwks.json', 'https://oas.prod-westus.controlplane.opaque-int.com/.well-known/jwks.json']

PUBLIC_AAS_JKUS `module-attribute` ¶

PUBLIC_AAS_JKUS: list[str] = ['https://sharedcus.cus.attest.azure.net/certs', 'https://sharedeus.eus.attest.azure.net/certs', 'https://sharedeus2.eus2.attest.azure.net/certs', 'https://shareduks.uks.attest.azure.net/certs']

DEFAULT_RUNTIMES `module-attribute` ¶

DEFAULT_RUNTIMES: list[Runtime] = [Runtime.AZURE_AAS_CVM, Runtime.AZURE_OAS_OPAQUE_CVM, Runtime.AZURE_OAS_OPAQUE_CVM_CGPU]

Python SDK API Reference¶

Agentic Workflows¶

WorkflowService ¶

submit ¶

WorkflowServiceOptions ¶

WorkflowSubmitOptions ¶

Attestation¶

Appraiser ¶

appraise abstractmethod ¶

Appraisal dataclass ¶

Runtime ¶

Attestation Authority Appraiser¶

AttestationAuthorityAppraiser ¶

appraise ¶

from_appraisers classmethod ¶

from_runtimes classmethod ¶

get_unverified_runtime staticmethod ¶

AttestationAuthorityAppraiserOptions ¶

AKS CVM Appraiser¶

CVMAppraiser ¶

CVMClaims dataclass ¶

CVMAppraiserOptions ¶

O-TCB CVM Appraiser¶

OTCBAppraiser ¶

OTCBClaims dataclass ¶

OTCBAppraiserOptions ¶

Appraisal Errors¶

AppraisalError ¶

UntrustedJKUError ¶

Constants¶

PUBLIC_OAS_JKUS module-attribute ¶

PUBLIC_AAS_JKUS module-attribute ¶

DEFAULT_RUNTIMES module-attribute ¶

appraise `abstractmethod` ¶

Appraisal `dataclass` ¶

from_appraisers `classmethod` ¶

from_runtimes `classmethod` ¶

get_unverified_runtime `staticmethod` ¶

CVMClaims `dataclass` ¶

OTCBClaims `dataclass` ¶

PUBLIC_OAS_JKUS `module-attribute` ¶

PUBLIC_AAS_JKUS `module-attribute` ¶

DEFAULT_RUNTIMES `module-attribute` ¶