API Gateway Client Technical Requirements

  1. Introduction

    This document outlines the technical requirements clients must adhere to when interacting with our RESTful API Gateway. The gateway can be reached either directly (gateway.api.berkeley.edu) or via an on-premise proxy (proxyapis.berkeley.edu). Direct connection is advised for lowest latencies–the proxy is made available for those clients hosted within private networks or behind strict firewalls.

  2. Client Requirements for Direct Connection

    Applicable when sending requests directly to the cloud native gateway at “gateway.api.berkeley.edu”

    1. Transport Layer Security (TLS) Version

      Clients must use an up-to-date version of TLS for secure communications:

      2.1.1. Clients must use TLS 1.2 or 1.3 for their requests.
      2.1.2. Clients should be capable of adopting future versions of TLS to ensure secure communication continuity.

    2. Support for TLS Cipher Suites

      Clients must support strong cipher suites to maintain high security standards:

      2.2.1. TLS 1.3
      • TLS_AES_128_GCM_SHA256 (0x1301) ECDH x25519
      • TLS_AES_256_GCM_SHA384 (0x1302) ECDH x25519
      • TLS_CHACHA20_POLY1305_SHA256 (0x1303) ECDH x25519

      2.2.2. TLS 1.2
      • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (0xc02f) ECDH x25519
      • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (0xc027) ECDH x25519
      • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (0xc030)   ECDH x25519
      • TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 (0xcca8)   ECDH x25519

    3. Public Key Infrastructure (PKI) and Root Certificates

      Clients must properly implement PKI and trust the Certificate Authority's (CA) root certificates for seamless certificate rotation. Note: modern server Operating Systems provide curated CA root certificate bundles that include required root certificates.

      2.3.1. Install and maintain a trust store containing our CA's root certificates: https://www.amazontrust.com/repository/
      2.3.2. Regularly update the trust store with the latest root certificates from our CA: https://www.amazontrust.com/repository/
      2.3.3. Validate the server's certificate chain up to the root certificate with every connection.

    4. Hypertext Transfer Protocol (HTTP) Version

      Clients must use an up-to-date version of HTTP:

      2.4.1. Clients must support HTTP 1.1 or 2.0.
      2.4.2. Be prepared to adopt future versions of HTTP as they become standard.

    5. Server Name Indication (SNI)

      Clients must support SNI, which allows serving multiple domains from a single IP address:

      2.5.1. Clients must include the SNI extension in the “Client Hello” message of their TLS negotiation.
      2.5.2. Clients must handle responses from different domains served over the same IP address.

    6. DNS Time To Live (TTL)

      Clients must respect the TTL values in DNS responses to ensure proper load balancing and service resolution:

      2.6.1. Clients must respect the TTL value and avoid making additional DNS queries during the TTL.
      2.6.2. Clients must clear the DNS cache and make a new DNS query once the TTL for a record has expired.

  3. Client Requirements for Proxy Connection

    Applicable when sending requests via the on-prem proxy at “proxyapis.api.berkeley.edu”

    1. Transport Layer Security (TLS) Version

      Clients must use an up-to-date version of TLS for secure communications:

      3.1.1. Clients must use TLS 1.2 or 1.3 for their requests.
      3.1.2. Clients should be capable of adopting future versions of TLS to ensure secure communication continuity.

    2. Support for TLS Cipher Suites

      Clients must support strong cipher suites to maintain high security standards:

      3.2.1. TLS 1.3
      • TLS_AES_128_GCM_SHA256 (0x1301) ECDH x25519
      • TLS_AES_256_GCM_SHA384 (0x1302) ECDH x25519
      • TLS_CHACHA20_POLY1305_SHA256 (0x1303) ECDH x25519

      3.2.2. TLS 1.2
      • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (0xc02f) ECDH x25519
      • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (0xc027) ECDH x25519
      • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (0xc030)   ECDH x25519
      • TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 (0xcca8)   ECDH x25519

    3. Public Key Infrastructure (PKI) and Root Certificates

      Clients must properly implement PKI and trust the Certificate Authority's (CA) root certificates for seamless certificate rotation. Note: modern server Operating Systems provide curated CA root certificate bundles that include required root certificates.

      3.3.1. Install and maintain a trust store containing our CA's root certificates: https://calnetweb.berkeley.edu/calnet-technologists/web-certificates
      3.3.2. Regularly update the trust store with the latest root certificates from our CA: https://calnetweb.berkeley.edu/calnet-technologists/web-certificates
      3.3.3. Validate the server's certificate chain up to the root certificate with every connection.

    4. Hypertext Transfer Protocol (HTTP) Version

      Clients must use an up-to-date version of HTTP:

      3.4.1. Clients must support HTTP 1.1 or 2.0.
      3.4.2. Be prepared to adopt future versions of HTTP as they become standard.

  4. Conclusion

    Adherence to the requirements outlined above is crucial for successful integration with our RESTful API Gateway. For clarification and further assistance, please contact our technical support team at eis-support.berkeley.edu.

    Note: This document may be updated as technology and security standards evolve. Just as EIS always strives to introduce new requirements in a collaborative manner, clients are expected to keep abreast of these changes to maintain their systems' compatibility with our API Gateway.