Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated method for identifying devices by IPv4 address #139

Merged
merged 17 commits into from
May 16, 2023
Merged

Updated method for identifying devices by IPv4 address #139

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
898362c
Update qod-api.yaml
eric-murray Apr 19, 2023
0968d79
Update qod-api.yaml
eric-murray Apr 19, 2023
d539627
Update qod-api.yaml
eric-murray Apr 19, 2023
286c5b0
Update qod-api.yaml
eric-murray Apr 20, 2023
0ae46ba
Update qod-api.yaml
eric-murray Apr 20, 2023
cced452
Update QoD_API.md
eric-murray Apr 20, 2023
510ebd8
Update QoD_API.md
eric-murray Apr 20, 2023
a48d615
Update code/API_definitions/qod-api.yaml
eric-murray Apr 21, 2023
3882c44
Update qod-api.yaml
eric-murray Apr 24, 2023
5b76e26
Merge branch 'camaraproject:main' into main
eric-murray May 5, 2023
6c53620
Update qod-api.yaml
eric-murray May 5, 2023
a011dea
Update QoD_API.md
eric-murray May 5, 2023
f76b89c
Update qod-api.yaml
eric-murray May 5, 2023
3a7027a
Update QoD_API.md
eric-murray May 5, 2023
0525029
Update qod-api.yaml
eric-murray May 5, 2023
a210979
Update qod-api.yaml
eric-murray May 9, 2023
2ff4b60
Update documentation/API_documentation/QoD_API.md
eric-murray May 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 80 additions & 22 deletions code/API_definitions/qod-api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,47 +57,59 @@ paths:
$ref: "#/components/schemas/ErrorInfo"
examples:
Generic400:
summary: Schema validation failed
summary: Some parameter combinations or parameter values provided are not schema compliant
value:
status: 400
code: INVALID_ARGUMENT
message: "Schema validation failed at ..."
PhoneNumberRequired:
summary: Phone number is required as part of device
DeviceMissing:
summary: Device must be specified
value:
status: 400
code: INVALID_ARGUMENT
message: "Expected property is missing: device.phoneNumber"
Ipv4AddressRequired:
summary: ipv4Address is required as part of device
message: "Expected property is missing: device"
InsufficientDeviceProperties:
summary: Device must be identified by at least one parameter
value:
status: 400
code: INVALID_ARGUMENT
message: "Expected property is missing: device.ipv4Address"
IpAddressRequired:
summary: Some IP address is required as part of device
message: "Insufficient properties specified: device"
InconsistentDeviceProperties:
summary: Device parameters provided identify different devices
value:
status: 400
code: INVALID_ARGUMENT
message: "Expected property is missing: device.ipv4Address or device.ipv6Address"
DevicePortsRequired:
summary: devicePorts is required
message: "Multiple inconsistent parameters specified: device"
CannotIdentifyDevice:
summary: No device can be identified from provided parameters
value:
status: 400
code: INVALID_ARGUMENT
message: "Expected property is missing: devicePorts"
QoSProfileRequired:
summary: qosProfile is required
message: "Unable to identify device from specified parameters: device"
InvalidDevicePublicPortValue:
summary: Invalid port specified for device public port
value:
status: 400
code: OUT_OF_RANGE
message: "Invalid port value specified: device.ipv4Address.publicPort"
ApplicationServerMissing:
summary: Application server must be specified
value:
status: 400
code: INVALID_ARGUMENT
message: "Expected property is missing: qosProfile"
DevicePortsRangesNotAllowed:
summary: Ranges at devicePorts are not allowed
message: "Expected property is missing: applicationServer"
QoSProfileMissing:
summary: Required QoS profile must be specified
value:
status: 400
code: INVALID_ARGUMENT
message: "Ranges not allowed: devicePorts"
message: "Expected property is missing: qosProfile"
InvalidDevicePortsRanges:
summary: Invalid port ranges specified for devicePorts
value:
status: 400
code: OUT_OF_RANGE
message: "Invalid port ranges specified: devicePorts"
"401":
$ref: "#/components/responses/Generic401"
"403":
Expand Down Expand Up @@ -223,6 +235,7 @@ components:
type: string
format: uuid
description: Session ID in UUID format

SessionInfo:
description: Session related information.
allOf:
Expand Down Expand Up @@ -253,6 +266,7 @@ components:
type: array
items:
$ref: "#/components/schemas/Message"

CreateSession:
description: Data type with attributes required for creating a session
type: object
Expand All @@ -276,6 +290,7 @@ components:
$ref: "#/components/schemas/ApplicationServer"
devicePorts:
$ref: "#/components/schemas/PortsSpec"
description: The ports used locally by the device for flows to which the requested QoS profile should apply. If omitted, then the qosProfile will apply to all flows between the device and the specified application server address and ports.
applicationServerPorts:
$ref: "#/components/schemas/PortsSpec"
qosProfile:
Expand All @@ -293,10 +308,12 @@ components:
- device
- applicationServer
- qosProfile

Port:
type: integer
minimum: 0
maximum: 65535

PortsSpec:
type: object
minProperties: 1
Expand Down Expand Up @@ -328,6 +345,7 @@ components:
- 5070
description: |
Ports may be specified as a list of ranges or single ports.

QosProfile:
type: string
enum:
Expand Down Expand Up @@ -401,10 +419,11 @@ components:
networkAccessIdentifier:
$ref: "#/components/schemas/NetworkAccessIdentifier"
ipv4Address:
$ref: "#/components/schemas/Ipv4Address"
$ref: "#/components/schemas/DeviceIpv4Addr"
ipv6Address:
$ref: "#/components/schemas/Ipv6Address"
description: Device identifier
description: One or more parameters allocated to the device that allow it to be identified

ApplicationServer:
type: object
minProperties: 1
Expand All @@ -414,14 +433,49 @@ components:
ipv6Address:
$ref: "#/components/schemas/Ipv6Address"
description: Application server identifier

NetworkAccessIdentifier:
type: string
example: "[email protected]"

PhoneNumber:
type: string
pattern: '^\+?[0-9]{5,15}$'
example: "123456789"
description: Subscriber number in E.164 format (starting with country code). Optionally prefixed with '+'.
description: Subscriber number (MSISDN) in E.164 format, starting with country code and optionally prefixed with '+'.

DeviceIpv4Addr:
type: object
properties:
publicAddress:
$ref: "#/components/schemas/SingleIpv4Addr"
privateAddress:
$ref: "#/components/schemas/SingleIpv4Addr"
publicPort:
$ref: "#/components/schemas/Port"
anyOf:
- required: [publicAddress, privateAddress]
- required: [publicAddress, publicPort]
example:
{
"publicAddress": "84.125.93.10",
"publicPort" : 59765
}
description: |
The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers).

If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress.

If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object)

In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone.

SingleIpv4Addr:
type: string
description: A single IPv4 address with no subnet mask
example: "84.125.93.10"
pattern: '^(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])$'

Ipv4Address:
type: string
format: ipv4
Expand All @@ -432,6 +486,7 @@ components:
- address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule.
- address/mask - an IP number as above with a mask width of the form 1.2.3.4/24.
In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version.

Ipv6Address:
type: string
format: ipv6
Expand All @@ -447,6 +502,7 @@ components:
- address/mask - an IP v6 number with a mask:
- 2001:db8:85a3:8d3::0/64
- 2001:db8:85a3:8d3::/64

Message:
type: object
properties:
Expand All @@ -460,6 +516,7 @@ components:
required:
- severity
- description

QosStatus:
type: string
enum:
Expand All @@ -470,6 +527,7 @@ components:
* `REQUESTED` - QoS has been requested by creating a session
* `AVAILABLE` - The requested QoS has been provided by the network
* `UNAVAILABLE` - The requested QoS cannot be provided by the network due to some reason

ErrorInfo:
type: object
required:
Expand Down
46 changes: 26 additions & 20 deletions documentation/API_documentation/QoD_API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Security access keys such as OAuth 2.0 client credentials used by client applica
Latency or throughput requirements of the application mapped to relevant QoS profile class.

**Identifier for the device**
At least one identifier for the device (user equipment) out of four options: IPv4 address, IPv6 address, Phone number, or Network Access Identifier [[5]](#5) assigned by the mobile network operator for the device.
At least one identifier for the device (user equipment) out of four options: IPv4 address (either public IP address and port, or public and private IP address), IPv6 address, Phone number, or Network Access Identifier [[5]](#5) assigned by the mobile network operator for the device.

**Identifier for the application server**
IPv4 and/or IPv6 address of the application server (application backend)
Expand Down Expand Up @@ -117,12 +117,12 @@ Following table defines API endpoints of exposed REST based for QoD management o
<td>
<p>The identifier for the device (user equipment). The developer can choose to provide the below specified device identifiers:</p>
<ul>
<li>ipv4Address: IPv4 address (supports mask) e.g. 192.168.0.1/24</li>
<li>ipv6Address: IPv6 address (supports mask) e.g. 2001:db8:85a3:8d3:1319:8a2e:370:7344</li>
<li>phoneNumber (including country code and optionally could be prefixed by "+" sign) e.g. 004912345678923</li>
<li>networkAccessIdentifier <a href="#5">[5]</a> assigned by the mobile network operator (MNO) for the device. e.g. [email protected]</li>
<li><b>ipv4Address</b>: Either public IPv4 address and port e.g. 84.125.93.10:59765, or public and private IPv4 addresses e.g. 84.125.93.10 & 192.168.0.1. The public IPv4 address alone is generally insufficient to identify the device. Subnet masks are not necessary or supported.</li>
<li><b>ipv6Address</b>: IPv6 address (supports mask) e.g. 2001:db8:85a3:8d3:1319:8a2e:370:7344</li>
<li><b>phoneNumber</b>: The device phone number, including country code and optionally prefixed by a "+" sign, e.g. 004912345678923</li>
<li><b>networkAccessIdentifier</b> <a href="#5">[5]</a> assigned by the mobile network operator (MNO) for the device. e.g. [email protected]</li>
</ul>
<p>NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device</p>
<p>NOTE: The MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST identify the same device</p>
</td>
</tr>
<tr>
Expand All @@ -137,7 +137,7 @@ Following table defines API endpoints of exposed REST based for QoD management o
</tr>
<tr>
<td><b>devicePorts (optional)</b></td>
<td>A list of single ports or port ranges on the device,<br> e.g. "devicePorts": {"ranges": [{"from": 5010,"to": 5020}],"ports": [5060,5070]}</td>
<td>The ports used locally by the device for flows to which the requested QoS profile should apply. If omitted, then the qosProfile will apply to all flows between the device and the specified application server address and ports.<br> e.g. "devicePorts": {"ranges": [{"from": 5010,"to": 5020}],"ports": [5060,5070]}</td>
</tr>
<tr>
<td><b>applicationServerPorts (optional)</b></td>
Expand Down Expand Up @@ -176,6 +176,9 @@ Following table defines API endpoints of exposed REST based for QoD management o
<tr>
<td><b>400: Invalid input</b></td>
</tr>
<tr>
<td><b>400: Out of range</b></td>
</tr>
<tr>
<td><b>401: Un-authorized</b></td>
</tr>
Expand Down Expand Up @@ -317,19 +320,22 @@ Following table provides an overview of common error names, codes, and messages

| No | Error Name | Error Code | Error Message |
| --- | ---------- | ---------- | ------------- |
|1 |400 | INVALID_INPUT | "Expected property is missing: device.msisdn" |
|2 |400 | INVALID_INPUT | "Expected property is missing: device.ipv4Address" |
|3 |400 | INVALID_INPUT | "Expected property is missing: device.ipv4Address or device.ipv6Address" |
|4 |400 | INVALID_INPUT | "Expected property is missing: devicePorts" |
|5 |400 | INVALID_INPUT | "Expected property is missing: qosProfile" |
|6 |400 | INVALID_INPUT | "Ranges not allowed: devicePorts" |
|7 |401 | UNAUTHORIZED | "No authorization to invoke operation" |
|8 |403 | FORBIDDEN | "Operation not allowed" |
|9 |404 | NOT_FOUND | "Session Id does not exist" |
|10 |409 | CONFLICT | "Another session is created for the same device" |
|11 |500 | INTERNAL | "Session could not be created" |
|12 |501 | NOT_IMPLEMENTED | "Service not implemented for the specified user device" |
|13 |503 | SERVICE_UNAVAILABLE | "Service unavailable" |
|1 |400 | INVALID_ARGUMENT | "Schema validation failed at ..." |
|2 |400 | INVALID_ARGUMENT | "Expected property is missing: device" |
|3 |400 | INVALID_ARGUMENT | "Insufficient properties specified: device" |
|4 |400 | INVALID_ARGUMENT | "Multiple inconsistent parameters specified: device" |
|5 |400 | INVALID_ARGUMENT | "Unable to identify device from specified parameters: device" |
|6 |400 | INVALID_ARGUMENT | "Expected property is missing: applicationServer" |
|7 |400 | INVALID_ARGUMENT | "Expected property is missing: qosProfile" |
|8 |400 | OUT_OF_RANGE | "Invalid port value specified: device.ipv4Address.publicPort" |
|9 |400 | OUT_OF_RANGE | "Invalid port ranges specified: devicePorts" |
|10 |401 | UNAUTHORIZED | "No authorization to invoke operation" |
|11 |403 | FORBIDDEN | "Operation not allowed" |
|12 |404 | NOT_FOUND | "Session Id does not exist" |
|13 |409 | CONFLICT | "Another session is created for the same device" |
|14 |500 | INTERNAL | "Session could not be created" |
|15 |501 | NOT_IMPLEMENTED | "Service not implemented for the specified user device" |
|16 |503 | SERVICE_UNAVAILABLE | "Service unavailable" |

### 4.5 Policies

Expand Down