GC HTTPS Everywhere/Implementation Guidance

From wiki
< GC HTTPS Everywhere
Revision as of 13:32, 26 April 2019 by Tim.allardyce (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
GC HTTPSEverywhere
ITPIN 2018-01 Implementation Strategy Implementation Guidance Communication Material


ITPIN Implementation Guidance

The following sections provide guidance to departments in meeting the requirements outlined in the ITPIN 2018-01.

Questions? Join the conversation on GCmessage (#HTTPSEverywhere-HTTPSpartout) or contact TBS Cyber Security at ZZTBSCYBERS@tbs-sct.gc.ca with any issues/concerns related to HTTPS implementation.

Compliance Checklist

Required Actions

Departments are required to:

  1. Ensure implementation of HTTPS meets the secure connection standard:
    1. All connection endpoints (servers, load balancers, proxies, etc) are configured to offer TLS 1.2 or above;
    2. All web servers support HSTS;
    3. Any remaining SHA-1 certificates are immediately replaced with SHA-256 certificates from a GC trusted Certificate Authority (CA);
    4. SSLv2, SSLv3, TLS 1.0, and TLS 1.1 protocols are disabled on all connection endpoints (servers, load balancers, proxies, etc);
    5. 3DES and RC4 ciphers are disabled on all connection endpoints (servers, load balancers, proxies, etc); and
    6. Any HTTP connections are automatically redirected to HTTPS, or disabled altogether.
  2. Newly developed websites and web services must adhere to this ITPIN upon launch.
  3. Websites and web services that involve an exchange of personal information or other sensitive information must receive priority following a risk-based approach, and migrate as soon as possible.
  4. All remaining websites and web services must be accessible through a secure connection, as outlined in Section 6.1, by December 31, 2019.

Departments should consider an HTTPS architecture that allows network security services to function, including web application firewalls (WAF) and network intrusion detection systems (NIDS), when traffic is encrypted. This will usually involve the placement of an SSL (TLS) offloading solution to decrypt HTTPS traffic, typically in the form of appliances or an onboard service on the existing appliances, in front of web servers; or the installation of software-based WAF or NIDS on the web servers where the traffic is decrypted for business processing.

It is recommended that departments should assess any existing SSL offload solution for capacity when applicable, or that they use centrally provided services such as those from Shared Services Canada if they do not have a solution capable of HTTPS inspection to monitor the security of their websites.

Note: The use of HTTPS is encouraged on intranets, but not explicitly required.

TBS Actions

TBS will:

  • Collaborate with Communications Security Establishment (CSE), Shared Services Canada (SSC), and Canadian Digital Services (CDS) services for tracking and verifying progress;
  • Establish automated tools to support compliance monitoring to the ITPIN; and
  • Provide additional guidance through other engagements and products following the issuance of this ITPIN.
Web Server Configuration


Departments should make use of CSE-approved protocols, as outlined in: CSE’S ITSP.40.062 Guidance on Securely Configuring Network Protocols. Per CSE guidance ITSP.40.062: TLS servers and clients should be configured to use TLS 1.2 as specified in RFC 5246 The Transport Layer Security (TLS) Protocol Version 1.2 [9]. Older versions of TLS and all versions of Secure Sockets Layer (SSL) should not be used since vulnerabilities exist.

A broad overview of the use of TLS is provided in the draft NIST Securing Web Transactions: TLS Server Certificate Management Special Publication (SP 1800-16 (DRAFT)). Detailed TLS configuration guidance for both servers and clients is similarly provided in NIST Special Publication (SP) 800 52 Rev 1 Guidelines on the Selection, Configuration, and Use of Transport Layer Security (TLS) Implementations. Note that NIST SP 800-52 Rev 2 draft is available for review, but has yet to be formally published.

Departments are encouraged to make use of the Mozilla server configurator as a means to develop modern configuration scripts, in addition to the tools available at SSL Labs to test public facing web servers for security level and compatibility:

Departments who have retained responsibility for management of network architecture are recommended to review CSE guidance in setting up external web application servers: Baseline Security Requirements for Network Security Zones in the Government of Canada (https://www.cse-cst.gc.ca/en/node/268/html/15236)

Redirect Domains

Many domains are currently in use across the GC as a means to provide easy access to specific pages to users, for marketing purposes, or as a proactive measure to protect against phishing and cybersquatting (the act of registering domains you don't intend to actually use, with the hopes of selling for profit). When a specific domain directs users to another domain, they are considered redirect domains.

For a redirect domain to be ITPIN compliant, they need to be secured prior to permanent redirection to the eventual (secure) destination domain. Since each URL has to resolve at the server before being redirected, they are still open to manipulation if HTTP. When a domain isn't properly secured internally first, it is impossible to provide an HSTS header for that domain, or achieve compliance against cipher and protocol requirements to be used.

For each of the redirected URLs, configuration should:

  1. first be permanently redirected to a secure version of itself, with HSTS enabled (http://domain-A --(301)--> https://domain-A (with HSTS)); and then
  2. permanently be redirected (301) to the HTTPS version of the destination site, with HSTS established there as well (https://domain-A --(301)--> https://final-domain (with HSTS))

Visitors will only ever get the double redirect once due to HSTS. In setting up your certificate for your primary site, you can use the Subject Alternative Name (SAN) field to include all of your pointed URLs, rather than having to get certificates for each one. If necessary, I’d recommend looking at Let’s Encrypt (https://letsencrypt.org/) as a source of free automated certs that provide for a large number of SANs.

Note: when redirecting to Canada.ca, or another major GC platform you may not/do not have control over, the configuration of the eventual domain is not your responsibility, nor will the results for that domain be reflected in your domain results. Each domain must be configured appropriately to reach full compliance.

Additional References:

  1. .htaccess Generator
  2. CISAGOV-pshtt (Github) - fully explains redirects, defaults vs. enforces HTTPS measurement by domain-scan

TLS Cipher Suite Support

Departments should make use of CSE-approved cryptographic algorithms, as outlined in:

Departments should choose TLS cipher suites using ephemeral Diffie-Hellman (DH) and ephemeral Elliptic Curve Diffie-Hellman (ECDH) (those with DHE or ECDHE specified in the cipher suite name) since they provide perfect forward secrecy. When using a cipher suite that provides perfect forward secrecy, the compromise of a long-term private key used in deriving a subsequent session key does not cause the compromise of prior session keys.

About Cipher Suites

A cipher suite is a defined set of algorithms used to secure network connections between two end points (e.g.: user client and server). In the TLS handshake, cipher suites are presented by both the client and server as a means to agree on a communications scheme, and determine a common code to use. If the two end points can't decide on a cipher suite to use (incompatible lists), no connection will be made.

TLS 1.2 cipher suites include an initial key exchange algorithm, a bulk/message encryption algorithm, and a message authentication code, as in the example here: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

The meaning of this name is:

  • TLS defines the protocol that this cipher suite is for; it will usually be TLS.
  • ECDHE_ECDSA indicates the key exchange algorithm being used. The key exchange algorithm is used to determine if and how the client and server will authenticate during the handshake.
  • AES_256_GCM indicates the block cipher being used to encrypt the message stream, together with the block cipher mode of operation.
  • SHA384 indicates the message authentication algorithm which is used to authenticate a message.

Secure configuration advice recommendations

In general, when configuring servers:

  • Avoid SHA-1 in the TLS handshake. When configuring TLS 1.2, it is suggested to specify SHA256 or SHA384 for cipher suite simplification and consistency with the hash function used for signature digest. Though there is no known specific vulnerability in the use of SHA-1 as part of the TLS handshake, SHA-1 has been shown to be unacceptably weak for use as a signature algorithm for issued certificates.
  • Avoid RC4. RC4 has never been approved by CSE for the protection of GC information. Modern browsers no longer support RC4-based cipher suites, and servers should no longer need to be configured to support RC4.
  • Servers should be configured to ensure that the server and client ephemeral key-pairs (see PFS below) satisfy the key length requirements specified in ITSP.40.111.

For details on the TLS handshake, see The Illustrated TLS Connection.

In the following table, the first column lists all ciphers as found in cryptographic guidance provided in ITSP.40.111. Departments are recommended to consider configurations that exclusively support the cipher suites listed in the second column, while preparing for CCCS updates to guidance for use of modern cipher suites of the third column (eliminating known vulnerable ciphers, and introducing approved TLS 1.3 cipher suites), preferring them in the listed order:

Full ITSP.40.111 Cipher Suites Modified ITSP 40.111 Cipher Suites Target Cipher Suites (Publication Pending)
  • TLS_RSA_WITH_AES_128_GCM_SHA256; (2)
  • TLS_RSA_WITH_AES_256_GCM_SHA384; (2)
  • TLS_RSA_WITH_AES_128_CCM; (2)
  • TLS_RSA_WITH_AES_256_CCM; (2)
  • TLS_RSA_WITH_AES_128_CBC_SHA256; (2)
  • TLS_RSA_WITH_AES_256_CBC_SHA256; (2)
  • TLS_RSA_WITH_AES_128_CBC_SHA; (1)(2)(4)
  • TLS_RSA_WITH_AES_256_CBC_SHA; (1)(2)
  • TLS_RSA_WITH_AES_128_GCM_SHA256; (2)
  • TLS_RSA_WITH_AES_256_GCM_SHA384; (2)
  • TLS_RSA_WITH_AES_128_CCM; (2)
  • TLS_RSA_WITH_AES_256_CCM; (2)
  • TLS_RSA_WITH_AES_128_CBC_SHA256; (2)
  • TLS_RSA_WITH_AES_256_CBC_SHA256; (2)
  • TLS_RSA_WITH_AES_128_CBC_SHA; (1)(2)(4)
  • TLS_RSA_WITH_AES_256_CBC_SHA; (1)(2)
  • TLS_AES_256_GCM_SHA384 (5)
  • TLS_AES_128_GCM_SHA256 (5)
  • TLS_AES_128_CCM_SHA256 (5)
  • TLS_AES_128_CCM_8_SHA256 (5)

Recommended and prioritized (TLS 1.3):

  • TLS_AES_256_GCM_SHA384 (5)
  • TLS_AES_128_GCM_SHA256 (5)
  • TLS_AES_128_CCM_SHA256 (5)

Recommended and prioritized (TLS 1.2):


Sufficient (Exception Use Only) and prioritized (TLS 1.2):



  • (1) Departments are recommended to avoid ciphers suites using SHA-1 in the handshake for simplicity’s sake, to align with PKI guidance to use SHA-256 signed certificates.
  • (2) Departments are recommended to avoid using non-ephemeral cipher suites as much as possible, for future proofing (not included in TLS 1.3), and to ensure forward secrecy.
  • (3) While presently included in CSE guidance, the use of 3DES is not recommended in the context of HTTPS.
  • (4) Mandatory cipher suite for TLS 1.2 as specified in RFC 5246
  • (5) Approved TLS 1.3 cipher suite, as specified in RFC 8446. Note: The use of TLS_CHACHA20_POLY1305_SHA256 is not approved for use in the GC at this time. TLS_AES_128_CCM_8_SHA256 has been removed from the target cipher suites list as is no longer recommended for TLS 1.3.
  • (6) All Diffie-Hellman (DH/DHE) cipher suites must adhere to CSE guidance to use a minimum 2048-bit key.

Perfect Forward Secrecy (PFS)

Forward secrecy protects information sent over an encrypted HTTPS connection now from being decrypted later, even if the server’s private key is later compromised, through the use of different public/private key pairs each session. In TLS, forward secrecy is provided by choosing cipher suites that include the DHE and ECDHE key exchanges.

Departments should make use of CSE-approved DHE and ECDHE cipher suites that support Perfect Forward Secrecy, as strongly recommended in:

Note: TLS 1.3, the newest version of TLS, requires new connections to use forward secrecy by removing support for static RSA and DH key exchange.

  • The GC HTTPS dashboard for all external domains will note when a domain offers little or no forward secrecy.
  • cyber.gc.ca is configured to offer robust forward secrecy.


HTTP/2 (finalized in 2015) is a backwards-compatible update to HTTP/1.1 (finalized in 1999) that is optimized for the modern web.

HTTP/2 includes many features that can drastically speed up website performance, and emerged from the advancements Google demonstrated with SPDY in 2009.

While HTTP/2 does not require the use of encryption in its formal spec, every major browser that has implemented HTTP/2 has only implemented support for encrypted connections, and no major browser is working on support for HTTP/2 over unencrypted connections.

This means that in practice, the major performance benefits of HTTP/2 first require the use of HTTPS.

TLS 1.3

Note: the use of TLS 1.3 must be accompanied with the understanding of how it impacts your security architecture, and use of network appliances. TLS 1.3 mandates an end-to-end secure connection, and may force changes in infrastructure and TLS termination points.

Forthcoming updates to the GC recommended cipher suites list will prioritize TLS 1.3 cipher suites over TLS 1.2.

TLS 1.3 differs from TLS 1.2 and earlier versions of TLS in several substantial ways, in addition to the cipher suite changes; these changes result in it not being directly compatible with the earlier versions of TLS. The following is a list of the major functional differences between TLS 1.2 and TLS 1.3. It is not intended to be exhaustive and there are many minor differences. [1]

  • The list of supported symmetric algorithms has been pruned of all algorithms that are considered legacy. Those that remain all use Authenticated Encryption with Associated Data (AEAD) algorithms. The cipher suite concept has been changed to separate the authentication and key exchange mechanisms from the record protection algorithm (including secret key length) and a hash to be used with the key derivation function and HMAC.
  • A 0-RTT mode was added, saving a round-trip at connection setup for some application data, at the cost of certain security properties. Admins should be aware of the security implications of 0-RTT, detailed in RFC 8446 Appendix E.5.
  • Static RSA and Diffie-Hellman cipher suites have been removed; all public-key based key exchange mechanisms now provide forward secrecy.
  • All handshake messages after the ServerHello are now encrypted. The newly introduced EncryptedExtension message allows various extensions previously sent in clear in the ServerHello to also enjoy confidentiality protection from active attackers.
  • The key derivation functions have been re-designed. The new design allows easier analysis by cryptographers due to their improved key separation properties. The HMAC-based Extract-and-Expand Key Derivation Function (HKDF) is used as an underlying primitive.
  • Elliptic curve algorithms are now in the base spec and new signature algorithms. Recommended curve algorithms are found in the table below.
  • The TLS 1.2 version negotiation mechanism has been deprecated in favor of a version list in an extension. This increases compatibility with existing servers that incorrectly implemented version negotiation.
  • Session resumption with and without server-side state as well as the Pre-Shared Key (PSK)-based cipher suites of earlier TLS versions have been replaced by a single new PSK exchange. Where non-PSK
  • Updated references to point to the updated versions of RFCs, as appropriate (e.g., RFC 5280 rather than RFC 3280).

Recommended TLS 1.3 Supported Groups RFC Reference
secp256r1 RFC 8422
secp384r1 RFC 8422
secp521r1 RFC 8422
ffdhe2048 RFC 7919
ffdhe3072 RFC 7919
ffdhe4096 RFC 7919
ffdhe6144 RFC 7919
ffdhe8192 RFC 7919

The following list of TLS 1.3 signature algorithms conforms with ITSP.40.111:

Recommended TLS 1.3 Signature Algorithms RFC Reference
ecdsa_secp256r1_sha256 (0x0403) RFC 8446
ecdsa_secp384r1_sha384 (0x0503) RFC 8446
ecdsa_secp521r1_sha512 (0x0603) RFC 8446
rsa_pss_pss_sha256 (0x0809) RFC 8446
rsa_pss_pss_sha384 (0x080a) RFC 8446
rsa_pss_pss_sha512 (0x080b) RFC 8446
rsa_pss_rsae_sha256 (0x0804) RFC 8446
rsa_pss_rsae_sha384 (0x0805) RFC 8446
rsa_pss_rsae_sha512 (0x0806) RFC 8446
rsa_pkcs1_sha256 (0x0401) RFC 8446
rsa_pkcs1_sha384 (0x0501) RFC 8446
rsa_pkcs1_sha512 (0x0601) RFC 8446

For a complete list of major differences, see the Transport Layer Security (TLS) Protocol Version 1.3 specification, section 1.3.

Web Server Configuration Templates

For example templates of popular Web Server Configurations click here!


Given the wide range of configuration options available for TLS, we recommend that you regularly test the configuration of your web servers by running automated scans. There are a number of publicly available tools to help test the TLS configuration of your web or mail server. Some tools you may find useful are:

These scans will identify most common issues and configuration problems. They should not be seen as a replacement for skilled penetration testing of your services, but if you have already used tools such as these to help identify and mitigate common issues, then penetration testers will have more time to spend ensuring there are not more subtle or unique flaws in your service.

Search Engine Optimization (SEO)

In general, migrating to HTTPS improves a website’s own SEO and analytics.

  • As of August 2014, Google uses HTTPS as a ranking signal, which can improve search rankings.
  • Migrating to HTTPS will improve analytics about web traffic referred from HTTPS websites, as referrer information is not passed from HTTPS websites to HTTP websites.

Prior to HSTS taking effect, or preloading your domain, to make the migration as smooth as possible, and avoid taking a SEO ranking hit:

  • If possible, always choose to use a 301 redirect (signals permanent move) to redirect users from http:// to https://. Do not use a 302 redirect (signals temporary move), as this may negatively impact search rankings, since search engines will not formally replace your old HTTP site with HTTPS.
  • Use a canonical link element (<link rel="canonical">) to inform search engines that the “canonical” URL for a website uses https://. Ex: <link rel="canonical" href="https://example.gc.ca/folder/folder2/">

Additional References

There are a number of good guides that provide configuration advice for HTTPS:

In Mozilla’s advice on Server Side TLS, several TLS configurations are described (‘Modern’, ‘Intermediate’, and ‘Old’) that refer to some of the 'best' security settings possible, depending on the versions of the browsers that need to be supported. Supporting the ‘Old’ profile is risky and should be avoided, as it would mean supporting the insecure SSL protocol.

  1. Internet Engineering Task Force (IETF) TLS 1.3 Internet-Draft
Network and Security Appliances

Load Balancing and Reverse Proxies

Load balancers and reverse proxy servers are often implemented with TLS offloading or termination capabilities, and should be included in scope of HTTPS activities. All endpoints should be adequately configured to meet ITPIN requirements.

For device specific configuration guidelines, refer to your device manual.

F5 BIG-IP Specific Support

F5 Networks Logo

New: Teams managing F5s across the GC are recommended to review the SSC EDC ADC team F5 implementation guidance relevant to ITPIN 2018-01, available here:.

Pdf icon.png

Using SSL ciphers with BIG-IP Client SSL and Server SSL profiles
For information about using SSL ciphers with BIG-IP Client SSL (TLS) and Server SSL (TLS) profiles, refer to the articles in tables in the following article:

Enforce TLS 1.2 HTTPS communications with F5 BIG-IP SSL profiles
To enforce TLS 1.2 with F5 BIG-IP, use 'TLSv1_2' in the Ciphers field of the client SSL profile to limit all client side communications to protocols that use TLSv1.2. Refer to the following for the detailed step-by-step instructions:

  • https://support.f5.com/csp/article/K17370 (scroll down to section “Configuring the SSL profile to use a specific protocol“)
  • https://support.f5.com/kb/en-us/products/big-ip_ltm/manuals/product/bigip-system-ssl-administration-12-1-1/4.html (scroll down to section “Assigning SSL profiles to a virtual server”)

  • HTTPS Strict Transport Security (HSTS)

    HTTP Strict Transport Security (HSTS)

    HSTS is a simple and widely supported standard to protect visitors by ensuring that their browsers always connect to a website over HTTPS. HSTS exists to remove the need for the common, insecure practice of redirecting users from http:// to https:// URLs.

    HSTS is also highly valuable as an organizational forcing function and compliance mechanism. When a domain owner sets an HSTS policy on its base domain with includeSubDomains and preload, the domain owner is saying '"Every part of our web infrastructure is HTTPS, and always will be."'

    When a browser knows that a domain has enabled HSTS, it does two things:

    • Always uses an https:// connection, even when clicking on an http:// link or after typing a domain into the location bar without specifying a protocol.
    • Removes the ability for users to click through warnings about invalid certificates
    • Note: HSTS headers set on HTTP endpoints are ignored by most browsers due to the potential for malicious headers to be injected, however are recognized on HTTPS endpoints.

    Types of HSTS

    Dynamic HSTS: Dynamic means that the browser has been instructed to enable HSTS by an HTTP response header (served over TLS) similar to the following:

    Strict-Transport-Security: max-age=31536000; includeSubDomains;

    This is vulnerable to an attack whereby the very first time the browser requests the domain with http:// (not https://) an adversary intercepts the communication.

    Static HSTS: In order to overcome this weakness we have the static mode which allows for hard-coding HSTS records directly into the browser's source. The header is changed to indicate the administrator's intention - note the inclusion of preload at the end:

    Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

    To enable HTTP Strict Transport Security (HSTS) to help the browser secure connections to your service; at least the first of the following two steps should be take, with preload only when ready:

    • add the Strict-Transport-Security HTTP header when the site is accessed over HTTPS - this instructs the browser to only request the HTTPS version in future (until the expiration time in the header elapses)
    • add your sites to the HSTS preload lists which modern browsers use to automatically redirect HTTP traffic to HTTPS (Chrome’s preload list is included in many of the other browsers’ lists)

    HSTS Considerations

    When moving to HSTS, bear in mind:

    • The policy should be deployed at https://domain.gc.ca, not your HTTP endpoint, nor https://www.domain.gc.ca, added to your .htaccess file.
    • In its simplest form, the policy tells a browser to enable HSTS for that exact domain or subdomain, and to remember it for a given number of seconds: Strict-Transport-Security: max-age=31536000; (1 year)
    • In its strongest and recommended form, the HSTS policy includes all subdomains, and indicates a willingness to be “preloaded” into browsers, pre-empting the need to visit via unsecure connection first:Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
    • All subdomains associated with the parent domain must be fully ready for HTTPS, e.g.: eliminating mixed content. (They do not have to each have their own HSTS policy.)
    • When starting with inclSubDomains, it is best to use a very short max-age time (e.g. 5 minutes - 300s) until you are sure your sub-domains are all fully compliant.

    When ready to preload a domain, departments' web teams are recommended to contact their IT Security teams for a review, prior to submitting the domain to the preload list, to ensure it meets the following requirements:

    • HTTPS is enabled on the site's root domain (e.g. https://domain.gc.ca), and all subdomains (e.g. https://www.domain.gc.ca) – especially the www subdomain, if a DNS record for it exists. This also includes any subdomains in use solely on intranets.
    • The HSTS policy includes all subdomains (inclSubDomains), with a long max-age (at least 1 year = 31536000s), and a header preload flag to indicate that the domain owner consents to preloading.
    • The website redirects from HTTP to HTTPS, at least on the site's root domain.

    Note: While preloading a domain is an easy proposition, backing out of preloaded status is not a simple task; be sure you are ready and want to preload your domain prior to doing so. Please ensure you read all of the details here before preloading. GC.ca will not be preloaded until such time that all subdomain (https://domain.gc.ca) sites are HTTPS and have HSTS enabled.

    Firefox, Safari, Opera, IE11 and Edge also incorporate Chrome’s HSTS preload list, making this feature shared across major browsers.

    HSTS Configuration for Common Web Servers

    Departments are encouraged to use the Mozilla configuration generator in developing HTST headers, referenced in Section 5, above.

    HSTS Configuration for WordPress

    For Wordpress, add the header info to the functions.php file.

    HSTS and Cookies

    When locking in the use of HTTPS through HSTS, cookies should be set with the Secure flag. The scope of the domain and path of the cookies should be set as restrictively as possible. This can help minimize damage from cross-site scripting (XSS) vulnerabilities, as cookies often contain session identifiers or other sensitive information.

    • Cookie names may be prepended with __Secure- to prevent cookies from being overwritten by insecure sources;
    • __Secure- prefix should be used for all cookies sent from secure origins (such as HTTPS).

    Additional References

    1. CISAGOV-pshtt (Github) - fully explains HSTS measurement by domain-scan
    2. HSTS Spec (IETF)
    3. Mozilla Configuration Generator
    4. HSTS Preload
    5. OWASP HSTS Cheat Sheet
    6. OWASP Secure Cookie page
    7. Browser support for HSTS
    8. HSTS web developer documentation maintained by the Mozilla community
    9. HSTS Cheat Sheet (Scott Helme)
    API / Web Service migration

    API Recommendations

    All APIs should use and require HTTPS to help guarantee confidentiality, authenticity, and integrity. HTTPS provides a stronger guarantee that a client is communicating with the real API and receiving back authentic contents. It also enhances privacy for applications and users using the API. For APIs that support cross-origin request sharing (CORS) or JSONP requests, it also ensures the requests are not blocked as mixed content. (https://w3c.github.io/webappsec-mixed-content/) All new APIs should use and require HTTPS. Rather than issue a redirect when visited over HTTP (redirects within APIs are problematic, as outlined below), the API should likely return an error message (such as the HTTP status code 403 Forbidden).

    Step Description
    1. Add HTTPS Support Once a certificate has been installed, test the API over HTTPS and make any needed programming or configuration adjustments. Enable HSTS for each successful API. Publish a dedicated information and resources page to help API users migrate their content to your HTTPS secure API.
    2. Measure HTTP and HTTPS Usage

    API statistics are key for measuring performance, seeing how others are using your API, and tracking usage over time. API usage over HTTP versus HTTPS should be tracked.

    3. Announce the deprecation

    Announce that HTTP has been deprecated at the endpoint of your API.

    4. Disable the HTTP Endpoint
    1. Announce any blackout tests ahead of time
    2. First, perform a “blackout test” by turning off the HTTP endpoint for a set time period
    3. Monitor the analytics and user complaints
    4. Refer complaining users to a dedicated page to encouraging them to migrate to your HTTPS service as soon as possible.
    5. It usually takes an upgrade to software libraries or to a few lines of code for an API integrator to switch to the HTTPS endpoint of an API
    6. As the analytics show increased compliance and fewer user complaints, try longer blackout periods, such as a few days to a week.
    7. Announce a deadline for when you will turn off the HTTP API if you have not yet done so.
    8. On the deadline date, disable the HTTP endpoint. Make an announcement, referring to your previous efforts to ensure a smooth transition and to your documentation, which includes a page on the migration.

    Add HTTPS Support to your APIs

    Following your system development life cycle and change process, acquire and installed a certificate, test the API over HTTPS and make any needed adjustments. Update your documentation to refer only to the HTTPS endpoint. Be sure to update all code examples, client libraries, sample applications, and your own applications (if you are an integrator of your own API). Update any pages, lists, or indexes that reference your API. Mark HTTP as deprecated in your documentation and strongly recommend migrating to the HTTPS endpoint. Publish a dedicated information and resources page to help API users migrate their content to your HTTPS secure API.

    Announce API HTTP Deprecation

    Announce that you have deprecated the HTTP endpoint of your API. Post this to your developer hub, blog, and/or mailing list. Optionally, include a deadline. If you have a method of contacting specific API integrators, such as an email address when they signed up for an API key, contact them. You may also have a list of known API-driven projects. Search the internet, and GitHub in particular, for references to the domain name or URL of your API, and your API’s documentation. Open issues on GitHub repositories about moving to the HTTPS endpoint, or even file a pull request making the change yourself.

    Measure API HTTPS Usage

    API analytics are key for measuring performance, seeing how others are using your API, and tracking usage over time. You should track usage of the API over HTTP versus HTTPS. If you have a way of identifying individual integrators, such as via an API key, application secret, or other submitted value, you can monitor their usage of HTTP versus HTTPS.

    Disable the API HTTP Endpoint

    This entire process could take anywhere from two weeks to six months or longer. You will want to weigh how widely used your API is, how critical it is, and how quickly integrators of your API tend to make adjustments. Questions to ask at this stage:

    • Does my API work over HTTPS?
    • Am I recommending HTTPS for my API?
    • Am I collecting useful information from API clients?

    In disabling, first step is to perform a “blackout test” by turning off the HTTP endpoint for a set time period; this period is usually somewhere between a few hours and a few days. Always announce any blackout tests ahead of time, and monitor your analytics and see what complaints this test sends your way. 'Optional: Pick a deadline for when you will turn off the HTTP API and include this in your announcement.' Refer blackout complainants to your HTTPS migration resources (published page) and encourage them to migrate as soon as possible. It usually takes a few lines of code or slight configuration change for an API integrator to switch to the HTTPS endpoint of an API, so do not be discouraged by negative feedback from disabling the HTTP endpoint. If you had no complaints, try a longer blackout, such as a few days to a week. Light API users may not have noticed the change in endpoint, and therefore need more of an opportunity to fail early, rather than once permanently changed. (This is especially helpful if you have no analytics and are relying on complaints as a metric.) You can conduct multiple blackouts if your analytics show they make a good improvement the number of integrators using HTTPS over HTTP, but be mindful of diminishing returns. Once satisfied with your approach and preparation for disabling the HTTP endpoing, announce a deadline for when you will turn off the HTTP API (if you have not yet done so). You can safely enable HSTS (//link to own content above) now, but do not redirect API traffic from HTTP to HTTPS. HSTS was primarily designed for web sites and is only supported in web browsers, not clients that would be used for integrating with APIs, and is a “future-proofing” step, in case you decide to provide browser access to your API in the future. As the API will continue to serve content over both HTTP and HTTPS, clients making HTTP requests to the API will continue to work until fully disabled. On the deadline, disable the HTTP endpoint. Make an announcement, referring your previous efforts to ensure a smooth transition and to your documentation, which includes a page on the migration.

    API Technical Considerations

    When turning off an HTTP endpoint, return an error in the same consumable manner with which your API would typically respond. Issue a clear error message, include a hyperlink if possible, and use an appropriate HTTP status code such as 403 Forbidden. Do not redirect HTTP to HTTPS: Redirects may break API clients as, unlike browsers, they may not be configured to automatically follow redirects. Even if they followed the redirect, many API clients will change a POST request into a GET request, breaking RESTful APIs, and introducing insecure behaviours. This incorrect behaviour is both common and well-documented. This is meant to apply to APIs that are RESTful or equivalent. If your API is actually a public dataset that is downloaded usually through a web browser, a redirect would likely be appropriate. (Note that HSTS could also handle this redirect for you.) Redirecting CORS Requests: Your API may support cross-origin resource sharing (CORS) through the use of Access-Control-Allow-Origin headers. While we recommend returning an error once an HTTP version of an API is shut down, you can optionally choose to redirect CORS requests, which is widely supported in web browsers. These web browsers will obey HSTS and the HSTS preload list, thus your choices are 1) break non-HTTPS CORS requests or 2) specially handle and redirect CORS requests.

    • First determine how widespread CORS requests are, what browsers make them, and ideally, what the referring URLs are (for ease of contacting the integrator).
    • Redirect to the HTTPS version of the API endpoint when the origin HTTP header is present to signify a CORS request. Note: CORS headers must be included in the redirect response, as well as the response to which the request is redirected.
    • CORS GET requests will not follow a redirect in Android before version 4.4, all versions of iOS, and all versions of Safari. This also applies to an HSTS “internal” redirect. If mobile browsers are not a major user, then forcing a redirect should go pretty smoothly.

    Redirecting JSONP Requests: Your API may support JSON with Padding (JSONP) requests, primarily due to users’ browsers still in use. Wherever possible, consider whether to support JSONP going forward, as it is not secure or performant. If you wish to handle all JSONP requests:

    • First determine how widespread JSONP requests are, what browsers make them, and ideally, what the referring URLs are (for ease of contacting the integrator).
    • Redirect to the HTTPS version of the API endpoint when the JSONP callback parameter for your API is present (usually ?jsonp= or ?callback=).
    • Note: enabling HSTS and submitting the domain to the HSTS preload list would be enough for browsers that support the preload list.

    Additional API References

    1. Mozilla guidance on CORS
    2. Mozilla guidance on JSON
    3. Why JSON is a Terrible Idea
    4. JSON vs. CORS code snippets
    Mixed Content Management

    Mixed Content Overview

    When an HTTPS website references insecure (HTTP) resources, this is called mixed content. Browsers prevent an HTTPS website from loading most insecure resources, like fonts, scripts, etc. Migrating an existing website from HTTP to HTTPS means identifying and fixing or replacing mixed content. Mixed content comes in two varieties:

    • Active mixed content includes resources that can greatly change the behaviour of a website, such as JavaScript, CSS, fonts, and iframes. Browsers refuse to load active mixed content, which often results in affected pages being completely unstyled or broken. Browsers treat these very aggressively because of the consequences if they were compromised. For example, a single compromised Javascript file compromises the entire website, regardless of how other resources are loaded.
    • Passive mixed content includes resources whose impact on the page’s overall behaviour is more minimal, such as images, audio, and video. Browsers will load passive mixed content, but will typically change the HTTPS indicator.

    Mixed Content: Migration strategy

    Every website’s mixed content situation will be different, but the general approach is:

    • Enable https:// for your website, but don’t force a redirect. Continue to present the http:// version as the canonical URL to search engines.
    • Identify the most obvious and widespread pieces of mixed content by loading your website in a browser over https:// and observing breakages. Chrome, Opera, and Firefox will log any mixed content warnings to the console, which should point out necessary site-wide changes. Use these to secure your resource links (//name anchor to below).
    • After fixing them, tackle the long tail by scanning your code (//name anchor to below) and crawling your website (//name anchor to below).
    • Finally, force the redirect to HTTPS, turn on HSTS (//link to GC content), and tell search engines that your new URL starts with https://.

    Note: the below instructions use tools 'optimized for an OS X or Linux environment'. Documentation for Windows-based tools would be a welcome contribution to this guide.

    Mixed Content: Linking to resources securely

    Most commonly used third party services, such as Google Analytics or AddThis, will automatically adapt when migrating to HTTPS. Other services may require manual updates, but have an https:// version ready: <link href="https://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet"> Generally speaking, for content on your own domain, stick to site-relative URLs wherever possible: <img src="/media/my-picture.png" /> When migrating a site with a lot of user- or staff-submitted content (e.g. a blog), you may find media hot-linked from a third-party domain which doesn’t support HTTPS. This is a great opportunity to improve your website’s privacy and lessen your dependency on third parties, by copying those media files to your own server instead and hosting them yourself.

    Mixed Content: Scanning your code

    After identifying and fixing the obvious issues, you can scan your website’s files for leads. On a 'Mac or Linux-based system', grep is very handy:

    • Images and scripts: grep -r "src=\"http:" *
    • Stylesheets and fonts: grep -r "href=\"http:" * | grep "<link"
    • CSS imports and references: grep -r "url(\"http:" *
    • Finding links in JavaScript is more challenging, but you can look for all http: references and try to exclude hyperlinks in HTML or Markdown: grep -r "http:" | grep -v "href=\"http:" or grep -r "http:" | grep -v "](http:"

    Mixed Content: Crawling your website

    There are free apps and services that you can use to scan your website, however are limited to a certain number of pages. This limitation requires you to take action on issues discovered, and rescan for a subsequent set of issues to manage, or confirm all corrective actions have been taken. As a start, these services are a good option, and provide a quick leg up on manual review.

    Mixed-content-scan is a very handy command line tool that can crawl an http:// or https:// website to see if it contains any references to insecure resources. This is especially helpful if your content is primarily managed in a content management system.

    Mixed-content-scan requires PHP, and Composer. Once Composer is installed, you can run mixed-content-scan on your domain with the following command: mixed-content-scan https://sub.domain.gc.ca.

    You should see something like this:
    [2018-02-15 16:56:48] MCS.NOTICE: Scanning https://sub.domain.gc.ca/ [] []
    [2018-02-15 16:56:49] MCS.INFO: 00000 - https://sub.domain.gc.ca/ [] []
    [2018-02-15 16:56:49] MCS.INFO: 00001 - https://sub.domain.gc.ca/faq/ [] []
    [2018-02-15 16:56:49] MCS.INFO: 00002 - https://sub.domain.gc.ca/hsts/ [] []
    [2018-02-15 16:56:49] MCS.INFO: 00003 - https://sub.domain.gc.ca/resources/ [] []
    [2018-02-15 16:56:49] MCS.NOTICE: Scanned 4 pages for Mixed Content [] []

    Any discovered mixed content will be listed as a WARNING.

    You can also get the results as newline-separated JSON objects: mixed-content-scan https://sub.domain.gc.ca --format=json

    Mixed Content: Automatically detecting mixed content

    Site owners also have the option of using a Content Security Policy header that will instruct browsers to ping a given URL with information about any observed mixed content warnings.

    Mixed Content: Using a Content Security Policy (CSP)

    Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks, including Cross Site Scripting (XSS) and data injection attacks. These attacks are used for everything from data theft to site defacement or distribution of malware.

    • block-all-mixed-content: Will prevent the loading of insecure content from sources.
    • upgrade-insecure-content: Forces the upgrade of insecure connections to a secure source/connection.

    A CSP policy that only specified pinging for mixed content warnings might look like: Content-Security-Policy-Report-Only: default-src https:; report-uri https://example.com/reporting/endpoint CSP reporting, especially for larger services, is an advanced approach that will likely require planning and tuning by a dedicated development team. Some resources:

    • An engineer describes Twitter’s approach as of 2014.
    • Report-uri.io, which offers a hosted reporting URI for CSP violations (or public key pinning violations) and accompanying dashboard.
    • A newly developed CSP extension, Upgrade Insecure Requests, will instruct browsers to automatically upgrade referenced HTTP URLs to HTTPS URLs without triggering mixed content detection. This extension is not finalized, and as of June 2015 is only available in Chrome.

    CSP Reporting

    Browsers will post errors to a URL specified in the CSP header; should be set and configured over time, by fine tuning slowly. CSP reporting is essential to proper use of CSP, and can be deployed in report-only mode initially until the CSP rules are matured.

    CSP guidance / resources

    Mixed Content: Why do browsers block mixed content?

    If mixed content were not blocked, an attacker could control the main website by conducting a Man in The Middle (MiTM) attack against any of its active resources.

    Even with passive content like images, attackers can manipulate what the page looks like, and so the yellow-lock icon is intended to communicate that security has been weakened and user confidence should be reduced. In addition, an attacker will be able to read any cookies for that domain that does not have the __Secure- flag, and set cookies.

    When a website is accessible over http://, loading other insecure resources does not generate any sort of warning, and so websites operating over plain HTTP often accumulate many of these sub-resources.

    Mixed Content: Security considerations for third party content

    Incorporating or loading content from third party domains creates an additional attack vector. Third party resources should be vetted and managed through appropriate application of web security controls such as Sub-Resource Integrity (SRI) and a Content Security Policy (CSP) to mitigate the risk of compromise due to attacks on linked resources.

    Even if a page has all page elements loaded over HTTPS, variations in HTTPS configurations could result in security vulnerabilities. For example, if ‘foo.gc.ca’ loads a page element over HTTPS from ‘bar.com’ but ‘bar.com’ is not as exacting with its HTTPS/TLS configuration, the page element from ‘bar.com’ may allow injection of malicious software into the page.

    If ‘bar.com’ uses a TLS configuration that is known to be weak, a malicious network adversary may be able to modify or replace the page element to inject software that could read the page contents or, potentially exploit browser vulnerabilities and accomplish more global access to the client device. Accordingly, just as it’s important to regularly evaluate the HTTPS/TLS configuration of US government websites, it will be important to also evaluate the configurations of the domains that serve third-party page elements.

    Note that this is still a strict improvement over incorporating content from third party domains over unencrypted HTTP. Attacks on the privacy, integrity, and security of connections to third party domains over unencrypted HTTP are trivial.

    Certificate Recommendations and Guidance

    In support of the HTTPS Everywhere initiative, a recommendations document was developed for the purpose of identifying the minimum requirements for TLS server certificate type and content, issuing CA conformance and website responsibilities that apply to all externally facing GC websites. This effort was led by TBS OCIO in close collaboration with members of the HTTPS working group including CRA, CSE, ESDC and SSC.

    While there are many technical details within the report that are not captured in this brief summary, the most important recommendations are:

    • Domain Validated (DV) server certificates are recommended for use by GC public facing. While the use of Organization Validated (OV) and Extended Validation (EV) certificates is not prevented, DV certificates are preferred due to their lower cost, and ability to support automated certificate issuance, for the same level of security between the web browser and web server as OV/EV certificates.
    • The use of the free service provided by Let’s Encrypt is recommended for obtaining DV certificates combined with the use of compatible ACME certificate management agents (e.g.: https://digital.canada.ca/).
      • Note: This CA should be chosen by an organization who has the ability to manage their certificates, and does not need 3rd party support in the case of an outage. Let’s Encrypt is very much serve yourself.
      • Organizations should conduct a thorough assessment of the ACME agent chosen prior to installation, and as updates are made available.
    • Organization Validated (OV) certificates are not recommended for use, as they provide no brand or security benefits above DV certificates.
    • If used, EV certificates should be obtained from SSC (contact ssc.ssltls.spc@canada.ca) in order to take advantage of the reduced pricing from an approved CA vendor (Entrust).
    Le-logo-twitter.png Entrust site seal ssl.png For additional information, please see Recommendations for TLS Server Certificates for GC Public Facing Web Services or contact TBS-CIOB Cybersecurity (zzTBSCybers@tbs-sct.gc.ca)

    Enterprise Certificate Management

    Recently the National Institute of Standards and Technology released Special Publication 1800-16 Securing Web Transactions: TLS Server Certificate Management for public comment. This draft practice guide provides additional information for enterprises that rely on Transport Layer Security (TLS) to secure both customer-facing and internal applications, so they can better manage TLS server certificates by:

    • Defining operational and security policies; identifying roles and responsibilities
    • Establishing comprehensive certificate inventories and ownership tracking
    • Conducting continuous monitoring of certificate operational and security status
    • Automating certificate management to minimize human error and maximize efficiency on a large scale
    • Enabling rapid migration to new certificates and keys when cryptographic mechanisms are found to be weak, compromised or vulnerable

    Automated Certificate Management Engine (ACME)

    RFC 8555: Automatic Certificate Management Environment
    Public Key Infrastructure using X.509 (PKIX) certificates are used for a number of purposes, the most significant of which is the authentication of domain names. Thus, certification authorities (CAs) in the Web PKI are trusted to verify that an applicant for a certificate legitimately represents the domain name(s) in the certificate. As of this writing, this verification is done through a collection of ad hoc mechanisms. This document describes a protocol that a CA and an applicant can use to automate the process of verification and certificate issuance. The protocol also provides facilities for other certificate management functions, such as certificate revocation. For details, see the IETF document here: https://tools.ietf.org/html/rfc8555

    From the Datatracker, published 2019-03-12: https://datatracker.ietf.org/doc/rfc8555/

    CAs & PKIs that offer ACME certificates (as of April 2019):

    1. Buypass
    2. Let's Encrypt
    3. Entrust (Linux)
    4. GlobalSign
    5. Venafi
    6. Sectigo (formerly Comodo CA)


    Wildcard Certificates

    It is recognized that wildcard certificates offer several advantages and they may be used where appropriate, however it should be recognized that wildcard certificates may introduce certain risks depending on how they are used.

    • Sharing the same private key (certificate) among multiple web servers may introduce additional vulnerabilities that will need to be properly mitigated.
    • Compromise through theft of the private key (certificate) would allow an attacker to establish rogue websites that will appear to belong to the domain protected by the wildcard certificate.
    • Compromise of the private key renders all TLS sessions protected by that private key vulnerable; the use of a cipher suite supporting Perfect Forward Secrecy is recommended to avoid this issue.

    GC Website owners must ensure appropriate risk mitigation measures are in place to minimize the risk of private key compromise.

    • Use of FIPS 140-2 Level 2 or higher Hardware Security Modules is recommended where warranted by risk assessment or cost/benefit trade-off analysis.
    • In the absence of HSMs, risk mitigation measures should include effective monitoring and auditing of the system so that private key compromise can be detected as early as possible followed immediately with revocation of the associated server certificate.

    Per the Recommendations for TLS Server Certificates [PDF], “care must be exercised when using multi-domain and wildcard certificates to ensure collateral damage is minimized in the event of private key compromise. Copying the same private key to multiple web servers is strongly discouraged unless appropriate risk mitigation measures are in place such as using CSE approved Hardware Security Modules to protect the private key.”

    Download the Recommendations for TLS Server Certificates.pdf:

    Pdf icon.png

    HTTP Public Key Pinning (HPKP)

    HPKP has been deprecated, as of end of 2017.

    To defend against certificate misissuance, web developers should use Certificate Authority Authorization (CAA) and the Expect-CT header, including its reporting function. Expect-CT is safer than HPKP due to the flexibility it gives site operators to recover from any configuration errors, and due to the built-in support offered by a number of CAs.

    Implementation of the Expect-CT header can be undertaken as follows, with a 1 year expiry: http request Expect-CT: enforce, max-age=31536000, report-uri="https://example.com"

    Note: caution should be taken in implementing the Expect-CT header, as there is a risk of rendering your site unreachable if done wrong. In testing, it is recommended to deploy the header without the enforce element, and a max-age of 0 (zero). This arrangement will ensure that you don't block any connections with a bad certificate, however do send an error to the report-uri address (e.g.: email mailbox for simplicity's sake, or a script to handle the error and log/notify as required if desired). After testing for a period of time to provide assurance that everything still works as expected, you are able to enable the enforce directive, and increase the max-age (recommended to be 1 year - 31536000).

    Prior to enforcing Expect-CT, be sure that your CA uses the CT logs (as they should, per certificate recommendations).

    Set up for CAA is performed in the DNS record, explicitly naming which CA(s) are allowed to issue certificates for your website. SSL Mate has developed a very helpful tool to assist in the development of DNS entries for CAA, available here.

    TLS Attacks and Mitigations

    TLS Attacks and Mitigation: Overview

    Attacks on HTTPS connections generally fall into 3 categories:

    • Compromising the quality of the HTTPS connection, through cryptanalysis or other protocol weaknesses.
    • Compromising the client computer, such as by installing a malicious root certificate into the system or browser trust store.
    • Obtaining a “rogue” certificate trusted by major browsers, generally by manipulating or compromising a certificate authority.

    These are all possible, but for most attackers they are very difficult and require significant expense. Importantly, they are all targeted attacks, and are not feasible to execute against any user connecting to any website.

    By contrast, plain HTTP connections can be easily intercepted and modified by anyone involved in the network connection, and so attacks can be carried out at large scale and at low cost.

    Readers are recommended to reference the following sources for detailed information regarding TLS Attacks and Mitigations:

    Additional Considerations of HTTPS

    Additional Considerations of HTTPS

    Website Security

    To protect GC electronic networks, devices and information, the following is a non-exhaustive list of security considerations that can be implemented in a layered manner to support a defence-in-depth approach for web services and minimize opportunities for cyber attacks:

    • Deploy modern operating systems (OS) and applications that are maintained with supported, up-to-date, and tested versions of software.
    • Actively manage software vulnerabilities, including fixing known vulnerabilities quickly following a timely patch maintenance policy for OS and applications, and taking other mitigating steps, where patches can’t be applied.
    • Implement appropriate host-based protections to protect systems against both known and unknown malicious activity.
    • Minimize available services and control connectivity by removing or disabling all non-essential ports and services as well as removing unnecessary accounts from systems.
    • Enable system logging to improve the ability to detect and identify anomalous behaviours, perform system monitoring, and to assist with incident response and forensic analysis of compromised systems.
    • Carefully control and manage privileges assigned to users and administrators. Provide a reasonable (but minimal) level of system privileges and rights needed for their role.
    • Use strong authentication mechanisms (for example, multi-factor authentication) where possible to protect from unauthorized access.
    • Design web services so that they are protected from common security vulnerabilities such as SQL injection and others described in widely-used publications such as the Open Web Application Security * Project (OWASP) Top 10.

    For more information on best practices, refer to Communications Security Establishment’s (CSE’s) IT security advice and guidance.

    Additional Guidance: Website Security | US-CERT

    Additional References