1 //****************************************************************
3 // Copyright 2015 Samsung Electronics All Rights Reserved.
5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
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
11 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
21 #ifndef OC_PROVISIONINGMANAGER_CXX_H_
22 #define OC_PROVISIONINGMANAGER_CXX_H_
26 #include "pinoxmcommon.h"
28 #include "../csdk/security/provisioning/include/ocprovisioningmanager.h"
30 #include "ocprovisioningmanager.h"
33 #include "OCPlatform_impl.h"
34 #include "oxmverifycommon.h"
35 #include "casecurityinterface.h"
36 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
37 #include "mbedtls/x509_crt.h"
42 class OCSecureResource;
44 typedef std::vector<std::shared_ptr<OCSecureResource>> DeviceList_t;
45 typedef std::vector<OicUuid_t> UuidList_t;
46 typedef std::vector<OCProvisionResult_t> PMResultList_t;
47 typedef std::function<void(PMResultList_t *result, int hasError)> ResultCallBack;
48 typedef std::function<void(uint16_t credId, uint8_t *trustCertChain,
49 size_t chainSize)>CertChainCallBack;
50 typedef std::function<OCStackResult(uint8_t verifNum[])> DisplayNumCB;
51 typedef std::function<OCStackResult()> UserConfirmNumCB;
52 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
53 typedef std::function<OCStackResult(const mbedtls_x509_crt *peerCert,
54 int depth)> PeerCertCB;
57 struct ProvisionContext
59 ResultCallBack callback;
60 ProvisionContext(ResultCallBack cb) : callback(cb){}
63 struct TrustCertChainContext
65 CertChainCallBack callback;
66 TrustCertChainContext(CertChainCallBack cb) : callback(cb){}
69 struct DisplayNumContext
71 DisplayNumCB callback;
72 DisplayNumContext(DisplayNumCB cb) : callback(cb){}
75 struct UserConfirmNumContext
77 UserConfirmNumCB callback;
78 UserConfirmNumContext(UserConfirmNumCB cb) : callback(cb){}
81 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
82 struct PeerCertContext
85 PeerCertContext(PeerCertCB cb) : callback(cb){}
90 * This class is for credential's to be set to devices.
91 * The types supported are
93 * 1: symmetric pair-wise key
94 * 2: symmetric group key
96 * 8: signed asymmetric key (aka certificate)
101 OicSecCredType_t type;
104 Credential() = default;
105 Credential(OicSecCredType_t type, size_t size) : type(type), keySize(size)
109 * API to get credential type of device.
110 * @return credential type of device.
112 OicSecCredType_t getCredentialType() const
118 * API to get size of credential key type.
119 * @return size of credential key type.
121 size_t getCredentialKeySize() const
127 * API to set credential type of device.
128 * Device can have following credential types
129 * - symmetric pair-wise key
130 * - symmetric group key
132 * - signed asymmetric key (aka certificate)
134 * @param type credential type.
136 void setCredentialType(OicSecCredType_t type)
142 * API to set size of credential key type.
143 * @param keySize credential key size.
144 * @note can be either 128 or 256 for symmetric pair-wise key
146 void setCredentialKeySize(size_t keySize)
148 this->keySize = keySize;
156 * The API is responsible for initialization of the provisioning manager. It will load
157 * provisioning database which have owned device's list and their linked status.
159 * @param dbPath file path of the sqlite3 database.
161 * @return ::OC_STACK_OK in case of success and other value otherwise.
163 static OCStackResult provisionInit(const std::string& dbPath);
166 * API to terminate the OTM process
168 * @return ::OC_STACK_OK in case of success and other value otherwise.
170 static OCStackResult terminatePM();
173 * API is responsible for discovery of devices in it's subnet. It will list
174 * all the device in subnet which are not yet owned.
176 * @param timeout Timeout in seconds, time until which function will listen to
177 * responses from server before returning the list of devices.
178 * @param list List of candidate devices to be provisioned.
179 * @return ::OC_STACK_OK in case of success and other value otherwise.
181 static OCStackResult discoverUnownedDevices(unsigned short timeout,
185 * API is responsible for discovery of devices in it's subnet. It will list
186 * all the device in subnet which are already owned by calling provisioning client.
188 * @param timeout Timeout in seconds, time until which function will listen to
189 * responses from server before returning the list of devices.
190 * @param list List of owned devices.
191 * @return ::OC_STACK_OK in case of success and other value otherwise.
193 static OCStackResult discoverOwnedDevices(unsigned short timeout,
197 * API is responsible for discovery of devices in specified endpoint/deviceID.
198 * And this function will only return the specified device's response.
200 * @param timeout Timeout in seconds, time until which function will listen to
201 * responses from server before returning the specified device.
202 * @param deviceID deviceID of target device
203 * @param foundDevice OCSecureResource object of found device.
204 * @return ::OC_STACK_OK in case of success and other value otherwise.\n
205 * ::OC_STACK_INVALID_PARAM when deviceID is NULL or ppFoundDevice is not
208 static OCStackResult discoverSingleDevice(unsigned short timeout,
209 const OicUuid_t* deviceID,
210 std::shared_ptr<OCSecureResource> &foundDevice);
213 * API is responsible for discovery of devices in specified endpoint/deviceID.
214 * And this function will only return the specified device's response.
216 * @param timeout Timeout in seconds, time until which function will listen to
217 * responses from server before returning the specified device.
218 * @param deviceID deviceID of target device.
219 * @param hostAddress MAC address of target device.
220 * @param connType ConnectivityType for discovery.
221 * @param foundDevice OCSecureResource object of found device.
222 * @return ::OC_STACK_OK in case of success and other value otherwise.
223 * ::OC_STACK_INVALID_PARAM when deviceID is NULL or ppFoundDevice is not
226 static OCStackResult discoverSingleDeviceInUnicast(unsigned short timeout,
227 const OicUuid_t* deviceID,
228 const std::string& hostAddress,
229 OCConnectivityType connType,
230 std::shared_ptr<OCSecureResource> &foundDevice);
232 #ifdef MULTIPLE_OWNER
234 * API is responsible for discovery of MOT(Mutilple Owner Transfer)
235 * devices in current subnet.
237 * @param timeout Timeout in seconds, time until which function will listen to
238 * responses from server before returning the list of devices.
239 * @param list List of MOT enabled devices.
240 * @return ::OC_STACK_OK in case of success and other value otherwise.
242 static OCStackResult discoverMultipleOwnerEnabledDevices(unsigned short timeout,
246 * API is responsible for discovery of Multiple owned device in
249 * @param timeout Timeout in seconds, time until which function will listen to
250 * responses from server before returning the list of devices.
251 * @param list List of Multiple Owned devices.
252 * @return ::OC_STACK_OK in case of success and other value otherwise.
254 static OCStackResult discoverMultipleOwnedDevices(unsigned short timeout,
260 * API for registering Pin Callback.
262 * @param InputPinCallback inputPin callback function.
263 * @return ::OC_STACK_OK in case of success and other value otherwise.
265 static OCStackResult setInputPinCallback(InputPinCallback inputPin);
268 * API for de-registering Pin Callback.
270 * @return ::OC_STACK_OK in case of success and other value otherwise.
272 static OCStackResult unsetInputPinCallback();
275 * API to set Pin Type policy.
277 * @param pinSize pin Size
278 * @param pinType Type of the pin.
279 * @return OC_STACK_OK in case of success and other value otherwise.
281 static OCStackResult setRandomPinPolicy(size_t pinSize, OicSecPinType_t pinType);
284 * API to get status of all the devices in current subnet. The status include endpoint
285 * information and doxm information which can be extracted during owned and unowned
286 * discovery. Along with this information, API will provide information about
288 * Device can have following states
289 * - ON/OFF: Device is switched on or off.
291 * @param timeout Wait time for the API.
292 * @param ownedDevList List of owned devices.
293 * @param unownedDevList List of unowned devices.
294 * @return ::OC_STACK_OK in case of success and other value otherwise.
296 static OCStackResult getDevInfoFromNetwork(unsigned short timeout,
297 DeviceList_t &ownedDevList,
298 DeviceList_t &unownedDevList);
300 * Server API to register callback to display stack generated PIN.
302 * @param displayPin Callback Method to Display generated PIN.
303 * @return ::OC_STACK_OK in case of success and other value otherwise.
305 static OCStackResult setDisplayPinCB(GeneratePinCallback displayPin);
308 * API to remove device credential and ACL from all devices in subnet.
310 * @param resultCallback Callback provided by API user, callback will be called when
311 * credential revocation is finished.
312 * @param uuid Device uuid to be revoked.
313 * @param waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device
314 * discovery in seconds.
315 * @return ::OC_STACK_OK in case of success and other value otherwise.
317 static OCStackResult removeDeviceWithUuid(unsigned short waitTimeForOwnedDeviceDiscovery,
319 ResultCallBack resultCallback);
322 * API to save ACL which has several ACE into Acl of SVR.
324 * @param acl ACL to be saved in Acl of SVR.
325 * @return OC_STACK_OK in case of success and other value otherwise.
327 static OCStackResult saveACL(const OicSecAcl_t* acl);
330 * api to register Callback for displaying verifNum in verification Just-Works
332 * @param displayNumCB Callback which is to be registered.
333 * @return OC_STACK_OK in case of success and other value otherwise.
335 static OCStackResult registerDisplayNumCallback(DisplayNumCB displayNumCB);
338 * API to De-register Callback for displaying verifNum in verification Just-Works
340 * @return OC_STACK_OK in case of success and other value otherwise.
342 static OCStackResult deregisterDisplayNumCallback();
345 * API to reister Callback for getting user confirmation in verification Just-Works
346 *@param userConfirmCB Callback which is to be registered.
347 * @return OC_STACK_OK in case of success and other value otherwise.
349 static OCStackResult registerUserConfirmCallback(UserConfirmNumCB userConfirmCB);
352 * API to De-register Callback for getting user confirmation in verification Just-Works
354 * @return OC_STACK_OK in case of success and other value otherwise.
356 static OCStackResult deregisterUserConfirmCallback();
359 * Set option for Mutual Verified Just-Works
360 * The default is both display PIN and get user confirmation.
362 static OCStackResult setVerifyOptionMask(VerifyOptionBitmask_t optionMask);
365 * Callback function to display Verification Number.
367 * @param[in] ctx User context returned in callback
368 * @param[in] verifNum Array of MUTUAL_VERIF_NUM_LEN size bytes
370 * @return OC_STACK_OK in case of success and other value otherwise.
372 static OCStackResult displayNumCallbackWrapper(void* ctx,
373 uint8_t verifNum[MUTUAL_VERIF_NUM_LEN]);
376 * Callback function to get 'Num' verification result.
378 * @return OC_STACK_OK in case of success and other value otherwise.
380 static OCStackResult confirmUserCallbackWrapper(void* ctx);
383 * API to cleanup PDM in case of timeout.
384 * It will remove the PDM_DEVICE_INIT state devices from PDM.
386 * @return OC_STACK_OK in case of success and other value otherwise.
388 static OCStackResult pdmCleanupForTimeout();
390 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
392 * API to save Trust certificate chain into Cred of SVR.
394 * @param[in] trustCertChain Trust certificate chain to be saved in Cred of SVR.
395 * @param[in] chainSize Size of trust certificate chain to be saved in Cred of SVR
396 * @param[in] encodingType Encoding type of trust certificate chain to be saved in Cred of SVR
397 * @param[out] credId CredId of saved trust certificate chain in Cred of SVR.
398 * @return OC_STACK_OK in case of success and other value otherwise.
400 static OCStackResult saveTrustCertChain(uint8_t *trustCertChain, size_t chainSize,
401 OicEncodingType_t encodingType, uint16_t *credId);
404 * API to read Trust certificate chain from SVR.
405 * Caller must free when done using the returned trust certificate
406 * @param[in] credId CredId of trust certificate chain in SVR.
407 * @param[out] trustCertChain Trust certificate chain.
408 * @param[out] chainSize Size of trust certificate chain
409 * @return OC_STACK_OK in case of success and other value otherwise.
411 static OCStackResult readTrustCertChain(uint16_t credId, uint8_t **trustCertChain,
415 * API to register Notifier for trustCertChain change.
417 * @param[in] TrustCertChainChangeCB trustCertChain Change will be
418 * notified asynchronously. User need to "delete[]" trustCertChain
419 * in the callback function.
420 * @return OC_STACK_OK in case of success and other value otherwise.
422 static OCStackResult registerTrustCertChangeNotifier(CertChainCallBack);
425 * API to remove Already registered Notifier.
427 *@return OC_STACK_OK always, kept it for symmetry.
429 static OCStackResult removeTrustCertChangeNotifier();
432 * Notifier wrapper for trustCertChain change.
434 * @param[in] ctx User context returned in callback
435 * @param[in] credId trustCertChain changed for this ID
436 * @param[in] trustCertChain trustcertchain binary blob
437 * @param[in] chainSize size of trustCertChain
439 static void certCallbackWrapper(void* ctx, uint16_t credId, uint8_t *trustCertChain,
443 * Wrapper to save the seed value to generate device UUID
445 * @param[in] seed buffer of seed value
446 * @param[in] seedSize byte length of seed
448 static OCStackResult setDeviceIdSeed(const uint8_t* seed, size_t seedSize);
451 * Callback wrapper for getting peer certificate.
453 * @param[in] ctx User context returned in callback
454 * @param[in] cert certificate
455 * @param[in] depth depth of chain
457 static int peerCertCallbackWrapper(void *ctx, const mbedtls_x509_crt *cert,
461 * API to set the function for getting peer certificate.
463 static OCStackResult setPeerCertCallback(PeerCertCB cb);
464 #endif // __WITH_DTLS__ || __WITH_TLS__
467 * This function configures SVR DB as self-ownership.
469 *@return OC_STACK_OK in case of successful configue and other value otherwise.
471 static OCStackResult configSelfOwnership();
476 * This class represents a secure virtual device, which can be provisioned by the
477 * provisioning client.
479 class OCSecureResource
482 std::weak_ptr<std::recursive_mutex> m_csdkLock;
483 OCProvisionDev_t *devPtr; // pointer to device.
487 OCSecureResource(std::weak_ptr<std::recursive_mutex> csdkLock, OCProvisionDev_t *dPtr);
492 * API to provision credentials between two devices and ACLs for the devices who
495 * @param cred Type of credentials & key size to be provisioned to the device.
496 * @param acl1 ACL for device 1. If this is not required set NULL.
497 * @param device2 Second device to be provisioned.
498 * @param acl2 ACL for device 2. If this is not required set NULL.
499 * @param resultCallback Callback will be called when provisioning request receives
500 * a response from first resource server.
501 * @return ::OC_STACK_OK in case of success and other value otherwise.
503 OCStackResult provisionPairwiseDevices(const Credential &cred, const OicSecAcl_t* acl1,
504 const OCSecureResource &device2, const OicSecAcl_t* acl2,
505 ResultCallBack resultCallback);
508 * API to do ownership transfer for un-owned device.
510 * @param resultCallback Result callback function to be invoked when
511 * ownership transfer finished.
512 * @return ::OC_STACK_OK in case of success and other value otherwise.
514 OCStackResult doOwnershipTransfer(ResultCallBack resultCallback);
517 * API to send ACL information to resource.
519 * @param acl ACL to provision.
520 * @param resultCallback Callback will be called when provisioning request
521 * receives a response from resource server.
522 * @return ::OC_STACK_OK in case of success and other value otherwise.
524 OCStackResult provisionACL(const OicSecAcl_t* acl,
525 ResultCallBack resultCallback);
528 * API to provision credential to devices.
530 * @param cred Type of credentials to be provisioned to the device.
531 * @param device2 Second device' instance, representing resource to be provisioned.
532 * @param resultCallback Callback will be called when provisioning request receives
533 * a response from first resource server.
534 * @return ::OC_STACK_OK in case of success and other value otherwise.
536 OCStackResult provisionCredentials(const Credential &cred,
537 const OCSecureResource &device2,
538 ResultCallBack resultCallback);
541 * API to remove the credential & relationship between the two devices.
543 * @param device2 Second device information to be unlinked.
544 * @param resultCallback Callback provided by API user, callback will be called when
545 * device unlink is finished.
546 * @return ::OC_STACK_OK in case of success and other value otherwise.
548 OCStackResult unlinkDevices(const OCSecureResource &device2,
549 ResultCallBack resultCallback);
552 * API to remove device credential from all devices in subnet.
554 * @param resultCallback Callback provided by API user, callback will be called when
555 * credential revocation is finished.
556 * @param waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device
557 * discovery in seconds.
558 * @return ::OC_STACK_OK in case of success and other value otherwise.
560 OCStackResult removeDevice(unsigned short waitTimeForOwnedDeviceDiscovery,
561 ResultCallBack resultCallback);
564 * API to provision DirectPairing to devices.
566 * @param pconf pointer to PCONF (Pairing Configuration).
567 * @param resultCallback Callback will be called when provisioning request receives
568 * a response from first resource server.
569 * @return ::OC_STACK_OK in case of success and other value otherwise.
571 OCStackResult provisionDirectPairing(const OicSecPconf_t *pconf,
572 ResultCallBack resultCallback);
574 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
576 * API to provision cert.
578 * @param type type of cred.
579 * @param credId id of cert.
580 * @param resultCallback Callback will be called when provisioning request
581 * receives a response from resource server.
582 * @return ::OC_STACK_OK in case of success and other value otherwise.
584 OCStackResult provisionTrustCertChain(OicSecCredType_t type, uint16_t credId,
585 ResultCallBack resultCallback);
587 #endif // __WITH_DTLS__ or __WITH_TLS__
590 * This method is used to get linked devices' IDs.
592 * @param uuidList Information about the list of linked devices uuids.
593 * @return ::OC_STACK_OK in case of success and other value otherwise.
595 OCStackResult getLinkedDevices(UuidList_t &uuidList);
598 * API to get the device ID of this resource.
601 std::string getDeviceID();
604 * API to get the information of device for provisioning.
605 * @return @ref OCProvisionDev_t Reference provides information of device for provisioning.
607 OCProvisionDev_t* getDevPtr()const;
610 * This function returns the device's IP address.
611 * @return device address.
613 std::string getDevAddr();
616 * This function returns the device's Status.
617 * @return Device status (1 = ON and 2 = OFF).
619 int getDeviceStatus();
622 * This function provides the owned status of the device.
623 * @return Device owned status.
625 bool getOwnedStatus();
628 * API to get the proper OxM for OT.
630 * @param oxm Address to save the selected OxM.
632 * @return ::OC_STACK_OK in case of success and other value otherwise.
634 OCStackResult getOTMethod(OicSecOxm_t* oxm);
637 * Common callback wrapper, which will be called from OC-APIs.
639 static void callbackWrapper(void* ctx, int nOfRes,
640 OCProvisionResult_t *arr, bool hasError);
642 #ifdef MULTIPLE_OWNER
644 * API to update 'doxm.oxmsel' to resource server.
646 * @param resultCallback Callback provided by API user, callback will be
647 * called when credential revocation is finished.
648 * @param oxmSelVal Method of multiple ownership transfer (ref. oic.sec.oxm)
649 * @return ::OC_STACK_OK in case of success and other value otherwise.
651 OCStackResult selectMOTMethod( const OicSecOxm_t oxmSelVal,
652 ResultCallBack resultCallback);
655 * API to update 'doxm.mom' to resource server.
657 * @param resultCallback Callback provided by API user, callback will be
658 * called when credential revocation is finished.
659 * @param momType Mode of multiple ownership transfer (ref. oic.sec.mom)
660 * @return ::OC_STACK_OK in case of success and other value otherwise.
662 OCStackResult changeMOTMode( const OicSecMomType_t momType,
663 ResultCallBack resultCallback);
666 * API to add preconfigured PIN to local SVR DB.
668 * @param preconfPIN Preconfig PIN which is used while multiple owner authentication
669 * @param preconfPINLength Byte length of preconfig PIN
670 * @return ::OC_STACK_OK in case of success and other value otherwise.
672 OCStackResult addPreconfigPIN(const char* preconfPIN,
673 size_t preconfPINLength);
676 * API to provision preconfigured PIN.
678 * @param resultCallback Callback provided by API user, callback will be called when
679 * credential revocation is finished.
680 * @param preconfPin Preconfig PIN which is used while multiple owner authentication
681 * @param preconfPinLength Byte length of preconfig PIN
682 * @return ::OC_STACK_OK in case of success and other value otherwise.
684 OCStackResult provisionPreconfPin(const char * preconfPin,
685 size_t preconfPinLength, ResultCallBack resultCallback);
688 * API to do multiple ownership transfer for MOT enabled device.
690 * @param resultCallback Result callback function to be invoked when
691 * multiple ownership transfer finished.
692 * @return ::OC_STACK_OK in case of success and other value otherwise.
694 OCStackResult doMultipleOwnershipTransfer(ResultCallBack resultCallback);
697 * API to remove sub-owner from resource server
699 * @param[in] subOwner sub-owner UUID to be removed
700 * @param[in] resultCallback callback provided by API user, callback will be invoked when
701 * DELETE 'subowneruuid' request recieves a response from resource server.
702 * @return ::OC_STACK_OK in case of success and other value otherwise.
704 OCStackResult removeSubOwner(const OicUuid_t* subOwnerId, ResultCallBack resultCallback);
707 * API to remove all sub-owner from resource server
709 * @param[in] resultCallback callback provided by API user, callback will be invoked when
710 * DELETE 'subowneruuid' request recieves a response from resource server.
711 * @return ::OC_STACK_OK in case of success and other value otherwise.
713 OCStackResult removeAllSubOwner(ResultCallBack resultCallback);
716 * API to get a sub-owner list
718 * @param[out] Sub-owner list of resource server
719 * @return ::OC_STACK_OK in case of success and other value otherwise.
721 OCStackResult getSubOwnerList(UuidList_t &uuidList);
724 * API to get the proper OxM for MOT.
726 * @param oxm Address to save the selected OxM.
728 * @return ::OC_STACK_OK in case of success and other value otherwise.
730 OCStackResult getMOTMethod( OicSecOxm_t* oxm);
733 * API to check whether MOT is supported.
735 * @return ::true in case of MOT supported.
737 bool isMOTSupported();
740 * API to check whether MOT is enabled.
742 * @return ::true in case of MOT enabled.
747 #endif // MULTIPLE_OWNER
750 void validateSecureResource();
754 #endif // OC_PROVISIONINGMANAGER_CXX_H_