This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Common types

Understanding common types
  • 1:
  • 2:
  • 3:

List of common protobuf packages used by SPEKTRA Edge services

1 -

All messages and enums in package goten.types

Proto package goten.types

goten.types Shared Messages

Here is the list of goten.types shared messages:

Memo Message

Memo

Name Type Description
create_time .google.protobuf.Timestamp
update_time .google.protobuf.Timestamp
message string
created_by string

Meta Message

Metadata

Name Type Description
create_time .google.protobuf.Timestamp
update_time .google.protobuf.Timestamp
delete_time .google.protobuf.Timestamp
uuid string
tags repeated string
labels map<string, string>
annotations map<string, string>
generation int64 generation is the version number of the spec of the resource. This number increments when the resource is updated with any changes of its spec.
resource_version string An opaque value that represents the internal version of this object that can be used by clients to determine when objects have changed. May be used for optimistic concurrency, change detection, and the watch operation on a resource or set of resources. Clients must treat these values as opaque and passed unmodified back to the server. They may only be valid for a particular resource or set of resources.
owner_references repeated OwnerReference List of objects depended by this object. If ALL objects in the list have been deleted, this object will be garbage collected, unless, the last owner reference had the unset_on_delete flag set to true - in this case the object won’t be garbage collected, just the owner reference will be unset. If this object is managed by a controller, then an entry in this list will point to this controller, with the controller field set to true.
shards map<string, int64> List of all shard indices by their keys
syncing SyncingMeta Information about resource region and synchronization
lifecycle Lifecycle Current lifecycle information about resource.
services ServicesInfo Information about services access.ownership of given resource. Non populated value should be treated as unregulated access.

LabelSelector Message

A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all objects. A null label selector matches no objects.

Name Type Description
match_labels map<string, string> matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is “key”, the operator is “In”, and the values array contains only “value”. The requirements are ANDed.
match_expressions repeated LabelSelectorRequirement matchExpressions is a list of label selector requirements. The requirements are ANDed.

LabelSelectorRequirement Message

A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values.

Name Type Description
key string key is the label key that the selector applies to. +patchMergeKey=key +patchStrategy=merge
operator string operator represents a key’s relationship to a set of values. Valid operators are In, NotIn, Exists and DoesNotExist.
values repeated string values is an array of string values. If the operator is In or NotIn, the values array must be non-empty. If the operator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. +optional

OwnerReference Message

OwnerReference contains enough information to let you identify an owning object. An owning object must be in the same namespace as the dependent, or be cluster-scoped, so there is no namespace field.

Name Type Description
kind string Resource kind, for example “library.goten.com/Site”
version string For example v1
name string Name of the resource, for example projects/p1/devices/d1
region string Region ID owning resource
controller bool If true, this reference points to the managing controller.
requires_owner_reference bool This flag indicates that owner must have schema-based reference for this owner reference to be valid. Otherwise it will be removed. If there are no other owners, resource will be deleted. It also works if owner resource unsets its reference. This extends default behavior of meta references, where ownees are deleted only when owner is deleted. Here, we also want to delete ownee if owner just stops pointing to ownee via own reference (or never pointed at all). This flag is useful if higher-level service creates some resource in lower level service and assigns via schema reference.
unset_on_delete bool This flag indicates if the reference should be unset on the owner deletion. If set, owner’s deletion will not cause the resource deletion, but rather only the owner reference will be unset

SyncingMeta Message

SyncingMeta is a helper object associated with each resource that is either regional or is governed by Policy object. This object is used for internal purposes like Sync controller which ensures data synchronization of all resources across multiple regions.

Name Type Description
owning_region string For regional resources (or their descendants) it is equal to the region ID (present in resource name). Otherwise it is equal to the region as defined in Policy object under default_control_region field.
regions repeated string List of regions where owning resource can be present. If can be present in all regions, will contain “*”.

Lifecycle Message

Name Type Description
state Lifecycle.State Current resource state
block_deletion bool Optional flag indicating that resource must not be deleted - at least yet. This flag is not accessible via API, it is expected developer will populate it if needed from custom server code. It should be used when some condition (other than blocking back reference) applies that server is not aware of. If flag is true, then constraint store will block resource deletion. GC will also defer from cleaning up, however developer should ensure that eventually deletion will be done.

ServicesInfo Message

ServicesInfo contains information about resource ownership/access in terms of service. As goten is a multi-service framework, it is possible for a resource in one service to be “owned” by another one. Owning service may also need to regulate access to other services via allowed services field. It should be note that Goten does not provide authorization layer of its own, ServicesInfo is provided for convenience, but actual restriction should be implemented by actual services.

Name Type Description
owning_service string Service domain owning resource
allowed_services repeated string List of services with allowed access to resource.

MultiRegionPolicy Message

MultiRegionPolicy is an object defining relation between service in multi-region environment and resource holding this policy (as one of its fields). Policy ought to be used for high-level resources like “Project” or “Organization” which form top elements in scopes. Policy then, attached to such a high level resource defines syncing policies for all kid resources and limits their geographical belonging (kid resources can belong only to the region allowed by a policy). Note: While policy governs all resources under policy holder resource, policy holder resource itself is not subject to this policy. This rule allows information about policy spread properly across regions and enables routing.

Name Type Description
enabled_regions repeated string List of regions available in the scope. It is forbidden to create resource within given scope outside allowed regions.
default_control_region string Must be within restricted_regions. Defines region handling CUD requests for resources not attached to any region.
criteria_for_disabled_sync repeated MultiRegionPolicy.CriteriaForDisabledSync List of criteria according to which synchronization is disabled.

MultiRegionPolicy.CriteriaForDisabledSync Message

CriteriaForDisabledSync is a rule preventing data synchronization. By default, everything within Policy scope is synced (unless schema tells otherwise). However, within single scope to which this policy is attached, it is possible to blacklist synchronization for specific criteria. Examples: { resource_type_name: “devices.service.com/Device”, sourceRegion: “france” } -> will make Devices in France private { resource_type_name: “devices.service.com/Device”, destRegion: “hongkong” } -> will prevent from syncing Devices INTO HongKong region { resource_type_name: “devices.service.com/Device”, sourceRegion: “germany”, destRegion: “hongkong” } -> Will block syncing of Devices from Germany to HongKong. { resource_type_name: “devices.service.com/Pod” } -> will make Pods in all regions private { region: “japan” } -> will make all resources in Japan private

Name Type Description
resource_type_name string Fully qualified name of a resource. If not provided, all are considered. Required format: “${SERVICE_DOMAIN}/${RESOURCE_SINGLE_NAME_CAMEL}, for example: “devices.service.com/Device”
source_region string Source region indicates that this rule prevents syncing into this region. If left blank, then all regions are considered.
dest_region string Dest region indicates that this rule prevents syncing from this region. If left blank, then all regions are considered.

goten.types Shared Enumerations

Here is the list of goten.types shared enumerations:

Lifecycle.State Enumeration

current resource state

Name Description
UNDEFINED Must never be used
ACTIVE Resource is up and running
DELETING Resource is in slow-deletion process.

View Enumeration

View defines list of fields of the resource that will be obtained in servers response.

Name Description
UNSPECIFIED
NAME
BASIC
DETAIL
FULL

WatchType Enumeration

WatchType defines how client wants to subscribe for real-time updates when making Watch request.

Name Description
STATEFUL In a Stateful type, by default first watch response contains whole snapshot of a given query according to the provided filter, field mask, order by fields. Paging is supported (page token and size can be used), but resuming not (resume token cannot be used). Reason is, that server drops all state for given watch session after disconnection and cannot match resuming token with some known state. Subsequent responses will contain incremental changes to the initially given snapshot. Server will provide additional information like index positions (and changes of those). It is possible to split snapshot and incremental changes into chunks (and therefore, many watch responses) by using maximum chunk size field in a request. In that case, client is expected to check the appropriate flag in each response messages to find a marker when “complete” message finishes. Clients should specify at least chunk size or page size. If none of them are present, server may enforce own limit on number of resources (page size) and return snapshot with next page token, if that limit was exceeded. If page size is accepted by the server (not too big), then response may be chunked only on user wish, but its not necessary. This type is made for users desiring real-time updates of a defined pages for use in for example UI dashboards, which is typical case when users are capped by a page size.
STATELESS In a stateless type, initial snapshot of a query is sent within N watch responses (N = (NumRes / ChunkSize)), where: NumRes is a number of resources passing optional filter specified in a request (and parent if applicable), and ChunkSize is a maximum number of resource changes allowed to be included in a single Watch<Collection>Response. This chunk size should be specified in request object. Ordering and paging is not supported: request must not specify page token, order by fields or page size. Response object will never contain next/prev page tokens and index positions inside resource change objects must be ignored by a client. Field mask is allowed to be used. As client is supposed to contain state of the session, it is allowed to use resumption tokens and it may be provided with response. Server cannot tell the difference between added or modified resource - instead of using “Add” or “Modified” change types, server uses stateless “Set” type. The only common part is “Removed” type. If client does not specify chunk size, server may enforce its own default value. This type is made for users that do not care about ordering or paging but need general view of a set of resources in the unordered fashion, for example controllers. The benefit of this type, is that number of resources is never capped.

2 -

All messages and enums in package ntt.api

Proto package ntt.api

ntt.api Shared Messages

Here is the list of ntt.api shared messages:

DeviceIdentity Message

Name Type Description
serial_number string
manufacturer string
product_name string
tpm_version TpmVersion Only TPM2.0 is supported
ek_tpm_pub bytes TPM_PUBLIC format object obtained by tpm2.ReadPublic
ekcert bytes ASN.1 DER encoded EK certificate.
ekcerturl string For Intel TPMs, Intel hosts certificates at a public URL derived from the Public key. Clients or servers can perform an HTTP GET to this URL, and use ParseEKCertificate on the response body.
idevid_cert_tpm_pub bytes TPM_PUBLIC format object obtained by tpm2.ReadPublic
idevid_cert bytes ASN.1 DER encoded IDevID certificate.
ldevid_cert_tpm_pub bytes TPM_PUBLIC format object obtained by tpm2.ReadPublic
ldevid_cert bytes ASN.1 DER encoded LDevID certificate.
ak_params DeviceIdentity.AttestationParams
challenge_format DeviceIdentity.ChallengeFormat ChallengeFormat defines the method of generating identity activation challenge by the Verifier (server). It should affect the interpretation ChallengeResponse fields cred_encrypted_by_ekpub and secret_encrypted_by_cred. Attestor (client) is responsible for chosing the right format depending on TPM version and the presence of TrouSerS daemon.

DeviceIdentity.AttestationParams Message

Name Type Description
akpub bytes https: // trustedcomputinggroup.org/wp-content/uploads/TPM-Main-Part-2-TPM-Structures_v1.2_rev116_01032011.pdf https: // www.trustedcomputinggroup.org/wp-content/uploads/TPM-Rev-2.0-Part-2-Structures-01.38.pdf TPMT_PUBLIC (TPM 2.0) or TPM_PUBKEY (TPM 1.2)
creation_data bytes TPMS_CREATION_DATA
attest bytes TPMS_ATTEST
signature bytes TPMT_SIGNATURE

IdentityChallenge Message

One of IDevID or LDevID is mandatory for IdentityChallenge to succeed DevID keys can be either signing or decrypt With GlobalSign + Compulab, we use decrypt keys, but other vendors like Dell may be using signing keys instead, so api should allow both

Name Type Description
platform_attestation_nonce bytes Platform attestation
cred_encrypted_by_ekpub bytes AK TPM Residency check
secret_encrypted_by_ekcred bytes
cred_encrypted_by_idevid_pub bytes IDevID TPM Residency check
secret_encrypted_by_idevid_cred bytes
cred_encrypted_by_ldevid_pub bytes LDevID TPM Residency check
secret_encrypted_by_ldevid_cred bytes
digest_to_sign_with_idevid bytes IDevID verification when key is signing
rsa_secret_to_decrypt_with_idevid bytes IDevID verification when key is decrypt
digest_to_sign_with_ldevid bytes LDevID verification when key is signing
rsa_secret_to_decrypt_with_ldevid bytes LDevID verification when key is decrypt

IdentityChallengeResponse Message

Name Type Description
ak_activation_decrypted_secret bytes
idevid_activation_decrypted_secret bytes
ldevid_activation_decrypted_secret bytes
digest_signed_by_idevid bytes
digest_signed_by_ldevid bytes
rsa_decrypted_with_idevid bytes
rsa_decrypted_with_ldevid bytes
quotes repeated IdentityChallengeResponse.Quote
pcrs repeated PCR
eventlog bytes Binary contents of /sys/kernel/security/tpm0/binary_bios_measurements

IdentityChallengeResponse.Quote Message

Name Type Description
quote bytes TPMS_ATTEST (TSS_VALIDATION.Data or TSS_VALIDATION.rgbData) This contains PCR selection information for which the signature was calculated and other required data, like nonce.
signature bytes TSS_VALIDATION.ValidationData or TSS_VALIDATION.rgbValidationData

PCR Message

Name Type Description
index uint32s
digest_hex string Hex-encoded digest string (without 0x prefix, e.g. “DEADBEEF”)
digest_alg DigestAlg
comment string User’s comments for this entry

Account Message

Name Type Description
user User
service_account ServiceAccount

User Message

Name Type Description
email string
access_token string
token_type string
refresh_token string
expiry .google.protobuf.Timestamp

ServiceAccount Message

Name Type Description
type string
client_email string
private_key_id string
private_key string

HealthCheckSpec Message

HealthCheck describes a health check to be performed in the context of a device or a container. Only the exec check can be truly executed inside a container. All the other checks are run on the host device. When run for device health check, host/IP address is mandatory for connectivity checks. For container health checks, host/IP is optional and would default to IP address of the container. It is important to note that a health check for https://endpoint.com/api defined for a container would be run from the host device and not from withthin the container

Name Type Description
http_get_check HTTPGetCheck http_get_check specifies the http request to perform.
tcp_check TCPCheck tcp_check specifies an action involving a TCP port.
icmp_check ICMPCheck icmp_check specifies an icmp health check
grpc_check GRPCCheck GRPC specifies an action involving a GRPC port. It is essential that the grpc server inplements this api https://github.com/grpc/grpc/blob/master/doc/health-checking.md If not, tcp_check should be used.
exec ExecCheck Exec specifies the command to execute in the container to determine its health
device_file_check DeviceFileCheck device_file_check is only available for device. It can be configured to ensure specific hardware is connected (eg modem /dev/cdc-wdm0, RFID reader device /dev/ttyACM0 etc)
timeout .google.protobuf.Duration Timeout for the HealthCheck. Defaults to 1 second, greater than 5 seconds is not allowed
interval .google.protobuf.Duration Interval for health check, 60 seconds minimum interval
name string name for the health check. A meaningful name for this might be useful as a metrics label

HTTPGetCheck Message

HTTPGetCheck describes health check based on HTTP Get requests.

Name Type Description
url string http_url field has to be used when the IP to perform health check is a container IP that cannot not be known beforehand, In all other cases, simple url string can be used Although not explicitly declared as oneof, url and http_url is oneof type
http_url HTTPGetCheck.HTTPUrl
http_headers repeated HTTPGetCheck.HTTPHeader Custom headers to set in the request. HTTP allows repeated headers. optional
skip_tls_check bool
expected_response_code int32 optional. By default any response code >= 400 or response code == 300 are considered as failure Sometimes, the health check might actually expect 401/403/511 without proper authentication setting expected_response_code will help to consider this as successful for health check
enable_detailed_metrics bool By default only Success or Failure metric will be generated. This field can be used to enable response time metric and network metrics if supported

HTTPGetCheck.HTTPUrl Message

Name Type Description
path string Path to access on the HTTP server, defaults to /
port int32 port to access on the container. defaults to 80 for http and 443 for https Number must be in the range 1 to 65535.
host string Host name to connect to. For containers this defaults to the container IP or wan interface IP in host mode networking For device, this is a mandatory parameter
scheme string Scheme to use for connecting to the host. optional, defaults to HTTP.

HTTPGetCheck.HTTPHeader Message

HTTPHeader describes a custom header to be used in HTTP HealthChecks

Name Type Description
name string The header field name. This will be canonicalized upon output, so case-variant names will be understood as the same header.
value string The header field value

ICMPCheck Message

Name Type Description
host string domain name or IP Addres to perform ICMP check
enable_detailed_metrics bool By default only Success or Failure metric will be generated. This field can be used to enable network metrics such as latency/jitter

TCPCheck Message

TCPCheck performs a TCP connect check. Only TCP handshake is performed. No data is sent

Name Type Description
port int32 Port number to access on the container or given destination. Number must be in the range 1 to 65535.
host string Host name to connect to. For containers this defaults to the container IP or wan interface IP in host mode networking For device, this is a mandatory parameter

GRPCCheck Message

Name Type Description
port int32 Port number of the gRPC service. Number must be in the range 1 to 65535.
service string Service is the name of the service to place in the gRPC HealthCheckRequest (see https://github.com/grpc/grpc/blob/master/doc/health-checking.md). If this is not specified, the default behavior is defined by gRPC.
host string Host name to connect to. For containers this defaults to the container IP or wan interface IP in host mode networking For device, this is a mandatory parameter
skip_tls_check bool

ExecCheck Message

ExecCheck describes a “run in container” action.

Name Type Description
command repeated string Command is the command line to execute inside the container, the working directory for the command is root (’/’) in the container’s filesystem. The command is simply exec’d, it is not run inside a shell, so traditional shell instructions ('

DeviceFileCheck Message

Name Type Description
file_type DeviceFileCheck.FileTypeOneOf
device_file_name string

DeviceFileCheck.FileTypeOneOf Message

Name Type Description
is_directory bool
is_block_device bool
is_char_device bool
is_fifo bool
is_regular_file bool

ntt.api Shared Enumerations

Here is the list of ntt.api shared enumerations:

LaunchStage Enumeration

The launch stage as defined by Google Cloud Platform Launch Stages.

Name Description
LAUNCH_STAGE_UNSPECIFIED Do not use this default value.
EARLY_ACCESS Early Access features are limited to a closed group of testers. To use these features, you must sign up in advance and sign a Trusted Tester agreement (which includes confidentiality provisions). These features may be unstable, changed in backward-incompatible ways, and are not guaranteed to be released.
ALPHA Alpha is a limited availability test for releases before they are cleared for widespread use. By Alpha, all significant design issues are resolved and we are in the process of verifying functionality. Alpha customers need to apply for access, agree to applicable terms, and have their projects whitelisted. Alpha releases don’t have to be feature complete, no SLAs are provided, and there are no technical support obligations, but they will be far enough along that customers can actually use them in test environments or for limited-use tests – just like they would in normal production cases.
BETA Beta is the point at which we are ready to open a release for any customer to use. There are no SLA or technical support obligations in a Beta release. Products will be complete from a feature perspective, but may have some open outstanding issues. Beta releases are suitable for limited production use cases.
GA GA features are open to all developers and are considered stable and fully qualified for production use.
DEPRECATED Deprecated features are scheduled to be shut down and removed. For more information, see the “Deprecation Policy” section of our Terms of Service and the Google Cloud Platform Subject to the Deprecation Policy documentation.

TpmVersion Enumeration

Name Description
TPMVAGNOSTIC
TPMV12
TPMV20

DigestAlg Enumeration

Name Description
SHA1
SHA256

DeviceIdentity.ChallengeFormat Enumeration

Name Description
TPM20_CREDENTIAL Credential Protection as defined in section 24 of the TPM specification revision 2 part 1 See: https://trustedcomputinggroup.org/resource/tpm-library-specification/ Returned primitives are of type TPM2B_ID_OBJECT and TPM2B_ENCRYPTED_SECRET. NOTE: ECC is not supported. Reference implementation: github.com/google/go-attestation@v0.3.2/attest/activation.go:generateChallengeTPM20, which uses github.com/google/go-tmp@v0.3.2/tmp2/credactivation/credential_activation.go:Generate

3 -

All messages and enums in package ntt.rpc

Proto package ntt.rpc

ntt.rpc Shared Messages

Here is the list of ntt.rpc shared messages:

Status Message

The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. The error model is designed to be:

  • Simple to use and understand for most users
  • Flexible enough to meet unexpected needs

Overview

The Status message contains three pieces of data: error code, error message, and error details. The error code should be an enum value of [google.rpc.Code][google.rpc.Code], but it may accept additional error codes if needed. The error message should be a developer-facing English message that helps developers understand and resolve the error. If a localized user-facing error message is needed, put the localized message in the error details or localize it in the client. The optional error details may contain arbitrary information about the error. There is a predefined set of error detail types in the package google.rpc that can be used for common error conditions.

Language mapping

The Status message is the logical representation of the error model, but it is not necessarily the actual wire format. When the Status message is exposed in different client libraries and different wire protocols, it can be mapped differently. For example, it will likely be mapped to some exceptions in Java, but more likely mapped to some error codes in C.

Other uses

The error model and the Status message can be used in a variety of environments, either with or without APIs, to provide a consistent developer experience across different environments.

Example uses of this error model include:

  • Partial errors. If a service needs to return partial errors to the client, it may embed the Status in the normal response to indicate the partial errors.

  • Workflow errors. A typical workflow has multiple steps. Each step may have a Status message for error reporting.

  • Batch operations. If a client uses batch request and batch response, the Status message should be used directly inside batch response, one for each error sub-response.

  • Asynchronous operations. If an API call embeds asynchronous operation results in its response, the status of those operations should be represented directly using the Status message.

  • Logging. If some API errors are stored in logs, the message Status could be used directly after any stripping needed for security/privacy reasons.

Name Type Description
code int32 The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
message string A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
details repeated .google.protobuf.Any A list of messages that carry the error details. There is a common set of message types for APIs to use.