challenger

OAuth 2.0-based authentication service that validates user can receive messages at a certain address
Log | Files | Refs | Submodules | README | LICENSE

challenger-httpd_common.h (4542B)

      1 /*
      2   This file is part of Challenger
      3   Copyright (C) 2023 Taler Systems SA
      4 
      5   Challenger is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU Affero General Public License as published by the Free Software
      7   Foundation; either version 3, or (at your option) any later version.
      8 
      9   Challenger is distributed in the hope that it will be useful, but WITHOUT ANY
     10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     11   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
     12 
     13   You should have received a copy of the GNU Affero General Public License along with
     14   Challenger; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     15 */
     16 /**
     17  * @file challenger-httpd_common.h
     18  * @brief common helper functions
     19  * @author Christian Grothoff
     20  */
     21 #ifndef CHALLENGER_HTTPD_COMMON_H
     22 #define CHALLENGER_HTTPD_COMMON_H
     23 
     24 #include "challenger-httpd.h"
     25 
     26 /**
     27  * Extract the client secret from the
     28  * authorization header of @a connection.
     29  *
     30  * @param connection HTTP connection to get client secret from
     31  * @return NULL if there is no well-formed secret
     32  */
     33 const char *
     34 CH_get_client_secret (struct MHD_Connection *connection);
     35 
     36 
     37 /**
     38  * Return desired output format.
     39  *
     40  * @param connection connection to check
     41  * @return 0 for HTML and 1 for JSON.
     42  */
     43 int
     44 CH_get_output_type (struct MHD_Connection *connection);
     45 
     46 
     47 /**
     48  * Compute code that would grant access to the ``/token``
     49  * endpoint to obtain an access token for a particular
     50  * challenge address. NOTE: We may not want
     51  * to include all of these when hashing...
     52  *
     53  * @param nonce nonce of the challenge process
     54  * @param client_secret secret of the client that should receive access
     55  * @param client_scope scope of the grant
     56  * @param address address that access is being granted to
     57  * @param client_redirect_uri redirect URI of the client
     58  * @return code that grants access
     59  */
     60 char *
     61 CH_compute_code (const struct CHALLENGER_ValidationNonceP *nonce,
     62                  const char *client_secret,
     63                  const char *client_scope,
     64                  const json_t *address,
     65                  const char *client_redirect_uri);
     66 
     67 
     68 /**
     69  * Extracts a @a nonce from the given @a code.
     70  *
     71  * @param code access code computed via #CH_compute_code()
     72  * @param[out] nonce set to nonce used in #CH_compute_code()
     73  * @return #GNUNET_OK on success
     74  */
     75 enum GNUNET_GenericReturnValue
     76 CH_code_to_nonce (const char *code,
     77                   struct CHALLENGER_ValidationNonceP *nonce);
     78 
     79 
     80 /**
     81  * The challenge of @a nonce was solved, build the full redirect URL
     82  * for the client.
     83  *
     84  * @param nonce the nonce of the challenge
     85  * @param connection connection being handled
     86  * @param[out] url set to the redirect URL
     87  * @return #GNUNET_OK on success,
     88  *         #GNUNET_NO if an error was returned on @a connection (#MHD_YES)
     89  *         #GNUNET_SYSERR to just close @a connection (#MHD_NO)
     90  */
     91 enum GNUNET_GenericReturnValue
     92 CH_build_full_redirect_url (const struct CHALLENGER_ValidationNonceP *nonce,
     93                             struct MHD_Connection *connection,
     94                             char **url);
     95 
     96 
     97 /**
     98  * Send a OAuth 2.0 response indicating an error following
     99  * section 5.2 of RFC 6749.
    100  *
    101  * @param connection the MHD connection to use
    102  * @param ec error code uniquely identifying the error
    103  * @param oauth_error error as of the OAuth 2.0 protocol
    104  * @param http_status HTTP status code to use
    105  * @param detail additional optional detail about the error
    106  * @return a MHD result code
    107  */
    108 enum MHD_Result
    109 CH_reply_with_oauth_error (
    110   struct MHD_Connection *connection,
    111   unsigned int http_status,
    112   const char *oauth_error,
    113   enum TALER_ErrorCode ec,
    114   const char *detail);
    115 
    116 
    117 /**
    118  * Redirect the client on @a connection to the given
    119  * @a client_redirect_uri providing the given OAuth2.0
    120  * error details.
    121  *
    122  * @param connection HTTP request to handle
    123  * @param client_redirect_uri base URI where to redirect
    124  * @param state client state to pass to server
    125  * @param oauth_error error status to return (e.g. "invalid_scope")
    126  * @param oauth_error_description longer description to return, optional, can be NULL
    127  * @param oauth_error_uri URI with additional information about the error, optional, can be NULL
    128  * @return MHD response queueing status
    129  */
    130 enum MHD_Result
    131 TALER_MHD_redirect_with_oauth_status (
    132   struct MHD_Connection *connection,
    133   const char *client_redirect_uri,
    134   const char *state,
    135   const char *oauth_error,
    136   const char *oauth_error_description,
    137   const char *oauth_error_uri);
    138 
    139 #endif