Merge pull request ARMmbed#9 from pan-/palsm-orig

BLE SM: Slight API adjustements and docs
pan- · Jan 19, 2018 · cc7b2ba · cc7b2ba
2 parents 4fb9593 + 888a050
commit cc7b2ba
Show file tree

Hide file tree

Showing 3 changed files with 41 additions and 7 deletions.
diff --git a/features/FEATURE_BLE/ble/SecurityManager.h b/features/FEATURE_BLE/ble/SecurityManager.h
@@ -452,9 +452,9 @@ class SecurityManager {
  return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
  }
 
- virtual ble_error_t setEncryptionKeyRequirements(uint8_t minimumBitSize, uint8_t maximumBitSize) {
- (void) minimumBitSize;
- (void) maximumBitSize;
+ virtual ble_error_t setEncryptionKeyRequirements(uint8_t minimumByteSize, uint8_t maximumByteSize) {
+ (void) minimumByteSize;
+ (void) maximumByteSize;
  return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porters: override this API if security is supported. */
  }
 

diff --git a/features/FEATURE_BLE/ble/pal/PalSecurityManager.h b/features/FEATURE_BLE/ble/pal/PalSecurityManager.h
@@ -468,6 +468,9 @@ class SecurityManager : private mbed::NonCopyable<SecurityManager> {
 
  virtual ble_error_t get_secure_connections_support(bool &enabled) = 0;
 
+ /**
+ * Set the io capability that will be used during pairing feature exchange.
+ */
  virtual ble_error_t set_io_capability(io_capability_t io_capability) = 0;
 
  ////////////////////////////////////////////////////////////////////////////
@@ -484,9 +487,20 @@ class SecurityManager : private mbed::NonCopyable<SecurityManager> {
  uint16_t &timeout_in_10ms
  ) = 0;
 
+ /**
+ * Set the key size boundaries that will be used during pairing feature
+ * exchange.
+ *
+ * @param[in] min_encryption_key_size The minimum encryption key size in bytes
+ * required for pairing. This value shall be in the range [7 : 16].
+ *
+ * @param[in] max_encryption_key_size The maximum encryption key size in bytes
+ * required for pairing. This value shall be in the range
+ * [min_encryption_key_size : 16].
+ */
  virtual ble_error_t set_encryption_key_requirements(
- uint16_t min_encryption_key_bitsize,
- uint16_t max_encryption_key_bitsize
+ uint8_t min_encryption_key_size,
+ uint8_t max_encryption_key_size
  ) = 0;
 
  ////////////////////////////////////////////////////////////////////////////
@@ -583,6 +597,26 @@ class SecurityManager : private mbed::NonCopyable<SecurityManager> {
  // MITM
  //
 
+ /**
+ * Set the default passkey that will be used when the SM needs a passkey to
+ * be displayed.
+ *
+ * By default, the pal security manager generates a random passkey when a
+ * passkey has to be displayed by the application. A call to this function
+ * with a valid passkey alter this behaviour and the SecurityManager shall
+ * pass the passkey set into SecurityManagerEvent::on_passkey_display .
+ *
+ * A call to this function with a null pointer will reset the behaviour and
+ * indicates to the security manager that passkeys passed to
+ * SecurityManagerEvent::on_passkey_display shall be randomly generated.
+ *
+ * @param[in] passkey Set the passkey that shall be used by the security
+ * manager when SecurityManagerEvent::on_passkey_display is called. If
+ * passkey is a null pointer then the security manager generates a random
+ * passkey everytime it calls SecurityManagerEvent::on_passkey_display.
+ *
+ * @return BLE_ERROR_NONE or an appropriate error code.
+ */
  virtual ble_error_t set_display_passkey(const passkey_num_t passkey) = 0;
 
  /**

diff --git a/features/FEATURE_BLE/source/generic/GenericSecurityManager.cpp b/features/FEATURE_BLE/source/generic/GenericSecurityManager.cpp
@@ -286,8 +286,8 @@ class GenericSecurityManager : public SecurityManager,
  }
  }
 
- virtual ble_error_t setEncryptionKeyRequirements(uint8_t minimumBitSize, uint8_t maximumBitSize) {
- return pal.set_encryption_key_requirements(minimumBitSize, maximumBitSize);
+ virtual ble_error_t setEncryptionKeyRequirements(uint8_t minimumByteSize, uint8_t maximumByteSize) {
+ return pal.set_encryption_key_requirements(minimumByteSize, maximumByteSize);
  }
 
  ////////////////////////////////////////////////////////////////////////////