Instance identity is a part of Metadata that describes and validates an instance. Instance identity enables you quickly locate a target instance, 

and provides authentication for such actions as software updates, access control, or application activation. The signature of instance identity is encrypted by the PKCS#7 standard. 

Use cases

You can use instance identity (instance-identity) in scenarios such as authentication, granting access, or instance identification, as follows.

  • A typical software activation (with one serial number for one device) does not work in the environment of cloud computing where the sales model of the Alibaba Cloud Marketplace is flexible. In this case, you can use instance identity to complete the software activation. For more information, see the Sample 1. No audience in the signature.

  • When you write sensitive data in the instance, you can use instance identity to verify that the server is your instance.

  • Scenarios whereby you want to confirm the source of the target server.

Feature details

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

  • Instance identity document: Describes the attributes of an instance.  The following table lists instance identity document items.

    Properties Description Can it be changed?
    account-id ID of the Alibaba Cloud account to which the instance belongs No
    create-time Instance creation time No
    instance-id Instance ID. No
    mac MAC address of the instance primary network interface No
    region-id ID of the region to which the instance belongs No
    serial-number Serial number of the instance  No
    zone-id ID of the zone to which the instance belongs No
    instance-type Instance types Yes. It changes after you change the instance type.
    image-id Image ID of the instance Yes. It changes after you replace the system disk of the instance.
    private-ip Private IP of the instance Yes. It changes after you change the private IP of a VPC-Connected instance.
  • Instance identity signature: Verifies the instance identity in the cryptographic method of the PKCS#7 standard.

    • To enhance the security of the signature, you can protect it by specifying the audience parameter in it. However, even if you specify audience, another user may get information about the identity document and the identity signature. Therefore, we recommend the value of the audience parameter  is a random string, timestamp, regularly changed data, or some output generated by a specific algorithm.

    • If you specify the audience parameter,  you must modify the instance identity document and signature simultaneously. For example, if you have specified the  audience parameter while obtaining the signature, before you verify the signature by using the OpenSSL commands,  you must add the value of the audience  parameter at the end of the dynamically obtained instance identity document in the format of  "audience":"Value of the audience", and separate the parameters with a comma (,).

Usage

The instance identity is verified by using the OpenSSL commands. Make sure that you have the OpenSSL configured in your instance. Visit https://www.openssl.org/source to download and update OpenSSL service.

Take CentOS 7.4 as an example to use the instance identity.

  1. Connect to your Linux instance.
  2. Run curl http://100.100.100.200/latest/dynamic/instance-identity/document to query the file of instance identity document.
  3. Run curl http://100.100.100.200/latest/dynamic/instance-identity/pkcs7 or curl http://100.100.100.200/latest/dynamic/instance-identity/pkcs7?audience=XXXX to get the instance identity signature.


  4. Verify the instance identity by using OpenSSL.
    openssl smime -verify -in $signature -inform PEM -content $DOCUMENT -certfile AliyunPubkey -noverify > /dev/null
    Note
    • Specify the variable $signature with the responded instance identity signature.
    • Specify the variable $DOCUMENT with the responded instance identity document.

      (Optional) In step 3, if you have specified the audience parameter, add the value of the audience parameter at the end of the dynamically obtained instance identity document in the format of  "audience":"Value of the audience", and separate the parameters with a comma (,).

    • Specify the variable AliyunPubkey with the Alibaba Cloud public certificate.

The public certificate of Alibaba Cloud in all regions is as follows.


-----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-----

Sample 1. No audience in the signature

Assume that you have published an image in the image market. The following example shows you how to grant access to the instances of your customers.

  1. Connect to the target instance.
  2. Verify whether the image used by the instance is from the Alibaba Cloud Marketplace, or from another source, by calling the metadata items of product-code and charge-type For more information, see  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 cert.cer in the working directory and save the public certificate to the file.
  4. Determine the identity of the instance by running the following 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. Once the response result shows Verification successful, remove the restriction and run the image in the instance.

Sample 2. Audience in the signature

Assume that you published an image in the image market. The following example shows you how to grant access to the instances  of your customers by specifying an audience  parameter during the process of validation. To make sure that the instance identity is not maliciously acquired and used, you can implement the access control at the application server by combining your audience parameter.  We recommend the value of the  audience parameter is a random string, timestamp, regularly changed data, or some output generated by a specific algorithm.

  1. Connect to the target instance.
  2. Verify whether the image used by the instance is from the Alibaba Cloud Marketplace, or another source, by calling the metadata items of product-code and 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
  3. Create a temporary file cert.cer in the working directory and save the public certificate to the file.
  4. Determine the identity of the instance by running the following script.
    
    #! /usr/bin/bash
    function verify_signature_with_specified_audience(){
    audience=‘your audience’ #Here is your 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. Once the response result shows Verification successful, remove the restriction and run the image in the instance.