All Products
Search
Document Center

Elastic Compute Service:Use instance identities

Last Updated:Sep 08, 2023

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

Background information

Instance identities

Instance identities are part of instance metadata that can be used to identify and differentiate instances and provide a basis for managing permissions on applications and activating software. Instance identities are generated in real time and dynamically change with instance information. For more information, see Overview of ECS instance metadata.

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

  • Instance identity document

    The instance identity document includes instance information that is described in the following table.

    Item

    Description

    account-id

    The ID of the Alibaba Cloud account to which the instance belongs.

    instance-id

    The instance ID.

    mac

    The media access control (MAC) address of the primary elastic network interface (ENI) of the instance.

    region-id

    The region ID of the instance.

    serial-number

    The serial number of the instance.

    zone-id

    The zone ID of the instance.

    instance-type

    The instance type.

    image-id

    The ID of the image used by the instance.

    private-ip

    The private IP address of the instance.

  • Instance identity signature

    The instance identity signature is a secure, reliable digital signature that is encrypted by using the PKCS #7 standard.

    You can specify the audience parameter in an instance identity signature to prevent the signature from being spoofed. The value of audience can be a random string, a timestamp, regularly changing data, or data generated by a specific algorithm. After you specify the audience parameter in an instance identity signature, it is difficult for others to guess the value of audience even if they obtain information about the instance identity document and instance identity signature. You can use the audience parameter for authentication. For more information, see Example 2: Use instance identities with the audience parameter specified.

Scenarios

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

  • Traditionally, each piece of software off the cloud is activated by using a single license code. This practice is not suitable for cloud-based software that 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 Use instance identities.

  • When you write sensitive data to an instance, you can use the instance identity 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.

Configure instance identities

This section describes how to configure instance identities. In this example, an instance that runs CentOS 7.4 is used.

Note

OpenSSL is required to validate and use instance identities to ensure security. If you have not configured OpenSSL, go to the OpenSSL official website to download and install OpenSSL.

  1. Connect to a Linux instance.

    For more information, see Connect to a Linux instance by using a password or key.

  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:

    • Run the following command without the audience parameter:

      curl http://100.100.100.200/latest/dynamic/instance-identity/pkcs7
    • Run the following command with the audience parameter:

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

      In the preceding command, replace XXXX with an actual value. Example: audience=test.

  4. Run the following command to validate the instance identity by using OpenSSL:

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

    Take note of the following parameters in the preceding command:

    • $signature: Set this parameter to the instance identity signature that you obtained.

    • $DOCUMENT: Set this parameter to the instance identity document that you obtained.

      Note

      If you specified the audience parameter in the previous step, add the parameter in the "audience":"<Value of audience>" format to the end of the instance identity document. You can add multiple audience parameters and separate the parameters with commas (,).

    • AliyunPubkey: Set this parameter to 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-----

Use instance identities

Example 1: Use instance identities without specifying the audience parameter

This example demonstrates how to use the identity of an instance that uses an Alibaba Cloud Marketplace image as an application software seller.

  1. Connect to a Linux instance.

    For more information, see Connect to a Linux instance by using a password or key.

  2. Run the following commands to check whether the image used by the instance is from Alibaba Cloud Marketplace.

    You can check the product-code and charge-type items in the metadata of the instance. The product-code item indicates the product code of the Alibaba Cloud Marketplace image. 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. Validate 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
  5. If Verification successful is returned, the instance identity is validated and you have the permissions to manage application software.

Example 2: Use instance identities with the audience parameter specified

This example also demonstrates how to use the identity of an instance that uses an Alibaba Cloud Marketplace image as an application software seller. You can specify the audience parameter to identify the instance and implement policy control at the application server to allow authenticated users to use software. This can protect the license codes against unauthorized use.

  1. Connect to a Linux instance.

    For more information, see Connect to a Linux instance by using a password or key.

  2. Run the following commands to check whether the image used by the instance is from Alibaba Cloud Marketplace.

    You can check the product-code and charge-type items in the metadata of the instance. The product-code item indicates the product code of the Alibaba Cloud Marketplace image. 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. Validate the instance identity.

    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, the instance identity is validated and you have the permissions to manage application software.