This topic describes instance identities and how to use instance identities. This topic also provides examples on how to use instance identities with custom parameters specified and unspecified.

Background information

Instance identities are part of the metadata of instances and can be used to identify and differentiate instances. They provide an important trust foundation to control application permissions and activate software. Instance identities are generated in real time and dynamically change with instances.

Each instance identity consists of an instance identity document (document) and an instance identity signature (signature).

The instance identity document is used to describe information of an instance and contains instance properties described in the following table.

Property Description Changeable
account-id The ID of the Alibaba Cloud account to which the instance belongs. No
instance-id The ID of the instance. No
mac The media access control (MAC) address of the primary elastic network interface (ENI) of the instance. No
region-id The ID of the region where the instance resides. No
serial-number The serial number of the instance. No
zone-id The ID of the zone where the instance resides. No
instance-type The instance type. Yes. This property changes when the instance type of the instance is changed.

For more information, see Overview of instance upgrade and downgrade.

image-id The ID of the image used by the instance. Yes. This property changes when the system disk of the instance is replaced.

For more information, see Replace the system disk (public images).

private-ip The private IP address of the instance. Yes. This property changes when the private IP address of the instance in a virtual private cloud (VPC) is changed.

For more information, see Modify a private IP address.

The instance identity signature is encrypted by using the PKCS #7 standard and is secure and reliable.

You can specify the audience parameter in the instance identity signature. The value of the audience parameter can be a random string, a timestamp, regularly changing data, or data generated by a specific algorithm. After the audience parameter is specified, it is difficult for other users to guess the value of the audience parameter even if they have obtained information about the identity document and the identity signature. This effectively prevents fraudulent use of signatures.

If you specify the audience parameter, you must simultaneously set the instance identity document and signature. For example, if you specify the audience parameter when you obtain the identity signature, you must add the audience value to the end of the dynamically obtained instance identity document in the following format before you verify the signature by using OpenSSL: "audience":"Value of audience". Separate multiple values with commas (,).

In the following scenarios, you can use instance identities (instance-identity) for authentication, authorization, or identifying runtime environment.

  • Software is traditionally activated by using a single serial number for a single device. This practice is not suitable for using software on the cloud because software is used at varying points in time and in different scenarios. You can use instance identities for user authorization when you publish application software in Alibaba Cloud Marketplace. For more information, see Example 1: Use instance identities without specifying the audience parameter.
  • When you write sensitive data to an instance, you can use instance identities to ensure that you are writing the sensitive data to the exact instance that you want to use.
  • Scenarios where you want to confirm the source of the instance.

Use instance identities

OpenSSL is required if you want to use instance identities. If you do not have OpenSSL configured in your instance, you must go to the OpenSSL official website to download and install OpenSSL. The following example demonstrates how to use instance identities on a Linux instance that runs CentOS 7.4.

  1. Connect to the Linux instance.
  2. Run the following command to obtain the instance identity document: 
    curl http://100.100.100.200/latest/dynamic/instance-identity/document
  3. Use one of the following methods to obtain the instance identity signature:
    • Do not specify the audience parameter: 
      curl http://100.100.100.200/latest/dynamic/instance-identity/pkcs7
    • Specify the audience parameter: 
      curl http://100.100.100.200/latest/dynamic/instance-identity/pkcs7?audience=XXXX
  4. Verify the instance identity by using OpenSSL. 
    openssl smime -verify -in $signature -inform PEM -content $DOCUMENT -certfile AliyunPubkey -noverify > /dev/null
    The following section describes the parameters in the preceding command:
    • $signature specifies the identity signature that you obtained.
    • $DOCUMENT specifies the identity document that you obtained.

      (Optional) If you specified the audience parameter in Step 3, you must add the audience value to the end of the dynamically obtained instance identity document in the following format: "audience":"Value of audience". Separate multiple values with commas (,).

    • AliyunPubkey specifies the Alibaba Cloud public certificate.
    The following code demonstrates the Alibaba Cloud public certificate: 
    -----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-----

Example 1: Use instance identities without specifying the audience parameter

The following example demonstrates how to use instance identities as an application software seller if an image is published to Alibaba Cloud Marketplace.

  1. Connect to the instance.
  2. Verify whether the image used by the instance is from Alibaba Cloud Marketplace.

    You can check the product-code and charge-type items in the instance metadata. The product-code item indicates the product code of the Alibaba Cloud Marketplace image, and the charge-type item indicates the billing method of the Alibaba Cloud Marketplace image. For more information, see Overview of ECS 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
  3. Create a temporary file named cert.cer in the current directory and save the Alibaba Cloud public certificate to the file.
  4. Identify the instance.
    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
  5. If Verification successful is returned, you have permissions to use the application software.

Example 2: Use instance identities while specifying the audience parameter

The following example demonstrates how to use instance identities as an application software seller if an image is published to Alibaba Cloud Marketplace. You can specify the audience parameter to identify the instance and implement policy control at the application server to allow authenticated users to use the software. This can protect the authorization code (license) against unauthorized use. The value of the audience parameter can be a random string, a timestamp, regularly changing data, or data generated by a specific algorithm.

  1. Connect to the instance.
  2. Verify whether the image used by the instance is from Alibaba Cloud Marketplace.

    You can check the product-code and charge-type items in the instance metadata. The product-code item indicates the product code of the Alibaba Cloud Marketplace image, and the charge-type item indicates the billing method of the Alibaba Cloud Marketplace image. 

    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
  3. Create a temporary file named cert.cer in the current directory and save the Alibaba Cloud public certificate to the file.
  4. Identify the instance.
    Example script: 
    #!/usr/bin/bash
function verify_signature_with_specified_audience(){
audience=‘your audience’ # Specify the audience parameter.
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
  5. If Verification successful is returned, you have permissions to use the application software.