diplodocus.org Git - nmh/blob - h/oauth.h

   1 /*
   2  * Implementation of OAuth 2.0 [1] for XOAUTH2 in SMTP [2] and POP3 [3].
   3  *
   4  * Google defined XOAUTH2 for SMTP, and that's what we use here.  If other
   5  * providers implement XOAUTH2 or some similar OAuth-based SMTP authentication
   6  * protocol, it should be simple to extend this.
   7  *
   8  * [1] https://tools.ietf.org/html/rfc6749
   9  * [2] https://developers.google.com/gmail/xoauth2_protocol
  10  * [3] http://googleappsdeveloper.blogspot.com/2014/10/updates-on-authentication-for-gmail.html
  11  *
  12  * Presumably [2] should document POP3 and that is an over-sight.  As it stands,
  13  * that blog post is the closest we have to documentation.
  14  *
  15  * According to [1] 2.1 Client Types, this is a "native application", a
  16  * "public" client.
  17  *
  18  * To summarize the flow:
  19  *
  20  * 1. User runs mhlogin which prints a URL the user must visit, and prompts for
  21  *    a code retrieved from that page.
  22  *
  23  * 2. User vists this URL in browser, signs in with some Google account, and
  24  *    copies and pastes the resulting code back to mhlogin.
  25  *
  26  * 3. mhlogin does HTTP POST to Google to exchange the user-provided code for a
  27  *    short-lived access token and a long-lived refresh token.
  28  *
  29  * 4. send uses the access token in SMTP auth if not expired.  If it is expired,
  30  *    it does HTTP POST to Google including the refresh token and gets back a
  31  *    new access token (and possibly refresh token).  If the refresh token has
  32  *    become invalid (e.g. if the user took some reset action on the Google
  33  *    account), the user must use mhlogin again, then re-run send.
  34  */
  35
  36 typedef enum {
  37     /* error loading profile */
  38     MH_OAUTH_BAD_PROFILE = OK + 1,
  39
  40     /* error initializing libcurl */
  41     MH_OAUTH_CURL_INIT,
  42
  43     /* local error initializing HTTP request */
  44     MH_OAUTH_REQUEST_INIT,
  45
  46     /* error executing HTTP POST request */
  47     MH_OAUTH_POST,
  48
  49     /* HTTP response body is too big. */
  50     MH_OAUTH_RESPONSE_TOO_BIG,
  51
  52     /* Can't process HTTP response body. */
  53     MH_OAUTH_RESPONSE_BAD,
  54
  55     /* The authorization server rejected the grant (authorization code or
  56      * refresh token); possibly the user entered a bad code, or the refresh
  57      * token has become invalid, etc. */
  58     MH_OAUTH_BAD_GRANT,
  59
  60     /* HTTP server indicates something is wrong with our request. */
  61     MH_OAUTH_REQUEST_BAD,
  62
  63     /* Attempting to refresh an access token without a refresh token. */
  64     MH_OAUTH_NO_REFRESH,
  65
  66
  67     /* requested user not in cred file */
  68     MH_OAUTH_CRED_USER_NOT_FOUND,
  69
  70     /* error loading serialized credentials */
  71     MH_OAUTH_CRED_FILE
  72 } mh_oauth_err_code;
  73
  74 typedef struct mh_oauth_ctx mh_oauth_ctx;
  75
  76 typedef struct mh_oauth_cred mh_oauth_cred;
  77
  78 typedef struct mh_oauth_service_info mh_oauth_service_info;
  79
  80 struct mh_oauth_service_info {
  81     /* Name of service, so we can search static internal services array
  82      * and for determining default credential file name. */
  83     char *name;
  84
  85     /* Human-readable name of the service; in mh_oauth_ctx::svc this is not
  86      * another buffer to free, but a pointer to either static SERVICE data
  87      * (below) or to the name field. */
  88     char *display_name;
  89
  90     /* [1] 2.2 Client Identifier, 2.3.1 Client Password */
  91     char *client_id;
  92     /* [1] 2.3.1 Client Password */
  93     char *client_secret;
  94     /* [1] 3.1 Authorization Endpoint */
  95     char *auth_endpoint;
  96     /* [1] 3.1.2 Redirection Endpoint */
  97     char *redirect_uri;
  98     /* [1] 3.2 Token Endpoint */
  99     char *token_endpoint;
 100     /* [1] 3.3 Access Token Scope */
 101     char *scope;
 102 };
 103
 104 /*
 105  * Do the complete dance for XOAUTH2 as used by POP3 and SMTP.
 106  *
 107  * Load tokens for svc from disk, refresh if necessary, and return the
 108  * base64-encoded client response.
 109  *
 110  * If refreshing, writes freshened tokens to disk.
 111  *
 112  * Exits via adios on any error.
 113  */
 114 char *
 115 mh_oauth_do_xoauth(const char *user, const char *svc, FILE *log);
 116
 117 /*
 118  * Allocate and initialize a new OAuth context.
 119  *
 120  * Caller must call mh_oauth_free(ctx) when finished, even on error.
 121  *
 122  * svc_name must point to a null-terminated string identifying the service
 123  * provider.  Support for "gmail" is built-in; anything else must be defined in
 124  * the user's profile.  The profile can also override "gmail" settings.
 125  *
 126  * Accesses global m_defs via context_find.
 127  *
 128  * On error, return FALSE and set an error in ctx; ctx is always allocated.
 129  */
 130 boolean
 131 mh_oauth_new(mh_oauth_ctx **ctx, const char *svc_name);
 132
 133 /*
 134  * Free all resources associated with ctx.
 135  */
 136 void
 137 mh_oauth_free(mh_oauth_ctx *ctx);
 138
 139 /*
 140  * Return null-terminated human-readable name of the service, e.g. "Gmail".
 141  *
 142  * Never returns NULL.
 143  */
 144 const char *
 145 mh_oauth_svc_display_name(const mh_oauth_ctx *ctx);
 146
 147 /*
 148  * Enable logging for subsequent operations on ctx.
 149  *
 150  * log must not be closed until after mh_oauth_free.
 151  *
 152  * For all HTTP requests, the request is logged with each line prefixed with
 153  * "< ", and the response with "> ".  Other messages are prefixed with "* ".
 154  */
 155 void
 156 mh_oauth_log_to(FILE *log, mh_oauth_ctx *ctx);
 157
 158 /*
 159  * Return the error code after some function indicated an error.
 160  *
 161  * Must not be called if an error was not indicated.
 162  */
 163 mh_oauth_err_code
 164 mh_oauth_get_err_code(const mh_oauth_ctx *ctx);
 165
 166 /*
 167  * Return null-terminated error message after some function indicated an error.
 168  *
 169  * Never returns NULL, but must not be called if an error was not indicated.
 170  */
 171 const char *
 172 mh_oauth_get_err_string(mh_oauth_ctx *ctx);
 173
 174 /*
 175  * Return the null-terminated URL the user needs to visit to authorize access.
 176  *
 177  * URL may be invalidated by subsequent calls to mh_oauth_get_authorize_url,
 178  * mh_oauth_authorize, or mh_oauth_refresh.
 179  *
 180  * On error, return NULL.
 181  */
 182 const char *
 183 mh_oauth_get_authorize_url(mh_oauth_ctx *ctx);
 184
 185 /*
 186  * Exchange code provided by the user for access (and maybe refresh) token.
 187  *
 188  * On error, return NULL.
 189  */
 190 mh_oauth_cred *
 191 mh_oauth_authorize(const char *code, mh_oauth_ctx *ctx);
 192
 193 /*
 194  * Refresh access (and maybe refresh) token if refresh token present.
 195  *
 196  * On error, return FALSE and leave cred untouched.
 197  */
 198 boolean
 199 mh_oauth_refresh(mh_oauth_cred *cred);
 200
 201 /*
 202  * Return whether access token is present and not expired at time T.
 203  */
 204 boolean
 205 mh_oauth_access_token_valid(time_t t, const mh_oauth_cred *cred);
 206
 207 /*
 208  * Free all resources associated with cred.
 209  */
 210 void
 211 mh_oauth_cred_free(mh_oauth_cred *cred);
 212
 213 /*
 214  * Return the null-terminated file name for storing this service's OAuth tokens.
 215  *
 216  * Accesses global m_defs via context_find.
 217  *
 218  * Never returns NULL.
 219  */
 220 const char *
 221 mh_oauth_cred_fn(const char *svc_name);
 222
 223 /*
 224  * Serialize OAuth tokens to file.
 225  *
 226  * On error, return FALSE.
 227  */
 228 boolean
 229 mh_oauth_cred_save(FILE *fp, mh_oauth_cred *cred, const char *user);
 230
 231 /*
 232  * Load OAuth tokens from file.
 233  *
 234  * Calls m_getfld(), which writes to stderr with advise().
 235  *
 236  * On error, return NULL.
 237  */
 238 mh_oauth_cred *
 239 mh_oauth_cred_load(FILE *fp, mh_oauth_ctx *ctx, const char *user);
 240
 241 /*
 242  * Return null-terminated SASL client response for XOAUTH2 from access token.
 243  *
 244  * Store the length in res_len.
 245  *
 246  * Must not be called except after successful mh_oauth_access_token_valid or
 247  * mh_oauth_refresh call; i.e. must have a valid access token.
 248  */
 249 const char *
 250 mh_oauth_sasl_client_response(size_t *res_len,
 251                               const char *user, const mh_oauth_cred *cred);
 252
 253 /*
 254  * Retrieve the various entries for the OAuth mechanism
 255  */
 256
 257 boolean
 258 mh_oauth_get_service_info(const char *svc_name, mh_oauth_service_info *svcinfo,
 259                           char *errbuf, size_t errbuflen);
 260
 261 char *mh_oauth_get_svc_name(mh_oauth_ctx *ctx);
 262 void mh_oauth_set_cred_fn(mh_oauth_ctx *ctx, char *filename);