Alicloud Kms Ops

> This skill follows the Agent Skill OpenSpec.

Alibaba Cloud KMS Operations Skill

Overview

Alibaba Cloud Key Management Service (KMS) provides centralized management of cryptographic keys and secrets on Alibaba Cloud. This skill is an operational runbook for agents: explicit scope, credential rules, pre-flight checks, dual-path execution (official SDK/API and official aliyun CLI), response validation, and failure recovery. Do not use the web console as the primary agent execution path.

KMS covers three primary resource domains:

• Keys (CMK) — Customer Master Keys for encryption, decryption, signing, and verification
• Secrets — Generic secret values with version management and automatic rotation
• KMS Instances — Dedicated KMS instances for enhanced security and compliance

> UX Compliance: This skill follows the User Experience Specification. All operations include onboarding guidance, minimal prompts, smart defaults, clear feedback, and user-friendly error handling.

CLI applicability (repository policy)

• cli_applicability: dual-path: Official aliyun supports KMS product. Both the SDK (via JIT Go) and aliyun kms paths MUST be documented in each execution flow. CLI coverage gaps (if any) will be documented in references/cli-usage.md.

Five Core Standards (Quality Gates)

Every generated skill MUST satisfy these five standards. Use them as a design checklist during population:

| # | Standard | How This Skill Fulfills It | |---|----------|---------------------------| | 1 | Clear Boundaries | SHOULD/SHOULD NOT Use conditions with precise triggers and delegation rules | | 2 | Structured I/O | Placeholder conventions ({{env.*}}, {{user.*}}, {{output.*}}) with type and source documented | | 3 | Explicit Actionable Steps | Every operation: Pre-flight → Execute → Validate → Recover, with numbered imperative steps | | 4 | Complete Failure Strategies | Error taxonomy table with ≥ 10 product-specific codes; HALT vs retry per error type | | 5 | Absolute Single Responsibility | One product (KMS), one primary resource model (Keys + Secrets); cross-product delegation to other skills |

Refer to the [meta-skill](../alicloud-skill-generator/SKILL.md#five-core-standards-quality-gates) for detailed descriptions of each standard.

Well-Architected Framework Integration (卓越架构)

In addition to the Five Core Standards, every generated skill MUST map its operations to Alibaba Cloud's Well-Architected Framework five pillars:

| Pillar | Skill Integration | Reference | |--------|-------------------|-----------| | 安全 (Security) | IAM permissions, credential masking, key policies, HSM protection | references/well-architected-assessment.md §2.1 | | 稳定 (Stability) | Key deletion protection, backup key material, DR runbook | references/well-architected-assessment.md §2.2 | | 成本 (Cost) | KMS instance pricing model, symmetric vs asymmetric key cost | references/well-architected-assessment.md §2.3 | | 效率 (Efficiency) | Batch key alias management, automated rotation, CLI/API automation | references/well-architected-assessment.md §2.4 | | 性能 (Performance) | Cryptographic throughput, latency for encrypt/decrypt, HSM vs software | references/well-architected-assessment.md §2.5 |

See [references/well-architected-assessment.md](references/well-architected-assessment.md) for the complete specification.

Trigger & Scope (Agent-Readable)

SHOULD Use This Skill When

• User mentions "Alibaba Cloud KMS" OR "密钥管理服务" OR "Key Management Service" OR "KMS实例" OR "加密密钥"
• Task involves CRUD or lifecycle operations on Keys / Secrets / Aliases
• Task keywords: KMS, key, CMK, symmetric key, asymmetric key, encrypt, decrypt, secret, rotation, BYOK, data key, alias, KMS instance, sign, verify
• User asks to deploy, configure, troubleshoot, or monitor KMS via API, SDK, CLI, or automation
• Cryptographic operation requirements: generate data keys, encrypt/decrypt data, sign/verify signatures

SHOULD NOT Use This Skill When

• Task is purely RAM / permission model → delegate to: alicloud-ram-ops
• Task is about VPC networking for KMS instances → delegate to: alicloud-vpc-ops
• Task is about CloudHSM (Hardware Security Module) → delegate to: alicloud-cloudhsm-ops (when present)
• Task is purely billing / account management → delegate to: alicloud-billing-ops (when present)
• User insists on console-only flows with no API → state limitation; do not invent undocumented HTTP steps

Delegation Rules

| 能力 | 委托目标 | 说明 | |------|----------|------| | GCL 质量门禁 | alicloud-gcl-runner-ops | 对写操作执行前，委托 GCL 循环进行对抗性评审 |

Variable Convention (Agent-Readable)

Structured placeholders reduce injection ambiguity and unsafe prompts:

| Placeholder | Meaning | Agent Action | |-------------|---------|--------------| | {{env.ALIBABA_CLOUD_ACCESS_KEY_ID}} | From runtime environment | NEVER ask the user; fail if unset | | {{env.ALIBABA_CLOUD_ACCESS_KEY_SECRET}} | From runtime environment | NEVER ask the user; fail if unset | | {{env.ALIBABA_CLOUD_REGION_ID}} | From runtime environment | Use documented default only if skill explicitly allows | | {{user.region}} | User-supplied region | Ask once; reuse | | {{user.key_id}} | User-supplied CMK ID | Ask once; reuse | | {{user.secret_name}} | User-supplied secret name | Ask once; reuse | | {{user.alias_name}} | User-supplied key alias | Ask once; reuse | | {{user.key_spec}} | User-supplied key spec (AliyunAES256, AliyunSM4, RSA2048, ECP256, ECSM2) | Ask once; reuse | | {{output.key_id}} | From last KMS API response (CreateKey) | Parse: $.KeyId | | {{output.secret_name}} | From last KMS API response (CreateSecret) | Parse: $.SecretName | | {{output.request_id}} | From API response (global) | Parse: $.RequestId |

> {{env.*}} MUST NOT be collected from the user. {{user.*}} MUST be collected interactively when missing.

> 凭据安全（强制）： 参考 [Credential Masking 规则](../alicloud-skill-generator/references/credential-masking.md)

API and Response Conventions (Agent-Readable)

• OpenAPI is canonical for path, query, body fields, enums, and response shapes. API version: 2016-01-20. Protocol: RPC-style (HTTPS GET/POST).
• Base endpoint: kms.aliyuncs.com (or regional: kms.{region}.aliyuncs.com)
• Errors: Map SDK/HTTP errors to code / status / message fields per spec. KMS uses Code, Message, RequestId in responses.
• Timestamps: UTC ISO 8601 (e.g. 2026-05-20T10:00:00Z).
• Idempotency: KMS does not use standard client tokens; duplicate resource prevention relies on unique names (alias, secret) and key lifecycle states.

Response Field Table

| Operation | JSON Path | Type | Description | |-----------|-----------|------|-------------| | CreateKey | $.KeyId | string | Globally unique CMK identifier | | CreateKey | $.KeyArn | string | Alibaba Cloud Resource Name of the key | | DescribeKey | $.KeyState | string | Lifecycle state: Enabled, Disabled, PendingDeletion, PendingImport | | DescribeKey | $.KeySpec | string | Key type: AliyunAES256, AliyunSM4, RSA2048, ECP256, ECSM2 | | DescribeKey | $.ProtectionLevel | string | Protection level: SOFTWARE, HSM | | ListKeys | $.Keys.Key[].KeyId | array | CMK IDs on current page | | ListKeys | $.TotalCount | integer | Total CMKs in region | | CreateAlias | $.RequestId | string | Request ID | | DeleteAlias | $.RequestId | string | Request ID | | CreateSecret | $.SecretName | string | Created secret name | | DescribeSecret | $.SecretType | string | Secret type: Generic, Extendable, Rds, RAMCredentials | | DescribeSecret | $.RotationInterval | string | Auto rotation interval | | GetSecretValue | $.SecretData | string | Retrieved secret value | | Encrypt | $.CiphertextBlob | string | Base64-encoded ciphertext | | Decrypt | $.Plaintext | string | Base64-encoded decrypted plaintext | | GenerateDataKey | $.Plaintext | string | Base64-encoded plaintext data key | | GenerateDataKey | $.CiphertextBlob | string | Base64-encoded encrypted data key | | AsymmetricSign | $.Value | string | Base64-encoded signature | | AsymmetricVerify | $.Value | boolean | Signature verification result |

Expected State Transitions

| Operation | Initial State | Target State | Poll Interval | Max Wait | |-----------|---------------|--------------|---------------|----------| | CreateKey | — | Enabled | 2s | 30s | | EnableKey | Disabled | Enabled | 2s | 15s | | DisableKey | Enabled | Disabled | 2s | 15s | | ScheduleKeyDeletion | Enabled/Disabled | PendingDeletion | N/A (async) | N/A | | CancelKeyDeletion | PendingDeletion | Enabled | N/A (async) | N/A | | CreateSecret | — | Available | 2s | 30s | | DeleteSecret | Available | ScheduledDeletion | N/A (async) | N/A | | RestoreSecret | ScheduledDeletion | Available | N/A (async) | N/A |

Quick Start

What This Skill Does

This skill enables you to deploy, configure, troubleshoot, and monitor KMS resources on Alibaba Cloud using the aliyun CLI (primary) or JIT Go SDK (fallback).

Prerequisites

• [ ] aliyun CLI installed (or Go 1.24+ runtime for JIT fallback)
• [ ] Credentials configured: ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET
• [ ] Region set: ALIBABA_CLOUD_REGION_ID

Verify Setup

# Check CLI and KMS API connectivity
aliyun kms DescribeRegions

Your First Command

# Example: List all KMS keys in current region
aliyun kms ListKeys --RegionId {{env.ALIBABA_CLOUD_REGION_ID}}

Next Steps

• [Core Concepts](references/core-concepts.md) — Understand KMS architecture, key lifecycle, and protection levels
• [Common Operations](#execution-flows) — Create, manage, and delete keys and secrets
• [Troubleshooting](references/troubleshooting.md) — Fix common KMS issues

Runtime Rules

| Rule | Status | Details | |------|--------|---------| | CLI Path | MANDATORY | Always use the SkillOpt wrapper script scripts/kms-skillopt-wrapper.sh for all CLI operations. Fallback to native aliyun kms only when the wrapper script is confirmed missing or cannot be sourced. | | SkillOpt Enabled | DEFAULT | SKILLOPT_ENABLED=true by default. Disable only for debugging or offline environments. | | Langfuse Tracing | OPTIONAL | Enable with --skillopt-langfuse-enable flag for observability. Requires valid Langfuse environment variables. |

Capabilities at a Glance

| Operation | Description | Complexity | Risk Level | |-----------|-------------|------------|------------| | CreateKey | Create a Customer Master Key (CMK) | Medium | Low | | DescribeKey | View key details and state | Low | None | | EnableKey / DisableKey | Change key lifecycle state | Low | Medium | | ScheduleKeyDeletion | Schedule key deletion (30-day window) | Low | High | | CancelKeyDeletion | Cancel scheduled key deletion | Low | Low | | CreateAlias | Create/update alias for a key | Low | Low | | DeleteAlias | Delete a key alias | Low | Low | | ListKeys | List all CMKs in region | Low | None | | CreateSecret | Create a managed secret | Medium | Low | | GetSecretValue | Retrieve secret value | Low | Low | | PutSecretValue | Store new secret version | Low | Low | | RotateSecret | Manually rotate a secret | Medium | Low | | DeleteSecret | Schedule secret deletion | Low | High | | RestoreSecret | Restore a scheduled-deletion secret | Low | Medium | | Encrypt | Encrypt data with symmetric key | Low | Low | | Decrypt | Decrypt ciphertext | Low | Low | | GenerateDataKey | Generate data key for envelope encryption | Low | Low | | AsymmetricSign / AsymmetricVerify | Sign and verify with asymmetric key | Medium | Low |

Changelog

| Version | Date | Changes | |---------|------|---------| | 1.0.0 | 2026-05-20 | Initial KMS ops skill — dual-path (CLI + SDK), 17 operations |

> EXECUTION MANDATORY RULE: 所有 control-plane CLI 执行步骤 必须 通过 SkillOpt wrapper ./scripts/kms-skillopt-wrapper.sh 运行。 > 以下所有代码块中的 aliyun kms ... 命令在执行时应替换为 ./scripts/kms-skillopt-wrapper.sh ...。 > 仅在 wrapper 脚本不可用或 skillopt-lib.sh 缺失时，才退回到原生 aliyun kms CLI 调用。 > 参考 ## Runtime Rules 中的 CLI path 规则。

Execution Flows (Agent-Readable)

> Wrapper-First Execution Rule (MANDATORY): All CLI examples in this section MUST be executed via the SkillOpt wrapper script scripts/kms-skillopt-wrapper.sh unless explicitly noted otherwise. Fallback to native aliyun kms commands only when the wrapper script is confirmed missing or cannot be sourced.

Every operation: Pre-flight → Execute (CLI primary + JIT Go SDK fallback) → Validate → Recover. Do not skip phases.

Preference hint: KMS is fully supported by aliyun CLI via RPC-style API. CLI is the primary execution path. JIT Go SDK serves as fallback for edge cases or advanced Go SDK integration.

Operation: CreateKey

Pre-flight Checks

| Check | Method | Expected | On Failure | |-------|--------|----------|------------| | CLI | aliyun version | Exit code 0 | Document CLI install per self-healing framework | | Credentials | Valid AK configured per ~/.aliyun/config.json or env vars | Configured | HALT; user configures credentials | | Region | aliyun kms DescribeRegions | {{user.region}} in returned list | Suggest valid region | | KMS activated | aliyun kms DescribeAccountKmsStatus | Already activated | If not, call OpenKmsService to activate |

Execution — CLI (aliyun) (Primary Path)

# Create a symmetric encryption key with software protection
aliyun kms CreateKey \
  --KeyUsage ENCRYPT/DECRYPT \
  --KeySpec Aliyun_AES_256 \
  --ProtectionLevel SOFTWARE \
  --Description "{{user.description}}" \
  --RegionId "{{user.region}}"

# Create an asymmetric key for signing (SM2 — OSCCA-compliant regions only)
aliyun kms CreateKey \
  --KeyUsage SIGN/VERIFY \
  --KeySpec EC_SM2 \
  --ProtectionLevel SOFTWARE \
  --RegionId "{{user.region}}"

# Create a key with automatic rotation enabled (7–365 days; software symmetric keys only)
aliyun kms CreateKey \
  --KeyUsage ENCRYPT/DECRYPT \
  --KeySpec Aliyun_AES_256 \
  --ProtectionLevel SOFTWARE \
  --EnableAutomaticRotation true \
  --RotationInterval 365 \
  --RegionId "{{user.region}}"

Execution — JIT Go SDK (Fallback Path)

package main

import (
    "fmt"
    "os"

    openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
    kmssdk "github.com/alibabacloud-go/kms-20160120/v3/client"
    "github.com/alibabacloud-go/tea/tea"
    "github.com/alibabacloud-go/tea-utils/v2/service"
)

func main() {
    config := &openapi.Config{
        AccessKeyId:     tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")),
        AccessKeySecret: tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")),
        Endpoint:        tea.Sprintf("kms.%s.aliyuncs.com", os.Getenv("ALIBABA_CLOUD_REGION_ID")),
    }

    client, err := kmssdk.NewClient(config)
    if err != nil {
        fmt.Printf("Error: failed to create KMS client (credential omitted)\n")
        os.Exit(1)
    }

    request := &kmssdk.CreateKeyRequest{
        KeyUsage:        tea.String("ENCRYPT/DECRYPT"),
        KeySpec:         tea.String("Aliyun_AES_256"),
        ProtectionLevel: tea.String("SOFTWARE"),
        Description:     tea.String("JIT-created symmetric key"),
    }

    runtime := &service.RuntimeOptions{ConnectTimeout: tea.Int(5000), ReadTimeout: tea.Int(5000)}
    resp, err := client.CreateKeyWithOptions(request, runtime)
    if err != nil {
        fmt.Printf("Error: CreateKey failed — %v\n", err)
        os.Exit(1)
    }

    fmt.Println(tea.ToString(resp.Body.KeyId))
}

Execute:

mkdir -p /tmp/aliyun-sdk-workspace && cd /tmp/aliyun-sdk-workspace
go mod init kms-jit
export GOPROXY="https://goproxy.cn,direct"

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [buhaiqing](https://github.com/buhaiqing)
- **Source:** [buhaiqing/aliyun-skills](https://github.com/buhaiqing/aliyun-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.