sdk/fidl/fuchsia.bluetooth.sys/pairing.fidl - fuchsia - Git at Google

 // Copyright 2022 The Fuchsia Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 library fuchsia.bluetooth.sys;

 using fuchsia.bluetooth as bt;

 /// Allows system clients to enable Bluetooth pairing.
 @available(added=HEAD)
 @discoverable
 closed protocol Pairing {
     /// Assign a PairingDelegate to respond to pairing procedures. The provided I/O capabilities
     /// will be used to determine the pairing methods used.
     ///
     /// Only one PairingDelegate can be set at a time system-wide - if this is called
     /// while another delegate is set, the new delegate will be closed immediately.
     /// Closing a PairingDelegate after it is set aborts all ongoing pairing procedures
     /// without accepting and unsets the delegate.
     ///
     /// If no PairingDelegate is set, all pairings will be rejected even if the
     /// peer connection was initiated by the local device.
     ///
     /// + request `input` Bluetooth input capability, see `InputCapability`
     /// + request `output` Bluetooth output capability, see `OutputCapability`
     /// + request `delegate` PairingDelegate which will receive pairing requests
     strict SetPairingDelegate(resource struct {
         input InputCapability;
         output OutputCapability;
         delegate client_end:PairingDelegate;
     });

     /// Assign a PairingDelegate2 to handle pairing procedures.  The provided
     /// I/O capabilities will be used to determine the methods used.
     ///
     /// Only one of PairingDelegate or PairingDelegate2 can be set at a time
     /// system-wide.  If this is called while another delegate is set, the new
     /// delegate will be closed immediately.
     ///
     /// Closing a PairingDelegate2 unsets the pairing delegate. Ongoing
     /// PairingRequests can still be completed, but new requests will act as if
     /// no delegate is set.
     ///
     /// If no delegate is set, all pairings will be rejected even if the
     /// peer connection was initiated by the local device.
     ///
     /// + request `input` Bluetooth input capability, see `InputCapability`
     /// + request `output` Bluetooth output capability, see `OutputCapability`
     /// + request `delegate` PairingDelegate2 which will receive pairing requests
     strict SetDelegate(resource struct {
         input InputCapability;
         output OutputCapability;
         delegate client_end:PairingDelegate2;
     });
 };

 /// Input Capabilities for pairing exchanges.
 /// These should be set based on the ability of the local system to enter
 /// responses to pairing requests.
 /// See Volume 3, Part C, Table 5.3 for more information.
 type InputCapability = strict enum {
     /// There is no user input method available for responding 'yes' or 'no' to
     /// a pairing request.
     /// Note: setting this setting will mean most pairings are considered
     /// unauthenticated and vulnerable to machine-in-the-middle attacks.
     NONE = 1;
     /// The user can respond yes or no to a request.
     CONFIRMATION = 2;
     /// The user has a keyboard (or other UI) where they can type a numerical code
     /// and signal they have finished or cancel.
     KEYBOARD = 3;
 };

 /// Output Capabilities for pairing excanges.
 /// These should be set based on the ability of the local system to display
 /// information to the user initiating or accepting a Bluetooth pairing.
 /// See Volume 3, Part C, Table 5.4 for more information.
 type OutputCapability = strict enum {
     /// There is no display available for pairing.
     NONE = 1;
     /// There is a display that can show at least a six-digit decimal number.
     DISPLAY = 2;
 };

 /// Different types required by the Security Manager for pairing methods.
 /// Bluetooth SIG has different requirements for different device capabilities.
 type PairingMethod = strict enum {
     /// The user is asked to accept or reject pairing.
     /// This is the minimum method - even when both devices do not support
     /// input or output, the delegate will be asked to confirm any pairing
     /// not initiated with user intent.
     CONSENT = 1;

     /// The user is shown a 6-digit numerical passkey on this device which they
     /// must enter on the peer device.
     PASSKEY_DISPLAY = 2;

     /// The user is shown a 6-digit numerical passkey on this device which will
     /// also shown on the peer device. The user must compare the passkeys and
     /// accept the pairing if the passkeys match.
     PASSKEY_COMPARISON = 3;

     /// The user is asked to enter a 6-digit passkey on this device which is
     /// communicated via the peer device.
     PASSKEY_ENTRY = 4;
 };


 /// Used to convey information to the peer on progress typing a passkey. The
 /// various types of keypresses can be used to customize what is communicated to
 /// the user requesting a pairing.
 type PairingKeypress = strict enum {
     /// The user has entered a single digit.
     DIGIT_ENTERED = 1;

     /// The user has erased a single digit.
     DIGIT_ERASED = 2;

     /// The user has cleared the entire passkey.
     PASSKEY_CLEARED = 3;

     /// The user has finished entering the passkey.
     PASSKEY_ENTERED = 4;
 };

 /// A Bluetooth Pairing Delegate is responsible for confirming or denying
 /// pairing requests received from Bluetooth peers that connect or are
 /// being connected to the local device.
 ///
 /// Any new pairing will result in a call to `PairingDelegate.OnPairingRequest`,
 /// including pairings where the InputCapability and OutputCapability are set
 /// to none. The delegate is expected to have enough context to derive whether
 /// to accept or deny the pairing.
 ///
 /// Only one delegate is allowed to be set per system at a time. See
 /// `fuchsia.bluetooth.sys.Pairing` for how to set the pairing delegate.
 closed protocol PairingDelegate {
     /// Called to confirm a pairing. The pairing process will be continued if
     /// `accept` response is true and rejected otherwise.
     /// If the pairing method requires a passkey it must be included as well.
     /// Pairing methods that do not require a passkey ignore the `entered_passkey`
     /// repsonse.
     ///
     /// The pairing can fail (usually by timeout or peer disconnect) before the
     /// response is received. The OnPairingComplete method will be called when this
     /// occurs.  Any response sent in this case will be ignored.
     ///
     /// + request `peer` information about the peer being paired
     /// + request `method` method of pairing active. See `PairingMethod`
     /// + request `displayed_passkey` a passkey to display to the user if
     ///   PASSKEY_DISPLAY or PASSKEY_COMPARISON is being used. Meaningless
     ///   otherwise.
     /// - response `accept` true if the pairing is accepted
     /// - response `entered_passkey` passkey entered by the user. Ignored unless
     ///   method is PASSKEY_ENTRY.
     strict OnPairingRequest(struct {
         peer Peer;
         method PairingMethod;
         displayed_passkey uint32;
     }) -> (struct {
         accept bool;
         entered_passkey uint32;
     });

     /// Called when the pairing procedure for a peer has been completed.
     /// This can be due to successful completion or an error (e.g. due to cancellation
     /// by the peer, a timeout, or disconnection).
     /// * request `id` The Bluetooth peer ID of the peer which was being paired.
     /// * request `success` true if the pairing succeeded, otherwise false.
     strict OnPairingComplete(struct {
         id bt.PeerId;
         success bool;
     });

     /// Called to notify keypresses from the peer device during pairing using
     /// `PairingMethod.PASSKEY_DISPLAY`.
     ///
     /// This event is used to provide key press events to the delegate for a responsive user
     /// experience as the user types the passkey on the peer device. This event will be called
     /// once for each keypress.
     ///
     /// This event will only be called between when an OnPairingRequest has been sent for
     /// `id` and when OnPairingComplete is sent.
     ///
     /// Note: many devices do not send these events
     /// * request `id` The peer id of the peer that sent the keypress event.
     /// * request `keypress` The type of event which was received.
     strict OnRemoteKeypress(struct {
         id bt.PeerId;
         keypress PairingKeypress;
     });

     /// The delegate can send this event to notify the peer of local keypresses
     /// during pairing using `PairingMethod.PASSKEY_ENTRY`.
     ///
     /// Sending local keypress events can allow the user additional time for
     /// pairing when entering a passkey.
     ///
     /// This should only be sent after an OnPairingRequest has been received
     /// with a PASSKEY_ENTRY method, and before the reponse for that pairing
     /// request.
     ///
     /// * request `id` id of a peer with a pairing request active
     /// * request `keypress` the type of notification which should be sent
     strict -> OnLocalKeypress(struct {
         id bt.PeerId;
         keypress PairingKeypress;
     });
 };

 @available(added=HEAD)
 type PairingProperties = flexible union {
     /// The user is asked to accept or reject pairing.
     /// This is the minimum method - even when both devices do not support
     /// input or output, the delegate will be asked to confirm any pairing
     /// not initiated with user intent.
     1: consent struct {};
     /// The user is shown a 6-digit numerical passkey on this device which they
     /// must key in on the peer device.
     /// The passkey to be displayed is provided.
     2: passkey_display uint32;
     /// The user is shown a 6-digit numerical passkey on this device which will
     /// also be shown on the peer device. The user must compare the passkeys and
     /// accept the pairing if the passkeys match.
     /// The passkey to be displayed is provided.
     3: passkey_confirmation uint32;
     /// The user is asked to enter a 6-digit passkey on this device which is
     /// communicated via the peer device.
     4: passkey_entry struct {};
 };

 /// This protocol is active when a pairing is in progress, and provided to the
 /// PairingDelegate via the `PairingDelegate.StartRequest`
 /// The server will close this protocol with an epitaph if the pairing process
 /// completes early without success:
 ///  - ZX_ERR_UNAVAILABLE - Bluetooth peer has disconnected
 ///  - ZX_ERR_NOT_SUPPORTED - a passkey was provided when it was not expected
 ///  - ZX_ERR_BAD_STATE - a keypress was sent when not using
 ///                       PairingProperties.passkey_entry
 ///  - ZX_ERR_TIMED_OUT - no activity was detected, and the pairing was stopped
 @available(added=HEAD)
 closed protocol PairingRequest {
     /// Accept the pairing request.
     /// entered_passkey is required if the PairingProperties.passkey_entry
     /// method is used, ignored otherwise.
     strict Accept(table {
         1: entered_passkey uint32;
     });

     /// Reject the pairing request.
     /// Closing this protocol will also reject the pairing request.
     strict Reject();

     /// Used to communicate local keypresses to update the remote peer on
     /// the progress of the pairing. The responses to this method should
     /// be used for flow control.
     strict Keypress(struct {
         keypress PairingKeypress;
     }) -> ();


     /// Sent when the pairing method is passkey_display.  Can be used to
     /// update the UI to indicate reception of keypresses.
     strict -> OnKeypress(struct {
         keypress PairingKeypress;
     });

     /// Sent once when the pairing is completed, just before the protocol is
     /// closed.
     /// The success value along with the PeerId will also be sent to the
     /// delegate using the `PairingDelegate.RequestComplete` call.
     strict -> OnComplete(struct {
         success bool;
     });
 };

 /// A Bluetooth Pairing Delegate is responsible for confirming or denying
 /// pairing requests received from Bluetooth peers that connect or are
 /// being connected to the local device.
 ///
 /// Any new pairing will result in a call to `PairingDelegate.StartRequest`,
 /// including pairings where the InputCapability and OutputCapability are set
 /// to none. The delegate is expected to have enough context to derive whether
 /// to accept or reject the pairing.
 ///
 /// Only one delegate is allowed to be set per system at a time. See
 /// `fuchsia.bluetooth.sys.Pairing` for how to set the pairing delegate.
 @available(added=HEAD)
 closed protocol PairingDelegate2 {
     /// Called when a pairing with `peer` is started. The pairing process is
     /// continued using the PairingRequest protocol.
     ///
     /// The properties of the pairing are provided in `info` which indicates
     /// what type of interaction is intended locally.
     ///
     /// Multiple requests can be active at one time for different peers, and
     /// requests can outlive this protocol.  Dropping the request protocol will
     /// automatically reject the pairing.
     ///
     /// All fields will always be present.
     strict StartRequest(resource table {
         /// Peer making the request.
         1: peer Peer;
         /// Properties of the pairing.
         2: info PairingProperties;
         /// Protocol used to complete the pairing process.
         3: request client_end:PairingRequest;
     });

     /// Called when the pairing procedure for a peer has been completed.  This
     /// can be due to successful completion or an error (e.g. due to
     /// cancellation by the peer, a timeout, or disconnection).
     ///
     /// + request `id` The Bluetooth peer ID of the peer which was being paired
     /// + request `success` true if the pairing succeeded, otherwise false
     strict RequestComplete(struct {
         id bt.PeerId;
         success bool;
     });
 };
	// Copyright 2022 The Fuchsia Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.
	library fuchsia.bluetooth.sys;

	using fuchsia.bluetooth as bt;

	/// Allows system clients to enable Bluetooth pairing.
	@available(added=HEAD)
	@discoverable
	closed protocol Pairing {
	/// Assign a PairingDelegate to respond to pairing procedures. The provided I/O capabilities
	/// will be used to determine the pairing methods used.
	///
	/// Only one PairingDelegate can be set at a time system-wide - if this is called
	/// while another delegate is set, the new delegate will be closed immediately.
	/// Closing a PairingDelegate after it is set aborts all ongoing pairing procedures
	/// without accepting and unsets the delegate.
	///
	/// If no PairingDelegate is set, all pairings will be rejected even if the
	/// peer connection was initiated by the local device.
	///
	/// + request `input` Bluetooth input capability, see `InputCapability`
	/// + request `output` Bluetooth output capability, see `OutputCapability`
	/// + request `delegate` PairingDelegate which will receive pairing requests
	strict SetPairingDelegate(resource struct {
	input InputCapability;
	output OutputCapability;
	delegate client_end:PairingDelegate;
	});

	/// Assign a PairingDelegate2 to handle pairing procedures. The provided
	/// I/O capabilities will be used to determine the methods used.
	///
	/// Only one of PairingDelegate or PairingDelegate2 can be set at a time
	/// system-wide. If this is called while another delegate is set, the new
	/// delegate will be closed immediately.
	///
	/// Closing a PairingDelegate2 unsets the pairing delegate. Ongoing
	/// PairingRequests can still be completed, but new requests will act as if
	/// no delegate is set.
	///
	/// If no delegate is set, all pairings will be rejected even if the
	/// peer connection was initiated by the local device.
	///
	/// + request `input` Bluetooth input capability, see `InputCapability`
	/// + request `output` Bluetooth output capability, see `OutputCapability`
	/// + request `delegate` PairingDelegate2 which will receive pairing requests
	strict SetDelegate(resource struct {
	input InputCapability;
	output OutputCapability;
	delegate client_end:PairingDelegate2;
	});
	};

	/// Input Capabilities for pairing exchanges.
	/// These should be set based on the ability of the local system to enter
	/// responses to pairing requests.
	/// See Volume 3, Part C, Table 5.3 for more information.
	type InputCapability = strict enum {
	/// There is no user input method available for responding 'yes' or 'no' to
	/// a pairing request.
	/// Note: setting this setting will mean most pairings are considered
	/// unauthenticated and vulnerable to machine-in-the-middle attacks.
	NONE = 1;
	/// The user can respond yes or no to a request.
	CONFIRMATION = 2;
	/// The user has a keyboard (or other UI) where they can type a numerical code
	/// and signal they have finished or cancel.
	KEYBOARD = 3;
	};

	/// Output Capabilities for pairing excanges.
	/// These should be set based on the ability of the local system to display
	/// information to the user initiating or accepting a Bluetooth pairing.
	/// See Volume 3, Part C, Table 5.4 for more information.
	type OutputCapability = strict enum {
	/// There is no display available for pairing.
	NONE = 1;
	/// There is a display that can show at least a six-digit decimal number.
	DISPLAY = 2;
	};

	/// Different types required by the Security Manager for pairing methods.
	/// Bluetooth SIG has different requirements for different device capabilities.
	type PairingMethod = strict enum {
	/// The user is asked to accept or reject pairing.
	/// This is the minimum method - even when both devices do not support
	/// input or output, the delegate will be asked to confirm any pairing
	/// not initiated with user intent.
	CONSENT = 1;

	/// The user is shown a 6-digit numerical passkey on this device which they
	/// must enter on the peer device.
	PASSKEY_DISPLAY = 2;

	/// The user is shown a 6-digit numerical passkey on this device which will
	/// also shown on the peer device. The user must compare the passkeys and
	/// accept the pairing if the passkeys match.
	PASSKEY_COMPARISON = 3;

	/// The user is asked to enter a 6-digit passkey on this device which is
	/// communicated via the peer device.
	PASSKEY_ENTRY = 4;
	};


	/// Used to convey information to the peer on progress typing a passkey. The
	/// various types of keypresses can be used to customize what is communicated to
	/// the user requesting a pairing.
	type PairingKeypress = strict enum {
	/// The user has entered a single digit.
	DIGIT_ENTERED = 1;

	/// The user has erased a single digit.
	DIGIT_ERASED = 2;

	/// The user has cleared the entire passkey.
	PASSKEY_CLEARED = 3;

	/// The user has finished entering the passkey.
	PASSKEY_ENTERED = 4;
	};

	/// A Bluetooth Pairing Delegate is responsible for confirming or denying
	/// pairing requests received from Bluetooth peers that connect or are
	/// being connected to the local device.
	///
	/// Any new pairing will result in a call to `PairingDelegate.OnPairingRequest`,
	/// including pairings where the InputCapability and OutputCapability are set
	/// to none. The delegate is expected to have enough context to derive whether
	/// to accept or deny the pairing.
	///
	/// Only one delegate is allowed to be set per system at a time. See
	/// `fuchsia.bluetooth.sys.Pairing` for how to set the pairing delegate.
	closed protocol PairingDelegate {
	/// Called to confirm a pairing. The pairing process will be continued if
	/// `accept` response is true and rejected otherwise.
	/// If the pairing method requires a passkey it must be included as well.
	/// Pairing methods that do not require a passkey ignore the `entered_passkey`
	/// repsonse.
	///
	/// The pairing can fail (usually by timeout or peer disconnect) before the
	/// response is received. The OnPairingComplete method will be called when this
	/// occurs. Any response sent in this case will be ignored.
	///
	/// + request `peer` information about the peer being paired
	/// + request `method` method of pairing active. See `PairingMethod`
	/// + request `displayed_passkey` a passkey to display to the user if
	/// PASSKEY_DISPLAY or PASSKEY_COMPARISON is being used. Meaningless
	/// otherwise.
	/// - response `accept` true if the pairing is accepted
	/// - response `entered_passkey` passkey entered by the user. Ignored unless
	/// method is PASSKEY_ENTRY.
	strict OnPairingRequest(struct {
	peer Peer;
	method PairingMethod;
	displayed_passkey uint32;
	}) -> (struct {
	accept bool;
	entered_passkey uint32;
	});

	/// Called when the pairing procedure for a peer has been completed.
	/// This can be due to successful completion or an error (e.g. due to cancellation
	/// by the peer, a timeout, or disconnection).
	/// * request `id` The Bluetooth peer ID of the peer which was being paired.
	/// * request `success` true if the pairing succeeded, otherwise false.
	strict OnPairingComplete(struct {
	id bt.PeerId;
	success bool;
	});

	/// Called to notify keypresses from the peer device during pairing using
	/// `PairingMethod.PASSKEY_DISPLAY`.
	///
	/// This event is used to provide key press events to the delegate for a responsive user
	/// experience as the user types the passkey on the peer device. This event will be called
	/// once for each keypress.
	///
	/// This event will only be called between when an OnPairingRequest has been sent for
	/// `id` and when OnPairingComplete is sent.
	///
	/// Note: many devices do not send these events
	/// * request `id` The peer id of the peer that sent the keypress event.
	/// * request `keypress` The type of event which was received.
	strict OnRemoteKeypress(struct {
	id bt.PeerId;
	keypress PairingKeypress;
	});

	/// The delegate can send this event to notify the peer of local keypresses
	/// during pairing using `PairingMethod.PASSKEY_ENTRY`.
	///
	/// Sending local keypress events can allow the user additional time for
	/// pairing when entering a passkey.
	///
	/// This should only be sent after an OnPairingRequest has been received
	/// with a PASSKEY_ENTRY method, and before the reponse for that pairing
	/// request.
	///
	/// * request `id` id of a peer with a pairing request active
	/// * request `keypress` the type of notification which should be sent
	strict -> OnLocalKeypress(struct {
	id bt.PeerId;
	keypress PairingKeypress;
	});
	};

	@available(added=HEAD)
	type PairingProperties = flexible union {
	/// The user is asked to accept or reject pairing.
	/// This is the minimum method - even when both devices do not support
	/// input or output, the delegate will be asked to confirm any pairing
	/// not initiated with user intent.
	1: consent struct {};
	/// The user is shown a 6-digit numerical passkey on this device which they
	/// must key in on the peer device.
	/// The passkey to be displayed is provided.
	2: passkey_display uint32;
	/// The user is shown a 6-digit numerical passkey on this device which will
	/// also be shown on the peer device. The user must compare the passkeys and
	/// accept the pairing if the passkeys match.
	/// The passkey to be displayed is provided.
	3: passkey_confirmation uint32;
	/// The user is asked to enter a 6-digit passkey on this device which is
	/// communicated via the peer device.
	4: passkey_entry struct {};
	};

	/// This protocol is active when a pairing is in progress, and provided to the
	/// PairingDelegate via the `PairingDelegate.StartRequest`
	/// The server will close this protocol with an epitaph if the pairing process
	/// completes early without success:
	/// - ZX_ERR_UNAVAILABLE - Bluetooth peer has disconnected
	/// - ZX_ERR_NOT_SUPPORTED - a passkey was provided when it was not expected
	/// - ZX_ERR_BAD_STATE - a keypress was sent when not using
	/// PairingProperties.passkey_entry
	/// - ZX_ERR_TIMED_OUT - no activity was detected, and the pairing was stopped
	@available(added=HEAD)
	closed protocol PairingRequest {
	/// Accept the pairing request.
	/// entered_passkey is required if the PairingProperties.passkey_entry
	/// method is used, ignored otherwise.
	strict Accept(table {
	1: entered_passkey uint32;
	});

	/// Reject the pairing request.
	/// Closing this protocol will also reject the pairing request.
	strict Reject();

	/// Used to communicate local keypresses to update the remote peer on
	/// the progress of the pairing. The responses to this method should
	/// be used for flow control.
	strict Keypress(struct {
	keypress PairingKeypress;
	}) -> ();


	/// Sent when the pairing method is passkey_display. Can be used to
	/// update the UI to indicate reception of keypresses.
	strict -> OnKeypress(struct {
	keypress PairingKeypress;
	});

	/// Sent once when the pairing is completed, just before the protocol is
	/// closed.
	/// The success value along with the PeerId will also be sent to the
	/// delegate using the `PairingDelegate.RequestComplete` call.
	strict -> OnComplete(struct {
	success bool;
	});
	};

	/// A Bluetooth Pairing Delegate is responsible for confirming or denying
	/// pairing requests received from Bluetooth peers that connect or are
	/// being connected to the local device.
	///
	/// Any new pairing will result in a call to `PairingDelegate.StartRequest`,
	/// including pairings where the InputCapability and OutputCapability are set
	/// to none. The delegate is expected to have enough context to derive whether
	/// to accept or reject the pairing.
	///
	/// Only one delegate is allowed to be set per system at a time. See
	/// `fuchsia.bluetooth.sys.Pairing` for how to set the pairing delegate.
	@available(added=HEAD)
	closed protocol PairingDelegate2 {
	/// Called when a pairing with `peer` is started. The pairing process is
	/// continued using the PairingRequest protocol.
	///
	/// The properties of the pairing are provided in `info` which indicates
	/// what type of interaction is intended locally.
	///
	/// Multiple requests can be active at one time for different peers, and
	/// requests can outlive this protocol. Dropping the request protocol will
	/// automatically reject the pairing.
	///
	/// All fields will always be present.
	strict StartRequest(resource table {
	/// Peer making the request.
	1: peer Peer;
	/// Properties of the pairing.
	2: info PairingProperties;
	/// Protocol used to complete the pairing process.
	3: request client_end:PairingRequest;
	});

	/// Called when the pairing procedure for a peer has been completed. This
	/// can be due to successful completion or an error (e.g. due to
	/// cancellation by the peer, a timeout, or disconnection).
	///
	/// + request `id` The Bluetooth peer ID of the peer which was being paired
	/// + request `success` true if the pairing succeeded, otherwise false
	strict RequestComplete(struct {
	id bt.PeerId;
	success bool;
	});
	};