Networked Media Open Specifications
HOME RECS... GITHUB WIKI FAQs IS-XX... MORE...

AMWA BCP-003-01: Securing communications in NMOS APIs

Scope

This document specifies how to secure communications used for HTTP and WebSocket communications within NMOS APIs.

This is based on best practice used for HTTPS, and is intended to promote a secure approach to interoperability.

The recommendations are also suitable for other APIs beyond NMOS.

Use of insecure communication (plain HTTP etc.) is forbidden within the scope of this document.

Fine-grained Client authorisation – providing a mechanism to determine what actions a Client may take against an API – is not in scope, but may be part of a future revision.

Use of HTTP/2 is not in scope, but may be part of a future revision.

Securing video and audio transport is not in scope.

Although security of web pages presented to users is also important, this is outside the scope of this document, which is concerned only with APIs.

Use of Normative Language

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL, “NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Normative References

These appear at the end of the Markdown source for this document, and are referenced as hyperlinks within the main body.

Definitions

See also the NMOS Glossary, and definitions within RFCs.

API

An HTTP / WebSocket API as defined in an AMWA NMOS Specification (IS-04, IS-05, IS-06, etc.)

Server

The entity that is providing the API, for example:

Client

The entity that is using the API, for example:

Message

Information sent according to an NMOS API, e.g.:

A Message can also carry payload data related to an NMOS API.

Introduction (informative)

The AMWA NMOS Interface Specfications use HTTP and WebSockets for API communications between Nodes, network services and control applications.

This document identifies best practice for providing these communications with:

This is achieved as follows:

A later document will cover authorisation, i.e. how the Server can determine whether the Client should be allowed to carry out the requested operation.

When used correctly HTTPS provides an excellent level of security. However it is important it is implemented well, with up-to-date versions, and in a way that will ensure cross vendor inter-operability. These recommendations only provide an overview of this rapidly-changing field, and readers should see Further Reading for more detail, and information about test software and other resources.

TLS

TLS Versions

Implementations SHOULD support TLS 1.3 and SHALL support TLS 1.2.

Note: TLS 1.3 has only recently been finalised, so is not yet mandatory here. However, implementors should be ready to upgrade, as 1.3 may be mandatory in a future revision.

Implementations SHALL NOT use TLS 1.0 or 1.1. These are deprecated.

Implementations SHALL NOT use SSL. Although the SSL protocol has previously been used to secure HTTP traffic, no version of SSL is now considered secure.

TLS 1.3 Cipher Suites

Note: TLS allows several different cipher suites; interoperability requires the Server and Client to support at least one common suite, which needs to be sufficiently secure.

This section applies to implementations using TLS 1.3. It is consistent with RFC 8446.

All Servers and Clients SHALL support this cipher suite:

TLS_AES_128_GCM_SHA256

All Servers SHOULD support the following cipher suites:

TLS_AES_256_GCM_SHA384

TLS_CHACHA20_POLY1305_SHA256

TLS 1.2 Cipher Suites

This section applies to implementations using TLS 1.2.

All Servers and Clients SHALL support this cipher suite:

TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8

All Servers SHOULD support the following cipher suites, unless hardware limitations make this impractical. In such a case Servers SHOULD support the first four listed suites, which are used with ECDSA certificates.

Servers SHOULD be configured to use the priority order listed:

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256

TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

TLS_DHE_RSA_WITH_AES_128_GCM_SHA256

TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

TLS_DHE_RSA_WITH_AES_128_CBC_SHA256

TLS_DHE_RSA_WITH_AES_256_CBC_SHA256

X.509 Certificates and Certificate Authority

Implementations SHALL use TLS with X.509 v3 certificates, as per RFC 5280.

A Certificate Authority (CA) SHOULD be available to sign certificates.

The CA root certificate SHALL be available to Servers and Clients.

Implementers SHOULD consider using a trusted CA service; if a self-managed CA is used it is important to keep its private key very safe.

If a CA cannot be provided, then “self-signed” certificates MAY be exchanged directly between Clients and Servers. However such an approach does not scale at all well beyond the simple case with a single Client and Server (e.g. a camera and and control unit), as it requires each Client and Server to be provisioned with the certifcate of each and every other party with which it communicates, and certificate revocation can be a significant overhead.

Wildcard certificates SHOULD NOT be used.

Certificates SHOULD contain the Subject Alternate Name extension. The Subject Alternate Name field SHOULD contain the Common Name, and any other names the server is known by, to ensure client compatibility.

Certificates SHOULD NOT use IP addresses as the Common Name or as a Subject Alternate Name.

There SHALL be a way of revoking Certificates that are no longer needed or compromised.

The CA SHOULD support OCSP requests as per RFC 6960 and OCSP stapling (see so that Clients can check whether certificates are compromised.)

Server Behaviour

Certificate Management: Server

Servers SHALL provide a means of installing X.509 certificates. These SHOULD be signed by the CA, unless “self-signed” certificates are being used

Servers SHALL support installation of multiple certificates, and SHALL support both RSA and ECDSA certificates.

Servers SHALL provide a secure mechanism to install and store the private key(s) and key chain for their certificates.

It SHOULD be possible for a user to perform the above operations.

HTTP: Server

Note: as discussed in the scope this applies to API requests. Secure presentation of web pages to users is not in scope.

Servers SHALL accept and respond to HTTPS requests, using a TLS version and cipher suite allowed by TLS

Servers SHALL NOT accept or respond to plain HTTP requests

Servers SHOULD use the Strict-Transport-Security header as per [RFC 6797] to declare that they only will communicate with secure connections.

Servers SHALL reject all requests not explicitly allowed by the API with HTTP response code 405 Method not allowed.

Servers SHALL validate all request payloads and reject those that are invalid with an appropriate 4xx Client Error code.

Servers SHOULD log invalid requests, to help check for broken/malicious clients.

Servers SHOULD NOT use SSL compression, as this has a known vulnerability.

Implementers SHOULD consider the impact of TLS Session Tickets (RFC 5077) on performance.

Implementers SHOULD be aware of OWASP’s recommendations on Server Protocol and Cipher Configuration.

Servers SHOULD be as specific as possible in the use of CORS.

WebSockets: Server

This section applies to Servers providing Messages through a WebSocket connection, for example for subscription to an AMWA IS-04 Query API.

Servers SHALL provide an encrypted WebSocket connection (wss: URL scheme), using a TLS version and cipher suite allowed by TLS

Note: this is default for IS-04 WebSocket subscriptions when using HTTPS for the Query API.

Servers SHALL NOT provided unencrypted WebSocket connection (ws: URL scheme).

Other Protocols: Server

Other protocols used for Messages SHOULD be secured using TLS, where this is supported.

Security of protocols where TLS is not available is outside the scope of this document. Security of ST 2110 streams is outside the scope of this document.

DNS-SD: Server

Servers SHALL support unicast DNS-SD to advertise their API endpoints.

Servers SHOULD NOT advertise multicast DNS-SD, except where a DNS server is not available.

Servers SHALL use a name listed in the Common Name and/or Subject Alternate Name fields of its certificate in DNS-SD advertisements whether unicast or multicast.

Client Behaviour

Certificate Management: Client

Clients SHALL provide a means of installing a root certificate, and SHALL use this to check the validity of Server certificates.

Clients SHALL provide a way of removing root certificates.

Client SHOULD use OCSP Stapling to identify revoked certificates.

It SHOULD be possible for a user to perform these operations.

HTTP: Client

Clients SHALL make API requests using HTTPS, using a TLS version and cipher suite allowed by TLS

Clients SHALL NOT make API requests using plain HTTP.

Clients SHALL NOT continue communication with a Server after a failed handshake, except with the express permission of the user.

WebSockets: Client

This section applies to Clients requesting WebSocket connections as part of an API, for example for subscription to an AMWA IS-04 Query API, or WebSocket connections for transport of data, for example AMWA IS-07 events.

Clients SHALL require encrypted WebSocket connections (wss:), using a TLS version and cipher suite allowed by TLS.

Clients SHALL NOT use unencrypted WebSocket connections (ws:).

Other Protocols: Client

Other protocols used for Messages SHOULD be secured using TLS, where this is supported.

DNS-SD: Client

Clients SHOULD use unicast DNS-SD in preference to multicast DNS-SD to find API endpoints from a Server.

Clients SHOULD NOT rely on DNS-SD announcements of Node API endpoints for correct operation.

Other Considerations

DHCP

In most cases DHCP will be available on the network. However, it is an insecure protocol and should not be considered as means of providing security without the other provisions of this document.

DNS

In most cases DNS will be available on the network. However in many cases it should be considered insecure, and should not be considered as means of providing security without the other provisions of this document.

Secure deployment of DNS is currently outside the scope of this document.

Recommendations for Future Interface Specifications

Creators of new AMWA Interface Specifcations SHOULD ensure that the recommendations of this document are followed in the Specification itself.

Organisers of interoperabily testing of new Specifications SHOULD include tests of whether implementations meet the recommendations of this document.

All those involved in creating and testing new Specifications SHOULD be aware of the general recommendations and “Cheat Sheets” of the Open Web Application Security Project (OWASP). These go further than the scope of this document, and cover areas such as access control, security tokens, audit logs and carriage of sensitive information. See Further Reading.

Further Reading

The IETF RFCs referenced here provide much more information.

OWASP provides a number of useful “Cheat Sheets”, including REST Security and Transport Layer Protection.

BBC R&D White Papers 337 and 338 provide more information about securing NMOS APIs with TLS and PKI, and many references to online resources and test tools. 337 also discusses IPv6.

“Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile”