# AWS Transfer Family for AS2 Applicability Statement 2 (AS2) is an RFC-defined file-transmission specification that includes strong message protection and verification mechanisms. Protecting an AS2 payload in transit uses Cryptographic Message Syntax (CMS) with encryption and digital signatures to provide data protection and peer authentication. A signed Message Disposition Notice (MDN) response payload provides verification (non-repudiation) that a message was received and successfully decrypted. The AS2 protocol is critical for workflows with compliance requirements that rely on having data protection and security features built into the protocol. AWS Transfer Family AS2 endpoints are [Drummond certified](https://aws.amazon.com/about-aws/whats-new/2023/06/aws-transfer-family-drummond-group-as2-certification/), enabling customers in industries such as retail, life sciences, manufacturing, financial services, and utilities to securely transact with their business partners. When you use AS2 with Transfer Family, the transacted data is natively accessible in AWS for: + Processing, analysis, and machine learning + Integration with enterprise resource planning (ERP) systems + Integration with customer relationship management (CRM) systems To exchange files with a partner who has an AS2-enabled server, you must: + Generate a public-private key pair for encryption + Generate a public-private key pair for signing + Exchange the public keys with your partner **Important** HTTPS AS2 server endpoints are not currently supported. You are responsible for TLS termination. Transfer Family provides a workshop that you can attend, in which you can configure a Transfer Family endpoint with AS2 enabled, and a Transfer Family AS2 connector. You can view the details for this workshop [here](https://catalog.workshops.aws/transfer-family-as2/en-US). For step-by-step instructions to configure AS2 in Transfer Family, see the following: 1. [Import AS2 certificates](managing-as2-partners.md#configure-as2-certificate) 1. [Create AS2 profiles](configure-as2-profile.md) 1. [Create an AS2 server](create-as2-transfer-server.md) 1. [Create an AS2 agreement](create-as2-transfer-server.md#as2-agreements) 1. [Configure AS2 connectors](configure-as2-connector.md) For a complete example, see [Setting up an AS2 configuration](as2-example-tutorial.md). **Note** To show support for AS2 Terraform templates, add a thumbs up reaction (👍) to the [Transfer Family Terraform templates feature request](https://github.com/aws-ia/terraform-aws-transfer-family/issues/62#issue-3364703944). You can also add a comment describing your use case. ## AS2 use cases If you are an AWS Transfer Family customer who wants to exchange files with a partner who has an AS2-enabled server, the most complex part of the setup involves generating one public-private key pair for encryption and another for signing and exchanging the public keys with the partner. ![\[Diagram that shows the use of public-private key pairs for encryption and signing.\]](http://docs.aws.amazon.com/transfer/latest/userguide/images/as2-architecture-high-level.png) Consider the following variations for using AWS Transfer Family with AS2. **Note** *Trading partner* is the partner associated with that partner profile. All mentions of *MDN* in the following table assume *signed* MDNs. **AS2 use cases** | | | --- | | Inbound-only use cases [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/transfer/latest/userguide/as2-for-transfer-family.html) | | Outbound-only use cases [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/transfer/latest/userguide/as2-for-transfer-family.html) | | Inbound and outbound use cases [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/transfer/latest/userguide/as2-for-transfer-family.html) | ## AS2 CloudFormation templates This topic provides information about AWS CloudFormation templates that you can use to quickly deploy AS2 servers and configurations for AWS Transfer Family. These templates automate the setup process and help you implement best practices for AS2 file transfers. + The basic AS2 template is described in [Use a template to create a demo Transfer Family AS2 stack](create-as2-transfer-server.md#as2-cfn-demo-template) + The AS2 template for customizing HTTP headers is described in [Customize HTTP headers for AS2 messages](as2-custom-http-headers.md). ### Customizing AS2 templates You can customize the provided templates to meet your specific requirements: 1. Download the template from the S3 URL. 1. Modify the YAML code to adjust configurations such as: + Security settings and certificate configurations + Network architecture and VPC settings + Storage options and file handling + Monitoring and notification preferences 1. Upload your modified template to your own S3 bucket. 1. Deploy the customized template using the CloudFormation console or AWS CLI. **Important** When customizing templates, ensure that you maintain the dependencies between resources and follow security best practices. ### Testing your AS2 deployment After deploying an AS2 server using a template, you can test the configuration: 1. Check the CloudFormation stack outputs for sample commands and endpoint information. 1. Use the AWS CLI to send a test file: ``` aws s3api put-object --bucket your-bucket-name --key test.txt --body test.txt aws transfer start-file-transfer --connector-id your-connector-id --send-file-paths /your-bucket-name/test.txt ``` 1. Verify file delivery in the destination S3 bucket. 1. Check CloudWatch logs for successful processing and MDN responses. For more comprehensive testing, consider using third-party AS2 clients to send files to your Transfer Family AS2 server. ### Best practices for AS2 template deployment Follow these best practices when using AS2 CloudFormation templates: Security Use strong certificates and rotate them regularly. Implement least-privilege IAM policies. Restrict network access using security groups. Reliability Deploy across multiple Availability Zones. Implement monitoring and alerting for failed transfers. Set up automated retries for failed transfers. Performance Choose appropriate instance types for your transfer volume. Implement S3 lifecycle policies for efficient file management. Monitor and optimize network configurations. Cost Optimization Use auto-scaling for variable workloads. Implement S3 storage classes for older files. Monitor and adjust resources based on actual usage. # Configuring AS2 To create an AS2-enabled server, you must also specify the following components: + **Agreements** – Bilateral trading partner *agreements*, or partnerships, define the relationship between the two parties that are exchanging messages (files). To define an agreement, Transfer Family combines server, local profile, partner profile, and certificate information. Transfer Family AS2-inbound processes use agreements. + **Certificates** – *Public key (X.509) certificates* are used in AS2 communication for message encryption and verification. Certificates are also used for connector endpoints. + **Local profiles and partner profiles** – A *local profile* defines the local (AS2-enabled Transfer Family server) organization or "party." Similarly, a *partner profile* defines the remote partner organization, external to Transfer Family. While not required for all AS2-enabled servers, for outbound transfers, you need a **connector**. A connector captures the parameters for an outbound connection. The connector is required for sending files to a customer's external, non AWS server. The following diagram shows the relationship between the AS2 objects involved in the inbound and outbound processes. ![\[Diagram that shows the relationship between the AS2 objects involved in the inbound and outbound processes.\]](http://docs.aws.amazon.com/transfer/latest/userguide/images/as2-architecture-in-out-agree-connect.png) For an end-to-end example AS2 configuration, see [Setting up an AS2 configuration](as2-example-tutorial.md). **Topics** + [AS2 configurations](#as2-supported-configurations) + [AS2 quotas and limitations](#as2-limitations) + [AS2 features and capabilities](#as2-capabilities) ## AS2 configurations This topic describes the supported configurations, features, and capabilities for transfers that use the Applicability Statement 2 (AS2) protocol, including the accepted ciphers and digests. **Signing, encryption, compression, MDN** For both inbound and outbound transfers, the following items are either required or optional: + **Encryption** – Required (for HTTP transport, which is the only transport method currently supported). Unencrypted messages are only accepted if forwarded by a TLS-terminating proxy such as an Application Load Balancer (ALB) and the `X-Forwarded-Proto: https` header is present. + **Signing** – Optional + **Compression** – Optional (the only currently supported compression algorithm is ZLIB) + **Message Disposition Notice (MDN)** – Optional **Ciphers** The following ciphers are supported for both inbound and outbound transfers: + AES128\$1CBC + AES192\$1CBC + AES256\$1CBC + 3DES (for backward compatibility only) **Digests** The following digests are supported: + **Inbound signing and MDN** – SHA1, SHA256, SHA384, SHA512 + **Outbound signing and MDN** – SHA1, SHA256, SHA384, SHA512 **MDN** For MDN responses, certain types are supported, as follows: + **Inbound transfers** – Synchronous and asynchronous + **Outbound transfers** – Synchronous and asynchronous + **Simple Mail Transfer Protocol (SMTP) (email MDN)** – Not supported **Transports** + **Inbound transfers** – HTTP is the only currently supported transport, and you must specify it explicitly. **Note** If you need to use HTTPS for inbound transfers, you can terminate TLS on an Application Load Balancer or a Network Load Balancer. This is described in [Receive AS2 messages over HTTPS](send-as2-messages.md#receive-https). + **Outbound transfers** – If you provide an HTTP URL, you must also specify an encryption algorithm. If you provide an HTTPS URL, you have the option of specifying **NONE** for your encryption algorithm. ## AS2 quotas and limitations This section discusses quotas and limitations for AS2 **Topics** + [AS2 quotas](#as2-quotas) + [Quotas for handling secrets](#as2-quotas-secrets) + [Known limitations](#as2-known-limitations) ### AS2 quotas The following quotas are in place for AS2 file transfers. To request an increase for a quota that's adjustable, see [AWS service quotas](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html) in the *AWS General Reference*. **AS2 quotas** | Name | Default | Adjustable | | --- | --- | --- | | Maximum number of files per outbound request | 10 | No | | Maximum number of outbound requests per second | 100 | No | | Maximum number of inbound requests per second | 100 | No | | Maximum outbound bandwidth per account (outbound SFTP and AS2 requests both contribute to this value) | 50 MB per second | No | ### Quotas for handling secrets AWS Transfer Family makes calls to AWS Secrets Manager on behalf of AS2 customers that are using Basic authentication. Additionally Secrets Manager makes calls to AWS KMS. **Note** These quotas aren't specific to your use of secrets for Transfer Family: they're shared among all the services in your AWS account. For Secrets Manager `GetSecretValue`, the quota that applies is **Combined rate of DescribeSecret and GetSecretValue API requests**, as described in [AWS Secrets Manager quotas](https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_limits.html#quotas). **Secrets Manager `GetSecretValue`** | Name | Value | Description | | --- | --- | --- | | Combined rate of DescribeSecret and GetSecretValue API requests | Each supported Region: 10,000 per second | The maximum transactions per second for DescribeSecret and GetSecretValue API operations combined. | For AWS KMS, the following quotas apply for `Decrypt`. For details, see [ Request quotas for each AWS KMS API operation](https://docs.aws.amazon.com/kms/latest/developerguide/requests-per-second.html#rps-table) **AWS KMS `Decrypt`** | Quota name | Default value (requests per second) | | --- | --- | | Cryptographic operations (symmetric) request rate | These shared quotas vary with the AWS Region and the type of AWS KMS key used in the request. Each quota is calculated separately. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/transfer/latest/userguide/create-b2b-server.html) | | Custom key store request quotas This quota only applies if you are using an external key store. | Custom key store request quotas are calculated separately for each custom key store. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/transfer/latest/userguide/create-b2b-server.html) | ### Known limitations + Server-side TCP keep-alive is not supported. The connection times out after 350 seconds of inactivity unless the client sends keep-alive packets. + For an active agreement to be accepted by the service and appear in Amazon CloudWatch logs, messages must contain valid AS2 headers. + The server that's receiving messages from AWS Transfer Family for AS2 must support the Cryptographic Message Syntax (CMS) algorithm protection attribute for validating message signatures, as defined in [RFC 6211](https://datatracker.ietf.org/doc/html/rfc6211). This attribute is not supported in some older IBM Sterling products. + Duplicate message IDs result in a processed/Warning: duplicate-document message. + The key length for AS2 certificates must be at least 2048 bits, and at most 4096. + When sending AS2 messages or asynchronous MDNs to a trading partner's HTTPS endpoint, the messages or MDNs must use a valid SSL certificate that's signed by a publicly trusted certificate authority (CA). Self-signed certificates are currently supported for outbound transfers only. + The endpoint must support the TLS version 1.2 protocol and a cryptographic algorithm that's permitted by the security policy (as described in [Security policies for AWS Transfer Family servers](security-policies.md)). + Multiple attachments and certificate exchange messaging (CEM) from AS2 version 1.2 is not currently supported. + Basic authentication is currently supported for outbound messages only. + You can attach a file-processing workflow to a Transfer Family server that uses the AS2 protocol: however, AS2 messages don't execute workflows attached to the server. ## AS2 features and capabilities The following tables list the features and capabilities available for Transfer Family resources that use AS2. ### AS2 features Transfer Family offers the following features for AS2. | Feature | Supported by AWS Transfer Family | | --- |--- | | [Drummond certification](https://aws.amazon.com/about-aws/whats-new/2023/06/aws-transfer-family-drummond-group-as2-certification/) | Yes | | [AWS CloudFormation support](https://docs.aws.amazon.com/transfer/latest/userguide/as2-cfn-demo-template.html) | Yes | | [Amazon CloudWatch metrics](https://docs.aws.amazon.com/transfer/latest/userguide/as2-monitoring.html) | Yes | | [SHA-2 cryptographic algorithms](https://docs.aws.amazon.com/transfer/latest/userguide/security-policies.html#cryptographic-algorithms) | Yes | | Support for Amazon S3 | Yes | | Support for Amazon EFS | No | | Scheduled Messages | Yes 1 | | AWS Transfer Family Managed Workflows | No | | Certificate Exchange Messaging (CEM) | No | | Mutual TLS (mTLS) | No | | Support for self-signed certificates | Yes | 1. Outbound Scheduled Messages available by [scheduling AWS Lambda functions using Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-run-lambda-schedule.html) ### AS2 send and receive capabilities The following table provides a list of AWS Transfer Family AS2 send and receive capabilities. | Capability | Inbound: Receiving with server | Outbound: Sending with connector | | --- |--- |--- | | [TLS Encrypted Transport (HTTPS)](send-as2-messages.md#as2-https-process) | Yes 1 | Yes | | Non-TLS Transport (HTTP) | Yes | Yes 2 | | Synchronous MDN | Yes | Yes | | Message Compression | Yes | Yes | | Asynchronous MDN | Yes | Yes | | Static IP Address | Yes | Yes | | Bring Your Own IP Address | Yes | No | | Multiple File Attachments | No | No | | Basic Authentication | No | Yes | | AS2 Restart | Not applicable | No | | AS2 Reliability | No | No | | Custom Subject per Message | Not applicable | No | 1. Inbound TLS Encrypted Transport available with Network Load Balancer (NLB) or Application Load Balancer (ALB) 2. Outbound non-TLS Transport available only when encryption is enabled # Manage AS2 certificates This topic discusses how to import and manage AS2 certificates. Importing certificates is the first step in the AS2 process for Transfer Family. 1. Import certificates 1. [Create AS2 profiles](configure-as2-profile.md) 1. [Create an AS2 server](create-as2-transfer-server.md) 1. [Create an AS2 agreement](create-as2-transfer-server.md#as2-agreements) 1. [Configure AS2 connectors](configure-as2-connector.md) ## Import AS2 certificates The Transfer Family AS2 process uses certificate keys for both encryption and signing of transferred information. Partners can use the same key for both purposes, or a separate key for each. If you have common encryption keys kept in escrow by a trusted third-party so that data can be decrypted in the event of a disaster or security breach, we recommend having separate signing keys. By using separate signing keys (which you do not escrow), you don't compromise the non-repudiation features of your digital signatures. **Note** The key length for AS2 certificates must be at least 2048 bits, and at most 4096. The following points detail how AS2 certificates are used during the process. + Inbound AS2 + The trading partner sends their public key for the signing certificate, and this key is imported to the partner profile. + The local party sends the public key for their encryption and signing certificates. The partner then imports the private key or keys. The local party can send separate certificate keys for signing and encryption, or can choose to use the same key for both purposes. + Outbound AS2 + The partner sends the public key for their encryption certificate, and this key is imported to the partner profile. + The local party sends the public key for the certificate for signing, and imports the private key of the certificate for signing. + If you are using HTTPS, you can import a self-signed Transport Layer Security (TLS) certificate. For details on how to create certificates, see [Step 1: Create certificates for AS2](as2-example-tutorial.md#as2-create-certs). This procedure explains how to import certificates by using the Transfer Family console. If you want to use the AWS CLI instead, see [Step 2: Import certificates as Transfer Family certificate resources](as2-example-tutorial.md#as2-import-certs-example). **To specify an AS2-enabled certificate** 1. Open the AWS Transfer Family console at [https://console.aws.amazon.com/transfer/](https://console.aws.amazon.com/transfer/). 1. In the left navigation pane, under **AS2 Trading Partners**, choose **Certificates**. 1. Choose **Import certificate**. 1. In the **Certificate configuration** section, for **Certificate description**, enter an easily identifiable name for the certificate. Make sure that you can identify the certificate's purpose by its description. Additionally, choose the role for the certificate. 1. In the **Certificate usage** section, choose the purpose for this certificate. It can be used for encryption, signing, or both. **Tip: **If you choose **Encryption and signing** for the usage, Transfer Family creates two identical certificates (each having their own ID): one with a usage value of `ENCRYPTION` and one with a usage value of `SIGNING`. 1. In the **Certificate contents** section, provide a public certificate from a trading partner, or the public and private keys for a local certificate. Fill in the **Certificate contents** section with the appropriate details. + If you choose **Self-signed certificate**, you do not provide the certificate chain. + Paste the certificate text and its chain into the **Certificate and Certificate chain** field. + If this certificate is a local certificate, paste in its private key. 1. Choose **Import certificate** to complete the process and save the details for the imported certificate. **Note** TLS certificates can only be imported as a partner's public certificate. If you select **Public certificate from a partner**, and then select **Transport Layer Security (TLS)** for the usage, you receive a warning. Also, TLS certificates must be self-signed (that is, you must select **Self Signed Certificate** to import a TLS certificate). ## AS2 certificate rotation Often, certificates are valid for a period of six months to a year. You might have set up profiles that you want to persist for a longer duration. To facilitate this, Transfer Family provides certificate rotation. You can specify multiple certificates for a profile, allowing you to keep using the profile for multiple years. Transfer Family uses certificates for signing (optional) and encryption (mandatory). You can specify a single certificate for both purposes, if you like. Certificate rotation is the process of replacing an old expiring certificate with a newer certificate. The transition is a gradual one to avoid disrupting transfers where a partner in the agreement has yet to configure a new certificate for outbound transfers or might be sending payloads that are signed or encrypted with an old certificate during a period when a newer certificate might also be in use. The intermediate period where both old and new certificates are valid is referred to as a *grace period*. X.509 certificates have `Not Before` and `Not After` dates. However, these parameters might not provide enough control for administrators. Transfer Family provides `Active Date` and `Inactive Date` settings to control which certificate is used for outbound payloads and which is accepted for inbound payloads. ### Certificate expiration monitoring Transfer Family publishes a Amazon CloudWatch metric `DaysUntilExpiry` after importing a certificate. The metric emits the number of days between the current date and the date specified as the `InactiveDate` on the Certificate. The metric is found under the `Transfer` AWS namespace in the CloudWatch metrics dashboard. This metric will always have a metric dimension for **CertificateId** and will optionally include a **Description** dimension if provided by the customer on the certificate. For more information about CloudWatch metric dimensions, see [Dimension](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_Dimension.html) in the *CloudWatch API Reference*. **Note** It can take up to a full day after importing a Certificate for Transfer Family to emit this metric to the customer account. You can use this metric to create CloudWatch alarms that notify you when certificates are approaching expiration. Outbound certificate selection uses the maximum value that is prior to the date of the transfer as an `Inactive Date`. Inbound processes accept certificates within the range of `Not Before` and `Not After` and within the range of `Active Date` and `Inactive Date`. ### Certificate rotation example The following table describes one possible way to configure two certificates for a single profile. **Two certificates in rotation** | Name | NOT BEFORE (controlled by certificate authority) | ACTIVE DATE (set by Transfer Family) | INACTIVE DATE (set by Transfer Family) | NOT AFTER (set by certificate authority) | | --- | --- | --- | --- | --- | | Cert1 (older certificate) | 2019-11-01 | 2020-01-01 | 2020-12-31 | 2024-01-01 | | Cert2 (newer certificate) | 2020-11-01 | 2020-06-01 | 2021-06-01 | 2025-01-01 | Note the following: + When you specify an `Active Date` and `Inactive Date` for a certificate, the range must be inside the range between `Not Before` and `Not After`. + We recommend that you configure several certificates for each profile, making sure that the active date range for all the certificates combined covers the amount of time for which you want to use the profile. + We recommend that you specify some grace time between when your older certificate becomes inactive and when your newer certificate becomes active. In the preceding example, the first certificate does not become inactive until 2020-12-31, while the second certificate becomes active on 2020-06-01, providing a 6-month grace period. During the period from 2020-06-01 until 2020-12-31, both certificates are active. # Create AS2 profiles This topic discusses how to create profiles for use in the AS2 process. A *local profile* defines the local (AS2-enabled Transfer Family server) organization or "party." Similarly, a *partner profile* defines the remote partner organization, external to Transfer Family. 1. [Import AS2 certificates](managing-as2-partners.md#configure-as2-certificate) 1. Create AS2 profiles 1. [Create an AS2 server](create-as2-transfer-server.md) 1. [Create an AS2 agreement](create-as2-transfer-server.md#as2-agreements) 1. [Configure AS2 connectors](configure-as2-connector.md) Use this procedure to create both local and partner profiles. This procedure explains how to create AS2 profiles by using the Transfer Family console. If you want to use the AWS CLI instead, see [Step 3: Create profiles for you and your trading partner](as2-example-tutorial.md#as2-create-profiles-example). **To create an AS2 profile** 1. Open the AWS Transfer Family console at [https://console.aws.amazon.com/transfer/](https://console.aws.amazon.com/transfer/). 1. In the left navigation pane, under **AS2 Trading Partners**, choose **Profiles**, then choose **Create profile**. 1. In the **Profile configuration** section, enter the AS2 ID for the profile. This value is used for the AS2 protocol-specific HTTP headers `as2-from` and `as2-to` to identify the trading partnership, which determines the certificates to use, and so on. 1. In the **Profile type** section, choose **Local profile** or **Partner profile**. 1. In the **Certificates** section, choose one or more certificates from the dropdown menu. **Tip: **If you want to import a certificate that is not listed in the dropdown menu, select **Import a new Certificate**. This opens a new browser window at the **Import certificate** screen. For the procedure about importing certificates see [Import AS2 certificates](managing-as2-partners.md#configure-as2-certificate). 1. (Optional) In the **Tags** section, specify one or more key-value pairs to help identify this profile. 1. Choose **Create profile** to complete the process and save the new profile. # Create an AS2 server This topic provides instructions for creating an AS2-enabled Transfer Family server, using either the console or a CloudFormation template. For an end-to-end example AS2 configuration, see [Setting up an AS2 configuration](as2-example-tutorial.md). After you create an AS2 server, you can add an agreement to the server. 1. [Import AS2 certificates](managing-as2-partners.md#configure-as2-certificate) 1. [Create AS2 profiles](configure-as2-profile.md) 1. Create an AS2 server 1. [Create an AS2 agreement](#as2-agreements) 1. [Configure AS2 connectors](configure-as2-connector.md) **Topics** + [Create an AS2 server using the Transfer Family console](#create-server-as2-console) + [Use a template to create a demo Transfer Family AS2 stack](#as2-cfn-demo-template) + [Create an AS2 agreement](#as2-agreements) ## Create an AS2 server using the Transfer Family console This procedure explains how to create an AS2-enabled server by using the Transfer Family console. If you want to use the AWS CLI instead, see [Step 4: Create a Transfer Family server that uses the AS2 protocol](as2-example-tutorial.md#as2-example-server). **Note** You can attach a file-processing workflow to a Transfer Family server that uses the AS2 protocol: however, AS2 messages don't execute workflows attached to the server. **To create an AS2-enabled server** 1. Open the AWS Transfer Family console at [https://console.aws.amazon.com/transfer/](https://console.aws.amazon.com/transfer/). 1. In the left navigation pane, choose **Servers**, and then choose **Create server**. 1. On the **Choose protocols** page, select **AS2 (Applicability Statement 2)**, and then choose **Next**. 1. On the **Choose an identity provider** page, choose **Next**. **Note** For AS2, you cannot choose an identity provider because basic authentication is not supported for the AS2 protocol. Instead, you control access through virtual private cloud (VPC) security groups. 1. On the **Choose an endpoint** page, do the following: ![\[Console screenshot showing the Choose an endpoint page with VPC hosted selected.\]](http://docs.aws.amazon.com/transfer/latest/userguide/images/create-server-choose-endpoint-vpc-internal.png) 1. For **Endpoint type**, choose **VPC hosted** to host your server's endpoint. For information about setting up your VPC-hosted endpoint, see [Create a server in a virtual private cloud](create-server-in-vpc.md). **Note** Publicly accessible endpoints are not supported for the AS2 protocol. To make your VPC endpoint accessible over the internet, choose **Internet Facing** under **Access**, and then supply your Elastic IP addresses. 1. For **Access**, choose one of the following options: + **Internal** – Choose this option to provide access from within your VPC and VPC-connected environments, such as an on-premises data center over Direct Connect or VPN. + **Internet Facing** – Choose this option to provide access over the internet and from within your VPC and VPC-connected environments, such as an on-premises data center over Direct Connect or VPN. If you choose **Internet Facing**, supply your Elastic IP addresses when prompted. 1. For **VPC**, either choose an existing VPC or choose **Create VPC** to create a new VPC. 1. For **FIPS Enabled**, keep the **FIPS Enabled endpoint** check box cleared. **Note** FIPS-enabled endpoints are not supported for the AS2 protocol. 1. Choose **Next**. 1. On the **Choose a domain** page, choose **Amazon S3** to store and access your files as objects by using the selected protocol. Choose **Next**. 1. On the **Configure additional details** page, choose the settings that you need. **Note** If you are configuring any other protocols along with AS2, all of the additional detail settings apply. However, for the AS2 protocol, the only settings that apply are those in the **CloudWatch logging** and **Tags** sections. Even though setting up a CloudWatch logging role is optional, we highly recommend setting it up so that you can see the status of your messages and troubleshoot configuration issues. 1. On the **Review and create** page, review your choices to make sure they are correct. + If you want to edit any of your settings, choose **Edit** next to the step that you want to change. **Note** If you edit a step, we recommend that you review each step after the step that you chose to edit. + If you have no changes, choose **Create server** to create your server. You are taken to the **Servers** page, shown following, where your new server is listed. It can take several minutes before the status for your new server changes to **Online**. At that point, your server can perform file operations for your users. ## Use a template to create a demo Transfer Family AS2 stack We supply a self-contained, CloudFormation template to quickly create an AS2-enabled Transfer Family server. The template configures the server with a public Amazon VPC endpoint, certificates, local and partner profiles, an agreement, and a connector. The basic AS2 server template creates the following resources: + An AS2-enabled Transfer Family server with a VPC endpoint + Local and partner AS2 profiles with certificates + An agreement between the profiles + An Amazon S3 bucket for file storage + Required IAM roles and policies + CloudWatch logging configuration Before using this template, note the following: + If you create a stack from this template, you will be billed for the AWS resources that are used. + The template creates multiple certificates and places them in AWS Secrets Manager to store them securely. You can delete these certificates from Secrets Manager if you want, because you're charged for using this service. Deleting these certificates in Secrets Manager doesn't delete them from the Transfer Family server. Therefore, the functionality of the demo stack isn't affected. However, for certificates that you're going to use with a production AS2 server, you might want to use Secrets Manager to manage and periodically rotate your stored certificates. + We recommend that you use the template as a base only, and mainly for demonstration purposes. If you want to use this demo stack in production, we recommend that you modify the template's YAML code to create a more robust stack. For example, create production-level certificates, and create an AWS Lambda function that you can use in production. **To create an AS2-enabled Transfer Family server from a CloudFormation template** 1. Open the CloudFormation console at [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. In the left navigation pane, choose **Stacks**. 1. Choose **Create stack**, and then choose **With new resources (standard)**. 1. In the **Prerequisite - Prepare template** section, choose **Choose an existing template**. 1. Copy this link, [AS2 demo template](https://s3.amazonaws.com/aws-transfer-resources/as2-templates/aws-transfer-as2-basic.template.yml), and paste it into the **Amazon S3 URL** field. 1. Choose **Next**. 1. On the **Specify stack details** page, name your stack, and then specify the following parameters: + Under **AS2**, enter values for **Local AS2 ID** and **Partner AS2 ID**, or accept the defaults, `local` and `partner`, respectively. + Under **Network**, enter a value for **Security group ingress CIDR IP**, or accept the default, `0.0.0.0/0`. **Note** This value, in CIDR format, specifies which IP addresses are allowed for incoming traffic to the AS2 server. The default value, `0.0.0.0/0`, allows all IP addresses. + Under **General**, enter a value for **Prefix**, or accept the default, `transfer-as2`. This prefix is placed before any resource names that are created by the stack. For example, if you use the default prefix, your Amazon S3 bucket is named `transfer-as2-amzn-s3-demo-bucket`. 1. Choose **Next**. On the **Configure stack options** page, choose **Next** again. 1. Review the details for the stack that you're creating, and then choose **Create stack**. **Note** At the bottom of the page, under **Capabilities**, you must acknowledge that CloudFormation might create AWS Identity and Access Management (IAM) resources. After the stack is created, you can send a test AS2 message from the partner server to your local Transfer Family server by using the AWS Command Line Interface (AWS CLI). A sample AWS CLI command for sending a test message is created along with all of the other resources in the stack. To use this sample command, go to the **Outputs** tab of your stack, and copy the **TransferExampleAs2Command**. You can then run the command by using the AWS CLI. If you haven't already installed the AWS CLI, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the *AWS Command Line Interface User Guide*. The sample command has the following format: ``` aws s3api put-object --bucket amzn-s3-demo-bucket --key test.txt && aws transfer start-file-transfer --region aws-region --connector-id TransferConnectorId --send-file-paths /amzn-s3-demo-bucket/test.txt ``` **Note** Your version of this command contains the actual values for the `amzn-s3-demo-bucket` and `TransferConnectorId` resources in your stack. This sample command consists of two separate commands that are chained together by using the `&&` string. The first command creates a new, empty text file in your bucket: ``` aws s3api put-object --bucket amzn-s3-demo-bucket --key test.txt ``` Then, the second command uses the connector to send the file from the partner profile to the local profile. The Transfer Family server has an agreement set up that allows the local profile to accept messages from the partner profile. ``` aws transfer start-file-transfer --region aws-region --connector-id TransferConnectorId --send-file-paths /amzn-s3-demo-bucket/test.txt ``` After you run the command, you can go to your Amazon S3 bucket (`amzn-s3-demo-bucket`) and view the contents. If the command is successful, you should see the following objects in your bucket: + `processed/` – This folder contains a JSON file that describes the transferred file and the MDN response. + `processing/` – This folder temporarily contains files as they are being processed, but after a transfer is completed, this folder should be empty. + `server-id/` – This folder is named based on your Transfer Family server ID. It contains `from-partner` (this folder is dynamically named, based on the partner's AS2 ID), which itself contains `failed/`, `processed/`, and `processing/` folders. The `/server-id/from-partner/processed/` folder contains a copy of the transferred text file, and the corresponding JSON and MDN files. + `test.txt` – This object is the (empty) file that was transferred. ## Create an AS2 agreement Agreements are associated with Transfer Family servers. They specify the details for trading partners that use the AS2 protocol to exchange messages or files by using Transfer Family, for *inbound* transfers—sending AS2 files from an external, partner-owned source to a Transfer Family server. This procedure explains how to create AS2 agreements by using the Transfer Family console. If you want to use the AWS CLI instead, see [Step 5: Create an agreement between you and your partner](as2-example-tutorial.md#as2-create-agreement-example). **To create an agreement for a Transfer Family server** 1. Open the AWS Transfer Family console at [https://console.aws.amazon.com/transfer/](https://console.aws.amazon.com/transfer/). 1. In the left navigation pane, choose **Servers**, and then choose a server that uses the AS2 protocol. As an alternative, as long as you have at least one Transfer Family server that uses the AS2 protocol, select **Agreements to receive messages** from the **AS2 Trading Partners** menu. Then, in the **Create agreement** screen, select the AS2 server to which you want to associate this agreement. 1. On the server details page, scroll down to the **Agreements** section. 1. Choose **Add agreement**. 1. Fill in the agreement parameters, as follows: 1. In the **Agreement configuration** section, enter a descriptive name. Make sure that you can identify the agreement's purpose by its name. Also, set the **Status** for the agreement: either **Active** (selected by default) or **Inactive**. 1. In the **Communication configuration** section, choose a local profile and a partner profile. Also, choose whether or not to enforce message signing. + By default, **Enforce message signing** is enabled, which means that Transfer Family rejects unsigned messages from your trading partner for this agreement. + Clear this setting to allow Transfer Family to accept unsigned messages from your trading partner for this agreement. 1. In the **Inbox directory configuration** section, provide the following information. + Determine whether or not to select **Specify separate directories to store your AS2 messages, MDN files, and JSON status files**. + If you select this option, you specify separate locations for payload files, failed files, MDN files, status files, and temporary files. + If you clear this option, all AS2 files go into the location that you specify for your base directory. + For **S3 Bucket**, choose an Amazon S3 bucket. + For **Prefix**, you can enter a prefix (folder) to use for storing files in the bucket. For example, if you enter **amzn-s3-demo-bucket** for your bucket and **incoming** for your prefix, your AS2 files are saved to the `/amzn-s3-demo-bucket/incoming` folder. + For **AWS IAM Role**, choose a role that can access the bucket you specified. + For **Preserve filename**, choose whether to preserve original filenames for incoming AS2 message payloads. + If you select this setting, the filename provided by your trading parter is preserved when the file is saved in Amazon S3. + If you clear this setting, when Transfer Family saves the file, the filename is adjusted, as described in [File names and locations](send-as2-messages.md#file-names-as2). 1. (Optional) Add tags in the **Tags** section. 1. After you have entered all the information for the agreement, choose **Create agreement**. The new agreement appears in the **Agreements** section of the server details page. # Configure AS2 connectors The purpose of a connector is to establish a relationship between trading partners for *outbound* transfers—sending AS2 files from a Transfer Family server to an external, partner-owned destination. For the connector, you specify the local party, the remote partner, and their certificates (by creating local and partner profiles). After you have a connector in place, you can transfer information to your trading partners. Each AS2 server is assigned three static IP addresses. AS2 connectors use these IP addresses for sending asynchronous MDNs to your trading partners over AS2. **Note** The message size received by a trading partner will not match the object size in Amazon S3. This discrepancy occurs because the AS2 message wraps the file in an envelope prior to sending. So, the file size might increase, even if the file is sent with compression. Therefore, make sure that the trading partner's maximum file size is greater than the size of the file that you are sending. 1. [Import AS2 certificates](managing-as2-partners.md#configure-as2-certificate) 1. [Create AS2 profiles](configure-as2-profile.md) 1. [Create an AS2 server](create-as2-transfer-server.md) 1. [Create an AS2 agreement](create-as2-transfer-server.md#as2-agreements) 1. Create an AS2 connector ## Create an AS2 connector This procedure explains how to create AS2 connectors by using the AWS Transfer Family console. If you want to use the AWS CLI instead, see [Step 6: Create a connector between you and your partner](as2-example-tutorial.md#as2-create-connector-example). **To create an AS2 connector** 1. Open the AWS Transfer Family console at [https://console.aws.amazon.com/transfer/](https://console.aws.amazon.com/transfer/). 1. In the left navigation pane, choose **Connectors to send messages**, from the **AS2 Trading Partners** menu, and then choose **Create AS2 connector**. 1. In the **Connector configuration** section, specify the following information: + **URL** – Enter the URL for outbound connections. + **IP addressing mode** – Choose **IPv4 only** (default) to use IPv4 addresses exclusively, or **Dual-stack** to support both IPv6 and IPv4. In dual-stack mode, the connector prefers IPv6 when DNS resolution returns IPv6 results, and uses IPv4 when only IPv4 DNS results are returned. + **Access role** – Choose the Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role to use. Make sure that this role provides read and write access to the parent directory of the file location that's used in the `StartFileTransfer` request. Additionally, make sure that the role provides read and write access to the parent directory of the files that you intend to send with `StartFileTransfer`. **Note** If you're using Basic authentication for your connector, the access role requires the `secretsmanager:GetSecretValue` permission for the secret. If the secret is encrypted by using a customer managed key instead of the AWS managed key in AWS Secrets Manager, then the role also needs the `kms:Decrypt` permission for that key. If you name your secret with the prefix `aws/transfer/`, you can add the necessary permission with a wildcard character (`*`), as shown in [Example permission to create secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_examples.html#auth-and-access_examples_wildcard). + **Logging role** (optional) – Choose the IAM role for the connector to use to push events to your CloudWatch logs. 1. In the **AS2 configuration** section, choose the local and partner profiles, the encryption and signing algorithms, and whether to compress the transferred information. Note the following: + The **Preserve S3 Content-Type** parameter is enabled by default. When set, Transfer Family uses the Amazon S3 `Content-Type` that is associated with objects in S3 instead of having the content type mapped based on the file extension. Clear this setting if you want the service to map content type for your AS2 messages based on file extension, rather than using the content type from the S3 object. + For the encryption algorithm, do not choose `DES_EDE3_CBC` unless you must support a legacy client that requires it, as it is a weak encryption algorithm. + The **Subject** is used as the `subject` HTTP header attribute in AS2 messages that are being sent with the connector. + If you choose to create a connector without an encryption algorithm, you must specify `HTTPS` as your protocol. 1. In the **Basic authentication** section, specify the following information. + To send sign-on credentials along with outbound messages, select **Enable Basic authentication**. If you don't want to send any credentials with outbound messages, keep **Enable Basic authentication** cleared. + If you're using authentication, choose or create a secret. + To create a new secret, choose **Create a new secret** and then enter a username and password. These credentials must match the user that connects to the partner's endpoint. ![\[The Create connector page in the AWS Transfer Family console, showing the Basic authentication section with Create a new secret chosen.\]](http://docs.aws.amazon.com/transfer/latest/userguide/images/as2-basic-auth-create-secret.png) + To use an existing secret, choose **Choose an existing secret**, and then choose a secret from the dropdown menu. For the details of creating a correctly formatted secret in Secrets Manager, see [Enable Basic authentication for AS2 connectors](#as2-secret-create). ![\[The Create connector page in the AWS Transfer Family console, showing the Basic authentication section with Choose an existing secret chosen.\]](http://docs.aws.amazon.com/transfer/latest/userguide/images/as2-basic-auth-select-secret.png) 1. In the **MDN configuration** section, specify the following information: + **Request MDN** – You have the option to require your trading partner to send you an MDN after they have successfully received your message over AS2. + **Signed MDN** – You have the option to require that MDNs be signed. This option is available only if you have selected **Request MDN**. 1. After you've confirmed all of your settings, choose **Create AS2 connector** to create the connector. The **Connectors** page appears, with the ID of your new connector added to the list. To view the details for your connectors, see [View AS2 connector details](#connectors-view-info). ## AS2 connector algorithms When you create an AS2 connector, the following security algorithms are attached to the connector. | Type | Algorithm | | --- | --- | | TLS Cipher | TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1128\$1GCM\$1SHA256 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1GCM\$1SHA256 TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA256 TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1GCM\$1SHA384 TLS\$1ECDHE\$1ECDSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA384 | ## Basic authentication for AS2 connectors When you create or update a Transfer Family server that uses the AS2 protocol, you can add Basic authentication for outbound messages. You do this by adding authentication information to a connector. **Note** Basic authentication is available only if you're using HTTPS. To use authentication for your connector, select **Enable Basic authentication** in the **Basic authentication ** section. After you enable Basic authentication, you can choose to create a new secret, or use an existing one. In either case, the credentials in the secret are sent with outbound messages that use this connector. The credentials must match the user that is attempting to connect to the trading partner's remote endpoint. The following screenshot shows **Enable Basic authentication** selected, and **Create a new secret** chosen. After making these choices, you can enter a username and password for the secret. ![\[The Transfer Family console Connectors page, showing the message authentication information for your connector. In this case, Enable Basic authentication is selected, and Create a new secret is chosen.\]](http://docs.aws.amazon.com/transfer/latest/userguide/images/as2-basic-auth-create-secret.png) The following screenshot shows **Enable Basic authentication** selected, and **Choose an existing secret** chosen. Your secret must be in the correct format, as described in [Enable Basic authentication for AS2 connectors](#as2-secret-create). ![\[The Transfer Family console Connectors page, showing the message authentication information for your connector. In this case, Enable Basic authentication is selected, and Choose an existing secret is chosen.\]](http://docs.aws.amazon.com/transfer/latest/userguide/images/as2-basic-auth-select-secret.png) ## Enable Basic authentication for AS2 connectors When you enable Basic authentication for AS2 connectors, you can either create a new secret in the Transfer Family console, or you can use a secret that you create in AWS Secrets Manager. In either case, your secret is stored in Secrets Manager. **Topics** + [Create a new secret in the console](#as2-secret-details-console) + [Use an existing secret](#use-existing-secret) + [Create a secret in AWS Secrets Manager](#as2-secret-details-asm) ### Create a new secret in the console When you're creating a connector in the console, you can create a new secret. To create a new secret, choose **Create a new secret** and then enter a username and password. These credentials must match the user that connects to the partner's endpoint. ![\[The AWS Transfer Family console Create connector page, showing the Basic authentication section with Create a new secret chosen.\]](http://docs.aws.amazon.com/transfer/latest/userguide/images/as2-basic-auth-create-secret.png) **Note** When you create a new secret in the console, the name of the secret follows this naming convention: **/aws/transfer/*connector-id***, where *connector-id* is the ID of the connector that you're creating. Consider this when you are trying to locate the secret in AWS Secrets Manager. ### Use an existing secret When you're creating a connector in the console, you can specify an existing secret. To use an existing secret, choose **Choose an existing secret**, and then choose a secret from the dropdown menu. For the details of creating a correctly formatted secret in Secrets Manager, see [Create a secret in AWS Secrets Manager](#as2-secret-details-asm). ![\[The AWS Transfer Family console Create connector page, showing the Basic authentication section with Choose an existing secret chosen.\]](http://docs.aws.amazon.com/transfer/latest/userguide/images/as2-basic-auth-select-secret.png) ### Create a secret in AWS Secrets Manager The following procedure describes how to create an appropriate secret for use with your AS2 connector. **Note** Basic authentication is available only if you're using HTTPS. **To store user credentials in Secrets Manager for AS2 Basic authentication** 1. Sign in to the AWS Management Console and open the AWS Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/). 1. In the left navigation pane, choose **Secrets**. 1. On the **Secrets** page, choose **Store a new secret**. 1. On the **Choose secret type** page, for **Secret type**, choose **Other type of secret**. 1. In the **Key/value pairs** section, choose the **Key/value** tab. + **Key** – Enter **Username**. + **value** – Enter the name of the user that is authorized to connect to the partner' server. 1. If you want to provide a password, choose **Add row**, and in the **Key/value pairs** section, choose the **Key/value** tab. Choose **Add row**, and in the **Key/value pairs** section, choose the **Key/value** tab. + **Key** – Enter **Password**. + **value** – Enter the password for the user. 1. If you want to provide a private key, choose **Add row**, and in the **Key/value pairs** section, choose the **Key/value** tab. + **Key** – Enter **PrivateKey**. + **value** – Enter a private key for the user. This value must be stored in OpenSSH format, and must correspond to the public key that is stored for this user in the remote server. 1. Choose **Next**. 1. On the **Configure secret** page, enter a name and description for your secret. We recommend that you use a prefix of **aws/transfer/** for the name. For example, you could name your secret **aws/transfer/connector-1**. 1. Choose **Next**, and then accept the defaults on the **Configure rotation** page. Then choose **Next**. 1. On the **Review** page, choose **Store** to create and store the secret. After you create the secret, you can choose it when you are creating a connector (see [Configure AS2 connectors](#configure-as2-connector)). In the step where you enable Basic authentication, choose the secret from the dropdown list of available secrets. ## View AS2 connector details You can find a list of details and properties for an AS2 AWS Transfer Family connector in the AWS Transfer Family console. An AS2 connector's properties include its URL, roles, profiles, MDNs, tags, and monitoring metrics. This is the procedure for viewing connector details. **To view connector details** 1. Open the AWS Transfer Family console at [https://console.aws.amazon.com/transfer/](https://console.aws.amazon.com/transfer/). 1. In the left navigation pane, choose **Connectors**. 1. Choose the identifier in the **Connector ID** column to see the details page for the selected connector. You can change the properties for the AS2 connector on the connector's details page by choosing **Edit**. ![\[The Transfer Family console connector details page, showing the URL, access role, and logging role for the selected connector.\]](http://docs.aws.amazon.com/transfer/latest/userguide/images/as2-connector-details_01-top.png) ![\[The Transfer Family console connector details page, showing the AS2 configuration details for the selected connector.\]](http://docs.aws.amazon.com/transfer/latest/userguide/images/as2-connector-details_02-middle.png) ![\[The Transfer Family console connector details page, showing the AS2 Basic authentication section details, tags, static IP, and AS2 monitoring information for the selected connector.\]](http://docs.aws.amazon.com/transfer/latest/userguide/images/as2-basic-auth-details-pane.png) **Note** You can get much of this information, albeit in a different format, by running the following AWS Command Line Interface (AWS CLI command: ``` aws transfer describe-connector --connector-id your-connector-id ``` For more information, see [https://docs.aws.amazon.com/transfer/latest/APIReference/API_DescribeConnector.html](https://docs.aws.amazon.com/transfer/latest/APIReference/API_DescribeConnector.html) in the API reference. # Sending and receiving AS2 messages This section describes the processes for sending and receiving AS2 messages. It also provide details on filenames and locations associated with AS2 messages. The following table lists the available encryption algorithms for AS2 messages, and when you can use them. | Encryption algorithm | HTTP | HTTPS | Notes | | --- |--- |--- |--- | | AES128\$1CBC | Yes | Yes | | | AES192\$1CBC | Yes | Yes | | | AES256\$1CBC | Yes | Yes | | | DES\$1EDE3\$1CBC | Yes | Yes | Only use this algorithm if you must support a legacy client that requires it, as it is a weak encryption algorithm. | | NONE | No | Yes | If you are sending messages to a Transfer Family server, you can only select NONE if you are using an Application Load Balancer (ALB). | **Topics** + [Receive AS2 message process](#as2-inbound-process) + [Sending and receiving AS2 messages over HTTPS](#as2-https-process) + [Transferring files by using an AS2 connector](#transfer-as2-connectors) + [File names and locations](#file-names-as2) + [Status codes](#status-codes) + [Sample JSON files](#file-as2-json) ## Receive AS2 message process The inbound process is defined as a message or file that's being transferred to your AWS Transfer Family server. The sequence for inbound messages is as follows: 1. An admin or automated process starts an AS2 file transfer on the partner's remote AS2 server. 1. The partner's remote AS2 server signs and encrypts the file contents, then sends an HTTP POST request to an AS2 inbound endpoint hosted on Transfer Family. 1. Using the configured values for the server, partners, certificates, and agreement, Transfer Family decrypts and verifies the AS2 payload. The file contents are stored in the configured Amazon S3 file store. 1. The signed MDN response is returned either inline with the HTTP response, or asynchronously through a separate HTTP POST request back to the originating server. 1. An audit trail is written to Amazon CloudWatch with details about the exchange. 1. The decrypted file is available in a folder named `inbox/processed`. ![\[Diagram that shows the processing sequence for inbound messages.\]](http://docs.aws.amazon.com/transfer/latest/userguide/images/as2-architecture-inbound.png) ## Sending and receiving AS2 messages over HTTPS This section describes how to configure a Transfer Family server that uses the AS2 protocol to send and receive messages over HTTPS. **Topics** + [Send AS2 messages over HTTPS](#send-https) + [Receive AS2 messages over HTTPS](#receive-https) ### Send AS2 messages over HTTPS To send AS2 messages using HTTPS, create a connector with the following information: + For the URL, specify an HTTPS URL + For the encryption algorithm, select any of the available algorithms. **Note** To send messages to a Transfer Family server while not using encryption (that is, you select `NONE` for the encryption algorithm), you must use an Application Load Balancer (ALB). + Provide the remaining values for the connector as described in [Configure AS2 connectors](configure-as2-connector.md). ### Receive AS2 messages over HTTPS AWS Transfer Family AS2 servers currently only provide HTTP transport over port 5080. However, you can terminate TLS on a network or application load balancer in front of your Transfer Family server VPC endpoint by using a port and certificate of your choosing. With this approach, you can have incoming AS2 messages use HTTPS. **Prerequisites** + The VPC must be in the same AWS Region as your Transfer Family server. + The subnets of your VPC must be within the Availability Zones that you want to use your server in. **Note** Each Transfer Family server can support up to three Availability Zones. + Allocate up to three Elastic IP addresses in the same Region as your server. Or, you can choose to bring your own IP address range (BYOIP). **Note** The number of Elastic IP addresses must match the number of Availability Zones that you use with your server endpoints. You can configure either a Network Load Balance (NLB) or an Application Load Balancer (ALB). The following table lists the pros and cons for each approach. The table below provides the differences in capabilities when you use an NLB versus an ALB to terminate TLS. | Feature | Network Load Balancer (NLB) | Application Load Balancer (ALB) | | --- | --- | --- | | Latency | Lower latency as it operates at the network layer. | Higher latency as it operates at the application layer. | | Static IP support | Can attach Elastic IP addresses that can be static. | Cannot attach Elastic IP addresses: provides a domain whose underlying IP addresses can change. | | Advanced routing | Doesn't support advanced routing. | Supports advanced routing. Can inject `X-Forwarded-Proto` header required for AS2 without encryption. This header is described in [X-Forwarded-Proto](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto) on the [developer.mozilla.org](https://developer.mozilla.org/) website. | | TLS/SSL termination | Supports TLS/SSL termination | Supports TLS/SSL termination | | Mutual TLS (mTLS) | Transfer Family doesn't currently support using an NLB for mTLS | Support for mTLS | ------ #### [ Configure NLB ] This procedure describes how to set up an internet-facing Network Load Balancer (NLB) in your VPC. **To create a Network Load Balancer and define the VPC endpoint of the server as the load balancer's target** 1. Open the Amazon Elastic Compute Cloud console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. From the navigation pane, choose **Load Balancers**, and then choose **Create load balancer**. 1. Under **Network Load Balancer**, choose **Create**. 1. In the **Basic configuration** section, enter the following information: + For **Name**, enter a descriptive name for the load balancer. + For **Scheme**, choose **Internet-facing**. + For **IP address type**, choose **IPv4**. 1. In the **Network mapping** section, enter the following information: + For **VPC**, choose the virtual private cloud (VPC) that you created. + Under **Mappings**, choose the Availability Zones associated with the public subnets that are available in the same VPC that you use with your server endpoints. + For the **IPv4 address** of each subnet, choose one of the Elastic IP addresses that you allocated. 1. In the **Listeners and routing** section, enter the following information: + For **Protocol**, choose **TLS**. + For **Port**, enter **5080**. + For **Default action**, choose **Create target group**. For the details of creating a new target group, see [To create a target group](#create-target-group). After you create a target group, enter its name in the **Default action** field. 1. In the **Secure listener settings** section, choose your certificate in the **Default SSL/TLS certificate** area. 1. Choose **Create load balancer** to create your NLB. 1. (Optional, but recommended) Turn on access logs for the Network Load Balancer to maintain a full audit trail, as described in [Access logs for your Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-access-logs.html). We recommend this step because the TLS connection is terminated at the NLB. Therefore, the source IP address that's reflected in your Transfer Family AS2 CloudWatch log groups is the NLB's private IP address, instead of your trading partner's external IP address. ------ #### [ Configure ALB ] This procedure describes how to set up an Application Load Balancer (ALB) in your VPC. **To create an Application Load Balancer and define the VPC endpoint of the server as the load balancer's target** 1. Open the Amazon Elastic Compute Cloud console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. From the navigation pane, choose **Load Balancers**, and then choose **Create load balancer**. 1. Under **Application Load Balancer**, choose **Create**. 1. In the ALB console, create a new HTTP listener on port 443 (HTTPS). 1. (Optional). If you want to set up mutual authentication (mTLS), configure security settings and a trust store. 1. Attach your SSL/TLS certificate to the listener. 1. Under **Client certificate handling**, select **Mutual authentication (mTLS)**. 1. Choose **Verify with trust store**. 1. Under **Advanced mTLS settings**, choose or create a trust store by uploading your CA certificates. 1. Create a new target group and add the private IP addresses of your Transfer Family AS2 server endpoints as targets on port 5080. For the details of creating a new target group, see [To create a target group](#create-target-group). 1. Configure health checks for the target group to use the HTTP protocol on port 5080. 1. Create a new rule to forward HTTPS traffic from the listener to the target group. 1. Configure the listener to use your SSL/TLS certificate. ------ After you set up the load balancer, clients communicate with the load balancer over the custom port listener. Then, the load balancer communicates with the server over port 5080. **To create a target group** 1. After you choose **Create target group** in the previous procedure, you are taken to the **Specify group details** page for a new target group. 1. In the **Basic configuration** section, enter the following information. + For **Choose a target type**, choose **IP addresses**. + For **Target group name**, enter a name for the target group. + For **Protocol**, your selection is dependent upon whether you are using an ALB or an NLB. + For a Network Load Balancer (NLB), choose **TCP** + For an Application Load Balancer (ALB), choose **HTTP** + For **Port**, enter **5080**. + For **IP address** type, choose **IPv4**. + For **VPC**, choose the VPC that you created for your Transfer Family AS2 server. 1. In the **Health checks** section, choose the **Health check protocol**. + For an ALB, choose **HTTP** + For an NLB, choose **TCP** 1. Choose **Next**. 1. On the **Register targets** page, enter the following information: + For **Network**, confirm that the VPC that you created for your Transfer Family AS2 server is specified. + For **IPv4 address**, enter the private IPv4 address of your Transfer Family AS2 server's endpoints. If you have more than one endpoint for your server, choose **Add IPv4 address** to add another row for entering another IPv4 address. Repeat this process until you've entered the private IP addresses for all of your server's endpoints. + Make sure that **Ports** is set to **5080**. + Choose **Include as pending below** to add your entries to the **Review targets** section. 1. In the **Review targets** section, review your IP targets. 1. Choose **Create target group**, then go back to the previous procedure for creating your NLB and enter the new target group where indicated. **Test access to the server from an Elastic IP address** Connect to the server over the custom port by using an Elastic IP address or the DNS name of the Network Load Balancer. **Important** Manage access to your server from client IP addresses by using the [network access control lists (network ACLs)](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-network-acls.html) for the subnets configured on the load balancer. Network ACL permissions are set at the subnet level, so the rules apply to all resources that are using the subnet. You can't control access from client IP addresses by using security groups, because the load balancer's target type is set to **IP addresses** instead of **Instances**. Therefore, the load balancer doesn't preserve source IP addresses. If the [Network Load Balancer's health checks](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/target-group-health-checks.html) fail, this means that the load balancer can't connect to the server endpoint. To troubleshoot this issue, check the following: Confirm that the server [endpoint's associated security group](https://aws.amazon.com/premiumsupport/knowledge-center/sftp-enable-elastic-ip-custom-port/) allows inbound connections from the subnets that are configured on the load balancer. The load balancer must be able to connect to the server endpoint over port 5080. Confirm that the server's **State** is **Online**. ## Transferring files by using an AS2 connector AS2 connectors establish a relationship between trading partners for transfers of AS2 messages from a Transfer Family server to an external, partner-owned destination. You can use Transfer Family to send AS2 messages by referencing the connector ID and the paths to the files, as illustrated in the following `start-file-transfer` AWS Command Line Interface (AWS CLI) command: ``` aws transfer start-file-transfer --connector-id c-1234567890abcdef0 \ --send-file-paths "/amzn-s3-demo-source-bucket/myfile1.txt" "/amzn-s3-demo-source-bucket/myfile2.txt" ``` To get the details for your connectors, run the following command: ``` aws transfer list-connectors ``` The `list-connectors` command returns the connector IDs, URLs, and Amazon Resource Names (ARNs) for your connectors. To return the properties of a particular connector, run the following command with the ID that you want to use: ``` aws transfer describe-connector --connector-id your-connector-id ``` The `describe-connector` command returns all of the properties for the connector, including its URL, roles, profiles, Message Disposition Notices (MDNs), tags, and monitoring metrics. You can confirm that the partner successfully received the files by viewing the JSON and MDN files. These files are named according to the conventions described in [File names and locations](#file-names-as2). If you configured a logging role when you created the connector, you can also check your CloudWatch logs for the status of AS2 messages. To view AS2 connector details, see [View AS2 connector details](configure-as2-connector.md#connectors-view-info). For more information about creating AS2 connectors, see [Configure AS2 connectors](configure-as2-connector.md). **To send an AS2 outbound message** The outbound process is defined as a message or file being sent from AWS to an external client or service. The sequence for outbound messages is as follows: 1. An admin calls the `start-file-transfer` AWS Command Line Interface (AWS CLI) command or the `StartFileTransfer` API operation. This operation references a `connector` configuration. 1. Transfer Family detects a new file request and locates the file. The file is compressed, signed, and encrypted. 1. A transfer HTTP client performs an HTTP POST request to transmit the payload to the partner's AS2 server. 1. The process returns the signed MDN response, either inline with the HTTP response (synchronous or asynchronous MDN). 1. As the file moves between different stages of transmission, the process delivers the MDN response receipt and processing details to the customer. 1. The remote AS2 server makes the decrypted and verified file available to the partner admin. ![\[Diagram that shows the processing sequence for outbound messages.\]](http://docs.aws.amazon.com/transfer/latest/userguide/images/as2-architecture-outbound.png) AS2 processing supports many of the RFC 4130 protocols, with a focus on common use cases and integration with existing AS2-enabled server implementations. For details of the supported configurations, see [AS2 configurations](create-b2b-server.md#as2-supported-configurations). ## File names and locations This section discusses the file-naming conventions for AS2 transfers. For inbound file transfers, note the following: + You specify the base directory in an agreement. The base directory is the Amazon S3 bucket name combined with a prefix, if any. For example, `/amzn-s3-demo-bucket/AS2-folder`. + If an incoming file is processed successfully, the file (and the corresponding JSON file) is saved to the `/processed` folder. For example, `/amzn-s3-demo-bucket/AS2-folder/processed`. The JSON file contains the following fields: + `agreement-id` + `as2-from` + `as2-to` + `as2-message-id` + `transfer-id` + `client-ip` + `connector-id` + `failure-message` + `file-path` + `message-subject` + `mdn-message-id` + `mdn-subject` + `requester-file-name` + `requester-content-type` + `server-id` + `status-code` + `failure-code` + `transfer-size` + If an incoming file cannot be processed successfully, the file (and the corresponding JSON file) is saved to the `/failed` folder. For example, `/amzn-s3-demo-bucket/AS2-folder/failed`. + The transferred file is stored in the `processed` folder as `original_filename.messageId.original_extension`. That is, the message ID for the transfer is appended to the name of the file, before its original extension. + A JSON file is created and saved as `original_filename.messageId.original_extension.json`. In addition to the message ID being added, the string `.json` is appended to the transferred file's name. + A Message Disposition Notice (MDN) file is created and saved as `original_filename.messageId.original_extension.mdn`. In addition to the message ID being added, the string `.mdn` is appended to the transferred file's name. + If there is an inbound file named `ExampleFileInS3Payload.dat`, the following files are created: + **File** – `ExampleFileInS3Payload.c4d6b6c7-23ea-4b8c-9ada-0cb811dc8b35@44313c54b0a46a36.dat` + **JSON** – `ExampleFileInS3Payload.c4d6b6c7-23ea-4b8c-9ada-0cb811dc8b35@44313c54b0a46a36.dat.json` + **MDN** – `ExampleFileInS3Payload.c4d6b6c7-23ea-4b8c-9ada-0cb811dc8b35@44313c54b0a46a36.dat.mdn` For outbound transfers, the naming is similar, with the difference that there is no incoming message file, and also, the transfer ID for the transferred message is added to the file name. The transfer ID is returned by the `StartFileTransfer` API operation (or when another process or script calls this operation). + The `transfer-id` is an identifier that is associated with a file transfer. All requests that are part of a `StartFileTransfer` call share a `transfer-id`. + The base directory is the same as the path that you use for the source file. That is, the base directory is the path that you specify in the `StartFileTransfer` API operation or `start-file-transfer` AWS CLI command. For example: ``` aws transfer start-file-transfer --send-file-paths /amzn-s3-demo-bucket/AS2-folder/file-to-send.txt ``` If you run this command, MDN and JSON files are saved in `/amzn-s3-demo-bucket/AS2-folder/processed` (for successful transfers), or `/amzn-s3-demo-bucket/AS2-folder/failed` (for unsuccessful transfers). + A JSON file is created and saved as `original_filename.transferId.messageId.original_extension.json`. + An MDN file is created and saved as `original_filename.transferId.messageId.original_extension.mdn`. + If there is an outbound file named `ExampleFileOutTestOutboundSyncMdn.dat`, the following files are created: + **JSON** – `ExampleFileOutTestOutboundSyncMdn.dedf4601-4e90-4043-b16b-579af35e0d83.fbe18db8-7361-42ff-8ab6-49ec1e435f34@c9c705f0baaaabaa.dat.json` + **MDN** – `ExampleFileOutTestOutboundSyncMdn.dedf4601-4e90-4043-b16b-579af35e0d83.fbe18db8-7361-42ff-8ab6-49ec1e435f34@c9c705f0baaaabaa.dat.mdn` You can also check the CloudWatch logs to view the details of your transfers, including any that failed. ## Status codes The following table lists all of the status codes that can be logged to CloudWatch logs when you or your partner send an AS2 message. Different message processing steps apply to different message types and are intended for monitoring only. The COMPLETED and FAILED states represent the final step in processing, and are visible in JSON files. **** | Code | Description | Processing completed? | | --- | --- | --- | | PROCESSING | The message is in the process of being converted to its final format. For example, decompression and decryption steps both have this status. | No | | MDN\$1TRANSMIT | Message processing is sending an MDN response. | No | | MDN\$1RECEIVE | Message processing is receiving an MDN response. | No | | COMPLETED | Message processing has completed successfully. This state includes when an MDN is sent for an inbound message or for MDN verification of outbound messages. | Yes | | FAILED | The message processing has failed. For a list of error codes, see [AS2 error codes](as2-monitoring.md#as2-error-codes). | Yes | ## Sample JSON files This section lists sample JSON files for both inbound and outbound transfers, including sample files for successful transfers and transfers that fail. Sample outbound file that is successfully transferred: ``` { "requester-content-type": "application/octet-stream", "message-subject": "File xyzTest from MyCompany_OID to partner YourCompany", "requester-file-name": "TestOutboundSyncMdn-9lmCr79hV.dat", "as2-from": "MyCompany_OID", "connector-id": "c-c21c63ceaaf34d99b", "status-code": "COMPLETED", "disposition": "automatic-action/MDN-sent-automatically; processed", "transfer-size": 3198, "mdn-message-id": "OPENAS2-11072022063009+0000-df865189-1450-435b-9b8d-d8bc0cee97fd@PartnerA_OID_MyCompany_OID", "mdn-subject": "Message be18db8-7361-42ff-8ab6-49ec1e435f34@c9c705f0baaaabaa has been accepted", "as2-to": "PartnerA_OID", "transfer-id": "dedf4601-4e90-4043-b16b-579af35e0d83", "file-path": "/amzn-s3-demo-bucket/as2testcell0000/openAs2/TestOutboundSyncMdn-9lmCr79hV.dat", "as2-message-id": "fbe18db8-7361-42ff-8ab6-49ec1e435f34@c9c705f0baaaabaa", "timestamp": "2022-07-11T06:30:10.791274Z" } ``` Sample outbound file that is unsuccessfully transferred: ``` { "failure-code": "HTTP_ERROR_RESPONSE_FROM_PARTNER", "status-code": "FAILED", "requester-content-type": "application/octet-stream", "subject": "Test run from Id da86e74d6e57464aae1a55b8596bad0a to partner 9f8474d7714e476e8a46ce8c93a48c6c", "transfer-size": 3198, "requester-file-name": "openAs2TestOutboundWrongAs2Ids-necco-3VYn5n8wE.dat", "as2-message-id": "9a9cc9ab-7893-4cb6-992a-5ed8b90775ff@718de4cec1374598", "failure-message": "http://Test123456789.us-east-1.elb.amazonaws.com:10080 returned status 500 for message with ID 9a9cc9ab-7893-4cb6-992a-5ed8b90775ff@718de4cec1374598", "transfer-id": "07bd3e07-a652-4cc6-9412-73ffdb97ab92", "connector-id": "c-056e15cc851f4b2e9", "file-path": "/amzn-s3-demo-bucket-4c1tq6ohjt9y/as2IntegCell0002/openAs2/openAs2TestOutboundWrongAs2Ids-necco-3VYn5n8wE.dat", "timestamp": "2022-07-11T21:17:24.802378Z" } ``` Sample inbound file that is successfully transferred: ``` { "requester-content-type": "application/EDI-X12", "subject": "File openAs2TestInboundAsyncMdn-necco-5Ab6bTfCO.dat sent from MyCompany to PartnerA", "client-ip": "10.0.109.105", "requester-file-name": "openAs2TestInboundAsyncMdn-necco-5Ab6bTfCO.dat", "as2-from": "MyCompany_OID", "status-code": "COMPLETED", "disposition": "automatic-action/MDN-sent-automatically; processed", "transfer-size": 1050, "mdn-subject": "Message Disposition Notification", "as2-message-id": "OPENAS2-11072022233606+0000-5dab0452-0ca1-4f9b-b622-fba84effff3c@MyCompany_OID_PartnerA_OID", "as2-to": "PartnerA_OID", "agreement-id": "a-f5c5cbea5f7741988", "file-path": "processed/openAs2TestInboundAsyncMdn-necco-5Ab6bTfCO.OPENAS2-11072022233606+0000-5dab0452-0ca1-4f9b-b622-fba84effff3c@MyCompany_OID_PartnerA_OID.dat", "server-id": "s-5f7422b04c2447ef9", "timestamp": "2022-07-11T23:36:36.105030Z" } ``` Sample inbound file that is unsuccessfully transferred: ``` { "failure-code": "INVALID_REQUEST", "status-code": "FAILED", "subject": "Sending a request from InboundHttpClientTests", "client-ip": "10.0.117.27", "as2-message-id": "testFailedLogs-TestRunConfig-Default-inbound-direct-integ-0c97ee55-af56-4988-b7b4-a3e0576f8f9c@necco", "as2-to": "0beff6af56c548f28b0e78841dce44f9", "failure-message": "Unsupported date format: 2022/123/456T", "agreement-id": "a-0ceec8ca0a3348d6a", "as2-from": "ab91a398aed0422d9dd1362710213880", "file-path": "failed/01187f15-523c-43ac-9fd6-51b5ad2b08f3.testFailedLogs-TestRunConfig-Default-inbound-direct-integ-0c97ee55-af56-4988-b7b4-a3e0576f8f9c@necco", "server-id": "s-0582af12e44540b9b", "timestamp": "2022-07-11T06:30:03.662939Z" } ``` # Customize HTTP headers for AS2 messages When sending AS2 messages to trading partners, you may need to customize the HTTP headers to meet specific requirements or enhance compatibility with your partner's AS2 server configuration. This CloudFormation template creates an infrastructure to enable customized HTTP headers for AS2 messages sent through AWS Transfer Family. It sets up an Amazon API Gateway and Lambda function to act as a proxy, allowing dynamic modification of headers required by trading partners' AS2 servers. Use this template to do the following: + Add custom HTTP headers to outbound AS2 messages + Override default header values with custom values **Important** Be careful when overriding default header values, as it can cause send failures: some AS2 headers are required. + Ensure compatibility with trading partners that have specific header requirements ## Template Overview The template creates the following main components: + A Lambda function that processes and forwards AS2 messages + An Amazon API Gateway to expose the Lambda function + IAM roles and permissions for the Lambda function + Conditional resources for HTTPS support The template file is available here: [Dynamic HTTP headers template](https://s3.amazonaws.com/aws-transfer-resources/as2-templates/dynamic-http-headers.template.yml). ## How It Works 1. The Amazon API Gateway receives incoming AS2 messages from AWS Transfer Family. 1. The request is forwarded to the Lambda function. 1. The Lambda function processes the request, adding or modifying headers as needed. 1. The modified request is then forwarded to the partner's AS2 server. 1. The response from the partner's server is returned through the Lambda and Amazon API Gateway back to AWS Transfer Family. ## Key Features + *Dynamic Header Modification:* Allows customization of the Subject header and addition of other required headers. + *Protocol Support:* Works with both HTTP and HTTPS protocols. + *Flexible Configuration:* Allows specification of partner host, port, and path. ## Implementation Details The template implements the following key components: ### Lambda Function The core of the solution is a Node.js Lambda function that: + Receives requests from the Amazon API Gateway + Modifies headers based on configuration and incoming request data + Forwards the modified request to the partner's AS2 server + Handles both HTTP and HTTPS protocols + Includes error handling and logging ### Amazon API Gateway An HTTP API is set up to: + Receive incoming AS2 messages + Route requests to the Lambda function + Return responses back to AWS Transfer Family ### Template parameters Enter information for the template parameters as follows. Note that all of these parameters are strings. + `Environment`: this parameter is used to name the resources that the template creates: whether they are intended for a development or production environment. Valid values are **dev** and **prod**. + `PartnerHost`: the IP address or hostname of the AS2 partner server. + `PartnerPort`: the port number for the AS2 partner server. If not specified, defaults to 80 for HTTP and 443 for HTTPS. + `PartnerPath`: the path to the AS2 endpoint on the partner server + `ProtocolType`: the protocol to use for the AS2 communication: valid values are **HTTP** and **HTTPS**. ### Conditional Resources For HTTPS support, the template conditionally creates: + A Lambda Layer for CA certificates + HTTPS-specific configuration in the Lambda function ## Deployment and Usage **To customize AS2 HTTP headers using a CloudFormation template** 1. Open the CloudFormation console at [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/). 1. In the left navigation pane, choose **Stacks**. 1. Choose **Create stack**, and then choose **With new resources (standard)**. 1. In the **Prerequisite - Prepare template** section, choose **Choose an existing template**. 1. Copy this link, [Dynamic HTTP headers template](https://s3.amazonaws.com/aws-transfer-resources/as2-templates/dynamic-http-headers.template.yml), and paste it into the **Amazon S3 URL** field. 1. Choose **Next**. 1. Fill in the parameter details with your information. These are detailed in [Template parameters](#as2-header-template-parameter-details). 1. Choose **Next**. On the **Configure stack options** page, choose **Next** again. 1. Review the details for the stack that you're creating, and then choose **Create stack**. **Note** At the bottom of the page, under **Capabilities**, you must acknowledge that CloudFormation might create AWS Identity and Access Management (IAM) resources. After deploying this CloudFormation stack: 1. Note the Amazon API Gateway endpoint URL provided in the stack outputs. 1. Update your existing AWS Transfer Family Connector to use this new Amazon API Gateway endpoint. 1. The solution will now handle AS2 messages, adding or modifying headers as configured. **Warning** Only modify the Subject header or add headers that your partner explicitly expects. Changing other headers may cause transfer failures. # Monitoring AS2 usage You can monitor AS2 activity using Amazon CloudWatch and AWS CloudTrail. To view other Transfer Family server metrics, see [Amazon CloudWatch logging for AWS Transfer Family servers](structured-logging.md) **AS2 metrics** | Metric | Description | | --- | --- | | InboundMessage | The total number of AS2 messages successfully received from a trading partner. Units: Count Period: 5 minutes | | InboundFailedMessage | The total number of AS2 messages that were unsuccessfully received from a trading partner. That is, a trading partner sent a message, but the Transfer Family server was not able to successfully process it. Units: Count Period: 5 minutes | | OutboundMessage | The total number of AS2 messages successfully sent from the Transfer Family server to a trading partner. Units: Count Period: 5 minute | | OutboundFailedMessage | The total number of AS2 messages that were unsuccessfully sent to a trading partner. That is, they were sent from the Transfer Family server, but were not successfully received by the trading partner. Units: Count Period: 5 minutes | | DaysUntilExpiry | The number of days until a Certificate expires determined by the `InactiveDate` set on the Certificate when importing. Units: Count Dimensions: `CertificateId`, `Description` (if provided) Period: 1 day For more information, see [AS2 certificate rotation](managing-as2-partners.md#as2-certificate-rotation). | ## AS2 Status codes The following table lists all of the status codes that can be logged to CloudWatch logs when you or your partner send an AS2 message. Different message processing steps apply to different message types and are intended for monitoring only. The COMPLETED and FAILED states represent the final step in processing, and are visible in JSON files. **** | Code | Description | Processing completed? | | --- | --- | --- | | PROCESSING | The message is in the process of being converted to its final format. For example, decompression and decryption steps both have this status. | No | | MDN\$1TRANSMIT | Message processing is sending an MDN response. | No | | MDN\$1RECEIVE | Message processing is receiving an MDN response. | No | | COMPLETED | Message processing has completed successfully. This state includes when an MDN is sent for an inbound message or for MDN verification of outbound messages. | Yes | | FAILED | The message processing has failed. For a list of error codes, see [AS2 error codes](#as2-error-codes). | Yes | ## AS2 error codes The following table lists and describes error codes that you might receive from AS2 file transfers. **AS2 error codes** | Code | Error | Description and resolution | | --- | --- | --- | | ACCESS\$1DENIED | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/transfer/latest/userguide/as2-monitoring.html) | Occurs when handling a `StartFileTransfer` request where any of the `SendFilePaths` are not valid or malformed. That is, the path is missing the Amazon S3 bucket name, or the path includes characters that aren't valid. Also occurs if Transfer Family fails to assume the access role or logging role.Ensure that the path contains a valid Amazon S3 bucket name and key name. | | AGREEMENT\$1NOT\$1FOUND | Agreement was not found. | Either the agreement was not found, or the agreement is associated with an inactive profile.Update the agreement within the Transfer Family server to include active profiles. | | CONNECTOR\$1NOT\$1FOUND | Connector or related configuration was not found. | Either the connector was not found, or the connector is associated with an inactive profile. Update the connector to include active profiles. | | CREDENTIALS\$1RETRIEVAL\$1FAILED | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/transfer/latest/userguide/as2-monitoring.html) | For AS2 Basic authentication, the secret must be formatted correctly. The following resolutions correspond to the errors listed in the previous column. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/transfer/latest/userguide/as2-monitoring.html) | | DECOMPRESSION\$1FAILED | Failed to decompress message. | Either the file sent is corrupt, or the compression algorithm is not valid. Resend the message and verify that ZLIB compression is used, or resend the message without compression enabled. | | DECRYPT\$1FAILED | Failed to decrypt message message-ID. Ensure that the partner has the correct public encryption key. | Decryption failed. Confirm that the partner sent a payload by using a valid certificate and that encryption was performed by using a valid encryption algorithm. | | DECRYPT\$1FAILED\$1INVALID\$1SMIME\$1FORMAT | Unable to parse enveloped mimePart. | MIME payload is either corrupt or in an unsupported SMIME format. The sender should make sure that the format they're using is supported, and then resend the payload. | | DECRYPT\$1FAILED\$1NO\$1DECRYPTION\$1KEY\$1FOUND | No matching decryption key found. | The partner profile did not have a certificate assigned that matched the message, or the certificates that matched the message are now expired or no longer valid. You must update the partner profile and ensure that it contains a valid certificate. | | DECRYPT\$1FAILED\$1UNSUPPORTED\$1ENCRYPTION\$1ALG | SMIME Payload Decryption requested using unsupported algorithm with ID: encryption-ID. | The remote sender has sent an AS2 payload with an unsupported encryption algorithm. The sender must choose an encryption algorithm that's supported by AWS Transfer Family. | | DUPLICATE\$1MESSAGE | Duplicate or double processed step. | The payload has a duplicate processing step. For example, there are two encryption steps. Resend the message with a single step for signing, compression, and encryption. | | ENCRYPT\$1FAILED\$1NO\$1ENCRYPTION\$1KEY\$1FOUND | No valid public encryption certificates found in profile: *local-profile-ID* | Transfer Family is attempting to encrypt an outbound message, but no encryption certificates are found for the local profile.Resolution options:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/transfer/latest/userguide/as2-monitoring.html) | | ENCRYPTION\$1FAILED | Failed to encrypt file file-name. | The file to be sent is not available for encryption. Verify that the file is in its expected AS2 location and that AWS Transfer Family has permission to read the file. | | FILE\$1SIZE\$1TOO\$1LARGE | File size is too large. | This occurs when sending or receiving a file that exceeds the file size limit. | | HTTP\$1ERROR\$1RESPONSE\$1FROM\$1PARTNER | *partner-URL* returned status 400 for message with ID=*message-ID*. | Communicating with the partner's AS2 server returned an unexpected HTTP response code. The partner might be able to provide more diagnostics from their AS2 server logs. | | INSUFFICENT\$1MESSAGE\$1SECURITY\$1UNENCRYPTED | Encryption is required. | The partner sent an unencrypted message to Transfer Family, which is not supported. The sender must use an encrypted payload. | | INVALID\$1ENDPOINT\$1PROTOCOL | Only HTTP and HTTPS are supported. | You must specify HTTP or HTTPS as the protocol in your AS2 connector configuration. | | INVALID\$1REQUEST | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/transfer/latest/userguide/as2-monitoring.html) | This error has several causes. The following resolutions correspond to the errors listed in the previous column. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/transfer/latest/userguide/as2-monitoring.html) | | INVALID\$1URL\$1FORMAT | Invalid URL format: URL | This occurs when you are sending an outbound message using a connector configured with a malformed URL. Ensure that the connector is configured with a valid HTTP or HTTPS URL. | | MDN\$1RESPONSE\$1INDICATES\$1AUTHENTICATION\$1FAILED | Not applicable | The receiver cannot authenticate the sender. The trading partner returns an MDN to Transfer Family with the [disposition modifier ](https://datatracker.ietf.org/doc/html/rfc4130#section-7.5.4) Error: authentication-failed. | | MDN\$1RESPONSE\$1INDICATES\$1DECOMPRESSION\$1FAILED | Not applicable | This occurs when the receiver cannot decompress the message contents. The trading partner returns an MDN to Transfer Family with the [disposition modifier ](https://datatracker.ietf.org/doc/html/rfc4130#section-7.5.4) Error: decompression-failed. | | MDN\$1RESPONSE\$1INDICATES\$1DECRYPTION\$1FAILED | Not applicable | The receiver cannot decrypt the message contents. The trading partner returns an MDN to Transfer Family with the [disposition modifier ](https://datatracker.ietf.org/doc/html/rfc4130#section-7.5.4) Error: authentication-failed. | | MDN\$1RESPONSE\$1INDICATES\$1INSUFFICIENT\$1MESSAGE\$1SECURITY | Not applicable | The receiver expects the message to be signed or encrypted, but it isn’t. The trading partner returns an MDN to Transfer Family with the [disposition modifier ](https://datatracker.ietf.org/doc/html/rfc4130#section-7.5.4) Error: insufficient-message-security.Enable signing and/or encryption on the connector to match the trading partner's expectations. | | MDN\$1RESPONSE\$1INDICATES\$1INTEGRITY\$1CHECK\$1FAILED | Not applicable | The receiver cannot verify content integrity. The trading partner returns an MDN to Transfer Family with the [disposition modifier ](https://datatracker.ietf.org/doc/html/rfc4130#section-7.5.4) Error: integrity-check-failed. | | PATH\$1NOT\$1FOUND | Unable to create directory *file-path*. The parent path could not be found. | Transfer Family is attempting to create a directory in the customer's Amazon S3 bucket, but the bucket is not found.Ensure that each path mentioned in the `StartFileTransfer` command contains the name of an existing bucket. | | SEND\$1FILE\$1NOT\$1FOUND | File path file-path not found. | Transfer Family can't locate the file in the send file operation. Check that the configured home directory and path are valid and that Transfer Family has read permissions for the file. | | SERVER\$1NOT\$1FOUND | Server associated with the message cannot be found. | Transfer Family could not find the server when receiving a message. This can happen if the server is deleted during the processing of an incoming message. | | SERVER\$1NOT\$1ONLINE | Server server-ID is not online. | The Transfer Family server is offline.Start the server so that it can receive and process messages. | | SIGNING\$1FAILED | Failed to sign file. | The file to be sent is not available for signing, or signing could not be performed. Verify that the file is in its expected AS2 location and that AWS Transfer Family has permission to read the file. | | SIGNING\$1FAILED\$1NO\$1SIGNING\$1KEY\$1FOUND | No certificate found for profile: local-profile-ID. | Attempting to sign an outbound message, but no signing certificates are found for the local profile.Resolution options:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/transfer/latest/userguide/as2-monitoring.html) | | UNABLE\$1RESOLVE\$1HOST\$1TO\$1IP\$1ADDRESS | Unable to resolve hostname to IP addresses. | Transfer Family is unable to perform DNS to IP address resolution on the public DNS server that is configured in the AS2 connector. Update the connector to point to a valid partner URL. | | UNABLE\$1TO\$1CONNECT\$1TO\$1REMOTE\$1HOST\$1OR\$1IP | Connection to endpoint timed out. | Transfer Family cannot establish a socket connection to the configured partner's AS2 server. Check that the partner's AS2 server is available at the configured IP address. | | UNABLE\$1TO\$1RESOLVE\$1HOSTNAME | Unable to resolve hostname hostname. | The Transfer Family server could not resolve the partner's hostname by using a public DNS server. Check that the configured host is registered and that the DNS record has had time to publish. | | VERIFICATION\$1FAILED | Signature verification failed for AS2 message message-ID or a MIC code did not match. | Check that the sender's signing certificate matches the signing certificates for the remote profile. Also check that the MIC algorithms are compatible with AWS Transfer Family. | | VERIFICATION\$1FAILED\$1NO\$1MATCHING\$1KEY\$1FOUND | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/transfer/latest/userguide/as2-monitoring.html) | AWS Transfer Family is attempting to verify the signature for a received message, but no matching signing certificate is found for the partner profile. Resolution options:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/transfer/latest/userguide/as2-monitoring.html) | # Certificate expiration monitoring AWS Transfer Family automatically monitors the expiration dates of AS2 certificates and publishes a Amazon CloudWatch metric to help you track when certificates are approaching expiration. This allows you to proactively manage certificate renewals and avoid service disruptions. ## DaysUntilExpiry metric When you import a certificate for AS2 use, Transfer Family automatically creates a CloudWatch metric called `DaysUntilExpiry`. This metric tracks the number of days remaining until the certificate expires based on the `InactiveDate` you specified when importing the certificate. **Metric details:** + **Metric name:** `DaysUntilExpiry` + **Namespace:** `AWS/Transfer` + **Dimensions:** `CertificateId` (always present), `Description` (if provided during certificate import) + **Units:** Count (days) + **Frequency:** Published daily **Important** It can take up to a full day after importing a certificate for Transfer Family to emit this metric to your account. The metric value decreases by one each day as the certificate approaches its inactive date. For example, if a certificate has 30 days until expiration, the metric will show 30, then 29 the next day, and so on. ## Best practices for certificate monitoring Follow these best practices when setting up certificate expiration monitoring: + **Set multiple alert thresholds:** Create alarms for different time periods (for example, 30 days, 14 days, and 7 days before expiration) to provide adequate time for certificate renewal. + **Use appropriate statistics:** Use the `Maximum` statistic when creating alarms to ensure you capture the most recent metric value. + **Configure proper alarm actions:** Set up notifications to alert the appropriate team members who can renew certificates. + **Test your alerts:** Regularly test your notification system to ensure alerts are delivered properly. + **Document your process:** Maintain documentation about your certificate renewal process and who is responsible for different certificates. ## Example alarm configurations Here are some example alarm configurations for different notification scenarios: ### 30-day expiration warning Create an alarm that triggers when a certificate has 30 days or fewer until expiration: + **Metric:** DaysUntilExpiry + **Statistic:** Maximum + **Period:** 1 day + **Threshold:** 30 + **Comparison:** Less than or equal to threshold + **Missing data treatment:** Treat missing data as good (not breaching) ### Critical 7-day expiration warning Create a critical alarm that triggers when a certificate has 7 days or fewer until expiration: + **Metric:** DaysUntilExpiry + **Statistic:** Maximum + **Period:** 1 day + **Threshold:** 7 + **Comparison:** Less than or equal to threshold + **Missing data treatment:** Treat missing data as good (not breaching)