6 Requirements for secure API design

29.5013GPP5G SystemPrinciples and Guidelines for Services DefinitionRelease 18Stage 3TS

Tools: ARFCN - Frequency Conversion for 5G NR/LTE/UMTS/GSM

6.1 Introduction

This clause contains a list of security requirements for API design provided by SA3.

6.2 General

The following requirements are intended as general guidance for 3GPP Stage 3 work in order to specify secure protocols and APIs. As such, these guidelines are independent of the specific technology and shall be followed at all times.

– The valid format and range of values (when applicable) for each IE shall be defined unambiguously.

NOTE 1: Explicitly defining format and range of values not only helps to improve the security of a certain implementation, but also allows for reliable interoperability between different protocol implementations. Example: Defining a "lowercase string variable of length 10 and range [a..z]" is much more explicit that just defining a "string of length 10". There are known vulnerabilities such as a denial of service (resulting in the parser converting from a string representing an integer – an attacker can pass in an arbitrarily large integer and trigger an unhandled exception) and such leading to a heap corruption and crash (proof-of-concept available), or potentially remote code execution (no proof-of-concept known). Unicode literals also require special treatment when doing string comparisons to ensure that equivalent strings return true when compared.

– For each message the number of leaf IEs shall not exceed 16K. If a leaf IE is an array of a simple data type, then the whole array shall count as one leaf. If a leaf IE is a data structure or an array of data structures, then it shall be considered a branch, i.e. it shall not be counted as a leaf. The data structure’s (branch) attributes determine the number of leaves. For instance, a data structure with e.g. three attributes will count as three leaves.

– The maximum size of the JSON body of any HTTP request/response shall not exceed 16 million octets before compression is applied, if any.

NOTE 2: APIs need to be designed taking care to avoid a too large HTTP payload size for performance reasons.

– The maximum nesting depth of leaves shall not exceed 32. If a leaf IE is an array of a simple data type, then the whole array shall be considered as the first level of nesting. If a leaf IE is a data structure or an array of data structures, then it shall be considered a branch and the first level of nesting. The data structure’s attributes (leaves) shall be considered as the second level of nesting. For instance, a data structure with e.g. one attribute-A, which is also a data structure with e.g. one attribute-B, then attribute-B will make the third level of nesting.

NOTE 3: There are resource exhaustion attacks on JSON parsers. Defined maximum numbers of IEs, sizes and nesting depths allow implementations to know an upper bound of required resources. It also allows validation of incoming messages. Recursively processing nested objects leads to stack exhaustion and a denial of service bug.

– For data structures where values are accessible using names (sometimes referred to as keys), e.g. a JSON object, the name shall be unique. The occurrence of the same name (or key) twice within such a structure shall be an error and the message shall be rejected.

NOTE 4: Serialization schemes (e.g. JSON) can leave the handling of repeated names (keys) up to the implementer’s discretion. For example, for a repeated name an error can be raised, the pair can be ignored, or the first or last value read can be used, though there is no canonical order in which a parser should treat the data it receives. Failure to adhere to consistent handling rules can lead to vulnerabilities. From a security perspective rejecting objects with repeated names, rather than accepting according to some rule, is the more robust solution, and aids in identification of potentially malicious activity. There are known attacks with specially crafted malicious messages that are designed to confuse implementations of NFs to get fraudulent messages into a PLMN.

6.3 SBA-specific requirements

The following requirements shall be considered for every network function that implements a service-based interface.

– OpenAPI specifications are machine-readable JSON objects and can be used as the basis for re-configuring an NFs action when an API or message structure changes. Therefore, each OpenAPI specifications shall contain all necessary information to correctly and unambiguously parse the contents of the message body.

NOTE: Attacks often exploit corner cases and unspecified behavior in order to exploit a system. Traffic normalization counters this by either dropping traffic that is malformed or by forcing certain information elements to a "normal" value. Typically, this relates to inconsistent fields.

– 3GPP TS 33.501 [22] documents which type of information shall be confidentiality protected on the N32 interface. The fields where these types of information (e.g. SUPI) is contained may have different names. Even if the field names are different, the mechanism specified in clause 5.2.3.3 of 3GPP TS 29.573 [24] shall clearly identify the type of information carried in each IE and which information types shall be confidentiality protected.

Annex A (informative):
TS Skeleton Template

A TS Skeleton Template to be used as a starting point of drafting a 5G System SBI Stage 3 specification is available at the following location:

https://www.3gpp.org/ftp/information/All_Templates/29.xxx-SBI-Stage3-Template.zip

Annex B (informative):
Backward Incompatible Changes

This Annex provides information about the changes in the API that are considered as backwards compatible and those that are considered as backwards incompatible. This list is to be considered informative and it may be expanded in future releases, when necessary.

Backward compatible changes are additions or changes in the API that do not break the existing Service Consumer behaviour. Examples of backward compatible changes include:

– Adding a new, optional child resource/URI;

– Supporting a new HTTP method;

– Adding new elements to a resource representation;

– Changing the order of fields in a resource representation;

– Addition of a new status code:

NOTE 1: When a NF / NF Service receives a HTTP status code that it cannot recognize it will treat it as the corresponding x00 status code as specified in clause 5.2.7.3 of 3GPP TS 29.500 [2].

– Corrections of obvious errors in an OpenAPI file required to enable a correct parsing of the file such as misspelled references;

– Corrections that only relate to smaller and optional parts of the functionality (e.g. a supported feature, see 3GPP TS 29.500 [2] clause 6.6.2), even if the changes are backward incompatible with respect to that part of the functionality; and

NOTE 2: It is recommended to only apply corrections which are also backward compatible with respect to such smaller and optional parts of the functionality. If this is not possible a new supported feature can be introduced to enable a negotiation of the support of the correction, and the old corresponding supported feature can be marked as "withdrawn" in the table defining the supported features of an API.

– Backward-compatible changes related to the semantics (i.e. functional behaviour) specified for an API.

Changes in the API that do not result in any loss of existing functionality (i.e. functionality that works fine if both consumer and provider do not support the change) if only consumer or only provider implements the change can be considered as backwards compatible corrections or additions.

Backward incompatible changes are additions or changes in the API that break the existing Service Consumer behaviour. Here is a list of backward incompatible changes that shall require incrementing the 1^st field (MAJOR) of the API version number unless they only relate to smaller and optional parts of the functionality (see above):

– Removing a resource/URI:

– Removing support for an HTTP method;

– Renaming a field in a resource representation;

– Adding mandatory parameters to a resource URI or resource representation;

– Attribute data type changes;

– Cardinality changes (NOTE 3); and

NOTE 3: Whether attribute cardinality changes are backward compatible depend on the type of change. Examples of non-backward compatibility changes include decreasing the upper bound of a cardinality range for attributes sent by the NF service consumer, changing the meaning of the default behavior associated to the absence of an attribute of cardinality 0..N, etc.

– Backward incompatible changes related to the semantics (i.e. functional behaviour) specified for an API.

Changes in the API that result in loss of existing functionality (i.e. functionality that works fine if both consumer and provider do not support the change) if only consumer or only provider implements the change can be considered as backwards incompatible modifications.

When a change although being categorised as backwards compatible correction or addition results in interoperability issues, it is expected that the issue will be resolved by implementing the change at both consumer and provider.

Annex C (Informative):
Resource modelling