TLS Configuration
WARNING: This information is part of a limited availability release. Portions of this API may be subject to changes and improvements over time. Fields marked deprecated may be removed in the future and their use is discouraged. For more information, see our product and feature lifecycle descriptions.
TLS configurations are a collection of TLS settings that together represent your access to a set of IP pools. If you have access to multiple sets of IP pools, you can apply different configuration options to your TLS enabled domains using the Subscriber Provided Prefix (SPP) product.
You can also view your TLS configurations in the web interface.
Limitations and considerations
- IPv4 only and dual-stack controls only work if IPv6 prefixes are present.
- Cipher suites on TLS 1.3 are not configurable, by design.
- If you have multiple accounts accessing BYOIP configuration:
- Fastly configures access to this functionality on the primary customer account. If you need access on other accounts you own, reach out to Fastly Support and include the customer ID for the accounts on which you want to enable access.
- Once other customer IDs are added, IP configurations can be created in the BYOIP space by any of the customers in the set of customer IDs associated with the BYOIP address space or vipspace. When a customer ID creates a configuration, they take ownership of the object and only that customer ID can further edit the configuration.
- Responses currently include an attribute titled
bulk
. This refers to the bulk TLS API and can be ignored for SPP purposes.
Advanced configuration
The following are advanced options of the Subscriber Provided Prefix product. Contact Fastly Support to to enable any of these options.
Setting default certificates
Fastly serves a default certificate any time a TLS client does not provide Server Name Indication (SNI) information in the TLS handshake. Fastly also serves the default certificate any time SNI information is present, but no match is found for the domain provided in the TLS client hello extension information we receive.
This feature allows you to indicate a default ECDSA and RSA certificate when using self-managed certificates. If no SNI match is found, Fastly will first check if the client supports ECDSA. If it does, Fastly sends the fallback ECDSA certificate. If there is no SNI match and the client does not support ECDSA, Fastly sends the RSA fallback certificate.
Specifying an IP address to be assigned
This feature allows you to specify the IP address assigned to a Fastly TLS configuration when being created.
When creating a new TLS configuration, you can request to assign a valid IPv4 address from your prefix ranges, a feature useful for existing address assignment plans. If present, IPv6 addresses will continue to be derived automatically.
A new attribute listed below is the configurable DNS records relationship. All other listed attributes are already available in the SPP API product. When making POST requests, submit the DNS records relationship as an array of one IPv4 address. DNS records may also be retrieved on TLS configurations using GET and including DNS records, which may then contain an array of more than one IPv4 address.
Cipher suites
Fastly’s cipher suite support lets you identify the preferred set of encryption and key-exchange algorithms to be applied in a specific order on the Fastly servers, when a client makes a request for content.
Refer to the documentation for a list of supported cipher suites. When configuring, for TLS 1.3 or 1.3+0RTT, use the attribute named tls_1_3_cipher_suite_profile
(this is not configurable initially). For TLS-1.2, TLS-1.1, and TLS-1.0, use tls_1_2_cipher_suite_profile
.
Note the following:
- Fastly's TLS terminator (and QUIC terminator) use an implementation described as "server preference" when selecting a cipher suite during connection setup. Every client presents a list of cipher suites it supports and the server prefers the first cipher suite in its own list that is also anywhere in the client's list.
- Cipher suites for TLS 1.3 or 1.3+0RTT are not editable as of October 2021 and any values received will be ignored.
- Future changes to the technically valid and Fastly-supported cipher suites are possible.
Customers with access to multiple sets of IP pools can apply different configuration options to their TLS-enabled domains.
Data model
http_protocols | array | HTTP protocols available on your configuration. At least one protocol is required:
http/1.1 is always supported and is required in the array.
http/2 is optionally supported in the array.
http/3 is optionally supported in the array. | |
name | string | A custom name for your TLS configuration. Optional, we will assign a value to this if none is provided. | |
tls_1_2_cipher_suite_profile | array | An ordered collection of OpenSSL-formatted cipher suite names used for TLS-1.0, TLS-1.1 and TLS-1.2 protocol versions. Note: Setting this field is an advanced feature that requires enablement by Fastly Support. | |
tls_protocols | array | TLS protocols available on your configuration. The following TLS protocols are supported: [“1.0”, “1.1”, “1.2”] [“1.0”, “1.1”, “1.2”, “1.3”] [“1.0”, “1.1”, “1.2”, “1.3+0RTT”] [“1.2”] [“1.2”, “1.3”] [“1.2”, “1.3+0RTT”]. | |
vipspace | string | A Fastly assigned name representing a set of network prefixes that are available for operations like acquiring TLS configurations.
This field is Required, and must be customer_assigned_vipspace . |
TLS configuration request object (create)
All of the attributes to create a TLS configuration.
http_protocols | array | HTTP protocols available on your configuration. At least one protocol is required:
http/1.1 is always supported and is required in the array.
http/2 is optionally supported in the array.
http/3 is optionally supported in the array. | |
name | string | A custom name for your TLS configuration. Optional, we will assign a value to this if none is provided. | |
relationships.default_certificate.id | string | Alphanumeric string identifying the default TLS certificate. | |
relationships.default_ecdsa_certificate.id | string | Alphanumeric string identifying the default ECDSA TLS certificate. | |
relationships.dns_records.id | string | The IPv4 address that will be used for your TLS configuration. Note: Setting this field is an advanced feature that requires enablement by Fastly Support. | |
tls_1_2_cipher_suite_profile | array | An ordered collection of OpenSSL-formatted cipher suite names used for TLS-1.0, TLS-1.1 and TLS-1.2 protocol versions. Note: Setting this field is an advanced feature that requires enablement by Fastly Support. | |
tls_protocols | array | TLS protocols available on your configuration. The following TLS protocols are supported: [“1.0”, “1.1”, “1.2”] [“1.0”, “1.1”, “1.2”, “1.3”] [“1.0”, “1.1”, “1.2”, “1.3+0RTT”] [“1.2”] [“1.2”, “1.3”] [“1.2”, “1.3+0RTT”]. | |
type | string | Resource type. [Default tls_configuration ] | |
vipspace | string | A Fastly assigned name representing a set of network prefixes that are available for operations like acquiring TLS configurations.
This field is Required, and must be customer_assigned_vipspace . |
TLS configuration response object
All of the attributes for retrieving a TLS configuration.
bulk | boolean | Signifies whether the configuration is used for Platform TLS or not. We will always assume for this product that the value for this is “false”, signifying you have full access to the main set of APIs for custom TLS certificates and TLS subscriptions, as well as the TLS management UI. Read-only. | |
created_at | string | Date and time in ISO 8601 format. Read-only. | |
default | boolean | Signifies whether or not Fastly will use this configuration as a default when creating a new TLS activation. Read-only. | |
http_protocols | array | HTTP protocols available on your configuration. At least one protocol is required:
http/1.1 is always supported and is required in the array.
http/2 is optionally supported in the array.
http/3 is optionally supported in the array. | |
id | string | Alphanumeric string identifying a TLS configuration. | |
name | string | A custom name for your TLS configuration. Optional, we will assign a value to this if none is provided. | |
relationships.default_certificate.id | string | Alphanumeric string identifying the default TLS certificate. | |
relationships.default_ecdsa_certificate.id | string | Alphanumeric string identifying the default ECDSA TLS certificate. | |
relationships.dns_records.id | string | The IP address or hostname of the DNS record. | |
relationships.service.id | string | Alphanumeric string identifying the service. | |
tls_1_2_cipher_suite_profile | array | An ordered collection of OpenSSL-formatted cipher suite names used for TLS-1.0, TLS-1.1 and TLS-1.2 protocol versions. Note: Setting this field is an advanced feature that requires enablement by Fastly Support. | |
tls_1_3_cipher_suite_profile | array | An ordered collection of OpenSSL-formatted cipher suite names used for TLS-1.3. If TLS-1.3 is selected, you will get the default list. Read-only. | |
tls_protocols | array | TLS protocols available on your configuration. The following TLS protocols are supported: [“1.0”, “1.1”, “1.2”] [“1.0”, “1.1”, “1.2”, “1.3”] [“1.0”, “1.1”, “1.2”, “1.3+0RTT”] [“1.2”] [“1.2”, “1.3”] [“1.2”, “1.3+0RTT”]. | |
type | string | Resource type. [Default tls_configuration ] | |
updated_at | string | Date and time in ISO 8601 format. Read-only. | |
vipspace | string | A Fastly assigned name representing a set of network prefixes that are available for operations like acquiring TLS configurations.
This field is Required, and must be customer_assigned_vipspace . |
TLS configuration request object (update)
All of the attributes to update a TLS configuration.
http_protocols | array | HTTP protocols available on your configuration. At least one protocol is required:
http/1.1 is always supported and is required in the array.
http/2 is optionally supported in the array.
http/3 is optionally supported in the array. | |
name | string | A custom name for your TLS configuration. Optional, we will assign a value to this if none is provided. | |
relationships.default_certificate.id | string | Alphanumeric string identifying the default TLS certificate. | |
relationships.default_ecdsa_certificate.id | string | Alphanumeric string identifying the default ECDSA TLS certificate. | |
tls_1_2_cipher_suite_profile | array | An ordered collection of OpenSSL-formatted cipher suite names used for TLS-1.0, TLS-1.1 and TLS-1.2 protocol versions. Note: Setting this field is an advanced feature that requires enablement by Fastly Support. | |
tls_protocols | array | TLS protocols available on your configuration. The following TLS protocols are supported: [“1.0”, “1.1”, “1.2”] [“1.0”, “1.1”, “1.2”, “1.3”] [“1.0”, “1.1”, “1.2”, “1.3+0RTT”] [“1.2”] [“1.2”, “1.3”] [“1.2”, “1.3+0RTT”]. | |
type | string | Resource type. [Default tls_configuration ] |