1 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
2 /* General definitions for Kerberos version 5. */
4 * Copyright 1989, 1990, 1995, 2001, 2003, 2007, 2011 by the Massachusetts
5 * Institute of Technology. All Rights Reserved.
7 * Export of this software from the United States of America may
8 * require a specific license from the United States Government.
9 * It is the responsibility of any person or organization contemplating
10 * export to obtain such a license before exporting.
12 * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
13 * distribute this software and its documentation for any purpose and
14 * without fee is hereby granted, provided that the above copyright
15 * notice appear in all copies and that both that copyright notice and
16 * this permission notice appear in supporting documentation, and that
17 * the name of M.I.T. not be used in advertising or publicity pertaining
18 * to distribution of the software without specific, written prior
19 * permission. Furthermore if you modify this software you must label
20 * your software as modified software and not distribute it in such a
21 * fashion that it might be confused with the original M.I.T. software.
22 * M.I.T. makes no representations about the suitability of
23 * this software for any purpose. It is provided "as is" without express
24 * or implied warranty.
27 * Copyright (C) 1998 by the FundsXpress, INC.
29 * All rights reserved.
31 * Export of this software from the United States of America may require
32 * a specific license from the United States Government. It is the
33 * responsibility of any person or organization contemplating export to
34 * obtain such a license before exporting.
36 * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
37 * distribute this software and its documentation for any purpose and
38 * without fee is hereby granted, provided that the above copyright
39 * notice appear in all copies and that both that copyright notice and
40 * this permission notice appear in supporting documentation, and that
41 * the name of FundsXpress. not be used in advertising or publicity pertaining
42 * to distribution of the software without specific, written prior
43 * permission. FundsXpress makes no representations about the suitability of
44 * this software for any purpose. It is provided "as is" without express
45 * or implied warranty.
47 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
48 * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
49 * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
52 #ifndef KRB5_GENERAL__
53 #define KRB5_GENERAL__
55 /* By default, do not expose deprecated interfaces. */
56 #ifndef KRB5_DEPRECATED
57 #define KRB5_DEPRECATED 0
60 #if defined(__MACH__) && defined(__APPLE__)
61 # include <TargetConditionals.h>
62 # if TARGET_RT_MAC_CFM
63 # error "Use KfM 4.0 SDK headers for CFM compilation."
67 #if defined(_MSDOS) || defined(_WIN32)
74 #define KRB5_CALLCONV_C
75 #endif /* !KRB5_CALLCONV */
76 #endif /* !KRB5_CONFIG__ */
78 #ifndef KRB5_CALLCONV_WRONG
79 #define KRB5_CALLCONV_WRONG
82 #ifndef THREEPARAMOPEN
83 #define THREEPARAMOPEN(x,y,z) open(x,y,z)
86 #define KRB5_OLD_CRYPTO
89 #include <limits.h> /* for *_MAX */
92 #ifndef KRB5INT_BEGIN_DECLS
93 #if defined(__cplusplus)
94 #define KRB5INT_BEGIN_DECLS extern "C" {
95 #define KRB5INT_END_DECLS }
97 #define KRB5INT_BEGIN_DECLS
98 #define KRB5INT_END_DECLS
105 # pragma pack(push,2)
108 #if (__GNUC__ * 10000 + __GNUC_MINOR__ * 100 + __GNUC_PATCHLEVEL__) >= 30203
109 # define KRB5_ATTR_DEPRECATED __attribute__((deprecated))
111 # define KRB5_ATTR_DEPRECATED __declspec(deprecated)
113 # define KRB5_ATTR_DEPRECATED
118 /* typedef struct _profile_t *profile_t; */
125 * Word-size related definition.
128 typedef unsigned char krb5_octet;
130 #if INT_MAX == 0x7fff
131 typedef int krb5_int16;
132 typedef unsigned int krb5_ui_2;
133 #elif SHRT_MAX == 0x7fff
134 typedef short krb5_int16;
135 typedef unsigned short krb5_ui_2;
137 #error undefined 16 bit type
140 #if INT_MAX == 0x7fffffffL
141 typedef int krb5_int32;
142 typedef unsigned int krb5_ui_4;
143 #elif LONG_MAX == 0x7fffffffL
144 typedef long krb5_int32;
145 typedef unsigned long krb5_ui_4;
146 #elif SHRT_MAX == 0x7fffffffL
147 typedef short krb5_int32;
148 typedef unsigned short krb5_ui_4;
150 #error: undefined 32 bit type
153 #define VALID_INT_BITS INT_MAX
154 #define VALID_UINT_BITS UINT_MAX
156 #define KRB5_INT32_MAX 2147483647
157 /* this strange form is necessary since - is a unary operator, not a sign
159 #define KRB5_INT32_MIN (-KRB5_INT32_MAX-1)
161 #define KRB5_INT16_MAX 65535
162 /* this strange form is necessary since - is a unary operator, not a sign
164 #define KRB5_INT16_MIN (-KRB5_INT16_MAX-1)
171 * begin "base-defs.h"
175 * Basic definitions for Kerberos V5 library
185 typedef unsigned int krb5_boolean;
186 typedef unsigned int krb5_msgtype;
187 typedef unsigned int krb5_kvno;
189 typedef krb5_int32 krb5_addrtype;
190 typedef krb5_int32 krb5_enctype;
191 typedef krb5_int32 krb5_cksumtype;
192 typedef krb5_int32 krb5_authdatatype;
193 typedef krb5_int32 krb5_keyusage;
194 typedef krb5_int32 krb5_cryptotype;
196 typedef krb5_int32 krb5_preauthtype; /* This may change, later on */
197 typedef krb5_int32 krb5_flags;
198 typedef krb5_int32 krb5_timestamp;
199 typedef krb5_int32 krb5_error_code;
200 typedef krb5_int32 krb5_deltat;
202 typedef krb5_error_code krb5_magic;
204 typedef struct _krb5_data {
210 typedef struct _krb5_octet_data {
217 * Hack length for crypto library to use the afs_string_to_key It is
218 * equivalent to -1 without possible sign extension
219 * We also overload for an unset salt type length - which is also -1, but
222 #define SALT_TYPE_AFS_LENGTH UINT_MAX
223 #define SALT_TYPE_NO_LENGTH UINT_MAX
225 typedef void * krb5_pointer;
226 typedef void const * krb5_const_pointer;
228 typedef struct krb5_principal_data {
231 krb5_data *data; /**< An array of strings */
234 } krb5_principal_data;
236 typedef krb5_principal_data * krb5_principal;
239 * Per V5 spec on definition of principal types
242 /* Name type not known */
243 #define KRB5_NT_UNKNOWN 0
244 /* Just the name of the principal as in DCE, or for users */
245 #define KRB5_NT_PRINCIPAL 1
246 /* Service and other unique instance (krbtgt) */
247 #define KRB5_NT_SRV_INST 2
248 /* Service with host name as instance (telnet, rcommands) */
249 #define KRB5_NT_SRV_HST 3
250 /* Service with host as remaining components */
251 #define KRB5_NT_SRV_XHST 4
253 #define KRB5_NT_UID 5
255 #define KRB5_NT_X500_PRINCIPAL 6
256 /* Name in form of SMTP email name */
257 #define KRB5_NT_SMTP_NAME 7
258 /* Windows 2000 UPN */
259 #define KRB5_NT_ENTERPRISE_PRINCIPAL 10
260 #define KRB5_NT_WELLKNOWN 11
261 /* First component of NT_WELLKNOWN principals */
262 #define KRB5_WELLKNOWN_NAMESTR "WELLKNOWN"
263 /* Windows 2000 UPN and SID */
264 #define KRB5_NT_MS_PRINCIPAL -128
265 /* NT 4 style name */
266 #define KRB5_NT_MS_PRINCIPAL_AND_ID -129
267 /* NT 4 style name and SID */
268 #define KRB5_NT_ENT_PRINCIPAL_AND_ID -130
270 /* constant version thereof: */
271 typedef const krb5_principal_data *krb5_const_principal;
273 #define krb5_princ_realm(context, princ) (&(princ)->realm)
274 #define krb5_princ_set_realm(context, princ,value) ((princ)->realm = *(value))
275 #define krb5_princ_set_realm_length(context, princ,value) (princ)->realm.length = (value)
276 #define krb5_princ_set_realm_data(context, princ,value) (princ)->realm.data = (value)
277 #define krb5_princ_size(context, princ) (princ)->length
278 #define krb5_princ_type(context, princ) (princ)->type
279 #define krb5_princ_name(context, princ) (princ)->data
280 #define krb5_princ_component(context, princ,i) \
281 (((i) < krb5_princ_size(context, princ)) \
282 ? (princ)->data + (i) \
285 /** Constant for realm referrals. */
286 #define KRB5_REFERRAL_REALM ""
289 * Referral-specific functions.
292 /** Check for a match with KRB5_REFERRAL_REALM.
294 * @param [in] r Realm to check
296 * @retval TRUE if @a r is zero-length; Otherwise - FALSE
298 krb5_boolean KRB5_CALLCONV
299 krb5_is_referral_realm(const krb5_data *r);
301 /** Return an anonymous realm data.
303 * This function returns constant storage that must not be freed.
305 * @sa @c KRB5_ANONYMOUS_REALMSTR
307 const krb5_data *KRB5_CALLCONV
308 krb5_anonymous_realm(void);
310 /** Build an anonymous principal.
312 * This function returns constant storage that must not be freed.
314 * @sa KRB5_ANONYMOUS_PRINCSTR
316 krb5_const_principal KRB5_CALLCONV
317 krb5_anonymous_principal(void);
319 #define KRB5_ANONYMOUS_REALMSTR "WELLKNOWN:ANONYMOUS"
320 #define KRB5_ANONYMOUS_PRINCSTR "ANONYMOUS" /* wellknown name type */
329 /** structure for address */
330 typedef struct _krb5_address {
332 krb5_addrtype addrtype;
334 krb5_octet *contents;
337 /* per Kerberos v5 protocol spec */
338 #define ADDRTYPE_INET 0x0002
339 #define ADDRTYPE_CHAOS 0x0005
340 #define ADDRTYPE_XNS 0x0006
341 #define ADDRTYPE_ISO 0x0007
342 #define ADDRTYPE_DDP 0x0010
343 #define ADDRTYPE_NETBIOS 0x0014
344 #define ADDRTYPE_INET6 0x0018
345 /* not yet in the spec... */
346 #define ADDRTYPE_ADDRPORT 0x0100
347 #define ADDRTYPE_IPPORT 0x0101
349 /* macros to determine if a type is a local type */
350 #define ADDRTYPE_IS_LOCAL(addrtype) (addrtype & 0x8000)
357 struct _krb5_context;
358 typedef struct _krb5_context * krb5_context;
360 struct _krb5_auth_context;
361 typedef struct _krb5_auth_context * krb5_auth_context;
363 struct _krb5_cryptosystem_entry;
366 * begin "encryption.h"
369 /** Exposed contents of a key. */
370 typedef struct _krb5_keyblock {
372 krb5_enctype enctype;
374 krb5_octet *contents;
377 /** Opaque identifier for a key.
379 * Use with the krb5_k APIs for better
380 * performance for repeated operations with the same key usage. Key
381 * identifiers must not be used simultaneously within multiple
382 * threads, as they may contain mutable internal state and are not
386 typedef struct krb5_key_st *krb5_key;
388 #ifdef KRB5_OLD_CRYPTO
389 typedef struct _krb5_encrypt_block {
391 krb5_enctype crypto_entry; /* to call krb5_encrypt_size, you need
392 this. it was a pointer, but it
393 doesn't have to be. gross. */
395 } krb5_encrypt_block;
398 typedef struct _krb5_checksum {
400 krb5_cksumtype checksum_type; /* checksum type */
402 krb5_octet *contents;
405 typedef struct _krb5_enc_data {
407 krb5_enctype enctype;
409 krb5_data ciphertext;
412 typedef struct _krb5_crypto_iov {
413 krb5_cryptotype flags;
417 /* per Kerberos v5 protocol spec */
418 #define ENCTYPE_NULL 0x0000
419 #define ENCTYPE_DES_CBC_CRC 0x0001 /**< DES cbc mode with CRC-32 */
420 #define ENCTYPE_DES_CBC_MD4 0x0002 /**< DES cbc mode with RSA-MD4 */
421 #define ENCTYPE_DES_CBC_MD5 0x0003 /**< DES cbc mode with RSA-MD5 */
422 #define ENCTYPE_DES_CBC_RAW 0x0004 /**< @deprecated DES cbc mode raw */
423 #define ENCTYPE_DES3_CBC_SHA 0x0005 /**< @deprecated DES-3 cbc mode with NIST-SHA */
424 #define ENCTYPE_DES3_CBC_RAW 0x0006 /**< @deprecated DES-3 cbc mode raw */
425 #define ENCTYPE_DES_HMAC_SHA1 0x0008 /**< @deprecated */
427 #define ENCTYPE_DSA_SHA1_CMS 0x0009 /**< DSA with SHA1, CMS signature */
428 #define ENCTYPE_MD5_RSA_CMS 0x000a /**< MD5 with RSA, CMS signature */
429 #define ENCTYPE_SHA1_RSA_CMS 0x000b /**< SHA1 with RSA, CMS signature */
430 #define ENCTYPE_RC2_CBC_ENV 0x000c /**< RC2 cbc mode, CMS enveloped data */
431 #define ENCTYPE_RSA_ENV 0x000d /**< RSA encryption, CMS enveloped data */
432 #define ENCTYPE_RSA_ES_OAEP_ENV 0x000e /**< RSA w/OEAP encryption, CMS enveloped data */
433 #define ENCTYPE_DES3_CBC_ENV 0x000f /**< DES-3 cbc mode, CMS enveloped data */
435 #define ENCTYPE_DES3_CBC_SHA1 0x0010
436 #define ENCTYPE_AES128_CTS_HMAC_SHA1_96 0x0011
437 #define ENCTYPE_AES256_CTS_HMAC_SHA1_96 0x0012
438 #define ENCTYPE_ARCFOUR_HMAC 0x0017
439 #define ENCTYPE_ARCFOUR_HMAC_EXP 0x0018
440 #define ENCTYPE_UNKNOWN 0x01ff
442 #define CKSUMTYPE_CRC32 0x0001
443 #define CKSUMTYPE_RSA_MD4 0x0002
444 #define CKSUMTYPE_RSA_MD4_DES 0x0003
445 #define CKSUMTYPE_DESCBC 0x0004
448 #define CKSUMTYPE_RSA_MD5 0x0007
449 #define CKSUMTYPE_RSA_MD5_DES 0x0008
450 #define CKSUMTYPE_NIST_SHA 0x0009
451 #define CKSUMTYPE_HMAC_SHA1_DES3 0x000c
452 #define CKSUMTYPE_HMAC_SHA1_96_AES128 0x000f
453 #define CKSUMTYPE_HMAC_SHA1_96_AES256 0x0010
454 #define CKSUMTYPE_MD5_HMAC_ARCFOUR -137 /*Microsoft netlogon cksumtype*/
455 #define CKSUMTYPE_HMAC_MD5_ARCFOUR -138 /*Microsoft md5 hmac cksumtype*/
457 /* The following are entropy source designations. Whenever
458 * krb5_C_random_add_entropy is called, one of these source ids is passed
459 * in. This allows the library to better estimate bits of
460 * entropy in the sample and to keep track of what sources of entropy have
461 * contributed enough entropy. Sources marked internal MUST NOT be
462 * used by applications outside the Kerberos library
466 KRB5_C_RANDSOURCE_OLDAPI = 0, /*calls to krb5_C_RANDOM_SEED (INTERNAL)*/
467 KRB5_C_RANDSOURCE_OSRAND = 1, /* /dev/random or equivalent (internal)*/
468 KRB5_C_RANDSOURCE_TRUSTEDPARTY = 2, /* From KDC or other trusted party*/
469 /*This source should be used carefully; data in this category
470 * should be from a third party trusted to give random bits
471 * For example keys issued by the KDC in the application server.
473 KRB5_C_RANDSOURCE_TIMING = 3, /* Timing of operations*/
474 KRB5_C_RANDSOURCE_EXTERNAL_PROTOCOL = 4, /*Protocol data possibly from attacker*/
475 KRB5_C_RANDSOURCE_MAX = 5 /*Do not use; maximum source ID*/
479 /* round x up to nearest multiple of y */
480 #define krb5_roundup(x, y) ((((x) + (y) - 1)/(y))*(y))
483 /* macro function definitions to help clean up code */
486 #define krb5_x(ptr,args) ((ptr)?((*(ptr)) args):(abort(),1))
487 #define krb5_xc(ptr,args) ((ptr)?((*(ptr)) args):(abort(),(char*)0))
489 #define krb5_x(ptr,args) ((*(ptr)) args)
490 #define krb5_xc(ptr,args) ((*(ptr)) args)
494 * @brief Encrypt data using a key.
496 * @param context Context structure [input, output]
497 * @param key Key value from key table, ticket, etc. [input]
498 * @param usage Key usage [input]
499 * @param cipher_state Cipher state [input]
500 * @param input Data to be encrypted [input]
501 * @param output Encrypted data [output]
506 * KRB5_BAD_ENCTYPE Bad encryption type
508 * Kerberos error codes
513 krb5_error_code KRB5_CALLCONV
514 krb5_c_encrypt(krb5_context context, const krb5_keyblock *key,
515 krb5_keyusage usage, const krb5_data *cipher_state,
516 const krb5_data *input, krb5_enc_data *output);
519 * @brief Decrypt data using a key.
521 * @param context Context structure [input, output]
522 * @param key Key value from key table, ticket, etc. [input]
523 * @param usage Key usage [input]
524 * @param cipher_state Cipher state [input]
525 * @param input Encrypted data [input]
526 * @param output Decrypted data [output]
531 * KRB5_BAD_ENCTYPE Bad encryption type
533 * Kerberos error codes
538 krb5_error_code KRB5_CALLCONV
539 krb5_c_decrypt(krb5_context context, const krb5_keyblock *key,
540 krb5_keyusage usage, const krb5_data *cipher_state,
541 const krb5_enc_data *input, krb5_data *output);
544 * @brief Compute the length of the ciphertext produced by encrypting @a inputlen bytes.
546 * @param context Context structure [input, output]
547 * @param enctype Encryption type [input]
548 * @param inputlen Length of encrypted data [input]
549 * @param length Length of unecrypted data [output]
554 * KRB5_BAD_ENCTYPE Bad encryption type
556 * Kerberos error codes
559 krb5_error_code KRB5_CALLCONV
560 krb5_c_encrypt_length(krb5_context context, krb5_enctype enctype,
561 size_t inputlen, size_t *length);
564 * @brief Write the block size for the specified encryption type into the @a size_t pointed to by @a blocksize.
566 * @param context Context structure [input, output]
567 * @param enctype Encryption type [input]
568 * @param blocksize Attribute of encryption system [output]
573 * KRB5_BAD_ENCTYPE Bad encryption type
575 * ENOMEM Insufficient memory
577 * Kerberos error codes
581 krb5_error_code KRB5_CALLCONV
582 krb5_c_block_size(krb5_context context, krb5_enctype enctype,
586 * @brief Write the length of the specified key to keylength.
588 * @param context Context structure [input, output]
589 * @param enctype Encryption type [input]
590 * @param keybytes Number of bytes required to make a key [input]
591 * @param keylength Length of final key
596 * Kerberos error codes
598 krb5_error_code KRB5_CALLCONV
599 krb5_c_keylengths(krb5_context context, krb5_enctype enctype,
600 size_t *keybytes, size_t *keylength);
603 * @brief Initialize a new cipher state for @a enc_type in the specified @c _krb5_keyblock.
605 * @param context Context structure [input, output]
606 * @param key Key [input]
607 * @param usage Usage [input]
608 * @param new_state New cipher state [output]
610 * @note @a new_state contains the new cipher state.
615 * Kerberos error codes
617 krb5_error_code KRB5_CALLCONV
618 krb5_c_init_state(krb5_context context, const krb5_keyblock *key,
619 krb5_keyusage usage, krb5_data *new_state);
622 * @brief Free a cipher state previously allocated by krb5_c_init_state().
624 * @param context Context structure [input, output]
625 * @param key Key [input]
626 * @param state Cipher state to be freed [input]
631 * Kerberos error codes
634 krb5_error_code KRB5_CALLCONV
635 krb5_c_free_state(krb5_context context, const krb5_keyblock *key,
639 * @brief Generate pseudo-random bytes from @a input.
641 * @param context Context structure [input, output]
642 * @param keyblock Key [input]
643 * @param input Input data [input]
644 * @param output Output data [output]
649 * Kerberos error codes
652 krb5_error_code KRB5_CALLCONV
653 krb5_c_prf(krb5_context context, const krb5_keyblock *keyblock, krb5_data *input, krb5_data *output);
656 * @brief Get the number of pseudo-random bytes output by krb5_c_prf() for the specified @a enctype.
658 * @param context Context structure [input, output]
659 * @param enctype Encryption type [input]
660 * @param len Number of bytes for @a enctype [output]
662 * Make sure to free the allocated memory when it is no longer needed.
667 * Kerberos error codes
670 krb5_error_code KRB5_CALLCONV
671 krb5_c_prf_length(krb5_context context, krb5_enctype enctype, size_t *len);
674 * @return Returns KRB-FX-CF2 in a newly allocated
675 * keyblock on success or an error code on error.
677 * This function is simple in that it assumes
678 * pepper1 and pepper2 are C strings with no
679 * internal nulls and that the enctype of the
680 * result will be the same as that of k1. Both
681 * of these assumptions are true of current
684 krb5_error_code KRB5_CALLCONV
685 krb5_c_fx_cf2_simple(krb5_context context,
686 krb5_keyblock *k1, const char *pepper1,
687 krb5_keyblock *k2, const char *pepper2,
688 krb5_keyblock **out);
691 * @brief Create a key from @a random_key.
693 * @param context Context structure [input, output]
694 * @param enctype Encryption type [input]
695 * @param k5_random_key Pointer to an allocated and initialized keyblock [output]
697 * The @a length field in @c _krb5_c_keylength ensures that @a random_key->contents points to an allocated buffer
698 * of the correct length.
700 * Make sure to free the allocated memory when it is no longer needed.
705 * KRB5_BAD_ENCTYPE Bad encryption type
707 * ENOMEM Insufficient memory
709 * Kerberos error codes
712 krb5_error_code KRB5_CALLCONV
713 krb5_c_make_random_key(krb5_context context, krb5_enctype enctype,
714 krb5_keyblock *k5_random_key);
717 * @param context Context structure [input, output]
718 * @param enctype Encryption type [input]
719 * @param random_data Pointer to @c _krb5_data structure [input]
720 * @param k5_random_key Pointer to an allocated and initialized keyblock [output]
725 * Kerberos error codes
727 krb5_error_code KRB5_CALLCONV
728 krb5_c_random_to_key(krb5_context context, krb5_enctype enctype,
729 krb5_data *random_data, krb5_keyblock *k5_random_key);
732 * @brief Add entropy to the pseudo-random number generator.
734 * @param context Context structure [input, output]
735 * @param randsource Entropy source [input]
736 * @param data Data [input, output]
738 * @note This might cause the @c PRNG to be reseeded, although this is not guaranteed.
743 * Kerberos error codes
747 krb5_error_code KRB5_CALLCONV
748 krb5_c_random_add_entropy(krb5_context context, unsigned int randsource,
749 const krb5_data *data);
752 * @brief Generate pseudo-random bytes using entropy from OS.
754 * @param context Context structure [input, output]
755 * @param data Random data [output]
757 * @a data->length specifies the number of bytes to generate and @a data->data points to an allocated buffer of the correct length.
762 * KRB5_CRYPTO_INTERNAL Cryptosystem internal error
764 * Kerberos error codes
766 krb5_error_code KRB5_CALLCONV
767 krb5_c_random_make_octets(krb5_context context, krb5_data *data);
770 * @brief Collect entropy from the OS if possible.
772 * @a strong requests that as strong
773 * of a source of entropy as available be used. Setting @a strong may
774 * increase the probability of blocking and should not be used for normal
775 * applications. Good uses include seeding the PRNG for kadmind
778 * @param context Context structure [input, output]
779 * @param strong Strongest available source of entropy [input]
780 * @param success 1 if OS provides entropy, 0 if OS did not provide entropy [output]
782 * @note If @a strong is non-zero, this function attempts to use the strongest available source of entropy.
785 * If the OS provided and @a success is non-null,@a success is set to 1
788 * Kerberos error codes
790 krb5_error_code KRB5_CALLCONV
791 krb5_c_random_os_entropy(krb5_context context, int strong, int *success);
793 /** @deprecated Replaced by krb5_c_ API family. */
794 krb5_error_code KRB5_CALLCONV
795 krb5_c_random_seed(krb5_context context, krb5_data *data);
798 * @brief Convert the specified string to a key, using the specified encryption type, salt value, and parameters.
800 * @param context Context structure [input, output]
801 * @param enctype Encryption type [input]
802 * @param string String to be converted [input]
803 * @param salt Salt value [input]
804 * @param key Generated key [output]
809 * KRB5_BAD_ENCTYPE Bad encryption type
811 * KRB5_CRYPTO_INTERNAL Cryptosystem internal error
813 * ENOMEM Insufficient memory
815 * Kerberos error codes
820 krb5_error_code KRB5_CALLCONV
821 krb5_c_string_to_key(krb5_context context, krb5_enctype enctype,
822 const krb5_data *string, const krb5_data *salt,
826 * @brief Convert a string representation of a key into a @c _krb5_keyblock structure using a specified group of parameters.
828 * @param context Context structure [input, output]
829 * @param enctype Encryption type [input]
830 * @param string String form of the key [input]
831 * @param salt Salt value used in the encryption [input]
832 * @param params Parameters to be used for this conversion [input]
833 * @param key Keyblock [output]
838 * KRB5_BAD_ENCTYPE Bad encryption type
840 * KRB5_CRYPTO_INTERNAL Cryptosystem internal error
842 * ENOMEM Insufficient memory
844 * Kerberos error codes
849 krb5_error_code KRB5_CALLCONV
850 krb5_c_string_to_key_with_params(krb5_context context,
851 krb5_enctype enctype,
852 const krb5_data *string,
853 const krb5_data *salt,
854 const krb5_data *params,
858 * @brief Compare two encryption types.
860 * @param context Context structure [input, output]
861 * @param e1 First encryption type [input]
862 * @param e2 Second encryption type [input]
863 * @param similar @c TRUE if types are similar, @c FALSE if types are different [output]
866 * TRUE @a enctypes are similar
868 * FALSE @a enctypes are different
870 * KRB5_BAD_ENCTYPE Bad encryption type
872 * Kerberos error codes
876 krb5_error_code KRB5_CALLCONV
877 krb5_c_enctype_compare(krb5_context context, krb5_enctype e1, krb5_enctype e2,
878 krb5_boolean *similar);
881 * @brief Compute a checksum.
883 * @param context Context structure [input, output]
884 * @param cksumtype Checksum type [input]
885 * @param key Encryption key [input]
886 * @param usage Usage [input]
887 * @param input Input data [input]
888 * @param cksum Checksum [output]
893 * KRB5_BAD_ENCTYPE Bad encryption type
895 * ENOMEM Insufficient memory
897 * Kerberos error codes
901 krb5_error_code KRB5_CALLCONV
902 krb5_c_make_checksum(krb5_context context, krb5_cksumtype cksumtype,
903 const krb5_keyblock *key, krb5_keyusage usage,
904 const krb5_data *input, krb5_checksum *cksum);
907 * @brief Verify the checksum of data in @a cksum that was created with a @a key using the specified key usage.
909 * @param context Context structure [input, output]
910 * @param key Encryption key [input]
911 * @param usage Usage [input]
912 * @param data Data [input]
913 * @param cksum Checksum to be verified [input]
914 * @param valid Non-zero for success, zero for failure [output]
921 * KRB5_BAD_ENCTYPE Bad encryption type
923 * KRB5_BAD_MSIZE Message size is incompatible with encryption type
925 * Kerberos error codes
929 krb5_error_code KRB5_CALLCONV
930 krb5_c_verify_checksum(krb5_context context, const krb5_keyblock *key,
931 krb5_keyusage usage, const krb5_data *data,
932 const krb5_checksum *cksum, krb5_boolean *valid);
935 * @brief Output the checksum length produced by the specified checksum type.
937 * @param context Context structure [input, output]
938 * @param cksumtype Checksum type [input]
939 * @param length Checksum length [output]
944 * KRB5_BAD_ENCTYPE Bad encryption type
946 * Kerberos error codes
950 krb5_error_code KRB5_CALLCONV
951 krb5_c_checksum_length(krb5_context context, krb5_cksumtype cksumtype,
955 * @brief Get list of checksum types that match a specified encryption type.
957 * @param context Context structure [input, output]
958 * @param enctype Encryption type [input]
959 * @param count Count of checksums matching the encryption type [output]
960 * @param cksumtypes List of matching checksums [output]
962 * This returns only the checksum types that use key derivation.
964 * Make sure to free the allocated memory when it is no longer needed.
969 * ENOMEM Insufficient memory
971 * Kerberos error codes
976 krb5_error_code KRB5_CALLCONV
977 krb5_c_keyed_checksum_types(krb5_context context, krb5_enctype enctype,
978 unsigned int *count, krb5_cksumtype **cksumtypes);
980 #define KRB5_KEYUSAGE_AS_REQ_PA_ENC_TS 1
981 #define KRB5_KEYUSAGE_KDC_REP_TICKET 2
982 #define KRB5_KEYUSAGE_AS_REP_ENCPART 3
983 #define KRB5_KEYUSAGE_TGS_REQ_AD_SESSKEY 4
984 #define KRB5_KEYUSAGE_TGS_REQ_AD_SUBKEY 5
985 #define KRB5_KEYUSAGE_TGS_REQ_AUTH_CKSUM 6
986 #define KRB5_KEYUSAGE_TGS_REQ_AUTH 7
987 #define KRB5_KEYUSAGE_TGS_REP_ENCPART_SESSKEY 8
988 #define KRB5_KEYUSAGE_TGS_REP_ENCPART_SUBKEY 9
989 #define KRB5_KEYUSAGE_AP_REQ_AUTH_CKSUM 10
990 #define KRB5_KEYUSAGE_AP_REQ_AUTH 11
991 #define KRB5_KEYUSAGE_AP_REP_ENCPART 12
992 #define KRB5_KEYUSAGE_KRB_PRIV_ENCPART 13
993 #define KRB5_KEYUSAGE_KRB_CRED_ENCPART 14
994 #define KRB5_KEYUSAGE_KRB_SAFE_CKSUM 15
995 #define KRB5_KEYUSAGE_APP_DATA_ENCRYPT 16
996 #define KRB5_KEYUSAGE_APP_DATA_CKSUM 17
997 #define KRB5_KEYUSAGE_KRB_ERROR_CKSUM 18
998 #define KRB5_KEYUSAGE_AD_KDCISSUED_CKSUM 19
999 #define KRB5_KEYUSAGE_AD_MTE 20
1000 #define KRB5_KEYUSAGE_AD_ITE 21
1002 /* XXX need to register these */
1004 #define KRB5_KEYUSAGE_GSS_TOK_MIC 22
1005 #define KRB5_KEYUSAGE_GSS_TOK_WRAP_INTEG 23
1006 #define KRB5_KEYUSAGE_GSS_TOK_WRAP_PRIV 24
1008 /* Defined in hardware preauth draft */
1010 #define KRB5_KEYUSAGE_PA_SAM_CHALLENGE_CKSUM 25
1011 #define KRB5_KEYUSAGE_PA_SAM_CHALLENGE_TRACKID 26
1012 #define KRB5_KEYUSAGE_PA_SAM_RESPONSE 27
1014 /* Defined in KDC referrals draft */
1016 * @note There is a conflict with the value of @c KRB5_KEYUSAGE_PA_REFERRAL:
1017 * it is used for hardware Pre-athentication @a and KDC referrals.
1020 #define KRB5_KEYUSAGE_PA_REFERRAL 26 /* XXX note conflict with above */
1022 /* Defined in [MS-SFU] */
1023 #define KRB5_KEYUSAGE_PA_S4U_X509_USER_REQUEST 26 /* XXX note conflict with above */
1024 #define KRB5_KEYUSAGE_PA_S4U_X509_USER_REPLY 27 /* XXX note conflict with above */
1026 #define KRB5_KEYUSAGE_AD_SIGNEDPATH -21
1027 #define KRB5_KEYUSAGE_IAKERB_FINISHED 42
1028 #define KRB5_KEYUSAGE_PA_PKINIT_KX 44
1029 /* define in draft-ietf-krb-wg-preauth-framework*/
1030 #define KRB5_KEYUSAGE_FAST_REQ_CHKSUM 50
1031 #define KRB5_KEYUSAGE_FAST_ENC 51
1032 #define KRB5_KEYUSAGE_FAST_REP 52
1033 #define KRB5_KEYUSAGE_FAST_FINISHED 53
1034 #define KRB5_KEYUSAGE_ENC_CHALLENGE_CLIENT 54
1035 #define KRB5_KEYUSAGE_ENC_CHALLENGE_KDC 55
1036 #define KRB5_KEYUSAGE_AS_REQ 56
1039 * @brief Verify that the specified encryption type is a valid Kerberos encryption type.
1041 * @param ktype Encryption type [input]
1050 krb5_boolean KRB5_CALLCONV
1051 krb5_c_valid_enctype(krb5_enctype ktype);
1054 * @brief Verify that specified checksum type is a valid Kerberos checksum type.
1056 * @param ctype Checksum type [input]
1065 krb5_boolean KRB5_CALLCONV
1066 krb5_c_valid_cksumtype(krb5_cksumtype ctype);
1069 * @brief Test whether a checksum type is collision-proof.
1071 * @param ctype Checksum type [input]
1074 * 0 Not collision-proof, or checksum type is not in the list
1078 krb5_boolean KRB5_CALLCONV
1079 krb5_c_is_coll_proof_cksum(krb5_cksumtype ctype);
1082 * @brief Test whether a checksum type is keyed.
1084 * @param ctype Checksum type [input]
1087 * 0 Checksum does not use derived keys, or checksum type is not in the list
1089 * 1 Checksum uses derived keys
1091 krb5_boolean KRB5_CALLCONV
1092 krb5_c_is_keyed_cksum(krb5_cksumtype ctype);
1095 #define KRB5_CRYPTO_TYPE_EMPTY 0 /* [in] ignored */
1096 #define KRB5_CRYPTO_TYPE_HEADER 1 /* [out] header */
1097 #define KRB5_CRYPTO_TYPE_DATA 2 /* [in, out] plaintext */
1098 #define KRB5_CRYPTO_TYPE_SIGN_ONLY 3 /* [in] associated data */
1099 #define KRB5_CRYPTO_TYPE_PADDING 4 /* [out] padding */
1100 #define KRB5_CRYPTO_TYPE_TRAILER 5 /* [out] checksum for encrypt */
1101 #define KRB5_CRYPTO_TYPE_CHECKSUM 6 /* [out] checksum for MIC */
1102 #define KRB5_CRYPTO_TYPE_STREAM 7 /* [in] entire message */
1104 krb5_error_code KRB5_CALLCONV
1105 krb5_c_make_checksum_iov(krb5_context context, krb5_cksumtype cksumtype,
1106 const krb5_keyblock *key, krb5_keyusage usage,
1107 krb5_crypto_iov *data, size_t num_data);
1109 krb5_error_code KRB5_CALLCONV
1110 krb5_c_verify_checksum_iov(krb5_context context, krb5_cksumtype cksumtype,
1111 const krb5_keyblock *key, krb5_keyusage usage,
1112 const krb5_crypto_iov *data, size_t num_data,
1113 krb5_boolean *valid);
1115 krb5_error_code KRB5_CALLCONV
1116 krb5_c_encrypt_iov(krb5_context context, const krb5_keyblock *key,
1117 krb5_keyusage usage, const krb5_data *cipher_state,
1118 krb5_crypto_iov *data, size_t num_data);
1120 krb5_error_code KRB5_CALLCONV
1121 krb5_c_decrypt_iov(krb5_context context, const krb5_keyblock *key,
1122 krb5_keyusage usage, const krb5_data *cipher_state,
1123 krb5_crypto_iov *data, size_t num_data);
1125 krb5_error_code KRB5_CALLCONV
1126 krb5_c_crypto_length(krb5_context context, krb5_enctype enctype,
1127 krb5_cryptotype type, unsigned int *size);
1129 krb5_error_code KRB5_CALLCONV
1130 krb5_c_crypto_length_iov(krb5_context context, krb5_enctype enctype,
1131 krb5_crypto_iov *data, size_t num_data);
1133 krb5_error_code KRB5_CALLCONV
1134 krb5_c_padding_length(krb5_context context, krb5_enctype enctype,
1135 size_t data_length, unsigned int *size);
1137 krb5_error_code KRB5_CALLCONV
1138 krb5_k_create_key(krb5_context context, const krb5_keyblock *key_data,
1142 * Keys are logically immutable and can be "copied" by reference count.
1145 krb5_k_reference_key(krb5_context context, krb5_key key);
1148 * @brief Decrement the reference count on a key and free it if it hits zero.
1151 krb5_k_free_key(krb5_context context, krb5_key key);
1153 /** Retrieve a copy of the keyblock from a krb5_key structure. */
1154 krb5_error_code KRB5_CALLCONV
1155 krb5_k_key_keyblock(krb5_context context, krb5_key key,
1156 krb5_keyblock **key_data);
1158 /** Retrieve the enctype of a krb5_key structure. */
1160 krb5_enctype KRB5_CALLCONV
1161 krb5_k_key_enctype(krb5_context context, krb5_key key);
1163 krb5_error_code KRB5_CALLCONV
1164 krb5_k_encrypt(krb5_context context, krb5_key key, krb5_keyusage usage,
1165 const krb5_data *cipher_state, const krb5_data *input,
1166 krb5_enc_data *output);
1168 krb5_error_code KRB5_CALLCONV
1169 krb5_k_encrypt_iov(krb5_context context, krb5_key key, krb5_keyusage usage,
1170 const krb5_data *cipher_state, krb5_crypto_iov *data,
1173 krb5_error_code KRB5_CALLCONV
1174 krb5_k_decrypt(krb5_context context, krb5_key key, krb5_keyusage usage,
1175 const krb5_data *cipher_state, const krb5_enc_data *input,
1178 krb5_error_code KRB5_CALLCONV
1179 krb5_k_decrypt_iov(krb5_context context, krb5_key key, krb5_keyusage usage,
1180 const krb5_data *cipher_state, krb5_crypto_iov *data,
1183 krb5_error_code KRB5_CALLCONV
1184 krb5_k_make_checksum(krb5_context context, krb5_cksumtype cksumtype,
1185 krb5_key key, krb5_keyusage usage, const krb5_data *input,
1186 krb5_checksum *cksum);
1188 krb5_error_code KRB5_CALLCONV
1189 krb5_k_make_checksum_iov(krb5_context context, krb5_cksumtype cksumtype,
1190 krb5_key key, krb5_keyusage usage,
1191 krb5_crypto_iov *data, size_t num_data);
1193 krb5_error_code KRB5_CALLCONV
1194 krb5_k_verify_checksum(krb5_context context, krb5_key key, krb5_keyusage usage,
1195 const krb5_data *data, const krb5_checksum *cksum,
1196 krb5_boolean *valid);
1198 krb5_error_code KRB5_CALLCONV
1199 krb5_k_verify_checksum_iov(krb5_context context, krb5_cksumtype cksumtype,
1200 krb5_key key, krb5_keyusage usage,
1201 const krb5_crypto_iov *data, size_t num_data,
1202 krb5_boolean *valid);
1204 krb5_error_code KRB5_CALLCONV
1205 krb5_k_prf(krb5_context context, krb5_key key, krb5_data *in, krb5_data *out);
1207 #ifdef KRB5_OLD_CRYPTO
1209 * old cryptosystem routine prototypes. These are now layered
1210 * on top of the functions above.
1212 /** @deprecated Replaced by krb5_c_ API family.*/
1213 krb5_error_code KRB5_CALLCONV
1214 krb5_encrypt(krb5_context context, krb5_const_pointer inptr,
1215 krb5_pointer outptr, size_t size, krb5_encrypt_block *eblock,
1218 /** @deprecated Replaced by krb5_c_ API family. */
1219 krb5_error_code KRB5_CALLCONV
1220 krb5_decrypt(krb5_context context, krb5_const_pointer inptr,
1221 krb5_pointer outptr, size_t size, krb5_encrypt_block *eblock,
1224 /** @deprecated Replaced by krb5_c_ API family. */
1225 krb5_error_code KRB5_CALLCONV
1226 krb5_process_key(krb5_context context, krb5_encrypt_block *eblock,
1227 const krb5_keyblock * key);
1229 /** @deprecated Replaced by krb5_c_ API family. */
1230 krb5_error_code KRB5_CALLCONV
1231 krb5_finish_key(krb5_context context, krb5_encrypt_block * eblock);
1233 /** @deprecated See krb5_c_string_to_key() */
1234 krb5_error_code KRB5_CALLCONV
1235 krb5_string_to_key(krb5_context context, const krb5_encrypt_block *eblock,
1236 krb5_keyblock * keyblock, const krb5_data *data,
1237 const krb5_data *salt);
1239 /** @deprecated Replaced by krb5_c_ API family. */
1240 krb5_error_code KRB5_CALLCONV
1241 krb5_init_random_key(krb5_context context, const krb5_encrypt_block *eblock,
1242 const krb5_keyblock *keyblock, krb5_pointer *ptr);
1244 /** @deprecated Replaced by krb5_c_ API family. */
1245 krb5_error_code KRB5_CALLCONV
1246 krb5_finish_random_key(krb5_context context, const krb5_encrypt_block *eblock,
1249 /** @deprecated Replaced by krb5_c_ API family. */
1250 krb5_error_code KRB5_CALLCONV
1251 krb5_random_key(krb5_context context, const krb5_encrypt_block *eblock,
1252 krb5_pointer ptr, krb5_keyblock **keyblock);
1254 /** @deprecated Replaced by krb5_c_ API family. */
1255 krb5_enctype KRB5_CALLCONV
1256 krb5_eblock_enctype(krb5_context context, const krb5_encrypt_block *eblock);
1258 /** @deprecated Replaced by krb5_c_ API family. */
1259 krb5_error_code KRB5_CALLCONV
1260 krb5_use_enctype(krb5_context context, krb5_encrypt_block *eblock,
1261 krb5_enctype enctype);
1263 /** @deprecated Replaced by krb5_c_ API family. */
1264 size_t KRB5_CALLCONV
1265 krb5_encrypt_size(size_t length, krb5_enctype crypto);
1267 /** @deprecated See krb5_c_checksum_length() */
1268 size_t KRB5_CALLCONV
1269 krb5_checksum_size(krb5_context context, krb5_cksumtype ctype);
1271 /** @deprecated See krb5_c_make_checksum() */
1272 krb5_error_code KRB5_CALLCONV
1273 krb5_calculate_checksum(krb5_context context, krb5_cksumtype ctype,
1274 krb5_const_pointer in, size_t in_length,
1275 krb5_const_pointer seed, size_t seed_length,
1276 krb5_checksum * outcksum);
1278 /** @deprecated See krb5_c_verify_checksum() */
1279 krb5_error_code KRB5_CALLCONV
1280 krb5_verify_checksum(krb5_context context, krb5_cksumtype ctype,
1281 const krb5_checksum * cksum, krb5_const_pointer in,
1282 size_t in_length, krb5_const_pointer seed,
1283 size_t seed_length);
1285 #endif /* KRB5_OLD_CRYPTO */
1288 * end "encryption.h"
1292 * begin "fieldbits.h"
1295 /* kdc_options for kdc_request */
1296 /* options is 32 bits; each host is responsible to put the 4 bytes
1297 representing these bits into net order before transmission */
1298 /* #define KDC_OPT_RESERVED 0x80000000 */
1299 #define KDC_OPT_FORWARDABLE 0x40000000
1300 #define KDC_OPT_FORWARDED 0x20000000
1301 #define KDC_OPT_PROXIABLE 0x10000000
1302 #define KDC_OPT_PROXY 0x08000000
1303 #define KDC_OPT_ALLOW_POSTDATE 0x04000000
1304 #define KDC_OPT_POSTDATED 0x02000000
1305 /* #define KDC_OPT_UNUSED 0x01000000 */
1306 #define KDC_OPT_RENEWABLE 0x00800000
1307 /* #define KDC_OPT_UNUSED 0x00400000 */
1308 /* #define KDC_OPT_RESERVED 0x00200000 */
1309 /* #define KDC_OPT_RESERVED 0x00100000 */
1310 /* #define KDC_OPT_RESERVED 0x00080000 */
1311 /* #define KDC_OPT_RESERVED 0x00040000 */
1312 #define KDC_OPT_CNAME_IN_ADDL_TKT 0x00020000
1313 #define KDC_OPT_CANONICALIZE 0x00010000
1314 #define KDC_OPT_REQUEST_ANONYMOUS 0x00008000
1315 /* #define KDC_OPT_RESERVED 0x00004000 */
1316 /* #define KDC_OPT_RESERVED 0x00002000 */
1317 /* #define KDC_OPT_RESERVED 0x00001000 */
1318 /* #define KDC_OPT_RESERVED 0x00000800 */
1319 /* #define KDC_OPT_RESERVED 0x00000400 */
1320 /* #define KDC_OPT_RESERVED 0x00000200 */
1321 /* #define KDC_OPT_RESERVED 0x00000100 */
1322 /* #define KDC_OPT_RESERVED 0x00000080 */
1323 /* #define KDC_OPT_RESERVED 0x00000040 */
1324 #define KDC_OPT_DISABLE_TRANSITED_CHECK 0x00000020
1325 #define KDC_OPT_RENEWABLE_OK 0x00000010
1326 #define KDC_OPT_ENC_TKT_IN_SKEY 0x00000008
1327 /* #define KDC_OPT_UNUSED 0x00000004 */
1328 #define KDC_OPT_RENEW 0x00000002
1329 #define KDC_OPT_VALIDATE 0x00000001
1332 * Mask of ticket flags in the TGT which should be converted into KDC
1333 * options when using the TGT to get derivitive tickets.
1335 * New mask = KDC_OPT_FORWARDABLE | KDC_OPT_PROXIABLE |
1336 * KDC_OPT_ALLOW_POSTDATE | KDC_OPT_RENEWABLE
1338 #define KDC_TKT_COMMON_MASK 0x54800000
1340 /* definitions for ap_options fields */
1341 /* ap_options are 32 bits; each host is responsible to put the 4 bytes
1342 representing these bits into net order before transmission */
1343 #define AP_OPTS_RESERVED 0x80000000
1344 #define AP_OPTS_USE_SESSION_KEY 0x40000000 /**< Use session key */
1345 #define AP_OPTS_MUTUAL_REQUIRED 0x20000000 /**< Perform a mutual
1346 authentication exchange */
1347 #define AP_OPTS_ETYPE_NEGOTIATION 0x00000002
1348 #define AP_OPTS_USE_SUBKEY 0x00000001 /**< Generate a subsession key
1349 from the current session key
1350 obtained from the credentials */
1351 /* #define AP_OPTS_RESERVED 0x10000000 */
1352 /* #define AP_OPTS_RESERVED 0x08000000 */
1353 /* #define AP_OPTS_RESERVED 0x04000000 */
1354 /* #define AP_OPTS_RESERVED 0x02000000 */
1355 /* #define AP_OPTS_RESERVED 0x01000000 */
1356 /* #define AP_OPTS_RESERVED 0x00800000 */
1357 /* #define AP_OPTS_RESERVED 0x00400000 */
1358 /* #define AP_OPTS_RESERVED 0x00200000 */
1359 /* #define AP_OPTS_RESERVED 0x00100000 */
1360 /* #define AP_OPTS_RESERVED 0x00080000 */
1361 /* #define AP_OPTS_RESERVED 0x00040000 */
1362 /* #define AP_OPTS_RESERVED 0x00020000 */
1363 /* #define AP_OPTS_RESERVED 0x00010000 */
1364 /* #define AP_OPTS_RESERVED 0x00008000 */
1365 /* #define AP_OPTS_RESERVED 0x00004000 */
1366 /* #define AP_OPTS_RESERVED 0x00002000 */
1367 /* #define AP_OPTS_RESERVED 0x00001000 */
1368 /* #define AP_OPTS_RESERVED 0x00000800 */
1369 /* #define AP_OPTS_RESERVED 0x00000400 */
1370 /* #define AP_OPTS_RESERVED 0x00000200 */
1371 /* #define AP_OPTS_RESERVED 0x00000100 */
1372 /* #define AP_OPTS_RESERVED 0x00000080 */
1373 /* #define AP_OPTS_RESERVED 0x00000040 */
1374 /* #define AP_OPTS_RESERVED 0x00000020 */
1375 /* #define AP_OPTS_RESERVED 0x00000010 */
1376 /* #define AP_OPTS_RESERVED 0x00000008 */
1377 /* #define AP_OPTS_RESERVED 0x00000004 */
1380 #define AP_OPTS_WIRE_MASK 0xfffffff0
1382 /* definitions for ad_type fields. */
1383 #define AD_TYPE_RESERVED 0x8000
1384 #define AD_TYPE_EXTERNAL 0x4000
1385 #define AD_TYPE_REGISTERED 0x2000
1387 #define AD_TYPE_FIELD_TYPE_MASK 0x1fff
1390 /* flags are 32 bits; each host is responsible to put the 4 bytes
1391 representing these bits into net order before transmission */
1392 /* #define TKT_FLG_RESERVED 0x80000000 */
1393 #define TKT_FLG_FORWARDABLE 0x40000000
1394 #define TKT_FLG_FORWARDED 0x20000000
1395 #define TKT_FLG_PROXIABLE 0x10000000
1396 #define TKT_FLG_PROXY 0x08000000
1397 #define TKT_FLG_MAY_POSTDATE 0x04000000
1398 #define TKT_FLG_POSTDATED 0x02000000
1399 #define TKT_FLG_INVALID 0x01000000
1400 #define TKT_FLG_RENEWABLE 0x00800000
1401 #define TKT_FLG_INITIAL 0x00400000
1402 #define TKT_FLG_PRE_AUTH 0x00200000
1403 #define TKT_FLG_HW_AUTH 0x00100000
1404 #define TKT_FLG_TRANSIT_POLICY_CHECKED 0x00080000
1405 #define TKT_FLG_OK_AS_DELEGATE 0x00040000
1406 #define TKT_FLG_ENC_PA_REP 0x00010000
1407 #define TKT_FLG_ANONYMOUS 0x00008000
1408 /* #define TKT_FLG_RESERVED 0x00004000 */
1409 /* #define TKT_FLG_RESERVED 0x00002000 */
1410 /* #define TKT_FLG_RESERVED 0x00001000 */
1411 /* #define TKT_FLG_RESERVED 0x00000800 */
1412 /* #define TKT_FLG_RESERVED 0x00000400 */
1413 /* #define TKT_FLG_RESERVED 0x00000200 */
1414 /* #define TKT_FLG_RESERVED 0x00000100 */
1415 /* #define TKT_FLG_RESERVED 0x00000080 */
1416 /* #define TKT_FLG_RESERVED 0x00000040 */
1417 /* #define TKT_FLG_RESERVED 0x00000020 */
1418 /* #define TKT_FLG_RESERVED 0x00000010 */
1419 /* #define TKT_FLG_RESERVED 0x00000008 */
1420 /* #define TKT_FLG_RESERVED 0x00000004 */
1421 /* #define TKT_FLG_RESERVED 0x00000002 */
1422 /* #define TKT_FLG_RESERVED 0x00000001 */
1424 /* definitions for lr_type fields. */
1425 #define LR_TYPE_THIS_SERVER_ONLY 0x8000
1427 #define LR_TYPE_INTERPRETATION_MASK 0x7fff
1429 /* definitions for msec direction bit for KRB_SAFE, KRB_PRIV */
1430 #define MSEC_DIRBIT 0x8000
1431 #define MSEC_VAL_MASK 0x7fff
1441 /** Protocol version number */
1446 #define KRB5_AS_REQ ((krb5_msgtype)10) /**< Req for initial authentication */
1447 #define KRB5_AS_REP ((krb5_msgtype)11) /**< Response to KRB_AS_REQ request */
1448 #define KRB5_TGS_REQ ((krb5_msgtype)12) /**< TGS request to server */
1449 #define KRB5_TGS_REP ((krb5_msgtype)13) /**< Response to KRB_TGS_REQ req */
1450 #define KRB5_AP_REQ ((krb5_msgtype)14) /**< application request to server */
1451 #define KRB5_AP_REP ((krb5_msgtype)15) /**< Response to KRB_AP_REQ_MUTUAL */
1452 #define KRB5_SAFE ((krb5_msgtype)20) /**< Safe application message */
1453 #define KRB5_PRIV ((krb5_msgtype)21) /**< Private application message */
1454 #define KRB5_CRED ((krb5_msgtype)22) /**< Credential forwarding message */
1455 #define KRB5_ERROR ((krb5_msgtype)30) /**< Error response */
1458 #define KRB5_LRQ_NONE 0
1459 #define KRB5_LRQ_ALL_LAST_TGT 1
1460 #define KRB5_LRQ_ONE_LAST_TGT (-1)
1461 #define KRB5_LRQ_ALL_LAST_INITIAL 2
1462 #define KRB5_LRQ_ONE_LAST_INITIAL (-2)
1463 #define KRB5_LRQ_ALL_LAST_TGT_ISSUED 3
1464 #define KRB5_LRQ_ONE_LAST_TGT_ISSUED (-3)
1465 #define KRB5_LRQ_ALL_LAST_RENEWAL 4
1466 #define KRB5_LRQ_ONE_LAST_RENEWAL (-4)
1467 #define KRB5_LRQ_ALL_LAST_REQ 5
1468 #define KRB5_LRQ_ONE_LAST_REQ (-5)
1469 #define KRB5_LRQ_ALL_PW_EXPTIME 6
1470 #define KRB5_LRQ_ONE_PW_EXPTIME (-6)
1471 #define KRB5_LRQ_ALL_ACCT_EXPTIME 7
1472 #define KRB5_LRQ_ONE_ACCT_EXPTIME (-7)
1475 #define KRB5_PADATA_NONE 0
1476 #define KRB5_PADATA_AP_REQ 1
1477 #define KRB5_PADATA_TGS_REQ KRB5_PADATA_AP_REQ
1478 #define KRB5_PADATA_ENC_TIMESTAMP 2
1479 #define KRB5_PADATA_PW_SALT 3
1480 #if 0 /* Not used */
1481 #define KRB5_PADATA_ENC_ENCKEY 4 /* Key encrypted within itself */
1483 #define KRB5_PADATA_ENC_UNIX_TIME 5 /**< timestamp encrypted in key */
1484 #define KRB5_PADATA_ENC_SANDIA_SECURID 6 /**< SecurId passcode */
1485 #define KRB5_PADATA_SESAME 7 /**< Sesame project */
1486 #define KRB5_PADATA_OSF_DCE 8 /**< OSF DCE */
1487 #define KRB5_CYBERSAFE_SECUREID 9 /**< Cybersafe */
1488 #define KRB5_PADATA_AFS3_SALT 10 /**< Cygnus */
1489 #define KRB5_PADATA_ETYPE_INFO 11 /**< Etype info for preauth */
1490 #define KRB5_PADATA_SAM_CHALLENGE 12 /**< draft challenge system */
1491 #define KRB5_PADATA_SAM_RESPONSE 13 /**< draft challenge system response */
1492 #define KRB5_PADATA_PK_AS_REQ_OLD 14 /**< PKINIT */
1493 #define KRB5_PADATA_PK_AS_REP_OLD 15 /**< PKINIT */
1494 #define KRB5_PADATA_PK_AS_REQ 16 /**< PKINIT */
1495 #define KRB5_PADATA_PK_AS_REP 17 /**< PKINIT */
1496 #define KRB5_PADATA_ETYPE_INFO2 19
1497 #define KRB5_PADATA_USE_SPECIFIED_KVNO 20
1498 #define KRB5_PADATA_SVR_REFERRAL_INFO 20 /**< Windows 2000 referrals */
1499 #define KRB5_PADATA_SAM_REDIRECT 21
1500 #define KRB5_PADATA_GET_FROM_TYPED_DATA 22
1501 #define KRB5_PADATA_REFERRAL 25 /**< draft referral system */
1502 #define KRB5_PADATA_SAM_CHALLENGE_2 30 /**< draft challenge system, updated */
1503 #define KRB5_PADATA_SAM_RESPONSE_2 31 /**< draft challenge system, updated */
1504 #define KRB5_PADATA_PAC_REQUEST 128 /**< include Windows PAC */
1505 #define KRB5_PADATA_FOR_USER 129 /**< username protocol transition request */
1506 #define KRB5_PADATA_S4U_X509_USER 130 /**< certificate protocol transition request */
1507 #define KRB5_PADATA_FX_COOKIE 133
1508 #define KRB5_PADATA_FX_FAST 136
1509 #define KRB5_PADATA_FX_ERROR 137
1510 #define KRB5_PADATA_ENCRYPTED_CHALLENGE 138
1511 #define KRB5_PADATA_PKINIT_KX 147
1512 #define KRB5_ENCPADATA_REQ_ENC_PA_REP 149
1514 #define KRB5_SAM_USE_SAD_AS_KEY 0x80000000
1515 #define KRB5_SAM_SEND_ENCRYPTED_SAD 0x40000000
1516 #define KRB5_SAM_MUST_PK_ENCRYPT_SAD 0x20000000 /* currently must be zero */
1518 /** Transited encoding types */
1519 #define KRB5_DOMAIN_X500_COMPRESS 1
1521 /** alternate authentication types */
1522 #define KRB5_ALTAUTH_ATT_CHALLENGE_RESPONSE 64
1524 /* authorization data types */
1525 #define KRB5_AUTHDATA_IF_RELEVANT 1
1526 #define KRB5_AUTHDATA_KDC_ISSUED 4
1527 #define KRB5_AUTHDATA_AND_OR 5
1528 #define KRB5_AUTHDATA_MANDATORY_FOR_KDC 8
1529 #define KRB5_AUTHDATA_INITIAL_VERIFIED_CAS 9
1530 #define KRB5_AUTHDATA_OSF_DCE 64
1531 #define KRB5_AUTHDATA_SESAME 65
1532 #define KRB5_AUTHDATA_WIN2K_PAC 128
1533 #define KRB5_AUTHDATA_ETYPE_NEGOTIATION 129 /* RFC 4537 */
1534 #define KRB5_AUTHDATA_SIGNTICKET 512 /**< formerly 142 in krb5 1.8 */
1535 #define KRB5_AUTHDATA_FX_ARMOR 71
1537 /* password change constants */
1538 #define KRB5_KPASSWD_SUCCESS 0
1539 #define KRB5_KPASSWD_MALFORMED 1
1540 #define KRB5_KPASSWD_HARDERROR 2
1541 #define KRB5_KPASSWD_AUTHERROR 3
1542 #define KRB5_KPASSWD_SOFTERROR 4
1543 /* These are Microsoft's extensions in RFC 3244, and it looks like
1544 they'll become standardized, possibly with other additions. */
1545 #define KRB5_KPASSWD_ACCESSDENIED 5 /* unused */
1546 #define KRB5_KPASSWD_BAD_VERSION 6
1547 #define KRB5_KPASSWD_INITIAL_FLAG_NEEDED 7 /* unused */
1554 /** Ticket start time, end time, and renewal duration. */
1555 typedef struct _krb5_ticket_times {
1556 krb5_timestamp authtime; /**< Time at which KDC issued the initial ticket that corresponds to this ticket */
1557 /* XXX ? should ktime in KDC_REP == authtime
1558 in ticket? otherwise client can't get this */
1559 krb5_timestamp starttime; /**< optional in ticket, if not present, use @a authtime */
1560 krb5_timestamp endtime; /**< Ticket expiration time */
1561 krb5_timestamp renew_till; /**< Latest time at which renewal of ticket can be valid */
1562 } krb5_ticket_times;
1564 /** Structure for auth data */
1565 typedef struct _krb5_authdata {
1567 krb5_authdatatype ad_type; /**< ADTYPE */
1568 unsigned int length; /**< Length of data */
1569 krb5_octet *contents; /**< Data */
1572 /** Structure for transited encoding */
1573 typedef struct _krb5_transited {
1575 krb5_octet tr_type; /**< Transited encoding type */
1576 krb5_data tr_contents; /**< Contents */
1579 /** Encrypted part of ticket. */
1580 typedef struct _krb5_enc_tkt_part {
1582 /* to-be-encrypted portion */
1583 krb5_flags flags; /**< flags */
1584 krb5_keyblock *session; /**< session key: includes enctype */
1585 krb5_principal client; /**< client name/realm */
1586 krb5_transited transited; /**< list of transited realms */
1587 krb5_ticket_times times; /**< auth, start, end, renew_till */
1588 krb5_address **caddrs; /**< array of ptrs to addresses */
1589 krb5_authdata **authorization_data; /**< auth data */
1590 } krb5_enc_tkt_part;
1595 * Ticket structure that holds the C representation of the ticket protocol
1596 * message and a pointer to the representation of @c _krb5_enc_tkt_part.
1598 typedef struct _krb5_ticket {
1600 /* cleartext portion */
1601 krb5_principal server; /**< server name/realm */
1602 krb5_enc_data enc_part; /**< encryption type, kvno, encrypted encoding */
1603 krb5_enc_tkt_part *enc_part2; /**< ptr to decrypted version, if available */
1606 /* the unencrypted version */
1608 * Ticket authenticator.
1610 * Ticket authenticator: the @c c representation of @c AP-REQ message with decrypted authenticator.
1612 typedef struct _krb5_authenticator {
1614 krb5_principal client; /**< client name/realm */
1615 krb5_checksum *checksum; /**< checksum, includes type, optional */
1616 krb5_int32 cusec; /**< client usec portion */
1617 krb5_timestamp ctime; /**< client sec portion */
1618 krb5_keyblock *subkey; /**< true session key, optional */
1619 krb5_ui_4 seq_number; /**< sequence #, optional */
1620 krb5_authdata **authorization_data; /**< New add by Ari, auth data */
1621 } krb5_authenticator;
1624 * Ticket authentication data.
1626 typedef struct _krb5_tkt_authent {
1628 krb5_ticket *ticket;
1629 krb5_authenticator *authenticator;
1630 krb5_flags ap_options;
1633 /** Credentials structure including ticket, session key, and lifetime info. */
1634 typedef struct _krb5_creds {
1636 krb5_principal client; /**< client's principal identifier */
1637 krb5_principal server; /**< server's principal identifier */
1638 krb5_keyblock keyblock; /**< session encryption key info */
1639 krb5_ticket_times times; /**< lifetime info */
1640 krb5_boolean is_skey; /**< true if ticket is encrypted in
1641 another ticket's skey */
1642 krb5_flags ticket_flags; /**< flags in ticket */
1643 krb5_address **addresses; /**< addrs in ticket */
1644 krb5_data ticket; /**< ticket string itself */
1645 krb5_data second_ticket; /**< second ticket, if related to
1646 ticket (via DUPLICATE-SKEY or
1648 krb5_authdata **authdata; /**< authorization data */
1651 /** Last request entry */
1652 typedef struct _krb5_last_req_entry {
1654 krb5_int32 lr_type; /**< LR type */
1655 krb5_timestamp value; /**< Timestamp */
1656 } krb5_last_req_entry;
1658 /** Pre-authentication data */
1659 typedef struct _krb5_pa_data {
1661 krb5_preauthtype pa_type; /**< Preauthentication data type */
1662 unsigned int length; /**< Length of data */
1663 krb5_octet *contents; /**< Data */
1668 * The FAST error handling logic currently assumes that this structure and
1669 * krb5_pa_data * can be safely cast to each other if this structure changes,
1670 * that code needs to be updated to copy.
1672 typedef struct _krb5_typed_data {
1675 unsigned int length;
1679 /** Representation of KDC-REQ protocol message. */
1680 typedef struct _krb5_kdc_req {
1682 krb5_msgtype msg_type; /**< krb5_kdc_req AS_REQ or TGS_REQ? */
1683 krb5_pa_data **padata; /**< krb5_kdc_req e.g. encoded AP_REQ */
1685 krb5_flags kdc_options; /**< requested options */
1686 krb5_principal client; /**< includes realm; optional */
1687 krb5_principal server; /**< includes realm (only used if no client) */
1688 krb5_timestamp from; /**< requested starttime */
1689 krb5_timestamp till; /**< requested endtime */
1690 krb5_timestamp rtime; /**< (optional) requested renew_till */
1691 krb5_int32 nonce; /**< nonce to match request/response */
1692 int nktypes; /**< # of ktypes, must be positive */
1693 krb5_enctype *ktype; /**< requested enctype(s) */
1694 krb5_address **addresses; /**< requested addresses, optional */
1695 krb5_enc_data authorization_data; /**< encrypted auth data; OPTIONAL */
1696 krb5_authdata **unenc_authdata; /**< unencrypted auth data, if available */
1697 krb5_ticket **second_ticket;/**< second ticket array; OPTIONAL */
1698 /** the following field is added in March 2009; it is a hack so
1699 * that FAST state can be carried to pre-authentication plugins.
1700 * A new plugin interface may be a better long-term approach. It
1701 * is believed to be safe to extend this structure because it is
1702 * not found in any public APIs.
1707 /** Representation of @c EncKDCRepPart protocol message.
1709 * This is the cleartext message that is encrypted and inserted in @c KDC-REP.
1712 typedef struct _krb5_enc_kdc_rep_part {
1714 /* encrypted part: */
1715 krb5_msgtype msg_type; /**< krb5 message type */
1716 krb5_keyblock *session; /**< session key */
1717 krb5_last_req_entry **last_req; /**< array of ptrs to entries */
1718 krb5_int32 nonce; /**< nonce from request */
1719 krb5_timestamp key_exp; /**< expiration date */
1720 krb5_flags flags; /**< ticket flags */
1721 krb5_ticket_times times; /**< lifetime info */
1722 krb5_principal server; /**< server's principal identifier */
1723 krb5_address **caddrs; /**< array of ptrs to addresses, optional */
1724 krb5_pa_data **enc_padata; /**< Windows 2000 compat */
1725 } krb5_enc_kdc_rep_part;
1727 /** Representation of the @c KDC-REP protocol message. */
1728 typedef struct _krb5_kdc_rep {
1730 /* cleartext part: */
1731 krb5_msgtype msg_type; /**< AS_REP or KDC_REP? */
1732 krb5_pa_data **padata; /**< preauthentication data from KDC */
1733 krb5_principal client; /**< client's principal identifier */
1734 krb5_ticket *ticket; /**< ticket */
1735 krb5_enc_data enc_part; /**< encryption type, kvno, encrypted encoding */
1736 krb5_enc_kdc_rep_part *enc_part2; /**< unencrypted version, if available */
1739 /** Error message structure */
1740 typedef struct _krb5_error {
1742 /* some of these may be meaningless in certain contexts */
1743 krb5_timestamp ctime; /**< client sec portion; optional */
1744 krb5_int32 cusec; /**< client usec portion; optional */
1745 krb5_int32 susec; /**< server usec portion */
1746 krb5_timestamp stime; /**< server sec portion */
1747 krb5_ui_4 error; /**< error code (protocol error #'s) */
1748 krb5_principal client; /**< client's principal identifier; optional */
1749 krb5_principal server; /**< server's principal identifier */
1750 krb5_data text; /**< descriptive text */
1751 krb5_data e_data; /**< additional error-describing data */
1754 /** Authentication header. */
1755 typedef struct _krb5_ap_req {
1757 krb5_flags ap_options; /**< requested options */
1758 krb5_ticket *ticket; /**< ticket */
1759 krb5_enc_data authenticator; /**< authenticator (already encrypted) */
1762 /** C representaton of AP-REP message.
1764 * The server's response to a client's request for mutual authentication.
1766 typedef struct _krb5_ap_rep {
1768 krb5_enc_data enc_part; /**< Ciphertext of ApRepEncPart */
1771 /** Cleartext that is encrypted and put into @c _krb5_ap_rep. */
1772 typedef struct _krb5_ap_rep_enc_part {
1774 krb5_timestamp ctime; /**< client time, seconds portion */
1775 krb5_int32 cusec; /**< client time, microseconds portion */
1776 krb5_keyblock *subkey; /**< true session key, optional */
1777 krb5_ui_4 seq_number; /**< sequence #, optional */
1778 } krb5_ap_rep_enc_part;
1781 typedef struct _krb5_response {
1783 krb5_octet message_type;
1785 krb5_int32 expected_nonce; /**< The expected nonce for KDC_REP messages */
1786 krb5_timestamp request_time; /**< When we made the request */
1789 /** Credentials information inserted into @c EncKrbCredPart. */
1790 typedef struct _krb5_cred_info {
1792 krb5_keyblock *session; /**< session key used to encrypt ticket */
1793 krb5_principal client; /**< client name/realm, optional */
1794 krb5_principal server; /**< server name/realm, optional */
1795 krb5_flags flags; /**< ticket flags, optional */
1796 krb5_ticket_times times; /**< auth, start, end, renew_till, optional */
1797 krb5_address **caddrs; /**< array of ptrs to addresses */
1800 /** Cleartext credentials information. */
1801 typedef struct _krb5_cred_enc_part {
1803 krb5_int32 nonce; /**< nonce, optional */
1804 krb5_timestamp timestamp; /**< client time */
1805 krb5_int32 usec; /**< microsecond portion of time */
1806 krb5_address *s_address; /**< sender address, optional */
1807 krb5_address *r_address; /**< recipient address, optional */
1808 krb5_cred_info **ticket_info;
1809 } krb5_cred_enc_part;
1811 /** Credentials data structure.*/
1812 typedef struct _krb5_cred {
1814 krb5_ticket **tickets; /**< tickets */
1815 krb5_enc_data enc_part; /**< encrypted part */
1816 krb5_cred_enc_part *enc_part2; /**< unencrypted version, if available*/
1820 * Sandia password generation structure
1821 * Used by internal functions only
1823 typedef struct _passwd_phrase_element {
1827 } passwd_phrase_element;
1831 * Used by internal functions only
1833 typedef struct _krb5_pwd_data {
1836 passwd_phrase_element **element;
1839 /* these need to be here so the typedefs are available for the prototypes */
1841 * Note for Windows 2000 compatibility this is encoded
1842 * in the enc_padata field of the krb5_enc_kdc_rep_part.
1844 typedef struct _krb5_pa_svr_referral_data {
1845 /** Referred name, only realm is required */
1846 krb5_principal principal;
1847 } krb5_pa_svr_referral_data;
1849 typedef struct _krb5_pa_server_referral_data {
1850 krb5_data *referred_realm;
1851 krb5_principal true_principal_name;
1852 krb5_principal requested_principal_name;
1853 krb5_timestamp referral_valid_until;
1854 krb5_checksum rep_cksum;
1855 } krb5_pa_server_referral_data;
1857 typedef struct _krb5_pa_pac_req {
1858 /** TRUE if a PAC should be included in TGS-REP */
1859 krb5_boolean include_pac;
1863 * begin "safepriv.h"
1866 #define KRB5_AUTH_CONTEXT_DO_TIME 0x00000001 /**< set timestamp in the message */
1867 #define KRB5_AUTH_CONTEXT_RET_TIME 0x00000002
1868 #define KRB5_AUTH_CONTEXT_DO_SEQUENCE 0x00000004 /**< set sequence number in the message */
1869 #define KRB5_AUTH_CONTEXT_RET_SEQUENCE 0x00000008
1870 #define KRB5_AUTH_CONTEXT_PERMIT_ALL 0x00000010
1871 #define KRB5_AUTH_CONTEXT_USE_SUBKEY 0x00000020
1875 * Sequence number and timestamp information output by krb5_read_priv() and
1878 typedef struct krb5_replay_data {
1879 krb5_timestamp timestamp; /**< Timestamp, seconds portion */
1880 krb5_int32 usec; /**< Timestamp, microseconds portion */
1881 krb5_ui_4 seq; /**< Sequence number */
1884 /* flags for krb5_auth_con_genaddrs() */
1885 #define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR 0x00000001 /**< Generate the local network address */
1886 #define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR 0x00000002 /**< Generate the remote network address. */
1887 #define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR 0x00000004 /**< Generate the local network address and the local port. */
1888 #define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR 0x00000008 /**< Generate the remote network address and the remote port */
1890 /* type of function used as a callback to generate checksum data for
1893 typedef krb5_error_code
1894 (KRB5_CALLCONV * krb5_mk_req_checksum_func) (krb5_context, krb5_auth_context , void *,
1906 typedef krb5_pointer krb5_cc_cursor; /* cursor for sequential lookup */
1908 struct _krb5_ccache;
1909 typedef struct _krb5_ccache *krb5_ccache;
1910 struct _krb5_cc_ops;
1911 typedef struct _krb5_cc_ops krb5_cc_ops;
1914 * @brief Cursor for iterating over all ccaches
1916 struct _krb5_cccol_cursor;
1917 typedef struct _krb5_cccol_cursor *krb5_cccol_cursor;
1919 /* for retrieve_cred */
1920 #define KRB5_TC_MATCH_TIMES 0x00000001 /**< The requested lifetime must be
1921 at least as great as that specified */
1922 #define KRB5_TC_MATCH_IS_SKEY 0x00000002 /**< The is_skey field must match exactly */
1923 #define KRB5_TC_MATCH_FLAGS 0x00000004 /**< All the flags set in the match credentials
1924 must be set in the cache credentials */
1925 #define KRB5_TC_MATCH_TIMES_EXACT 0x00000008 /**< All the time fields must match exactly */
1926 #define KRB5_TC_MATCH_FLAGS_EXACT 0x00000010 /**< All the flags must match exactly */
1927 #define KRB5_TC_MATCH_AUTHDATA 0x00000020 /**< The authorization data must match */
1928 #define KRB5_TC_MATCH_SRV_NAMEONLY 0x00000040 /**< Only the name portion
1929 of the principal name must match */
1930 #define KRB5_TC_MATCH_2ND_TKT 0x00000080 /**< The second ticket must match */
1931 #define KRB5_TC_MATCH_KTYPE 0x00000100 /**< The encryption key type must match */
1932 #define KRB5_TC_SUPPORTED_KTYPES 0x00000200 /**< The supported key types must match */
1934 /* for set_flags and other functions */
1935 #define KRB5_TC_OPENCLOSE 0x00000001 /**< Open and close the cache each time a
1936 credentials cache routine is called */
1937 #define KRB5_TC_NOTICKET 0x00000002
1939 /** Retrieve the name but not type of a credential cache.
1941 * @param [in] context Context structure
1942 * @param [in] cache Credentials cache handle
1944 * @warning Returns the name of the credential cache as an alias that
1945 * should not be freed or modified by the caller. This name does not
1946 * include the type portion, so cannot be used as input to krb5_cc_resolve().
1949 * On success - the name of the credential cache.
1951 const char * KRB5_CALLCONV
1952 krb5_cc_get_name(krb5_context context, krb5_ccache cache);
1955 /** Generate a new handle for a specified (unopened) credentials cache.
1957 * @param [in] context Context structure
1958 * @param [in,out] cache Credentials cache handle
1960 * @deprecated Replaced by krb5_cc_new_unique()
1962 * This function generate a new credential chache whose name is guaranteed to be unique.
1964 * @note In the case the credential file, the cache stays unopen, but the new filename is reserved.
1966 * @retval 0 Success; Otherwise - Kerberos error codes
1968 krb5_error_code KRB5_CALLCONV
1969 krb5_cc_gen_new(krb5_context context, krb5_ccache *cache);
1970 #endif /* KRB5_DEPRECATED */
1972 /** Initialize credentials cache.
1974 * @param [in] context Context structure
1975 * @param [in] cache Credentials cache handle
1976 * @param [in] principal Default principal name for the credentials cache
1978 * Destroy an existing credentials cache and create a new credentials cache
1979 * by the same name, as specifed by @a cache for specified @a principal.
1981 * @note This function also modifies the specified credentials cache.
1986 * System errors; Permission errors; Kerberos error codes
1988 krb5_error_code KRB5_CALLCONV
1989 krb5_cc_initialize(krb5_context context, krb5_ccache cache,
1990 krb5_principal principal);
1992 /** Destroy a credentials cache.
1994 * @param [in] context Context structure
1995 * @param [in] cache Credentials cache handle
1997 * This function closes and deletes @a cache and releases any other resources
1998 * acquired during use of the credentials cache.
1999 * @a cache must identify a valid credentials cache.
2001 * @note After completion, @a cache may not be used. It may be reinitialized
2002 * with krb5_cc_resolve() or krb5_cc_gen_new().
2009 krb5_error_code KRB5_CALLCONV
2010 krb5_cc_destroy(krb5_context context, krb5_ccache cache);
2012 /** Close a credentials cache and invalidate its handle.
2014 * @param [in] context Context structure
2015 * @param [in] cache Credentials cache handle
2017 * @a cache may be reinitialized with krb5_cc_resolve() or krb5_cc_gen_new().
2019 * @sa KRB5_TC_OPENCLOSE flag
2024 * Kerberos error codes
2026 krb5_error_code KRB5_CALLCONV
2027 krb5_cc_close(krb5_context context, krb5_ccache cache);
2029 /** Store credentials in a specified credentials cache.
2031 * @param [in] context Context structure
2032 * @param [in,out] cache Credentials cache handle
2033 * @param [in] creds Credentials to be stored in cache
2035 * This function stores @a creds into @a cache.
2036 * If @a creds->server and the server in the decoded ticket @a creds->ticket
2037 * differ, both principals will be stored.
2041 * @return Permission errors; Storage failure errors; Kerberos error codes
2043 krb5_error_code KRB5_CALLCONV
2044 krb5_cc_store_cred(krb5_context context, krb5_ccache cache, krb5_creds *creds);
2046 /** Retrieve a specified credentials from a credentials cache.
2048 * @param [in] context Context structure
2049 * @param [in] cache Credentials cache handle
2050 * @param [in] flags Flags bit mask
2051 * @param [in] mcreds Credentials to match
2052 * @param [out] creds Credentials that match the requested value
2054 * This function searches a credentials cache for credentials matching @a mcreds
2055 * and returns it if found.
2057 * Valid values for @a flags are:
2059 * @li @c KRB5_TC_MATCH_TIMES The requested lifetime must be
2060 * at least as great as that specified.
2061 * @li @c KRB5_TC_MATCH_IS_SKEY The @a is_skey field much match exactly.
2062 * @li @c KRB5_TC_MATCH_FLAGS The flags in @a mcreds and @a creds must match
2063 * @li @c KRB5_TC_MATCH_TIMES_EXACT The requested lifetime must match exactly.
2064 * @li @c KRB5_TC_MATCH_FLAGS_EXACT Flags in @a mcreds and @a creds must match exactly.
2065 * @li @c KRB5_TC_MATCH_AUTHDATA The authorization data must match.
2066 * @li @c KRB5_TC_MATCH_SRV_NAMEONLY Only the name portion of the principal name must
2067 * match. The realm field can be different.
2068 * If this flag is not set, the entire principal
2070 * @li @c KRB5_TC_MATCH_2ND_TKT The second tickets must match.
2071 * @li @c KRB5_TC_MATCH_KTYPE The encryption key types must match.
2072 * @li @c KRB5_TC_MATCH_SUPPORTED_KTYPES Check all matching entries that have any supported
2073 * encryption type and return the one with the encryption
2074 * type listed earliest.
2076 * Use krb5_free_cred_contents() to free @a creds when it is no longer needed.
2078 * @retval 0 Success; Otherwise - Kerberos error codes
2080 krb5_error_code KRB5_CALLCONV
2081 krb5_cc_retrieve_cred(krb5_context context, krb5_ccache cache,
2082 krb5_flags flags, krb5_creds *mcreds,
2085 /** Get the primary principal of a credentials cache.
2087 * @param [in] context Context structure
2088 * @param [in] cache Credentials cache handle
2089 * @param [out] principal Primary principal
2091 * @note The primary principal is set by calling krb5_cc_initialize().
2093 * Use krb5_free_principal() to free @a principal when it is no longer needed.
2098 * Kerberos error codes
2100 krb5_error_code KRB5_CALLCONV
2101 krb5_cc_get_principal(krb5_context context, krb5_ccache cache,
2102 krb5_principal *principal);
2104 /** Prepare to sequentially read every credential in a credentials cache.
2106 * @param [in] context Context structure
2107 * @param [in] cache Credentials cache handle
2108 * @param [out] cursor Cursor
2110 * krb5_cc_end_seq_get() must be called to complete the retreive operation.
2112 * @note If @a cache was modified between the time of the call to this function
2113 * and the time of the final krb5_cc_end_seq_get(), the results are undefined.
2115 * @retval 0 Success; Otherwise - Kerberos error codes
2117 krb5_error_code KRB5_CALLCONV
2118 krb5_cc_start_seq_get(krb5_context context, krb5_ccache cache,
2119 krb5_cc_cursor *cursor);
2121 /** Retrieve the next entry from the credentials cache.
2123 * @param [in] context Context structure
2124 * @param [in] cache Credentials cache handle
2125 * @param [in,out] cursor Cursor
2126 * @param [out] creds Credentials cache entry corresponding to the cursor
2128 * @note The cursor value is updated upon successful completion of this function.
2129 * Subsequent calls to krb5_cc_next_cred() use the updated value.
2131 * Use krb5_free_cred_contents() to free @a creds when it is no longer needed.
2133 * @sa krb5_cc_start_seq_get(), krb5_end_seq_get()
2135 * @retval 0 Success; Otherwise - Kerberos error codes
2137 krb5_error_code KRB5_CALLCONV
2138 krb5_cc_next_cred(krb5_context context, krb5_ccache cache,
2139 krb5_cc_cursor *cursor, krb5_creds *creds);
2141 /** Finish a series of sequential processing credentials cache entries.
2143 * @param [in] context Context structure
2144 * @param [in] cache Credentials cache handle
2145 * @param [in,out] cursor Cursor that was created by krb5_cc_start_seq_get()
2147 * This function finishes processing credentials cache entries and invalidates @a cursor.
2149 * @sa krb5_cc_next_cred()
2151 * @retval 0 (always)
2153 krb5_error_code KRB5_CALLCONV
2154 krb5_cc_end_seq_get(krb5_context context, krb5_ccache cache,
2155 krb5_cc_cursor *cursor);
2157 /** Remove credentials from a credentials cache.
2159 * @param [in] context Context structure
2160 * @param [in] cache Credentials cache handle
2161 * @param [in] flags Bitwise-ORed search flags
2162 * @param [in] creds Credentials to be matched
2164 * @warning This function is not implemented on UNIX'es. Returns KRB5_CC_NOSUPP.
2166 * Valid values for search flags are:
2167 * @li @c KRB5_TC_MATCH_TIMES The requested lifetime is required to be at least
2168 * as great as that specified.
2169 * @li @c KRB5_TC_MATCH_IS_SKEY The @a is_skey field much match exactly.
2170 * @li @c KRB5_TC_MATCH_FLAGS The set bits in @a mcreds must match in @a creds.
2171 * @li @c KRB5_TC_MATCH_TIMES_EXACT The requested lifetime must match exactly.
2172 * @li @c KRB5_TC_MATCH_FLAGS_EXACT All bits in @a mcreds must match exactly.
2173 * @li @c KRB5_TC_MATCH_AUTHDATA The authentication data must match.
2174 * @li @c KRB5_TC_MATCH_SRV_NAMEONLY Only the name portion of the principal name must match.
2175 * The realm field can be different. By default,
2176 * the entire principal name must match.
2177 * @li @c KRB5_TC_MATCH_2ND_TKT The second tickets must match.
2178 * @li @c KRB5_TC_MATCH_KTYPE The encryption key types must match.
2179 * @li @c KRB5_TC_MATCH_SUPPORTED_KTYPES Check all matching entries that have
2180 * any supported encryption type.
2182 * @return No matches found; Data cannot be deleted; Kerberos error codes
2184 krb5_error_code KRB5_CALLCONV
2185 krb5_cc_remove_cred(krb5_context context, krb5_ccache cache, krb5_flags flags,
2188 /** Set options flags on a credentials cache.
2190 * @param [in] context Context structure
2191 * @param [in,out] cache Credentials cache handle
2192 * @param [in] flags Flag bit mask
2194 * This function resets @a cache flags to @a flags.
2196 * @retval 0 Success; Otherwise - Kerberos error codes
2198 krb5_error_code KRB5_CALLCONV
2199 krb5_cc_set_flags(krb5_context context, krb5_ccache cache, krb5_flags flags);
2201 /** Retrieve flags from a credentials cache structure.
2203 * @param [in] context Context structure
2204 * @param [in] cache Credentials cache handle returned by
2205 * krb5_cc_resolve() or krb5_cc_generate_new()
2206 * @param [out] flags Flag bit mask
2208 * @warning For memory credential cache always returns KRB5_OK.
2210 * @retval 0 Success; Otherwise - Kerberos error codes
2212 krb5_error_code KRB5_CALLCONV
2213 krb5_cc_get_flags(krb5_context context, krb5_ccache cache, krb5_flags *flags);
2215 /** Retrieve the type of a credential cache.
2217 * @param [in] context Context structure
2218 * @param [in] cache Credentials cache handle
2220 * @return The type of a credential cache as an alias that should not be
2221 * modified or freed by the caller.
2223 const char * KRB5_CALLCONV
2224 krb5_cc_get_type(krb5_context context, krb5_ccache cache);
2226 /** Move a credential cache.
2228 * @param [in] context Context structure
2229 * @param [in] src The credential cache to move the content from
2230 * @param [in] dst The credential cache to move the content to
2232 * This function re-initializes @a dst and populates it with the credentials
2233 * and default principal of @a src, and then, if successful, destroys @a src.
2235 * krb5_ccache objects are locked internally, so no data corruption
2236 * will result if this routine is called on the same credential caches
2237 * in multiple threads.
2240 * 0 Sucess; @a src is freed.
2242 * Kerberos error codes; @a src is still allocated, while @a dst is freed.
2244 krb5_error_code KRB5_CALLCONV
2245 krb5_cc_move(krb5_context context, krb5_ccache src, krb5_ccache dst);
2247 /** Return a timestamp of the last modification of the credentials cache.
2249 * @param [in] context Context structure
2250 * @param [in] ccache Credentials cache handle
2251 * @param [out] change_time The last change time of @a ccache
2253 * If an error occurs, @a change_time is set to 0.
2255 krb5_error_code KRB5_CALLCONV
2256 krb5_cc_last_change_time(krb5_context context, krb5_ccache ccache,
2257 krb5_timestamp *change_time);
2259 krb5_error_code KRB5_CALLCONV
2260 krb5_cc_lock(krb5_context context, krb5_ccache ccache);
2262 krb5_error_code KRB5_CALLCONV
2263 krb5_cc_unlock(krb5_context context, krb5_ccache ccache);
2265 /** Prepare to iterate over a collection of credentials caches.
2267 * @param [in] context Context structure
2268 * @param [in,out] cursor Cursor
2270 * Get a new cache iteration @a cursor that will iterate over all
2271 * credentials caches independent of type.
2273 * Use krb5_cccol_cursor_free() to release @a cursor when it is no longer needed.
2275 * @sa krb5_cccol_cursor_next()
2277 * @retval 0 Success; Otherwise - Kerberos error codes
2279 krb5_error_code KRB5_CALLCONV
2280 krb5_cccol_cursor_new(krb5_context context, krb5_cccol_cursor *cursor);
2282 /** Get the next credentials cache in the collection.
2284 * @param [in] context Context structure
2285 * @param [in,out] cursor Cursor
2286 * @param [out] ccache Credentials cache handle
2288 * @note When all caches are iterated over and the end of the list is reached,
2289 * @a ccache is set to NULL.
2291 * Use krb5_cc_close() to close @a ccache when it is no longer needed.
2293 * @sa krb5_cccol_cursor_new(), krb5_cccol_cursor_free()
2295 * @retval 0 Success; Otherwise - Kerberos error codes
2297 krb5_error_code KRB5_CALLCONV
2298 krb5_cccol_cursor_next(krb5_context context, krb5_cccol_cursor cursor,
2299 krb5_ccache *ccache);
2301 /** Free a credentials cache collection cursor.
2303 * @param [in] context Context structure
2304 * @param [in] cursor Cursor
2306 * @sa krb5_cccol_cursor_new(), krb5_cccol_cursor_next()
2308 * @retval 0 Success; Otherwise - Kerberos error codes
2310 krb5_error_code KRB5_CALLCONV
2311 krb5_cccol_cursor_free(krb5_context context, krb5_cccol_cursor *cursor);
2313 /** Return a timestamp of the last modification for the cache collection.
2315 * @param [in] context Context structure
2316 * @param [out] change_time Last modification timestamp
2318 * This function will go through the whole list of the credentials caches.
2319 * If the last modification time is successfully retrieved for the credentials
2320 * in the collection, it will be evaluated for being the most recent timestamp.
2321 * Otherwise, that particular cache will be ignored.
2323 * If there are no credentials in the caches, @a change_time is set to 0.
2325 * @retval 0 Success; Otherwise - Kerberos error codes
2327 krb5_error_code KRB5_CALLCONV
2328 krb5_cccol_last_change_time(krb5_context context, krb5_timestamp *change_time);
2330 krb5_error_code KRB5_CALLCONV
2331 krb5_cccol_lock(krb5_context context);
2333 krb5_error_code KRB5_CALLCONV
2334 krb5_cccol_unlock(krb5_context context);
2336 /** Create a new unique credentials cache of the specified type.
2338 * @param [in] context Context structure
2339 * @param [in] type Credentials cache type name
2340 * @param [in] hint Unused
2341 * @param [out] id Credentials cache handle
2346 * Kerberos error codes
2348 krb5_error_code KRB5_CALLCONV
2349 krb5_cc_new_unique(krb5_context context, const char *type, const char *hint,
2361 typedef struct krb5_rc_st *krb5_rcache;
2373 #define MAX_KEYTAB_NAME_LEN 1100 /* Long enough for MAXPATHLEN + some extra */
2375 typedef krb5_pointer krb5_kt_cursor; /* XXX */
2377 /** Key table entry. */
2378 typedef struct krb5_keytab_entry_st {
2380 krb5_principal principal; /**< principal of this key */
2381 krb5_timestamp timestamp; /**< time entry written to keytable */
2382 krb5_kvno vno; /**< key version number */
2383 krb5_keyblock key; /**< the secret key */
2384 } krb5_keytab_entry;
2387 typedef struct _krb5_kt *krb5_keytab;
2389 /** Return a type of a key table.
2391 * @param [in] context Context structure
2392 * @param [in] keytab Type of key table handle
2394 * The possible results might be "FILE", "MEMORY" etc
2396 * @warning The returned value must not be freed by the caller.
2399 * The key table prefix string.
2401 const char * KRB5_CALLCONV
2402 krb5_kt_get_type(krb5_context context, krb5_keytab keytab);
2404 /** Get a key table name
2406 * @param [in] context Context structure
2407 * @param [in] keytab Key table handle
2408 * @param [out] name Key table name
2409 * @param [in] namelen Maximum length to fill in name
2411 * Zeroes @a name and then copies the key table name including
2412 * its prefix and trailing delimeter.
2414 * @sa MAX_KEYTAB_NAME_LEN
2419 * KRB5_KT_NAME_TOOLONG Key table name does not fit in @a namelen bytes
2422 * Kerberos error codes
2424 krb5_error_code KRB5_CALLCONV
2425 krb5_kt_get_name(krb5_context context, krb5_keytab keytab, char *name,
2426 unsigned int namelen);
2428 /** Close a key table.
2430 * @param [in] context Context structure
2431 * @param [in] keytab Key table handle
2433 * Close a key table, invalidate its handle, and release any other resources
2434 * acquired during use of the key table.
2435 * Undo anything done by krb5_kt_resolve().
2439 krb5_error_code KRB5_CALLCONV
2440 krb5_kt_close(krb5_context context, krb5_keytab keytab);
2442 /** Get an entry from a key table.
2444 * @param [in] context Context structure
2445 * @param [in] keytab Key table handle
2446 * @param [in] principal Principal name
2447 * @param [in] vno Key version number
2448 * @param [in] enctype Encryption type. Use zero for any enctype.
2449 * @param [out] entry Returned entry from key table
2451 * Retrieve an entry from a key table that matches the @a keytab, @a principal,
2453 * The @a entry must be freed with krb5_kt_free_entry() when it is no longer needed.
2455 * @note If @a vno is zero, the function retrieves the highest-numbered-kvno
2456 * entry that matches the specified principal.
2461 * Kerberos error codes on failure
2463 krb5_error_code KRB5_CALLCONV
2464 krb5_kt_get_entry(krb5_context context, krb5_keytab keytab,
2465 krb5_const_principal principal, krb5_kvno vno,
2466 krb5_enctype enctype, krb5_keytab_entry *entry);
2468 /** Start a sequential retrieve of key table entries.
2470 * @param [in] context Context structure
2471 * @param [in] keytab Key table handle
2472 * @param [out] cursor Cursor
2474 * Prepare to read sequentially every key in the specified key table.
2475 * @a cursor is incremented for next call to krb5_kt_next_entry().
2476 * The function krb5_kt_end_seq_get() should be called to release the cursor.
2478 * @sa krb5_kt_next_entry(), krb5_kt_end_seq_get()
2483 * Kerberos error codes
2485 krb5_error_code KRB5_CALLCONV
2486 krb5_kt_start_seq_get(krb5_context context, krb5_keytab keytab,
2487 krb5_kt_cursor *cursor);
2489 /** Retrieve the next entry from the key table.
2491 * @param [in] context Context structure
2492 * @param [in] keytab Key table handle
2493 * @param [out] entry Returned key table entry
2494 * @param [in,out] cursor The cursor created by krb5_kt_start_seq_get()
2495 * and updated by successful runs of this routine
2497 * Return the next sequential entry in the specified key table and update @a cursor for
2499 * If the key table changes during the sequential get, an error is guaranteed.
2501 * @sa krb5_kt_start_seq_get(), krb5_kt_end_seq_get()
2506 * KRB5_KT_END - if the last entry was reached
2508 * Kerberos error codes
2510 krb5_error_code KRB5_CALLCONV
2511 krb5_kt_next_entry(krb5_context context, krb5_keytab keytab,
2512 krb5_keytab_entry *entry, krb5_kt_cursor *cursor);
2514 /** Complete a series of sequential key table entry retrievals and invalidate @a cursor.
2516 * @param [in] context Context structure
2517 * @param [in] keytab Key table handle
2518 * @param [out] cursor Cursor
2520 * This function should be called to release the cursor created by krb5_kt_start_seq_get()
2525 * Kerberos error codes
2527 krb5_error_code KRB5_CALLCONV
2528 krb5_kt_end_seq_get(krb5_context context, krb5_keytab keytab,
2529 krb5_kt_cursor *cursor);
2536 * begin "func-proto.h"
2539 /** Create and intialize a krb5_context structure.
2541 * @param [out] context Context structure
2543 * The @a context must be released by calling krb5_free_context() when
2544 * it is no longer needed.
2546 * @warning Any program or module that needs the Kerberos code to not trust
2547 * the environment must use krb5_init_secure_context(),
2548 * or clean out the environment.
2553 * Kerberos error codes
2555 krb5_error_code KRB5_CALLCONV
2556 krb5_init_context(krb5_context *context);
2558 /** Create and initialize a krb5_context structure using only configuration files.
2560 * @param [out] context Context structure
2562 * Initialize a context structure, using only configuration files that
2563 * are safe for a @c setuid program.
2564 * All information passed through the environment variables is ignored.
2566 * The @a context must be released by calling krb5_free_context() when
2567 * it is no longer needed.
2572 * Kerberos error codes
2574 krb5_error_code KRB5_CALLCONV
2575 krb5_init_secure_context(krb5_context *context);
2577 /** Free a krb5_context structure.
2579 * @param [in] context Context structure
2581 * This function frees a @a context that was created by krb5_init_context()
2582 * or krb5_init_secure_context().
2585 krb5_free_context(krb5_context context);
2587 /** Copy a krb5_context structure.
2589 * @param [in] ctx Context structure
2590 * @param [out] nctx_out New "cloned" context structure
2592 * The newly created context must be released by calling krb5_free_context()
2593 * when it is no longer needed.
2598 * Kerberos error codes
2600 krb5_error_code KRB5_CALLCONV
2601 krb5_copy_context(krb5_context ctx, krb5_context *nctx_out);
2603 /** Set default TGS encryption types in a krb5_context structure.
2605 * @param [in,out] context Context structure
2606 * @param [in] etypes Encryption type(s) to set
2608 * This function sets the default enctype list for TGS requests
2609 * made using @a context to @a etypes.
2611 * @note This overrides the default list (from config file or built-in).
2616 * KRB5_PROG_ETYPE_NOSUPP Program lacks support for encryption type
2618 * Kerberos error codes
2620 krb5_error_code KRB5_CALLCONV
2621 krb5_set_default_tgs_enctypes(krb5_context context, const krb5_enctype *etypes);
2623 /** Return a list of supported encryption types.
2625 * @param [in] context Context structure
2626 * @param [out] ktypes Zero-terminated list of encryption types
2628 * This function returns the content of @a context->tgs_etypes if it is non-NULL.
2629 * Otherwise, the libdefaults profile string of permitted_enctypes, if it exists.
2630 * Otherwise, the default enctype list that is defined as follows:
2631 * ENCTYPE_AES256_CTS_HMAC_SHA1_96, ENCTYPE_AES128_CTS_HMAC_SHA1_96,
2632 * ENCTYPE_DES3_CBC_SHA1, ENCTYPE_ARCFOUR_HMAC,
2633 * ENCTYPE_DES_CBC_CRC, ENCTYPE_DES_CBC_MD5, ENCTYPE_DES_CBC_MD4.
2635 * Use krb5_free_ktypes() to free @a ktypes when it is no longer needed.
2637 * @retval 0 Success; Otherwise - Kerberos error codes
2639 krb5_error_code KRB5_CALLCONV
2640 krb5_get_permitted_enctypes(krb5_context context, krb5_enctype **ktypes);
2642 /** Test whether the Kerberos library was built with multithread support.
2645 * TRUE if the library is threadsafe; FALSE otherwise
2647 krb5_boolean KRB5_CALLCONV
2648 krb5_is_thread_safe(void);
2652 /** Decrypt a ticket using the specified key table.
2654 * @param [in] context Context structure
2655 * @param [in] kt Key table
2656 * @param [in,out] ticket Ticket to be decrypted
2658 * This function takes a @a ticket as input and decrypts it using the
2659 * provided key data from @a kt. The result is placed into @a ticket->enc_part2.
2661 * @retval 0 Success; Otherwise - Kerberos error codes
2663 krb5_error_code KRB5_CALLCONV
2664 krb5_server_decrypt_ticket_keytab(krb5_context context, const krb5_keytab kt,
2665 krb5_ticket *ticket);
2667 /** Free the storage assigned to array of credentials.
2669 * @param [in] context Context structure
2670 * @param [in] tgts Array of credentials to be freed
2672 * @note The last entry in the array @a tgts must be a NULL pointer.
2675 krb5_free_tgt_creds(krb5_context context, krb5_creds **tgts);
2677 #define KRB5_GC_USER_USER 1 /**< want user-user ticket */
2678 #define KRB5_GC_CACHED 2 /**< want cached ticket only */
2679 #define KRB5_GC_CANONICALIZE 4 /**< set canonicalize KDC option */
2680 #define KRB5_GC_NO_STORE 8 /**< do not store in credentials cache */
2681 #define KRB5_GC_FORWARDABLE 16 /**< acquire forwardable tickets */
2682 #define KRB5_GC_NO_TRANSIT_CHECK 32 /**< disable transited check */
2683 #define KRB5_GC_CONSTRAINED_DELEGATION 64 /**< constrained delegation */
2685 /** Get an additional ticket.
2687 * @param [in] context Context structure
2688 * @param [in] options Options
2689 * @param [in,out] ccache Credentials cache handle
2690 * @param [in] in_creds Input credentials
2691 * @param [out] out_creds Output updated credentials
2693 * Use the specified credentials cache or a TGS exchange to get an additional
2694 * ticket for the client identified by @a in_creds->client.
2696 * Valid values for @a options are:
2697 * @li @c KRB5_GC_CACHED Search only credentials cache for the ticket
2698 * @li @c KRB5_GC_USER_USER Return a full user to user authentication ticket
2700 * @a in_creds must be non-null. @a in_creds->client and @a in_creds->server
2701 * must be filled in to specify the client and the server respectively.
2702 * If any special data needs to be included in the ticket (such as restrictions
2703 * on how the ticket can be used), specify it in @a in_creds->authdata.
2704 * If there is no special data to be passed, set @a in_creds->authdata to NULL.
2705 * The session key type is specified in @a in_creds->keyblock.keytype,
2708 * The expiration date is specified in @a in_creds->times.endtime.
2709 * The KDC may return tickets with an earlier expiration date.
2710 * If @a in_creds->times.endtime is set to 0, the latest possible
2711 * expiration date will be requested.
2713 * Any returned ticket and intermediate ticket-granting tickets are stored
2716 * Use krb5_free_creds() to free @a out_creds when it is no longer needed.
2721 * Kerberos error codes
2723 krb5_error_code KRB5_CALLCONV
2724 krb5_get_credentials(krb5_context context, krb5_flags options,
2725 krb5_ccache ccache, krb5_creds *in_creds,
2726 krb5_creds **out_creds);
2729 * @brief Contact the KDC to validate a credential.
2731 * @param context Context structure [input, output]
2732 * @param options Unused
2733 * @param ccache Credentials cache handle [input, output]
2734 * @param in_creds Input credentials [input]
2735 * @param out_creds Output credentials [output]
2737 * Make sure to free the allocated memory when it is no longer needed.
2741 * ENOMEM Insufficient memory
2743 * KRB5_PROG_ETYPE_NOSUPP Encryption type is not supported
2745 * KRB5_KDCREP_MODIFIED KDC reply did not match expectations
2747 * Kerberos error codes
2750 krb5_error_code KRB5_CALLCONV
2751 krb5_get_credentials_validate(krb5_context context, krb5_flags options,
2752 krb5_ccache ccache, krb5_creds *in_creds,
2753 krb5_creds **out_creds);
2756 * @brief Contact the KDC to renew credentials for a context.
2758 * @param context Context structure [input, output]
2759 * @param options Unused
2760 * @param ccache Credentials cache handle [input, output]
2761 * @param in_creds Input credentials [input]
2762 * @param out_creds Output credentials [output]
2764 * Make sure to free the allocated memory when it is no longer needed.
2769 * ENOMEM Insufficient memory
2771 * KRB5_PROG_ETYPE_NOSUPP Encryption type is not supported
2773 * KRB5_KDCREP_MODIFIED KDC reply did not match expectations
2775 * Kerberos error codes
2778 krb5_error_code KRB5_CALLCONV
2779 krb5_get_credentials_renew(krb5_context context, krb5_flags options,
2780 krb5_ccache ccache, krb5_creds *in_creds,
2781 krb5_creds **out_creds);
2783 /** Format a @c KRB_AP_REQ message.
2785 * @param [in] context Context structure
2786 * @param [in,out] auth_context Authentication context, containing the checksum
2787 * method to be used; a new authentication
2788 * context is returned if NULL is specified.
2789 * @param [in] ap_req_options AP_OPTS_ options
2790 * @param [in] service Service name, or NULL to use string @c host
2791 * @param [in] hostname Host name, or NULL to use local host
2792 * @param [in] in_data Application data's checksum to be
2793 * included in the authenticator; specify NULL
2794 * if no checksum is to be included
2795 * @param [in] ccache Credentials cache that is to be used to obtain
2796 * credentials to the desired service.
2797 * @param [out] outbuf @c AP-REQ message
2799 * Valid @a ap_req_options are:
2800 * @li @c AP_OPTS_USE_SESSION_KEY - Use the session key when creating the
2801 * request used for user to user authentication.
2802 * @li @c AP_OPTS_MUTUAL_REQUIRED - Request a mutual authentication packet from
2804 * @li @c AP_OPTS_USE_SUBKEY - Generate a subsession key from the current
2805 * session key obtained from the credentials.
2807 * This function is similar to krb5_mk_req_extended() except that it
2808 * uses a given @a hostname, @a service and @a ccache to construct credentials.
2810 * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
2812 * @retval 0 Success; Otherwise - Kerberos error codes
2814 krb5_error_code KRB5_CALLCONV
2815 krb5_mk_req(krb5_context context, krb5_auth_context *auth_context,
2816 krb5_flags ap_req_options, char *service, char *hostname,
2817 krb5_data *in_data, krb5_ccache ccache, krb5_data *outbuf);
2819 /** Format a @c KRB_AP_REQ message using supplied credentials.
2821 * @param [in] context Context structure
2822 * @param [in,out] auth_context Authentication context, containing the checksum
2823 * method to be used; a new authentication
2824 * context is returned if NULL is specified.
2825 * @param [in] ap_req_options AP_OPTS_ options
2826 * @param [in] in_data Application data's checksum to be
2827 * included in the authenticator; specify NULL
2828 * if no checksum is to be included
2829 * @param [in] in_creds Credentials for the service with valid ticket
2831 * @param [out] outbuf @c AP-REQ message
2833 * Valid @a ap_req_options are:
2834 * @li @c AP_OPTS_USE_SESSION_KEY - Use the session key when creating the
2835 * request used for user to user authentication.
2836 * @li @c AP_OPTS_MUTUAL_REQUIRED - Request a mutual authentication packet from
2838 * @li @c AP_OPTS_USE_SUBKEY - Generate a subsession key from the current
2839 * session key obtained from the credentials.
2841 * This function creates a KRB_AP_REQ message using supplied credentials
2842 * @a in_creds. The checksum @a in_data is included in the authenticator that
2843 * is part of the KRB_AP_REQ message.
2844 * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
2846 * @note A newly generated authenticator is stored in @a auth_context with the
2847 * @a client and @a checksum fields nulled out, unless an error is returned.
2848 * (This is to prevent pointer-sharing problems; the caller should not need
2849 * these fields anyway, since the caller supplied them.)
2850 * The old @a auth_context->key is overwritten by keyblock from @a in_creds.
2854 * @retval 0 Success; Otherwise - Kerberos error codes
2856 krb5_error_code KRB5_CALLCONV
2857 krb5_mk_req_extended(krb5_context context, krb5_auth_context *auth_context,
2858 krb5_flags ap_req_options, krb5_data *in_data,
2859 krb5_creds *in_creds, krb5_data *outbuf);
2861 /** Format and encrypt a @c KRB_AP_REP message.
2863 * @param [in] context Context structure
2864 * @param [in,out] auth_context Authentication context
2865 * @param [out] outbuf @c AP-REP message
2867 * The @c AP-REP message includes the data in the @a authentp field of @a
2868 * auth_context, and it is encrypted using the @a key field from @a auth_context.
2870 * When successful, @a outbuf->length and @a outbuf->data are filled in with the
2871 * length of the @c AP-REQ message and the allocated data holding it.
2873 * If the flags in @a auth_context indicate that a sequence number should be used
2874 * (either @c KRB5_AUTH_CONTEXT_DO_SEQUENCE or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE)
2875 * and the local sequence number in @a auth_context is 0, a new number will
2876 * be generated with krb5_generate_seq_number().
2878 * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
2880 * @retval 0 Success; Otherwise - Kerberos error codes
2882 krb5_error_code KRB5_CALLCONV
2883 krb5_mk_rep(krb5_context context, krb5_auth_context auth_context, krb5_data *outbuf);
2885 /** Format and encrypt a @c KRB_AP_REP message for DCE RPC.
2887 * @param [in] context Context structure
2888 * @param [in,out] auth_context Authentication context
2889 * @param [out] outbuf @c AP-REP message
2891 * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
2893 * @retval 0 Success; Otherwise - Kerberos error codes
2895 krb5_error_code KRB5_CALLCONV
2896 krb5_mk_rep_dce(krb5_context context, krb5_auth_context auth_context, krb5_data *outbuf);
2898 /** Parse and decrypt a @c KRB_AP_REP message.
2900 * @param [in] context Context structure
2901 * @param [in,out] auth_context Authentication context
2902 * @param [in] inbuf AP-REP message
2903 * @param [out] repl Decrypted reply message
2905 * This function parses, decrypts and verifies a message from @a inbuf and
2906 * fills in @a repl with a pointer to allocated memory containing the fields
2907 * from the encrypted response.
2908 * Use krb5_free_ap_rep_enc_part() to free @a repl when it is no longer needed.
2910 * @retval 0 Success; Otherwise - Kerberos error codes
2912 krb5_error_code KRB5_CALLCONV
2913 krb5_rd_rep(krb5_context context, krb5_auth_context auth_context,
2914 const krb5_data *inbuf, krb5_ap_rep_enc_part **repl);
2916 /** Parse and decrypt a @c KRB_AP_REP message for DCE RPC.
2918 * @param [in] context Context structure
2919 * @param [in,out] auth_context Authentication context
2920 * @param [in] inbuf AP-REP message
2921 * @param [out] nonce Sequence number from the decrypted reply
2923 * This function parses, decrypts and verifies a message from @a inbuf and
2924 * fills in @a nonce with a decrypted reply sequence number.
2926 * @retval 0 Success; Otherwise - Kerberos error codes
2928 krb5_error_code KRB5_CALLCONV
2929 krb5_rd_rep_dce(krb5_context context, krb5_auth_context auth_context,
2930 const krb5_data *inbuf, krb5_ui_4 *nonce);
2932 /** Format and encode a @c KRB_ERROR message.
2934 * @param [in] context Context structure
2935 * @param [in] dec_err Error structure to be encoded
2936 * @param [out] enc_err Encoded error structure
2938 * This function creates a @c KRB_ERROR message @a enc_err suitable to be
2939 * sent to the remote partner instead of sending a reply message.
2940 * Use krb5_free_data_contents() for free @a enc_err when it is no longer needed.
2942 * @retval 0 Success; Otherwise - Kerberos error codes
2944 krb5_error_code KRB5_CALLCONV
2945 krb5_mk_error(krb5_context context, const krb5_error *dec_err,
2946 krb5_data *enc_err);
2948 /** Decode a @c KRB-ERROR message.
2950 * @param [in] context Context structure
2951 * @param [in] enc_errbuf Encoded error message
2952 * @param [out] dec_error Decoded error message
2954 * This function processes @c KRB-ERROR message @a enc_errbuf and returns
2955 * an allocated structure @a dec_error containing the error message.
2956 * Use krb5_free_error() to free @a dec_error when it is no longer needed.
2958 * @retval 0 Success; Otherwise - Kerberos error codes
2960 krb5_error_code KRB5_CALLCONV
2961 krb5_rd_error(krb5_context context, const krb5_data *enc_errbuf,
2962 krb5_error **dec_error);
2964 /** Process @c KRB-SAFE message.
2966 * @param [in] context Context structure
2967 * @param [in,out] auth_context Authentication structure
2968 * @param [in] inbuf @c KRB-SAFE message to be parsed
2969 * @param [out] outbuf Data parsed from @c KRB-SAFE message
2970 * @param [out] outdata Replay data. Specify NULL if not needed
2972 * This function parses a @c KRB-SAFE message, verifies its integrity, and
2973 * stores its data into @a outbuf.
2975 * @note The @a outdata argument is required if KRB5_AUTH_CONTEXT_RET_TIME or
2976 * KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in the @a auth_context.`
2978 * @note The @a remote_addr argument in @a auth_context argument is mandatory.
2979 * It specifies the address of the sender. This address will be used
2980 * to verify the sender address in the KRB-SAFE message.
2982 * The keyblock used to verify the integrity of the message is taken from the
2983 * fields @a recv_subkey or @a key in @a auth_context.
2984 * The keyblock is chosen in the preceding order by the first one that is non-null.
2986 * @a remote_addr and @a localaddr in @a auth_context specify
2987 * the full addresses (host and port) of the sender and receiver, and must be of
2988 * type @c ADDRTYPE_ADDRPORT.
2990 * If @a local_addr is non-null, then the address of the receiver in the message
2991 * must match it. Otherwise, the receiver address in the message will be checked
2992 * against the list of local addresses as returned by krb5_os_localaddr().
2993 * If the check fails, an error is returned.
2995 * If KRB5_AUTH_CONTEXT_DO_SEQUENCE flag is set in @a auth_context
2996 * the @a remote_seq_number field of @a auth_context is compared to the
2997 * sequence number for the message, and error is returned
2998 * if it does not match. Otherwise, the sequence number is not used.
3000 * If KRB5_AUTH_CONTEXT_DO_TIME flag is set in @a auth_context,
3001 * then two additional checks are performed:
3002 * @li The timestamp in the message must be within the permitted clock skew
3003 * (which is usually five minutes), or error is returned.
3004 * @li The message must not be a replayed message field in @a auth_context.
3006 * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
3008 * @retval 0 Success; Otherwise - Kerberos error codes
3010 krb5_error_code KRB5_CALLCONV
3011 krb5_rd_safe(krb5_context context, krb5_auth_context auth_context,
3012 const krb5_data *inbuf, krb5_data *outbuf,
3013 krb5_replay_data *outdata);
3015 /** Process a @c KRB-PRIV message.
3017 * @param [in] context Context structure
3018 * @param [in,out] auth_context Authentication structure
3019 * @param [in] inbuf @c KRB-PRIV message to be parsed
3020 * @param [out] outbuf Data parsed from @c KRB-PRIV message
3021 * @param [out] outdata Replay data. Specify NULL if not needed
3023 * This function parses a @c KRB-PRIV message, verifies its integrity, and
3024 * stores its data into @a outbuf.
3026 * @note If the @c KRB5_AUTH_CONTEXT_RET_TIME or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE
3027 * flag is set in @a auth_context, the @a outdata is required.
3029 * @note The @a remote_addr argument in @a auth_context argument is mandatory.
3030 * It specifies the address of the sender. This address will be used
3031 * to verify the sender address in the KRB-SAFE message.
3033 * The keyblock used to decrypt the data and verify the integrity of the message
3034 * is taken from fields @a recv_subkey or @a key in @a auth_context.
3035 * The keyblock is chosen in the preceding order by the first one that is non-null.
3037 * If @c local_addr field of @a auth_context is non-null, the address of the
3038 * receiver in the message must match it. Otherwise, the receiver address in the
3039 * message will be checked against the list of local addresses as returned by
3040 * krb5_os_localaddr().
3042 * If the @a i_vector field in @a auth_context is non-null, it is used as an
3043 * initialization vector for the decryption (if the encryption type of
3044 * the message supports initialization vectors) and its contents are replaced
3045 * with the last block of encrypted data in the message.
3047 * If KRB5_AUTH_CONTEXT_DO_SEQUENCE flag is set in @a auth_context
3048 * the @a remote_seq_number field of @a auth_context is compared to the
3049 * sequence number for the message, and error is returned
3050 * if it does not match. Otherwise, the sequence number is not used.
3052 * @retval 0 Success; Otherwise - Kerberos error codes
3054 krb5_error_code KRB5_CALLCONV
3055 krb5_rd_priv(krb5_context context, krb5_auth_context auth_context,
3056 const krb5_data *inbuf, krb5_data *outbuf,
3057 krb5_replay_data *outdata);
3059 /** Convert a single-string principal name to a krb5_principal structure.
3061 * @param [in] context Context structure
3062 * @param [in] name Single string representation of a principal name
3063 * @param [out] nprincipal Principal
3065 * Convert a single-string representation of a principal name to a
3066 * krb5_principal structure.
3068 * A single-string representation of a Kerberos name consists of one
3069 * or more principal name components, separated by slashes, optionally followed by
3070 * the \@ character and a realm name.
3071 * If the realm name is not specified, the local realm is used.
3073 * To use the slash and \@ symbols as part of a component (quoted)
3074 * instead of using them as a component separator or as a realm prefix),
3075 * put a backslash (\) character in front of the symbol.
3076 * Similarly, newline, tab, backspace, and NULL characters
3077 * can be included in a component by using @a n, @a t,@a b or @a 0, respectively.
3079 * @note The realm in a Kerberos @a name cannot contain slash, colon,
3080 * or NULL characters.
3082 * Use krb5_free_principal() to free @a nprincipal when it is no longer needed.
3087 * Kerberos error codes
3089 krb5_error_code KRB5_CALLCONV
3090 krb5_parse_name(krb5_context context, const char *name, krb5_principal *nprincipal);
3092 #define KRB5_PRINCIPAL_PARSE_NO_REALM 0x1 /**< Error if realm is present */
3093 #define KRB5_PRINCIPAL_PARSE_REQUIRE_REALM 0x2 /**< Error if realm is not present */
3094 #define KRB5_PRINCIPAL_PARSE_ENTERPRISE 0x4 /**< Create single-component
3095 enterprise principle */
3097 /** Convert a single-string principal name to a krb5_principal with restrictions.
3099 * @param [in] context Context structure
3100 * @param [in] name Single string representation of a principal name
3101 * @param [in] flags Flag
3102 * @param [out] nprincipal Principal
3104 * Similar to krb5_parse_name(), this function converts a single-string
3105 * representation of a principal name to a krb5_principal structure;
3106 * takes the additional flags.
3108 * The following flags are valid:
3109 * @li @c KRB5_PRINCIPAL_PARSE_NO_REALM - no realm must be present in @a name
3110 * @li @c KRB5_PRINCIPAL_PARSE_MUST_REALM - realm must be present in @a name
3111 * @li @c KRB5_PRINCIPAL_PARSE_ENTERPRISE - Create single-component enterprise principal
3113 * Use krb5_free_principal() to free @a nprincipal when it is no longer needed.
3118 * Kerberos error codes
3120 krb5_error_code KRB5_CALLCONV
3121 krb5_parse_name_flags(krb5_context context, const char *name,
3122 int flags, krb5_principal *nprincipal);
3124 /** Convert a krb5_principal structure to a single-string representation.
3126 * @param [in] context Context structure
3127 * @param [in] principal Principal
3128 * @param [out] name Single string representation of a Kerberos principal name
3130 * The resulting single-string representation uses the format and quoting conventions
3131 * described for krb5_parse_name().
3133 * Use krb5_free_unparsed_name() to free @a name when it is no longer needed.
3138 * Kerberos error codes
3140 krb5_error_code KRB5_CALLCONV
3141 krb5_unparse_name(krb5_context context, krb5_const_principal principal,
3142 register char **name);
3144 /** Convert krb5_principal structure to string format.
3146 * @param [in] context Context structure
3147 * @param [in] principal Principal
3148 * @param [out] name Single string format of principal name
3149 * @param [out] size Size of unparsed name buffer
3151 * @sa krb5_unparse_name()
3156 * Kerberos error codes. On failure @a name is set to NULL
3158 krb5_error_code KRB5_CALLCONV
3159 krb5_unparse_name_ext(krb5_context context, krb5_const_principal principal,
3160 char **name, unsigned int *size);
3162 #define KRB5_PRINCIPAL_UNPARSE_SHORT 0x1 /**< Omit realm if it is the local realm */
3163 #define KRB5_PRINCIPAL_UNPARSE_NO_REALM 0x2 /**< Omit realm always */
3164 #define KRB5_PRINCIPAL_UNPARSE_DISPLAY 0x4 /**< Don't escape special characters */
3166 /** Convert krb5_principal structure to a single-string with restrictions.
3168 * @param [in] context Context structure
3169 * @param [in] principal Principal
3170 * @param [in] flags Flags
3171 * @param [out] name Single string representation of a Kerberos principal name
3173 * Similar to krb5_unparse_name(), this function converts a krb5_principal structure
3174 * to a single-string representation; takes the additional flags.
3176 * The following flags are valid:
3177 * @li @c KRB5_PRINCIPAL_UNPARSE_SHORT - omit realm if it is the local realm
3178 * @li @c KRB5_PRINCIPAL_UNPARSE_NO_REALM - omit realm in the principal name @a name
3179 * @li @c KRB5_PRINCIPAL_UNPARSE_DISPLAY - no quoting in the principal name @a name
3181 * Use krb5_free_unparsed_name() to free @a name when it is no longer needed.
3186 * Kerberos error codes. On failure @a name is set to NULL
3188 krb5_error_code KRB5_CALLCONV
3189 krb5_unparse_name_flags(krb5_context context, krb5_const_principal principal,
3190 int flags, char **name);
3192 /** Convert krb5_principal structure to string format with restrictions.
3194 * @param [in] context Context structure
3195 * @param [in] principal Principal
3196 * @param [in] flags Flags
3197 * @param [out] name Single string format of principal name
3198 * @param [out] size Size of unparsed name buffer
3200 * @sa krb5_unparse_name() krb5_unparse_name_flags() krb5_unparse_name_ext()
3205 * Kerberos error codes. On failure @a name is set to NULL
3207 krb5_error_code KRB5_CALLCONV
3208 krb5_unparse_name_flags_ext(krb5_context context, krb5_const_principal principal,
3209 int flags, char **name, unsigned int *size);
3211 /** Set the realm in the current context.
3213 * @param [in,out] context Context structure
3214 * @param [in] principal Principal name
3215 * @param [in] realm Realm name
3217 * Set the realm name part of @a principal to @a realm.
3219 * @note This function frees the previous realm of @a principal.
3224 * Kerberos error codes
3226 krb5_error_code KRB5_CALLCONV
3227 krb5_set_principal_realm(krb5_context context, krb5_principal principal,
3230 /** Search a list of addresses for a specified address.
3232 * @param context Context structure
3233 * @param [in] addr Address to search for
3234 * @param [in] addrlist Address list to be searched.
3235 * Specify NULL if there is no address list
3237 * @note If @a addrlist contains only a NetBIOS addresses,
3238 * it will be treated as empty list.
3241 * TRUE if @a addr is listed in @a addrlist, or @c addrlist is NULL; FALSE otherwise
3243 krb5_boolean KRB5_CALLCONV_WRONG
3244 krb5_address_search(krb5_context context, const krb5_address *addr,
3245 krb5_address *const *addrlist);
3247 /** Compare two Kerberos addresses.
3249 * @param context Context structure
3250 * @param [in] addr1 First address to be compared
3251 * @param [in] addr2 Second address to be compared
3254 * TRUE if the addresses are the same, FALSE otherwise
3256 krb5_boolean KRB5_CALLCONV
3257 krb5_address_compare(krb5_context context, const krb5_address *addr1,
3258 const krb5_address *addr2);
3260 /** Return an ordering of the specified addresses.
3262 * @param context Context structure
3263 * @param [in] addr1 First address
3264 * @param [in] addr2 Second address
3267 * 0 The two addresses are the same
3269 * \< 0 First address is less than second
3271 * \> 0 First address is greater than second
3274 krb5_address_order(krb5_context context, const krb5_address *addr1,
3275 const krb5_address *addr2);
3277 /** Compare the realms of two principals.
3279 * @param [in] context Context structure
3280 * @param [in] princ1 First principal
3281 * @param [in] princ2 Second principal
3284 * TRUE if the realm names are the same; FALSE otherwise
3286 krb5_boolean KRB5_CALLCONV
3287 krb5_realm_compare(krb5_context context, krb5_const_principal princ1,
3288 krb5_const_principal princ2);
3290 /** Compare two principals.
3292 * @param [in] context Context structure
3293 * @param [in] princ1 First principal
3294 * @param [in] princ2 Second principal
3297 * TRUE if the principals are the same; FALSE otherwise
3299 krb5_boolean KRB5_CALLCONV
3300 krb5_principal_compare(krb5_context context,
3301 krb5_const_principal princ1,
3302 krb5_const_principal princ2);
3304 /** Compare two principals ignoring realm components.
3306 * @param [in] context Context structure
3307 * @param [in] princ1 First principal
3308 * @param [in] princ2 Second principal
3310 * Similar to krb5_principal_compare() but do not compare the realm
3311 * components of the principals
3314 * TRUE if the principals are the same; FALSE otherwise
3316 krb5_boolean KRB5_CALLCONV
3317 krb5_principal_compare_any_realm(krb5_context context,
3318 krb5_const_principal princ1,
3319 krb5_const_principal princ2);
3321 #define KRB5_PRINCIPAL_COMPARE_IGNORE_REALM 1 /**< ignore realm component */
3322 #define KRB5_PRINCIPAL_COMPARE_ENTERPRISE 2 /**< UPNs as real principals */
3323 #define KRB5_PRINCIPAL_COMPARE_CASEFOLD 4 /**< case-insensitive */
3324 #define KRB5_PRINCIPAL_COMPARE_UTF8 8 /**< treat principals as UTF-8 */
3326 /** Compare two principals with additional flags.
3328 * @param [in] context Context structure
3329 * @param [in] princ1 First principal
3330 * @param [in] princ2 Second principal
3331 * @param [in] flags Flags
3334 * @li @c KRB5_PRINCIPAL_COMPARE_IGNORE_REALM - ignore realm component
3335 * @li @c KRB5_PRINCIPAL_COMPARE_ENTERPRISE - UPNs as real principals
3336 * @li @c KRB5_PRINCIPAL_COMPARE_CASEFOLD case-insensitive
3337 * @li @c KRB5_PRINCIPAL_COMPARE_UTF8 - treat principals as UTF-8
3339 * @sa krb5_principal_compare()
3342 * TRUE if the principal names are the same; FALSE otherwise
3344 krb5_boolean KRB5_CALLCONV
3345 krb5_principal_compare_flags(krb5_context context,
3346 krb5_const_principal princ1,
3347 krb5_const_principal princ2,
3350 /** Initialize an empty @c _krb5_keyblock.
3352 * @param [in] context Context structure
3353 * @param [in] enctype Encryption type
3354 * @param [in] length Length of keyblock
3355 * @param [out] out Pointer to empty keyblock
3357 * Initialize a new keyblock and allocate storage
3358 * for the contents of the key, which will be freed along
3359 * with the keyblock when krb5_free_keyblock is called.
3360 * It is legal to pass in a length of 0, in which
3361 * case contents are left unallocated.
3362 * Use krb5_free_keyblock() to free @a out when it is no longer needed.
3364 * @note If @a length is set to 0, contents are left unallocated.
3366 * @retval 0 Success; Otherwise - Kerberos error codes
3368 krb5_error_code KRB5_CALLCONV
3369 krb5_init_keyblock(krb5_context context, krb5_enctype enctype,
3370 size_t length, krb5_keyblock **out);
3372 /** Copy a keyblock.
3374 * @param [in] context Context structure
3375 * @param [in] from Keyblock to be copied
3376 * @param [out] to Copy of keyblock @a from
3378 * This function copies the content of @a from to @a to
3379 * Use krb5_free_keyblock() to free @a to when it is no longer needed.
3381 * @retval 0 Success; Otherwise - Kerberos error codes
3383 krb5_error_code KRB5_CALLCONV
3384 krb5_copy_keyblock(krb5_context context, const krb5_keyblock *from,
3385 krb5_keyblock **to);
3387 /** Copy the contents of a keyblock.
3389 * @param [in] context Context structure
3390 * @param [in] from Key to be copied
3391 * @param [out] to Output key
3393 * This function copies @a from->contents to @a to.
3394 * Use krb5_free_keyblock_contents() to zero out and free @a to
3395 * when it is no longer needed.
3397 * @retval 0 Success; Otherwise - Kerberos error codes
3399 krb5_error_code KRB5_CALLCONV
3400 krb5_copy_keyblock_contents(krb5_context context, const krb5_keyblock *from,
3403 /** Copy a krb5_creds structure.
3405 * @param [in] context Context structure
3406 * @param [in] incred Credentials structure to be copied
3407 * @param [out] outcred Copy of @a incred
3409 * This function copies the content of @a incred to @a outcred
3410 * Use krb5_free_creds() to free @a outcred when it is no longer needed.
3412 * @retval 0 Success; Otherwise - Kerberos error codes
3414 krb5_error_code KRB5_CALLCONV
3415 krb5_copy_creds(krb5_context context, const krb5_creds *incred, krb5_creds **outcred);
3417 /** Copy a krb5_data object.
3419 * @param [in] context Context structure
3420 * @param [in] indata Data object to be copied
3421 * @param [out] outdata Copy of @a indata
3423 * This function copies the content of @a indata to @a outdata
3424 * Use krb5_free_data() to free @a outdata when it is no longer needed.
3426 * @retval 0 Success; Otherwise - Kerberos error codes
3428 krb5_error_code KRB5_CALLCONV
3429 krb5_copy_data(krb5_context context, const krb5_data *indata, krb5_data **outdata);
3431 /** Copy a principal.
3433 * @param [in] context Context structure
3434 * @param [in] inprinc Principal to be copied
3435 * @param [out] outprinc Copy of @a inprinc
3437 * This function copies the content of @a inprinc to @a outprinc
3438 * Use krb5_free_principal() to free @a outprinc when it is no longer needed.
3440 * @retval 0 Success; Otherwise - Kerberos error codes
3442 krb5_error_code KRB5_CALLCONV
3443 krb5_copy_principal(krb5_context context, krb5_const_principal inprinc,
3444 krb5_principal *outprinc);
3446 /** Copy an array of addresses.
3448 * @param [in] context Context structure
3449 * @param [in] inaddr Array of addresses to be copied
3450 * @param [out] outaddr Copy of array of addresses
3452 * This function copies the content of @a inaddr to @a outaddr.
3453 * Use krb5_free_addresses() to free @a outaddr when it is no longer needed.
3455 * @retval 0 Success; Otherwise - Kerberos error codes
3457 krb5_error_code KRB5_CALLCONV
3458 krb5_copy_addresses(krb5_context context, krb5_address *const *inaddr,
3459 krb5_address ***outaddr);
3461 /** Copy a krb5_ticket structure.
3463 * @param [in] context Context structure
3464 * @param [in] from Ticket to be copied
3465 * @param [out] pto Copy of ticket
3467 * This function copies the content of @a from to @a pto
3468 * Use krb5_free_ticket() to free @a pto when it is no longer needed.
3470 * @retval 0 Success; Otherwise - Kerberos error codes
3472 krb5_error_code KRB5_CALLCONV
3473 krb5_copy_ticket(krb5_context context, const krb5_ticket *from, krb5_ticket **pto);
3475 /** Copy an array of authorization data structures.
3477 * @param [in] context Context structure
3478 * @param [in] in_authdat Array of @a krb5_authdata structures
3479 * @param [out] out New array of @a krb5_authdata structures
3481 * This function copies the content of @a in_authdat to @a out
3482 * Use krb5_free_authdata() to free @a out when it is no longer needed.
3484 * @note The last array entry in @a in_authdat must be a NULL pointer.
3486 * @retval 0 Success; Otherwise - Kerberos error codes
3488 krb5_error_code KRB5_CALLCONV
3489 krb5_copy_authdata(krb5_context context,
3490 krb5_authdata *const *in_authdat, krb5_authdata ***out);
3492 /** Merge two authdata arrays with fresh allocation.
3494 * @param [in] context Context structure
3495 * @param [in] inauthdat1 1st array of @a krb5_authdata structures
3496 * @param [in] inauthdat2 2d array of @a krb5_authdata structures
3497 * @param [out] outauthdat New array of @a krb5_authdata structures
3499 * Merge two authdata arrays, such as the array from a ticket
3500 * and authenticator.
3501 * Use krb5_free_authdata() to free @a outauthdat when it is no longer needed.
3503 * @note The last array entry in @a inauthdat1 and @a inauthdat2
3504 * must be a NULL pointer.
3506 * @retval 0 Success; Otherwise - Kerberos error codes
3508 krb5_error_code KRB5_CALLCONV
3509 krb5_merge_authdata(krb5_context context,
3510 krb5_authdata *const *inauthdat1,
3511 krb5_authdata * const *inauthdat2,
3512 krb5_authdata ***outauthdat);
3514 /** Copy a krb5_authenticator srtucture.
3516 * @param [in] context Context structure
3517 * @param [in] authfrom krb5_authenticator structure to be copied
3518 * @param [out] authto Copy of krb5_authenticator structure
3520 * This function copies the content of @a authfrom to @a authto
3521 * Use krb5_free_authenticator() to free @a authto when it is no longer needed.
3523 * @retval 0 Success; Otherwise - Kerberos error codes
3525 krb5_error_code KRB5_CALLCONV
3526 krb5_copy_authenticator(krb5_context context, const krb5_authenticator *authfrom,
3527 krb5_authenticator **authto);
3529 /** Copy a krb5_checksum structure.
3531 * @param [in] context Context structure
3532 * @param [in] ckfrom Checksum to be copied
3533 * @param [out] ckto Copy of krb5_checksum structure
3535 * This function copies the content of @a ckfrom to @a ckto
3536 * Use krb5_free_checksum() to free @a ckto when it is no longer needed.
3538 * @retval 0 Success; Otherwise - Kerberos error codes
3540 krb5_error_code KRB5_CALLCONV
3541 krb5_copy_checksum(krb5_context context, const krb5_checksum *ckfrom,
3542 krb5_checksum **ckto);
3544 /** Generate a replay cache object for server use and open it.
3546 * @param [in] context Context structure
3547 * @param [in] piece Unique identifier for replay cache
3548 * @param [out] rcptr Handle to an open rcache
3550 * This function generates a replay cache name, allocates memory for its
3551 * handle @a rcptr, and then opens it. Unique identifier @a piece is used
3552 * to differentiate this replay cache from the others on the system and
3553 * typically it is the first component of the principal name of the caller.
3554 * The handle @a rcptr should be closed with krb5_rc_close().
3555 * Use krb5_rc_destroy() to destroy @a rcptr when it is no longer needed.
3557 * @retval 0 Success; Otherwise - Kerberos error codes
3559 krb5_error_code KRB5_CALLCONV
3560 krb5_get_server_rcache(krb5_context context, const krb5_data *piece,
3561 krb5_rcache *rcptr);
3563 /** Build a principal name using length-counted strings.
3565 * @param [in] context Context structure
3566 * @param [out] princ Principal name
3567 * @param [in] rlen Realm name length
3568 * @param [in] realm Realm name
3569 * @param [in] ... List of arguments specifying length and content for each argument
3571 * Call krb5_free_principal() to free allocated memory for principal when it is no longer needed.
3573 * @note krb5_build_principal() and krb5_build_principal_va() perform the same task.
3574 * krb5_build_principal() takes variadic arguments.
3575 * krb5_build_principal_va() takes a pre-computed @a varargs pointer.
3578 * Example of how to build principal WELLKNOWN/ANONYMOUS@R
3579 * krb5_build_principal_ext(context, &principal, strlen("R"), "R",
3580 * strlen(KRB5_WELLKNOWN_NAMESTR), KRB5_WELLKNOWN_NAMESTR,
3581 * strlen(KRB5_ANONYMOUS_PRINCSTR), KRB5_ANONYMOUS_PRINCSTR, 0);
3587 * Kerberos error codes
3589 krb5_error_code KRB5_CALLCONV_C
3590 krb5_build_principal_ext(krb5_context context, krb5_principal * princ,
3591 unsigned int rlen, const char * realm, ...);
3593 /** Build a principal name using null-terminated strings.
3595 * @param [in] context Context structure
3596 * @param [out] princ Principal name
3597 * @param [in] rlen Realm name length
3598 * @param [in] realm Realm name
3599 * @param [in] ... List of len1, sl1, len2, sl2...
3601 * Call krb5_free_principal() to free @a princ when it is no longer needed.
3603 * @note krb5_build_principal() and krb5_build_principal_va() perform the same task.
3604 * krb5_build_principal() takes variadic arguments.
3605 * krb5_build_principal_va() takes a pre-computed @a varargs pointer.
3608 * Example of how to build principal H/S@R
3609 * krb5_build_principal(context, &principal,
3610 * strlen("R"), "R", "H", "S", (char*)NULL);
3616 * Kerberos error codes
3618 krb5_error_code KRB5_CALLCONV_C
3619 krb5_build_principal(krb5_context context,
3620 krb5_principal * princ,
3622 const char * realm, ...)
3624 __attribute__ ((sentinel))
3629 * @param [in] context Context structure
3630 * @param [out] princ Principal structure
3631 * @param [in] rlen Realm name length
3632 * @param [in] realm Realm name
3633 * @param [in] ap @c va_list of argument
3635 * @deprecated Replaced by krb5_build_principal() and krb5_build_principal_va().
3637 * Build a principal name, using a precomputed @c va_list.
3639 * @note krb5_build_principal() and krb5_build_principal_va() perform the same task.
3640 * krb5_build_principal() takes variadic arguments.
3641 * krb5_build_principal_va() takes a pre-computed @a varargs pointer.
3643 * Use krb5_free_principal() to free @a princ when it is no longer needed.
3645 * @retval 0 Success; otherwise - Kerberos error codes
3647 KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
3648 krb5_build_principal_va(krb5_context context,
3649 krb5_principal princ,
3655 /** Build a principal name, using a precomputed variable argument list
3657 * @param [in] context Context structure
3658 * @param [out] princ Principal structure. Locally allocated.
3659 * @param [in] rlen Realm name length
3660 * @param [in] realm Realm name
3661 * @param [in] ap @c va_list of arguments
3663 * Similar to krb5_build_principal() this function builds a principal name,
3664 * but its name components are specified as va_list.
3666 * Use krb5_free_principal() to deallocate the @a princ when it is no longer needed.
3669 * Function usage example:
3671 * va_start(ap, realm);
3672 * krb5_build_principal_alloc_va(context, princ, rlen, realm, ap);
3679 * Kerberos error codes
3681 krb5_error_code KRB5_CALLCONV
3682 krb5_build_principal_alloc_va(krb5_context context,
3683 krb5_principal *princ,
3688 /** Convert a Kerberos V4 principal to a Kerberos V5 principal.
3690 * @param [in] context Context structure
3691 * @param [in] name V4 name
3692 * @param [in] instance V4 instance
3693 * @param [in] realm Realm
3694 * @param [out] princ V5 principal
3696 * This function builds a @a princ from V4 specification based on given input.
3697 * @a name.instance@realm.
3699 * Use krb5_free_principal() to free @a princ when it is no longer needed.
3701 * @retval 0 Success; Otherwise - Kerberos error codes
3703 krb5_error_code KRB5_CALLCONV
3704 krb5_425_conv_principal(krb5_context context, const char *name,
3705 const char *instance, const char *realm,
3706 krb5_principal *princ);
3708 /** Convert a Kerberos V5 principal to a Kerberos V4 principal.
3710 * @param [in] context Context structure
3711 * @param [in] princ V5 Principal
3712 * @param [out] name V4 principal's name to be filled in
3713 * @param [out] inst V4 principal's instance name to be filled in
3714 * @param [out] realm Principal's realm name to be filled in
3716 * This function separates a V5 principal @a princ into @a name, @a instance, and @a realm.
3721 * KRB5_INVALID_PRINCIPAL Invalid principal name
3723 * KRB5_CONFIG_CANTOPEN Can't open or find Kerberos configuration file
3725 * Kerberos error codes
3727 krb5_error_code KRB5_CALLCONV
3728 krb5_524_conv_principal(krb5_context context, krb5_const_principal princ,
3729 char *name, char *inst, char *realm);
3735 /** Convert a Kerberos V5 credentials to a Kerberos V4 credentials
3737 * @note Not implemented
3739 * @retval KRB524_KRB4_DISABLED (always)
3742 krb5_524_convert_creds(krb5_context context, krb5_creds *v5creds,
3743 struct credentials *v4creds);
3746 #define krb524_convert_creds_kdc krb5_524_convert_creds
3747 #define krb524_init_ets(x) (0)
3752 /** Get a handle for a key table.
3754 * @param [in] context Context structure
3755 * @param [in] name Name of the key table
3756 * @param [out] ktid Key table handle
3758 * Resolve the key table name @a name and fill in a handle identifying the key table.
3759 * The key table is not opened.
3761 * @note @a name must be of the form @c type:residual, where @a type must be a type known
3762 * to the library and @a residual portion should be specific to the particular keytab type.
3764 * @sa krb5_kt_close()
3767 * Example: krb5_kt_resolve(context, "FILE:/tmp/filename",&ktid);
3773 * Kerberos error codes
3775 krb5_error_code KRB5_CALLCONV
3776 krb5_kt_resolve(krb5_context context, const char *name, krb5_keytab *ktid);
3778 /** Get default key table name.
3780 * @param [in] context Context structure
3781 * @param [in,out] name Key table name to be resolved
3782 * @param [in] name_size Size of @a name to return
3784 * Fill @a name with the first @a name_size bytes of the name of the
3785 * default key table for the current user. The name is obtained either
3786 * from the environment variable KRB5_KTNAME or from @a default_keytab_name
3787 * entry in @a libdefaults section of krb5 configuration file or
3788 * falls back on the default keytab name for the OS.
3790 * @sa MAX_KEYTAB_NAME_LEN
3795 * KRB5_CONFIG_NOTENUFSPACE Buffer is too short
3797 * Kerberos error codes
3799 krb5_error_code KRB5_CALLCONV
3800 krb5_kt_default_name(krb5_context context, char *name, int name_size);
3802 /** Resolve default key table.
3804 * @param [in] context Context structure
3805 * @param [in,out] id Key table handle
3807 * Fill @a keytab with the default key table's @a handle.
3812 * Kerberos error codes
3814 krb5_error_code KRB5_CALLCONV
3815 krb5_kt_default(krb5_context context, krb5_keytab *id);
3817 /** Free the contents of a key table entry.
3819 * @param [in] context Context structure
3820 * @param [in] entry Key table entry whose contents are to be freed
3822 * @note The pointer is not freed.
3824 * @retval 0 Success; Otherwise - Kerberos error codes
3826 krb5_error_code KRB5_CALLCONV
3827 krb5_free_keytab_entry_contents(krb5_context context, krb5_keytab_entry *entry);
3829 /** Free the contents of a key table entry.
3831 * @param [in] context Context structure
3832 * @param [in] entry Key table entry to be freed
3834 * @warning Use krb5_free_keytab_entry_contents instead; this does the same
3835 * thing but is misnamed and retained for backward compatability.
3837 krb5_error_code KRB5_CALLCONV
3838 krb5_kt_free_entry(krb5_context context, krb5_keytab_entry *entry);
3841 /* remove and add are functions, so that they can return NOWRITE
3842 if not a writable keytab */
3844 /** Remove an entry from a key table.
3846 * @param [in] context Context structure
3847 * @param [in] id Key table handle
3848 * @param [in] entry Entry to remove from key table
3853 * KRB5_KT_NOWRITE Key table is not writable
3855 * Kerberos error codes
3857 krb5_error_code KRB5_CALLCONV
3858 krb5_kt_remove_entry(krb5_context context, krb5_keytab id, krb5_keytab_entry *entry);
3860 /** Add a new entry to a key table.
3862 * @param [in] context Context structure
3863 * @param [in] id Key table handle
3864 * @param [in] entry Entry to be added
3869 * ENOMEM Insufficient memory
3871 * KRB5_KT_NOWRITE Key table is not writeable
3873 * Kerberos error codes
3875 krb5_error_code KRB5_CALLCONV
3876 krb5_kt_add_entry(krb5_context context, krb5_keytab id, krb5_keytab_entry *entry);
3878 /** Convert a principal name into the default salt for that principal.
3880 * @param [in] context Context structure
3881 * @param [in] pr Principal name
3882 * @param [out] ret Default salt for @a pr to be filled in
3884 * @retval 0 Success; Otherwise - Kerberos error codes
3886 krb5_error_code KRB5_CALLCONV_WRONG
3887 krb5_principal2salt(krb5_context context,
3888 register krb5_const_principal pr, krb5_data *ret);
3889 /* librc.spec--see rcache.h */
3893 /** Resolve a credentials cache name.
3895 * @param [in] context Context structure
3896 * @param [in] name Credentials cache name to be resolved
3897 * @param [out] cache Credentials cache handle
3899 * Fills in @a cache with a @a cache handle that corresponds to the name in @a name.
3900 * @a name should be of the form @c type:residual,
3901 * and @a type must be a type known to the library.
3902 * If the @a name does not contain a colon, interpret it as a file name.
3905 * Example: krb5_cc_resolve(context, "MEMORY:C_", &cache);
3911 * Kerberos error codes
3913 krb5_error_code KRB5_CALLCONV
3914 krb5_cc_resolve(krb5_context context, const char *name, krb5_ccache *cache);
3916 /** Duplicate ccache handle.
3918 * @param [in] context Context structure
3919 * @param [in] in Credentials cache handle to be duplicated
3920 * @param [out] out Credentials cache handle
3922 * Create a new handle referring to the same cache as @a in.
3923 * The new handle and @a in can be closed independently.
3925 krb5_error_code KRB5_CALLCONV
3926 krb5_cc_dup(krb5_context context, krb5_ccache in, krb5_ccache *out);
3928 /** Return the name of the default credentials cache.
3930 * @param [in] context Context structure
3932 * Try the environment variable KRB5CCNAME first then, if it is not set,
3933 * fall back on the default ccache name for the OS.
3936 * Name of default credentials cache for the current user.
3938 const char *KRB5_CALLCONV
3939 krb5_cc_default_name(krb5_context context);
3941 /** Set the default credentials cache name.
3943 * @param [in,out] context Context structure
3944 * @param [in] name Default credentials cache name
3946 * This function frees the old default credentials cache name and then
3947 * sets it to @a name.
3952 * KV5M_CONTEXT Bad magic number for @c _krb5_context structure
3954 * Kerberos error codes
3956 krb5_error_code KRB5_CALLCONV
3957 krb5_cc_set_default_name(krb5_context context, const char *name);
3959 /** Resolve the default crendentials cache name.
3961 * @param [in,out] context Context structure
3962 * @param [out] ccache Pointer to credentials cache name
3967 * KV5M_CONTEXT Bad magic number for @c _krb5_context structure
3969 * KRB5_FCC_INTERNAL The name of the default credentials cache cannot be obtained
3971 * Kerberos error codes
3973 krb5_error_code KRB5_CALLCONV
3974 krb5_cc_default(krb5_context context, krb5_ccache *ccache);
3976 /** Copy a credentials cache.
3978 * @param [in] context Context structure
3979 * @param [in] incc Credentials cache to be copied
3980 * @param [out] outcc Copy of credentials cache to be filled in
3982 * @retval 0 Success; Otherwise - Kerberos error codes
3984 krb5_error_code KRB5_CALLCONV
3985 krb5_cc_copy_creds(krb5_context context, krb5_ccache incc, krb5_ccache outcc);
3987 /** Get some configuration for the credential cache in the cache.
3989 * @param [in] context Context structure
3990 * @param [in] id The credential cache to store the data for
3991 * @param [in] principal Configuration for this principal;
3992 * if NULL, global for the whole cache.
3993 * @param [in] key Name under which the configuraion is stored
3994 * @param [in,out] data Data to be fetched; free with krb5_free_data_contents()
3999 * Kerberos error codes
4001 krb5_error_code KRB5_CALLCONV
4002 krb5_cc_get_config(krb5_context context, krb5_ccache id,
4003 krb5_const_principal principal,
4004 const char *key, krb5_data *data);
4006 /** Store some configuration for the credential cache in the cache.
4008 * @param [in,out] context a Keberos context
4009 * @param [in] id the credential cache to store the data for.
4010 * @param [in] principal configuration for a specific principal;
4011 * if NULL, global for the whole cache.
4012 * @param [in] key name under which the configuraion is stored.
4013 * @param [in] data data to store. If NULL, old configuration is removed.
4015 * @note Existing configuration under the same key is over-written.
4017 * @warning Before version 1.10 @a data was assumed to be always non-zero
4022 * Kerberos error codes
4024 krb5_error_code KRB5_CALLCONV
4025 krb5_cc_set_config(krb5_context context, krb5_ccache id,
4026 krb5_const_principal principal,
4027 const char *key, krb5_data *data);
4029 /** Test whether a principal is a configuration principal.
4031 * @param [in] context a Keberos context
4032 * @param [in] principal principal to check if it a configuration principal
4035 * TRUE (non zero) if the principal is a configuration principal
4036 * (generated part of krb5_cc_set_config()); FALSE (zero) otherwise.
4038 krb5_boolean KRB5_CALLCONV
4039 krb5_is_config_principal(krb5_context context, krb5_const_principal principal);
4042 /** Free the storage assigned to a principal.
4044 * @param [in] context Context structure
4045 * @param [in] val Principal to be freed
4048 krb5_free_principal(krb5_context context, krb5_principal val);
4050 /** Free a krb5_authenticator structure.
4052 * @param context Context structure
4053 * @param [in] val Pointer to authenticator structure to be freed
4055 * This function frees the storage assigned to @a krb5_authenticator
4056 * structure, and then @a val itself is released.
4059 krb5_free_authenticator(krb5_context context, krb5_authenticator *val);
4061 /** Free the data stored in array of addresses.
4063 * @param context Context structure
4064 * @param [in] val Array of addresses to be freed
4066 * This function frees the storage assigned to array of @a krb5_address
4067 * structures, and then @a val itself is released.
4069 * @note The last entry in the array must be a NULL pointer.
4072 krb5_free_addresses(krb5_context context, krb5_address **val);
4074 /** Free the storage assigned to array of authentication data.
4076 * @param context Context structure
4077 * @param [in] val Array of authentication data to be freed
4079 * This function frees the storage assigned to array of @a krb5_authdata
4080 * structures, and then @a val itself is released.
4082 * @note The last entry in the array must be a NULL pointer.
4085 krb5_free_authdata(krb5_context context, krb5_authdata **val);
4089 * @param [in] context Context structure
4090 * @param [in] val Ticket to be freed
4092 * This function frees the storage assigned to @a krb5_ticket
4093 * structure, and then @a val itself is released.
4096 krb5_free_ticket(krb5_context context, krb5_ticket *val);
4098 /** Free an error allocated by either krb5_read_error() or krb5_sendauth().
4100 * @param [in] context Context structure
4101 * @param [in] val Error data structure to be freed
4103 * This function frees the storage assigned to @a krb5_error
4104 * structure, and then @a val itself is released.
4107 krb5_free_error(krb5_context context, register krb5_error *val);
4109 /** Free a credentials structure and invalidate its pointer.
4111 * @param [in] context Context structure
4112 * @param [in] val Pointer to data structure to be freed
4114 * This function frees the storage assigned to @a krb5_creds
4115 * structure, and then @a val itself is released.
4118 krb5_free_creds(krb5_context context, krb5_creds *val);
4120 /** Zero out the session key and free the credentials structure.
4122 * @param [in] context Context structure
4123 * @param [in,out] val Pointer to the data structure to be freed
4125 * @note The pointer to @a val is not freed.
4128 krb5_free_cred_contents(krb5_context context, krb5_creds *val);
4130 /** Free a krb5_checksum structure.
4132 * @param context Context structure
4133 * @param [in] val Pointer to data structure to be freed
4135 * This function frees the contents of a @a val and then releases @a val itself.
4138 krb5_free_checksum(krb5_context context, register krb5_checksum *val);
4140 /** Free the contents of a krb5_checksum structure.
4142 * @param context Context structure
4143 * @param [in] val Checksum structure to be released
4145 * @note The pointer to @a val itself is not freed.
4148 krb5_free_checksum_contents(krb5_context context, register krb5_checksum *val);
4150 /** Free the storage assigned to a keyblock.
4152 * @param [in] context Context structure
4153 * @param [in] val Keyblock to be freed
4155 * This function zeros out and frees the contents of a @a val and then
4156 * releases @a val itself.
4159 krb5_free_keyblock(krb5_context context, register krb5_keyblock *val);
4161 /** Zero out and free the contents of a keyblock.
4163 * @param [in] context Context structure
4164 * @param [in] key Keyblock to be freed
4166 * @note The pointer to @a key itself is not freed.
4169 krb5_free_keyblock_contents(krb5_context context, register krb5_keyblock *key);
4171 /** Free the subkey keyblock.
4173 * @param [in] context Context structure
4174 * @param [in] val Pointer to data structure to be freed
4176 * This function frees the storage assigned to the decrypted portion of an AP-REP
4177 * message, and then @a val itself is released.
4180 krb5_free_ap_rep_enc_part(krb5_context context, krb5_ap_rep_enc_part *val);
4182 /** Free the storage assigned to a krb5_data object
4184 * @param context Context structure
4185 * @param [in] val Pointer to data structure to be freed
4187 * This function zeros out and frees the contents field of @a val and then
4188 * frees @a val itself.
4191 krb5_free_data(krb5_context context, krb5_data *val);
4193 /** Zero out and free the contents of a krb5_data object
4195 * @param context Context structure
4196 * @param [in] val Pointer to data structure to be freed
4198 * @note The pointer to @a val itself is not freed.
4201 krb5_free_data_contents(krb5_context context, krb5_data *val);
4203 /** Free a simple character name string returned by krb5_unparse_name().
4205 * @param context Context structure
4206 * @param [in] val Pointer to name string to be freed
4208 * @note The pointer to @a val itself is not freed.
4211 krb5_free_unparsed_name(krb5_context context, char *val);
4213 /** Free an array of checksum types.
4215 * @param context Context structure
4216 * @param [in] val Array of checksum types to be freed
4218 * @note Make sure the checksum contents have already been freed.
4221 krb5_free_cksumtypes(krb5_context context, krb5_cksumtype *val);
4223 /* From krb5/os but needed but by the outside world */
4224 /** Retrieve the system time of day, in sec and ms, since the epoch.
4226 * @param [in] context Context structure
4227 * @param [out] seconds System timeofday, seconds portion
4228 * @param [out] microseconds System timeofday, microseconds portion
4230 * This function retrieves the system time of day with the context
4231 * specific time offset adjustment.
4233 * @sa krb5_crypto_us_timeofday()
4238 * Kerberos error codes
4240 krb5_error_code KRB5_CALLCONV
4241 krb5_us_timeofday(krb5_context context,
4242 krb5_timestamp *seconds, krb5_int32 *microseconds);
4244 /** Retrieve the current time with context specific time offset adjustment.
4246 * @param [in] context Context structure
4247 * @param [in,out] timeret Timestamp to fill in
4249 * This function retrieves the system time of day with the context
4250 * specific time offset adjustment.
4255 * Kerberos error codes
4257 krb5_error_code KRB5_CALLCONV
4258 krb5_timeofday(krb5_context context, register krb5_timestamp *timeret);
4260 /** Return all protocol addresses for this host.
4262 * @param [in] context Context structure
4263 * @param [out] addr Array of krb5_address pointers.
4264 * The last entry is a NULL pointer
4266 * Compile-time configuration flags indicate which protocol family addresses
4267 * can be returned. Both AF_INET and AF_INET6 are currently supported.
4269 * Use krb5_free_addresses() to free @a addr when it is no longer needed.
4271 * @retval 0 Success; Otherwise - Kerberos error codes
4273 krb5_error_code KRB5_CALLCONV
4274 krb5_os_localaddr(krb5_context context, krb5_address ***addr);
4276 /** Retrieve the default realm.
4278 * @param [in] context Context structure
4279 * @param [out] lrealm Pointer to default realm for the host
4281 * Retrieves the default realm to be used if no user-specified realm is available.
4283 * Use krb5_free_default_realm() to free @a lrealm when it is no longer needed.
4288 * Kerberos error codes
4290 krb5_error_code KRB5_CALLCONV
4291 krb5_get_default_realm(krb5_context context, char **lrealm);
4293 /** Override the default realm for the specified context.
4295 * @param [in,out] context Context structure
4296 * @param [in] lrealm Realm name for the default realm
4298 * If @a lrealm is NULL, clear the default realm setting.
4303 * Kerberos error codes
4305 krb5_error_code KRB5_CALLCONV
4306 krb5_set_default_realm(krb5_context context, const char *lrealm);
4308 /** Free the default realm string returned by krb5_get_default_realm().
4310 * @param context Context structure
4311 * @param [in] lrealm Realm to be freed
4314 krb5_free_default_realm(krb5_context context, char *lrealm);
4316 /** Generate a full principal name from a service name.
4318 * @param [in] context Context structure
4319 * @param [in] hostname Host name, or NULL to use local host
4320 * @param [in] sname Service name, or NULL to use string @c host
4321 * @param [in] type Principal type: @c KRB5_NT_SRV_HST or @c KRB5_NT_UNKNOWN
4322 * @param [out] ret_princ Generated principal
4324 * This function converts a given @a hostname and @a sname into @a krb5_principal
4325 * structure @a ret_princ.
4327 * The @a type can be one of the following:
4329 * @li @c KRB5_NT_SRV_HOST canonicalizes the host name (a fully
4330 * qualified lowercase @a hostname using the primary name and the
4331 * domain name), \b before @a ret_princ is generated in the form
4332 * sname//hostname\@LOCAL.REALM. Most applications should use @a KRB5_NT_SRV_HOST.
4334 * @li @c KRB5_NT_UNKNOWN generates a principal name with
4335 * the form @a sname\/hostname\@LOCAL.REALM, but the @a hostname \b will \b not be
4336 * canonicalized first. It will appear exactly as it was passed in @a hostname.
4338 * Use krb5_free_principal to free @a ret_princ when it is no longer needed.
4343 * Kerberos error codes
4345 krb5_error_code KRB5_CALLCONV
4346 krb5_sname_to_principal(krb5_context context, const char *hostname, const char *sname,
4347 krb5_int32 type, krb5_principal *ret_princ);
4349 /** Test whether a principal matches a matching principal.
4351 * @param [in] context Context structure
4352 * @param [in] matching Matching principal
4353 * @param [in] princ Principal to test
4355 * @note A matching principal is a host-based principal with an empty realm and/or
4356 * second data component (hostname). Profile configuration may cause the
4357 * hostname to be ignored even if it is present. A principal matches a
4358 * matching principal if the former has the same non-empty (and non-ignored)
4359 * components of the latter.
4361 * If @a matching is NULL, return TRUE. If @a matching is not a matching
4362 * principal, return the value of krb5_principal_compare(context, matching,
4366 * TRUE if @a princ matches @a matching, FALSE otherwise.
4368 krb5_boolean KRB5_CALLCONV
4369 krb5_sname_match(krb5_context context, krb5_const_principal matching,
4370 krb5_const_principal princ);
4372 /** Change a password for an existing Kerberos account.
4374 * @param [in] context Context structure
4375 * @param [in] creds Kerberos credentials to the kadmin/changepw service
4376 * @param [in] newpw New password
4377 * @param [out] result_code A numeric error code
4378 * @param [out] result_code_string String equivalent to @a result_code
4379 * @param [out] result_string Change password response from the KDC
4381 * Change the password for the existing principal identified by @a creds.
4383 * The possible values of the output @a result_code are:
4385 * @li KRB5_KPASSWD_SUCCESS (0) - success
4386 * @li KRB5_KPASSWD_MALFORMED (1) - Malformed request error
4387 * @li KRB5_KPASSWD_HARDERROR (2) - Server error
4388 * @li KRB5_KPASSWD_AUTHERROR (3) - Authentication error
4389 * @li KRB5_KPASSWD_SOFTERROR (4) - Password change rejected
4391 * @retval 0 Success; Otherwise - Kerberos error codes
4393 krb5_error_code KRB5_CALLCONV
4394 krb5_change_password(krb5_context context, krb5_creds *creds, char *newpw,
4395 int *result_code, krb5_data *result_code_string,
4396 krb5_data *result_string);
4398 /** Set a password for a principal using specified credentials.
4400 * @param [in,out] context Context structure
4401 * @param [in] creds Credentials
4402 * @param [in] newpw New password
4403 * @param [in] change_password_for Change the password for this principal
4404 * @param [out] result_code Numeric error code returned by the remote system
4405 * @param [out] result_code_string Error code translated into a readable message
4406 * @param [out] result_string Data returned from the remote system
4408 * This function uses the credentials @a creds to set the password
4409 * @a newpw for the principal @a change_password_for.
4410 * It implements the set password operation of RFC 3244, for
4411 * interoperability with Microsoft Windows implementations.
4413 * @note If @a change_password_for is NULL, the change is performed on the
4414 * current principal. If @a change_password_for is non-null, the change is
4415 * performed on the principal name passed in @a change_password_for.
4417 * The error code and strings are returned in @a result_code,
4418 * @a result_code_string and @a result_string.
4420 * @sa krb5_set_password_using_ccache()
4423 * 0 Success and result_code is set to KRB5_KPASSWD_SUCCESS.
4425 * Kerberos error codes.
4427 krb5_error_code KRB5_CALLCONV
4428 krb5_set_password(krb5_context context, krb5_creds *creds, char *newpw,
4429 krb5_principal change_password_for, int *result_code,
4430 krb5_data *result_code_string, krb5_data *result_string);
4432 /** Set a password for a principal using cached credentials.
4434 * @param [in,out] context Context structure
4435 * @param [in] ccache Credentials cache
4436 * @param [in] newpw New password
4437 * @param [in] change_password_for Change the password for this principal
4438 * @param [out] result_code Numeric error code returned by the remote system
4439 * @param [out] result_code_string Error code translated into a readable message
4440 * @param [out] result_string Data returned from the remote system
4442 * This function uses the cached credentials from @a ccache to set the password
4443 * @a newpw for the principal @a change_password_for.
4444 * It implements RFC 3244 set password operation (interoperable with MS Windows
4445 * implementations) using the credentials cache.
4447 * The error code and strings are returned in @a result_code,
4448 * @a result_code_string and @a result_string.
4450 * @sa krb5_set_password()
4452 * @note If @a change_password_for is set to NULL, the change is performed
4453 * on the default principal in @a ccache. If @a change_password_for is non null,
4454 * the change is performed on the specified principal.
4459 * Kerberos error codes
4461 krb5_error_code KRB5_CALLCONV
4462 krb5_set_password_using_ccache(krb5_context context, krb5_ccache ccache,
4463 char *newpw, krb5_principal change_password_for,
4464 int *result_code, krb5_data *result_code_string,
4465 krb5_data *result_string);
4467 /** Retrieve configuration data from the context.
4469 * @param [in] context Context structure
4470 * @param [out] profile Pointer to data read from a configuration file
4472 * This function creates a new @a profile object that reflects profile
4473 * in the supplied @a context.
4475 * The @a profile object may be freed with profile_release() function.
4476 * See profile.h and profile API for more details.
4481 * Kerberos error codes
4483 krb5_error_code KRB5_CALLCONV
4484 krb5_get_profile(krb5_context context, struct _profile_t ** profile);
4487 /** @deprecated Replaced by krb5_get_init_creds_password().*/
4488 KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
4489 krb5_get_in_tkt_with_password(krb5_context context, krb5_flags options,
4490 krb5_address *const *addrs, krb5_enctype *ktypes,
4491 krb5_preauthtype *pre_auth_types,
4492 const char *password, krb5_ccache ccache,
4493 krb5_creds *creds, krb5_kdc_rep **ret_as_reply);
4495 /** @deprecated Replaced by krb5_get_init_creds(). */
4496 KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
4497 krb5_get_in_tkt_with_skey(krb5_context context, krb5_flags options,
4498 krb5_address *const *addrs, krb5_enctype *ktypes,
4499 krb5_preauthtype *pre_auth_types,
4500 const krb5_keyblock *key, krb5_ccache ccache,
4501 krb5_creds *creds, krb5_kdc_rep **ret_as_reply);
4503 /** @deprecated Replaced by krb5_get_init_creds_keytab(). */
4504 KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
4505 krb5_get_in_tkt_with_keytab(krb5_context context, krb5_flags options,
4506 krb5_address *const *addrs, krb5_enctype *ktypes,
4507 krb5_preauthtype *pre_auth_types,
4508 krb5_keytab arg_keytab, krb5_ccache ccache,
4509 krb5_creds *creds, krb5_kdc_rep **ret_as_reply);
4511 #endif /* KRB5_DEPRECATED */
4513 /** Parse and decrypt a @c KRB_AP_REQ message.
4515 * @param [in] context Context structure
4516 * @param [in,out] auth_context Authentication context. A new authentication
4517 * context is returned if NULL is specified
4518 * @param [in] inbuf AP-REQ message to be parsed
4519 * @param [in] server Server's principal for the @a ticket.
4520 * Use NULL for the principal of the @a keytab
4521 * @param [in] keytab Key table that contains a decryption key.
4522 * Use NULL for the default key table.
4523 * @param [out] ap_req_options If non-null, the AP-REQ flags on output
4524 * @param [out] ticket Returned ticket from the AP-REQ message.
4525 * Use NULL to specify that no ticket needed.
4527 * This function parses, decrypts and verifies a AP-REQ message from @a inbuf
4528 * and stores the authenticator in @a auth_context.
4530 * If a keyblock is present in the @a auth_context, it is used to decrypt
4531 * the ticket in AP-REQ message. (This is useful for user-to-user authentication.)
4532 * Otherwise, the decryption key is obtained from the @a keytab.
4534 * The client specified in the decrypted authenticator must match the client
4535 * specified in the @a ticket.
4537 * If the @a remote_addr field of @a auth_context is set, the request must came
4538 * from that address.
4540 * If a replay cache handle is provided in the @a auth_context, the authenticator
4541 * and @a ticket are verified against it. If no conflicts found, the new
4542 * authenticator is then stored in the replay cash of @a auth_context.
4544 * Various other checks are performed on the decoded data, including
4545 * cross-realm policy, clockskew, and ticket validation times.
4547 * On success the authenticator, subkey, and remote sequence number of the
4548 * request are stored in @a auth_context. If the @c AP_OPTS_MUTUAL_REQUIRED
4549 * bit is set, the local sequence number is XORed with the remote sequence
4550 * number in the request.
4552 * Use krb5_free_ticket() to free @a ticket when it is no longer needed.
4554 * @retval 0 Success; Otherwise - Kerberos error codes
4556 krb5_error_code KRB5_CALLCONV
4557 krb5_rd_req(krb5_context context, krb5_auth_context *auth_context,
4558 const krb5_data *inbuf, krb5_const_principal server,
4559 krb5_keytab keytab, krb5_flags *ap_req_options,
4560 krb5_ticket **ticket);
4562 /** Retrieve a service key from a key table.
4564 * @param [in] context Context structure
4565 * @param [in] keyprocarg Name of a key table or NULL to use default key table
4566 * @param [in] principal Service principal
4567 * @param [in] vno Key version number; use 0 to specify the key with
4568 * the highest version number
4569 * @param [in] enctype Key encryption type; use a keytype of 0 if
4570 * encryption type does not matter
4571 * @param [out] key Returned service key
4573 * Open and search the specified key table for the entry identified by @a principal, @a enctype,
4574 * and @a vno. If no key is found, return an error code.
4576 * The default key table is used, unless @a keyprocarg is non-null.
4577 * @a keyprocarg designates a specific key table.
4579 * Use krb5_free_keyblock() to free @a key when it is no longer needed.
4583 * @return Kerberos error code if not found or @a keyprocarg is invalid.
4585 krb5_error_code KRB5_CALLCONV
4586 krb5_kt_read_service_key(krb5_context context, krb5_pointer keyprocarg,
4587 krb5_principal principal, krb5_kvno vno,
4588 krb5_enctype enctype, krb5_keyblock **key);
4590 /** Format a @c KRB-SAFE message.
4592 * @param [in] context Context structure
4593 * @param [in,out] auth_context Authentication context
4594 * @param [in] userdata User data in the message
4595 * @param [out] outbuf Formatted @c KRB-SAFE buffer
4596 * @param [out] outdata Replay data. Specify NULL if not needed
4598 * This function creates an integrity protected @c KRB-SAFE message
4599 * using data supplied by the application.
4601 * Fields in @a auth_context specify the checksum type, the keyblock that
4602 * can be used to seed the checksum, full addresses (host and port) for
4603 * the sender and receiver, and KRB5_AUTH_CONTEXT_ flags.
4605 * The @a local_addr field of @a auth_context is used to
4606 * form the addresses used in the KRB-SAFE message. The remote_addr is optional;
4607 * if the receiver's address is unknown, it can be replaced by NULL.
4609 * @note The @a local_addr argument is mandatory.
4611 * @note The @a outdata argument is required if KRB5_AUTH_CONTEXT_RET_TIME or
4612 * KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in the @a auth_context.
4614 * If @c KRB5_AUTH_CONTEXT_DO_TIME flag is set in the @a auth_context, an entry
4615 * describing the message is entered in the replay cache @a auth_context->rcache
4616 * which enables the caller to detect if this message is sent back by an attacker.
4617 * If @c KRB5_AUTH_CONTEXT_DO_TIME is not set, the replay cache is not used.
4619 * If either @c KRB5_AUTH_CONTEXT_DO_SEQUENCE or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE
4620 * is set, the @a auth_context local sequence number will be placed in the
4621 * @a outdata as its sequence number.
4623 * @retval 0 Success; Otherwise - Kerberos error codes
4625 krb5_error_code KRB5_CALLCONV
4626 krb5_mk_safe(krb5_context context, krb5_auth_context auth_context,
4627 const krb5_data *userdata, krb5_data *outbuf,
4628 krb5_replay_data *outdata);
4630 /** Format a @c KRB-PRIV message.
4632 * @param [in] context Context structure
4633 * @param [in,out] auth_context Authentication context
4634 * @param [in] serdata User data for @c KRB-PRIV message
4635 * @param [out] outbuf Formatted @c KRB-PRIV message
4636 * @param [out] outdata Replay cache handle. Specify NULL if not needed.
4638 * This function is similar to krb5_mk_safe(), but the message is encrypted and
4639 * integrity-protected, not just integrity-protected.
4641 * The @a remote_addr and @a remote_port fields of @a auth_context are
4642 * optional; @a local_addr, is mandatory. If the receiver's address is unknown,
4643 * it can be replaced by NULL.
4645 * The encryption type is taken either from @a send_subkey or, if NULL,
4646 * from @a key field of @a auth_context.
4648 * If the @a i_vector field in @a auth_context is non-null, it is used
4649 * as an initialization vector for the encryption (if the chosen encryption
4650 * type supports initialization vectors), and its contents are replaced with
4651 * the last block of encrypted data upon return.
4653 * @note If the @c KRB5_AUTH_CONTEXT_RET_TIME or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE
4654 * flag is set in @a auth_context, the @a outdata is required.
4656 * @note The flags from @a auth_context specify whether sequence numbers or
4657 * timestamps will be used to identify the message.
4659 * @li @c KRB5_AUTH_CONTEXT_DO_TIME - Use timestamps in @a outdata
4660 * @li @c KRB5_AUTH_CONTEXT_RET_TIME - Copy timestamp to @a outdata.
4661 * @li @c KRB5_AUTH_CONTEXT_DO_SEQUENCE - Use local sequence numbers from
4662 * @a auth_context in replay cache.
4663 * @li @c KRB5_AUTH_CONTEXT_RET_SEQUENCE - Use local sequence numbers from
4664 * @a auth_context as a sequence number
4665 * in the encrypted message @a outbuf.
4667 * @retval 0 Success; Otherwise - Kerberos error codes
4669 krb5_error_code KRB5_CALLCONV
4670 krb5_mk_priv(krb5_context context, krb5_auth_context auth_context,
4671 const krb5_data *userdata, krb5_data *outbuf,
4672 krb5_replay_data *outdata);
4675 * @brief Send an authenticated message.
4677 * @param context Context structure [input, output]
4678 * @param auth_context Authentication context [input, output}
4679 * @param fd Pointer to file descriptor that describes network socket [input]
4680 * @param appl_version String that describes the application protocol version client is expected to use [input]
4681 * @param client Client principal name; ignored if @a in_creds is non-null [input]
4682 * @param server Server principal name; ignored if @a in_creds is non-null [input]
4683 * @param ap_req_options Specifies @c KRB-AP-REQ flags [input]
4684 * @param in_data Data to be sent to the server [input]
4685 * @param in_creds Input credentials, or NULL [input]
4686 * @param ccache Credentials cache [input, output]
4687 * @param error If non-null, contains error packet returned from server [output]
4688 * @param rep_result If non-null, contains result of mutual authentication exchange [output]
4689 * @param out_creds If non-null, the retrieved credentials [output]
4691 * Send an authenticated message from a client program to a server
4692 * program using the network connection specified by @a fd. In the MIT UNIX and
4693 * OpenVMS implementations, @a fd is a pointer to a network socket file descriptor.
4695 * Valid values for @a ap_req_options are:
4696 * @li @c AP_OPTS_USE_SESSION_KEY
4697 * @li @c AP_OPTS_MUTUAL_REQUIRED Perform a mutual authentication exchange
4698 * @li @c AP_OPTS_USE_SUBKEY
4700 * If @a in_creds is NULL:
4701 * @li @a server must be non-null
4702 * @li @a client can be NULL. If @a client is NULL, the credentials cache default principal is used.
4704 * If @a in_creds is non-null, @a in_creds->client and @a in_creds->server must be
4705 * filled in. If the other structure fields are filled in with valid credentials,
4706 * @a in_creds->ticket.length must be zero.
4708 * If @a rep_result is non-null, it is filled in with the result of the mutual
4709 * authentication exchange.
4711 * If @a in_creds->ticket.length is nonzero, @a in_creds is used
4712 * as the credentials to send to the server, and @a ccache is ignored. Otherwise,
4713 * @a ccache is used.
4715 * If @a out_creds, is non-null, it is filled in with the retrieved credentials.
4717 * @a ccache specifies the credential cache to use @a only when @a in_creds is
4718 * NULL or @a in_creds->ticket.length is zero.
4720 * If @a in_creds is NULL or @a in_creds->ticket.length is zero and @a ccache is NULL,
4721 * If the default credential cache does not contain the needed credentials,
4722 * the credentials will be retrieved from the KDC and stored in the credential cache.
4724 * If mutual authentication is used and @a rep_result is non-null, the sequence number
4725 * for the server is in *rep_result-\>seq_number. If mutual authentication is not
4726 * used, there is no way to negotiate a sequence number for the server.
4728 * If the server is using a different application protocol than that specified in
4729 * @a appl_version, an error will be returned.
4731 * If an error occurs during the authenticated message exchange and @a error is non-null,
4732 * the error packet (if any) sent from the server will be placed in it.
4734 * Make sure to free the allocated memory when it is no longer needed.
4739 * Kerberos error codes
4741 krb5_error_code KRB5_CALLCONV
4742 krb5_sendauth(krb5_context context, krb5_auth_context *auth_context,
4743 krb5_pointer fd, char *appl_version, krb5_principal client,
4744 krb5_principal server, krb5_flags ap_req_options,
4745 krb5_data *in_data, krb5_creds *in_creds, krb5_ccache ccache,
4746 krb5_error **error, krb5_ap_rep_enc_part **rep_result,
4747 krb5_creds **out_creds);
4750 * @brief Receive an authenticated message.
4752 * @param context Context structure [input, output]
4753 * @param auth_context Authentication context [input, output}
4754 * @param fd Pointer to file descriptor of network socket [input]
4755 * @param appl_version String describing the expected application protocol version. [input]
4756 * @param server Server principal [input]
4757 * @param flags Additional specifications; nonlibrary callers should use 0. [input]
4758 * @param keytab Decryption key [input]
4759 * @param ticket Ticket (optional); only filled in with client ticket data if non-null [output]
4761 * This routine, paired with krb5_sendauth(), provides a way for client and server programs to
4762 * send authenticated messages to one another through network connections.
4764 * krb5_recvauth() engages in an authentication dialog with the client program running krb5_sendauth()
4765 * to authenticate the client to the server.
4767 * Upon request from the client, krb5_recvauth() provides mutual authentication
4768 * to ensure the legitimacy of the server represented by krb5_recvauth().
4770 * The @a fd argument is a pointer to the network connection. As in krb5_sendauth()
4771 * in the MIT UNIX and OpenVMS implementations, @a fd is a pointer to a file descriptor.
4773 * @a server, @c _krb5_auth_context, and @a keytab are used to obtain the server's private key.
4776 * @li if client uses a different application protocol than that specified in @a appl_version,
4777 * an error is returned and the authentication exchange is aborted.
4779 * Make sure to free the allocated memory when it is no longer needed.
4784 * Kerberos error codes
4786 * @todo link to flags?
4788 krb5_error_code KRB5_CALLCONV
4789 krb5_recvauth(krb5_context context, krb5_auth_context *auth_context,
4790 krb5_pointer fd, char *appl_version, krb5_principal server,
4791 krb5_int32 flags, krb5_keytab keytab, krb5_ticket **ticket);
4794 * @brief Send authentication messages between client and server using the network.
4796 * @param context Context structure [input, output]
4797 * @param auth_context Authentication context [input, output}
4798 * @param fd Socket from which to read the client response [input]
4799 * @param server Verify the server principal is the same as requested by client; if NULL, an error is returned and the exchange is aborted [input]
4801 * @param keytab Decryption key [input]
4802 * @param ticket Optional, if non-null, filled with ticket data sent by the client [output]
4803 * @param version Pointer to application version string [output]
4805 * This routine provides a convenient means for client and server programs to send authenticated messages to
4806 * one another through network connections. (k5b5_sendauth() is the matching routine to krb5_recvauth_version() for the server.)
4808 * krb5_recvauth_version() engages in an authentication dialog with the client program running
4809 * krb5_sendauth() to authenticate the client to the server. In addition, if requested by the client,
4810 * krb5_recvauth_version() provides mutual authentication to prove to the client that the server represented by
4811 * krb5_recvauth_version() is legitimate.
4813 * @a fd is a pointer to the network connection. As in krb5_sendauth(), in the MIT UNIX and
4814 * OpenVMS implementations, @a fd is a pointer to a file descriptor.
4816 * The arguments @a server, @c _krb5_auth_context, and @a keytab are used by @c krb5_rd_req() to obtain the
4817 * server's private key.
4819 * If server is non-null, the principal component of it is used to determine
4820 * the replay cache to use. Otherwise, @c krb5_recvauth_version uses the default
4823 * Make sure to free the allocated memory when it is no longer needed.
4828 * KRB5_SENDAUTH_BADAUTHVERS Bad sendauth version was sent
4830 * KRB5_SENDAUTH_BADAPPLVERS Bad application version was sent
4832 * Kerberos error codes
4834 krb5_error_code KRB5_CALLCONV
4835 krb5_recvauth_version(krb5_context context,
4836 krb5_auth_context *auth_context,
4839 krb5_principal server,
4843 krb5_ticket **ticket,
4844 krb5_data *version);
4846 /** Format a @c KRB-CRED message for an array of credentials.
4848 * @param [in] context Context structure
4849 * @param [in,out] auth_context Authentication context
4850 * @param [in] ppcreds NULL terminated array of credentials
4851 * @param [out] ppdata Encoded credentials
4852 * @param [out] outdata Replay cache handle.
4853 * Specify NULL if not needed
4855 * This function takes an array of credentials @a ppcreds and formats
4856 * a @c KRB-CRED message @a ppdata to pass to krb5_rd_cred().
4858 * @note If the KRB5_AUTH_CONTEXT_RET_TIME or KRB5_AUTH_CONTEXT_RET_SEQUENCE
4859 * flag is set in @a auth_context, the @a outdata is required.
4861 * The message will be decrypted and verified using the @a recv_subkey
4862 * field of @a auth_context if it is non-null, or by the @a key field if
4863 * @a recv_subkey is null or fails to decrypt the message.
4868 * ENOMEM Insufficient memory
4870 * KRB5_RC_REQUIRED Message replay detection requires @a rcache parameter
4872 * Kerberos error codes
4874 krb5_error_code KRB5_CALLCONV
4875 krb5_mk_ncred(krb5_context context, krb5_auth_context auth_context,
4876 krb5_creds **ppcreds, krb5_data **ppdata,
4877 krb5_replay_data *outdata);
4879 /** Format a @c KRB-CRED message for a single set of credentials.
4881 * @param [in] context Context structure
4882 * @param [in,out] auth_context Authentication context
4883 * @param [in] pcreds Pointer to credentials
4884 * @param [out] ppdata Encoded credentials
4885 * @param [out] outdata Replay cache handle
4887 * This is a convenience function that calls krb5_mk_ncred() with a single set
4890 * @note If the @c KRB5_AUTH_CONTEXT_RET_TIME or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE
4891 * flag is set in @a auth_context, the @a outdata is required. Otherwise it can be
4897 * ENOMEM Insufficient memory
4899 * KRB5_RC_REQUIRED Message replay detection requires @a rcache parameter
4901 * Kerberos error codes
4903 krb5_error_code KRB5_CALLCONV
4904 krb5_mk_1cred(krb5_context context, krb5_auth_context auth_context,
4905 krb5_creds *pcreds, krb5_data **ppdata,
4906 krb5_replay_data *outdata);
4908 /** Read and validate a @c KRB-CRED message.
4910 * @param [in] context Context structure
4911 * @param [in,out] auth_context Authentication context
4912 * @param [in] pcreddata @c KRB-CRED message
4913 * @param [out] pppcreds Array of forwarded credentials
4914 * @param [out] outdata Replay data
4915 * Specify NULL if not needed.
4917 * @note The @a outdata argument is required if RB5_AUTH_CONTEXT_RET_TIME or
4918 * KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in the @a auth_context.`
4920 * The keyblock used to decrypt the data and verify the integrity of the message
4921 * is taken from fields @a recv_subkey or @a key in @a auth_context.
4922 * The keyblock is chosen in the preceding order by the first one that is non-null.
4923 * However, if the first non-null key fails to decrypt the message, the second one
4926 * Use krb5_free_tgt_creds() to free @a pppcreds when it is no longer needed.
4928 * @retval 0 Success; Otherwise - Kerberos error codes
4930 krb5_error_code KRB5_CALLCONV
4931 krb5_rd_cred(krb5_context context, krb5_auth_context auth_context,
4932 krb5_data *pcreddata, krb5_creds ***pppcreds,
4933 krb5_replay_data *outdata);
4935 /** Get a forwarded TGT and format a @c KRB-CRED message.
4937 * @param [in] context Context structure
4938 * @param [in] auth_context Authentication context with the key to encrypt @a outbuf
4939 * @param [in] rhost Remote host
4940 * @param [in] client Client principal for the TGT
4941 * @param [in] server Server principal for the TGT
4942 * @param [in] cc Credentials cache handle.
4943 * @param [in] forwardable Boolean indicating whether TGT should be forwardable
4944 * @param [out] outbuf Output buffer containing the TGT to be filled in
4946 * Get a TGT for use at the remote host @a rhost.
4947 * If @a rhost is NULL, @a server service principal will be used.
4948 * If @a cc is NULL, the default credential cache will be used.
4953 * ENOMEM Insufficient memory
4955 * KRB5_PRINC_NOMATCH Requested principal and ticket do not match
4957 * KRB5_NO_TKT_SUPPLIED Request did not supply a ticket
4959 * KRB5_CC_BADNAME Credential cache name or principal name malformed
4961 * Kerberos error codes
4963 krb5_error_code KRB5_CALLCONV
4964 krb5_fwd_tgt_creds(krb5_context context, krb5_auth_context auth_context,
4965 char *rhost, krb5_principal client, krb5_principal server,
4966 krb5_ccache cc, int forwardable, krb5_data *outbuf);
4968 /** Create and initialize an authentication context.
4970 * @param [in] context Context structure
4971 * @param [out] auth_context Authentication context
4973 * The @c _krb5_auth_context contains all data pertinent to the various authentication routines.
4975 * By default, @a flags for the context are set to enable the use of the replay cache
4976 * (KRB5_AUTH_CONTEXT_DO_TIME) but not sequence numbers.
4977 * Use krb5_auth_con_setflags() to change the flags.
4979 * The allocated @a auth_context must be freed with krb5_auth_con_free() when
4980 * it is no longer needed.
4982 * @retval 0 Success; Otherwise - Kerberos error codes
4984 krb5_error_code KRB5_CALLCONV
4985 krb5_auth_con_init(krb5_context context, krb5_auth_context *auth_context);
4987 /** Free a @c _krb5_auth_context structure.
4989 * @param [in] context Context structure
4990 * @param [in] auth_context Authentication context to be freed
4992 * This function frees @a auth_context allocated by krb5_auth_con_init()
4994 * @retval 0 (always)
4996 krb5_error_code KRB5_CALLCONV
4997 krb5_auth_con_free(krb5_context context, krb5_auth_context auth_context);
4999 /** Set a flags field in a krb5_auth_context structure.
5001 * @param context Context structure
5002 * @param [in,out] auth_context Authentication context
5003 * @param [in] flags Flags bit mask
5005 * Valid values for @a flags are:
5006 * @li @c KRB5_AUTH_CONTEXT_DO_TIME Use timestamps
5007 * @li @c KRB5_AUTH_CONTEXT_RET_TIME Save timestamps to output structure
5008 * @li @c KRB5_AUTH_CONTEXT_DO_SEQUENCE Use sequence numbers
5009 * @li @c KRB5_AUTH_RET_SEQUENCE Copy sequence numbers to output structure
5011 * @retval 0 (always)
5013 krb5_error_code KRB5_CALLCONV
5014 krb5_auth_con_setflags(krb5_context context, krb5_auth_context auth_context, krb5_int32 flags);
5016 /** Retrieve a flags field from a krb5_auth_context structure.
5018 * @param context Context structure
5019 * @param [in] auth_context Authentication context
5020 * @param [out] flags Flags bit mask
5022 * Valid values for @a flags are:
5023 * @li @c KRB5_AUTH_CONTEXT_DO_TIME Use timestamps in the message
5024 * @li @c KRB5_AUTH_CONTEXT_RET_TIME Save timestamps to output structure.
5025 * @li @c KRB5_AUTH_CONTEXT_DO_SEQUENCE Use sequence numbers in the message
5026 * @li @c KRB5_AUTH_RET_SEQUENCE Copy sequence numbers to output structure.
5029 * @retval 0 (always)
5031 krb5_error_code KRB5_CALLCONV
5032 krb5_auth_con_getflags(krb5_context context, krb5_auth_context auth_context, krb5_int32 *flags);
5034 /** Set checksum_function related fields in krb5_auth_contex structure.
5036 * @param context Context structure
5037 * @param [in,out] auth_context Authentication context
5038 * @param [in] func Function to perform the checksum
5039 * @param [in] data Pointer to arbitrary to be received by @a func
5041 * The checksum data is received when krb5_mk_req_extended() calls it.
5043 * @retval 0 (always)
5045 krb5_error_code KRB5_CALLCONV
5046 krb5_auth_con_set_checksum_func( krb5_context context,
5047 krb5_auth_context auth_context,
5048 krb5_mk_req_checksum_func func,
5051 /** Get checksum_function related fields from krb5_auth_contex structure.
5053 * @param context Context structure
5054 * @param [in] auth_context Authentication context
5055 * @param [out] func Pointer to krb5 function that performs the checksum
5056 * @param [out] data Pointer to data
5058 * @retval 0 (always)
5060 krb5_error_code KRB5_CALLCONV
5061 krb5_auth_con_get_checksum_func( krb5_context context,
5062 krb5_auth_context auth_context,
5063 krb5_mk_req_checksum_func *func,
5066 /** Sep the local and remote addresses in a krb5_auth_context structure.
5068 * @param [in] context Context structure
5069 * @param [in,out] auth_context Authentication context
5070 * @param [in] local_addr Local address
5071 * @param [in] remote_addr Remote address
5073 * This function releases the storage assigned to the contents of
5074 * the local and remote addresses of @a auth_context structure and
5075 * then sets them to @a local_addr and @a remote_addr respectively.
5077 * @sa krb5_auth_con_genaddrs()
5079 * @retval 0 Success; Otherwise - Kerberos error codes
5081 krb5_error_code KRB5_CALLCONV_WRONG
5082 krb5_auth_con_setaddrs(krb5_context context, krb5_auth_context auth_context,
5083 krb5_address *local_addr, krb5_address *remote_addr);
5085 /** Retrieve address fields from a krb5_auth_con structure.
5087 * @param [in] context Context structure
5088 * @param [in] auth_context Authentication context
5089 * @param [out] local_addr Local address; if NULL - not requested
5090 * @param [out] remote_addr Remote address; if NULL - not requested
5092 * If @a local_addr or @a remote_addr is non-null, the buffers are freed and
5093 * then newly allocated.
5095 * @retval 0 Success; Otherwise - Kerberos error codes
5097 krb5_error_code KRB5_CALLCONV
5098 krb5_auth_con_getaddrs(krb5_context context, krb5_auth_context auth_context,
5099 krb5_address **local_addr, krb5_address **remote_addr);
5101 /** Set local and remote port fields in a krb5_auth_context structure.
5103 * @param [in] context Context structure
5104 * @param [in,out] auth_context Authentication context
5105 * @param [in] local_port Local port
5106 * @param [in] remote_port Remote port
5108 * This function releases the storage assigned to the contents of
5109 * the local and remote ports of @a auth_context structure and
5110 * then sets them to @a local_port and @a remote_port respectively.
5112 * @sa krb5_auth_con_genaddrs()
5114 * @retval 0 Success; Otherwise - Kerberos error codes
5116 krb5_error_code KRB5_CALLCONV
5117 krb5_auth_con_setports(krb5_context context, krb5_auth_context auth_context,
5118 krb5_address *local_port, krb5_address *remote_port);
5120 /** Set an encryption key field in a krb5_auth_context structure.
5122 * @param [in] context Context structure
5123 * @param [in,out] auth_context Authentication context
5124 * @param [in] keyblock User key
5126 * @retval 0 Success. Otherwise - Kerberos error codes
5128 krb5_error_code KRB5_CALLCONV
5129 krb5_auth_con_setuseruserkey(krb5_context context, krb5_auth_context auth_context,
5130 krb5_keyblock *keyblock);
5132 /** Retrieve an encryption key from a krb5_auth_context structure.
5134 * @param [in] context Context structure
5135 * @param [in] auth_context Authentication context
5136 * @param [out] keyblock Keyblock structure containing a key
5138 * This function allocates the output @a keyblock and populates it with the
5139 * content of @a ac->send_key.
5140 * Use krb5_free_keyblock() to free @a keyblock when it it no longer needed
5142 * @retval 0 Success. Otherwise - Kerberos error codes
5144 krb5_error_code KRB5_CALLCONV
5145 krb5_auth_con_getkey(krb5_context context, krb5_auth_context auth_context,
5146 krb5_keyblock **keyblock);
5148 /** Get a copy of an encryption key from a krb5_auth_context structure.
5150 * @param context Context structure
5151 * @param [in] auth_context Authentication context
5152 * @param [in,out] key Output key structure to be filled in
5154 * This function populates the output @a key with the
5155 * content of @a auth_context->send_subkey.
5157 * @retval 0 (always)
5159 krb5_error_code KRB5_CALLCONV
5160 krb5_auth_con_getkey_k(krb5_context context, krb5_auth_context auth_context,
5163 /** Retrieve a send_subkey keyblock from a krb5_auth_context structure.
5165 * @param [in] context Context structure
5166 * @param [in] ac Authentication context
5167 * @param [out] keyblock Key block structure.
5169 * This function allocates the output @a keyblock and populates it with the
5170 * content of @a ac->send_subkey.
5171 * Use krb5_free_keyblock() to free @a keyblock when it is no longer needed.
5173 * @retval 0 Success; Otherwise - Kerberos error codes
5175 krb5_error_code KRB5_CALLCONV
5176 krb5_auth_con_getsendsubkey(krb5_context ctx, krb5_auth_context ac, krb5_keyblock **keyblock);
5178 /** Get a copy of a send_subkey key from a krb5_auth_context structure.
5180 * @param ctx Context structure
5181 * @param [in] ac Authentication context
5182 * @param [in,out] key Key structure to be filled in
5184 * This function populates the output @a key with the
5185 * content of @a auth_context->send_subkey.
5187 * @retval 0 (always)
5189 krb5_error_code KRB5_CALLCONV
5190 krb5_auth_con_getsendsubkey_k(krb5_context ctx, krb5_auth_context ac,
5193 /** Retrieve a recv_subkey keyblock from a krb5_auth_context structure.
5195 * @param ctx Context structure
5196 * @param [in] ac Authentication context
5197 * @param [out] keyblock Key block structure
5199 * This function populates the output @a keyblock with the
5200 * content of @a auth_context->recv_subkey.
5201 * Use krb5_free_keyblock() to free @a keyblock when it is no longer needed.
5203 * @retval 0 Success; Otherwise - Kerberos error codes
5205 krb5_error_code KRB5_CALLCONV
5206 krb5_auth_con_getrecvsubkey(krb5_context ctx, krb5_auth_context ac, krb5_keyblock **keyblock);
5208 /** Get a copy of a recv_subkey key from a krb5_auth_context structure.
5210 * @param ctx Context structure
5211 * @param [in] ac Authentication context
5212 * @param [in,out] key Key block structure to be filled in
5214 * This function populates the output @a key with the
5215 * content of @a auth_context->recv_subkey.
5217 * @retval 0 (always)
5219 krb5_error_code KRB5_CALLCONV
5220 krb5_auth_con_getrecvsubkey_k(krb5_context ctx, krb5_auth_context ac, krb5_key *key);
5222 /** Set a send_subkey field in a krb5_auth_context structure.
5224 * @param [in] ctx Context structure
5225 * @param [in,out] ac Authentication context
5226 * @param [in] keyblock Key to be stored in @a ac->send_subkey
5228 * The old @a ac->send_subkey is freed.
5230 * @retval 0 Success. Otherwise - Kerberos error codes
5232 krb5_error_code KRB5_CALLCONV
5233 krb5_auth_con_setsendsubkey(krb5_context ctx, krb5_auth_context ac,
5234 krb5_keyblock *keyblock);
5236 /** Assign send_subkey field in a krb5_auth_context structure to a given key.
5238 * @param [in] ctx Context structure
5239 * @param [in,out] ac Authentication context
5240 * @param [in] key Key to be assigned to @a ac->send_subkey
5242 * The old @a ac->send_subkey is freed.
5243 * The @a key reference count is incremented.
5245 * @retval 0 (always)
5247 krb5_error_code KRB5_CALLCONV
5248 krb5_auth_con_setsendsubkey_k(krb5_context ctx, krb5_auth_context ac, krb5_key key);
5250 /** Set a recv_subkey field in a krb5_auth_context structure.
5252 * @param [in] ctx Context structure
5253 * @param [in,out] ac Authentication context
5254 * @param [in] keyblock Keyblock to be stored in @a ac->recv_subkey
5256 * The old @a ac->recv_subkey is freed.
5258 * @retval 0 Success. Otherwise - Kerberos error codes
5260 krb5_error_code KRB5_CALLCONV
5261 krb5_auth_con_setrecvsubkey(krb5_context ctx, krb5_auth_context ac,
5262 krb5_keyblock *keyblock);
5264 /** Assign recv_subkey field in a krb5_auth_context structure to a given key.
5266 * @param [in] ctx Context structure
5267 * @param [in,out] ac Authentication context
5268 * @param [in] key Key to be assigned to @a ac->send_subkey
5270 * The old @a ac->recv_subkey is freed.
5271 * The @a key reference count is incremented.
5273 * @retval 0 (always)
5275 krb5_error_code KRB5_CALLCONV
5276 krb5_auth_con_setrecvsubkey_k(krb5_context ctx, krb5_auth_context ac,
5280 /** @deprecated Replaced by krb5_auth_con_getsendsubkey(). */
5281 KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
5282 krb5_auth_con_getlocalsubkey(krb5_context context, krb5_auth_context auth_context,
5283 krb5_keyblock **keyblock);
5285 /** @deprecated Replaced by krb5_auth_con_getrecvsubkey(). */
5286 KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
5287 krb5_auth_con_getremotesubkey(krb5_context context, krb5_auth_context auth_context,
5288 krb5_keyblock **keyblock);
5291 /** Retrieve a local sequence number from a krb5_auth_context structure.
5293 * @param context Context structure
5294 * @param [in] auth_context Authentication context
5295 * @param [in,out] seqnumber Local sequence number to be filled in
5297 * Retrieve the local sequence number used during authentication and store
5298 * it in the @a seqnumber.
5299 * The @c KRB5_AUTH_CONTEXT_DO_SEQUENCE flag must be set in @a auth_context
5300 * for this function to have an effect.
5302 * @retval 0 (always)
5304 krb5_error_code KRB5_CALLCONV
5305 krb5_auth_con_getlocalseqnumber(krb5_context context, krb5_auth_context auth_context,
5306 krb5_int32 *seqnumber);
5308 /** Retrieve a remote sequence number from a krb5_auth_context structure.
5310 * @param context Context structure
5311 * @param [in] auth_context Authentication context
5312 * @param [in,out] seqnumber Remote sequence number to be filled in
5314 * Retrieve the remote sequence number used during authentication and store
5315 * it in the @a seqnumber.
5316 * The @c KRB5_AUTH_CONTEXT_DO_SEQUENCE flag must be set in @a auth_context
5317 * for this function to have an effect.
5319 * @retval 0 (always)
5321 krb5_error_code KRB5_CALLCONV
5322 krb5_auth_con_getremoteseqnumber(krb5_context context, krb5_auth_context auth_context,
5323 krb5_int32 *seqnumber);
5326 /** @deprecated Not replaced.
5328 * RFC 4120 doesn't have anything like the initvector concept;
5329 * only really old protocols may need this API.
5331 KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
5332 krb5_auth_con_initivector(krb5_context context, krb5_auth_context auth_context);
5335 /** Set the replay cache field in a krb5_auth_context structure.
5337 * @param context Context structure
5338 * @param [in,out] auth_context Authentication context
5339 * @param [in] rcache Replay cache haddle
5341 * @retval 0 (always)
5343 krb5_error_code KRB5_CALLCONV
5344 krb5_auth_con_setrcache(krb5_context context, krb5_auth_context auth_context,
5345 krb5_rcache rcache);
5347 /** Retrieve rcache field from a krb5_auth_context structure.
5349 * @param context Context structure
5350 * @param [in] auth_context Authentication context
5351 * @param [out] rcache Replay cache handle
5353 * Set the output @a rcache to @a auth_context->rcache.
5355 * @retval 0 (always)
5357 krb5_error_code KRB5_CALLCONV_WRONG
5358 krb5_auth_con_getrcache(krb5_context context, krb5_auth_context auth_context,
5359 krb5_rcache *rcache);
5361 /** Retrieve an authenticator from the authentication context.
5363 * @param [in] context Context structure
5364 * @param [in] auth_context Authentication context
5365 * @param [out] authenticator Authenticator
5367 * Use krb5_free_authenticator() to free @a authenticator when it is no longer needed
5369 * @sa krb5_copy_authenticator()
5371 * @retval 0 Success. Otherwise - Kerberos error codes
5373 krb5_error_code KRB5_CALLCONV
5374 krb5_auth_con_getauthenticator(krb5_context context, krb5_auth_context auth_context,
5375 krb5_authenticator **authenticator);
5377 /** Set a checksum types field in a krb5_auth_context structure.
5379 * @param context Context structure
5380 * @param [in,out] auth_context Authentication context
5381 * @param [in] cksumtype Checksun type
5383 * Sets @a auth_context->req_cksumtype field to @a cksumtype.
5384 * This function is used to override the default checksum types defined in the
5385 * configuration file.
5387 * @retval 0 (always)
5389 krb5_error_code KRB5_CALLCONV
5390 krb5_auth_con_set_req_cksumtype(krb5_context context, krb5_auth_context auth_context,
5391 krb5_cksumtype cksumtype);
5393 #define KRB5_REALM_BRANCH_CHAR '.'
5396 * end "func-proto.h"
5400 * begin stuff from libos.h
5404 * @brief Read a password from the keyboard input.
5406 * @param context Context structure [input]
5407 * @param prompt First user prompt when reading password [input]
5408 * @param prompt2 Second user prompt, or NULL to read password only once [input]
5409 * @param return_pwd Returned password [output]
5410 * @param size_return During input, maximum size of password;
5411 * during output, total number of bytes in @a return_pwd [input, output]
5413 * The first *size_return bytes of the password entered are
5414 * returned in @a return_pwd. If fewer than *size_return bytes are entered as a password,
5415 * the remainder of @a return_pwd is zeroed.
5416 * Upon success, the total number of bytes filled in is stored in *size_return.
5418 * @a prompt is the prompt for the first reading of a password. It is printed
5419 * to the terminal, and then a password is read from the keyboard. No newlines
5420 * or spaces are emitted between the prompt and the cursor, unless the newline/space
5421 * is included in the prompt.
5423 * If @a prompt2 is a NULL pointer, the password is read only once.
5425 * If @a prompt2 is set, it is used as a prompt to read another
5426 * password in the same manner as described for the first password. After the
5427 * second password is read, the two passwords are compared, and an error is returned if they are not identical.
5429 * Echoing is turned off when the password is read.
5434 * Error in reading or verifying the password
5436 * Kerberos error codes
5438 krb5_error_code KRB5_CALLCONV
5439 krb5_read_password(krb5_context context,
5440 const char *prompt, const char *prompt2,
5441 char *return_pwd, unsigned int *size_return);
5443 /** Convert a principal name to a local name.
5445 * @param [in] context Context structure
5446 * @param [in] aname Principal name
5447 * @param [in] lnsize_in Maximum length name to be filled into @a lname
5448 * @param [out] lname Local name buffer to be filled in
5450 * If @a aname isn't in one of the local realms an error is returned.
5451 * If @a lnsize_in of @a lname is to small, an error is returned.
5453 * Local names, rather than principal names, can be used by programs that
5454 * translate to an environment-specific name (for example, a user account
5455 * name). The translation is null-terminated in all non-error returns.
5462 * Kerberos error codes
5464 krb5_error_code KRB5_CALLCONV
5465 krb5_aname_to_localname(krb5_context context, krb5_const_principal aname,
5466 int lnsize_in, char *lname);
5468 /** Get the Kerberos realm names for a host.
5470 * @param [in] context Context structure
5471 * @param [in] host Host name
5472 * @param [out] realmsp Pointer to list of realm names
5474 * Fill in @a realmsp with a pointer to an @c argv style list of names,
5475 * terminated with a NULL pointer.
5476 * If there are no known realms for the host, the filled-in pointer is set to NULL.
5478 * If @a host is NULL, the local host's realms are determined.
5480 * Use krb5_free_host_realm() to release @a realmsp when it is no longer needed.
5485 * ENOMEM Insufficient memory
5487 * Kerberos error codes
5489 krb5_error_code KRB5_CALLCONV
5490 krb5_get_host_realm(krb5_context context, const char *host, char ***realmsp);
5494 * @param context Context structure [input, output]
5498 * @todo part of referrals support? param descriptions? added pointer descr.
5501 krb5_error_code KRB5_CALLCONV
5502 krb5_get_fallback_host_realm(krb5_context context,
5503 krb5_data *hdata, char ***realmsp);
5505 /** Free the memory allocated by krb5_get_host_realm().
5507 * @param context Context structure
5508 * @param [in] realmlist List of the realm names to be released
5513 * Kerberos error codes
5515 krb5_error_code KRB5_CALLCONV
5516 krb5_free_host_realm(krb5_context context, char *const *realmlist);
5518 /** Determine if the principal is authorized to log in as a local user.
5520 * @param [in] context Context structure
5521 * @param [in] principal Principal name
5522 * @param [in] luser Local username
5524 * Determine whether the @a principal is authorized to log in
5525 * as a local user @a luser
5527 * If there is either no local account for @a luser or @a principal does not
5528 * match luser@realm for any default relam or it is not recorded in the existing
5529 * .k5login, the @a luser is not authorized to log into an account.
5532 * TRUE User is authorized to log in; FALSE otherwise
5534 krb5_boolean KRB5_CALLCONV
5535 krb5_kuserok(krb5_context context, krb5_principal principal, const char *luser);
5537 /** Generate a full IP address from @a address and port.
5539 * @param [in] context Context structure
5540 * @param [in,out] auth_context Authentication context to be updated with
5541 * new local and remote addresses.
5542 * @param [in] infd Input socket file descriptor
5543 * @param [in] flags Input flags, defined in @c KRB\$ROOT:[INCLUDE]KRB5.
5545 * The values for the symbols can be OR'd together. Valid values are:
5547 * @li @c KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR
5548 * @li @c KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR
5549 * @li @c KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR
5550 * @li @c KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR
5552 * @retval 0 Success; Otherwise - Kerberos error codes
5554 krb5_error_code KRB5_CALLCONV
5555 krb5_auth_con_genaddrs(krb5_context context, krb5_auth_context auth_context,
5556 int infd, int flags);
5558 /** Set time offset field in a krb5_context structure.
5560 * @param [in] context Context structure
5561 * @param [in] seconds Number of seconds to set in @c time_offset
5562 * field in @a context
5563 * @param [in] microseconds Number of microseconds to set in @c usec_offset
5564 * field in @a context
5566 * Take the @a real @a time as input, and set the time offset fields in the
5567 * context structure so the @c krb5_time routines return the correct time,
5568 * as corrected by the difference between the system time and the @a real @a time as passed to this routine.
5570 * Make sure to free the allocated memory when it is no longer needed.
5572 * @retval 0 Success; Otherwise - Kerberos error codes
5574 krb5_error_code KRB5_CALLCONV
5575 krb5_set_real_time(krb5_context context, krb5_timestamp seconds,
5576 krb5_int32 microseconds);
5578 /** Return the time offsets from the os context.
5580 * @param [in] context Context structure
5581 * @param [out] seconds Time offset from the OS context, seconds portion
5582 * @param [out] microseconds Time offset from the OS context, microseconds portion
5584 * This function returns the time offsets from @a context->os_context.
5586 * @retval 0 Success; Otherwise - Kerberos error codes
5588 krb5_error_code KRB5_CALLCONV
5589 krb5_get_time_offsets(krb5_context context, krb5_timestamp *seconds, krb5_int32 *microseconds);
5592 /** Convert a string to an encryption type.
5594 * @param [in] string String to convert to an encryption type
5595 * @param [out] enctypep Encryption type to be filled in
5597 * @retval 0 Success; Otherwise - EINVAL
5599 krb5_error_code KRB5_CALLCONV
5600 krb5_string_to_enctype(char *string, krb5_enctype *enctypep);
5602 /** Convert a string to a salt type.
5604 * @param [in] string String to convert to an encryption type
5605 * @param [out] salttypep Salt type to be filled in
5607 * @retval 0 Success; Otherwise - EINVAL
5609 krb5_error_code KRB5_CALLCONV
5610 krb5_string_to_salttype(char *string, krb5_int32 *salttypep);
5612 /** Convert a string to a checksum type.
5614 * @param [in] string String to be converted
5615 * @param [out] cksumtypep Checksum type to be filled in
5617 * @retval 0 Success; Otherwise - EINVAL
5619 krb5_error_code KRB5_CALLCONV
5620 krb5_string_to_cksumtype(char *string, krb5_cksumtype *cksumtypep);
5622 /** Convert a string to a timestamp.
5624 * @param [in] string String to be converted
5625 * @param [out] timestampp Pointer to timestamp
5627 * @retval 0 Success; Otherwise - EINVAL
5629 krb5_error_code KRB5_CALLCONV
5630 krb5_string_to_timestamp(char *string, krb5_timestamp *timestampp);
5632 /** Convert a string to a delta time value.
5634 * @param [in] string String to be converted
5635 * @param [out] deltatp Delta time to be filled in
5637 * @retval 0 Success; Otherwise - KRB5_DELTAT_BADFORMAT
5639 krb5_error_code KRB5_CALLCONV
5640 krb5_string_to_deltat(char *string, krb5_deltat *deltatp);
5642 /** Convert a Kerberos encryption type value to a string.
5644 * @param [in] enctype Encrytion type value to convert
5645 * @param [out] buffer Buffer to hold encryption type string
5646 * @param [in] buflen Maximum length of the string that can fit in @a buffer
5648 * @retval 0 Success; Otherwise - Kerberos error codes
5650 krb5_error_code KRB5_CALLCONV
5651 krb5_enctype_to_string(krb5_enctype enctype, char *buffer, size_t buflen);
5653 /** Convert a Kerberos encryption type value to a name
5655 * @param [in] enctype Encrytion type value to convert
5656 * @param [in] shortest Flag
5657 * @param [out] buffer Buffer to hold encryption type string
5658 * @param [in] buflen Maximum length of the string that can fit in @a buffer
5660 * If @a shortest is FALSE, this function returns the enctype's canonical name
5661 * (like "aes128-cts-hmac-sha1-96"). If @a shortest is TRUE, it return the enctype's
5662 * shortest alias (like "aes128-cts").
5664 * @retval 0 Success; Otherwise - Kerberos error codes
5666 krb5_error_code KRB5_CALLCONV
5667 krb5_enctype_to_name(krb5_enctype enctype, krb5_boolean shortest,
5668 char *buffer, size_t buflen);
5670 /** Convert a @a salttype to a string.
5672 * @param [in] salttype Salttype to convert
5673 * @param [out] buffer Buffer to receive the converted string
5674 * @param [in] buflen Length of @a buffer
5676 * @retval 0 Success; Otherwise - Kerberos error codes
5678 krb5_error_code KRB5_CALLCONV
5679 krb5_salttype_to_string(krb5_int32 salttype, char *buffer, size_t buflen);
5681 /** Convert a checksum type to a string.
5683 * @param [in] cksumtype Checksum type to be converted
5684 * @param [out] buffer Buffer to hold converted checksum type
5685 * @param [in] buflen Maximum length of @a buffer
5687 * The string is returned in the locale's appropriate date and time representation.
5689 * @retval 0 Success; Otherwise - Kerberos error codes
5691 krb5_error_code KRB5_CALLCONV
5692 krb5_cksumtype_to_string(krb5_cksumtype cksumtype, char *buffer, size_t buflen);
5694 /** Convert a timestamp to a string.
5696 * @param [in] timestamp Timestamp to be converted
5697 * @param [out] buffer Buffer to hold converted timestamp
5698 * @param [in] buflen Maximum length of buffer
5700 * The string is returned in the locale's appropriate date and time representation.
5702 * @retval 0 Success; Otherwise - Kerberos error codes
5704 krb5_error_code KRB5_CALLCONV
5705 krb5_timestamp_to_string(krb5_timestamp timestamp, char *buffer, size_t buflen);
5707 /** Convert a timestamp to a string, allowing optional padding in the output buffer.
5709 * @param [in] timestamp Timestamp to convert
5710 * @param [out] buffer Buffer to hold the converted timestamp
5711 * @param [in] buflen Length of buffer
5712 * @param [in] pad Optional value to pad @a buffer
5713 * if converted timestamp does not fill it
5715 * This function also tries multiple possible formats if the default
5716 * locale-specific fails.
5718 * @retval 0 Success; Otherwise - Kerberos error codes
5720 krb5_error_code KRB5_CALLCONV
5721 krb5_timestamp_to_sfstring(krb5_timestamp timestamp, char *buffer,
5722 size_t buflen, char *pad);
5724 /** Convert a relative time value to a string.
5726 * @param [in] deltat Relative time value to convert
5727 * @param [out] buffer Buffer to hold time string
5728 * @param [in] buflen Maximum length of string that fits in @a buffer
5730 * @retval 0 Success; Otherwise - Kerberos error codes
5732 krb5_error_code KRB5_CALLCONV
5733 krb5_deltat_to_string(krb5_deltat deltat, char *buffer, size_t buflen);
5735 /* The name of the Kerberos ticket granting service... and its size */
5736 #define KRB5_TGS_NAME "krbtgt"
5737 #define KRB5_TGS_NAME_SIZE 6
5739 /* flags for recvauth */
5740 #define KRB5_RECVAUTH_SKIP_VERSION 0x0001
5741 #define KRB5_RECVAUTH_BADAUTHVERS 0x0002
5742 /* initial ticket api functions */
5744 /** Text for prompt used in prompter callback function. */
5745 typedef struct _krb5_prompt {
5746 char *prompt; /**< the prompt to show to the user */
5747 int hidden; /**< boolean; informative prompt or hidden (as for PIN or OTP) */
5748 krb5_data *reply; /**< must be allocated before call to any prompt routine */
5752 * @brief Pointer to a prompter callback function.
5754 typedef krb5_error_code
5755 (KRB5_CALLCONV *krb5_prompter_fct)(krb5_context context, void *data,
5756 const char *name, const char *banner,
5757 int num_prompts, krb5_prompt prompts[]);
5760 * @brief Prompt user for password.
5762 * @param context Context structure [input, output]
5763 * @param data Unused
5764 * @param name Name to output during prompt [input]
5765 * @param banner Banner to output during prompt [input]
5766 * @param num_prompts Number of prompts passed in @a prompts [input]
5767 * @param prompts Array of krb5_prompt structures containing output prompts and replies [input, output]
5769 * Prompt the user for the password associated with the given principal name,
5770 * and set the reply field of the @a prompts argument to the password input. The hidden
5771 * flag in the @c prompts structure controls whether the password input is echoed back
5777 * Kerberos error codes
5780 krb5_error_code KRB5_CALLCONV
5781 krb5_prompter_posix(krb5_context context, void *data, const char *name,
5782 const char *banner, int num_prompts,
5783 krb5_prompt prompts[]);
5786 * @brief Store options for @c _krb5_get_init_creds
5788 typedef struct _krb5_get_init_creds_opt {
5790 krb5_deltat tkt_life;
5791 krb5_deltat renew_life;
5794 krb5_enctype *etype_list;
5795 int etype_list_length;
5796 krb5_address **address_list;
5797 krb5_preauthtype *preauth_list;
5798 int preauth_list_length;
5800 } krb5_get_init_creds_opt;
5802 #define KRB5_GET_INIT_CREDS_OPT_TKT_LIFE 0x0001
5803 #define KRB5_GET_INIT_CREDS_OPT_RENEW_LIFE 0x0002
5804 #define KRB5_GET_INIT_CREDS_OPT_FORWARDABLE 0x0004
5805 #define KRB5_GET_INIT_CREDS_OPT_PROXIABLE 0x0008
5806 #define KRB5_GET_INIT_CREDS_OPT_ETYPE_LIST 0x0010
5807 #define KRB5_GET_INIT_CREDS_OPT_ADDRESS_LIST 0x0020
5808 #define KRB5_GET_INIT_CREDS_OPT_PREAUTH_LIST 0x0040
5809 #define KRB5_GET_INIT_CREDS_OPT_SALT 0x0080
5810 #define KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT 0x0100
5811 #define KRB5_GET_INIT_CREDS_OPT_CANONICALIZE 0x0200
5812 #define KRB5_GET_INIT_CREDS_OPT_ANONYMOUS 0x0400
5815 /** Allocate a new extended krb5_get_init_creds_opt structure.
5817 * @param [in,out] context Context structure
5818 * @param [out] opt Pointer to @c _krb5_get_init_creds_opt structure to be allocated
5820 * The caller of this function must call krb5_get_init_creds_opt_free() to free @a opt
5821 * when it is no longer needed.
5823 * @retval 0 - Success; Kerberos errors otherwise.
5825 krb5_error_code KRB5_CALLCONV
5826 krb5_get_init_creds_opt_alloc(krb5_context context,
5827 krb5_get_init_creds_opt **opt);
5829 /** Free an extended krb5_get_init_creds_opt structure.
5831 * @param context Context structure
5832 * @param [in] opt Pointer to @c _krb5_get_init_creds_opt structure to be freed
5834 * @sa krb5_get_init_creds_opt_alloc()
5837 krb5_get_init_creds_opt_free(krb5_context context,
5838 krb5_get_init_creds_opt *opt);
5840 /** Initialize a krb5_get_init_creds_opt structure.
5842 * @param [in,out] opt Pointer to krb5_get_init_creds_opt structure to be initialized
5844 * @warning Callers MUST NOT call krb5_get_init_creds_opt_init() after allocating an
5845 * krb5_get_init_creds_opt structure using krb5_get_init_creds_opt_alloc().
5846 * To do so will introduce memory leaks.
5848 * Sets @a opt->flag to KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT
5851 krb5_get_init_creds_opt_init(krb5_get_init_creds_opt *opt);
5853 /** Initialize the ticket lifetime field in krb5_get_init_creds_opt structure.
5855 * @param [in,out] opt Options
5856 * @param [in] tkt_life Ticket lifetime
5858 * Sets KRB5_GET_INIT_CREDS_OPT_TKT_LIFE flag in @a opt
5860 * The @a opt pointer supplied to this function must have been
5861 * obtained using krb5_get_init_creds_opt_alloc()
5864 krb5_get_init_creds_opt_set_tkt_life(krb5_get_init_creds_opt *opt,
5865 krb5_deltat tkt_life);
5867 /** Set the ticket renewal lifetime field in krb5_get_init_creds_opt structure.
5869 * @param [in,out] opt Pointer to @a options field
5870 * @param [in] renew_life Ticket renewal lifetime
5872 * Sets KRB5_GET_INIT_CREDS_OPT_iRENEW_LIFE flag in @a opt
5874 * The @a opt pointer supplied to this function must have been
5875 * obtained using krb5_get_init_creds_opt_alloc()
5878 krb5_get_init_creds_opt_set_renew_life(krb5_get_init_creds_opt *opt,
5879 krb5_deltat renew_life);
5881 /** Set the forwardable field in krb5_get_init_creds_opt structure.
5883 * @param [in,out] opt Options
5884 * @param [in] forwardable Flag indicating whether credentials are forwardable
5886 * Sets KRB5_GET_INIT_CREDS_OPT_FORWARDABLE flag in @a opt
5887 * The @a opt pointer supplied to this function must have been
5888 * obtained using krb5_get_init_creds_opt_alloc()
5891 krb5_get_init_creds_opt_set_forwardable(krb5_get_init_creds_opt *opt,
5894 /** Set the proxiable field in krb5_get_init_creds_opt structure.
5896 * @param [in,out] opt Options
5897 * @param [in] proxiable Flag indicating whether credentials are proxiable
5899 * Sets KRB5_GET_INIT_CREDS_OPT_PROXYABLE flag in @a opt
5900 * The @a opt pointer supplied to this function must have been
5901 * obtained using krb5_get_init_creds_opt_alloc()
5904 krb5_get_init_creds_opt_set_proxiable(krb5_get_init_creds_opt *opt,
5907 /** Set canonicalize flag in krb5_get_init_creds_opt structure.
5909 * @param [in,out] opt Options
5910 * @param [in] canonicalize Boolean flag
5912 * Sets KRB5_GET_INIT_CREDS_OPT_CANONICALIZE flag in @a opt
5914 * The @a opt pointer supplied to this function must have been
5915 * obtained using krb5_get_init_creds_opt_alloc()
5918 krb5_get_init_creds_opt_set_canonicalize(krb5_get_init_creds_opt *opt,
5921 /** Set an anonymous flag in krb5_get_init_creds_opt structure.
5923 * @param [in,out] opt Options
5924 * @param [in] anonymous Boolean flag
5926 * This function may be used to request anonymous credentials from the KDC
5927 * by setting @a anonymous to non-zero.
5929 * Note that anonymous credentials are only a request; clients must verify that
5930 * credentials are anonymous if that is a requirement.
5932 * Sets KRB5_GET_INIT_CREDS_OPT_ANONYMOUS flag in @a opt.
5934 * The @a opt pointer supplied to this function must have been
5935 * obtained using krb5_get_init_creds_opt_alloc()
5938 krb5_get_init_creds_opt_set_anonymous(krb5_get_init_creds_opt *opt,
5941 /** Set an encryption list field in the krb5_get_init_creds_opt structure.
5943 * @param [in,out] opt Options
5944 * @param [in] etype_list Pointer to the encryption type to set
5945 * @param [in] etype_list_length Length of the etype_list field
5947 * The @a opt pointer supplied to this function must have been
5948 * obtained using krb5_get_init_creds_opt_alloc()
5951 krb5_get_init_creds_opt_set_etype_list(krb5_get_init_creds_opt *opt,
5952 krb5_enctype *etype_list,
5953 int etype_list_length);
5955 /** Set an address list field in krb5_get_init_creds_opt structure.
5957 * @param [in,out] opt Options
5958 * @param [in] addresses Addresses to be stored in the ticket
5960 * Sets KRB5_GET_INIT_CREDS_OPT_ADDRESS_LIST flag in @a opt
5963 krb5_get_init_creds_opt_set_address_list(krb5_get_init_creds_opt *opt,
5964 krb5_address **addresses);
5966 /** Set the preauth_list field in krb5_get_init_creds_opt structure.
5968 * @param [in,out] opt Options
5969 * @param [in] preauth_list Pointer to Pre-athentication type
5970 * @param [in] preauth_list_length Length of @a preauth_list field
5972 * Sets KRB5_GET_INIT_CREDS_OPT_PREAUTH_LIST flag in @a opt
5974 * The @a opt pointer supplied to this function must have been
5975 * obtained using krb5_get_init_creds_opt_alloc()
5978 krb5_get_init_creds_opt_set_preauth_list(krb5_get_init_creds_opt *opt,
5979 krb5_preauthtype *preauth_list,
5980 int preauth_list_length);
5982 /** Set prompt for a salt field in krb5_get_init_creds_opt structure.
5984 * @param [in,out] opt Options
5985 * @param [in] salt Salt data
5987 * Sets KRB5_GET_INIT_CREDS_OPT_SALT flag in @a opt.
5990 krb5_get_init_creds_opt_set_salt(krb5_get_init_creds_opt *opt,
5993 /** Set prompt for a password flag in krb5_get_init_creds_opt structure.
5995 * @param [in,out] opt Options
5996 * @param [in] prompt Boolean prompt to change password
5998 * Sets KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT flag in @a opt.
6001 krb5_get_init_creds_opt_set_change_password_prompt(krb5_get_init_creds_opt *opt,
6004 /** Generic preauth option attribute/value pairs */
6005 typedef struct _krb5_gic_opt_pa_data {
6008 } krb5_gic_opt_pa_data;
6010 /** Feed preauth plugins with the given options.
6012 * @param [in,out] context Context structure
6013 * @param [in] opt Pre options
6014 * @param [in] attr Pre attribute
6015 * @param [in] value Pre value
6017 * This function allows the caller to supply options to preauth
6018 * plugins. Preauth plugin modules are given a chance to look
6019 * at each option at the time this function is called in order
6020 * to check the validity of the option.
6021 * The @a opt pointer supplied to this function must have been
6022 * obtained using krb5_get_init_creds_opt_alloc()
6024 krb5_error_code KRB5_CALLCONV
6025 krb5_get_init_creds_opt_set_pa(krb5_context context,
6026 krb5_get_init_creds_opt *opt, const char *attr,
6029 /** Set a location of FAST cache containing TGT based on cache name.
6031 * @param [in,out] context Context structure
6032 * @param [in,out] opt Options
6033 * @param [in] fast_ccache_name Credential cache name
6035 * If the @a fast_ccache_name is set, then FAST may be
6036 * required by the client library. Starting from MIT Kerberos version 1.8
6037 * FAST is used if available; krb5_get_init_creds_opt_set_fast_flags()
6038 * may be used to require that the request fail is FAST is unavailable.
6039 * In version 1.7 setting the fast ccache at all required that FAST
6040 * be present or the request would fail.
6041 * The @a opt pointer supplied to this function must have been
6042 * obtained using krb5_get_init_creds_opt_alloc()
6044 krb5_error_code KRB5_CALLCONV
6045 krb5_get_init_creds_opt_set_fast_ccache_name(krb5_context context,
6046 krb5_get_init_creds_opt *opt,
6047 const char *fast_ccache_name);
6049 /** Set a location of FAST cache containing TGT based on krb5_ccache object.
6051 * @param [in,out] context Context structure
6052 * @param [in,out] opt Options
6053 * @param [in] fast_ccache_name Credential cache handle
6055 * Set the FAST ccache name as in krb5_get_init_creds_opt_set_fast_ccache_name(),
6056 * but using a krb5_ccache rather than a name.
6057 * The @a opt pointer supplied to this function must have been
6058 * obtained using krb5_get_init_creds_opt_alloc()
6060 krb5_error_code KRB5_CALLCONV
6061 krb5_get_init_creds_opt_set_fast_ccache(krb5_context context,
6062 krb5_get_init_creds_opt *opt,
6063 krb5_ccache fast_ccache_name);
6065 /** Set an output credentials cache in krb5_get_init_creds_opt structure.
6067 * @param [in,out] context Context structure
6068 * @param [in,out] opt Options
6069 * @param [in] ccache Credential cache to use
6071 * If set, then the krb5_get_init_creds family of APIs will write out credentials
6072 * to the given ccache. Setting an output ccache is desirable both because it
6073 * simplifies calling code and because it permits the krb5_get_init_creds APIs
6074 * to write out configuration information about the realm to the ccache.
6076 krb5_error_code KRB5_CALLCONV
6077 krb5_get_init_creds_opt_set_out_ccache(krb5_context context,
6078 krb5_get_init_creds_opt *opt,
6079 krb5_ccache ccache);
6081 /** Store FAST flags in krb5_get_init_creds_opt structure.
6083 * @param [in,out] context Context structure
6084 * @param [in,out] opt Options
6085 * @param [in] flags FAST flags (for example, KRB5_FAST_REQUIRED)
6087 * This function may be used to require that the request fail if FAST is unavailable.
6090 * 0 - Success; Kerberos errors otherwise.
6092 krb5_error_code KRB5_CALLCONV
6093 krb5_get_init_creds_opt_set_fast_flags(krb5_context context,
6094 krb5_get_init_creds_opt *opt,
6097 /** Obtain FAST flags from krb5_get_init_creds_opt structure.
6099 * @param [in,out] context Context structure
6100 * @param [in] opt Options
6101 * @param [out] out_flags FAST flags
6103 * Get FAST @a out_flags from @a opt
6104 * This function may be used to verify if KDC supports FAST.
6107 * 0 - Success; Kerberos errors otherwise.
6109 krb5_error_code KRB5_CALLCONV
6110 krb5_get_init_creds_opt_get_fast_flags(krb5_context context,
6111 krb5_get_init_creds_opt *opt,
6112 krb5_flags *out_flags);
6115 #define KRB5_FAST_REQUIRED 1l<<0 /**< Require KDC to support FAST*/
6118 (KRB5_CALLCONV *krb5_expire_callback_func)(krb5_context context, void *data,
6119 krb5_timestamp password_expiration,
6120 krb5_timestamp account_expiration,
6121 krb5_boolean is_last_req);
6123 /** Set an expire callback in extended krb5_get_init_creds_opt structure.
6125 * @param [in,out] context Context structure
6126 * @param [in,out] opt Options structure
6127 * @param [in] cb Callback function
6128 * @param [in] data Data
6130 * Set a callback to receive password and account expiration times.
6132 * This option only applies to krb5_get_init_creds_password(). @a cb will be
6133 * invoked if and only if credentials are successfully acquired. The callback
6134 * will receive the @a context from the krb5_get_init_creds_password() call and
6135 * the @a data argument supplied with this API. The remaining arguments should
6136 * be interpreted as follows:
6138 * If @a is_last_req is true, then the KDC reply contained last-req entries
6139 * which unambiguously indicated the password expiration, account expiration,
6140 * or both. (If either value was not present, the corresponding argument will
6141 * be 0.) Furthermore, a non-zero @a password_expiration should be taken as a
6142 * suggestion from the KDC that a warning be displayed.
6144 * If @a is_last_req is false, then @a account_expiration will be 0 and @a
6145 * password_expiration will contain the expiration time of either the password
6146 * or account, or 0 if no expiration time was indicated in the KDC reply. The
6147 * callback should independently decide whether to display a password
6148 * expiration warning.
6150 * Note that @a cb may be invoked even if credentials are being acquired for
6151 * the kadmin/changepw service in order to change the password. It is the
6152 * caller's responsibility to avoid displaying a password expiry warning in
6155 * @warning Setting an expire callback with this API will cause
6156 * krb5_get_init_creds_password() not to send password expiry warnings to the
6157 * prompter, as it ordinarily may.
6159 krb5_error_code KRB5_CALLCONV
6160 krb5_get_init_creds_opt_set_expire_callback(krb5_context context,
6161 krb5_get_init_creds_opt *opt,
6162 krb5_expire_callback_func cb,
6165 /** Get initial credentials using a password.
6167 * @param [in] context Context structure
6168 * @param [in,out] creds Credentials structure to be filled in
6169 * @param [in] client Client principal
6170 * @param [in] password Password associated with initial credentials
6171 * @param [in] prompter Pointer to password prompt routine
6172 * @param [in] data Data for password prompt routine
6173 * @param [in] start_time Time when a ticket should become valid; 0 means from now
6174 * @param [in] in_tkt_service Service name to use while getting initial credentials
6175 * @param [in] k5_gic_options Flags and options
6177 * This function requests KDC for an initial credentials for @a client using
6180 * @sa krb5_verify_init_creds()
6185 * EINVAL Invalid argument
6187 * KRB5_KDC_UNREACH Cannot contact any KDC for requested realm
6189 * KRB5_PREAUTH_FAILED Generic Pre-athentication failure
6191 * KRB5_LIBOS_PWDINTR Password read interrupted
6193 * KRB5_REALM_CANT_RESOLVE Cannot resolve network address for KDC in requested realm
6195 * KRB5KDC_ERR_KEY_EXP Password has expired
6197 * KRB5_LIBOS_BADPWDMATCH Password mismatch
6199 * KRB5_CHPW_PWDNULL New password cannot be zero length
6201 * KRB5_CHPW_FAIL Password change failed
6203 * Kerberos error codes
6205 krb5_error_code KRB5_CALLCONV
6206 krb5_get_init_creds_password(krb5_context context, krb5_creds *creds,
6207 krb5_principal client, char *password,
6208 krb5_prompter_fct prompter, void *data,
6209 krb5_deltat start_time, char *in_tkt_service,
6210 krb5_get_init_creds_opt *k5_gic_options);
6212 struct _krb5_init_creds_context;
6213 typedef struct _krb5_init_creds_context *krb5_init_creds_context;
6215 #define KRB5_INIT_CREDS_STEP_FLAG_CONTINUE 0x1 /* More responses needed */
6217 /** Free an initial credentials asynchronous context.
6219 * @param [in] context A krb5 library context
6220 * @param [in] ctx Initial credentials context to free.
6223 krb5_init_creds_free(krb5_context context, krb5_init_creds_context ctx);
6225 /** Acquire credentials asynchronously.
6227 * @param [in] context A krb5 library context
6228 * @param [in,out] ctx Initial credentials context
6230 * @retval 0 Success; Otherwise - Kerberos error codes
6232 krb5_error_code KRB5_CALLCONV
6233 krb5_init_creds_get(krb5_context context, krb5_init_creds_context ctx);
6235 /** Copy the acquired initial credentials contents.
6237 * @param [in] context A krb5 library context
6238 * @param [in] ctx Initial credentials context
6239 * @param [out] creds Copy of @a ctx->cred
6241 * This function copies the acquired initial credentials from
6242 * @a ctx->cred into @a creds.
6243 * Use krb5_free_cred_contents() to free @a creds when it is no longer needed.
6245 * @retval 0 Success; Otherwise - Kerberos error codes
6247 krb5_error_code KRB5_CALLCONV
6248 krb5_init_creds_get_creds(krb5_context context, krb5_init_creds_context ctx,
6251 /** Get the last error data from KDC while acquiring initial credentials.
6253 * @param [in] context A krb5 library context
6254 * @param [in] ctx Initial credentials context
6255 * @param [out] error If non-null, contains error packet returned from KDC
6257 * @retval 0 Success; Otherwise - Kerberos error codes
6259 krb5_error_code KRB5_CALLCONV
6260 krb5_init_creds_get_error(krb5_context context, krb5_init_creds_context ctx,
6261 krb5_error **error);
6263 /** Create a context for acquiring initial credentials.
6265 * @param [in] context A krb5 library context
6266 * @param [in] client Client principal to get initial credentials for.
6267 * If NULL - the default principal is used
6268 * @param [in] prompter Prompter
6269 * @param [in] data Prompter data
6270 * @param [in] start_time Time when credentials should become valid;
6272 * @param [in] options KRB5_GET_INIT_CREDS_OPT_ options for this request.
6273 * If NULL - the default options are used
6274 * (see krb5_get_init_creds_opt_init())
6275 * @param [out] ctx A new initial credentials context.
6277 * This function initializes a new context for acquiring initial credentials
6279 * Use krb5_init_creds_free() to free @a ctx when it is no longer needed.
6281 * @retval 0 Success; Otherwise - Kerberos error codes
6283 krb5_error_code KRB5_CALLCONV
6284 krb5_init_creds_init(krb5_context context, krb5_principal client,
6285 krb5_prompter_fct prompter, void *data,
6286 krb5_deltat start_time, krb5_get_init_creds_opt *options,
6287 krb5_init_creds_context *ctx);
6289 /** Specify a keytab to use for acquiring initial credentials.
6291 * @param [in] context A krb5 library context
6292 * @param [in,out] ctx Initial credentials context
6293 * @param [in] keytab Key table handle
6295 * @retval 0 Success; Otherwise - Kerberos error codes
6297 krb5_error_code KRB5_CALLCONV
6298 krb5_init_creds_set_keytab(krb5_context context, krb5_init_creds_context ctx,
6299 krb5_keytab keytab);
6301 /** Perform the next step of asynchronous initial credentials acquisition.
6303 * @param [in] context A krb5 library context
6304 * @param [in,out] ctx Initial credentials context
6305 * @param [in] in KDC response (empty on the first call)
6306 * @param [out] out Buffer to be sent by the caller to the KDC
6307 * for the indicated @a realm.
6308 * @param [out] realm The realm for which the next request should be sent
6309 * @param [out] flags Indicates whether more responses are needed
6310 * (see KRB5_INIT_CREDS_STEP_FLAG_CONTINUE )
6312 * Once the credentials have been acquired, the @a out buffer is empty and
6313 * @a flags is set to 0. If the request should be retried with TCP,
6314 * KRB5KRB_ERR_RESPONSE_TOO_BIG is returned.
6316 * @retval 0 Success; Otherwise - Kerberos error codes
6318 krb5_error_code KRB5_CALLCONV
6319 krb5_init_creds_step(krb5_context context, krb5_init_creds_context ctx,
6320 krb5_data *in, krb5_data *out, krb5_data *realm,
6321 unsigned int *flags);
6323 /** Set a password for acquiring initial credentials.
6325 * @param [in] context A krb5 library context
6326 * @param [in,out] ctx Initial credentials context
6327 * @param [in] password Password
6329 * @retval 0 Success; Otherwise - Kerberos error codes
6331 krb5_error_code KRB5_CALLCONV
6332 krb5_init_creds_set_password(krb5_context context, krb5_init_creds_context ctx,
6333 const char *password);
6335 /** Specify a requested service for the initial credentials.
6337 * @param [in] context A krb5 library context
6338 * @param [in,out] ctx Initial credentials context
6339 * @param [in] service Requested service
6341 * The old @a ctx->in_tkt_service is overriden by the new @a service.
6343 * @retval 0 Success; Otherwise - Kerberos error codes
6345 krb5_error_code KRB5_CALLCONV
6346 krb5_init_creds_set_service(krb5_context context, krb5_init_creds_context ctx,
6347 const char *service);
6349 /** Retrieve the ticket times from the initial credentials context.
6351 * @param [in] context A krb5 library context
6352 * @param [in] ctx Initial credentials context
6353 * @param [out] times Ticket times for the acquired credentials
6355 * @retval 0 Success; Otherwise - Kerberos error codes
6357 krb5_error_code KRB5_CALLCONV
6358 krb5_init_creds_get_times(krb5_context context, krb5_init_creds_context ctx,
6359 krb5_ticket_times *times);
6361 struct _krb5_tkt_creds_context;
6362 typedef struct _krb5_tkt_creds_context *krb5_tkt_creds_context;
6365 * Create a context to get credentials from a KDC's Ticket Granting Service.
6367 * @param[in] context A krb5 library context (see krb5_init_context())
6368 * @param[in] ccache A credentials cache containing the desired credentials
6369 * or a Ticket Granting Ticket (TGT) for the client realm.
6370 * TGT and service credentials may be stored into this
6371 * cache as they are acquired.
6372 * @param[in] creds Input credentials
6373 * @param[in] options KRB5_GC_* options for this request.
6374 * @param[out] ctx The TGS acquisition context.
6376 * The resulting TGS acquisition context can be used asynchronously with
6377 * krb5_tkt_creds_step() or synchronously with krb5_tkt_creds_get(). See also
6378 * krb5_get_credentials() for synchronous use.
6380 * Use krb5_tkt_creds_free() to free @a ctx when it is no longer needed.
6382 * @retval 0 Success; Otherwise - Kerberos error codes
6384 krb5_error_code KRB5_CALLCONV
6385 krb5_tkt_creds_init(krb5_context context, krb5_ccache ccache,
6386 krb5_creds *creds, krb5_flags options,
6387 krb5_tkt_creds_context *ctx);
6390 * Synchronously obtain credentials within an acquisition context.
6392 * @param[in] context A krb5 library context (see krb5_init_context())
6393 * @param[in] ctx A TGS acquisition context (see krb5_tkt_creds_init())
6395 * This function repeatedly generates requests, sends them to the appropriate
6396 * realms' KDCs, and processes the replies until credentials are available for
6397 * retrieval with krb5_tkt_creds_get_creds().
6399 * @retval 0 Success; Otherwise - Kerberos error codes
6401 krb5_error_code KRB5_CALLCONV
6402 krb5_tkt_creds_get(krb5_context context, krb5_tkt_creds_context ctx);
6405 * Retrieve credentials from an acquisition context, filling in @a creds.
6407 * @param[in] context A krb5 library context (see krb5_init_context())
6408 * @param[in] ctx A TGS acquisition context (see krb5_tkt_creds_init())
6409 * @param[out] creds The acquired credentials
6411 * The acquisition context must have completed obtaining credentials via either
6412 * krb5_tkt_creds_get() or krb5_tkt_creds_step().
6414 * @retval 0 Success; Otherwise - Kerberos error codes
6416 krb5_error_code KRB5_CALLCONV
6417 krb5_tkt_creds_get_creds(krb5_context context, krb5_tkt_creds_context ctx,
6421 * Release the resources used by an acquisition context.
6423 * @param[in] context A krb5 library context (see krb5_init_context())
6424 * @param[in] ctx A TGS acquisition context (see krb5_tkt_creds_init())
6427 krb5_tkt_creds_free(krb5_context context, krb5_tkt_creds_context ctx);
6429 #define KRB5_TKT_CREDS_STEP_FLAG_CONTINUE 0x1 /* More responses needed. */
6432 * Process a response and generate the next request to acquire credentials.
6434 * @param[in] context A krb5 library context (see krb5_init_context())
6435 * @param[in] ctx A TGS acquisition context (see krb5_tkt_creds_init())
6436 * @param[in] in The last response (empty or NULL for first call)
6437 * @param[out] out The next request to be sent
6438 * @param[out] realm The realm to which the next request should be sent
6439 * @param[out] flags Indicates whether more responses are needed
6441 * On the first call, @a in should be empty or NULL. If more responses are
6442 * needed, the @a flags output parameter will contain @a
6443 * KRB5_TKT_CREDS_STEP_FLAG_CONTINUE. In that case, the caller must transport
6444 * @a out to a KDC for @a realm and receive a response, which should be
6445 * provided as @a in to the next call.
6447 * @retval 0 Success; Otherwise - Kerberos error codes
6449 krb5_error_code KRB5_CALLCONV
6450 krb5_tkt_creds_step(krb5_context context, krb5_tkt_creds_context ctx,
6451 krb5_data *in, krb5_data *out, krb5_data *realm,
6452 unsigned int *flags);
6455 * Retrieve ticket times for obtained credentials, filling in @a times.
6457 * @param[in] context A krb5 library context (see krb5_init_context())
6458 * @param[in] ctx A TGS acquisition context (see krb5_tkt_creds_init())
6459 * @param[out] times Ticket times for the acquired credentials
6461 * The acquisition context must have completed obtaining credentials via either
6462 * krb5_tkt_creds_get() or krb5_tkt_creds_step().
6464 * @retval 0 Success; Otherwise - Kerberos error codes
6466 krb5_error_code KRB5_CALLCONV
6467 krb5_tkt_creds_get_times(krb5_context context, krb5_tkt_creds_context ctx,
6468 krb5_ticket_times *times);
6470 /** Get initial credentials using a key table.
6472 * @param [in] context Context structure
6473 * @param [in,out] creds Credentials structure to be filled in
6474 * @param [in] client Client principal to get initial credentials for
6475 * @param [in] arg_keytab Key table handle
6476 * @param [in] start_time Time when a ticket should become valid; 0 means from now
6477 * @param [in] in_tkt_service Service name to use while getting initial credentials
6478 * @param [in] k5_gic_options Flags and options
6480 * This function requests initial credentials for @a client from KDC using a key
6481 * stored in @a arg_keytab, or from the default keytab if @a arg_keytab is NULL.
6483 * @sa krb5_verify_init_creds()
6488 * Kerberos error codes
6490 krb5_error_code KRB5_CALLCONV
6491 krb5_get_init_creds_keytab(krb5_context context, krb5_creds *creds,
6492 krb5_principal client, krb5_keytab arg_keytab,
6493 krb5_deltat start_time, char *in_tkt_service,
6494 krb5_get_init_creds_opt *k5_gic_options);
6496 typedef struct _krb5_verify_init_creds_opt {
6498 int ap_req_nofail; /**< boolean */
6499 } krb5_verify_init_creds_opt;
6501 #define KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL 0x0001
6503 /** Initialize a @a flags field in krb5_verify_init_creds_opt structure.
6505 * @param [out] k5_vic_options Pointer to krb5_verify_init_creds_opt structure
6507 * Sets @a k5_vic_options flags fiels to zero.
6510 krb5_verify_init_creds_opt_init(krb5_verify_init_creds_opt *k5_vic_options);
6512 /** Set a @a ap_req_nofail field in krb5_verify_init_creds_opt structure.
6514 * @param [out] k5_vic_options Pointer to krb5_verify_init_creds_opt structure
6515 * @param [in] ap_req_nofail Boolean value to set for the ap_req_nofail field
6517 * This function sets KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL flag and
6518 * ap_req_nofail field to @a ap_req_nofail in @a k5_vic_options.
6519 * If @a ap_req_nofail is FALSE and keytab is missing (empty or unreadable),
6520 * krb5_verify_init_creds() will succeed even though verification cannot be
6522 * This function may be used to override the krb5 configuration setting for
6523 * verify_ap_req_nofail attribute.
6526 krb5_verify_init_creds_opt_set_ap_req_nofail(krb5_verify_init_creds_opt * k5_vic_options,
6529 /** Verify initial credentials and store them in the credentials cache.
6531 * @param [in] context Context structure
6532 * @param [in] creds Initial credentials to be verified
6533 * @param [in] server_arg Server principal;
6534 * if NULL - use a principal name from @a keytab_arg
6535 * @param [in] keytab_arg Key table to verify @a creds against
6536 * @param [out] ccache_arg Credentials cache to store all fetched from KDC credentials
6537 * if NULL - memory credential will be used and then destroyed.
6538 * @param [in] options Pointer to krb5_verify_init_creds_opt structure
6541 * @sa krb5_verify_init_creds_opt_set_ap_req_nofail() and
6542 * krb5_verify_init_creds_opt_init()
6544 * @retval 0 Success; Otherwise - Kerberos error codes
6546 krb5_error_code KRB5_CALLCONV
6547 krb5_verify_init_creds(krb5_context context, krb5_creds *creds,
6548 krb5_principal server_arg, krb5_keytab keytab_arg,
6549 krb5_ccache *ccache_arg, krb5_verify_init_creds_opt *options);
6551 /** Get validated credentials from the KDC.
6553 * @param [in,out] context Context structure
6554 * @param [out] creds Credential structure to fill in
6555 * @param [in] client Client principal name
6556 * @param [in] ccache Credentials cache
6557 * @param [in] in_tkt_service Principal name of requesting server
6559 * This function gets a validated single service ticket, that is specified as
6560 * @a in_tkt_service parameter, from KDC.
6561 * It uses credentials provided by @a client and @a in_tkt_service to retrieve the
6562 * old existing credentials from @a ccache so they can be used to get a validated
6563 * credential from KDC.
6564 * If @a in_tkt_service is NULL, the TGT name for the client's realm will be used.
6565 * The result is placed in @a creds.
6567 * @sa krb5_get_renewed_creds()
6572 * KRB5_NO_2ND_TKT Request missing second ticket
6574 * KRB5_NO_TKT_SUPPLIED Request did not supply a ticket
6576 * KRB5_PRINC_NOMATCH Requested principal and ticket do not match
6578 * KRB5_KDCREP_MODIFIED KDC reply did not match expectations
6580 * KRB5_KDCREP_SKEW Clock skew too great in KDC reply
6582 * Kerberos error codes
6584 krb5_error_code KRB5_CALLCONV
6585 krb5_get_validated_creds(krb5_context context, krb5_creds *creds,
6586 krb5_principal client, krb5_ccache ccache,
6587 char *in_tkt_service);
6589 /** Get renewed credential from KDC using the existing one.
6591 * @param [in,out] context Context structure
6592 * @param [out] creds Credentials structure to fill in
6593 * @param [in] client Client principal name
6594 * @param [in] ccache Credentials cache
6595 * @param [in] in_tkt_service Principal name of requesting server
6597 * This function gets a renewed single service ticket, that is specified as
6598 * @a in_tkt_service parameter, from KDC.
6599 * It uses credentials provided by @a client and @a in_tkt_service to retrieve the
6600 * old existing credentials from @a ccache so they can be used to get a new
6601 * credential from KDC.
6602 * If @a in_tkt_service is NULL, the TGT name for the client's realm will be used.
6603 * The result is placed in @a creds.
6605 * @sa krb5_get_validated_creds()
6610 * Kerberos error codes
6612 krb5_error_code KRB5_CALLCONV
6613 krb5_get_renewed_creds(krb5_context context, krb5_creds *creds,
6614 krb5_principal client, krb5_ccache ccache,
6615 char *in_tkt_service);
6618 * @brief Decode a formatted ticket.
6620 * @param code Formatted ticket [input]
6621 * @param rep Decoded ticket information [output]
6626 * KRB5KDC_ERR_BAD_PVNO Bad key version number
6628 * Kerberos error codes
6631 krb5_error_code KRB5_CALLCONV
6632 krb5_decode_ticket(const krb5_data *code, krb5_ticket **rep);
6634 /** Retrieve an attribute value from @a appdefaults section of krb5.conf.
6636 * @param [in] context Context structure
6637 * @param [in] appname Application name
6638 * @param [in] realm Realm name
6639 * @param [in] option Option to be checked
6640 * @param [in] default_value Default Boolean value to return if no match is found
6641 * @param [out] ret_value String value of @a option
6643 * This function gets the application defaults for @a option based on the given
6644 * @a appname and/or @a realm.
6646 * @sa krb5_appdefault_boolean()
6649 krb5_appdefault_string(krb5_context context, const char *appname,
6650 const krb5_data *realm, const char *option,
6651 const char *default_value, char ** ret_value);
6653 /** Retrieve a booloean attribute value from @a appdefaults section of krb5.conf.
6655 * @param [in] context Context structure
6656 * @param [in] appname Application name
6657 * @param [in] realm Realm name
6658 * @param [in] option Option to be checked
6659 * @param [in] default_value Default Boolean value to return if no match is found
6660 * @param [out] ret_value Boolean value of @a option
6662 * This function gets the application defaults for @a option based on the given
6663 * @a appname and/or @a realm.
6665 * @sa krb5_appdefault_string()
6668 krb5_appdefault_boolean(krb5_context context, const char *appname,
6669 const krb5_data *realm, const char *option,
6670 int default_value, int *ret_value);
6673 * Prompter enhancements
6676 #define KRB5_PROMPT_TYPE_PASSWORD 0x1
6677 #define KRB5_PROMPT_TYPE_NEW_PASSWORD 0x2
6678 #define KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN 0x3
6679 #define KRB5_PROMPT_TYPE_PREAUTH 0x4
6681 typedef krb5_int32 krb5_prompt_type;
6683 /** Get @a prompt_types field from a context.
6685 * @param [in] context Context structure
6688 * Pointer to the @a krb5_prompt_type field, which contains one
6689 * of the following values:
6690 * @li @c KRB5_PROMPT_TYPE_PASSWORD
6691 * @li @c KRB5_PROMPT_TYPE_NEW_PASSWORD
6692 * @li @c KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN
6693 * @li @c KRB5_PROMPT_TYPE_PREAUTH
6695 krb5_prompt_type* KRB5_CALLCONV
6696 krb5_get_prompt_types(krb5_context context);
6698 /* Error reporting */
6699 /** Set error message state in a context structure.
6701 * @param [in,out] ctx Context structure
6702 * @param [in] code Error code
6703 * @param [in] fmt Error string for the error code
6704 * @param [in] ... printf(3) style parameters
6706 void KRB5_CALLCONV_C
6707 krb5_set_error_message(krb5_context ctx, krb5_error_code code, const char *fmt, ...)
6708 #if !defined(__cplusplus) && (__GNUC__ > 2)
6709 __attribute__((__format__(__printf__, 3, 4)))
6713 /** Set error message state in a context structure using a precomputed va_list.
6715 * @param [in,out] ctx Context structure
6716 * @param [in] code Error code
6717 * @param [in] fmt Error string for the error code
6718 * @param [in] args @c va_list of arguments
6721 krb5_vset_error_message(krb5_context ctx, krb5_error_code code,
6722 const char *fmt, va_list args)
6723 #if !defined(__cplusplus) && (__GNUC__ > 2)
6724 __attribute__((__format__(__printf__, 3, 0)))
6728 /** Set the error message state of dest_ctx to that of src_ctx.
6730 * @param [in] dest_ctx Context structure where the error message state is copied to
6731 * @param [in] src_ctx Context structure where the error message state is copied from
6734 krb5_copy_error_message(krb5_context dest_ctx, krb5_context src_ctx);
6736 /** Get error message state specific to the context.
6738 * @param [in] ctx Context structure
6739 * @param [in] code Error code
6741 * The behavior of krb5_get_error_message() is only defined the first
6742 * time it is called after a failed call to a krb5 function using the
6743 * same context, and only when the error code passed in is the same as
6744 * that returned by the krb5 function.
6746 * This function never returns NULL, so its result may be used
6747 * unconditionally as a C string.
6749 * The string returned by this function must be freed using
6750 * krb5_free_error_message()
6752 * @note Future versions may return the same string for the second
6753 * and following calls.
6755 const char * KRB5_CALLCONV
6756 krb5_get_error_message(krb5_context ctx, krb5_error_code code);
6758 /** Free an error message state generated by krb5_get_error_message.
6760 * @param [in] ctx Context structure
6761 * @param [in] msg Pointer to error message
6764 krb5_free_error_message(krb5_context cxt, const char *msg);
6766 /** Clear the error message state.
6768 * @param [in,out] ctx Context structure
6770 * Similar to krb5_free_error_message() but @a ctx->msg is set to NULL.
6773 krb5_clear_error_message(krb5_context ctx);
6775 krb5_error_code KRB5_CALLCONV
6776 krb5_decode_authdata_container(krb5_context context,
6777 krb5_authdatatype type,
6778 const krb5_authdata *container,
6779 krb5_authdata ***authdata);
6781 krb5_error_code KRB5_CALLCONV
6782 krb5_encode_authdata_container(krb5_context context,
6783 krb5_authdatatype type,
6784 krb5_authdata * const*authdata,
6785 krb5_authdata ***container);
6790 /** This function both encodes and signs AD-KDCIssued authorization data.
6792 * @param [in] context Context structure
6793 * @param [in] key Session key
6794 * @param [in] issuer The name of the issuing principal
6795 * @param [in] authdata Authorization data to be signed
6796 * @param [out] ad_kdcissued Authorization data to be filled in
6798 * This function both encodes and signs AD-KDCIssued authorization data @a authdata
6799 * (RFC 4120 section 5.2.6.2). A set of authorization data @a ad_kdcissued containing
6800 * a single AD-KDCIssued element is returned to the caller.
6802 krb5_error_code KRB5_CALLCONV
6803 krb5_make_authdata_kdc_issued(krb5_context context,
6804 const krb5_keyblock *key,
6805 krb5_const_principal issuer,
6806 krb5_authdata *const *authdata,
6807 krb5_authdata ***ad_kdcissued);
6809 /** Decode and verify AD-KDCIssued authorization data.
6811 * @param [in] context Context structure
6812 * @param [in] key Session key
6813 * @param [in] ad_kdcissued KDC issued authorization data to be verified
6814 * @param [out] issuer The name of the issuing principal to be filled in (optional)
6815 * @param [out] authdata Authorization data to be filled in
6817 * This function both decodes and verifies AD-KDCIssued authorization data @a ad_kdcissued
6818 * (RFC 4120 section 5.2.6.2). The @a issuer and unwrapped authorization data @a authdata
6819 * are returned to the caller.
6821 krb5_error_code KRB5_CALLCONV
6822 krb5_verify_authdata_kdc_issued(krb5_context context,
6823 const krb5_keyblock *key,
6824 const krb5_authdata *ad_kdcissued,
6825 krb5_principal *issuer,
6826 krb5_authdata ***authdata);
6832 /* Microsoft defined types of data */
6833 #define PAC_LOGON_INFO 1 /**< Logon information */
6834 #define PAC_CREDENTIALS_INFO 2 /**< Credentials information */
6835 #define PAC_SERVER_CHECKSUM 6 /**< Server checksum */
6836 #define PAC_PRIVSVR_CHECKSUM 7 /**< KDC checksum */
6837 #define PAC_CLIENT_INFO 10 /**< Client name and ticket information */
6838 #define PAC_DELEGATION_INFO 11 /**< Client name and ticket information */
6839 #define PAC_UPN_DNS_INFO 12 /**< User principal name and DNS information */
6842 /** PAC data structure to convey authorization information */
6843 struct krb5_pac_data;
6844 typedef struct krb5_pac_data *krb5_pac;
6846 /** Add a buffer to the provided PAC and update header.
6848 * @param [in] context Context structure
6849 * @param [in,out] pac PAC handle
6850 * @param [in] type Type of data contained in @a data
6851 * @param [in] data Buffer to add
6853 * This function adds a new @a data to @a pac if there isn't already a buffer
6854 * of this type in @a pac.
6856 * The valid values of @type is one of the following:
6857 * @li @c PAC_LOGON_INFO - Logon information
6858 * @li @c PAC_CREDENTIALS_INFO - Credentials information
6859 * @li @c PAC_SERVER_CHECKSUM - Server checksum
6860 * @li @c PAC_PRIVSVR_CHECKSUM - KDC checksum
6861 * @li @c PAC_CLIENT_INFO - Client name and ticket information
6862 * @li @c PAC_DELEGATION_INFO - Constrained delegation information
6863 * @li @c PAC_UPN_DNS_INFO - User principal name and DNS information
6865 * @retval 0 Success; Otherwise - Kerberos error codes
6867 krb5_error_code KRB5_CALLCONV
6868 krb5_pac_add_buffer(krb5_context context, krb5_pac pac, krb5_ui_4 type,
6869 const krb5_data *data);
6871 /** Free the storage assigned to a PAC.
6873 * @param context Context structure
6874 * @param [in] pac PAC to be freed
6876 * This function zeros out and frees the content of a @a pac and then
6877 * releases @a pac itself.
6880 krb5_pac_free(krb5_context context, krb5_pac pac);
6882 /** Find a buffer in a PAC and copy data into output buffer.
6884 * @param [in] context Context structure
6885 * @param [in] pac PAC handle
6886 * @param [in] type Type of the buffer to be copied
6887 * @param [out] data Copy of a buffer to be filled in
6889 * Use krb5_free_data_contents() to free @a data when it is no longer needed.
6891 * @retval 0 Success; Otherwise - Kerberos error codes
6893 krb5_error_code KRB5_CALLCONV
6894 krb5_pac_get_buffer(krb5_context context, krb5_pac pac, krb5_ui_4 type,
6897 /** Return an array of the types of data in the PAC.
6899 * @param [in] context Context structure
6900 * @param [in,out] pac PAC handle
6901 * @param [out] len Number of entries in the @a types array.
6902 * @param [out] types If non-null, contains an array of types
6904 * Free @a types when it is no linger needed.
6906 * @retval 0 Success; Otherwise - Kerberos error codes
6908 krb5_error_code KRB5_CALLCONV
6909 krb5_pac_get_types(krb5_context context, krb5_pac pac, size_t *len,
6912 /** Create and initialize Privilege Attribute Certificate (PAC).
6914 * @param [in] context Context structure
6915 * @param [out] pac PAC handle
6917 * Use krb5_pac_free() to free @a pac when it is no longer needed.
6919 * @retval 0 Success; Otherwise - Kerberos error codes
6921 krb5_error_code KRB5_CALLCONV
6922 krb5_pac_init(krb5_context context, krb5_pac *pac);
6924 /** Parse the supplied data into the newly allocated PAC.
6926 * @param [in] context Context structure
6927 * @param [in] ptr PAC buffer
6928 * @param [in] len Size of @a ptr
6929 * @param [out] pac PAC handle
6931 * Use krb5_pac_free() to free @a pac when it is no longer needed.
6933 * @retval 0 Success; Otherwise - Kerberos error codes
6935 krb5_error_code KRB5_CALLCONV
6936 krb5_pac_parse(krb5_context context, const void *ptr, size_t len,
6941 * @param [in] context Context structure
6942 * @param [in] pac PAC handle
6943 * @param [in] authtime Timestamp to be compared with one in @a pac
6944 * @param [in] principal If non-null, use it to validate PAC's client name
6945 * and ticket information.
6946 * @param [in] server Compare it with PAC'c server checksum.
6948 * @param [in] privsvr If non-null, compare it with PAC'c KDC checksum
6950 * This function validates @a pac against the supplied @a server, @a privsvr,
6951 * @a principal and @a authtime and then, if successful, sets @a pac->verified
6954 * @note A checksum mismatch can occur if the PAC was copied from a cross-realm
6955 * TGT by an ignorant KDC; also Apple Mac OS X Server Open Directory (as of 10.6)
6956 * generates PACs with no server checksum at all. One should consider not failing
6957 * the whole authentication because of this reason, but, instead, marking PAC
6960 * @retval 0 Success; Otherwise - Kerberos error codes
6962 krb5_error_code KRB5_CALLCONV
6963 krb5_pac_verify(krb5_context context, const krb5_pac pac,
6964 krb5_timestamp authtime, krb5_const_principal principal,
6965 const krb5_keyblock *server, const krb5_keyblock *privsvr);
6967 /** Allow the appplication to override the profile's allow_weak_crypto setting.
6969 * @param [in,out] context Context structure
6970 * @param [in] enable Boolean flag
6972 * This function sets @a allow_weak_crypto field in @a context to @a enable.
6973 * It is primarily for use by aklog.
6975 * @retval 0 (always)
6977 krb5_error_code KRB5_CALLCONV
6978 krb5_allow_weak_crypto(krb5_context context, krb5_boolean enable);
6980 /* This structure may be extended to contain more fields in the future. */
6981 struct krb5_trace_info {
6982 const char *message;
6986 (KRB5_CALLCONV *krb5_trace_callback)(krb5_context context,
6987 const struct krb5_trace_info *info,
6990 /** Specify a callback function for trace events.
6992 * @param [in,out] context Context structure
6993 * @param [in] fn Callback function name
6994 * @param [in] cb_data Callback data
6996 * Specify a callback for trace events occurring in krb5 operations performed
6997 * within @a context. @a fn will be invoked with @a context as the first
6998 * argument, @a cb_data as the last argument, and a pointer to a struct
6999 * krb5_trace_info as the second argument. If the trace callback is reset via
7000 * this function or @a context is destroyed, @a fn will be invoked with a NULL
7001 * second argument to allow cleanup of @a cb_data. Supply a NULL value for @a
7002 * fn to disable trace callbacks within @a context.
7004 * @return Returns KRB5_TRACE_NOSUPP if tracing is not supported in the library
7005 * (unless @a fn is NULL).
7007 krb5_error_code KRB5_CALLCONV
7008 krb5_set_trace_callback(krb5_context context, krb5_trace_callback fn,
7011 /** Specify a file name for directing trace events.
7013 * @param [in,out] context Context structure
7014 * @param [in] filename File name
7016 * Open @a filename for appending (creating it, if necessary) and set up a
7017 * callback to write trace events to it.
7019 * @return KRB5_TRACE_NOSUPP if tracing is not supported in the library.
7021 krb5_error_code KRB5_CALLCONV
7022 krb5_set_trace_filename(krb5_context context, const char *filename);
7030 /* Don't use this! We're going to phase it out. It's just here to keep
7031 applications from breaking right away. */
7032 #define krb5_const const
7034 #undef KRB5_ATTR_DEPRECATED
7036 #endif /* KRB5_GENERAL__ */