Instance dynamic data (instance identity)

An instance identity, which includes an instance identity document and an instance identity signature, securely identifies an ECS instance. You can use it as a basis of trust for application access control and software activation. This topic describes what an instance identity is, its use cases, and how to retrieve and use it.

Instance identity

An instance identity consists of a dynamically generated instance identity document (document) and an instance identity signature (signature).

Instance identity document

The instance identity document provides identity information about the instance, such as its instance ID and IP address. The following table describes the properties in the document.

Parameter	Description
owner-account-id	The ID of the Alibaba Cloud account that owns the instance.
instance-id	The ID of the instance.
mac	The MAC address of the primary network interface of the instance.
region-id	The ID of the region to which the instance belongs.
serial-number	The serial number of the instance.
zone-id	The ID of the zone to which the instance belongs.
instance-type	The instance type.
image-id	The ID of the image that the instance uses.
private-ipv4	The private IPv4 address of the instance.

Instance identity signature

The instance identity signature verifies the authenticity and integrity of the instance identity document. The signature is digitally signed in the PKCS#7 format to ensure security and reliability.

Instance identity signatures support a custom audience parameter, which is used for authentication to prevent the signature from being misused. The audience parameter can be a random string, a timestamp, regularly changing information, or data generated by an algorithm. If you pass the audience parameter, it is difficult for another party to guess the value of the audience parameter, even if they obtain parts of the instance identity document and instance identity signature. The audience parameter is used for authentication. For more information, see Using instance identity.

Use cases

You can use an instance identity for authentication, authorization, or environment verification in the following scenarios:

Traditional software licensing with single-use activation codes is too rigid for dynamic cloud environments. When you list your application on Alibaba Cloud Marketplace, you can use an instance identity to implement flexible, dynamic user authorization.
When you write sensitive data to an ECS instance, you can use the instance identity to verify that you are writing data to the correct ECS instance and not to a different environment.
Other scenarios where you need to confirm a target server's origin.

Obtain instance identity

(Recommended) Security hardening mode

Linux instance

# Obtain a server access credential. You must set an expiration time. Do not include the X-Forwarded-For header.
TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:<credential-expiration-in-seconds>"`
# Obtain the instance identity.
curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/<dynamic data>

Windows instance
```
# Obtain a server access credential. You must set an expiration time. Do not include the X-Forwarded-For header.
$token = Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token-ttl-seconds" = "<credential-expiration-in-seconds>"} -Method PUT -Uri http://100.100.100.200/latest/api/token
# Obtain the instance identity.
Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token" = $token} -Method GET -Uri http://100.100.100.200/latest/<dynamic data>
```
- <credential-expiration-in-seconds>: The server access credential provides authentication to enhance data security. This value sets the credential's validity period in seconds. Valid values: 1 to 21600.
  - You can reuse the credential until it expires. After it expires, you must retrieve a new one.
  - A credential is valid only for the instance from which it was retrieved. If you try to use the credential on another instance, access is denied.
- <dynamic data>: Replace this with the path to the desired instance identity document or signature.
  - instance identity document: dynamic/instance-identity/document
  - instance identity signature: dynamic/instance-identity/pkcs7?audience=XXXX
    
    Important
    The ?audience=XXXX parameter is optional. For more information, see Instance identity signature.

Normal mode

Linux instance

curl http://100.100.100.200/latest/<dynamic data>

Windows instance (PowerShell)
```
Invoke-RestMethod http://100.100.100.200/latest/<dynamic data>
```
<dynamic data>: Replace this with the path to the desired instance identity document or signature.
- instance identity document: dynamic/instance-identity/document
- instance identity signature: dynamic/instance-identity/pkcs7?audience=XXXX
  
  Important
  The ?audience=XXXX parameter is optional. For more information, see Instance identity signature.

Using an instance identity

The following steps show how to use an instance identity in security hardening mode on an ECS instance that runs Alibaba Cloud Linux 3.

Important

Verifying and using an instance identity requires OpenSSL. If OpenSSL is not installed on your instance, go to the OpenSSL official website to download and install it.

Remotely connect to the Linux instance.

For more information, see Log on to a Linux instance using Workbench.

(Optional) Run the following commands to view the instance identity document and instance identity signature.

# Obtain a server access credential and set its expiration to 3600 seconds.
TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:3600"`
# Obtain the instance identity document.
curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/dynamic/instance-identity/document
# Obtain the instance identity signature.
curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/dynamic/instance-identity/pkcs7

TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:3600"`
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    29  100    29    0     0    805      0 --:--:-- --:--:-- --:--:--   805
curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/dynamic/instance-identity/document
{"zone-id":"cn-hangzhou-h","serial-number":"es4xxx","instance-id":"i-bp1xxx","region-id":"cn-hangzhou","private-ipv4":"xxx","owner-account-id":"xxx","mac":"xxx","image-id":"aliyun_3_x64_20G_alibase_20240528.vhd","instance-type":"ecs.e-c1m1.large"}
curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/dynamic/instance-identity/pkcs7
MIIDHwYJKo7ThvcNAOcrCoTfDCCAwwCAQExCzAJBgUrDpMCGgUAMTTRWOYJKo7ThvcNAOcrBoTfBSpSCAU77TnpvhmUltaWOiOiJhIoaYW5nbmVhdmS1dToidw2VvalEsl W51bWJ1ciI6TGtIMlINDk4MiNi TO2YmOtNDpzNv1hMTJhI wWyQAMmRhMi3k3OTAQNvTsTmur3RhbmNl1wlkTioia5i3ciDE1dn
BqdGo
aWJho
UEAxM
v45mv

Save the instance identity document, instance identity signature, and Alibaba Cloud public certificate to files.

Run the following command to save the instance identity document to a file named document.
```
curl 100.100.100.200/latest/dynamic/instance-identity/document > document
```

Run the following commands to save the instance identity signature to a file named signature.

echo "-----BEGIN CERTIFICATE-----" > signature
curl 100.100.100.200/latest/dynamic/instance-identity/pkcs7 >> signature
echo "" >> signature
echo "-----END CERTIFICATE-----" >> signature

Run the following command to save the Alibaba Cloud public certificate to a file named cert.cer.

cat <<EOF > cert.cer
-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEZmbRhzANBgkqhkiG9w0BAQsFADBsMRAwDgYDVQQGEwdV
bmtub3duMRAwDgYDVQQIEwdVbmtub3duMRAwDgYDVQQHEwdVbmtub3duMRAwDgYD
VQQKEwdVbmtub3duMRAwDgYDVQQLEwdVbmtub3duMRAwDgYDVQQDEwdVbmtub3du
MB4XDTE4MDIyMzAxMjkzOFoXDTM4MDIxODAxMjkzOFowbDEQMA4GA1UEBhMHVW5r
bm93bjEQMA4GA1UECBMHVW5rbm93bjEQMA4GA1UEBxMHVW5rbm93bjEQMA4GA1UE
ChMHVW5rbm93bjEQMA4GA1UECxMHVW5rbm93bjEQMA4GA1UEAxMHVW5rbm93bjCC
ASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAIJwy5sbZDiNyX4mvdP32pqM
YMK4k7+5lRnVR2Fky/5uwyGSPbddNXaXzwEm+u4wIsJiaAN3OZgJpYIoCGik+9lG
5gVAIr0+/3rZ61IbeVE+vDenDd8g/m/YIdYBfC2IbzgS9EVGAf/gJdtDODXrDfQj
Fk2rQsvpftVOUs3Vpl9O+jeCQLoRbZYm0c5v7jP/L2lK0MjhiywPF2kpDeisMtnD
/ArkSPIlg1qVYm3F19v3pa6ZioM2hnwXg5DibYlgVvsIBGhvYqdQ1KosNVcVGGQa
HCUuVGdS7vHJYp3byH0vQYYygzxUJT2TqvK7pD57eYMN5drc7e19oyRQvbPQ3kkC
AwEAAaMhMB8wHQYDVR0OBBYEFAwwrnHlRgFvPGo+UD5zS1xAkC91MA0GCSqGSIb3
DQEBCwUAA4IBAQBBLhDRgezd/OOppuYEVNB9+XiJ9dNmcuHUhjNTnjiKQWVk/YDA
v+T2V3t9yl8L8o61tRIVKQ++lDhjlVmur/mbBN25/UNRpJllfpUH6oOaqvQAze4a
nRgyTnBwVBZkdJ0d1sivL9NZ4pKelJF3Ylw6rp0YMqV+cwkt/vRtzRJ31ZEeBhs7
vKh7F6BiGCHL5ZAwEUYe8O3akQwjgrMUcfuiFs4/sAeDMnmgN6Uq8DFEBXDpAxVN
sV/6Hockdfinx85RV2AUwJGfClcVcu4hMhOvKROpcH27xu9bBIeMuY0vvzP2VyOm
DoJeqU7qZjyCaUBkPimsz/1eRod6d4P5qxTj
-----END CERTIFICATE-----
EOF

Run the following command to verify the instance identity with OpenSSL.

openssl smime -verify -in signature -inform PEM -content document -certfile cert.cer -noverify > /dev/null

If the response is Verification successful, the instance is successfully authenticated.

The parameters in the command are described as follows:

document: The file that contains the retrieved identity document.
signature: The file that contains the retrieved identity signature.

Note
If you specified an audience parameter when you retrieved the instance identity signature, you must manually append the parameter to the end of the instance identity document. The format is ,"audience":"your_audience_value".

cert.cer: The file that contains the Alibaba Cloud public certificate.

Click to view the Alibaba Cloud public certificate

Examples

Without the audience parameter

This example shows how a software vendor can use an instance identity to authorize an application listed on Alibaba Cloud Marketplace.

Remotely connect to the Linux instance.

For more information, see Log on to a Linux instance using Workbench.
Run the following commands to retrieve the product-code and charge-type of the Marketplace image from the instance metadata. This step confirms that the current ECS instance uses an image from Alibaba Cloud Marketplace.

For more information about metadata, see Instance metadata.
```
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
```

Create a file named cert.cer and save the Alibaba Cloud public certificate to it.

cat <<EOF > cert.cer
-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEZmbRhzANBgkqhkiG9w0BAQsFADBsMRAwDgYDVQQGEwdV
bmtub3duMRAwDgYDVQQIEwdVbmtub3duMRAwDgYDVQQHEwdVbmtub3duMRAwDgYD
VQQKEwdVbmtub3duMRAwDgYDVQQLEwdVbmtub3duMRAwDgYDVQQDEwdVbmtub3du
MB4XDTE4MDIyMzAxMjkzOFoXDTM4MDIxODAxMjkzOFowbDEQMA4GA1UEBhMHVW5r
bm93bjEQMA4GA1UECBMHVW5rbm93bjEQMA4GA1UEBxMHVW5rbm93bjEQMA4GA1UE
ChMHVW5rbm93bjEQMA4GA1UECxMHVW5rbm93bjEQMA4GA1UEAxMHVW5rbm93bjCC
ASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAIJwy5sbZDiNyX4mvdP32pqM
YMK4k7+5lRnVR2Fky/5uwyGSPbddNXaXzwEm+u4wIsJiaAN3OZgJpYIoCGik+9lG
5gVAIr0+/3rZ61IbeVE+vDenDd8g/m/YIdYBfC2IbzgS9EVGAf/gJdtDODXrDfQj
Fk2rQsvpftVOUs3Vpl9O+jeCQLoRbZYm0c5v7jP/L2lK0MjhiywPF2kpDeisMtnD
/ArkSPIlg1qVYm3F19v3pa6ZioM2hnwXg5DibYlgVvsIBGhvYqdQ1KosNVcVGGQa
HCUuVGdS7vHJYp3byH0vQYYygzxUJT2TqvK7pD57eYMN5drc7e19oyRQvbPQ3kkC
AwEAAaMhMB8wHQYDVR0OBBYEFAwwrnHlRgFvPGo+UD5zS1xAkC91MA0GCSqGSIb3
DQEBCwUAA4IBAQBBLhDRgezd/OOppuYEVNB9+XiJ9dNmcuHUhjNTnjiKQWVk/YDA
v+T2V3t9yl8L8o61tRIVKQ++lDhjlVmur/mbBN25/UNRpJllfpUH6oOaqvQAze4a
nRgyTnBwVBZkdJ0d1sivL9NZ4pKelJF3Ylw6rp0YMqV+cwkt/vRtzRJ31ZEeBhs7
vKh7F6BiGCHL5ZAwEUYe8O3akQwjgrMUcfuiFs4/sAeDMnmgN6Uq8DFEBXDpAxVN
sV/6Hockdfinx85RV2AUwJGfClcVcu4hMhOvKROpcH27xu9bBIeMuY0vvzP2VyOm
DoJeqU7qZjyCaUBkPimsz/1eRod6d4P5qxTj
-----END CERTIFICATE-----
EOF

Verify the instance identity.

Example script:

#!/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

If the returned result is Verification successful, this means that the instance is successfully authenticated. You can then disable the permission control for the application software.

Example 2: Pass the Audience Parameter

This section provides another example of listing an image on the Alibaba Cloud Marketplace to demonstrate how you, as an application seller, can use an instance identity. To prevent the unauthorized use of a license, you can combine the instance identity with your custom audience parameter and implement policy control on your application server before you release permission controls.

Remotely connect to the Linux instance.

For more information, see Log on to a Linux instance using Workbench.
Run the following commands to retrieve the product-code and charge-type of the Marketplace image from the instance metadata. This step confirms that the current ECS instance uses an image from Alibaba Cloud Marketplace.

For more information about metadata, see Instance metadata.
```
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
```

Create a file named cert.cer and save the Alibaba Cloud public certificate to it.

cat <<EOF > cert.cer
-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEZmbRhzANBgkqhkiG9w0BAQsFADBsMRAwDgYDVQQGEwdV
bmtub3duMRAwDgYDVQQIEwdVbmtub3duMRAwDgYDVQQHEwdVbmtub3duMRAwDgYD
VQQKEwdVbmtub3duMRAwDgYDVQQLEwdVbmtub3duMRAwDgYDVQQDEwdVbmtub3du
MB4XDTE4MDIyMzAxMjkzOFoXDTM4MDIxODAxMjkzOFowbDEQMA4GA1UEBhMHVW5r
bm93bjEQMA4GA1UECBMHVW5rbm93bjEQMA4GA1UEBxMHVW5rbm93bjEQMA4GA1UE
ChMHVW5rbm93bjEQMA4GA1UECxMHVW5rbm93bjEQMA4GA1UEAxMHVW5rbm93bjCC
ASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAIJwy5sbZDiNyX4mvdP32pqM
YMK4k7+5lRnVR2Fky/5uwyGSPbddNXaXzwEm+u4wIsJiaAN3OZgJpYIoCGik+9lG
5gVAIr0+/3rZ61IbeVE+vDenDd8g/m/YIdYBfC2IbzgS9EVGAf/gJdtDODXrDfQj
Fk2rQsvpftVOUs3Vpl9O+jeCQLoRbZYm0c5v7jP/L2lK0MjhiywPF2kpDeisMtnD
/ArkSPIlg1qVYm3F19v3pa6ZioM2hnwXg5DibYlgVvsIBGhvYqdQ1KosNVcVGGQa
HCUuVGdS7vHJYp3byH0vQYYygzxUJT2TqvK7pD57eYMN5drc7e19oyRQvbPQ3kkC
AwEAAaMhMB8wHQYDVR0OBBYEFAwwrnHlRgFvPGo+UD5zS1xAkC91MA0GCSqGSIb3
DQEBCwUAA4IBAQBBLhDRgezd/OOppuYEVNB9+XiJ9dNmcuHUhjNTnjiKQWVk/YDA
v+T2V3t9yl8L8o61tRIVKQ++lDhjlVmur/mbBN25/UNRpJllfpUH6oOaqvQAze4a
nRgyTnBwVBZkdJ0d1sivL9NZ4pKelJF3Ylw6rp0YMqV+cwkt/vRtzRJ31ZEeBhs7
vKh7F6BiGCHL5ZAwEUYe8O3akQwjgrMUcfuiFs4/sAeDMnmgN6Uq8DFEBXDpAxVN
sV/6Hockdfinx85RV2AUwJGfClcVcu4hMhOvKROpcH27xu9bBIeMuY0vvzP2VyOm
DoJeqU7qZjyCaUBkPimsz/1eRod6d4P5qxTj
-----END CERTIFICATE-----
EOF

Verify the instance identity.

Example script:

#!/usr/bin/bash
function verify_signature_with_specified_audience(){
audience='your audience' # Replace this with your audience value.
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

If the returned result is Verification successful, this indicates that the instance authentication is successful. Lift the permission controls for the application.

References

To retrieve other instance information from within an instance, see Instance metadata.
To automatically run scripts at instance startup using user data, see custom instance initialization.