Skip to content

Commit cd88f8c

Browse files
JacobBarthelmehJacobBarthelmeh
committed
adding in more function comments
1 parent 62fe4eb commit cd88f8c

4 files changed

Lines changed: 556 additions & 12 deletions

File tree

‎wolfhsm/wh_auth.h‎

Lines changed: 98 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -152,45 +152,133 @@ typedef struct whAuthConfig_t {
152152

153153
/** Public Auth Manager API Functions */
154154

155-
/* Initialize the auth manager */
155+
/**
156+
* @brief Initialize the auth manager.
157+
*
158+
* @param[in] context Pointer to the auth context.
159+
* @param[in] config Pointer to the auth configuration.
160+
* @return int Returns 0 on success, or a negative error code on failure.
161+
*/
156162
int wh_Auth_Init(whAuthContext* context, const whAuthConfig* config);
157163

158-
/* Cleanup the auth manager */
164+
/**
165+
* @brief Cleanup the auth manager.
166+
*
167+
* @param[in] context Pointer to the auth context.
168+
* @return int Returns 0 on success, or a negative error code on failure.
169+
*/
159170
int wh_Auth_Cleanup(whAuthContext* context);
160171

161-
/* Authenticate and login a user */
172+
/**
173+
* @brief Authenticate and login a user.
174+
*
175+
* @param[in] context Pointer to the auth context.
176+
* @param[in] client_id The client ID making the request.
177+
* @param[in] method The authentication method to use.
178+
* @param[in] username The username to authenticate.
179+
* @param[in] auth_data Pointer to the authentication data.
180+
* @param[in] auth_data_len Length of the authentication data.
181+
* @param[out] loggedIn Pointer to store the login status.
182+
* @return int Returns 0 on success, or a negative error code on failure.
183+
*/
162184
int wh_Auth_Login(whAuthContext* context, uint8_t client_id,
163185
whAuthMethod method, const char* username,
164186
const void* auth_data, uint16_t auth_data_len, int* loggedIn);
165187

166-
/* Logout a user */
188+
/**
189+
* @brief Logout a user.
190+
*
191+
* @param[in] context Pointer to the auth context.
192+
* @param[in] user_id The user ID to logout.
193+
* @return int Returns 0 on success, or a negative error code on failure.
194+
*/
167195
int wh_Auth_Logout(whAuthContext* context, whUserId user_id);
168196

169-
/* Check authorization for an action */
197+
/**
198+
* @brief Check authorization for an action.
199+
*
200+
* @param[in] context Pointer to the auth context.
201+
* @param[in] group The group to check authorization for.
202+
* @param[in] action The action to check authorization for.
203+
* @return int Returns 0 if authorized, or a negative error code on failure.
204+
*/
170205
int wh_Auth_CheckRequestAuthorization(whAuthContext* context, uint16_t group,
171206
uint16_t action);
172207

208+
/**
209+
* @brief Check if a key is authorized for use. @TODO, this is a place holder
210+
* for calls to check key use but wolfHSM currently does not call it before key
211+
* use.
212+
*
213+
* @param[in] context Pointer to the auth context.
214+
* @param[in] key_id The key ID to check authorization for.
215+
* @param[in] action The action to check authorization for.
216+
* @return int Returns 0 if authorized, or a negative error code on failure.
217+
*/
173218
int wh_Auth_CheckKeyAuthorization(whAuthContext* context, uint32_t key_id,
174219
uint16_t action);
175220

176-
/* Add a new user */
221+
/**
222+
* @brief Add a new user.
223+
*
224+
* @param[in] context Pointer to the auth context.
225+
* @param[in] username The username for the new user.
226+
* @param[out] out_user_id Pointer to store the new user ID.
227+
* @param[in] permissions The permissions for the new user.
228+
* @param[in] method The authentication method for the new user.
229+
* @param[in] credentials Pointer to the credentials data.
230+
* @param[in] credentials_len Length of the credentials data.
231+
* @return int Returns 0 on success, or a negative error code on failure.
232+
*/
177233
int wh_Auth_UserAdd(whAuthContext* context, const char* username,
178234
whUserId* out_user_id, whAuthPermissions permissions,
179235
whAuthMethod method, const void* credentials,
180236
uint16_t credentials_len);
181237

182-
/* Delete a user */
238+
/**
239+
* @brief Delete a user.
240+
*
241+
* @param[in] context Pointer to the auth context.
242+
* @param[in] user_id The user ID to delete.
243+
* @return int Returns 0 on success, or a negative error code on failure.
244+
*/
183245
int wh_Auth_UserDelete(whAuthContext* context, whUserId user_id);
184246

185-
/* Set user permissions */
247+
/**
248+
* @brief Set user permissions.
249+
*
250+
* @param[in] context Pointer to the auth context.
251+
* @param[in] user_id The user ID to set permissions for.
252+
* @param[in] permissions The new permissions to set.
253+
* @return int Returns 0 on success, or a negative error code on failure.
254+
*/
186255
int wh_Auth_UserSetPermissions(whAuthContext* context, whUserId user_id,
187256
whAuthPermissions permissions);
188257

189-
/* Get user information */
258+
/**
259+
* @brief Get user information.
260+
*
261+
* @param[in] context Pointer to the auth context.
262+
* @param[in] username The username to look up.
263+
* @param[out] out_user_id Pointer to store the user ID.
264+
* @param[out] out_permissions Pointer to store the user permissions.
265+
* @return int Returns 0 on success, or a negative error code on failure.
266+
*/
190267
int wh_Auth_UserGet(whAuthContext* context, const char* username,
191268
whUserId* out_user_id, whAuthPermissions* out_permissions);
192269

193-
/* Set user credentials */
270+
/**
271+
* @brief Set user credentials.
272+
*
273+
* @param[in] context Pointer to the auth context.
274+
* @param[in] user_id The user ID to set credentials for.
275+
* @param[in] method The authentication method.
276+
* @param[in] current_credentials Pointer to the current credentials data.
277+
* @param[in] current_credentials_len Length of the current credentials data.
278+
* @param[in] new_credentials Pointer to the new credentials data.
279+
* @param[in] new_credentials_len Length of the new credentials data.
280+
* @return int Returns 0 on success, or a negative error code on failure.
281+
*/
194282
int wh_Auth_UserSetCredentials(whAuthContext* context, whUserId user_id,
195283
whAuthMethod method,
196284
const void* current_credentials,

‎wolfhsm/wh_auth_base.h‎

Lines changed: 94 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,20 +33,62 @@
3333
#include "wolfhsm/wh_common.h"
3434
#include "wolfhsm/wh_auth.h"
3535

36-
36+
/**
37+
* @brief Initialize the auth base backend.
38+
*
39+
* @param[in] context Pointer to the auth base context.
40+
* @param[in] config Pointer to the configuration data.
41+
* @return int Returns 0 on success, or a negative error code on failure.
42+
*/
3743
int wh_AuthBase_Init(void* context, const void* config);
3844

45+
/**
46+
* @brief Cleanup the auth base backend.
47+
*
48+
* @param[in] context Pointer to the auth base context.
49+
* @return int Returns 0 on success, or a negative error code on failure.
50+
*/
3951
int wh_AuthBase_Cleanup(void* context);
4052

53+
/**
54+
* @brief Authenticate a user using the specified method.
55+
*
56+
* @param[in] context Pointer to the auth base context.
57+
* @param[in] client_id The client ID making the request.
58+
* @param[in] method The authentication method to use.
59+
* @param[in] username The username to authenticate.
60+
* @param[in] auth_data Pointer to the authentication data.
61+
* @param[in] auth_data_len Length of the authentication data.
62+
* @param[out] out_user_id Pointer to store the authenticated user ID.
63+
* @param[out] out_permissions Pointer to store the user permissions.
64+
* @param[out] loggedIn Pointer to store the login status.
65+
* @return int Returns 0 on success, or a negative error code on failure.
66+
*/
4167
int wh_AuthBase_Login(void* context, uint8_t client_id, whAuthMethod method,
4268
const char* username, const void* auth_data,
4369
uint16_t auth_data_len, uint16_t* out_user_id,
4470
whAuthPermissions* out_permissions, int* loggedIn);
4571

72+
/**
73+
* @brief Logout a user.
74+
*
75+
* @param[in] context Pointer to the auth base context.
76+
* @param[in] current_user_id The user ID of the current user performing the logout.
77+
* @param[in] user_id The user ID to logout.
78+
* @return int Returns 0 on success, or a negative error code on failure.
79+
*/
4680
int wh_AuthBase_Logout(void* context, uint16_t current_user_id,
4781
uint16_t user_id);
4882

49-
83+
/**
84+
* @brief Check if an action is authorized for a session.
85+
*
86+
* @param[in] context Pointer to the auth base context.
87+
* @param[in] user_id The user ID to check authorization for.
88+
* @param[in] group The group to check authorization for.
89+
* @param[in] action The action to check authorization for.
90+
* @return int Returns 0 if authorized, or a negative error code on failure.
91+
*/
5092
int wh_AuthBase_CheckRequestAuthorization(void* context, uint16_t user_id,
5193
uint16_t group, uint16_t action);
5294

@@ -55,22 +97,72 @@ int wh_AuthBase_CheckRequestAuthorization(void* context, uint16_t user_id,
5597
int wh_AuthBase_CheckKeyAuthorization(void* context, uint16_t user_id,
5698
uint32_t key_id, uint16_t action);
5799

100+
/**
101+
* @brief Add a new user.
102+
*
103+
* @param[in] context Pointer to the auth base context.
104+
* @param[in] username The username for the new user.
105+
* @param[out] out_user_id Pointer to store the new user ID.
106+
* @param[in] permissions The permissions for the new user.
107+
* @param[in] method The authentication method for the new user.
108+
* @param[in] credentials Pointer to the credentials data.
109+
* @param[in] credentials_len Length of the credentials data.
110+
* @return int Returns 0 on success, or a negative error code on failure.
111+
*/
58112
int wh_AuthBase_UserAdd(void* context, const char* username,
59113
uint16_t* out_user_id, whAuthPermissions permissions,
60114
whAuthMethod method, const void* credentials,
61115
uint16_t credentials_len);
62116

117+
/**
118+
* @brief Delete a user.
119+
*
120+
* @param[in] context Pointer to the auth base context.
121+
* @param[in] current_user_id The user ID of the current user performing the deletion.
122+
* @param[in] user_id The user ID to delete.
123+
* @return int Returns 0 on success, or a negative error code on failure.
124+
*/
63125
int wh_AuthBase_UserDelete(void* context, uint16_t current_user_id,
64126
uint16_t user_id);
65127

128+
/**
129+
* @brief Set user permissions.
130+
*
131+
* @param[in] context Pointer to the auth base context.
132+
* @param[in] current_user_id The user ID of the current user performing the operation.
133+
* @param[in] user_id The user ID to set permissions for.
134+
* @param[in] permissions The new permissions to set.
135+
* @return int Returns 0 on success, or a negative error code on failure.
136+
*/
66137
int wh_AuthBase_UserSetPermissions(void* context, uint16_t current_user_id,
67138
uint16_t user_id,
68139
whAuthPermissions permissions);
69140

141+
/**
142+
* @brief Get user information by username.
143+
*
144+
* @param[in] context Pointer to the auth base context.
145+
* @param[in] username The username to look up.
146+
* @param[out] out_user_id Pointer to store the user ID.
147+
* @param[out] out_permissions Pointer to store the user permissions.
148+
* @return int Returns 0 on success, or a negative error code on failure.
149+
*/
70150
int wh_AuthBase_UserGet(void* context, const char* username,
71151
uint16_t* out_user_id,
72152
whAuthPermissions* out_permissions);
73153

154+
/**
155+
* @brief Set user credentials (PIN, etc.).
156+
*
157+
* @param[in] context Pointer to the auth base context.
158+
* @param[in] user_id The user ID to set credentials for.
159+
* @param[in] method The authentication method.
160+
* @param[in] current_credentials Pointer to the current credentials data.
161+
* @param[in] current_credentials_len Length of the current credentials data.
162+
* @param[in] new_credentials Pointer to the new credentials data.
163+
* @param[in] new_credentials_len Length of the new credentials data.
164+
* @return int Returns 0 on success, or a negative error code on failure.
165+
*/
74166
int wh_AuthBase_UserSetCredentials(void* context, uint16_t user_id,
75167
whAuthMethod method,
76168
const void* current_credentials,

0 commit comments

Comments
 (0)