TLS/SSL with X.509 server certificate

The Bango Platform accepts HTTP API requests only over TLS/SSL, on the standard HTTPS port 443. Only TLS 1.2 and above, using modern cipher suites, is supported. The Bango Platform does not accept requests over plain HTTP. When a client connects to a server over any network, it needs to be able to trust that it’s not connected to a malicious impersonator or proxy. From the client’s perspective trust is achieved by successfully authenticating the server using an X.509 certificate passed by the server to the client when first establishing a connection, which is part of the TLS handshake. Bango services will always provide an X.509 certificate to the connecting client. The client performs a series of checks on the certificate to decide whether it is authentic and therefore a Bango service. If the client decides that the certificate is not trusted for that server, it immediately terminates the connection. When creating your client, we strongly recommend that you use a trusted third-party library to perform these checks and do not attempt to create your own implementation, as any mistakes may introduce vulnerabilities that can be exploited by attackers or cause authentication to fail when it shouldn’t. There are also best practices that the client should adhere to, to ensure minimal disruption to service availability. Conversely, there are also several inappropriate checks that the client may be tempted to perform but must be avoided to mitigate the risk of unnecessary failures. It is important to ensure that if authentication fails then the client will cease communication with the server and thus service will be unavailable to the client until authentication issues are resolved. Certificates are created in a chain: the server certificate is one end followed by intermediate certificates and finally at the other end is one or more certificate authorities, also known as roots. Clients will already have a copy of the root certificate and required intermediate certificates, which will be issued by a well-known certificate authority, such as Digicert or Let’s Encrypt. The server may also present an intermediate certificate in addition to the server certificate during the TLS handshake. Except for the root, each certificate in the chain is digitally signed by the next certificate in the chain, terminating at the root. The root certificate is self-signed, which means that the private key used to sign the certificate is the same as the public key contained within the certificate.

​

Appropriate Checks

Your client must carry out all of the following checks. If any of these fail, then your client must abort the connection and not proceed to send any data to an untrusted, potentially malicious, third party. If this happens persistently then contact Bango support.

​

Certificate subject matches hostname

The client must check that the server certificate presented contains the fully qualified domain name of the server it is attempting to connect to. This domain name will be one of the subject alternative names (subjectAltName). The value type for this field must be DNS. For example: when accessing our Resale product APIs, the subject alternative name or subjectAltName field must contain an entry with type DNS and value resale.api.bango.net.

​

Certificate Validity Period

All certificates define a validity period, which is contained within two fields: notBefore and notAfter. If the client’s clock is set to outside of this period, the check will fail, so you should ensure that your client’s clock is set accurately. Validity periods of all certificates in the chain must be checked.

​

Certificate Signature

This is the most important check and the most complex but will be implemented by third-party libraries within your client, so you just need to ensure that it’s enabled. The client must check that the digital signature on each certificate in the chain is authentic and was created with the corresponding private key to the signer public key contained within the certificate. All certificates in the chain must be checked. The root certificate will be self-signed and must already be in the client’s certificate authority store.

​

Inappropriate Checks

Certificates that Bango services present may change at any time. The validity of the certificate presented should be established only using the appropriate checks described above. Below is a list of checks and processes that you must not implement in your client. Performing these checks will cause eventual failures in your client to trust Bango services and cause Bango’s services to appear to be unavailable to you.

​

Distinguished Name Match

You must not rely on a specific value in the Distinguished Name field on any certificate. Bango or the certificate authority may change the Distinguished Name on the certificate any point.

​

Public Key Match

You must not attempt to match the public key of any certificate against a previously seen value. The public key of the certificate will change at each renewal.

​

Certificate Fingerprint/Thumbprint Match

You must not attempt to match any certificate’s fingerprint against a previously seen value. The fingerprint is unique to a certificate because it’s calculated by taking all properties of the certificate and generating a number from those values. The certificate fingerprint will change at each renewal.

​

Certificate Authority Match

Bango may change the certificate authorities or intermediates used in the chain at any time. Changing intermediates must have no impact on your client. We will provide a notification of a forthcoming certificate authority (root certificate) where possible. An exception will be if a CA is compromised, and we must make an emergency change. We will only use well-known certificate authorities that appear in Mozilla’s list of CAs.