1 /* 2 * Internal prototypes and structures for pam-krb5. 3 * 4 * Copyright 2005-2009, 2014, 2020 Russ Allbery <eagle@eyrie.org> 5 * Copyright 2011, 2012 6 * The Board of Trustees of the Leland Stanford Junior University 7 * Copyright 2005 Andres Salomon <dilinger@debian.org> 8 * Copyright 1999-2000 Frank Cusack <fcusack@fcusack.com> 9 * 10 * SPDX-License-Identifier: BSD-3-clause or GPL-1+ 11 */ 12 13 #ifndef INTERNAL_H 14 #define INTERNAL_H 1 15 16 #include <config.h> 17 #include <portable/krb5.h> 18 #include <portable/macros.h> 19 #include <portable/pam.h> 20 21 #include <stdarg.h> 22 #include <syslog.h> 23 24 /* Forward declarations to avoid unnecessary includes. */ 25 struct pam_args; 26 struct passwd; 27 struct vector; 28 29 /* Used for unused parameters to silence gcc warnings. */ 30 #define UNUSED __attribute__((__unused__)) 31 32 /* 33 * An authentication context, including all the data we want to preserve 34 * across calls to the public entry points. This context is stored in the PAM 35 * state and a pointer to it is stored in the pam_args struct that is passed 36 * as the first argument to most internal functions. 37 */ 38 struct context { 39 char *name; /* Username being authenticated. */ 40 krb5_context context; /* Kerberos context. */ 41 krb5_ccache cache; /* Active credential cache, if any. */ 42 krb5_principal princ; /* Principal being authenticated. */ 43 int expired; /* If set, account was expired. */ 44 int dont_destroy_cache; /* If set, don't destroy cache on shutdown. */ 45 int initialized; /* If set, ticket cache initialized. */ 46 krb5_creds *creds; /* Credentials for password changing. */ 47 krb5_ccache fast_cache; /* Temporary credential cache for FAST. */ 48 }; 49 50 /* 51 * The global structure holding our arguments, both from krb5.conf and from 52 * the PAM configuration. Filled in by pamk5_init and stored in the pam_args 53 * struct passed as a first argument to most internal functions. Sort by 54 * documentation order. 55 */ 56 struct pam_config { 57 /* Authorization. */ 58 char *alt_auth_map; /* An sprintf pattern to map principals. */ 59 bool force_alt_auth; /* Alt principal must be used if it exists. */ 60 bool ignore_k5login; /* Don't check .k5login files. */ 61 bool ignore_root; /* Skip authentication for root. */ 62 long minimum_uid; /* Ignore users below this UID. */ 63 bool only_alt_auth; /* Alt principal must be used. */ 64 bool search_k5login; /* Try password with each line of .k5login. */ 65 #ifdef __FreeBSD__ 66 bool allow_kdc_spoof;/* Allow auth even if KDC cannot be verified */ 67 #endif /* __FreeBSD__ */ 68 69 /* Kerberos behavior. */ 70 char *fast_ccache; /* Cache containing armor ticket. */ 71 bool anon_fast; /* sets up an anonymous fast armor cache */ 72 bool forwardable; /* Obtain forwardable tickets. */ 73 char *keytab; /* Keytab for credential validation. */ 74 char *realm; /* Default realm for Kerberos. */ 75 krb5_deltat renew_lifetime; /* Renewable lifetime of credentials. */ 76 krb5_deltat ticket_lifetime; /* Lifetime of credentials. */ 77 char *user_realm; /* Default realm for user principals. */ 78 79 /* PAM behavior. */ 80 bool clear_on_fail; /* Delete saved password on change failure. */ 81 bool debug; /* Log debugging information. */ 82 bool defer_pwchange; /* Defer expired account fail to account. */ 83 bool fail_pwchange; /* Treat expired password as auth failure. */ 84 bool force_pwchange; /* Change expired passwords in auth. */ 85 bool no_update_user; /* Don't update PAM_USER with local name. */ 86 bool silent; /* Suppress text and errors (PAM_SILENT). */ 87 char *trace; /* File name for trace logging. */ 88 89 /* PKINIT. */ 90 char *pkinit_anchors; /* Trusted certificates, usually per realm. */ 91 bool pkinit_prompt; /* Prompt user to insert smart card. */ 92 char *pkinit_user; /* User ID to pass to PKINIT. */ 93 struct vector *preauth_opt; /* Preauth options. */ 94 bool try_pkinit; /* Attempt PKINIT, fall back to password. */ 95 bool use_pkinit; /* Require PKINIT. */ 96 97 /* Prompting. */ 98 char *banner; /* Addition to password changing prompts. */ 99 bool expose_account; /* Display principal in password prompts. */ 100 bool force_first_pass; /* Require a previous password be stored. */ 101 bool no_prompt; /* Let Kerberos handle password prompting. */ 102 bool prompt_principal; /* Prompt for the Kerberos principal. */ 103 bool try_first_pass; /* Try the previously entered password. */ 104 bool use_authtok; /* Use the stored new password for changes. */ 105 bool use_first_pass; /* Always use the previous password. */ 106 107 /* Ticket caches. */ 108 char *ccache; /* Path to write ticket cache to. */ 109 char *ccache_dir; /* Directory for ticket cache. */ 110 bool no_ccache; /* Don't create a ticket cache. */ 111 bool retain_after_close; /* Don't destroy the cache on session end. */ 112 113 /* The authentication context, which bundles together Kerberos data. */ 114 struct context *ctx; 115 bool no_warn; /* XXX Dummy argument, remove when Heimdal is removed. */ 116 }; 117 118 /* Default to a hidden visibility for all internal functions. */ 119 #pragma GCC visibility push(hidden) 120 121 /* Parse the PAM flags, arguments, and krb5.conf and fill out pam_args. */ 122 struct pam_args *pamk5_init(pam_handle_t *, int flags, int, const char **); 123 124 /* Free the pam_args struct when we're done. */ 125 void pamk5_free(struct pam_args *); 126 127 /* 128 * The underlying functions between several of the major PAM interfaces. 129 */ 130 int pamk5_account(struct pam_args *); 131 int pamk5_authenticate(struct pam_args *); 132 133 /* 134 * The underlying function below pam_sm_chauthtok. If the second argument is 135 * true, we're doing the preliminary check and shouldn't actually change the 136 * password. 137 */ 138 int pamk5_password(struct pam_args *, bool only_auth); 139 140 /* 141 * Create or refresh the user's ticket cache. This is the underlying function 142 * beneath pam_sm_setcred and pam_sm_open_session. 143 */ 144 int pamk5_setcred(struct pam_args *, bool refresh); 145 146 /* 147 * Authenticate the user. Prompts for the password as needed and obtains 148 * tickets for in_tkt_service, krbtgt/<realm> by default. Stores the initial 149 * credentials in the final argument, allocating a new krb5_creds structure. 150 * If possible, the initial credentials are verified by checking them against 151 * the local system key. 152 */ 153 int pamk5_password_auth(struct pam_args *, const char *service, krb5_creds **); 154 155 /* 156 * Prompt the user for a new password, twice so that they can confirm. Sets 157 * PAM_AUTHTOK and puts the new password in newly allocated memory in pass if 158 * it's not NULL. 159 */ 160 int pamk5_password_prompt(struct pam_args *, char **pass); 161 162 /* 163 * Change the user's password. Prompts for the current password as needed and 164 * the new password. If the second argument is true, only obtains the 165 * necessary credentials without changing anything. 166 */ 167 int pamk5_password_change(struct pam_args *, bool only_auth); 168 169 /* 170 * Generic conversation function to display messages or get information from 171 * the user. Takes the message, the message type, and a place to put the 172 * result of a prompt. 173 */ 174 int pamk5_conv(struct pam_args *, const char *, int, char **); 175 176 /* 177 * Function specifically for getting a password. Takes a prefix (if non-NULL, 178 * args->banner will also be prepended) and a pointer into which to store the 179 * password. The password must be freed by the caller. 180 */ 181 int pamk5_get_password(struct pam_args *, const char *, char **); 182 183 /* Prompting function for the Kerberos libraries. */ 184 krb5_error_code pamk5_prompter_krb5(krb5_context, void *data, const char *name, 185 const char *banner, int, krb5_prompt *); 186 187 /* Prompting function that doesn't allow passwords. */ 188 krb5_error_code pamk5_prompter_krb5_no_password(krb5_context, void *data, 189 const char *name, 190 const char *banner, int, 191 krb5_prompt *); 192 193 /* Check the user with krb5_kuserok or the configured equivalent. */ 194 int pamk5_authorized(struct pam_args *); 195 196 /* Returns true if we should ignore this user (root or low UID). */ 197 int pamk5_should_ignore(struct pam_args *, PAM_CONST char *); 198 199 /* 200 * alt_auth_map support. 201 * 202 * pamk5_map_principal attempts to map the user to a Kerberos principal 203 * according to alt_auth_map. Returns 0 on success, storing the mapped 204 * principal name in newly allocated memory in principal. The caller is 205 * responsiple for freeing. Returns an errno value on any error. 206 * 207 * pamk5_alt_auth attempts an authentication to the given service with the 208 * given options and password and returns a Kerberos error code. On success, 209 * the new credentials are stored in krb5_creds. 210 * 211 * pamk5_alt_auth_verify verifies that Kerberos credentials are authorized to 212 * access the account given the configured alt_auth_map and is meant to be 213 * called from pamk5_authorized. It returns a PAM status code. 214 */ 215 int pamk5_map_principal(struct pam_args *, const char *username, 216 char **principal); 217 krb5_error_code pamk5_alt_auth(struct pam_args *, const char *service, 218 krb5_get_init_creds_opt *, const char *pass, 219 krb5_creds *); 220 int pamk5_alt_auth_verify(struct pam_args *); 221 222 /* FAST support. Set up FAST protection of authentication. */ 223 void pamk5_fast_setup(struct pam_args *, krb5_get_init_creds_opt *); 224 225 /* Context management. */ 226 int pamk5_context_new(struct pam_args *); 227 int pamk5_context_fetch(struct pam_args *); 228 void pamk5_context_free(struct pam_args *); 229 void pamk5_context_destroy(pam_handle_t *, void *data, int pam_end_status); 230 231 /* Get and set environment variables for the ticket cache. */ 232 const char *pamk5_get_krb5ccname(struct pam_args *, const char *key); 233 int pamk5_set_krb5ccname(struct pam_args *, const char *, const char *key); 234 235 /* 236 * Create a ticket cache file securely given a mkstemp template. Modifies 237 * template in place to store the name of the created file. 238 */ 239 int pamk5_cache_mkstemp(struct pam_args *, char *template); 240 241 /* 242 * Create a ticket cache and initialize it with the provided credentials, 243 * returning the new cache in the last argument 244 */ 245 int pamk5_cache_init(struct pam_args *, const char *ccname, krb5_creds *, 246 krb5_ccache *); 247 248 /* 249 * Create a ticket cache with a random path, initialize it with the provided 250 * credentials, store it in the context, and put the path into PAM_KRB5CCNAME. 251 */ 252 int pamk5_cache_init_random(struct pam_args *, krb5_creds *); 253 254 /* 255 * Compatibility functions. Depending on whether pam_krb5 is built with MIT 256 * Kerberos or Heimdal, appropriate implementations for the Kerberos 257 * implementation will be provided. 258 */ 259 krb5_error_code pamk5_compat_set_realm(struct pam_config *, const char *); 260 void pamk5_compat_free_realm(struct pam_config *); 261 262 /* Undo default visibility change. */ 263 #pragma GCC visibility pop 264 265 #endif /* !INTERNAL_H */ 266