Aspera on Cloud transfer service access keys are required to authenticate transfers to and from the cloud storage.

If you want to create and manage transfer service access keys programatically, without using the Aspera on Cloud UI, you can use the ATS API (except for Google Cloud Storage; access keys must be created in the AoC UI).

  1. Create an ATS API key if you do not already have one. For instructions, see Creating ATS API Keys.

  2. Retrieve your transfer service server ID and, for IBM Cloud, your authentication endpoint.

    Use curl or your browser to view a list of servers for your storage type and record the ID for the server in your region:

    If you know your region, you can limit the list by appending the region to the URL. For example: https://ats.aspera.io/pub/v1/servers/AWS/us-east-1.

    For example, the output for AWS us-east-1 shows that “id” is “6e2c5cc5-6641-4c68-a225-d0f370610d7d”:

    {
      "cloud" : "AWS",
      "id" : "6e2c5cc5-6641-4c68-a225-d0f370610d7d",
      "public_ips" : [ "54.89.55.209/32", "54.89.6.198/32", "34.193.71.58/32", "34.193.90.82/32", "34.193.86.227/32", "34.193.88.211/32", "34.193.1.216/32", "34.193.90.139/32", "34.193.75.213/32", "34.193.89.251/32", "34.192.238.97/32", "34.193.86.219/32", "34.193.47.122/32", "34.192.0.42/32", "34.193.89.217/32", "34.192.240.159/32" ],
      "region" : "us-east-1",
      "tcp_port" : 33001,
      "transfer_setup_url" : "https://ats-aws-us-east-1.aspera.io:443",
      "udp_port" : 33001
    }
  3. For AWS S3 storage, create an IAM policy and IAM role as described in Creating Access Keys Using AWS IAM Roles. Creating an access key that uses AWS access keys is supported but not recommended by Aspera; if you use AWS access keys you can skip this step.
  4. For AWS S3 storage, create a trust relationship policy and add it to the IAM role. Creating an access key that uses AWS access keys is supported but not recommended by Aspera; if you use AWS access keys you can skip this step.
    1. Create the trust relationship by running the following command:
      # curl -u api_key_id:api_key_secret -X GET https://ats.aspera.io/pub/v1/aws/trustpolicy"region=aws_region

      Specifying a region is optional. If no region is specified, the default of us-east-1 is used. The output is the trust policy and is similar to the following:

      200
      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Principal": {
              "AWS": "arn:aws:iam::39502375428:role/atp-aws-us-east-1-ts-atc-node"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
              "StringLike": {
                "sts:ExternalId": "6145nwef-905-4da3-9a5c-8fwet34204:t2348534n5"
              }
            }
          }
        ]
      }
    2. Copy the trust policy. In the AWS Console, open the ats-s3-access-keys role and paste the policy in the trust relationships.
  5. Create a JSON file that contains the access key specifications and transfer server ID. The JSON file requires different values depending on the storage type and, for AWS S3, the authentication method. Enter “/” for the path to allow transfers to the top directory.

    AWS S3 – IAM Role Authentication (Recommended)

    {
      "storage": {
         "type": "aws_s3",
         "endpoint" : "s3.amazonaws.com",
         "bucket":"bucket",
         "path": "/path",
         "storage_class": "STANDARD|REDUCED_REDUNDANCY|INFREQUENT_ACCESS",
         "server_side_encryption" : "AES256|AWS_KMS",
         "server_side_encryption_aws_kms_key_id" = "arn_encryption",
         "credentials": {
           "type": "assume-role",
           "assume_role_arn": "iam_role_arn",
           "assume_role_external_id": "external_id"
         }
       },
       "transfer_server_id": "server_id",
    }

    Usage notes:

    • You do not need to specify storage class for standard storage (the default).
    • Server-side encryption should match the policy of your storage. If no server-side encryption is specified for the storage, you do not need to specify this setting. If server side encryption is set to “AWS_KMS”, then “server_side_encryption_aws_kms_key_id” is required and is set to the ARN of the encryption key (for example “arn:aws:kms:us-east-1:648543846928:key/er23525-8754-84g4-8sf7-4834ngigfre45”).

    AWS S3 – AWS Access Key Authentication

    Note: The following example uses an AWS access key to authenticate to your object storage. Aspera strongly recommends using AWS IAM role authentication in your ATS access keys.

    {
     "storage" : {
         "type" : "aws_s3",
         "endpoint" : "s3.amazonaws.com",
         "bucket" : "bucket",     
         "path" : "/path",
         "storage_class" : "STANDARD|REDUCED_REDUNDANCY|INFREQUENT_ACCESS",
         "server_side_encryption" : "AES256|AWS_KMS",
         "server_side_encryption_aws_kms_key_id" = "arn_encryption",
         "credentials" : {
              "type" : "key",
              "access_key_id" : "aws_access_key",
              "secret_access_key" : "secret_access_key"
         }
    },
    "transfer_server_id": "server_id" 
    }

    Usage notes:

    • You do not need to specify storage class for standard storage (the default).
    • Server-side encryption should match the policy of your storage. If no server-side encryption is specified for the storage, you do not need to specify this setting. If server side encryption is set to “AWS_KMS”, then “server_side_encryption_aws_kms_key_id” is required and is set to the ARN of the encryption key (for example “arn:aws:kms:us-east-1:648543846928:key/er23525-8754-84g4-8sf7-4834ngigfre45”).

    Azure (Block and Page Storage)

    { 
    "storage" : {
         "type" : "azure",
         "api" : "BLOCK|PAGE"
         "container" : "container",
         "path" : "path",
         "credentials" : {
             "storage_endpoint" : "blob.core.windows.net",
             "type": "key",
             "account" : "account_name",
             "key" : "storage_access_key"
         }
     },   
    "transfer_server_id": "server_id" 
    }

    Azure SAS

    { 
    "storage" : {
         "type" : "azure_sas",
         "container" : "container",
         "path" : "path",
         "api": "BLOCK|PAGE",
         "credentials" : {
             "shared_access_signature" : "shared_url"
         } 
    },   
    "transfer_server_id": "server_id" 
    }

    Azure Files

    { 
    "storage" : {
         "type" : "azure-files",
         "path" : "path",
         "credentials" : {
             "file_service_endpoint" : "https://account.file.core.windows.net/",
             "password" : "password"
         } 
    },   
    "transfer_server_id": "server_id" 
    }

    Google Cloud Storage

    Google access keys must be created in the Aspera on Cloud GUI.

    IBM Cloud Object Storage (COS) – S3

    { 
    "storage" : {
         "type" : "ibm-s3",
         "bucket" : "bucket",
         "path" : "path",
         "endpoint" : "s3_auth_endpoint",
         "credentials" : { 
            "access_key_id" : "key_id",
     	"secret_access_key" : "key_secret"   
            }
    },   
    "transfer_server_id": "server_id" 
    }

    IBM Cloud Object Storage (COS) – Swift

    { 
    "storage" : {
         "type" : "ibm-swift",
         "container" : "container",
         "path" : "path",
         "credentials": {         
                "type" : "v1",
                "authentication_endpoint" : "swift_auth_endpoint",
                "username" : "username",
                "api_key" : "api_key"
         }
     },   
    "transfer_server_id": "server_id" 
    }
  6. Configure optional transfer and server settings in your access key configuration by adding a “configuration” object at the same level as “storage”.
    {
    "storage" : {},
    "configuration" : {
            "transfer" : {
                "cipher" : "cipher",
                "policy" : "policy",
                "target_rate_kbps" : target_rate,
                "target_rate_cap_kbps" : target_rate_cap,
                "content_protection_secret" : "secret",
                "preserve_timestamps" : true|false,
                "aggressiveness" : "aggressiveness",
            },
            "server" : {
                "activity_event_logging" : true|false,
                "recursive_counts" : true|false,
                "aej_logging" : true|false
            }
        },
    "transfer_server_id": "server_id" 
    }
    Element Type Description
    transfer JSON object The transfer configuration object.
    cipher String The minimum cipher allowed by the server for transfers that are authorized by this access key. Aspera supports three sizes of AES cipher keys (128, 192, and 256 bits) and supports two encryption modes, cipher feedback mode (CFB) and Galois/counter mode (GCM). The GCM mode encrypts data faster and increases transfer speeds compared to the CFB mode, but the client must support it.

    By default, AoC transfer service nodes are set to “any”, and the access key cipher is unset. In this case, transfers that are authorized by the access key can request any encryption cipher (or no encryption).

    If you choose to set a cipher in the access key, understand the following rules and their implications for clients.

    Note: To ensure client compatibility when requiring encryption, use a cipher with the form aes-XXX, which is supported by all clients and servers. Requiring GCM causes the server to reject transfers from clients that are running a version of Ascp 3.8.1 or older. For more information about how the server and client negotiate the transfer cipher, see the description of -c in the Ascp reference in the HST Server 3.9.0 Admin Guide.

    Cipher Rules

    • When the transfer requests a cipher key that is shorter than the cipher key that is configured in the access key, the tranfer is automatically upgraded to the access key setting. For example, when the access key setting is AES-192 and the transfer requests AES-128, the transfer is run with AES-192.
    • When the access key requires GCM, the transfer must use GCM (requires client version 3.9.0 or newer) or the transfer fails.
    • When the access key setting is empty, the transfer can use any encryption cipher.
    • When the access key setting is “none”, the transfer must use “none”. Transfer requests that specify an encryption cipher fail.

    Cipher Values

    Cipher Value Description Support
    aes-128
    aes-192
    aes-256
    Use the CFB or GCM mode depending on the client version and cipher requested. All client versions.
    aes-128-cfb
    aes-192-cfb
    aes-256-cfb
    Use the CFB encryption mode. Clients version 3.9.0 and newer.
    aes-128-gcm
    aes-192-gcm
    aes-256-gcm
    Use the GCM encryption mode. Clients version 3.9.0 and newer.
    none Require unencrypted transfers (not recommended). All client versions.
    policy String The policy allowed for transfers that are authorized by this access key. Value can be highregularfairlowtrickle, or fixed. Aspera recommends against setting the policy to fixed, which can result in the transfer rate exceeding network or storage capacity if the client also requests a high minimum transfer rate that is not capped by the server. This can decrease transfer performance and cause problems on the target storage. To avoid these problems, set the allowed policy to fair.
    target_rate_kbps Integer The default initial rate for transfers that are authorized by this access key, in kilobits per second.
    target_rate_cap_kbps Integer The maximum target rate for transfers that are authorized by this access key, in kilobits per second.
    content_protection_secret   String Provide a password to require that content be encrypted by the client (enforce client-side encryption-at-rest) for transfers that are authorized by this access key.
    preserve_timestamps Boolean   Set to true to preserve file access and modification timestamps for transfers that are authorized by this access key. The server configuration overrides the access key configuration. Timestamp support in object storage varies by provider; consult your object storage documentation to determine which settings are supported. Default is false.
    aggressiveness Float The aggressiveness of transfers that are authorized by this access key in claiming available bandwidth. Value can be 0.00-1.00.
    server JSON object The server configuration object.
    activity_event_logging Boolean Set to true to allow the Node API to query transfers that are associated with this access key through the /events endpoint. The access key configuration overrides the server configuration and must be enabled for event reporting to Aspera on Cloud. Default is false.
    recursive_counts Boolean Set to true to enable recursive counts. This option must be enabled for event reporting to Aspera on Cloud. Default is false.
    aej_logging Boolean Set to true to enable reporting to the IBM Aspera on Cloud Activity app. The access key configuration overrides the server configuration. Default is unset, such that the access key inherits the setting on the server.
  7. Create a Aspera on Cloud transfer service access key by running the following command:

    curl -i -u api_key_id:api_secret -H "Content-type: application/json" -X POST https://ats.aspera.io/pub/v1/access_keys -d@ak_config.json

    Where ak_config.json is the text file containing the access key configuration.

  8. Use the access key to transfer to and from your cloud storage.

You can manage transfer service access keys by using the API; for instructions, see Managing Access Keys with the ATS API.