All Products
Search

This Product

    Elastic Compute Service:Use instance identities

    Document Center

    Elastic Compute Service:Use instance identities

    Last Updated:Mar 29, 2024

    An instance identity consists of an instance identity document and an instance identity signature. Instance identities are used to rapidly identify and distinguish among Elastic Compute Service (ECS) instances. The instance identities provide a trust basis for managing permissions on applications and activating software. This topic describes the definition and scenarios of instance identities and how to obtain and use instance identities.

    Instance identities

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

    • Instance identity document

      An instance identity document contains the identity information of an instance. The following table describes the items that are contained in the instance identity document.

      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

      An instance identity signature is used by third parties to validate the authenticity and content of the instance identity document. An instance identity signature is a secure and 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 the audience parameter can be a random string, a timestamp, regularly changing information, or data generated by an algorithm. After the audience parameter is configured, spoofers cannot obtain the value of the audience parameter even if they have obtained some information about the identity document and signature. The audience parameter is used to perform authentication. For more information, see the Use instance identities section of this topic.

    Scenarios

    In the following scenarios, you can use instance identities for authentication, authorization, or runtime environment identification.

    • In most cases, 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.

    • When you write sensitive data to an ECS 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 in which you want to confirm the source of an instance.

    Obtain the instance identity document or signature

    (Recommended) Obtain the instance identity document or signature in security hardening mode

    • Linux instance

      # Obtain server access credentials. Set a validity period for the credentials and make sure that the request to create a token does 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:<Validity period of the server access credentials>"'
# Obtain the instance identity.
curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/<dynamic data>

    • Windows instance

      # Obtain server access credentials. Set a validity period for the credentials and make sure that the request to create a token does not include the X-Forwarded-For header.
$token=Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token-ttl-seconds" = "<Validity period of the server access credentials>"} -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>

      • <Validity period of the server access credentials>: Access credentials are used for authentication to enhance data security. Valid values: 1 to 21600. Unit: seconds.

        • During the validity period, you can repeatedly run the preceding command to obtain the instance identity. After the validity period ends, you must obtain new credentials before you request the instance identity.

        • The access credentials apply to only a single instance. If you copy the credentials to obtain the identity of another instance, instance acccess is denied.

      • <dynamic data>: Replace the value of the parameter with one of the following values:

        • dynamic/instance-identity/document: specifies an instance identification document.

        • dynamic/instance-identity/pkcs7?audience=XXXX: specifies an instance identity signature.

          Important

          The ?audience=XXXX parameter is optional. For more information, see the Instance identity signature section of this topic.

    Obtain the instance identity document or signature in 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 the value of the parameter with one of the following values:

      • dynamic/instance-identity/document: specifies an instance identification document.

      • dynamic/instance-identity/pkcs7?audience=XXXX: specifies an instance identity signature.

        Important

        The ?audience=XXXX parameter is optional. For more information, see the Instance identity signature section of this topic.

    Use instance identities

    Procedure

    This section describes how to use an instance identity in security hardening mode. In this example, a Linux instance that runs Alibaba Cloud Linux 3 is used.

    Important

    OpenSSL is required to validate and use instance identities to ensure security. If you did not configure OpenSSL, visit the OpenSSL official website to download and install OpenSSL.

    1. Connect to the Linux instance.

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

    2. Run the following commands to obtain the instance identity document and signature: 

      # Obtain server access credentials. Set the validity period 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

    3. Run the following command to use the OpenSSL service to validate the instance identity: 

      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 instance identity signature, add the parameter in the "audience":"<Value of audience>" format to the end of the instance identity document. You can add multiple audience parameters. Separate the parameters with commas (,).

      • AliyunPubkey: Set this parameter to the Alibaba Cloud public certificate.

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

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

    1. Connect to the Linux instance.

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

    2. Run the following commands to use the metadata service to obtain the product code (product-code) and billing method (charge-type) of the Alibaba Cloud Marketplace image and check whether the image used by the ECS instance comes from Alibaba Cloud Marketplace.

      For more information, see Obtain 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.

      Sample 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 demonstrates how to use the identity of an instance that uses an Alibaba Cloud Marketplace image as an application software vendor. You can specify the audience parameter to identify the instance and implement policy control on the application servers to allow authenticated users to use software. This can protect the license codes against unauthorized use.

    1. Connect to the Linux instance.

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

    2. Run the following commands to use the metadata service to obtain the product code (product-code) and billing method (charge-type) of the Alibaba Cloud Marketplace image and check whether the image used by the ECS instance comes from Alibaba Cloud Marketplace.

      For more information, see Obtain 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.

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

    References

    For information about how to obtain instance information from instance metadata, see Obtain instance metadata.