From 888a050381b1f7cb6bcbf0b6a50e855652d7d4b2 Mon Sep 17 00:00:00 2001
From: Vincent Coubard <vincent.coubard@arm.com>
Date: Fri, 19 Jan 2018 12:18:36 +0000
Subject: [PATCH] BLE SM: Slight API adjustements and docs

---
 features/FEATURE_BLE/ble/SecurityManager.h    |  6 +--
 .../FEATURE_BLE/ble/pal/PalSecurityManager.h  | 38 ++++++++++++++++++-
 .../source/generic/GenericSecurityManager.cpp |  4 +-
 3 files changed, 41 insertions(+), 7 deletions(-)

diff --git a/features/FEATURE_BLE/ble/SecurityManager.h b/features/FEATURE_BLE/ble/SecurityManager.h
index 72f7f73c70..7cdfc71658 100644
--- a/features/FEATURE_BLE/ble/SecurityManager.h
+++ b/features/FEATURE_BLE/ble/SecurityManager.h
@@ -452,9 +452,9 @@ public:
         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
index be2110e376..e3e38da06f 100644
--- a/features/FEATURE_BLE/ble/pal/PalSecurityManager.h
+++ b/features/FEATURE_BLE/ble/pal/PalSecurityManager.h
@@ -468,6 +468,9 @@ public:
 
     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 @@ public:
         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 @@ public:
     // 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
index c3e85d0446..330748ce46 100644
--- a/features/FEATURE_BLE/source/generic/GenericSecurityManager.cpp
+++ b/features/FEATURE_BLE/source/generic/GenericSecurityManager.cpp
@@ -286,8 +286,8 @@ public:
         }
     }
 
-    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);
     }
 
     ////////////////////////////////////////////////////////////////////////////