resource/csdk/security/include/pinoxmcommon.h

   1 //******************************************************************
   2 //
   3 // Copyright 2015 Samsung Electronics All Rights Reserved.
   4 //
   5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   6 //
   7 // Licensed under the Apache License, Version 2.0 (the "License");
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //      http://www.apache.org/licenses/LICENSE-2.0
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an "AS IS" BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  20
  21 #ifndef PIN_CALLBACK_DEF_H_
  22 #define PIN_CALLBACK_DEF_H_
  23
  24 #include "securevirtualresourcetypes.h"
  25 #include "casecurityinterface.h"
  26
  27 #ifdef __cplusplus
  28  extern "C" {
  29 #endif // __cplusplus
  30
  31 #define OXM_RANDOM_PIN_DEFAULT_SIZE (8)
  32 #define OXM_RANDOM_PIN_DEFAULT_PIN_TYPE (NUM_PIN | LOWERCASE_CHAR_PIN | UPPERCASE_CHAR_PIN)
  33 #define OXM_RANDOM_PIN_MIN_SIZE (4)
  34 #define OXM_RANDOM_PIN_MAX_SIZE (32)
  35 #define OXM_PRECONFIG_PIN_MAX_SIZE (OXM_RANDOM_PIN_MAX_SIZE)
  36
  37 /** Number of PIN type */
  38 #define OXM_PIN_TYPE_COUNT 3
  39
  40 /**
  41  * PIN type definition.
  42  * This type supports multiple bit set.
  43  * e.g.) NUM_PIN | UPPERCASE_CHAR_PIN
  44  */
  45 typedef enum OicSecPinType{
  46     NUM_PIN            = (0x1 << 0),    //Numeric PIN
  47     UPPERCASE_CHAR_PIN = (0x1 << 1),    //uppercase character PIN
  48     LOWERCASE_CHAR_PIN = (0x1 << 2)     //lowercase character PIN
  49 }OicSecPinType_t;
  50
  51 /**
  52  * Function pointer to print pin code.
  53  */
  54 typedef void (*GeneratePinCallback)(char* pinData, size_t pinSize);
  55
  56 /**
  57  * Function pointer to input pin code.
  58  */
  59 typedef void (*InputPinCallback)(char* pinBuf, size_t bufSize);
  60
  61 /**
  62  * Function pointer for getting master key for raw public key OTM.
  63  * Callback is expected to set *rpkMasterKey pointer to binary data buffer
  64  * containing the key. Master key lenght must not exceed OXM_RPK_MASTER_KEY_MAX_SIZE.
  65  */
  66 typedef void (*GetRPKMasterKeyCallback)(char **rpkMasterKey, size_t *rpkMasterKeyLen);
  67
  68 /**
  69  * Function pointer to close the displied PIN.
  70  */
  71 typedef void (*ClosePinDisplayCallback)(void);
  72
  73 /**
  74  * Function to setting generate PIN callback from user.
  75  *
  76  * @param pinCB implementation of generate PIN callback.
  77  */
  78 void SetGeneratePinCB(GeneratePinCallback pinCB);
  79
  80 /**
  81  * Function to set preconfigured PIN value.
  82  *
  83  * @param[in] pin    PIN data
  84  * @param[in] pinLen byte length of PIN
  85  */
  86 OCStackResult SetPin(const char * pin, size_t pinLen);
  87
  88 /**
  89  * Function to unset preconfigured PIN.
  90  */
  91 OCStackResult UnSetPin();
  92
  93 /**
  94  * Function to setting input PIN callback from user.
  95  *
  96  * @param pinCB implementation of input PIN callback.
  97  */
  98 void SetInputPinCB(InputPinCallback pinCB);
  99
 100 /**
 101  * Function to set the close PIN callback
 102  * This callback will be invoked when PIN based OTM is finished.
 103  *
 104  * @param closeCB implementation of close PIN callback.
 105  */
 106 void SetClosePinDisplayCB(ClosePinDisplayCallback closeCB);
 107
 108 /**
 109  * Function to unset the input PIN callback.
 110  * NOTE : Do not call this function while PIN based ownership transfer.
 111  */
 112 void UnsetInputPinCB();
 113
 114 /**
 115  * Function to unset the PIN generation callback.
 116  * NOTE : Do not call this function while PIN based ownership transfer.
 117  */
 118 void UnsetGeneratePinCB();
 119
 120 /**
 121  * Function to unset the PIN close callback.
 122  * NOTE : Do not call this function while PIN based ownership transfer is in progress.
 123  */
 124 void UnsetClosePinCB();
 125
 126 /**
 127  * Function to generate random PIN.
 128  * This function will send generated PIN to user via callback.
 129  *
 130  * @param pinBuffer is the reference to the buffer to store the generated PIN data.
 131  * @param bufferSize is the size of buffer.
 132  *
 133  * @return ::OC_STACK_OK in case of success or other value in case of error.
 134  */
 135 OCStackResult GeneratePin(char* pinBuffer, size_t bufferSize);
 136
 137 /**
 138  * Function to input PIN callback via input callback.
 139  *
 140  * @param[in,out] pinBuffer is the reference to the buffer to store the inputed PIN data.
 141  * @param[in] bufferSize is the size of buffer.
 142  *
 143  * @return ::OC_STACK_OK in case of success or other value in ccase of error.
 144  */
 145 OCStackResult InputPin(char* pinBuffer, size_t bufferSize);
 146
 147 /**
 148  * Function to invoke the callback for close a PIN dispaly.
 149  * NOTE : This function will be invoked from SRM while OTM
 150  */
 151 void ClosePinDisplay();
 152
 153 #ifdef MULTIPLE_OWNER
 154 /**
 155  * Function to save the Pre-configured PIN.
 156  *
 157  * @param[in] pinBuffer PIN data
 158  * @param[in] pinLength byte length of PIN
 159  *
 160  * @return ::OC_STACK_SUCCESS in case of success or other value in ccase of error.
 161  */
 162 OCStackResult SetPreconfigPin(const char *pinBuffer, size_t pinLength);
 163 #endif
 164
 165 /**
 166  * Function to setting the policy for random PIN generation
 167  *
 168  * @param[in] pinSize Byte length of random PIN
 169  * @param[in] pinType Type of random PIN (ref OicSecPinType)
 170  *
 171  * @return ::OC_STACK_OK in case of success or other value in case of error.
 172  */
 173 OCStackResult SetRandomPinPolicy(size_t pinSize, OicSecPinType_t pinType);
 174
 175 #ifdef __WITH_DTLS__
 176
 177 /**
 178  * This function is used by OTM and SRM to
 179  * register device UUID is required to derive the temporal PSK.
 180  */
 181 void SetUuidForPinBasedOxm(const OicUuid_t* uuid);
 182
 183 /**
 184  * This internal callback is used while Random PIN based OTM.
 185  * This callback will be used to establish a temporary secure session according to
 186  * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256.
 187  *
 188  * @param[in]  type type of PSK data required by tinyDTLS layer during DTLS handshake.
 189  * @param[in]  UNUSED1 UNUSED.
 190  * @param[in]  UNUSED2 UNUSED.
 191  * @param[out] result  Must be filled with the requested information.
 192  * @param[in]  result_length  Maximum size of @p result.
 193  *
 194  * @return The number of bytes written to @p result or a value
 195  *         less than zero on error.
 196  */
 197 int32_t GetDtlsPskForRandomPinOxm( CADtlsPskCredType_t type,
 198               const unsigned char *UNUSED1, size_t UNUSED2,
 199               unsigned char *result, size_t result_length);
 200
 201 #ifdef MULTIPLE_OWNER
 202 /**
 203  * This internal callback is used while Random PIN based MOT.
 204  * This callback will be used to establish a temporary secure session according to
 205  * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256.
 206  *
 207  * @param[in]  type type of PSK data required by tinyDTLS layer during DTLS handshake.
 208  * @param[in]  UNUSED1 UNUSED.
 209  * @param[in]  UNUSED2 UNUSED.
 210  * @param[out] result  Must be filled with the requested information.
 211  * @param[in]  result_length  Maximum size of @p result.
 212  *
 213  * @return The number of bytes written to @p result or a value
 214  *         less than zero on error.
 215  */
 216 int32_t GetDtlsPskForMotRandomPinOxm( CADtlsPskCredType_t type,
 217               const unsigned char *UNUSED1, size_t UNUSED2,
 218               unsigned char *result, size_t result_length);
 219
 220
 221 /**
 222  * This internal callback is used while Preconfigured-PIN OTM.
 223  * This callback will be used to establish a temporary secure session according to
 224  * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256.
 225  *
 226  * @param[in]  type type of PSK data required by tinyDTLS layer during DTLS handshake.
 227  * @param[in]  UNUSED1 UNUSED.
 228  * @param[in]  UNUSED2 UNUSED.
 229  * @param[out] result  Must be filled with the requested information.
 230  * @param[in]  result_length  Maximum size of @p result.
 231  *
 232  * @return The number of bytes written to @p result or a value
 233  *         less than zero on error.
 234  */
 235 int32_t GetDtlsPskForPreconfPinOxm( CADtlsPskCredType_t type,
 236               const unsigned char *UNUSED1, size_t UNUSED2,
 237               unsigned char *result, size_t result_length);
 238
 239
 240 /**
 241  * This internal callback is used while Preconfigured-PIN MOT.
 242  * This callback will be used to establish a temporary secure session according to
 243  * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256.
 244  *
 245  * @param[in]  type type of PSK data required by tinyDTLS layer during DTLS handshake.
 246  * @param[in]  UNUSED1 UNUSED.
 247  * @param[in]  UNUSED2 UNUSED.
 248  * @param[out] result  Must be filled with the requested information.
 249  * @param[in]  result_length  Maximum size of @p result.
 250  *
 251  * @return The number of bytes written to @p result or a value
 252  *         less than zero on error.
 253  */
 254 int32_t GetDtlsPskForMotPreconfPinOxm( CADtlsPskCredType_t type,
 255               const unsigned char *UNUSED1, size_t UNUSED2,
 256               unsigned char *result, size_t result_length);
 257
 258 #endif //MULTIPLE_OWNER
 259
 260 /**
 261  * API to derive the PSK based on PIN and new device's UUID.
 262  * New device's UUID should be set through SetUuidForPinBasedOxm() API before this API is invoked.
 263  *
 264  * @param[out] result generated PSK
 265  *
 266  * @return 0 for success, otherwise error.
 267  */
 268 int DerivePSKUsingPIN(uint8_t* result);
 269
 270 #endif //__WITH_DTLS__
 271
 272 #ifdef __cplusplus
 273 }
 274 #endif
 275
 276 #endif //PIN_CALLBACK_DEF_H_