Dit document valt onder de volgende licentie:
Creative Commons Attribution 4.0 International Public License
Dit betreft een technische module is die een aantal eisen invult op het gebied van transport security & http security.
Dit is de definitieve conceptversie van dit document. Wijzigingen naar aanleiding van consultaties zijn doorgevoerd.
Dit onderdeel is niet normatief.
Dit Hoofdstuk geeft een inleiding op de Nederlandse API strategie. De stategie is opgebouwd uit meerdere documenten, standaarden en modulen. De NL API Strategie wordt doorontwikkeld en beheerd door het Kennisplatform API's.
Op GitHub kan bekeken worden wat de actuele ontwikkelingen zijn met betrekking tot de Nederlandse API strategie.
Er worden slechts een beperkt aantal auteurs genoemd, echter aan deze strategie is door veel meer mensen gewerkt. Per onderdeel van de API strategie staan de degene verantwoordelijk voor de laatste versie vermeld. De genoemde auteurs zijn deelnemers aan de relevante werkgroep van het Kennisplatform API's zoals: API Strategie, Architectuur, Security, Design Rules, Authenticatie en Autorisatie, Strategie en Beleid, en Gebruikerswensen.
De API strategie bestaat uit een een inleidend document, verschillende normatieve documenten (NL GOV standaarden) en meerdere modulen die voor verschillende functionele of technische situaties kunnen worden ingezet. Een actueel overzicht van alle documenten is weergegeven in de onderstaande infographic:
De verschillende onderdelen van de NL API Strategie bevat de volgende documenten:
Onderdeel | Documentnaam & Verwijzing naar de gepubliceerde versie |
Status | Versie |
---|---|---|---|
Algemeen | Inleiding NL API Strategie | Vastgesteld (door Kennisplatform) |
09-03-2022 |
Algemeen | Architectuur NL API Strategie | Vastgesteld (door Kennisplatform) |
09-03-2022 |
Algemeen | Gebruikerswensen NL API Strategie | Vastgesteld (door Kennisplatform) |
09-03-2022 |
Normatieve standaard | API Design Rules (ADR) | Verplicht (pas toe leg uit) |
09-07-2020 v1.0.0 |
Verplichte standaard | Open API Specification (OAS) | Verplicht (pas toe leg uit) |
25-05-2018 v3.0.0 |
Normatieve standaard | NL GOV OAuth profiel | Verplicht (pas toe leg uit) |
09-07-2020 v1.0.0 |
Voorgestelde standaard | NL GOV OpenID Connect profile | Verplicht (pas toe leg uit) |
18-02-2021 v1.0.0 |
Verplichte standaard | Digikoppeling REST API koppelvlak specificatie | Verplicht (pas toe leg uit) |
14-11-2022 v1.1.1 |
Aanvullende module | API Geospatial Design Rules module | Vastgesteld * (door Kennisplatform) |
23-05-2023 |
Aanvullende module | API Transport Security module | Stabiel * (Werkgroep Kennisplatform) |
11-07-2023 |
Aanvullende module | API Access control module | Stabiel (Werkgroep Kennisplatform) |
11-07-2023 |
Aanvullende module | API Naming conventions module | Stabiel (Werkgroep Kennisplatform) |
12-07-2023 |
Aanvullende module | API Hypermedia module | Stabiel (Werkgroep Kennisplatform) |
12-07-2023 |
This section describes security principles, concepts and technologies to apply when working with APIs. Controls need to be applied for the security objectives of integrity, confidentiality and availability of the API and services and data provided thereby. The (new draft of the) architecture section of the API strategy contains architecture patterns for implementing Transport security.
The scope of this section is limited to generic security controls that directly influence the visible parts of an API. Effectively, only security standards directly applicable to interactions are discussed here. In order to meet the complete security objectives, every implementer MUST also apply a range of controls not mentioned in this section.
Note: security controls for signing and encrypting of application level messages will be part of a separate extension, Signing and Encryption.
One should secure all APIs assuming they can be accessed from any location on the internet. Information MUST be exchanged over TLS-based secured connections. No exceptions, so everywhere and always. This is required by law. One SHOULD follow the latest NCSC guidelines for TLS
API-11: Secure connections using TLS
Secure connections using TLS following the latest NCSC guidelines [NCSC.TLS].
Since the connection is always secured, the access method can be straightforward. This allows the application of basic access tokens instead of encrypted access tokens.
Even when using TLS-based secured connections information in URIs is not secured. URIs can be cached and logged outside of the servers controlled by clients and servers. Any information contained in them should therfor be considered readable by anyone with access to the netwerk being used (in case of the internet the whole world) and MUST NOT contain any sensitive information. Neither client secrets used for authentication, privacy sensitive informations suchs as BSNs nor any other information which should not be shared. Be aware that queries (anything after the '?' in a URI) are also part of an URI.
API-58: No sensitive information in URIs
Do not put any sensitive information in URIs
Even when the connection is secure URIs can be cached and logged, in systems outside the control of client and/or server.
How to test Sensitive information URIS is not machine testable and therfor not part of automated tests. It should be part of any security audit performed by human experts.
The usage of TLS is machine testable. The test is designed for maximum automation. To test, adherence to NCSC reccomendations should be tested. The serverside is what will be tested, only control over the server is assumed for testing. A testing client will be employed to test adherence of the server. Supporting any protocols, algorithms, key sizes, options or ciphers dat are deemed insufficient or phase out by NCSC will lead to failure on the automated test. Both positive and negative scenario's are part of the test. Testing that a subset of good and sufficient reccomendations are supported and testing that phase out and insufficient reccomendations are not. A manual exception to the automated test results can be made when phase out reccomendations are supported. The API provider will have to provide clear documentation for the phase out schedule.
The guidelines and principles defined in this extension are client agnostic. When implementing a client agnostic API, one SHOULD at least facilitate that multi-purpose generic HTTP-clients like browsers are able to securely interact with the API. When implementing an API for a specific client it may be possible to limit measures as long as it ensures secure access for this specific client. Nevertheless it is advised to review the following security measures, which are mostly inspired by the OWASP REST Security Cheat Sheet
Even while remaining client agnostic, clients can be classified in four major groups. This is much in line with common practice in OAuth2. The groups are:
This section contains elements that apply to the generic classes of clients listed above. Although not every client implementation has a need for all the specifications referenced below, a client agnostic API SHOULD provide these to facilitate any client to implement relevant security controls.
Most specifications referenced in this section are applicable to the first three classes of clients listed above. Security considerations for native applications are provided in [OAUth2 for Native Apps]](https://tools.ietf.org/html/rfc8252), much of which can help non-OAuth2 based implementations as well. For browser-based applications a subsection is included with additional details and information. System-to-system (sometimes called machine-to-machine) may have a need for the listed specifications as well. Note that different usage patterns may be applicable in contexts with system-to-system clients, see above under Client Authentication.
security-headers: Use mandatory security headers in API all responses
Return API security headers in all server responses to instruct the client to act in a secure manner
There are a number of security related headers that can be returned in the HTTP responses to instruct browsers to act in specific ways. However, some of these headers are intended to be used with HTML responses, and as such may provide little or no security benefits on an API that does not return HTML. The following headers SHOULD be included in all API responses:
Header | Rationale |
---|---|
Cache-Control: no-store |
Prevent sensitive information from being cached. |
Content-Security-Policy: frame-ancestors 'none' |
To protect against drag-and-drop style clickjacking attacks. |
Content-Type |
To specify the content type of the response. This SHOULD be application/json for JSON responses. |
Strict-Transport-Security |
To require connections over HTTPS and to protect against spoofed certificates. |
X-Content-Type-Options: nosniff |
To prevent browsers from performing MIME sniffing, and inappropriately interpreting responses as HTML. |
X-Frame-Options: DENY |
To protect against drag-and-drop style clickjacking attacks. |
Access-Control-Allow-Origin |
To relax the 'same origin' policy and allow cross-origin access. See CORS-policy below |
Note that strict transport security is not only mandated by this module but also by law.
The headers below are only intended to provide additional security when responses are rendered as HTML. As such, if the API will never return HTML in responses, then these headers may not be necessary. However, if there is any uncertainty about the function of the headers, or the types of information that the API returns (or may return in future), then it is RECOMMENDED to include them as part of a defense-in-depth approach.
Header | Rationale |
---|---|
Content-Security-Policy: default-src 'none' |
The majority of CSP functionality only affects pages rendered as HTML. |
Feature-Policy: 'none' |
Feature policies only affect pages rendered as HTML. |
Referrer-Policy: no-referrer |
Non-HTML responses SHOULD not trigger additional requests. |
In addition to the above listed HTTP security headers, web- and browser-based applications SHOULD apply Subresource Integrity SRI. When using third-party hosted contents, e.g. using a Content Delivery Network, this is even more relevant. While this is primarily a client implementation concern, it may affect the API when it is not strictly segregated or for example when shared supporting libraries are offered.
How to test The precense of the mandatory security headers can be tested in an automated way. A test client makes a call to the API root. The response is tested for the precense of mandatory headers.
API-50: Use CORS to control access
Use CORS to restrict access from other domains (if applicable).
Modern web browsers use Cross-Origin Resource Sharing (CORS) to minimize the risk associated with cross-site HTTP-requests. By default browsers only allow 'same origin' access to resources. This means that responses on requests to another [scheme]://[hostname]:[port]
than the Origin
request header of the initial request will not be processed by the browser. To enable cross-site requests API's can return a Access-Control-Allow-Origin
response header. It is RECOMMENDED to use a whitelist to determine the validity of different cross-site request. To do this check the Origin
header of the incoming request and check if the domain in this header is on the whitelist. If this is the case, set the incoming Origin
header in the Access-Control-Allow-Origin
response header.
Using a wildcard *
in the Access-Control-Allow-Origin
response header is NOT RECOMMENDED, because it disables CORS-security measures. Only for an open API which has to be accessed by numerous other websites this is appropriate.
How to test Tests of this design rule can only be performed when the intended client is known to the tester. A thest can be performed when this information is provided by the API provider. Otherwise no conclusive test result can be reached.
A specific subclass of clients are browser-based applications, that require the presence of particular security controls to facilitate secure implementation. Clients in this class are also known as user-agent-based or single-page-applications (SPA). As with the (draft) OAuth 2.0 for Browser-Based Apps, browser-based application can be split into three architectural patterns:
All browser-based application SHOULD follow the best practices specified in OAuth 2.0 for Browser-Based Apps.
Apply a whitelist of permitted HTTP Methods e.g. GET
, POST
, PUT
. Reject all requests not matching the whitelist with HTTP response code 405 Method not allowed
.
A REST request or response body SHOULD match the intended content type in the header. Otherwise this could cause misinterpretation at the consumer/producer side and lead to code injection/execution.
406 Unacceptable
or 415 Unsupported Media Type
.@consumes("application/json"); @produces("application/json")
. This avoids XXE-attack vectors for example.It is common for REST services to allow multiple response types (e.g. application/xml
or application/json
, and the client specifies the preferred order of response types by the Accept header in the request.
Accept
header to the Content-type
header of the response.406 Not Acceptable
response) if the Accept header does not specifically contain one of the allowable types.Services (potentially) including script code (e.g. JavaScript) in their responses MUST be especially careful to defend against header injection attack.
application/json
and not application/javascript
.HTTP defines status codes. When designing a REST API, don't just use 200
for success or 404
for error. Always use the semantically appropriate status code for the response.
Realizations may rely on internal usage of HTTP-Headers. Information for processing requests and responses can be passed between components, that can have security implications. For instance, this is commonly practices between a reverse proxy or TLS-offloader and an application server. Additional HTTP headers are used in such example to pass an original IP-address or client certificate.
Implementations MUST consider filtering both inbound and outbound traffic for HTTP-headers used internally. Primary focus for inbound filtering is to prevent injection of malicious headers on requests. For outbound filtering, the main concern is leaking of information.