From patchwork Sun May 8 20:26:31 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Neels Hofmeyr X-Patchwork-Id: 619697 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.osmocom.org (lists.osmocom.org [IPv6:2a01:4f8:191:444b::2:7]) by ozlabs.org (Postfix) with ESMTP id 3r2xr00p0Kz9snl for ; Mon, 9 May 2016 06:26:40 +1000 (AEST) Received: from lists.osmocom.org (lists.osmocom.org [144.76.43.76]) by lists.osmocom.org (Postfix) with ESMTP id C81F513F6E; Sun, 8 May 2016 20:26:35 +0000 (UTC) X-Original-To: openbsc@lists.osmocom.org Delivered-To: openbsc@lists.osmocom.org Received: from einhorn.in-berlin.de (einhorn.in-berlin.de [IPv6:2001:bf0:c000::1:8]) by lists.osmocom.org (Postfix) with ESMTP id 5CC8D13F55 for ; Sun, 8 May 2016 20:26:34 +0000 (UTC) X-Envelope-From: nhofmeyr@sysmocom.de X-Envelope-To: Received: from localhost (cable-37-120-51-1.cust.telecolumbus.net [37.120.51.1] (may be forged)) (authenticated bits=0) by einhorn.in-berlin.de (8.14.4/8.14.4/Debian-4+deb7u1) with ESMTP id u48KQXfk003063 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT) for ; Sun, 8 May 2016 22:26:33 +0200 From: Neels Hofmeyr To: openbsc@lists.osmocom.org Subject: [PATCH] api doc: auth_core.c: add \returns, cosmetic Date: Sun, 8 May 2016 22:26:31 +0200 Message-Id: <1462739191-25885-1-git-send-email-nhofmeyr@sysmocom.de> X-Mailer: git-send-email 2.1.4 X-BeenThere: openbsc@lists.osmocom.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: "Development of OpenBSC, OsmoBSC, OsmoNITB, OsmoCSCN" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: openbsc-bounces@lists.osmocom.org Sender: "OpenBSC" 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.) --- src/gsm/auth_core.c | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) 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 @@ static struct osmo_auth_impl *selected_auths[_OSMO_AUTH_ALG_NUM]; /*! \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 @@ int osmo_auth_register(struct osmo_auth_impl *impl) /*! \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 @@ int osmo_auth_load(const char *path) /*! \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 @@ static inline void c4_function(uint8_t *ck, const uint8_t *kc) /*! \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 @@ int osmo_auth_3g_from_2g(struct osmo_auth_vector *vec) /* 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 @@ int osmo_auth_3g_from_2g(struct osmo_auth_vector *vec) * \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 @@ int osmo_auth_gen_vec(struct osmo_auth_vector *vec, * \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