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

Update UeId definition in qod-api.yaml #123

Closed
wants to merge 2 commits into from
Closed

Update UeId definition in qod-api.yaml #123

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ca1fc5e
Update UeId definition in qod-api.yaml
eric-murray Feb 24, 2023
410746e
Rename PublicIpv4Addr field port to public_port
eric-murray Feb 24, 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
88 changes: 70 additions & 18 deletions code/API_definitions/qod-api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,41 +62,53 @@ paths:
status: 400
code: INVALID_ARGUMENT
message: "Schema validation failed at ..."
MsisdnRequired:
summary: msisdn is required as part of ueId
InsufficientProperties:
summary: ueId parameter must have at least one property specified
value:
status: 400
code: INVALID_ARGUMENT
message: "Expected property is missing: ueId.msisdn"
IPv4Required:
summary: ipv4addr is required as part of ueId
message: "Insufficient parameters specified: ueId"
InconsistentProperties:
summary: ueId parameters must identify the same UE
value:
status: 400
code: INVALID_ARGUMENT
message: "Expected property is missing: ueId.ipv4addr"
IPRequired:
summary: Some IP address is required as part of ueId
message: "Multiple inconsistent parameters specified: ueId"
UnidentifiedUE:
summary: Specified ueId parameters do not identify a UE
value:
status: 400
code: INVALID_ARGUMENT
message: "Expected property is missing: ueId.ipv4addr or ueId.ipv6addr"
UePortsRequired:
summary: uePorts is required
message: "UE cannot be identifed from specified parameters: ueId"
InvalidFormat:
summary: Parameter is incorrectly formatted
value:
status: 400
code: INVALID_ARGUMENT
message: "Expected property is missing: uePorts"
QoSRequired:
summary: qos is required
message: "Invalid parameter format: ueId.msisdn"
MissingParameter:
summary: A specified parameter is missing a required property
value:
status: 400
code: INVALID_ARGUMENT
message: "Expected property is missing: qos"
message: "Missing parameter: ueId.private_ip4_addr.public_ip_address"
ParameterOutOfRange:
summary: Parameter specified is outside of valid range
value:
status: 400
code: OUT_OF_RANGE
message: "Specified parameter out of range: ueId.public_ipv4_addr.public_port"
MissingRequiredParameter:
summary: Parameter is required but not specified
value:
status: 400
code: INVALID_ARGUMENT
message: "Required parameter is missing: qos"
UePortsRangesNotAllowed:
summary: Ranges at uePorts are not allowed
value:
status: 400
code: INVALID_ARGUMENT
code: OUT_OF_RANGE
message: "Ranges not allowed: uePorts"
"401":
$ref: "#/components/responses/Generic401"
Expand Down Expand Up @@ -398,8 +410,10 @@ components:
$ref: "#/components/schemas/ExternalId"
msisdn:
$ref: "#/components/schemas/MSISDN"
ipv4addr:
$ref: "#/components/schemas/Ipv4Addr"
public_ipv4_addr:
$ref: "#/components/schemas/PublicIpv4Addr"
private_ipv4_addr:
$ref: "#/components/schemas/PrivateIpv4Addr"
ipv6addr:
$ref: "#/components/schemas/Ipv6Addr"
description: User equipment identifier
Expand Down Expand Up @@ -430,6 +444,44 @@ 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.
PublicIpv4Addr:
description: |
Public (routable) source IP address and public port seen by, and identifying the device to, the application server
type: object
properties:
public_address:
$ref: "#/components/schemas/SingleIpv4Addr"
public_port:
$ref: "#/components/schemas/Port"
required:
- public_address
- public_port
example:
{
"public_address": "85.255.235.230",
"public_port": 60276
}
PrivateIpv4Addr:
description: |
Private (non-routable) source IP address directly allocated to the device, and the public (routable) source IP seen by and identifying the device to the application server. If the device does not have a public IP address, then the public_address value should be specified as the private address as well to indicate this.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Private (non-routable) source IP address directly allocated to the device, and the public (routable) source IP seen by and identifying the device to the application server. If the device does not have a public IP address, then the public_address value should be specified as the private address as well to indicate this.
Private (non-routable) source IP address directly allocated to the device, and the public (routable) source IP seen by and identifying the device to the application server. If the device does have a public IP address, then the public_address value should be specified as the private address as well to indicate this.

Is my understanding correct? If the device has a public address, then copy the value as a private address as well. With private addresses only it is not always possible to identify the device. For this scenario the name private_ipv4_addr would be misleading. IMO device_ipv4_addr or local_ipv4_addr would cover better both situations.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jlurien

No, that is not how I intended this to work.

It works as follows:

Identify device by private IP address

IF the device has been directly allocated a private IP address
AND the API caller wishes to identify the UE by that private address
THEN the API caller uses the private_ipv4_addr field of ueId to pass both private and public (CGNATed) IP addresses

If the private IP address has NOT been NATed to a public address (this will not be the normal case), then the private address is copied to the public_address field to indicate this. This is the exception documented in the description for PrivateIpv4Addr.

So the text is correct

Identify device by public IP address

IF the device has been directly allocated a private IP address which has been CGNATed to a public address OR the device has been directly allocated a public IP address (this would be unusual)
AND the API caller wishes to identify the device by its public address
THEN the API caller uses the public_ipv4_addr field of ueId to indicate both the public_address and port allocated to the device (the port being required to uniquely identify the device in the case of CGNATing)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Eric for the detailed clarification. This type of explanations would be useful also to be added to the API doc.

Then, for:

If the private IP address has NOT been NATed to a public address (this will not be the normal case), then the private address is copied to the public_address field to indicate this. This is the exception documented in the description for PrivateIpv4Addr.

In which scenarios can this happen? Private networks where both device and application server are in the same network? And every device is allocated a distinct private address?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this scenario would be for private or test networks where the private address allocated to the device is unique (within that network).

So the private address is sufficient to identify the device in this case, but I think making public_address required is better because this information will indeed be required for the normal case. Unfortunately, OAS does not support making fields conditionally mandatory - they are either required or optional.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we consider the term routable as ip address that is routable in the internet, then the existing text itself seems to be fine. This means private addr (non-routable) and public addr (routable). With that, my understanding is as below:

  • UE behind NAT with a private addr & want to identify using public ip addr -> use PublicIPv4Addr object
  • UE behind NAT with a private addr & want to identify using private ip addr-> use PrivateIpv4Addr object with public_address and private_address assigned with respective ip addrs.
  • UE in a private n/w with a private addr & want to identify using private ip addr itself -> use PrivateIpv4Addr object with public_address and private_address being the same private addr
  • UE is assigned a public addr (unusual case) & want to identify using public ip addr ->I thought we still be using the PrivateIpv4Addr object with public_address and private_address being the same public ip addr. This is one anomaly to the 'routable' term and as this is an unusual case, I tend to ignore it. (However, @eric-murray reply above 'Identify device by public IP address' indicates the use of PublicIpv4Addr object for this case -> not sure what should be the value of public_port would be in this case? This needs clarification)

From an AppServer implementation perspective, it uses the PublicIpv4Addr if populated. If not, it uses the PrivateIpv4Addr object to identify the device. Seems OK to me (pending the clarification requested above).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sfnuser

UE is assigned a public addr (unusual case) & want to identify using public ip addr ->I thought we still be using the PrivateIpv4Addr object with public_address and private_address being the same public ip addr. This is one anomaly to the 'routable' term and as this is an unusual case, I tend to ignore it. (However, @eric-murray reply above 'Identify device by public IP address' indicates the use of PublicIpv4Addr object for this case -> not sure what should be the value of public_port would be in this case? This needs clarification)

My thought was that, if a public address is allocated directly to the device, then it will not have a private address at all, and so expecting the API caller to use the private_ipv4_addr field to identify the device is somewhat counterintuitive.

On your specific point about also specifying the public_port, for this scenario it is indeed not strictly required. Not because the device does not have a public source port, but because it has been allocated ALL public source ports. So any port could be specified. This is different to requiring the private_address, as such a device definitely does not have a private address (at least, not one that the mobile network would know about).

Given that public_port most definitely is required for the CGNAT case, I decided to make that parameter mandatory. Allowing the API caller not to specify it will cause more problems than it solves. Ultimately, there are three parameters that may be required for IPv4 address - public address, private address and public port. The question is what combination of options do we allow the API caller in specifying these parameters.

My expectation is that allocating public IPv4 addresses directly to the device is an entirely hypothetical scenario. If anyone is aware of commercial networks that still do this, I'd be interested in details of those.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@eric-murray

My expectation is that allocating public IPv4 addresses directly to the device is an entirely hypothetical scenario. If anyone is aware of commercial networks that still do this, I'd be interested in details of those.

I agree. We have captured the use case and thought out options here anyways. If this do not suffice, a new issue shall be created at that point and discussed. We do not want to overcomplicate now.

type: object
properties:
private_address:
$ref: "#/components/schemas/SingleIpv4Addr"
public_address:
$ref: "#/components/schemas/SingleIpv4Addr"
required:
- private_address
- public_address
example:
{
"private_address": "10.67.188.91",
"public_address": "85.255.235.230"
}
SingleIpv4Addr:
type: string
format: ipv4
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])$'
Ipv6Addr:
type: string
format: ipv6
Expand Down