Commit 4d7d7d3b authored by Habib Virji's avatar Habib Virji

Security code comments which are doxygen compliant

Some file using comments similar to doxygen changed.
Comments has been updated to used return instead of retval.
Comments having in/out tags has been updated.
Some functions missing space after keyword has been updated.

Change-Id: I0e9b75d2f75576f992d0ff4bafeaf5ba16917cc6
Signed-off-by: default avatarHabib Virji <habib.virji@samsung.com>
Reviewed-on: https://gerrit.iotivity.org/gerrit/5027Tested-by: default avatarjenkins-iotivity <jenkins-iotivity@opendaylight.org>
Reviewed-by: default avatarJon A. Cruz <jonc@osg.samsung.com>
Reviewed-on: https://gerrit.iotivity.org/gerrit/5757
parent c1385693
/******************************************************************
*
* Copyright 2015 Samsung Electronics All Rights Reserved.
*
*
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
******************************************************************/
//******************************************************************
//
// Copyright 2015 Samsung Electronics All Rights Reserved.
//
//-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
//-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
#ifndef _IOTVT_B64_H_
#define _IOTVT_B64_H_
......@@ -41,27 +41,27 @@ extern "C" {
#define B64DECODE_OUT_SAFESIZE(x) (((x)*3)/4)
/**
* Result code of base64 functions
* Result code of base64 functions.
*/
typedef enum {
typedef enum
{
B64_OK = 0,
B64_INVALID_PARAM,
B64_OUTPUT_BUFFER_TOO_SMALL,
B64_ERROR
}B64Result;
} B64Result;
/**
* Encode the plain message in base64.
*
* @param[in] in Plain message
* @param[in] inLen Byte length of 'in'
* @param[in,out] outBuf Output buffer
* Base64 encoded message will be written into 'outBuf'
* NOTE : This method adds a NULL to the string configuration
* @param[in] outBufSize Size of output buffer
* @param[out] outLen Byte length of encoded message
* @param in is the plain message to be converted.
* @param inLen is the byte length of plain message.
* @param outBuf is the output buffer containing Base64 encoded message.
* @note outBuf adds a NULL to the string configuration.
* @param outBufSize is the size of output buffer.
* @param outLen is the byte length of encoded message.
*
* @return B64_OK for Success, otherwise some error value
* @return ::B64_OK for Success, otherwise some error value.
*/
B64Result b64Encode(const uint8_t* in, const size_t inLen,
char* outBuf, const size_t outBufSize, uint32_t *outLen);
......@@ -69,14 +69,14 @@ B64Result b64Encode(const uint8_t* in, const size_t inLen,
/**
* Decode the encoded message in base64.
*
* @param[in] in Base64 encoded message
* @param[in] inLen Byte lenth of 'in'
* @param[in, out] outBuf Output buffer
* Base64 decoded message will be written into 'outBuf'
* @param[in] outBufSize Size of output buffer
* @param[out] outLen Byte length of decoded message
* @param in is the Base64 encoded message to be converted.
* @param inLen is the byte length of the encoded message.
* @param outBuf is the output buffer containing decoded message.
* @note outBuf adds a NULL to the string configuration.
* @param outBufSize is the size of output buffer.
* @param outLen is the byte length of decoded message.
*
* @return B64_OK for Success, otherwise some error value
* @return ::B64_OK for Success, otherwise some error value.
*/
B64Result b64Decode(const char* in, const size_t inLen,
uint8_t* outBuf, size_t outBufSize, uint32_t *outLen);
......
......@@ -36,14 +36,12 @@ extern "C" {
/**
* Initialize Amacl resource by loading data from persistent storage.
*
* @retval OC_STACK_OK for Success, otherwise some error value
* @return ::OC_STACK_OK for Success, otherwise some error value.
*/
OCStackResult InitAmaclResource();
/**
* Perform cleanup for Amacl resources.
*
* @retval none
*/
void DeInitAmaclResource();
......@@ -52,13 +50,11 @@ void DeInitAmaclResource();
* If the Amacl is found for the given resource then populate the parameter
* amsId with Amacl resource amss id.
*
* @param resource resource for which AMS service is required.
* @param amsId ID of the ams service for the given resource
*
* @retval
* OC_STACK_OK If Amacl found for the resource
* OC_STACK_ERROR If no Amacl found for the resource
* @param resource for which AMS service is required.
* @param amsId of the ams service for the given resource.
*
* @return ::OC_STACK_OK, if Amacl is found for the resource, else ::OC_STACK_ERROR,
* if no Amacl found for the resource.
*/
OCStackResult AmaclGetAmsDeviceId(const char *resource, OicUuid_t *amsId);
......
......@@ -21,17 +21,18 @@
#ifndef IOTVT_SRM_AMSMGR_H
#define IOTVT_SRM_AMSMGR_H
#include <stdlib.h>
#include <stdint.h>
#include "ocstack.h"
#include "logger.h"
#include "policyengine.h"
#include "securevirtualresourcetypes.h"
#include "cainterface.h"
#include <stdlib.h>
#include <stdint.h>
typedef struct PEContext PEContext_t;
/**
* @brief The AMS context..
* The AMS context.
*/
typedef struct AmsMgrContext
{
......@@ -40,103 +41,95 @@ typedef struct AmsMgrContext
CARequestInfo_t *requestInfo;
} AmsMgrContext_t;
/**
* @brief This method updates AmsMgr context's endpoint & requestInfo
* This method updates AmsMgr context's endpoint & requestInfo.
*
* @param context Policy engine context.
* @param endpoint CA Endpoint info of the requester
* @param requestInfo CA RequestInfo of the requester
* @param context is the policy engine context.
* @param endpoint is the CA Endpoint info of the requester.
* @param requestInfo is the CA RequestInfo of the requester.
*
* @return ::OC_STACK_OK if successful, else other value in case of error.
*/
OCStackResult UpdateAmsMgrContext(PEContext_t *context, const CAEndpoint_t *endpoint,
const CARequestInfo_t *requestInfo);
OCStackResult UpdateAmsMgrContext(PEContext_t *context,
const CAEndpoint_t *endpoint,
const CARequestInfo_t *requestInfo);
/**
*
* This method is called by PolicyEngine to Discover AMS service.
* It sends muticast discovery request such as
* /oic/sec/doxm?deviceid="AMSSrvcDeviceID" to discover AMS service
* with deviceId="AMSSrvcDeviceID"
*
* @param context Policy engine context.
* with deviceId="AMSSrvcDeviceID".
*
* @retval
* OC_STACK_OK If able to successfully send multicast discovery request.
* OC_STACK_ERROR If unable to successfully send multicast discovery request due to error.
* @param context is the policy engine context.
*
* @return ::OC_STACK_OK,If able to successfully send multicast discovery request.
* else ::OC_STACK_ERROR, If unable to successfully send multicast discovery request
* due to error.
*/
OCStackResult DiscoverAmsService(PEContext_t *context);
/**
*
* This method sends unicast request to retrieve the secured port info of the
* discovered AMS service. It sends unicast discovery request such as
* /oic/res?rt="oic.sec.doxm" to the discovered AMS service
* /oic/res?rt="oic.sec.doxm" to the discovered AMS service.
*
* @param context Policy engine context.
*
* @retval
* OC_STACK_OK If able to successfully send unicast discovery request
* OC_STACK_ERROR If unable to successfully send unicast discovery request due to error
* @param context is the policy engine context.
*
* @return ::OC_STACK_OK,If able to successfully send unicast discovery request.
* else ::OC_STACK_ERROR, If unable to successfully send unicast discovery request
* due to error.
*/
OCStackResult SendUnicastSecurePortDiscovery(PEContext_t *context,OCDevAddr *devAddr,
OCConnectivityType connType);
OCStackResult SendUnicastSecurePortDiscovery(PEContext_t *context,
OCDevAddr *devAddr,
OCConnectivityType connType);
/**
*
* This method sends unicast request to AMS service to get ACL for
* the Subject and/or Resource. It sends unicast request such as
* /oic/sec/acl?sub="subjectId";rsrc="/a/led" to get the ACL for
* the subject & resource
* the subject & resource.
*
* @param context Policy engine context.
* @param context is the policy engine context.
*
* @retval
* OC_STACK_OK If able to successfully send unicast ACL request
* OC_STACK_ERROR If unable to successfully send unicast ACL request due to error
* @return ::OC_STACK_OK, If able to successfully send unicast ACL request.
* ::OC_STACK_ERROR, If unable to successfully send unicast ACL request due to error.
*
*/
OCStackResult SendAclReq(PEContext_t *context, OCDevAddr *devAddr, OCConnectivityType connType,
uint16_t securedPort);
OCStackResult SendAclReq(PEContext_t *context,
OCDevAddr *devAddr,
OCConnectivityType connType,
uint16_t securedPort);
/*
* Cleanup CARequestInfo_t object
* @param requestInfo pointer to RequestInfo_t object
* Cleanup CARequestInfo_t object.
*
* @param requestInfo is the pointer to @ref CARequestInfo_t.
*/
void FreeCARequestInfo(CARequestInfo_t *requestInfo);
/*
* This method is used by Policy engine to checks Amacl resource.
* If Amacl is found then it fills up context->amsMgrContext->amsDeviceId
* with amsID of the Amacl else leaves it empty.
*
* @param context Policy engine context.
* @param context is the policy engine context.
*
* @return true if AMacl for the resource is found
* false if AMacl for the resource is not found
* @return true, if Amacl for the resource is found. false, if Amacl for the
* resource is not found
*/
bool FoundAmaclForRequest(PEContext_t *context);
/*
* This method is used by Policy engine to process AMS request
*
* @param context Policy engine context.
* This method is used by Policy engine to process AMS request.
*
* @param context is the policy engine context.
*/
void ProcessAMSRequest(PEContext_t *context);
/*
* This method is used by Policy engine to free AMS context requestInfo
*
* @param requestInfo pointer to CARequestInfo_t.
* This method is used by Policy engine to free AMS context requestInfo/
*
* @param requestInfo is the pointer to @ref CARequestInfo_t.
*/
void FreeCARequestInfo(CARequestInfo_t *requestInfo);
......
......@@ -105,15 +105,6 @@ OCStackResult AddCredential(OicSecCred_t * cred);
*/
OCStackResult RemoveCredential(const OicUuid_t *credId);
/**
* Remove all credential data on credential resource and persistent storage
*
* @retval
* OC_STACK_OK - no errors
* OC_STACK_ERROR - stack process error
*/
OCStackResult RemoveAllCredentials(void);
#if defined(__WITH_DTLS__)
/**
* This internal callback is used by lower stack (i.e. CA layer) to
......
......@@ -29,43 +29,46 @@ extern "C" {
#endif
/**
* This function stores CRL in SRM
* @param crl - CRL
* This function stores CRL in SRM.
*
* @returns OC_STACK_OK for Success, otherwise some error value
* @param crl to be stored in SRM.
*
* @return ::OC_STACK_OK for Success, otherwise some error value.
*/
OCStackResult UpdateCRLResource(const OicSecCrl_t *crl);
/**
* This function get encoded with base64 CRL from SRM
* This function get encoded with base64 CRL from SRM.
*
* @note Caller responsible for resulting string memory (use OICFree to remove it).
*
* @returns encoded CRL with base64 format. NULL if error occured (e.g. CRL did not set)
* @note Caller responsible for resulting string memory (use OICFree to remove it)
* @return encoded CRL with base64 format. NULL if error occured (e.g. CRL did not set).
*/
char* GetBase64CRL();
/**
* This function get encoded with DER CRL from SRM
* This function get encoded with DER CRL from SRM.
*
* @returns encoded CRL with DER format. array len is 0 if error occured (e.g. CRL did not set)
* @return encoded CRL with DER format. array len is 0 if error occured (e.g. CRL did not set).
*/
void GetDerCrl(ByteArray crlArray);
/**
* This function get CRL from SRM
* This function get CRL from SRM.
*
* @param crl [out] - pointer to buffer that contains crl. Shoul be not NULL. Buffer
* @param crl is a pointer to buffer that contains crl. Shoul be not NULL. Buffer
* will be allocated by the function and content of *crl will be ignored.
* @param outlen [out] - pointer to length of the CRL buffer. Shoul be not NULL.
* @param outlen is a pointer to length of the CRL buffer. Should be not NULL.
*
* @returns OC_STACK_OK if success and errorcode otherwise.
* @note Caller responsible for crl buffer memory (use OICFree to free it)
* @note Caller responsible for crl buffer memory (use OICFree to free it).
*
* @return ::OC_STACK_OK if success, otherwise some error value.
*/
OicSecCrl_t * JSONToCrlBin(const char * jsonStr);
/**
* Initialize CLR resource by loading data from persistent storage.
* Initialize CRL resource by loading data from persistent storage.
*
* @returns OC_STACK_OK for Success, otherwise some error value
* @return ::OC_STACK_OK for Success, otherwise some error value.
*/
OCStackResult InitCRLResource();
......@@ -74,15 +77,15 @@ OCStackResult InitCRLResource();
*/
void DeInitCRLResource();
/**
* Get an instance of CRL resource.
*
* @return reference to the @ref OicSecCrl_t, holding reference to CRL resource.
*/
OicSecCrl_t *GetCRLResource();
OCEntityHandlerResult CRLEntityHandler(OCEntityHandlerFlag flag,
OCEntityHandlerRequest * ehRequest,
void* callbackParameter);
#ifdef __cplusplus
}
#endif
#endif //IOTVT_SRM_CRLR_H
......@@ -30,21 +30,21 @@ extern "C" {
/**
* Initialize DOXM resource by loading data from persistent storage.
*
* @retval OC_STACK_OK for Success, otherwise some error value
* @return ::OC_STACK_OK for Success, otherwise some error value.
*/
OCStackResult InitDoxmResource();
/**
* Perform cleanup for DOXM resources.
*
* @retval OC_STACK_OK for Success, otherwise some error value
* @return ::OC_STACK_OK for Success, otherwise some error value.
*/
OCStackResult DeInitDoxmResource();
/**
* This method is used by SRM to retrieve DOXM resource data..
*
* @retval reference to @ref OicSecDoxm_t, binary format of Doxm resource data
* @return reference to @ref OicSecDoxm_t, binary format of Doxm resource data.
*/
const OicSecDoxm_t* GetDoxmResourceData();
......@@ -53,44 +53,43 @@ const OicSecDoxm_t* GetDoxmResourceData();
* The JSON DOXM can be from persistent database or
* or received as PUT/POST request.
*
* @param[in] jsonStr doxm data in json string.
* @return pointer to OicSecDoxm_t.
* @param jsonStr is a doxm data in json string.
*
* @note Caller needs to invoke OCFree after done
* using the return pointer
* @note Caller needs to invoke OCFree after done using the return pointer.
*
* @return pointer to @ref OicSecDoxm_t.
*/
OicSecDoxm_t * JSONToDoxmBin(const char * jsonStr);
/**
* This method converts DOXM data into JSON format.
* Caller needs to invoke 'free' when finished done using
* return string
* return string.
*
* @param[in] doxm Pointer to OicSecDoxm_t.
* @return pointer to json string.
* @note Caller needs to invoke OCFree after done using the return pointer.
*
* @note Caller needs to invoke OCFree after done
* using the return pointer
* @return pointer to the json string.
*/
char * BinToDoxmJSON(const OicSecDoxm_t * doxm);
/**
* This method returns the SRM device ID for this device.
*
* @retval OC_STACK_OK for Success, otherwise some error value
* @return ::OC_STACK_OK for Success, otherwise some error value.
*/
OCStackResult GetDoxmDeviceID(OicUuid_t *deviceID);
/**
* @brief Gets the OicUuid_t value for the owner of this device.
* Gets the OicUuid_t value for the owner of this device.
*
* @return OC_STACK_OK if devOwner is a valid UUID, otherwise OC_STACK_ERROR.
* @return ::OC_STACK_OK if devOwner is a valid UUID, otherwise ::OC_STACK_ERROR.
*/
OCStackResult GetDoxmDevOwnerId(OicUuid_t *devOwner);
/** This function deallocates the memory for OicSecDoxm_t .
*
* @param[in] doxm Pointer to OicSecDoxm_t.
* @param doxm is the pointer to @ref OicSecDoxm_t.
*/
void DeleteDoxmBinData(OicSecDoxm_t* doxm);
......@@ -105,5 +104,3 @@ void RestoreDoxmToInitState();
#endif
#endif //IOTVT_SRM_DOXMR_H
......@@ -31,7 +31,6 @@
typedef struct AmsMgrContext AmsMgrContext_t;
typedef enum PEState
{
STOPPED = 0, //Policy engine state machine is not running
......@@ -40,7 +39,6 @@ typedef enum PEState
BUSY //Can't process new request as processing other requests
} PEState_t;
typedef struct PEContext
{
PEState_t state;
......@@ -56,13 +54,12 @@ typedef struct PEContext
/**
* Check whether a request should be allowed.
*
* @param context Pointer to Policy Engine context to use.
* @param subjectId Pointer to Id of the requesting entity.
* @param resource Pointer to URI of Resource being requested.
* @param permission Requested permission.
* @param context is the pointer to Policy Engine context to use.
* @param subjectId is the pointer to Id of the requesting entity.
* @param resource is the pointer to URI of Resource being requested.
* @param permission is the requested permission.
*
* @return ACCESS_GRANTED if request should go through,
* otherwise some flavor of ACCESS_DENIED
* @return ::ACCESS_GRANTED if request should go through, otherwise some flavor of ACCESS_DENIED.
*/
SRMAccessResponse_t CheckPermission(
PEContext_t *context,
......@@ -74,33 +71,35 @@ SRMAccessResponse_t CheckPermission(
* Initialize the Policy Engine. Call this before calling CheckPermission().
* TODO Eventually this and DeInit() need to be called from a new
* "SRMInit(SRMContext_t *)" function, TBD after BeachHead.
* @param context Pointer to Policy Engine context to initialize.
* @return OC_STACK_OK for Success, otherwise some error value
* @param context is the pointer to Policy Engine context to initialize.
*
* @return ::OC_STACK_OK for Success, otherwise some error value.
*/
OCStackResult InitPolicyEngine(PEContext_t *context);
/**
* De-Initialize the Policy Engine. Call this before exiting to allow Policy
* Engine to do cleanup on context.
* @param context Pointer to Policy Engine context to de-initialize.
* @return none
*
* @param context is the pointer to Policy Engine context to de-initialize.
*/
void DeInitPolicyEngine(PEContext_t *context);
/**
* Return the uint16_t CRUDN permission corresponding to passed CAMethod_t.
* Get CRUDN permission for a method.
*
* @param method is CRUDN permission being seeked.
*
* @return the uint16_t CRUDN permission .
*/
uint16_t GetPermissionFromCAMethod_t(const CAMethod_t method);
/*
* This method reset Policy Engine context to default state and update
* it's state to @param state.
*
* @param context Policy engine context.
* @param state Set Policy engine state to this.
*
* @return none
* @param context is the policy engine context.
* @param state set Policy engine state to this.
*/
void SetPolicyEngineState(PEContext_t *context, const PEState_t state);
......
......@@ -28,14 +28,14 @@ extern "C" {
/**
* Initialize Pstat resource by loading data from persistent storage.
*
* @retval OC_STACK_OK for Success, otherwise some error value
* @return ::OC_STACK_OK for Success, otherwise some error value.
*/
OCStackResult InitPstatResource();
/**
* Perform cleanup for Pstat resources.
*
* @retval OC_STACK_OK for Success, otherwise some error value
* @return ::OC_STACK_OK for Success, otherwise some error value.
*/
OCStackResult DeInitPstatResource();
......
......@@ -28,85 +28,85 @@ extern "C" {
#endif
/**
* @brief Register Persistent storage callback.
* @param persistentStorageHandler [IN] Pointers to open, read, write, close & unlink handlers.
* @return
* OC_STACK_OK - No errors; Success
* OC_STACK_INVALID_PARAM - Invalid parameter
* Register Persistent storage callback.
*
* @param persistentStorageHandler [IN] Pointers to open, read, write, close & unlink handlers.
*
* @return ::OC_STACK_OK is no errors and successful. ::OC_STACK_INVALID_PARAM for invalid parameter.
*/
OCStackResult SRMRegisterPersistentStorageHandler(OCPersistentStorage* persistentStorageHandler);
/**
* @brief Get Persistent storage handler pointer.
* @return
* The pointer to Persistent Storage callback handler
* Get Persistent storage handler pointer.
*
* @return The pointer to Persistent Storage callback handler.
*/
OCPersistentStorage* SRMGetPersistentStorageHandler();
/**
* @brief Register request and response callbacks.
* Requests and responses are delivered in these callbacks.
* @param reqHandler [IN] Request handler callback ( for GET,PUT ..etc)
* @param respHandler [IN] Response handler callback.
* @param errHandler [IN] Error handler callback.
* @return
* OC_STACK_OK - No errors; Success
* OC_STACK_INVALID_PARAM - Invalid parameter
* Register request and response callbacks. Requests and responses are delivered in these callbacks.
*
* @param reqHandler Request handler callback ( for GET,PUT ..etc)
* @param respHandler Response handler callback.
* @param errHandler Error handler callback.
*
* @return ::OC_STACK_OK is no errors and successful. ::OC_STACK_INVALID_PARAM for invalid parameter.
*/
OCStackResult SRMRegisterHandler(CARequestCallback reqHandler,
CAResponseCallback respHandler,
CAErrorCallback errHandler);
/**
* @brief Initialize all secure resources ( /oic/sec/cred, /oic/sec/acl, /oic/sec/pstat etc).
* @return OC_STACK_OK for Success, otherwise some error value