使用实例标识

本文介绍实例标识的概念和使用方法，并分别给出传入和不传入自定义参数时的示例。

背景信息

作为实例元数据的一部分，实例标识可以帮助您快速辨识并区分ECS实例，为应用程序权限控制和软件激活等提供重要的信任基础。实例标识的所有信息均实时生成，随取即用，并跟随实例信息而动态变化。

实例标识由动态生成的实例标识文档（document）和实例标识签名（signature）组成。

实例标识文档用于描述实例的各种信息，包含的主要属性如下表所示：


属性	描述	能否变更
account-id	实例所属用户账号ID	否
instance-id	实例ID	否
mac	实例主网卡MAC地址	否
region-id	实例所属的地域ID	否
serial-number	实例的序列号	否
zone-id	实例所属可用区ID	否
instance-type	实例规格	实例变更实例规格后会发生变化。例如：升降配
image-id	实例使用的镜像ID	实例更换系统盘后会发生变化。例如：更换操作系统（系统盘）
private-ip	实例的私网IP地址	VPC类型实例修改私网IP地址后会发生变化。例如：修改私有IP地址

实例标识签名采用PKCS#7格式加密，纯数字化，安全可靠。

实例标识签名还支持传入自定义audience参数，audience参数可以是随机字符串、时间戳、规律性变化的信息或者根据算法所生成的数据。传入audience参数后，即使他人获取了标识文档和标识签名的部分信息，也很难猜测到 audience 参数取值，可以有效防止签名被非法冒用。

一旦传入audience参数，您需要同时设置标识文档及标识签名。例如，当您获取标识签名时传入了audience参数，则需要在OpenSSL校验之前，手动把audience参数的信息加入实时生成的标识文档末尾处，格式为"audience":"audience参数取值"，参数之间使用半角逗号（,）连接。

在以下场景中，您可以借助实例标识（instance-identity）实现鉴权、授权或者判断运行环境等目的：

传统的线下手动激活的软件授权是一码单用，但由于云上软件的使用时间及场景多变，您可以在上架云市场应用软件时使用实例标识灵活地完成用户授权。更多详情，请参见示例一：不传入audience参数。
当您在ECS实例中写入敏感数据时，您可以使用实例标识确保当前所写入的位置是您的ECS实例而不是其他环境。
其他需要确认目标服务器来源的场景。

使用实例标识需要OpenSSL支持，如果您没有配置OpenSSL服务，请前往OpenSSL官网下载并安装OpenSSL服务。此处以CentOS 7.4为例，示范如何使用实例标识。

远程连接Linux实例。

运行以下命令获取实例标识文档。

curl http://100.100.100.200/latest/dynamic/instance-identity/document

选择一种方式获取实例标识签名。

不传入audience参数：

curl http://100.100.100.200/latest/dynamic/instance-identity/pkcs7

传入audience参数：

curl http://100.100.100.200/latest/dynamic/instance-identity/pkcs7?audience=XXXX

使用OpenSSL认证实例标识。

openssl smime -verify -in $signature -inform PEM -content $DOCUMENT -certfile AliyunPubkey -noverify > /dev/null

命令中参数作用如下：

$signature处填入您获取的标识签名。
$DOCUMENT处填入您获取的标识文档。
（可选）如果您在第三步传入了audience参数，您需要手动将信息附加到实例标识文档末尾处，格式为"audience":"audience参数取值"，参数之间使用半角逗号（,）连接。
AliyunPubkey处填入阿里云公有证书。

以下为阿里云公有证书：

示例一：不传入audience参数

以在云市场上架一份镜像为例，示范如何从应用软件卖家角度使用实例标识。

进入ECS实例环境。
确认当前ECS实例使用的镜像是否来自于云市场镜像。
具体可以通过Metadata中的product-code项（云市场镜像的商品码）和charge-type项（云市场镜像的计费方式）。更多详情，请参见ECS实例元数据概述。
```
curl http://100.100.100.200/latest/meta-data/image/market-place/product-code
curl http://100.100.100.200/latest/meta-data/image/market-place/charge-type
```
在当前工作目录下创建临时文件cert.cer，并保存阿里云公有证书到该文件中。

辨别实例身份。

示例脚本如下：

#!/usr/bin/bash
function verify_signature_without_audience(){
curl 100.100.100.200/latest/dynamic/instance-identity/document > document
echo "-----BEGIN CERTIFICATE-----" > signature
curl 100.100.100.200/latest/dynamic/instance-identity/pkcs7 >> signature
echo "" >> signature
echo "-----END CERTIFICATE-----" >> signature
openssl smime -verify -in signature -inform PEM -content document -certfile cert.cer -noverify > /dev/null
}
verify_signature_without_audience

若标识返回结果为Verification successful，则放开应用软件的权限控制。

示例二：传入audience参数

同样以在云市场上架一份镜像为例，示范如何从应用软件卖家角度使用实例标识。结合您自定义的audience参数，并在放开权限控制之前，通过应用端Server实现策略控制，防止授权码（License）被非法使用。您的audience参数取值可以是随机字符串、时间戳、规律性变化的信息或者根据您的算法所生成的数据。

进入ECS实例环境。
确认当前ECS实例使用的镜像是否来自于云市场镜像。
具体可以通过Metadata中的product-code项（云市场镜像的商品码）和charge-type项（云市场镜像的计费方式）。
```
curl http://100.100.100.200/latest/meta-data/image/market-place/product-code
curl http://100.100.100.200/latest/meta-data/image/market-place/charge-type
```
在当前工作目录下创建临时文件cert.cer，并保存阿里云公有证书到该文件中。

辨别实例身份。

示例脚本如下：

#!/usr/bin/bash
function verify_signature_with_specified_audience(){
audience='your audience' #此处填入您的audience取值
document=$(curl 100.100.100.200/latest/dynamic/instance-identity/document)
audience_json=',"audience":''"'${audience}'"}'
echo -n ${document%?}${audience_json} > document
echo "-----BEGIN CERTIFICATE-----" > signature
curl 100.100.100.200/latest/dynamic/instance-identity/pkcs7?audience=${audience} >> signature
echo "" >> signature
echo "-----END CERTIFICATE-----" >> signature
openssl smime -verify -in signature -inform PEM -content document -certfile cert.cer -noverify > /dev/null
}
verify_signature_with_specified_audience

若标识返回结果为Verification successful，则放开应用软件的权限控制。