/usr/include/webauth/tokens.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 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 | /*
* WebAuth token manipulation functions.
*
* These interfaces parse, unparse, and otherwise manipulate WebAuth tokens.
* Tokens in WebAuth have two canonical representations: an encrypted wire
* format, which is encrypted in some key (except for the key hint) and
* base64-encoded, and a decrypted struct representation that's used
* internally by WebAuth code. Each token type has a corresponding encode and
* decode function to convert between those two representations.
*
* Written by Russ Allbery <eagle@eyrie.org>
* Copyright 2011, 2012, 2013
* 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_TOKENS_H
#define WEBAUTH_TOKENS_H 1
#include <webauth/defines.h>
#include <sys/types.h>
#include <time.h>
struct webauth_context;
struct webauth_keyring;
/*
* The types of tokens specified in the protocol, used in the type field of
* the webauth_token struct. WA_TOKEN_UNKNOWN will never be returned in that
* struct but is used internally for errors. WA_TOKEN_ANY is used as the
* argument to webauth_token_decode when the caller doesn't know which type of
* token to expect.
*/
enum webauth_token_type {
WA_TOKEN_UNKNOWN,
WA_TOKEN_APP,
WA_TOKEN_CRED,
WA_TOKEN_ERROR,
WA_TOKEN_ID,
WA_TOKEN_LOGIN,
WA_TOKEN_PROXY,
WA_TOKEN_REQUEST,
WA_TOKEN_WEBKDC_FACTOR,
WA_TOKEN_WEBKDC_PROXY,
WA_TOKEN_WEBKDC_SERVICE,
WA_TOKEN_ANY = 255
};
/*
* In the following token struct definitions, the "encode" comments are used
* internally by the WebAuth code to generate encoding rules for the wire
* format of the tokens.
*/
/*
* Application token, used by a WebAuth Application Server to hold
* authentication information for its own use. (Note that applications are
* not required to use this token format; nothing else in the WebAuth protocol
* uses it. It is, however, the token format used by mod_webauth in the
* standard WebAuth distribution for the application cookie.)
*/
struct webauth_token_app {
const char *subject; /* encode: s, optional */
const char *authz_subject; /* encode: sz, optional */
time_t last_used; /* encode: lt, optional */
const void *session_key; /* encode: k, optional */
size_t session_key_len;
const char *initial_factors; /* encode: ia, optional */
const char *session_factors; /* encode: san, optional */
unsigned long loa; /* encode: loa, optional */
time_t creation; /* encode: ct, creation, optional */
time_t expiration; /* encode: et */
};
/*
* Credential token, which holds a credential for some other service (usually
* a Kerberos service ticket). It is sent back by the WebKDC to a WebAuth
* Application Server when requested using a proxy token, and the WAS also
* uses it to store the credentials in cookies.
*/
struct webauth_token_cred {
const char *subject; /* encode: s */
const char *type; /* encode: crt */
const char *service; /* encode: crs */
const void *data; /* encode: crd */
size_t data_len;
time_t creation; /* encode: ct, creation */
time_t expiration; /* encode: et */
};
/*
* Error token, returned by the WebKDC in response to a request token if some
* error occurred in processing that request.
*/
struct webauth_token_error {
unsigned long code; /* encode: ec, ascii */
const char *message; /* encode: em */
time_t creation; /* encode: ct, creation */
};
/*
* Id token, which identifies a user to a WebAuth Authentication Server. This
* token is sent from the WebKDC to the WAS following a user authentication to
* communicate the authentication information.
*/
struct webauth_token_id {
const char *subject; /* encode: s, optional */
const char *authz_subject; /* encode: sz, optional */
const char *auth; /* encode: sa */
const void *auth_data; /* encode: sad, optional */
size_t auth_data_len;
const char *initial_factors; /* encode: ia, optional */
const char *session_factors; /* encode: san, optional */
unsigned long loa; /* encode: loa, optional */
time_t creation; /* encode: ct, creation */
time_t expiration; /* encode: et */
};
/*
* Login token, sent from the WebLogin server to the WebKDC and containing the
* user's username and password or other authentication secret.
*/
struct webauth_token_login {
const char *username; /* encode: u */
const char *password; /* encode: p, optional */
const char *otp; /* encode: otp, optional */
const char *otp_type; /* encode: ott, optional */
time_t creation; /* encode: ct, creation */
};
/*
* Proxy token, returned by the WebKDC to a WebAuth Application Server if the
* WAS may need to request various tokens (particularly credential tokens).
* The embedded webkdc-proxy token is stored in an intermediate binary form
* and used as an opaque blob for creating later requests to the WebKDC.
*/
struct webauth_token_proxy {
const char *subject; /* encode: s */
const char *authz_subject; /* encode: sz, optional */
const char *type; /* encode: pt */
const void *webkdc_proxy; /* encode: wt */
size_t webkdc_proxy_len;
const char *initial_factors; /* encode: ia, optional */
const char *session_factors; /* encode: san, optional */
unsigned long loa; /* encode: loa, optional */
time_t creation; /* encode: ct, creation */
time_t expiration; /* encode: et */
};
/*
* Request token, sent by the WebAuth Application Server to the WebKDC.
*
* This token has two forms. The first is sent by the WAS to the WebKDC via a
* redirect to request either an id or a proxy token for the user, depending
* on whether the WAS will need credentials. The second is sent to the WebKDC
* as part of a request for a service token and contains only the command and
* creation time.
*/
struct webauth_token_request {
const char *type; /* encode: rtt, optional */
const char *auth; /* encode: sa, optional */
const char *proxy_type; /* encode: pt, optional */
const void *state; /* encode: as, optional */
size_t state_len;
const char *return_url; /* encode: ru, optional */
const char *options; /* encode: ro, optional */
const char *initial_factors; /* encode: ia, optional */
const char *session_factors; /* encode: san, optional */
unsigned long loa; /* encode: loa, optional */
const char *command; /* encode: cmd, optional */
time_t creation; /* encode: ct, creation */
};
/*
* WebKDC facter token, which adds additional factors that will be combined
* with valid login or webkdc-proxy tokens but which cannot, by themselves,
* authenticate the user. This token is stored as a separate cookie in the
* user's browser, possibly with a longer lifespan than the single sign-on
* credentials, and may also be returned by the user information service for
* certain types of authentications.
*/
struct webauth_token_webkdc_factor {
const char *subject; /* encode: s */
const char *factors; /* encode: ia */
time_t creation; /* encode: ct, creation */
time_t expiration; /* encode: et */
};
/*
* WebKDC proxy token, which stores user credentials or authentication
* information for later use by the WebKDC. This is the token that's stored
* as a single sign-on cookie in the user's browser, allowing the user to
* authenticate to subsequent web sites without reauthenticating. This token
* is also returned inside a proxy token to a WAS, which can then present it
* back to the WebKDC to obtain id or cred tokens.
*
* The session_factors data element is special. It's not included in the wire
* representation of this token, and therefore will always be NULL when
* initialized from the wire. It's used internally to store session
* information obtained from other sources and used for generating other
* tokens (particularly id and proxy tokens), and is then discarded when the
* token is encoded.
*/
struct webauth_token_webkdc_proxy {
const char *subject; /* encode: s */
const char *proxy_type; /* encode: pt */
const char *proxy_subject; /* encode: ps */
const void *data; /* encode: pd, optional */
size_t data_len;
const char *initial_factors; /* encode: ia, optional */
unsigned long loa; /* encode: loa, optional */
time_t creation; /* encode: ct, creation */
time_t expiration; /* encode: et */
/* Not included in the wire representation. */
const char *session_factors;
};
/*
* WebKDC service token, sent by the WebKDC to a WAS and returned by the WAS
* to the WebKDC as part of the request token. The purpose of this token is
* to store the session key used for encrypting the request token and its
* responses. It's encrypted in the WebKDC's long-term key, and is therefore
* used by the WebKDC to recover the session key without having local state.
*/
struct webauth_token_webkdc_service {
const char *subject; /* encode: s */
const void *session_key; /* encode: k */
size_t session_key_len;
time_t creation; /* encode: ct, creation */
time_t expiration; /* encode: et */
};
/*
* A generic token. This wrapper is used by the public interface for token
* encoding and decoding so that we don't need a separate interface for every
* token type.
*/
struct webauth_token {
enum webauth_token_type type;
union {
struct webauth_token_app app;
struct webauth_token_cred cred;
struct webauth_token_error error;
struct webauth_token_id id;
struct webauth_token_login login;
struct webauth_token_proxy proxy;
struct webauth_token_request request;
struct webauth_token_webkdc_factor webkdc_factor;
struct webauth_token_webkdc_proxy webkdc_proxy;
struct webauth_token_webkdc_service webkdc_service;
} token;
};
BEGIN_DECLS
/*
* Map a token code to the string name used for the toke type attribute, or
* vice versa. webauth_token_type_code returns WA_TOKEN_UNKNOWN when given an
* unknown token type string. webauth_token_type_string returns NULL when
* given WA_TOKEN_UNKNOWN, WA_TOKEN_ANY, or an invalid enumeration value.
*/
enum webauth_token_type webauth_token_type_code(const char *type)
__attribute__((__nonnull__, __pure__));
const char *webauth_token_type_string(enum webauth_token_type type)
__attribute__((__pure__));
/*
* Decode a token. Takes the expected token type, a string, and a keyring and
* decodes the token into the corresponding data argument, which will be a
* newly pool-allocated pointer to a generic token struct. The expected token
* type may be WA_TOKEN_ANY to accept any token type. On error, the data
* argument is set to NULL and an error code is returned.
*
* The raw variant takes a token that is not base64-encoded, such as the
* webkdc-proxy token embedded inside a proxy token.
*/
int webauth_token_decode(struct webauth_context *, enum webauth_token_type,
const char *, const struct webauth_keyring *,
struct webauth_token **)
__attribute__((__nonnull__));
int webauth_token_decode_raw(struct webauth_context *, enum webauth_token_type,
const void *, size_t,
const struct webauth_keyring *,
struct webauth_token **)
__attribute__((__nonnull__));
/*
* Encode a token. Takes a token struct and a keyring to use for encryption,
* and stores in the token argument the newly created token (in pool-allocated
* memory). On error, the token argument is set to NULL and an error code is
* returned.
*
* The raw variant generates a token that is not base64-encoded, such as the
* webkdc-proxy token embedded inside a proxy token, and stores the length of
* the generated token in length.
*/
int webauth_token_encode(struct webauth_context *,
const struct webauth_token *,
const struct webauth_keyring *, const char **token)
__attribute__((__nonnull__));
int webauth_token_encode_raw(struct webauth_context *,
const struct webauth_token *,
const struct webauth_keyring *,
const void **token, size_t *length)
__attribute__((__nonnull__));
/*
* Decrypts a token. The best decryption key on the ring will be tried first,
* and if that fails all the remaining keys will be tried. Returns the
* decrypted data in output and its length in output_len.
*
* Returns WA_ERR_NONE, WA_ERR_NO_MEM, WA_ERR_CORRUPT, WA_ERR_BAD_HMAC, or
* WA_ERR_BAD_KEY.
*/
int webauth_token_decrypt(struct webauth_context *, const void *input,
size_t input_len, void **output, size_t *output_len,
const struct webauth_keyring *)
__attribute__((__nonnull__));
/*
* Encrypts an input buffer (normally encoded attributes) into a token, using
* the key from the keyring that has the most recent valid valid_from time.
* The encoded token will be stored in newly pool-allocated memory in the
* provided output argument, with its length stored in output_len.
*
* Returns a WebAuth status code, which may be WA_ERR_BAD_KEY if no suitable
* and valid encryption key could be found in the keyring.
*/
int webauth_token_encrypt(struct webauth_context *, const void *input,
size_t len, void **output, size_t *output_len,
const struct webauth_keyring *)
__attribute__((__nonnull__));
END_DECLS
#endif /* !WEBAUTH_TOKENS_H */
|