Key Management Service:FAQ about application access

"No such host" or "not known" error when accessing a KMS instance

KMS instances are VPC-bound — they only accept traffic from virtual private clouds (VPCs) you explicitly associate with the instance. If the domain name kst-xxx.cryptoservice.kms.aliyuncs.com cannot be resolved, your application's network has no path to the instance.

• Same region: Associate your application's VPC with the KMS instance. See Access a KMS instance from multiple VPCs in the same region. To check which VPCs are currently associated, see View KMS instance details.

• Different regions: Establish a cross-region network connection between your application's VPC and the KMS instance's VPC before associating them.

The domain name of a KMS instance cannot be resolved

If ping kst-hzz62****.cryptoservice.kms.aliyuncs.com returns a "cannot resolve" error from inside the VPC, the server's DNS is not using Alibaba Cloud's internal resolvers. Check that the DNS configuration points to 100.100.2.136 and 100.100.2.138. For details, see Do I need to modify the DNS configuration of the server to use PrivateZone?.

An on-premises data center cannot access a KMS instance by domain name

After you connect an on-premises data center to an Alibaba Cloud VPC, DNS queries for kms.aliyuncs.com still resolve locally by default. Fix this in two steps:

1. On the Express Connect router, allow the 100.100.2.136 and 100.100.2.138 route segments so the data center can reach Alibaba Cloud's DNS servers.

   Important

   If your data center connects through a provider network rather than an Alibaba Cloud enterprise network or Express Connect circuit, contact your provider for router configuration. Relevant references: Cloud-to-on-premises network interconnection, Connect an on-premises data center to a VPC over an Express Connect circuit, Add and manage route entries, Process messages from an on-premises data center using Message Queue for Apache RocketMQ over an Express Connect circuit.

2. In the local primary DNS configuration file named.conf, forward queries for kms.aliyuncs.com to Alibaba Cloud DNS:

   The exact syntax varies by DNS software. Follow your DNS software's documentation.

   zone "kms.aliyuncs.com" {
       type forward;
       forwarders { 100.100.2.136;100.100.2.138;};
   };

The KMS endpoint is inaccessible

KMS endpoints accept only HTTPS. If your SDK is connecting over HTTP, the endpoint will be unreachable. Enable HTTPS in your SDK configuration:

req.setProtocol(ProtocolType.HTTPS);

UnknownHostException when accessing a KMS instance (Java SDK)

Error: Caused by: java.net.UnknownHostException: kst-hzz664da459rvtjtd****.cryptoservice.kms.aliyuncs.com

This error has the same root cause as the "no such host" error: your application cannot reach the KMS instance's VPC. Work through two checks:

1. Verify network connectivity to the KMS instance's VPC:

   • Same region: Attach your VPC to the KMS instance. See Access a KMS instance from multiple VPCs in the same region.

   • Cross-VPC: Use Cloud Enterprise Network (CEN), VPN Gateway, VPC peering connection, or PrivateLink. See VPC interconnection.

   • VPC to public network: Use a static public IP, Elastic IP Address, NAT Gateway, or Server Load Balancer. See Public network access.

   • VPC to data center: Use VPN Gateway, Express Connect, or Smart Access Gateway. See Connect a VPC to an on-premises data center/other clouds.

2. Verify DNS resolution for the KMS VPC. See Introduction to internal DNS resolution.

Forbidden.NoPermission when accessing a KMS instance via an application access point

Error: Forbidden.NoPermission : This operation is forbidden by permission system.

The application access point (AAP) permission policy is missing the required key or secret. Edit the AAP to add them under RBAC Permissions and Accessible Resources. See Create an application access point.

"This operation for key-xxxxxx is forbidden by permission system" when retrieving a secret value

When KMS stores a secret, it encrypts the secret value with a key from the same KMS instance. To retrieve that secret, the application must have permission to use both the secret and the corresponding key for decryption.

If accessing KMS through a client key of an AAP:

1. In the KMS console, choose Application Access > AAPs in the left navigation pane.

2. Click the AAP name to open the Details page.

3. In the Actions column of the permission policy, click Modify, then configure:

   • RBAC Permissions: Select CryptoServiceKeyUser.

   • Accessible Resources: In Available Resources, select the key and click the icon to add it. Alternatively, click the icon next to Selected Resources to enter the key ID manually in key/key-hzz6xxxxxx format.

4. Click Update.

If accessing KMS with the AccessKey pair of a RAM user or RAM role:

1. Log on to the RAM console.

2. In the left navigation pane, choose Permission Management > Policies.

3. Click the policy attached to your RAM user or RAM role.

4. On the Policy Document tab, click Modify Policy Document, add the following to the Statement field, then click Continue to Edit Basic Information and OK:

   {
       "Effect": "Allow",
       "Action": "kms:Decrypt",
       "Resource": "acs:kms:${region}:${account}:key/keyId-example"
   }

For more information, see Custom permission policies for Key Management Service.

Forbidden.KeyNotFound when accessing or using a key

The region, key ID, or alias in the request doesn't match the one used for encryption. Make sure the decryption operation uses the same region, key ID, or alias as the original encryption operation.

"Unable to find valid certification path to requested target" when accessing a KMS instance

This error typically has one of two causes:

Wrong KMS instance selected when downloading the CA certificate

1. In the KMS console, choose Resource > Instances.

2. Click Download under Instance CA Certificate.

3. In the Instance CA Certificate dialog box, select the correct instance ID, then click Download and store the certificate securely.

The downloaded file is named PrivateKmsCA_kst-******.pem. Integrate this file into your SDK to verify the KMS instance's SSL certificate.

Outdated SDK version

Install the latest SDK version. Check that the Java SDK's tea dependency is version 1.2.3 or later.

"Incorrect ClientKey password" when accessing a KMS instance

Errors by SDK:

• Java: java.io.IOException: keystore password was incorrect

• PHP: Could not decrypt the privateKey of clientKey, the password is incorrect, or it is not a valid pkcs12

• Go: panic: pkcs12: decryption password incorrect

• Python: OpenSSL.crypto.Error: [('PKCS12 routines', '', 'mac verify failure')]

The ClientKey password is wrong or malformed. Check the following:

• Password format: The password must be 8–64 characters and include at least two of: digits, lowercase letters, uppercase letters, and special characters (~!@#$%^&*?_-). If the current password doesn't meet this requirement, create a new ClientKey. See Create a ClientKey.

• Password file: If the password is read from a file, the file must be a plain text file with exactly one line of content — no line feeds or tab characters.

Certificate validation issues when a third-party ISV (independent software vendor) accesses KMS through a dedicated gateway

Self-signed certificates on dedicated gateways cause validation failures for third-party clients. Enable public network access for the KMS instance so the ISV can connect through the shared gateway, which presents a certificate from a trusted certification authority (CA).

1. In the KMS console, choose Resource > Instances.

2. Click the target instance ID, then enable Internet access on the Share Resources tab. When the instance is shared with multiple Alibaba Cloud accounts, configure Internet access permissions per account.

3. Switch to the Instance tab and note the public endpoint.

UnsupportedOperation when calling a KMS API operation

This error has three distinct causes. Match your situation to the one below:

Internet access not enabled

If you use an Alibaba Cloud SDK to perform cryptographic operations with a key in a KMS instance but haven't enabled Internet access, the shared gateway rejects the request.

1. In the KMS console, choose Resource > Instances, then click the instance ID.

2. On the Share Resources tab, enable Internet access. When the instance is shared with multiple accounts, configure access per account.

3. Switch to the Instance tab and copy the public endpoint.

Service key used for direct cryptographic operations

The Encrypt, Decrypt, and GenerateDataKey APIs require a customer master key (CMK). Service keys — managed by other Alibaba Cloud products — cannot be used directly. Switch to a CMK.

Key algorithm doesn't match the operation

Verify that your CMK's algorithm and key usage setting match the API you're calling.

HTTP 413 returned when accessing a KMS instance

After Protocol Buffers encoding, the request body cannot exceed 3 MB. If it does, the server returns HTTP 413.

To stay within limits:

• Encryption and decryption: Keep payloads under 6 KB for symmetric keys and under 1 KB for asymmetric keys. For larger data, use envelope encryption.

• Signing: For large messages, generate a digest locally and pass the digest to the Sign/Verify API instead of the full message.

MissingParameter when calling an OpenAPI operation for cryptographic operations through a dedicated gateway

Error: MissingParamter AParamter x-kms-acccesskeyid does not exist in http header or body "$430c76cd-******

The KMS instance image version is earlier than 3.0.0. Calling OpenAPI operations for cryptographic operations through a dedicated gateway requires image version 3.0.0 or later.

On the Instances page, check the image version in the instance details. If it's outdated, click Upgrade. See Upgrade the image version of a KMS instance.

QPS Limit Exceeded when syncing KMS secrets from Container Service for Kubernetes (ACK) using ack-secret-manager

When a large number of secrets are synced at once, KMS throttling kicks in and interrupts the sync. This issue is fixed in ack-secret-manager version 0.5.2. Upgrade to the latest version.

Is the secret management feature of KMS supported on Android?

No. The secret management feature is not currently supported on Android.