Troubleshoot application access issues via SDK - Key Management Service

List of issues

The "no such host" or "not known" error occurs when you access a KMS instance
The "Forbidden.NoPermission" error occurs when you access a KMS instance through an application access point
The "This operation for key-xxxxxx is forbidden by permission system" error occurs when you retrieve a secret value
The "Forbidden.KeyNotFound" error occurs when you access or use a key
The "UnsupportedOperation" error occurs when you call a KMS API operation
The "unable to find valid certification path to requested target" error occurs when you access a KMS instance
The domain name of a KMS instance cannot be resolved
An "Incorrect ClientKey password" error occurs when you access a KMS instance
An HTTP 413 status code is returned when an application accesses a KMS instance
Is the secret management feature of KMS supported on Android?
The KMS endpoint is inaccessible
An on-premises data center cannot access a KMS instance by its domain name
The "QPS Limit Exceeded" error occurs when ACK syncs KMS secrets by using ack-secret-manager
The "MissingParameter" error occurs when you use a dedicated gateway to call an OpenAPI operation for cryptographic operations
A third-party ISV encounters certificate validation issues when accessing KMS through a dedicated gateway

'no such host' or 'not known' error

Problem

When an application uses the KMS instance SDK for Go to access a KMS instance, the following error is returned: kst-xxx.cryptoservice.kms.aliyuncs.com: no such host.
When an application uses the KMS instance SDK for Java to access a KMS instance, the following error is returned: kst-xxx.cryptoservice.kms.aliyuncs.com: nodename nor servname provided, or not known.

Cause

A KMS instance is a dedicated key and secret management service that you can access only from an associated Virtual Private Cloud (VPC).

Solution

If the VPC where your application runs and the KMS instance are in the same region, associate the VPC with the KMS instance. For more information, see Access a KMS instance from multiple VPCs in the same region.

To check which VPCs are associated with your KMS instance, see View KMS instance details.
If the VPC where your application runs and the KMS instance are in different regions, establish a network connection between the two VPCs.

'Forbidden.NoPermission' error when using an AAP

Problem

When you access a KMS instance, the error description or SDK exception message contains the following: Forbidden.NoPermission : This operation is forbidden by permission system.

Solution

This error occurs because the permission policy for the application access point (AAP) does not grant the required key or secret permissions under RBAC Permissions and Accessible Resources. For more information, see Create an application access point.

'...forbidden by permission system' error when retrieving a secret

Problem

When you retrieve a secret value, the error description or SDK exception message returned by KMS contains the following: This operation for key-xxxxxx is forbidden by permission system.

The following code provides a sample exception message from the KMS instance SDK for Java:

Connected to the target VM, address: '127.0.xxx', transport: 'socket'
Exception in thread "main" com.aliyun.tea.TeaException Create breakpoint : This operation for key-hzz6xxx xxx is forbidden by permission system.
    at com.aliyun.dkms.gcs.openapi.Client.doRequest(Client.java:159)
    at com.aliyun.dkms.gcs.sdk.Client.getSecretValueWithOptions(Client.java:190)
    at com.aliyun.dkms.gcs.sdk.Client.getSecretValue(Client.java:213)
    at com.yqn.center.user.config.RdsSecretSampleCode.main(RdsSecretSampleCode.java:209)
Disconnected from the target VM, address: '127.0.xxx', transport: 'socket'
Process finished with exit code 1

Cause

Your application lacks the permission to use the key for decryption.

When you create a secret, you select a key within the same KMS instance for encryption. To retrieve the secret, your application must have permission not only to access the secret but also to use the corresponding key for decryption.

Solution

Scenario 1: Accessing KMS through an application access point (AAP) by using a ClientKey

Edit the permission policy of the AAP to grant the application permission to use the key for decryption.
1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Application Access > Multi-Cloud Access (formerly AAP).
2. Click the name of the target AAP to go to the Details page.
3. In the Actions column of the permission policy, click Modify. Configure the following parameters and click Update.
  - RBAC Permissions: Select CryptoServiceKeyUser.
  - Accessible Resources: In the Available Resources section, select the key and click the icon. Alternatively, click the icon next to Selected Resources to add a key in the key/key_id format. Example: key/key-hzz6xxxxxx.
Scenario 2: Accessing KMS by using the AccessKey pair of a RAM user or by assuming a RAM role

Edit the RAM permission policy to grant the application permission to use the key for decryption.
1. Log on to the RAM console.
2. In the left-side navigation pane, choose Permissions > Policies.
3. Find the permission policy that is attached to your RAM user or RAM role and click the policy name.
4. On the Policy Document tab, click Modify Policy Document. Add the following script to the Statement section and click Continue to edit basic information.
```
        {
            "Effect": "Allow",
            "Action": "kms:Decrypt",
            "Resource": "acs:kms:${region}:${account}:key/keyId-example"
        }
```
  For more information about permission policies, see Custom permission policies for Key Management Service.

'Forbidden.KeyNotFound' error

Cause: In most cases, the region, key ID, or alias specified in the request does not match the one used for encryption.

Solution: Make sure the region, key ID, or alias used for decryption matches the one used for encryption.

'UnsupportedOperation' error

Incorrect network access configuration
- Cause: Your application is using a standard Alibaba Cloud SDK, not a KMS-specific SDK, to perform cryptographic operations on a key from a KMS instance.
- Solution:
  1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Instances.
  2. In the instance list, click the ID of the target instance. On the details page, turn on the Public Network Access switch in the RD Multi-Account section.
    
    Note
    If a KMS instance is shared among multiple Alibaba Cloud accounts, you can set public network access permissions for each account.
  3. On the Basic Information tab of the instance details page, find the Public Endpoint. The endpoint is displayed after you enable public network access and has a format similar to kms.cn-hangzhou.aliyuncs.com.
Incorrect key type
- Cause: Your application uses a service key when it calls a cryptographic API operation, such as Encrypt, Decrypt, or GenerateDataKey, through an SDK.
- Solution: For cryptographic operations, use a customer master key (CMK) directly, not a service key that is managed by another cloud service.
Mismatch between key algorithm and API
- Scenario 1: Encryption, decryption, and data key generation
  - When you call the GenerateDataKey operation, the key algorithm of the customer master key (CMK) is an asymmetric algorithm such as RSA, ECC.
  - Solution: Make sure that the key algorithm of the CMK is a symmetric algorithm such as AES, and that the key usage is ENCRYPT/DECRYPT.
- Scenario 2: Signing and verification
  - When you call the Sign or Verify operation, the key algorithm of the customer master key (CMK) is a symmetric cryptographic algorithm such as AES.
  - Solution: Make sure that the key algorithm of the CMK is an asymmetric algorithm such as RSA, ECC, and that the key usage is SIGN/VERIFY.

'Unable to find valid certification path' error

Possible cause 1: You selected the CA certificate for the wrong KMS instance

Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Instances.
On the Instances page, click Download in the Instance CA Certificate column.
In the Instance CA Certificate dialog box, select the instance ID, click Download, and then store the certificate in a secure location.

By default, the downloaded CA certificate is named PrivateKmsCA_kst-******.pem. You can integrate the certificate into the SDK to verify the authenticity and validity of the SSL certificate of the KMS instance service.

Possible cause 2: An incorrect version of the SDK is installed

We recommend that you install the latest version of the SDK. The following list provides the open-source repository addresses of the SDKs:

KMS Instance SDK for Java

Note
The tea dependency must be version 1.2.3 or later.
KMS Instance SDK for PHP
KMS Instance SDK for Go
KMS Instance SDK for Python 3, KMS Instance SDK for Python 2
KMS Instance SDK for C#

Cannot resolve KMS instance domain name

Problem

In the VPC to which the KMS instance belongs or in an associated VPC, an application cannot access the domain name of the KMS instance. For example, the ping kst-hzz62****.cryptoservice.kms.aliyuncs.com command fails to resolve the domain name, and the returned message contains "cannot resolve".

Solution

Check whether your server's DNS configuration uses the default Alibaba Cloud DNS servers: 100.100.2.136 and 100.100.2.138. For more information, see Do I need to modify the DNS configuration of the server to use PrivateZone?.

'Incorrect ClientKey password' error

Problem

When you use the KMS instance SDK for Java to access a KMS instance, the following error is returned: java.io.IOException: keystore password was incorrect.
When you use the KMS instance SDK for PHP to access a KMS instance, the following error is returned: Could not decrypt the privateKey of clientKey, the password is incorrect,or it is not a valid pkcs12.
When you use the KMS instance SDK for Go to access a KMS instance, the following error is returned: panic: pkcs12: decryption password incorrect.
When you use the KMS instance SDK for Python to access a KMS instance, the following error is returned: OpenSSL.crypto.Error: [('PKCS12 routines', '', 'mac verify failure')].

Cause

The specified password for the ClientKey is incorrect.

Solution

Check whether the ClientKey password meets the format requirements. If not, you must create a new ClientKey. For more information, see Create a ClientKey.

A ClientKey password must be 8 to 64 characters and contain at least two of the following character types: digits (0-9), lowercase letters (a-z), uppercase letters (A-Z), and special characters (~!@#$%^&*?_-).
If you read the ClientKey password from a file, make sure the file is a plain text file that contains only a single line of the password. The file cannot contain extraneous characters like line breaks or tabs.

HTTP 413 status code

The request body, after being encoded with Protocol Buffers, cannot exceed 3 MB. Requests larger than this limit are rejected with an HTTP 413 status code.

Encryption and decryption: We recommend that you do not exceed 6 KB of data per operation for symmetric keys or 1 KB for asymmetric keys. For larger amounts of data, use envelope encryption.
Signing and verification: If a message to be signed is large, we recommend that your application generates a digest of the message locally and then calls the Sign or Verify operation to sign or verify the digest.

'UnknownHostException' error

Problem

When your application uses the KMS instance SDK for Java to access a KMS instance, the following error is returned: Caused by: java.net.UnknownHostException: kst-hzz664da459rvtjtd****.cryptoservice.kms.aliyuncs.com.

Solution

Verify that your application environment has network connectivity to the VPC of the KMS instance.

If the VPC of your application and the KMS instance are in the same region, associate the VPC with the KMS instance. For more information, see Access a KMS instance from multiple VPCs in the same region. For other scenarios, see the following solutions.
- Cross-VPC interconnection solutions
  
  You can use Cloud Enterprise Network (CEN), VPN Gateway, a VPC peering connection, or PrivateLink to enable private communication between VPCs. For information about the features and configuration of these solutions, see VPC interconnection.
- Connecting a VPC to the internet
  
  You can use a static public IP address of an ECS instance, an Elastic IP Address, a NAT Gateway, or Server Load Balancer (SLB) to allow cloud resources in a VPC to access or be accessed from the internet. For more information, see Public network access.
- Connecting a VPC to an on-premises data center
  
  You can use a VPN Gateway, an Express Connect circuit, or a Smart Access Gateway to connect your on-premises data center to a VPC on the cloud and build a hybrid cloud. For more information, see Connect a VPC to an on-premises data center or another cloud.
Make sure that the KMS VPC domain name resolution is correctly configured. For information about DNS resolution settings, see Introduction to internal DNS resolution.

Is KMS secret management supported on Android?

No, the secret management feature is not currently supported on Android.

The KMS endpoint is inaccessible

This issue usually occurs because the HTTPS protocol is not enabled when you use an SDK to access KMS.

To ensure data security, KMS endpoints support only the HTTPS protocol. When you use an SDK to access a KMS endpoint, run the following code to make sure that HTTPS is enabled for KMS.

req.setProtocol(ProtocolType.HTTPS);

On-premises data center cannot access KMS instance

Problem

An on-premises data center is connected to an Alibaba Cloud VPC. Without any additional configuration, the on-premises data center cannot access a KMS instance by using the domain name kms.aliyuncs.com configured in PrivateZone.

Solution

On the Express Connect router, allow the 100.100.2.136 and 100.100.2.138 route segments to ensure that the on-premises data center can ping 100.100.2.136 and 100.100.2.138. For questions about Express Connect router configuration, consult your network solutions architect or refer to the following documents: 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, and Process messages from an on-premises data center by using Message Queue for Apache RocketMQ over an Express Connect circuit.

Important
If your on-premises data center is not connected by using Alibaba Cloud CEN or an Express Connect circuit, contact your network provider for router configuration.
Modify the local DNS primary configuration file named.conf to forward DNS queries for the KMS domain name (kms.aliyuncs.com) to Alibaba Cloud DNS for resolution. The following code provides a sample configuration:
```
zone "kms.aliyuncs.com" { 
        type forward; 
        forwarders { 100.100.2.136;100.100.2.138;}; 
};
```
Note
The configuration for route forwarding varies based on the DNS software. For more information, see the documentation for your DNS software.

'QPS Limit Exceeded' error when ACK syncs secrets

Cause

Syncing a large number of KMS secrets can trigger the service's throttling policy, causing synchronization to fail.

Solution

This issue is fixed in ack-secret-manager version 0.5.2. Upgrade to version 0.5.2 or a later version.

'MissingParameter' error on dedicated gateway

Problem

When you use an Alibaba Cloud SDK to call an OpenAPI operation for cryptographic operations through a dedicated gateway, the following error is returned: MissingParamter AParamter x-kms-acccesskeyid does not exist in http header or body "$430c76cd-******.

Cause

The image version of the KMS instance is earlier than 3.0.0. To use a dedicated gateway to call OpenAPI operations for cryptographic operations, the image version of the KMS instance must be 3.0.0 or later.

Solution

On the Instances page, check the image version in the instance details. Click Upgrade to upgrade the image version of the KMS instance. For more information, see Upgrade the image version of a KMS instance.

Third-party ISV certificate validation issues

Enabling public access allows the third-party ISV to connect via the shared gateway, which uses a certificate signed by a trusted certification authority (CA).

Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Instances.
In the instance list, click the ID of the target instance. On the details page, turn on the Public Network Access switch in the RD Multi-Account section.

Note
If a KMS instance is shared among multiple Alibaba Cloud accounts, you can set public network access permissions for each account.
On the Basic Information tab of the instance details page, find the Public Endpoint. The endpoint is displayed after you enable public network access and has a format similar to kms.cn-hangzhou.aliyuncs.com.