[#12131] docs(kms): Describe the provider-neutral KMS API

[nevzheng]

What changes were proposed in this pull request?

Document the complete provider-neutral KMS design:

• API and key-reference contracts;
• named-source configuration, discovery, routing, and lifecycle;
• provider normalization and authentication;
• error and credential-handling boundaries;
• test coverage and remaining work; and
• Iceberg table encryption as an application of the API.

Why are the changes needed?

The KMS API spans public Java contracts, server lifecycle, provider adapters, and security-sensitive configuration. Reviewers and operators need one authoritative description of those boundaries and extension rules.

Part of #12131. Depends on the complete KMS API stack.

Does this PR introduce any user-facing change?

No code behavior changes. It adds the design document for the API introduced by this series.

How was this patch tested?

• Reviewed against the implementation and provider test commands.
• ./gradlew spotlessCheck rat

Series

• Epic: [EPIC] Add a provider-neutral KMS API for key validation #12131
• Position: 11 of 11
• Previous: [#12131] test(azure): Cover Key Vault metadata end to end #12141
• Next: none
• Full stack: [#12131] feat(kms): Define key inspection API #12132 → [#12131] feat(kms): Configure and route named sources #12133 → [#12131] feat(kms): Add Transit key inspection clients #12134 → [#12131] feat(aws): Add KMS key inspection #12135 → [#12131] feat(gcp): Add Cloud KMS key inspection #12136 → [#12131] feat(azure): Add Key Vault key inspection #12137 → [#12131] test(kms): Cover Transit providers end to end #12138 → [#12131] test(aws): Cover KMS adapters end to end #12139 → [#12131] test(gcp): Cover Cloud KMS metadata end to end #12140 → [#12131] test(azure): Cover Key Vault metadata end to end #12141 → [#12131] docs(kms): Describe the provider-neutral KMS API #12142

[nevzheng]

Hi @roryqi and @asdf1234 — please review this KMS API change (11/11). Previous: #12141. Epic: #12131.

[github-actions]

Code Coverage Report

Overall Project	68.05% +0.15%	🟢
Files changed	79.72%	🟢

Module	Coverage
aliyun	1.72%	🔴
api	48.25% +0.43%	🟢
authorization-common	85.96%	🟢
aws	51.64% +9.61%	🟢
azure	47.32% +44.85%	🟢
catalog-common	9.92%	🔴
catalog-fileset	79.74%	🟢
catalog-glue	66.91%	🟢
catalog-hive	79.4%	🟢
catalog-jdbc-common	45.7%	🟢
catalog-jdbc-doris	81.72%	🟢
catalog-jdbc-mysql	79.33%	🟢
catalog-jdbc-postgresql	83.39%	🟢
catalog-jdbc-starrocks	79.16%	🟢
catalog-kafka	77.01%	🟢
catalog-lakehouse-generic	59.18%	🟢
catalog-lakehouse-hudi	79.1%	🟢
catalog-lakehouse-iceberg	85.86%	🟢
catalog-lakehouse-paimon	84.23%	🟢
catalog-model	77.72%	🟢
cli	44.5%	🟢
client-java	78.27%	🟢
common	51.95%	🟢
core	82.67% -0.41%	🟢
filesystem-hadoop3	77.28%	🟢
flink	0.0%	🔴
flink-common	47.09%	🟢
flink-runtime	0.0%	🔴
gcp	47.02% +32.9%	🟢
hadoop-auth	68.0%	🟢
hadoop-common	12.7%	🔴
hive-metastore-common	53.4%	🟢
iceberg-common	64.65%	🟢
iceberg-rest-server	74.91%	🟢
idp-basic	86.02%	🟢
integration-test-common	0.0%	🔴
jobs	66.17%	🟢
lance-common	20.67%	🔴
lance-rest-server	64.84%	🟢
lineage	53.02%	🟢
optimizer	83.24%	🟢
optimizer-api	21.95%	🔴
server	85.92%	🟢
server-common	76.12%	🟢
spark	28.57%	🔴
spark-common	46.01%	🟢
tencent	69.84%	🟢
transit	90.75%	🟢
trino-connector	40.29%	🟢

Files

Module	File	Coverage
api	KmsApi.java	100.0%	🟢
	KmsClient.java	100.0%	🟢
	KmsReference.java	100.0%	🟢
	KmsAuthenticationException.java	0.0%	🔴
	KmsClientFactory.java	0.0%	🔴
	KmsConfigurationException.java	0.0%	🔴
	KmsKeyProperties.java	0.0%	🔴
aws	AwsKmsClient.java	100.0%	🟢
	AwsKmsKeyProperties.java	100.0%	🟢
	AwsKmsClientFactory.java	93.33%	🟢
azure	AzureKeyVaultKmsKeyProperties.java	100.0%	🟢
	AzureKeyVaultKmsClientFactory.java	97.37%	🟢
	AzureKeyVaultKeyIdentifier.java	96.08%	🟢
	AzureKeyVaultKmsClient.java	88.89%	🟢
core	KmsConfig.java	100.0%	🟢
	KmsClientRegistry.java	98.88%	🟢
	GravitinoEnv.java	20.93%	🔴
gcp	GoogleCloudKmsKeyMetadata.java	100.0%	🟢
	GoogleCloudKmsKeyProperties.java	100.0%	🟢
	GoogleCloudKmsSdkMetadataService.java	100.0%	🟢
	GoogleCloudKmsClient.java	95.56%	🟢
	GoogleCloudKmsClientFactory.java	85.29%	🟢
	GoogleCloudKmsMetadataService.java	0.0%	🔴
transit	OpenBaoTransitKmsKeyProperties.java	100.0%	🟢
	TransitKeyData.java	100.0%	🟢
	TransitReadKeyResponse.java	100.0%	🟢
	VaultTransitKmsKeyProperties.java	100.0%	🟢
	OpenBaoTransitKmsClient.java	97.3%	🟢
	OpenBaoTransitKmsClientFactory.java	91.23%	🟢
	VaultTransitKmsClientFactory.java	91.23%	🟢
	TransitApiClient.java	90.22%	🟢
	TransitReadKeyRequest.java	83.33%	🟢
	VaultTransitKmsClient.java	82.35%	🟢
	FileTokenSupplier.java	81.48%	🟢