diff --git a/code/API_definitions/webrtc-call-handling.yaml b/code/API_definitions/webrtc-call-handling.yaml index a009b50..28b3df3 100644 --- a/code/API_definitions/webrtc-call-handling.yaml +++ b/code/API_definitions/webrtc-call-handling.yaml @@ -167,24 +167,6 @@ info: } ``` - # Authorization and authentication - - The "Camara Security and Interoperability Profile" provides details of how an - API consumer requests an access token. Please refer to Identity and Consent - Management (https://github.com/camaraproject/IdentityAndConsentManagement/) - for the released version of the profile. - - The specific authorization flows to be used will be agreed upon during the - onboarding process, happening between the API consumer and the API provider, - taking into account the declared purpose for accessing the API, whilst also - being subject to the prevailing legal framework dictated by local legislation. - - In cases where personal data is processed by the API and users can exercise - their rights through mechanisms such as opt-in and/or opt-out, the use of - three-legged access tokens is mandatory. This ensures that the API remains - in compliance with privacy regulations, upholding the principles of - transparency and user-centric privacy-by-design. - # Additional CAMARA error responses The list of error codes in this API specification is not exhaustive. Therefore the API specification may not document some non-mandatory error @@ -198,14 +180,49 @@ info: As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. + # Located calls + + As part of the extended, or contextual information of calls, a location can + be provided as part of the call information. A regular call **MAY** provide + an `originatorLocationDetails` object in order to help the receiver to + locate the geographic position of the device calling. In aim of security, + routing or any other use case provided by the network. + + As each party can share its own location, there are two separated objects + `originatorLocationDetails` and `receiverLocationDetails`, both serving + the same purpose and implementing the `locationDetails` schema. + + The `locationDetails` schema follows PIDF-LO concepts (3GPP TS 24.229, + RFC 4119, RFC 5139, RFC 5491) with either a circle or ellipsoid shape. + # Emergency Calling + - Introduces a new `callType` attribute with values `REGULAR` or `EMERGENCY`. - - When `callType` is `EMERGENCY`, the client **MAY** include `locationDetails` - describing the caller's location. - - `locationDetails` follows PIDF-LO concepts (3GPP TS 24.229, RFC 4119, RFC 5139, + - When `callType` is `EMERGENCY`, the client **MAY** include + `originatorLocationDetails` describing the caller's location. + - `originatorLocationDetails` implements the `locationDetails` schema. + This schema follows PIDF-LO concepts (3GPP TS 24.229, RFC 4119, RFC 5139, RFC 5491) with either a circle or ellipsoid shape. - If `callType` is omitted, it defaults to `REGULAR`. + # Authorization and authentication + + The "Camara Security and Interoperability Profile" provides details of how an + API consumer requests an access token. Please refer to Identity and Consent + Management (https://github.com/camaraproject/IdentityAndConsentManagement/) + for the released version of the profile. + + The specific authorization flows to be used will be agreed upon during the + onboarding process, happening between the API consumer and the API provider, + taking into account the declared purpose for accessing the API, whilst also + being subject to the prevailing legal framework dictated by local legislation. + + In cases where personal data is processed by the API and users can exercise + their rights through mechanisms such as opt-in and/or opt-out, the use of + three-legged access tokens is mandatory. This ensures that the API remains + in compliance with privacy regulations, upholding the principles of + transparency and user-centric privacy-by-design. + license: name: Apache 2.0 url: 'https://www.apache.org/licenses/LICENSE-2.0.html' @@ -245,10 +262,12 @@ paths: schema: $ref: '#/components/schemas/MediaSessionInformation' examples: - Media session request: - $ref: '#/components/examples/exampleMediaSessionRequest' + RegularMediaSessionRequest: + $ref: '#/components/examples/exampleRegularMediaSessionRequest' EmergencyMediaSessionRequest: $ref: '#/components/examples/exampleEmergencyMediaSessionRequest' + LocatedMediaSessionRequest: + $ref: '#/components/examples/exampleLocatedMediaSessionRequest' responses: '201': description: Created @@ -498,7 +517,7 @@ components: enum: - REGULAR - EMERGENCY - locationDetails: + originatorLocationDetails: $ref: '#/components/schemas/LocationDetails' WrtcSDPDescriptor: type: object @@ -586,11 +605,8 @@ components: description: 'The method used to obtain the location information. * **GPS:** Global Positioning System (highly accurate) - * **DBH:** Device-Based Hybrid - * **DBH_HELO:** Device-Based Hybrid using Apple Hybridized Emergency Location - * **Other:** Other methods (e.g., landmarks, IP Based etc.) ' @@ -672,7 +688,8 @@ components: type: number description: Orientation of the ellipsoid in degrees. examples: - exampleMediaSessionRequest: + exampleRegularMediaSessionRequest: + summary: Regular call initiation with media information value: originatorAddress: tel:+17085852753 originatorName: tel:+17085852753 @@ -783,7 +800,7 @@ components: type: offer sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:ruAnBNYnTJqDVZAIJV59VpQ5DxGI6tMX9h9kkHSz\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\na=ptime:20\r\n" callType: EMERGENCY - locationDetails: + originatorLocationDetails: shape: Circle coordinates: latitude: 47.6062 @@ -794,6 +811,27 @@ components: pdf: normal value: 92 timestamp: '2025-10-06T19:31:25Z' + exampleLocatedMediaSessionRequest: + summary: Regular call initiation with location details + value: + originatorAddress: 'tel:+17085852753' + originatorName: Alice + receiverAddress: tel:+17085854000 + receiverName: Bob + offer: + type: offer + sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:ruAnBNYnTJqDVZAIJV59VpQ5DxGI6tMX9h9kkHSz\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\na=ptime:20\r\n" + originatorLocationDetails: + shape: Circle + coordinates: + latitude: 47.5124 + longitude: -122.4176 + radius: 27 + method: GPS + confidence: + pdf: normal + value: 97 + timestamp: '2025-10-06T19:31:25Z' responses: Generic400: description: Bad Request diff --git a/code/API_definitions/webrtc-events.yaml b/code/API_definitions/webrtc-events.yaml index 8205c52..be79c1c 100644 --- a/code/API_definitions/webrtc-events.yaml +++ b/code/API_definitions/webrtc-events.yaml @@ -142,6 +142,21 @@ info: a unique SessionId, to create a dedicated subscription and receive events about the session itself and its status progressing inside the network. + **Located calls** + + The CAMARA WebRTC API provides an standardization way to locate caller + origin. If provided by the network, it helps to contextualize the calls + in aim of enhanced security, routing or any other use case. The located + calls include a `originatorLocationDetails` object on the `session-invitation` + event that could be parsed and used by the API consumer. + + As each party can share its own location, there are two separated objects + `originatorLocationDetails` and `receiverLocationDetails`, both serving + the same purpose and implementing the `locationDetails` schema. + + The `locationDetails` schema follows PIDF-LO concepts (3GPP TS 24.229, + RFC 4119, RFC 5139, RFC 5491) with either a circle or ellipsoid shape. + ## 3. Subscription ends (subscription-ended) A `org.camaraproject.webrtc-events.v0.subscription-ended` event indicates that @@ -265,6 +280,8 @@ paths: examples: NEW_SESSION_INCOMING (session-invitation): $ref: "#/components/examples/NEW_SESSION_INCOMING" + NEW_LOCATED_SESSION_INCOMING (session-invitation): + $ref: "#/components/examples/NEW_LOCATED_SESSION_INCOMING" SESSION_UPDATE (session-status): $ref: "#/components/examples/SESSION_UPDATE" REGISTRATION_EXPIRED (registration-ends): @@ -891,6 +908,10 @@ components: sequenceNumber: type: integer description: The sequence number of the notification sent to client + originatorLocationDetails: + $ref: '#/components/schemas/LocationDetails' + receiverLocationDetails: + $ref: '#/components/schemas/LocationDetails' MediaSessionStatusUpdate: allOf: @@ -1030,6 +1051,116 @@ components: description: The HTTP method to use for sending the message. enum: - POST + LocationDetails: + type: object + description: Details about the caller's location and related information. This + object adheres to 3GPP TS 24.229, RFC 4119, RFC 5139, and RFC 5491 for PIDF-LO + compatibility. + properties: + shape: + type: string + enum: + - Circle + - Ellipsoid + description: The shape representing the caller's location (Circle or Ellipsoid). + coordinates: + oneOf: + - $ref: '#/components/schemas/CircleCoordinates' + - $ref: '#/components/schemas/EllipsoidCoordinates' + description: The coordinates of the caller's location, specific to the chosen + shape. + method: + type: string + enum: + - GPS + - DBH + - DBH_HELO + - Other + description: 'The method used to obtain the location information. + + * **GPS:** Global Positioning System (highly accurate) + * **DBH:** Device-Based Hybrid + * **DBH_HELO:** Device-Based Hybrid using Apple Hybridized Emergency Location + * **Other:** Other methods (e.g., landmarks, IP Based etc.) + + ' + confidence: + type: object + description: The confidence level of the location information. + properties: + pdf: + type: string + enum: + - normal + - uniform + description: The probability density function (PDF) associated with the + confidence value. + value: + type: number + minimum: 0 + maximum: 100 + description: The confidence value (percentage). + timestamp: + type: string + format: date-time + description: The timestamp (in ISO 8601 format) indicating when the location + information was Calculated. \nThis is crucial for emergency services to + assess the timeliness of the data. if not provided current timestamp will + be used by default" + CircleCoordinates: + type: object + required: + - latitude + - longitude + - radius + properties: + latitude: + type: number + format: float + description: Latitude of the center point in decimal degrees (WGS84). + longitude: + type: number + format: float + description: Longitude of the center point in decimal degrees (WGS84). + radius: + type: number + format: float + description: Radius of the circle in meters, indicating the uncertainty. + EllipsoidCoordinates: + type: object + required: + - latitude + - longitude + - zAxis + - semiMajorAxis + - semiMinorAxis + - verticalAxis + - orientation + properties: + latitude: + type: number + format: float + description: Latitude in the WGS 84 geocentric coordinate system. + longitude: + type: number + format: float + description: Longitude in the WGS 84 geocentric coordinate system. + zAxis: + type: number + format: float + description: Altitude (optional) in the WGS 84 geocentric coordinate system. + semiMajorAxis: + type: number + description: Length of the semi-major axis of the ellipsoid in meters. + semiMinorAxis: + type: number + description: Length of the semi-minor axis of the ellipsoid in meters. + verticalAxis: + type: number + description: Length of the vertical axis of the ellipsoid in meters. + orientation: + type: number + description: Orientation of the ellipsoid in degrees. responses: CreateSubscriptionBadRequest400: @@ -1505,6 +1636,42 @@ components: mediaSessionId: "0AEE1B58BAEEDA3EABA42B32EBB3DFE07E9CFF402EAF9EED8EF" reason: "New subscriber incoming call" sequenceNumber: 1 + NEW_LOCATED_SESSION_INCOMING: + description: |- + Example of located `session-invitation` event. + + An extended example of `session-invitation` that includes location + details within the `LocationDetails` object + value: + id: "VzYQCOClM6Kc7Xmyq7mP58Jx" + source: https://notificationServer.opentelco.com + type: org.camaraproject.webrtc-events.v0.session-invitation + specversion: "1.0" + datacontenttype: application/json + time: 2024-11-05T05:40:23.682Z + data: + subscriptionId: "qs15-h556-rt89-1298" + originatorAddress: "tel:+11234567899" + originatorName: "Alice" + receiverAddress: "tel:+11234998765" + receiverName: "Bob" + status: "Initial" + offer: + sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0" + mediaSessionId: "0AEE1B58BAEEDA3EABA42B32EBB3DFE07E9CFF402EAF9EED8EF" + reason: "New subscriber incoming call" + sequenceNumber: 1 + locationDetails: + shape: Circle + coordinates: + latitude: 47.6062 + longitude: -122.3321 + radius: 35 + method: GPS + confidence: + pdf: normal + value: 92 + timestamp: '2024-11-05T05:35:12.254Z' REGISTRATION_ENDS: description: |- Example of `registration-ends` events.