Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit ee25d07e authored by Madhav Iyengar's avatar Madhav Iyengar
Browse files

contexthub: Make client registration API safer 

Modifies the registration API for new endpoint session capabilities to
return a new dedicated IEndpointCommunication interface tied to the
client registration. All endpoint/session APIs have been moved to the
new interface. This prevents security issues resulting from pid re-use.

Adds an unregister() API to IEndpointCommunication for a client to
signal that its associated hub will no longer be active. Subsequent
calls on IEndpointCommunication APIs will fail.

Bug: 384897139
Flag: android.chre.flags.offload_api
Test: Builds
Change-Id: Ibd8a28e96315ca146d62413b5337ece9912d14c4
parent e14868ac

contexthub/aidl/aidl_api/android.hardware.contexthub/current/android/hardware/contexthub/IContextHub.aidl

+1 −9
Original line number Diff line number Diff line
@@ -51,14 +51,6 @@ interface IContextHub { 
  void sendMessageDeliveryStatusToHub(in int contextHubId, in android.hardware.contexthub.MessageDeliveryStatus messageDeliveryStatus);

  List<android.hardware.contexthub.HubInfo> getHubs();

  List<android.hardware.contexthub.EndpointInfo> getEndpoints();

  void registerEndpoint(in android.hardware.contexthub.EndpointInfo endpoint);

  void unregisterEndpoint(in android.hardware.contexthub.EndpointInfo endpoint);

  void registerEndpointCallback(in android.hardware.contexthub.IEndpointCallback callback);

  int[2] requestSessionIdRange(int size);

  void openEndpointSession(int sessionId, in android.hardware.contexthub.EndpointId destination, in android.hardware.contexthub.EndpointId initiator, in @nullable String serviceDescriptor);

  void sendMessageToEndpoint(int sessionId, in android.hardware.contexthub.Message msg);

  void sendMessageDeliveryStatusToEndpoint(int sessionId, in android.hardware.contexthub.MessageDeliveryStatus msgStatus);

  void closeEndpointSession(int sessionId, in android.hardware.contexthub.Reason reason);

  void endpointSessionOpenComplete(int sessionId);

  @PropagateAllowBlocking android.hardware.contexthub.IEndpointCommunication registerEndpointHub(in android.hardware.contexthub.IEndpointCallback callback, in android.hardware.contexthub.HubInfo hubInfo);

  const int EX_CONTEXT_HUB_UNSPECIFIED = (-1) /* -1 */;

}

contexthub/aidl/aidl_api/android.hardware.contexthub/current/android/hardware/contexthub/IEndpointCommunication.aidl

0 → 100644
+46 −0
Original line number Diff line number Diff line 
/*

 * Copyright (C) 2024 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

///////////////////////////////////////////////////////////////////////////////

// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE.                          //

///////////////////////////////////////////////////////////////////////////////



// This file is a snapshot of an AIDL file. Do not edit it manually. There are

// two cases:

// 1). this is a frozen version file - do not edit this in any case.

// 2). this is a 'current' file. If you make a backwards compatible change to

//     the interface (from the latest frozen version), the build system will

//     prompt you to update this file with `m <name>-update-api`.

//

// You must not make a backward incompatible change to any AIDL file built

// with the aidl_interface module type with versions property set. The module

// type is used to build AIDL files in a way that they can be used across

// independently updatable components of the system. If a device is shipped

// with such a backward incompatible change, it has a high risk of breaking

// later when a module using the interface is updated, e.g., Mainline modules.



package android.hardware.contexthub;

@VintfStability

interface IEndpointCommunication {

  void registerEndpoint(in android.hardware.contexthub.EndpointInfo endpoint);

  void unregisterEndpoint(in android.hardware.contexthub.EndpointInfo endpoint);

  int[2] requestSessionIdRange(int size);

  void openEndpointSession(int sessionId, in android.hardware.contexthub.EndpointId destination, in android.hardware.contexthub.EndpointId initiator, in @nullable String serviceDescriptor);

  void sendMessageToEndpoint(int sessionId, in android.hardware.contexthub.Message msg);

  void sendMessageDeliveryStatusToEndpoint(int sessionId, in android.hardware.contexthub.MessageDeliveryStatus msgStatus);

  void closeEndpointSession(int sessionId, in android.hardware.contexthub.Reason reason);

  void endpointSessionOpenComplete(int sessionId);

  void unregister();

}

contexthub/aidl/android/hardware/contexthub/IContextHub.aidl

+15 −121
Original line number Diff line number Diff line
@@ -18,19 +18,16 @@ package android.hardware.contexthub; 


import android.hardware.contexthub.ContextHubInfo;

import android.hardware.contexthub.ContextHubMessage;

import android.hardware.contexthub.EndpointId;

import android.hardware.contexthub.EndpointInfo;

import android.hardware.contexthub.HostEndpointInfo;

import android.hardware.contexthub.HubInfo;

import android.hardware.contexthub.IContextHubCallback;

import android.hardware.contexthub.IEndpointCallback;

import android.hardware.contexthub.Message;

import android.hardware.contexthub.IEndpointCommunication;

import android.hardware.contexthub.MessageDeliveryStatus;

import android.hardware.contexthub.NanSessionStateUpdate;

import android.hardware.contexthub.NanoappBinary;

import android.hardware.contexthub.NanoappInfo;

import android.hardware.contexthub.Reason;

import android.hardware.contexthub.Service;

import android.hardware.contexthub.Setting;



@VintfStability
@@ -271,125 +268,22 @@ interface IContextHub { 
    List<EndpointInfo> getEndpoints();



    /**

     * Publishes an endpoint from the calling side (e.g. Android). Endpoints must be registered

     * prior to starting a session.

     */

    void registerEndpoint(in EndpointInfo endpoint);



    /**

     * Teardown an endpoint from the calling side (e.g. Android). This endpoint must have already

     * been published via registerEndpoint().

     */

    void unregisterEndpoint(in EndpointInfo endpoint);



    /**

     * Attaches a callback interface to receive events targeted at endpoints registered by the

     * caller.

     */

    void registerEndpointCallback(in IEndpointCallback callback);



    /**

     * Request a range of session IDs for the caller to use when initiating sessions. This may be

     * called more than once, but typical usage is to request a large enough range to accommodate

     * the maximum expected number of concurrent sessions, but not overly large as to limit other

     * clients.

     * Registers a new hub for endpoint communication which will receive events for its endpoints

     * over the given callback. Returns an interface for the hub to register endpoints, start

     * sessions, and send messages.

     *

     * @param size The number of sessionId reserved for host-initiated sessions. This number should

     *         be less than or equal to 1024.

     *

     * @return An array with two elements representing the smallest and largest possible session id

     *         available for host.

     *

     * @throws EX_ILLEGAL_ARGUMENT if the size is invalid.

     * @throws EX_SERVICE_SPECIFIC if the id range requested cannot be allocated.

     */

    int[2] requestSessionIdRange(int size);



    /**

     * Request to open a session for communication between an endpoint previously registered by the

     * caller and a target endpoint found in getEndpoints(), optionally scoped to a service

     * published by the target endpoint.

     *

     * Upon returning from this function, the session is in pending state, and the final result will

     * be given by an asynchronous call to onEndpointSessionOpenComplete() on success, or

     * onCloseEndpointSession() on failure.

     *

     * @param sessionId Caller-allocated session identifier, which must be unique across all active

     *         sessions, and must fall in a range allocated via requestSessionIdRange().

     * @param destination The EndpointId representing the destination side of the session.

     * @param initiator The EndpointId representing the initiating side of the session, which

     *         must've already been published through registerEndpoint().

     * @param serviceDescriptor Descriptor for the service specification for scoping this session

     *         (nullable). Null indicates a fully custom marshalling scheme. The value should match

     *         a published descriptor for both destination and initiator.

     *

     * @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the

     *         arguments is invalid.

     * @throws EX_SERVICE_SPECIFIC on other errors

     *         - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.

     */

    void openEndpointSession(int sessionId, in EndpointId destination, in EndpointId initiator,

            in @nullable String serviceDescriptor);



    /**

     * Send a message from one endpoint to another on the (currently open) session.

     * It is valid for the same callback to be registered for multiple hubs, as the

     * IEndpointCallback events provide sufficient information to determine which hub the event is

     * intended for:

     * * session ids are allocated to a specific hub and are unique

     * * endpoints are identified by hub and endpoint id

     *

     * @param sessionId The integer representing the communication session, previously set in

     *         openEndpointSession() or onEndpointSessionOpenRequest().

     * @param msg The Message object representing a message to endpoint from the endpoint on host.

     * @param callback Interface to send endpoint events targeting the caller

     * @param hubInfo Details of the hub being registered

     * @return Interface for the hub to interact with other endpoint hubs

     *

     * @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the

     *         arguments is invalid.

     * @throws EX_SERVICE_SPECIFIC on other errors

     *         - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.

     */

    void sendMessageToEndpoint(int sessionId, in Message msg);



    /**

     * Sends a message delivery status to the endpoint in response to receiving a Message with flag

     * FLAG_REQUIRES_DELIVERY_STATUS. Each message with the flag should have a MessageDeliveryStatus

     * response. This method sends the message delivery status back to the remote endpoint for a

     * session.

     *

     * @param sessionId The integer representing the communication session, previously set in

     *         openEndpointSession() or onEndpointSessionOpenRequest().

     * @param msgStatus The MessageDeliveryStatus object representing the delivery status for a

     *         specific message (identified by the sequenceNumber) within the session.

     *

     * @throws EX_UNSUPPORTED_OPERATION if ContextHubInfo.supportsReliableMessages is false for

     *          the hub involved in this session.

     */

    void sendMessageDeliveryStatusToEndpoint(int sessionId, in MessageDeliveryStatus msgStatus);



    /**

     * Closes a session previously opened by openEndpointSession() or requested via

     * onEndpointSessionOpenRequest(). Processing of session closure must be ordered/synchronized

     * with message delivery, such that if this session was open, any messages previously passed to

     * sendMessageToEndpoint() that are still in-flight must still be delivered before the session

     * is closed. Any in-flight messages to the endpoint that requested to close the session will

     * not be delivered.

     *

     * @param sessionId The integer representing the communication session, previously set in

     *         openEndpointSession() or onEndpointSessionOpenRequest().

     * @param reason The reason for this close endpoint session request.

     *

     * @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the

     *         arguments is invalid.

     * @throws EX_SERVICE_SPECIFIC on other errors

     *         - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.

     */

    void closeEndpointSession(int sessionId, in Reason reason);



    /**

     * Notifies the HAL that the session requested by onEndpointSessionOpenRequest is ready to use.

     *

     * @param sessionId The integer representing the communication session, previously set in

     *         onEndpointSessionOpenRequest(). This id is assigned by the HAL.

     *

     * @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the

     *         arguments is invalid.

     * @throws EX_SERVICE_SPECIFIC on other errors

     *         - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.

     * @throws EX_ILLEGAL_STATE if hubInfo.hubId has already been registered

     */

    void endpointSessionOpenComplete(int sessionId);

    @PropagateAllowBlocking

    IEndpointCommunication registerEndpointHub(in IEndpointCallback callback, in HubInfo hubInfo);

}

contexthub/aidl/android/hardware/contexthub/IEndpointCommunication.aidl

0 → 100644
+152 −0
Original line number Diff line number Diff line 
/*

 * Copyright (C) 2024 The Android Open Source Project

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */



package android.hardware.contexthub;



import android.hardware.contexthub.EndpointId;

import android.hardware.contexthub.EndpointInfo;

import android.hardware.contexthub.IEndpointCallback;

import android.hardware.contexthub.Message;

import android.hardware.contexthub.MessageDeliveryStatus;

import android.hardware.contexthub.Reason;

import android.hardware.contexthub.Service;



@VintfStability

interface IEndpointCommunication {

    /**

     * Publishes an endpoint from the calling side (e.g. Android). Endpoints must be registered

     * prior to starting a session.

     */

    void registerEndpoint(in EndpointInfo endpoint);



    /**

     * Teardown an endpoint from the calling side (e.g. Android). This endpoint must have already

     * been published via registerEndpoint().

     */

    void unregisterEndpoint(in EndpointInfo endpoint);



    /**

     * Request a range of session IDs for the caller to use when initiating sessions. This may be

     * called more than once, but typical usage is to request a large enough range to accommodate

     * the maximum expected number of concurrent sessions, but not overly large as to limit other

     * clients.

     *

     * @param size The number of sessionId reserved for host-initiated sessions. This number should

     *         be less than or equal to 1024.

     *

     * @return An array with two elements representing the smallest and largest possible session id

     *         available for host.

     *

     * @throws EX_ILLEGAL_ARGUMENT if the size is invalid.

     * @throws EX_SERVICE_SPECIFIC if the id range requested cannot be allocated.

     */

    int[2] requestSessionIdRange(int size);



    /**

     * Request to open a session for communication between an endpoint previously registered by the

     * caller and a target endpoint found in getEndpoints(), optionally scoped to a service

     * published by the target endpoint.

     *

     * Upon returning from this function, the session is in pending state, and the final result will

     * be given by an asynchronous call to onEndpointSessionOpenComplete() on success, or

     * onCloseEndpointSession() on failure.

     *

     * @param sessionId Caller-allocated session identifier, which must be unique across all active

     *         sessions, and must fall in a range allocated via requestSessionIdRange().

     * @param destination The EndpointId representing the destination side of the session.

     * @param initiator The EndpointId representing the initiating side of the session, which

     *         must've already been published through registerEndpoint().

     * @param serviceDescriptor Descriptor for the service specification for scoping this session

     *         (nullable). Null indicates a fully custom marshalling scheme. The value should match

     *         a published descriptor for both destination and initiator.

     *

     * @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the

     *         arguments is invalid.

     * @throws EX_SERVICE_SPECIFIC on other errors

     *         - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.

     */

    void openEndpointSession(int sessionId, in EndpointId destination, in EndpointId initiator,

            in @nullable String serviceDescriptor);



    /**

     * Send a message from one endpoint to another on the (currently open) session.

     *

     * @param sessionId The integer representing the communication session, previously set in

     *         openEndpointSession() or onEndpointSessionOpenRequest().

     * @param msg The Message object representing a message to endpoint from the endpoint on host.

     *

     * @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the

     *         arguments is invalid.

     * @throws EX_SERVICE_SPECIFIC on other errors

     *         - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.

     */

    void sendMessageToEndpoint(int sessionId, in Message msg);



    /**

     * Sends a message delivery status to the endpoint in response to receiving a Message with flag

     * FLAG_REQUIRES_DELIVERY_STATUS. Each message with the flag should have a MessageDeliveryStatus

     * response. This method sends the message delivery status back to the remote endpoint for a

     * session.

     *

     * @param sessionId The integer representing the communication session, previously set in

     *         openEndpointSession() or onEndpointSessionOpenRequest().

     * @param msgStatus The MessageDeliveryStatus object representing the delivery status for a

     *         specific message (identified by the sequenceNumber) within the session.

     *

     * @throws EX_UNSUPPORTED_OPERATION if ContextHubInfo.supportsReliableMessages is false for

     *          the hub involved in this session.

     */

    void sendMessageDeliveryStatusToEndpoint(int sessionId, in MessageDeliveryStatus msgStatus);



    /**

     * Closes a session previously opened by openEndpointSession() or requested via

     * onEndpointSessionOpenRequest(). Processing of session closure must be ordered/synchronized

     * with message delivery, such that if this session was open, any messages previously passed to

     * sendMessageToEndpoint() that are still in-flight must still be delivered before the session

     * is closed. Any in-flight messages to the endpoint that requested to close the session will

     * not be delivered.

     *

     * @param sessionId The integer representing the communication session, previously set in

     *         openEndpointSession() or onEndpointSessionOpenRequest().

     * @param reason The reason for this close endpoint session request.

     *

     * @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the

     *         arguments is invalid.

     * @throws EX_SERVICE_SPECIFIC on other errors

     *         - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.

     */

    void closeEndpointSession(int sessionId, in Reason reason);



    /**

     * Notifies the HAL that the session requested by onEndpointSessionOpenRequest is ready to use.

     *

     * @param sessionId The integer representing the communication session, previously set in

     *         onEndpointSessionOpenRequest(). This id is assigned by the HAL.

     *

     * @throws EX_ILLEGAL_ARGUMENT if any of the arguments are invalid, or the combination of the

     *         arguments is invalid.

     * @throws EX_SERVICE_SPECIFIC on other errors

     *         - EX_CONTEXT_HUB_UNSPECIFIED if the request failed for other reasons.

     */

    void endpointSessionOpenComplete(int sessionId);



    /**

     * Unregisters this hub. Subsequent calls on this interface will fail.

     *

     * @throws EX_ILLEGAL_STATE if this interface was already unregistered.

     */

    void unregister();

}

contexthub/aidl/default/ContextHub.cpp

+75 −26

File changed.

Preview size limit exceeded, changes collapsed.