Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: [kms] code documentation improvements #5689

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

docs: [kms] code documentation improvements #5689

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
13fd625
fix!: Pagination feature is introduced for method `ListKeyHandles` in…
gcf-owl-bot[bot] Sep 19, 2024
bb11beb
🦉 Updates from OwlBot post-processor
gcf-owl-bot[bot] Sep 19, 2024
a5ac9b6
feat: Add GroundedGenerationService API
gcf-owl-bot[bot] Oct 30, 2024
d6f6c77
🦉 Updates from OwlBot post-processor
gcf-owl-bot[bot] Oct 30, 2024
df34097
docs: A comment for enum `CryptoKeyVersionAlgorithm` is changed
gcf-owl-bot[bot] Nov 26, 2024
e8fb7fe
🦉 Updates from OwlBot post-processor
gcf-owl-bot[bot] Nov 26, 2024
dec625b
docs: code documentation improvements
gcf-owl-bot[bot] Dec 17, 2024
359de43
🦉 Updates from OwlBot post-processor
gcf-owl-bot[bot] Dec 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 24 additions & 4 deletions packages/google-cloud-kms/protos/google/cloud/kms/v1/autokey.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,8 @@ option java_multiple_files = true;
option java_outer_classname = "AutokeyProto";
option java_package = "com.google.cloud.kms.v1";

// Provides interfaces for using Cloud KMS Autokey to provision new
// Provides interfaces for using [Cloud KMS
// Autokey](https://cloud.google.com/kms/help/autokey) to provision new
// [CryptoKeys][google.cloud.kms.v1.CryptoKey], ready for Customer Managed
// Encryption Key (CMEK) use, on-demand. To support certain client tooling, this
// feature is modeled around a [KeyHandle][google.cloud.kms.v1.KeyHandle]
Expand All @@ -53,9 +54,9 @@ service Autokey {
// Creates a new [KeyHandle][google.cloud.kms.v1.KeyHandle], triggering the
// provisioning of a new [CryptoKey][google.cloud.kms.v1.CryptoKey] for CMEK
// use with the given resource type in the configured key project and the same
// location. [GetOperation][Operations.GetOperation] should be used to resolve
// the resulting long-running operation and get the resulting
// [KeyHandle][google.cloud.kms.v1.KeyHandle] and
// location. [GetOperation][google.longrunning.Operations.GetOperation] should
// be used to resolve the resulting long-running operation and get the
// resulting [KeyHandle][google.cloud.kms.v1.KeyHandle] and
// [CryptoKey][google.cloud.kms.v1.CryptoKey].
rpc CreateKeyHandle(CreateKeyHandleRequest)
returns (google.longrunning.Operation) {
Expand Down Expand Up @@ -180,6 +181,20 @@ message ListKeyHandlesRequest {
}
];

// Optional. Optional limit on the number of
// [KeyHandles][google.cloud.kms.v1.KeyHandle] to include in the response. The
// service may return fewer than this value. Further
// [KeyHandles][google.cloud.kms.v1.KeyHandle] can subsequently be obtained by
// including the
// [ListKeyHandlesResponse.next_page_token][google.cloud.kms.v1.ListKeyHandlesResponse.next_page_token]
// in a subsequent request. If unspecified, at most 100
// [KeyHandles][google.cloud.kms.v1.KeyHandle] will be returned.
int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

// Optional. Optional pagination token, returned earlier via
// [ListKeyHandlesResponse.next_page_token][google.cloud.kms.v1.ListKeyHandlesResponse.next_page_token].
string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

// Optional. Filter to apply when listing
// [KeyHandles][google.cloud.kms.v1.KeyHandle], e.g.
// `resource_type_selector="{SERVICE}.googleapis.com/{TYPE}"`.
Expand All @@ -191,4 +206,9 @@ message ListKeyHandlesRequest {
message ListKeyHandlesResponse {
// Resulting [KeyHandles][google.cloud.kms.v1.KeyHandle].
repeated KeyHandle key_handles = 1;

// A token to retrieve next page of results. Pass this value in
// [ListKeyHandlesRequest.page_token][google.cloud.kms.v1.ListKeyHandlesRequest.page_token]
// to retrieve the next page of results.
string next_page_token = 2;
}
23 changes: 22 additions & 1 deletion packages/google-cloud-kms/protos/google/cloud/kms/v1/autokey_admin.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,8 @@ option java_multiple_files = true;
option java_outer_classname = "AutokeyAdminProto";
option java_package = "com.google.cloud.kms.v1";

// Provides interfaces for managing Cloud KMS Autokey folder-level
// Provides interfaces for managing [Cloud KMS
// Autokey](https://cloud.google.com/kms/help/autokey) folder-level
// configurations. A configuration is inherited by all descendent projects. A
// configuration at one folder overrides any other configurations in its
// ancestry. Setting a configuration on a folder is a prerequisite for Cloud KMS
Expand Down Expand Up @@ -110,6 +111,23 @@ message AutokeyConfig {
singular: "autokeyConfig"
};

// The states AutokeyConfig can be in.
enum State {
// The state of the AutokeyConfig is unspecified.
STATE_UNSPECIFIED = 0;

// The AutokeyConfig is currently active.
ACTIVE = 1;

// A previously configured key project has been deleted and the current
// AutokeyConfig is unusable.
KEY_PROJECT_DELETED = 2;

// The AutokeyConfig is not yet initialized or has been reset to its default
// uninitialized state.
UNINITIALIZED = 3;
}

// Identifier. Name of the [AutokeyConfig][google.cloud.kms.v1.AutokeyConfig]
// resource, e.g. `folders/{FOLDER_NUMBER}/autokeyConfig`.
string name = 1 [(google.api.field_behavior) = IDENTIFIER];
Expand All @@ -126,6 +144,9 @@ message AutokeyConfig {
// `cloudkms.admin` role (or pertinent permissions). A request with an empty
// key project field will clear the configuration.
string key_project = 2 [(google.api.field_behavior) = OPTIONAL];

// Output only. The state for the AutokeyConfig.
State state = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Request message for
Expand Down
14 changes: 8 additions & 6 deletions packages/google-cloud-kms/protos/google/cloud/kms/v1/ekm_service.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,6 @@ import "google/api/resource.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.Kms.V1";
option go_package = "cloud.google.com/go/kms/apiv1/kmspb;kmspb";
option java_multiple_files = true;
Expand Down Expand Up @@ -289,7 +288,7 @@ message Certificate {
// [CryptoKeys][google.cloud.kms.v1.CryptoKey] and
// [CryptoKeyVersions][google.cloud.kms.v1.CryptoKeyVersion] with a
// [ProtectionLevel][google.cloud.kms.v1.ProtectionLevel] of
// [EXTERNAL_VPC][CryptoKeyVersion.ProtectionLevel.EXTERNAL_VPC], as well as
// [EXTERNAL_VPC][google.cloud.kms.v1.ProtectionLevel.EXTERNAL_VPC], as well as
// performing cryptographic operations using keys created within the
// [EkmConnection][google.cloud.kms.v1.EkmConnection].
message EkmConnection {
Expand Down Expand Up @@ -355,6 +354,7 @@ message EkmConnection {
// All [CryptoKeys][google.cloud.kms.v1.CryptoKey] created with this
// [EkmConnection][google.cloud.kms.v1.EkmConnection] use EKM-side key
// management operations initiated from Cloud KMS. This means that:
//
// * When a [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]
// associated with this [EkmConnection][google.cloud.kms.v1.EkmConnection]
// is
Expand All @@ -363,7 +363,8 @@ message EkmConnection {
// external key material.
// * Destruction of external key material associated with this
// [EkmConnection][google.cloud.kms.v1.EkmConnection] can be requested by
// calling [DestroyCryptoKeyVersion][EkmService.DestroyCryptoKeyVersion].
// calling
// [DestroyCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.DestroyCryptoKeyVersion].
// * Automatic rotation of key material is supported.
CLOUD_KMS = 2;
}
Expand All @@ -378,13 +379,14 @@ message EkmConnection {
google.protobuf.Timestamp create_time = 2
[(google.api.field_behavior) = OUTPUT_ONLY];

// A list of
// Optional. A list of
// [ServiceResolvers][google.cloud.kms.v1.EkmConnection.ServiceResolver] where
// the EKM can be reached. There should be one ServiceResolver per EKM
// replica. Currently, only a single
// [ServiceResolver][google.cloud.kms.v1.EkmConnection.ServiceResolver] is
// supported.
repeated ServiceResolver service_resolvers = 3;
repeated ServiceResolver service_resolvers = 3
[(google.api.field_behavior) = OPTIONAL];

// Optional. Etag of the currently stored
// [EkmConnection][google.cloud.kms.v1.EkmConnection].
Expand All @@ -409,7 +411,7 @@ message EkmConnection {
// [CryptoKeys][google.cloud.kms.v1.CryptoKey] and
// [CryptoKeyVersions][google.cloud.kms.v1.CryptoKeyVersion] with a
// [ProtectionLevel][google.cloud.kms.v1.ProtectionLevel] of
// [EXTERNAL_VPC][CryptoKeyVersion.ProtectionLevel.EXTERNAL_VPC] in a given
// [EXTERNAL_VPC][google.cloud.kms.v1.ProtectionLevel.EXTERNAL_VPC] in a given
// project and location.
message EkmConfig {
option (google.api.resource) = {
Expand Down
35 changes: 18 additions & 17 deletions packages/google-cloud-kms/protos/google/cloud/kms/v1/resources.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,6 @@ import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";

option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.Kms.V1";
option go_package = "cloud.google.com/go/kms/apiv1/kmspb;kmspb";
option java_multiple_files = true;
Expand Down Expand Up @@ -184,7 +183,7 @@ message CryptoKey {
// [DESTROY_SCHEDULED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DESTROY_SCHEDULED]
// state before transitioning to
// [DESTROYED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DESTROYED].
// If not specified at creation time, the default duration is 24 hours.
// If not specified at creation time, the default duration is 30 days.
google.protobuf.Duration destroy_scheduled_duration = 14
[(google.api.field_behavior) = IMMUTABLE];

Expand All @@ -194,7 +193,7 @@ message CryptoKey {
// where all related cryptographic operations are performed. Only applicable
// if [CryptoKeyVersions][google.cloud.kms.v1.CryptoKeyVersion] have a
// [ProtectionLevel][google.cloud.kms.v1.ProtectionLevel] of
// [EXTERNAL_VPC][CryptoKeyVersion.ProtectionLevel.EXTERNAL_VPC], with the
// [EXTERNAL_VPC][google.cloud.kms.v1.ProtectionLevel.EXTERNAL_VPC], with the
// resource name in the format `projects/*/locations/*/ekmConnections/*`.
// Note, this list is non-exhaustive and may apply to additional
// [ProtectionLevels][google.cloud.kms.v1.ProtectionLevel] in the future.
Expand Down Expand Up @@ -348,6 +347,8 @@ message CryptoKeyVersion {
// The suffix following `HMAC_` corresponds to the hash algorithm being used
// (eg. SHA256).
//
// Algorithms beginning with `PQ_` are post-quantum.
//
// For more information, see [Key purposes and algorithms]
// (https://cloud.google.com/kms/docs/algorithms).
enum CryptoKeyVersionAlgorithm {
Expand Down Expand Up @@ -913,6 +914,20 @@ message ExternalProtectionLevelOptions {
string ekm_connection_key_path = 2;
}

// A
// [KeyAccessJustificationsPolicy][google.cloud.kms.v1.KeyAccessJustificationsPolicy]
// specifies zero or more allowed
// [AccessReason][google.cloud.kms.v1.AccessReason] values for encrypt, decrypt,
// and sign operations on a [CryptoKey][google.cloud.kms.v1.CryptoKey].
message KeyAccessJustificationsPolicy {
// The list of allowed reasons for access to a
// [CryptoKey][google.cloud.kms.v1.CryptoKey]. Zero allowed access reasons
// means all encrypt, decrypt, and sign operations for the
// [CryptoKey][google.cloud.kms.v1.CryptoKey] associated with this policy will
// fail.
repeated AccessReason allowed_access_reasons = 1;
}

// [ProtectionLevel][google.cloud.kms.v1.ProtectionLevel] specifies how
// cryptographic operations are performed. For more information, see [Protection
// levels] (https://cloud.google.com/kms/docs/algorithms#protection_levels).
Expand Down Expand Up @@ -999,17 +1014,3 @@ enum AccessReason {
// * Google-initiated support access to protect system reliability.
CUSTOMER_AUTHORIZED_WORKFLOW_SERVICING = 11;
}

// A
// [KeyAccessJustificationsPolicy][google.cloud.kms.v1.KeyAccessJustificationsPolicy]
// specifies zero or more allowed
// [AccessReason][google.cloud.kms.v1.AccessReason] values for encrypt, decrypt,
// and sign operations on a [CryptoKey][google.cloud.kms.v1.CryptoKey].
message KeyAccessJustificationsPolicy {
// The list of allowed reasons for access to a
// [CryptoKey][google.cloud.kms.v1.CryptoKey]. Zero allowed access reasons
// means all encrypt, decrypt, and sign operations for the
// [CryptoKey][google.cloud.kms.v1.CryptoKey] associated with this policy will
// fail.
repeated AccessReason allowed_access_reasons = 1;
}
8 changes: 5 additions & 3 deletions packages/google-cloud-kms/protos/google/cloud/kms/v1/service.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,6 @@ import "google/cloud/kms/v1/resources.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/wrappers.proto";

option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.Kms.V1";
option go_package = "cloud.google.com/go/kms/apiv1/kmspb;kmspb";
option java_multiple_files = true;
Expand Down Expand Up @@ -793,7 +792,9 @@ message ImportCryptoKeyVersionRequest {
// [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion], the
// [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] must be a child of
// [ImportCryptoKeyVersionRequest.parent][google.cloud.kms.v1.ImportCryptoKeyVersionRequest.parent],
// have been previously created via [ImportCryptoKeyVersion][], and be in
// have been previously created via
// [ImportCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.ImportCryptoKeyVersion],
// and be in
// [DESTROYED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DESTROYED]
// or
// [IMPORT_FAILED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.IMPORT_FAILED]
Expand Down Expand Up @@ -1504,7 +1505,8 @@ message MacVerifyRequest {
// checksum. [KeyManagementService][google.cloud.kms.v1.KeyManagementService]
// will report an error if the checksum verification fails. If you receive a
// checksum error, your client should verify that
// CRC32C([MacVerifyRequest.tag][]) is equal to
// CRC32C([MacVerifyRequest.mac][google.cloud.kms.v1.MacVerifyRequest.mac]) is
// equal to
// [MacVerifyRequest.mac_crc32c][google.cloud.kms.v1.MacVerifyRequest.mac_crc32c],
// and if so, perform a limited number of retries. A persistent mismatch may
// indicate an issue in your computation of the CRC32C checksum. Note: This
Expand Down
Loading
Loading