Key Management Service (KMS) provides application access points (AAPs) for identity authentication and access control. A self-managed application requires an AAP for identity and behavior authentication before the application can access a key or a secret by using an SDK.
Introduction to an AAP
An AAP contains two critical pieces of information: permission policy and credential.
We recommend that you create an AAP for each application that needs to access KMS. This way, different applications can have different access permissions on KMS resources.
Permission policies
Permission policies are used to configure which applications are allowed to access specified keys and secrets. You can configure up to three permission policies for each AAP. To create a permission policy, configure the following information:
RBAC permissions:
CryptoServiceKeyUser: allows for the use of keys in a KMS instance. The cryptographic operations of Instance API are supported. For more information, see List of operations by function.
CryptoServiceSecretUser: allows for the use of secrets in a KMS instance. The secret-related operations of Instance API are supported. For more information, see List of operations by function.
SecretUser: allows for the use of all secrets within the current account. The GetSecretValue operation of OpenAPI is supported.
Accessible resources: the KMS resources that can be accessed, such as keys and secrets.
Network access rules: the source IP addresses from which access is allowed.
Credentials
Credentials are used to authenticate the identities and behavior of users that access KMS resources. The following types of credentials are supported. In this topic, authentication is based on a client key.
Client key: A client key is used to sign requests that are initiated from an application to KMS and verify signatures. A client key contains Application Access Secret(ClientKeyContent) and Password.
ImportantKMS does not save client keys. If you do not save your client key or you lose your client key, you can delete the old client key and create a different client key.
A client key has a default validity period of five years. When you create a client key, you can specify a custom validity period for the client key. We recommend that you set the validity period to one year. To ensure access to KMS, you must change your client key before the expiration date of the client key. For more information, see Change a client key. After your client key is changed, we recommend that you delete the client key that is no longer in use from KMS.
If your client key is disclosed, delete the existing client key and create a different client key. You can create up to three client keys for an AAP.
RAM role: You can use this method in scenarios in which your application runs on an Elastic Compute Service (ECS) instance, a Container Service for Kubernetes (ACK) cluster, or Function Compute, your application is associated with a Resource Access Management (RAM) role, and you need to retrieve a secret value by using a KMS endpoint. KMS authenticates OpenAPI requesters by using RAM.
Use an AAP to implement access control
AAPs allow you to configure network access rules. When you use an SDK to perform cryptographic operations or retrieve secret values, you can configure network access rules. The following three categories are supported:
Private: If your application needs to access keys and secrets by using a KMS instance endpoint, select this option.
Public: If your application needs to access secrets by using a KMS public endpoint, select this option.
VPC: If your application needs to access secrets by using a KMS VPC endpoint, select this option. This option is supported only when your KMS instance is in the China (Hangzhou), China (Shanghai), China (Shenzhen), and China (Zhangjiakou) regions.
Cryptographic operations: You can perform cryptographic operations only when you use KMS Instance SDK and a KMS instance endpoint to access KMS. When you create your AAP, set the Network Type parameter to Private.
Secret value retrieval: You can retrieve a secret value by using KMS Instance SDK or a secret SDK. We recommend that you use a secret SDK and set the Network Type parameter to Private when you create your AAP. This helps achieve high queries per second (QPS) and high security.
KMS Instance SDK: If you use KMS Instance SDK, set the Network Type parameter to Private and the Allowed Source IP Addresses parameter to IP addresses in the virtual private clouds (VPCs) that are associated with your KMS instance for your AAP.
Secret SDK: If you use a secret SDK, set the Network Type parameter to Private, Public, or VPC for your AAP.
Examples
In the following example, KMS Instance SDK is used to perform cryptographic operations and retrieve secret values.
The following content describes the description of the AAP in the figure:
Your application can access key-hzz660a5e7ensihzs**** and key-hzz660a5e8dq4iih6**** keys and test_01 and test_02 secrets of the kst-hzz660a5c8ac57csp**** KMS instance over the 192.168.XX.XX IP address.
If you create a client key for the AAP, your browser automatically downloads the client key file and the password file for the client key. When you initialize an SDK, you must configure clientKeyFilePath and clientKeyPass. clientKeyFilePath specifies the path to the client key file. clientKeyPass specifies the password for the client key. The following sample code provides an example on how to initialize KMS Instance SDK for Java. For more information, see KMS Instance SDK for Java.
import com.aliyun.dkms.gcs.openapi.models.Config;
import com.aliyun.dkms.gcs.sdk.Client;
// The connection protocol. Set the value to https. KMS supports connections only over HTTPS.
String protocol = "https";
// The endpoint of your KMS instance. Specify the value in the following format: <ID of your KMS instance >.cryptoservice.kms.aliyuncs.com.
String endpoint = "<your KMS Instance Id>.cryptoservice.kms.aliyuncs.com";
// The client key.
String clientKeyFilePath = "<your client key file path>";
//String clientKey = "<your client key>";
// The password of the client key file.
String clientKeyPass = "<your client key password>";
// The certificate authority (CA) certificate of the KMS instance. You can specify the path to the CA certificate file or enter the content of the CA certificate.
String caCertPath = "<path/to/DKMSInstanceCACertificates>";
//String caCert = "<The DKMS instance CA certificates content>";
Client client = new Client(new Config()
.setProtocol(protocol)
.setEndpoint(endpoint)
.setCaFilePath(caCertPath) // The path to the CA certificate file or the content of the CA certificate. Configure this parameter based on your business requirements.
//.setCa(caCert) // The content of the CA certificate.
.setClientKeyFile(clientKeyFilePath)// The path to the client key file or the content of the client key file. Configure this parameter based on your business requirements.
//.setClientKeyContent(clientKey)// The content of the client key file.
.setPassword(clientKeyPass));