This file is indexed.

/usr/include/webauth/basic.h is in libwebauth-dev 4.6.1-1+b1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
/*
 * Basic WebAuth API.
 *
 * This interface provides the basic WebAuth context used by all other WebAuth
 * library interfaces and the functions to create and destroy it, basic error
 * handling and error reporting, and the WebAuth error codes.  Any software
 * wanting to use the WebAuth library needs to call webauth_context_init()
 * before any other function and pass the returned context as the first
 * argument to other functions.
 *
 * Written by Russ Allbery <eagle@eyrie.org>
 * Copyright 2011, 2013, 2014
 *     The Board of Trustees of the Leland Stanford Junior University
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 */

#ifndef WEBAUTH_BASIC_H
#define WEBAUTH_BASIC_H 1

#include <webauth/defines.h>

/* Internal struct used to track WebAuth library state. */
struct webauth_context;

/*
 * webauth_context_init optionally takes an APR pool.  If we have the APR
 * headers included, it's nice to get strong type checking.  But one of the
 * goals of the APR usage in the WebAuth library is for it to be entirely
 * self-contained and transparent to the user.  So we switch to void * if the
 * relevant APR pool header hasn't previously been included.
 */
#ifdef APR_POOLS_H
# define WA_APR_POOL_T apr_pool_t
#else
# define WA_APR_POOL_T void
#endif

/*
 * Many WebAuth functions return an error status, or 0 on success.  For those
 * functions, the error codes are chosen from the following enum.  Additional
 * details about the error are stored in the context, but may be disposed of
 * if another WebAuth function is called before retrieving the error.
 *
 * Use webauth_error_message() to get the corresponding error message and any
 * additional information, if available.
 *
 * These error messages are in two blocks.  WA_ERR_* status codes are used
 * internally in the WebAuth code, and WA_PEC_* status codes are valid in
 * protocol elements (the code attribute of error tokens, the <errorCode>
 * element of an <errorResponse>, and the <loginErrorCode> element of a
 * <requestTokenResponse>).  Most WebAuth functions only return the internal
 * status codes, but webauth_krb5_* calls and webauth_webkdc_login may return
 * either type.
 *
 * The numeric values of the protocol status codes are fixed in the protocol
 * and must not change for interoperability reasons.  The WA_ERR_* status
 * codes are internal to the library API and may change with the API.
 */
enum webauth_status {
    WA_ERR_NONE = 0,

    /* Protocol status codes. */
    WA_PEC_SERVICE_TOKEN_EXPIRED       =  1, /* Past expiration time */
    WA_PEC_SERVICE_TOKEN_INVALID       =  2, /* Can't decrypt / bad format */
    WA_PEC_PROXY_TOKEN_EXPIRED         =  3, /* Past expiration time */
    WA_PEC_PROXY_TOKEN_INVALID         =  4, /* Can't decrypt / bad format */
    WA_PEC_INVALID_REQUEST             =  5, /* Missing/incorrect data, etc */
    WA_PEC_UNAUTHORIZED                =  6, /* Access denied */
    WA_PEC_SERVER_FAILURE              =  7, /* Server failure, try again */
    WA_PEC_REQUEST_TOKEN_STALE         =  8, /* Too old */
    WA_PEC_REQUEST_TOKEN_INVALID       =  9, /* Can't decrypt / bad format */
    WA_PEC_GET_CRED_FAILURE            = 10, /* Can't get credential */
    WA_PEC_REQUESTER_KRB5_CRED_INVALID = 11, /* <requesterCredential> was bad */
    WA_PEC_LOGIN_TOKEN_STALE           = 12, /* Too old */
    WA_PEC_LOGIN_TOKEN_INVALID         = 13, /* Can't decrypt / bad format */
    WA_PEC_LOGIN_FAILED                = 14, /* Username/password failed */
    WA_PEC_PROXY_TOKEN_REQUIRED        = 15, /* Missing required proxy-token */
    WA_PEC_LOGIN_CANCELED              = 16, /* User cancelled login */
    WA_PEC_LOGIN_FORCED                = 17, /* User must re-login */
    WA_PEC_USER_REJECTED               = 18, /* Principal not permitted */
    WA_PEC_CREDS_EXPIRED               = 19, /* User password expired */
    WA_PEC_MULTIFACTOR_REQUIRED        = 20, /* Multifactor login required */
    WA_PEC_MULTIFACTOR_UNAVAILABLE     = 21, /* MF required, not available */
    WA_PEC_LOGIN_REJECTED              = 22, /* User may not log on now */
    WA_PEC_LOA_UNAVAILABLE             = 23, /* Requested LoA not available */
    WA_PEC_AUTH_REJECTED               = 24, /* Auth to this site rejected */
    WA_PEC_AUTH_REPLAY                 = 25, /* Auth was a replay */
    WA_PEC_AUTH_LOCKOUT                = 26, /* Too many failed attempts */

    /* Internal status codes. */
    WA_ERR_INTERNAL = 1000,  /* Internal error */
    WA_ERR_APR,              /* An APR error occurred */
    WA_ERR_BAD_HMAC,         /* HMAC check failed */
    WA_ERR_BAD_KEY,          /* Unable to use key */
    WA_ERR_CORRUPT,          /* Data is incorrectly formatted */
    WA_ERR_FILE_NOT_FOUND,   /* File does not exist */
    WA_ERR_FILE_OPENREAD,    /* Unable to open file for reading */
    WA_ERR_FILE_OPENWRITE,   /* Unable to open file for writing */
    WA_ERR_FILE_READ,        /* Unable to read file file */
    WA_ERR_FILE_VERSION,     /* Bad file data version */
    WA_ERR_FILE_WRITE,       /* Unable to write to file */
    WA_ERR_INVALID,          /* Invalid argument to function */
    WA_ERR_INVALID_CONTEXT,  /* Invalid context passed to function */
    WA_ERR_KRB5,             /* A Kerberos error occured */
    WA_ERR_NOT_FOUND,        /* Item not found while searching */
    WA_ERR_NO_MEM,           /* No memory */
    WA_ERR_NO_ROOM,          /* Supplied buffer too small */
    WA_ERR_RAND_FAILURE,     /* Unable to get random data */
    WA_ERR_REMOTE_FAILURE,   /* A remote service call failed */
    WA_ERR_TOKEN_EXPIRED,    /* Token has expired */
    WA_ERR_TOKEN_REJECTED,   /* Token used in invalid context */
    WA_ERR_TOKEN_STALE,      /* Token is stale */
    WA_ERR_UNIMPLEMENTED,    /* Operation not supported */
    WA_ERR_FILE_LOCK,        /* Unable to lock file */

    /* Update webauth_error_message when adding more codes. */
};

/*
 * When setting logging callbacks, this enum identifies the log level for
 * which to set a callback.  The level is akin to syslog levels.
 */
enum webauth_log_level {
    WA_LOG_TRACE,
    WA_LOG_INFO,
    WA_LOG_NOTICE,
    WA_LOG_WARN,
};

/* Data type for a logging callback. */
typedef void (*webauth_log_func)(struct webauth_context *, void *,
                                 const char *);

BEGIN_DECLS

/*
 * Initialize a new WebAuth context.  Takes a pointer to a webauth_context
 * struct as its first argument.  The contents of that struct will be
 * overwritten without freeing, so it does not have to be initialized (but
 * should be freed if being reused).
 *
 * An APR pool may be optionally provided, in which case WebAuth will use a
 * subpool of that pool for all memory allocation.  If the provided pointer is
 * NULL, a new root pool will be created.  If you want control over what
 * function is called on memory allocation failure, provide a pool; otherwise,
 * WebAuth will use the default APR behavior, which is likely to be unfriendly
 * to your application.
 *
 * The initialized context must be freed with webauth_context_free.  Be sure
 * to do this during application shutdown or APR will not be closed properly.
 */
int webauth_context_init(struct webauth_context **, WA_APR_POOL_T *)
    __attribute__((__nonnull__(1)));

/*
 * A variant of of webauth_context_init for APR-aware applications.  The only
 * difference in this function is that it does not call apr_initialize and
 * therefore does not have to be (and should not be) paired with
 * webauth_context_free.  The pool argument is mandatory, and the WebAuth
 * library will use a sub-pool of that pool.
 */
int webauth_context_init_apr(struct webauth_context **, WA_APR_POOL_T *)
    __attribute__((__nonnull__));

/*
 * Free a WebAuth context.  After this call, the contents of the provided
 * webauth_context struct will be invalid and should not be reused without
 * calling webauth_init_context on that struct again.
 *
 * This function must not be called if webauth_context_init_apr was used.
 * Instead, just destroy the parent pool.
 */
void webauth_context_free(struct webauth_context *)
    __attribute__((__nonnull__));

/*
 * Returns the error message for the most recent WebAuth error.  This call
 * should be made before any additional WebAuth call if a WebAuth call fails,
 * or the error message may not be accurate.  The returned string is
 * pool-allocated and should not be modified or freed.
 */
const char *webauth_error_message(struct webauth_context *, int code);

/*
 * Set a logging callback for a particular log level.  The void * data is
 * passed through to the log function when it is called.  callback may be
 * NULL, in which case the callback for that log level is cleared.  Returns
 * a WebAuth error code, but the only error case is an invalid log level.
 *
 * If a callback is set and then later removed or overwritten, the data
 * pointer will be discarded but will not be freed.  The caller is responsible
 * for freeing the data in that situation.
 */
int webauth_log_callback(struct webauth_context *, enum webauth_log_level,
                          webauth_log_func callback, void *data)
    __attribute__((__nonnull__(1)));

END_DECLS

#endif /* !WEBAUTH_BASIC_H */