Change in libosmocore[master]: api doc: auth_core.c: add \returns, cosmetic

[gerrit-no-reply at lists.osmocom.org]

>From Neels Hofmeyr <nhofmeyr at sysmocom.de>:

Neels Hofmeyr has submitted this change and it was merged.

Change subject: api doc: auth_core.c: add \returns, cosmetic
......................................................................


api doc: auth_core.c: add \returns, cosmetic

Add various missing \returns doxygen entries.

In osmo_auth_3g_from_2g(), also adjust two comment-closing instances to
match common style and add a period to end a sentence.

(The recent addition of osmo_auth_3g_from_2g() raised my attention, and I added
more return value docs while at it.)

Change-Id: Iea71eb666bc061acb6b14215f398bd38d17b3ad3
Reviewed-on: https://gerrit.osmocom.org/33
Tested-by: Jenkins Builder
Reviewed-by: Holger Freyther <holger at freyther.de>
---
M src/gsm/auth_core.c
1 file changed, 9 insertions(+), 2 deletions(-)

Approvals:
  Jenkins Builder: Verified
  Holger Freyther: Looks good to me, approved



diff --git a/src/gsm/auth_core.c b/src/gsm/auth_core.c
index b78cdd5..f1ec2ed 100644
--- a/src/gsm/auth_core.c
+++ b/src/gsm/auth_core.c
@@ -43,6 +43,7 @@
 
 /*! \brief Register an authentication algorithm implementation with the core
  *  \param[in] impl Structure describing implementation and it's callbacks
+ *  \returns 0 on success, or a negative error code on failure
  *
  * This function is called by an authentication implementation plugin to
  * register itself with the authentication core.
@@ -64,6 +65,7 @@
 
 /*! \brief Load all available authentication plugins from the given path
  *  \param[in] path Path name of the directory containing the plugins
+ *  \returns number of plugins loaded in case of success, negative in case of error
  *
  * This function will load all plugins contained in the specified path.
  */
@@ -75,6 +77,7 @@
 
 /*! \brief Determine if a given authentication algorithm is supported
  *  \param[in] algo Algorithm which should be checked
+ *  \returns 1 if algo is supported, 0 if not, negative error on failure
  *
  * This function is used by an application to determine at runtime if a
  * given authentication algorithm is supported or not.
@@ -111,10 +114,12 @@
 
 /*! \brief Generate 3G CK + IK from 2G authentication vector
  *  \param vec Authentication Vector to be modified
+ *  \returns 1 if the vector was changed, 0 otherwise
  *
  * This function performs the C5 and C4 functions to derive the UMTS key
  * material from the GSM key material in the supplied vector, _if_ the input
- * vector doesn't yet have UMTS authentication capability */
+ * vector doesn't yet have UMTS authentication capability.
+ */
 int osmo_auth_3g_from_2g(struct osmo_auth_vector *vec)
 {
 	if ((vec->auth_types & OSMO_AUTH_TYPE_GSM) &&
@@ -124,7 +129,7 @@
 		/* We cannot actually set OSMO_AUTH_TYPE_UMTS as we have no
 		 * AUTN and no RES, and thus can only perform GSM
 		 * authentication with this tuple.
-		 * */
+		 */
 		return 1;
 	}
 
@@ -135,6 +140,7 @@
  *  \param[out] vec Generated authentication vector
  *  \param[in] aud Subscriber-specific key material
  *  \param[in] _rand Random challenge to be used
+ *  \returns 0 on success, negative error on failure
  *
  * This function performs the core cryptographic function of the AUC,
  * computing authentication triples/quintuples based on the permanent
@@ -167,6 +173,7 @@
  *  \param[in] rand_auts RAND value sent by the SIM/MS
  *  \param[in] auts AUTS value sent by the SIM/MS
  *  \param[in] _rand Random challenge to be used to generate vector
+ *  \returns 0 on success, negative error on failure
  *
  * This function performs a special variant of the  core cryptographic
  * function of the AUC: computing authentication triples/quintuples

-- 
To view, visit https://gerrit.osmocom.org/33
To unsubscribe, visit https://gerrit.osmocom.org/settings

Gerrit-MessageType: merged
Gerrit-Change-Id: Iea71eb666bc061acb6b14215f398bd38d17b3ad3
Gerrit-PatchSet: 2
Gerrit-Project: libosmocore
Gerrit-Branch: master
Gerrit-Owner: Neels Hofmeyr <nhofmeyr at sysmocom.de>
Gerrit-Reviewer: Holger Freyther <holger at freyther.de>
Gerrit-Reviewer: Jenkins Builder
Gerrit-Reviewer: Neels Hofmeyr <nhofmeyr at sysmocom.de>