使用Notation和Ratify进行OCI制品的加签和验签

相关概念

notation-alibabacloud-secret-manager：基于Notation社区标准的插件规范，通过阿里云KMS密钥管理服务中管理的密钥对ACR管理的镜像进行签名。

Ratify：是可以运行在Kubernetes集群中的二进制可执行验证引擎，用于对云原生制品中镜像签名、SBOM等安全元数据进行注入验证，并只允许在集群中部署满足策略要求的制品。

前提条件

• 已创建1.20或以上版本的ACK托管集群、ACK专有集群或ACK Serverless集群。请参见创建ACK托管集群、创建ACK专有集群、创建ACK Serverless集群。

• 已创建ACR企业高级版实例，请参见创建企业版实例。

• 已安装Notation CLI。

• 已购买并启用KMS实例，请参见购买和启用KMS实例。

步骤一：获取通过KMS实例管理的密钥

KMS密钥管理服务是一站式的密钥管理和数据加密服务平台，提供简单、可靠、安全、合规的数据加密保护和凭据管理能力。通过KMS实例创建并管理的密钥、以及导入到KMS实例中管理的自签密钥都可以通过notation-alibabacloud-secret-manager插件进行加签。

步骤二：安装notation-alibabacloud-secret-manager插件

notation-alibabacloud-secret-manager插件基于Notation社区标准的插件规范，通过阿里云KMS中管理的密钥对ACR管理的镜像进行签名。

1. 根据不同系统版本选择下载。更多版本下载请参见notation-alibabacloud-secret-manager。

   • Linux_arm64

     wget  https://notation-alibabacloud-secret-manager.oss-cn-hangzhou.aliyuncs.com/dist/v0.1.2/notation-alibabacloud-secret-manager_Linux_arm64.tar.gz      

   • Linux_X86_64

     wget https://notation-alibabacloud-secret-manager.oss-cn-hangzhou.aliyuncs.com/dist/v0.1.2/notation-alibabacloud-secret-manager_Linux_x86_64.tar.gz

2. 使用以下命令创建组件目录。

   mkdir -p  /root/.config/notation/plugins/alibabacloud.secretmanager.plugin/

3. 使用以下命令解压组件tar包到指定目录。

   tar -xvf notation-alibabacloud-secret-manager_Linux_<版本>.tar.gz  -C /root/.config/notation/plugins/alibabacloud.secretmanager.plugin/

4. 配置环境变量。

   export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
   export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
   export ALIBABA_CLOUD_KMS_INSTANCE_ENDPOINT=your_kms_endpoint
   export ALIBABA_CLOUD_KMS_CLIENTKEY_FILEPATH=your_clientkey_filepath
   export ALIBABA_CLOUD_KMS_PASSWORD=your_password
   export ALIBABA_CLOUD_KMS_CA_FILEPATH=your_ca_filepath

   说明

   notation-alibabacloud-secret-manager插件支持多种Credential配置方式。更多的配置方式请参考credentials。

   环境变量	描述	示例
   ALIBABA_CLOUD_ACCESS_KEY_ID	阿里云账号Access Key ID。	XXXXXX
   ALIBABA_CLOUD_ACCESS_KEY_SECRET	阿里云账号Access Secret Key。	XXXXXX
   ALIBABA_CLOUD_KMS_INSTANCE_ENDPOINT	指定KMS专属实例的VPC Endpoint。	kst-hzxxxxxxxxxx.cryptoservice.kms.aliyuncs.com
   ALIBABA_CLOUD_KMS_CLIENTKEY_FILEPATH	访问指定KMS专属实例应用接入点（AAP）的ClientKey凭据文件对应的本地文件路径。使用创建接入点的步骤c中浏览器下载的clientKey_KAAP.****.json内容，创建一个文件（例如/root/clientkey）。	/root/clientkey
   ALIBABA_CLOUD_KMS_PASSWORD	指定KMS专属实例应用接入点（AAP）的凭证口令。使用创建接入点的步骤c中浏览器下载的clientKey_KAAP.594c78e6-7244-4187-XXX-8d59dca2ceb4_Password.txt内容。	XXXXXX
   ALIBABA_CLOUD_KMS_CA_FILEPATH	指定KMS专属实例CA证书对应的本地文件路径。通过步骤四：下载KMS实例的CA证书，将浏览器下载的PrivateKmsCA_xxxxx.pem内容，创建一个文件。	/root/privatekmsca

步骤三：准备镜像并签名

1、在ACR中准备镜像

1. 使用企业版实例构建镜像或在本地构建和推送多架构镜像到容器镜像服务。

   说明

   ACR企业版实例支持OCI v1.1.0版本的镜像和分发规范，可使用ORAS等客户端工具管理和分发非容器镜像内容的OCI制品，请参见使用OCI v1.1.0规范管理和关联容器镜像及其衍生制品。

2. 配置专有网络或公网的访问控制，用于连接企业版实例。请参见配置网络访问控制。

3. 获取登录ACR企业版实例的密码。若您忘记或遗失密码，您可以通过配置访问凭证的方式重置密码。具体操作，请参见配置访问凭证。

2、使用Notation基于KMS中管理的密钥为ACR镜像签名

您可以使用notation-alibabacloud-secret-manager插件基于KMS凭据管家中的私钥和证书，对ACR中的指定镜像加签。

通过notation-alibabacloud-secret-manager插件使用KMS实例SDK for Go，您需要满足以下条件并自定义环境变量。

1. 使用以下命令登录镜像仓库。

   ./notation login --username=tsh_ram@11380257155*** test-for-doc-registry.cn-hangzhou.cr.aliyuncs.com

2. 使用以下命令对指定镜像加签并生成证书。<dirPath>生成证书的存放路径如（/root）

   ./notation sign  --id <keyId> --plugin alibabacloud.secretmanager.plugin test-for-doc-registry.cn-hangzhou.cr.aliyuncs.com/test/nginx:2.11 --plugin-config output_cert_dir=<dirPath>

   预期输出：

   Successfully signed test-for-doc-registry.cn-hangzhou.cr.aliyuncs.com/test/nginx@sha256:f57e1908e63538ad5159fa99443d0492d23b9d34ba7******

3. 您可以通过以下Notation CLI进行制品签名。

   notation sign --id <keyId> --plugin alibabacloud.secretmanager.plugin  <myRegistry>/<myRepo>@<digest> --plugin-config output_cert_dir=<dirPath>

   参数	说明
   id	指定的阿里云KMS实例ID。
   plugin-config	插件自定义参数。支持如下配置： output_cert_dir：签名时，使用该参数基于指定的KMS密钥签发对应的X.509验签证书，并以文件形式输出到参数指定文件目录下。 ca_certs：使用自签并导入KMS实例的密钥加签时，如果您同时使用密钥签发了X.509证书，可以使用该参数指定自签证书对应的文件路径。

步骤四：使用Ratify和Gatekeeper进行验签

1、安装Ratify和Gatekeeper

1. 开启基于Gatekeeper的策略治理，请参见启用安全策略管理。

2. 安装Ratify。

   1. 创建命名空间Ratify。

      kubectl create ns ratify

   2. 登录容器服务管理控制台，在左侧导航栏选择集群。

   3. 在集群列表页面，单击目标集群名称，然后在左侧导航栏，选择应用 > Helm。

   4. 在Helm页面，单击创建，参考如下信息完成基础信息配置，然后选中ratify，单击下一步。

      参数	示例值
      应用名	ratify
      命名空间	选择ratify。
      来源	默认为应用市场。
      Chart	应用场景：选择全部。 支持架构：选择amd64。 搜索框：搜索ratify。

   5. 在参数配置页面，选择Chart 版本，如需通过RRSA拉取镜像，请参考配置示例修改。然后单击确定。

      参数	说明	默认值	配置示例
      ServiceAccount.create	创建Ratify的专属ServiceAccount。取值： true（默认值）：会自动创建名为ratify-admin的ServiceAccount。 false：不会自动创建，如需使用RRSA拉取镜像，则需要提前创建ServiceAccount。	true	保持默认
      ServiceAccount.name	Ratify Service Account的自定义名称。	ratify-admin	保持默认
      ServiceAccount.annotations	自定义ServiceAccount的Annotations。	{}	为其添加Annotation pod-identity.alibabacloud.com/role-name: <Your-RRSA-role>配置以实现自动注入功能。 说明 其中<Your-RRSA-role>替换为您使用的RRSA角色。
      oras.authProviders.k8secretsEnabled	开启Kubernetes Secrets Provider用于和镜像仓库认证。	false	保持默认 说明 关于ORSA相关配置请参见ORAS Store配置示例。
      oras.authProviders.alibabacloudAcrBasicEnabled	开启阿里云ACR Provider用于ACR镜像仓库实例的RRSA认证。	false	true
      oras.cache.enabled	为ListReferrers和 GetSubjectDescriptor启用ORAS存储缓存。 重要 启用后，基于TTL的缓存可能会导致缓存与数据源之间不一致，如果需要强一致性，请禁用此参数。	true	保持默认
      oras.cache.ttl	设置ORAS Store中缓存TTL。	10	保持默认
      alibabacloudAcrConfig.defaultInstanceId	目标制品在ACR仓库中的默认实例ID。	``	必选项。 需要配置已创建的ACR企业版仓库实例ID。
      alibabacloudAcrConfig.acrInstancesConfig	当您需要从不同的阿里云ACR仓库实例中拉取镜像时，不同的实例名称instanceName和instanceId需要分别定义在列表中。	[]	需设置为如下内容，用于连接阿里云ACR私有仓库。
      upgradeCRDs.enabled	开启或关闭 Ratify CRD升级pre-install chart hooks插件。	true	如果不需要升级Ratify CRD的情况下，可以设置为false。 说明 设置为true时会触发pre-install hook，可能导致安装超时。
      featureFlags.RATIFY_CERT_ROTATION	开启或关闭TLS证书轮转，通过该配置可以使Ratify自动生成并轮转证书。	false	需设置为true，使Ratify后端自动生成并轮转证书。
      notationCert	已弃用。 请改用 notationCerts指定Notation的验证证书队列。指定的证书和证书链公钥用于创建Notation验证器使用的内置certstore。	无	保持默认
      notationCerts	用于配置Notation验证器中内置certstore的公钥证书和证书链队列。	``	需要按需填写Notation插件加签过程中返回的KMS验签证书，例如：

3. 在左侧导航栏选择安全管理 > 策略管理，单击我的策略，查看RatifyVerification策略已存在。

2、配置RRSA以拉取ACR私有镜像签名信息

Ratify支持通过RRSA方式拉取阿里云ACR私有仓库的签名数据。更多信息，请参见通过RRSA配置ServiceAccount的RAM权限实现Pod权限隔离。

1. 在指定集群的组件管理页面，安装ack-pod-identity-webhook组件。

2. 创建指定RAM角色ratify-role，配置其可信实体类型为身份提供商，并完成相关限制条件字段的配置，您也可以使用ack-ram-toolCLI工具完成自动化配置。

   {
     "Action": "sts:AssumeRole",
     "Condition": {
       "StringEquals": {
         "oidc:aud": "sts.aliyuncs.com",
         "oidc:iss": "<oidc_issuer_url>",
         "oidc:sub": "system:serviceaccount:<namespace>:<service_account>" # 使用安装ratify组件的命名空间和ServiceAccount。
       }
     },
     "Effect": "Allow",
     "Principal": {
       "Federated": [
         "<oidc_provider_arn>"
       ]
     }
   }

3. 为上述RAM角色ratify-role授予ACR的权限AliyunContainerRegistryFullAccess。

4. 在部署Ratify时创建ServiceAccount，同时给该ServiceAccount和对应部署Ratify的命名空间设置如下所示的Annotation。部署Ratify后，可以看到Ratify的Pod实例模板中的Env是被注入了指定的ALIBABA_CLOUD_ROLE_ARN、ALIBABA_CLOUD_OIDC_PROVIDER_ARN和ALIBABA_CLOUD_OIDC_TOKEN_FILE的环境变量。

   说明

   如果您已提前创建ServiceAccount，请为其添加Annotationpod-identity.alibabacloud.com/role-name: ratify-role。

   ---
   apiVersion: v1
   kind: Namespace
   metadata:
     name: ratify  # 指定Namespace的名称。
     labels:
       pod-identity.alibabacloud.com/injection: 'on'
   
   ---
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: ratify-admin    # 指定ServiceAccount的名称。
     namespace: ratify     # 指定Namespace的名称。
     annotations:
       pod-identity.alibabacloud.com/role-name: ratify-role #以上创建的RAM角色名称
   
   ---

步骤五：验证加签和验签已生效

您可以在ACK集群中使用指定镜像部署应用，以验证镜像的加签验签功能是否生效。

• 当部署有合法签名的镜像时，可以验证工作负载已成功部署在目标集群。

• 当部署使用了未包含签名镜像的工作负载时，可以查看Ratify是否成功拦截了此次部署，通过kubectl查看工作负载状态可以获取拦截信息，同时可以在Ratify Pod日志中查看更多的验签日志。

  kubectl get delpoy ${unsigned_deploy_name} -n${namespace} -oyaml  # 输入应用名称以及所在的命名空间

  页签日志如下所示：

  

更多Ratify配置信息说明

Ratify提供多种内置和外置的Verifier验证器插件，用于指定校验器处理的制品类型；您可以根据不同的验签需求自定义对应的KeyManagementProvider（KMP）实例，定义不同场景下Verifier验签使用的密钥或证书。Ratify还提供了Store用于发现和获取OCI v1.1规范的subject字段中关联类型的元数据，相关配置示例如下：

Notation Verifier配置示例

您可以在Verifier校验器中定义名称name 和 artifactType 字段指定制品类型。Verifier校验器支持集群或命名空间两种维度（使用NamespacedVerifier类型）的定义，更多Verifier信息，请参见Ratify官方文档。

使用默认配置安装Ratify组件后，集群会自动创建如下的Notation Verifier实例， 您可以根据实际使用需求配置具体的trustPolicyDoc策略。配置示例如下：

apiVersion: config.ratify.deislabs.io/v1beta1
kind: Verifier
metadata:
  name: verifier-notation
spec:
  artifactTypes: application/vnd.cncf.notary.signature
  name: notation
  parameters:
    trustPolicyDoc:
      trustPolicies:
      - name: default
        registryScopes:
        - '*'
        signatureVerification:
          level: strict
        trustStores:
        - ca:certs
        trustedIdentities:
        - '*'
      version: "1.0"
    verificationCertStores:
      certs:
      - ratify-notation-inline-cert
  version: 1.0.0
status:
  issuccess: true

KMP配置示例

您可以根据不同的验签需求自定义对应的KeyManagementProvider实例，并在CR中定义公钥或X.509证书。Notation和Cosign等验证器会在签名验证过程中关联对应的KMP实例资源。KMP支持集群或命名空间两种维度的定义，更多KMP信息，请参见Ratify官方文档。配置示例如下：

apiVersion: config.ratify.deislabs.io/v1beta1
kind: KeyManagementProvider
metadata:
  name: ratify-notation-inline-cert
spec:
  parameters:
    contentType: certificate
    value: |
      -----BEGIN CERTIFICATE-----
      XXXXXX
      XXXXXX
      XXXXXX
      -----END CERTIFICATE-----
  type: inline

ORAS Store配置示例

您可以在安装Ratify组件后，在默认创建的ORAS Store实例中进行authProvider配置，用于连接阿里云ACR私有仓库。配置示例如下：

apiVersion: config.ratify.deislabs.io/v1beta1
kind: Store
metadata:
  name: store-oras
spec:
  name: oras
  parameters:
    authProvider:
      acrInstancesConfig:
      - instanceName: name1
        instanceId: cri-aaaaaaaaaaaa
      - instanceName: name2
        instanceId: cri-bbbbbbbbbbbb
      defaultInstanceId: cri-ccccccccc
      name: alibabacloudAcrBasic