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 /** @defgroup KRB5_H krb5 library API
59 /* By default, do not expose deprecated interfaces. */
60 #ifndef KRB5_DEPRECATED
61 #define KRB5_DEPRECATED 0
64 #if defined(__MACH__) && defined(__APPLE__)
65 # include <TargetConditionals.h>
66 # if TARGET_RT_MAC_CFM
67 # error "Use KfM 4.0 SDK headers for CFM compilation."
71 #if defined(_MSDOS) || defined(_WIN32)
78 #define KRB5_CALLCONV_C
79 #endif /* !KRB5_CALLCONV */
80 #endif /* !KRB5_CONFIG__ */
82 #ifndef KRB5_CALLCONV_WRONG
83 #define KRB5_CALLCONV_WRONG
86 #ifndef THREEPARAMOPEN
87 #define THREEPARAMOPEN(x,y,z) open(x,y,z)
90 #define KRB5_OLD_CRYPTO
93 #include <limits.h> /* for *_MAX */
96 #ifndef KRB5INT_BEGIN_DECLS
97 #if defined(__cplusplus)
98 #define KRB5INT_BEGIN_DECLS extern "C" {
99 #define KRB5INT_END_DECLS }
101 #define KRB5INT_BEGIN_DECLS
102 #define KRB5INT_END_DECLS
109 # pragma pack(push,2)
112 #if (__GNUC__ * 10000 + __GNUC_MINOR__ * 100 + __GNUC_PATCHLEVEL__) >= 30203
113 # define KRB5_ATTR_DEPRECATED __attribute__((deprecated))
115 # define KRB5_ATTR_DEPRECATED __declspec(deprecated)
117 # define KRB5_ATTR_DEPRECATED
122 /* typedef struct _profile_t *profile_t; */
129 * Word-size related definition.
132 typedef unsigned char krb5_octet;
134 #if INT_MAX == 0x7fff
135 typedef int krb5_int16;
136 typedef unsigned int krb5_ui_2;
137 #elif SHRT_MAX == 0x7fff
138 typedef short krb5_int16;
139 typedef unsigned short krb5_ui_2;
141 #error undefined 16 bit type
144 #if INT_MAX == 0x7fffffffL
145 typedef int krb5_int32;
146 typedef unsigned int krb5_ui_4;
147 #elif LONG_MAX == 0x7fffffffL
148 typedef long krb5_int32;
149 typedef unsigned long krb5_ui_4;
150 #elif SHRT_MAX == 0x7fffffffL
151 typedef short krb5_int32;
152 typedef unsigned short krb5_ui_4;
154 #error: undefined 32 bit type
157 #define VALID_INT_BITS INT_MAX
158 #define VALID_UINT_BITS UINT_MAX
160 #define KRB5_INT32_MAX 2147483647
161 /* this strange form is necessary since - is a unary operator, not a sign
163 #define KRB5_INT32_MIN (-KRB5_INT32_MAX-1)
165 #define KRB5_INT16_MAX 65535
166 /* this strange form is necessary since - is a unary operator, not a sign
168 #define KRB5_INT16_MIN (-KRB5_INT16_MAX-1)
175 * begin "base-defs.h"
179 * Basic definitions for Kerberos V5 library
189 typedef unsigned int krb5_boolean;
190 typedef unsigned int krb5_msgtype;
191 typedef unsigned int krb5_kvno;
193 typedef krb5_int32 krb5_addrtype;
194 typedef krb5_int32 krb5_enctype;
195 typedef krb5_int32 krb5_cksumtype;
196 typedef krb5_int32 krb5_authdatatype;
197 typedef krb5_int32 krb5_keyusage;
198 typedef krb5_int32 krb5_cryptotype;
200 typedef krb5_int32 krb5_preauthtype; /* This may change, later on */
201 typedef krb5_int32 krb5_flags;
202 typedef krb5_int32 krb5_timestamp;
203 typedef krb5_int32 krb5_error_code;
204 typedef krb5_int32 krb5_deltat;
206 typedef krb5_error_code krb5_magic;
208 typedef struct _krb5_data {
214 /* Originally introduced for PKINIT; now unused. Do not use this. */
215 typedef struct _krb5_octet_data {
221 /* Originally used to recognize AFS and default salts. No longer used. */
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 #define KRB5_NT_UNKNOWN 0 /**< Name type not known */
243 #define KRB5_NT_PRINCIPAL 1 /**< Just the name of the principal
244 as in DCE, or for users */
245 #define KRB5_NT_SRV_INST 2 /**< Service and other unique instance (krbtgt) */
246 #define KRB5_NT_SRV_HST 3 /**< Service with host name as instance
247 (telnet, rcommands) */
248 #define KRB5_NT_SRV_XHST 4 /**< Service with host as remaining components */
249 #define KRB5_NT_UID 5 /**< Unique ID */
250 #define KRB5_NT_X500_PRINCIPAL 6 /**< PKINIT */
251 #define KRB5_NT_SMTP_NAME 7 /**< Name in form of SMTP email name */
252 #define KRB5_NT_ENTERPRISE_PRINCIPAL 10 /**< Windows 2000 UPN */
253 #define KRB5_NT_WELLKNOWN 11 /**< Well-known (special) principal */
254 #define KRB5_WELLKNOWN_NAMESTR "WELLKNOWN" /**< First component of
255 NT_WELLKNOWN principals */
256 #define KRB5_NT_MS_PRINCIPAL -128 /**< Windows 2000 UPN and SID */
257 #define KRB5_NT_MS_PRINCIPAL_AND_ID -129 /**< NT 4 style name */
258 #define KRB5_NT_ENT_PRINCIPAL_AND_ID -130 /**< NT 4 style name and SID */
260 /** Constant version of krb5_principal_data */
261 typedef const krb5_principal_data *krb5_const_principal;
263 #define krb5_princ_realm(context, princ) (&(princ)->realm)
264 #define krb5_princ_set_realm(context, princ,value) ((princ)->realm = *(value))
265 #define krb5_princ_set_realm_length(context, princ,value) (princ)->realm.length = (value)
266 #define krb5_princ_set_realm_data(context, princ,value) (princ)->realm.data = (value)
267 #define krb5_princ_size(context, princ) (princ)->length
268 #define krb5_princ_type(context, princ) (princ)->type
269 #define krb5_princ_name(context, princ) (princ)->data
270 #define krb5_princ_component(context, princ,i) \
271 (((i) < krb5_princ_size(context, princ)) \
272 ? (princ)->data + (i) \
275 /** Constant for realm referrals. */
276 #define KRB5_REFERRAL_REALM ""
279 * Referral-specific functions.
283 * Check for a match with KRB5_REFERRAL_REALM.
285 * @param [in] r Realm to check
287 * @return @c TRUE if @a r is zero-length, @c FALSE otherwise
289 krb5_boolean KRB5_CALLCONV
290 krb5_is_referral_realm(const krb5_data *r);
293 * Return an anonymous realm data.
295 * This function returns constant storage that must not be freed.
297 * @sa #KRB5_ANONYMOUS_REALMSTR
299 const krb5_data *KRB5_CALLCONV
300 krb5_anonymous_realm(void);
303 * Build an anonymous principal.
305 * This function returns constant storage that must not be freed.
307 * @sa #KRB5_ANONYMOUS_PRINCSTR
309 krb5_const_principal KRB5_CALLCONV
310 krb5_anonymous_principal(void);
312 #define KRB5_ANONYMOUS_REALMSTR "WELLKNOWN:ANONYMOUS" /**< Anonymous realm */
313 #define KRB5_ANONYMOUS_PRINCSTR "ANONYMOUS" /**< Anonymous principal name */
322 /** Structure for address */
323 typedef struct _krb5_address {
325 krb5_addrtype addrtype;
327 krb5_octet *contents;
330 /* per Kerberos v5 protocol spec */
331 #define ADDRTYPE_INET 0x0002
332 #define ADDRTYPE_CHAOS 0x0005
333 #define ADDRTYPE_XNS 0x0006
334 #define ADDRTYPE_ISO 0x0007
335 #define ADDRTYPE_DDP 0x0010
336 #define ADDRTYPE_NETBIOS 0x0014
337 #define ADDRTYPE_INET6 0x0018
338 /* not yet in the spec... */
339 #define ADDRTYPE_ADDRPORT 0x0100
340 #define ADDRTYPE_IPPORT 0x0101
342 /* macros to determine if a type is a local type */
343 #define ADDRTYPE_IS_LOCAL(addrtype) (addrtype & 0x8000)
350 struct _krb5_context;
351 typedef struct _krb5_context * krb5_context;
353 struct _krb5_auth_context;
354 typedef struct _krb5_auth_context * krb5_auth_context;
356 struct _krb5_cryptosystem_entry;
359 * begin "encryption.h"
362 /** Exposed contents of a key. */
363 typedef struct _krb5_keyblock {
365 krb5_enctype enctype;
367 krb5_octet *contents;
372 * Opaque identifier for a key.
374 * Use with the krb5_k APIs for better performance for repeated operations with
375 * the same key and usage. Key identifiers must not be used simultaneously
376 * within multiple threads, as they may contain mutable internal state and are
377 * not mutex-protected.
379 typedef struct krb5_key_st *krb5_key;
381 #ifdef KRB5_OLD_CRYPTO
382 typedef struct _krb5_encrypt_block {
384 krb5_enctype crypto_entry; /* to call krb5_encrypt_size, you need
385 this. it was a pointer, but it
386 doesn't have to be. gross. */
388 } krb5_encrypt_block;
391 typedef struct _krb5_checksum {
393 krb5_cksumtype checksum_type; /* checksum type */
395 krb5_octet *contents;
398 typedef struct _krb5_enc_data {
400 krb5_enctype enctype;
402 krb5_data ciphertext;
406 * Structure to describe a region of text to be encrypted or decrypted.
408 * The @a flags member describes the type of the iov.
409 * The @a data member points to the memory that will be manipulated.
410 * All iov APIs take a pointer to the first element of an array of krb5_crypto_iov's
411 * along with the size of that array. Buffer contents are manipulated in-place;
412 * data is overwritten. Callers must allocate the right number of krb5_crypto_iov
413 * structures before calling into an iov API.
415 typedef struct _krb5_crypto_iov {
416 krb5_cryptotype flags; /**< @ref KRB5_CRYPTO_TYPE type of the iov */
420 /* per Kerberos v5 protocol spec */
421 #define ENCTYPE_NULL 0x0000
422 #define ENCTYPE_DES_CBC_CRC 0x0001 /**< DES cbc mode with CRC-32 */
423 #define ENCTYPE_DES_CBC_MD4 0x0002 /**< DES cbc mode with RSA-MD4 */
424 #define ENCTYPE_DES_CBC_MD5 0x0003 /**< DES cbc mode with RSA-MD5 */
425 #define ENCTYPE_DES_CBC_RAW 0x0004 /**< @deprecated DES cbc mode raw */
426 #define ENCTYPE_DES3_CBC_SHA 0x0005 /**< @deprecated DES-3 cbc with SHA1 */
427 #define ENCTYPE_DES3_CBC_RAW 0x0006 /**< @deprecated DES-3 cbc mode raw */
428 #define ENCTYPE_DES_HMAC_SHA1 0x0008 /**< @deprecated */
430 #define ENCTYPE_DSA_SHA1_CMS 0x0009 /**< DSA with SHA1, CMS signature */
431 #define ENCTYPE_MD5_RSA_CMS 0x000a /**< MD5 with RSA, CMS signature */
432 #define ENCTYPE_SHA1_RSA_CMS 0x000b /**< SHA1 with RSA, CMS signature */
433 #define ENCTYPE_RC2_CBC_ENV 0x000c /**< RC2 cbc mode, CMS enveloped data */
434 #define ENCTYPE_RSA_ENV 0x000d /**< RSA encryption, CMS enveloped data */
435 #define ENCTYPE_RSA_ES_OAEP_ENV 0x000e /**< RSA w/OEAP encryption, CMS enveloped data */
436 #define ENCTYPE_DES3_CBC_ENV 0x000f /**< DES-3 cbc mode, CMS enveloped data */
438 #define ENCTYPE_DES3_CBC_SHA1 0x0010
439 #define ENCTYPE_AES128_CTS_HMAC_SHA1_96 0x0011 /**< RFC 3962 */
440 #define ENCTYPE_AES256_CTS_HMAC_SHA1_96 0x0012 /**< RFC 3962 */
441 #define ENCTYPE_ARCFOUR_HMAC 0x0017
442 #define ENCTYPE_ARCFOUR_HMAC_EXP 0x0018
443 #define ENCTYPE_UNKNOWN 0x01ff
445 #define CKSUMTYPE_CRC32 0x0001
446 #define CKSUMTYPE_RSA_MD4 0x0002
447 #define CKSUMTYPE_RSA_MD4_DES 0x0003
448 #define CKSUMTYPE_DESCBC 0x0004
451 #define CKSUMTYPE_RSA_MD5 0x0007
452 #define CKSUMTYPE_RSA_MD5_DES 0x0008
453 #define CKSUMTYPE_NIST_SHA 0x0009
454 #define CKSUMTYPE_HMAC_SHA1_DES3 0x000c
455 #define CKSUMTYPE_HMAC_SHA1_96_AES128 0x000f /**< RFC 3962. Used with
456 ENCTYPE_AES128_CTS_HMAC_SHA1_96 */
457 #define CKSUMTYPE_HMAC_SHA1_96_AES256 0x0010 /**< RFC 3962. Used with
458 ENCTYPE_AES256_CTS_HMAC_SHA1_96 */
459 #define CKSUMTYPE_MD5_HMAC_ARCFOUR -137 /*Microsoft netlogon cksumtype*/
460 #define CKSUMTYPE_HMAC_MD5_ARCFOUR -138 /*Microsoft md5 hmac cksumtype*/
463 * The following are entropy source designations. Whenever
464 * krb5_C_random_add_entropy is called, one of these source ids is passed in.
465 * This allows the library to better estimate bits of entropy in the sample and
466 * to keep track of what sources of entropy have contributed enough entropy.
467 * Sources marked internal MUST NOT be used by applications outside the
472 KRB5_C_RANDSOURCE_OLDAPI = 0, /*calls to krb5_C_RANDOM_SEED (INTERNAL)*/
473 KRB5_C_RANDSOURCE_OSRAND = 1, /* /dev/random or equivalent (internal)*/
474 KRB5_C_RANDSOURCE_TRUSTEDPARTY = 2, /* From KDC or other trusted party*/
476 * This source should be used carefully; data in this category
477 * should be from a third party trusted to give random bits
478 * For example keys issued by the KDC in the application server.
480 KRB5_C_RANDSOURCE_TIMING = 3, /* Timing of operations*/
481 KRB5_C_RANDSOURCE_EXTERNAL_PROTOCOL = 4, /*Protocol data possibly from attacker*/
482 KRB5_C_RANDSOURCE_MAX = 5 /*Do not use; maximum source ID*/
486 /* round x up to nearest multiple of y */
487 #define krb5_roundup(x, y) ((((x) + (y) - 1)/(y))*(y))
490 /* macro function definitions to help clean up code */
493 #define krb5_x(ptr,args) ((ptr)?((*(ptr)) args):(abort(),1))
494 #define krb5_xc(ptr,args) ((ptr)?((*(ptr)) args):(abort(),(char*)0))
496 #define krb5_x(ptr,args) ((*(ptr)) args)
497 #define krb5_xc(ptr,args) ((*(ptr)) args)
501 * Encrypt data using a key (operates on keyblock).
503 * @param [in] context Library context
504 * @param [in] key Encryption key
505 * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
506 * @param [in,out] cipher_state Cipher state; specify NULL if not needed
507 * @param [in] input Data to be encrypted
508 * @param [out] output Encrypted data
510 * This function encrypts the data block @a input and stores the output into @a
511 * output. The actual encryption key will be derived from @a key and @a usage
512 * if key derivation is specified for the encryption type. If non-null, @a
513 * cipher_state specifies the beginning state for the encryption operation, and
514 * is updated with the state to be passed as input to the next operation.
516 * @note The caller must initialize @a output and allocate at least enough
517 * space for the result (using krb5_c_encrypt_length() to determine the amount
518 * of space needed). @a output->length will be set to the actual length of the
521 * @retval 0 Success; otherwise - Kerberos error codes
523 krb5_error_code KRB5_CALLCONV
524 krb5_c_encrypt(krb5_context context, const krb5_keyblock *key,
525 krb5_keyusage usage, const krb5_data *cipher_state,
526 const krb5_data *input, krb5_enc_data *output);
529 * Decrypt data using a key (operates on keyblock).
531 * @param [in] context Library context
532 * @param [in] key Encryption key
533 * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
534 * @param [in,out] cipher_state Cipher state; specify NULL if not needed
535 * @param [in] input Encrypted data
536 * @param [out] output Decrypted data
538 * This function decrypts the data block @a input and stores the output into @a
539 * output. The actual decryption key will be derived from @a key and @a usage
540 * if key derivation is specified for the encryption type. If non-null, @a
541 * cipher_state specifies the beginning state for the decryption operation, and
542 * is updated with the state to be passed as input to the next operation.
544 * @note The caller must initialize @a output and allocate at least enough
545 * space for the result. The usual practice is to allocate an output buffer as
546 * long as the ciphertext, and let krb5_c_decrypt() trim @a output->length.
547 * For some enctypes, the resulting @a output->length may include padding
550 * @retval 0 Success; otherwise - Kerberos error codes
552 krb5_error_code KRB5_CALLCONV
553 krb5_c_decrypt(krb5_context context, const krb5_keyblock *key,
554 krb5_keyusage usage, const krb5_data *cipher_state,
555 const krb5_enc_data *input, krb5_data *output);
558 * Compute encrypted data length.
560 * @param [in] context Library context
561 * @param [in] enctype Encryption type
562 * @param [in] inputlen Length of the data to be encrypted
563 * @param [out] length Length of the encrypted data
565 * This function computes the length of the ciphertext produced by encrypting
566 * @a inputlen bytes including padding, confounder, and checksum.
568 * @retval 0 Success; otherwise - Kerberos error codes
570 krb5_error_code KRB5_CALLCONV
571 krb5_c_encrypt_length(krb5_context context, krb5_enctype enctype,
572 size_t inputlen, size_t *length);
575 * Return cipher block size.
577 * @param [in] context Library context
578 * @param [in] enctype Encryption type
579 * @param [out] blocksize Block size for @a enctype
581 * @retval 0 Success; otherwise - Kerberos error codes
583 krb5_error_code KRB5_CALLCONV
584 krb5_c_block_size(krb5_context context, krb5_enctype enctype,
588 * Return length of the specified key in bytes.
590 * @param [in] context Library context
591 * @param [in] enctype Encryption type
592 * @param [out] keybytes Number of bytes required to make a key
593 * @param [out] keylength Length of final key
595 * @retval 0 Success; otherwise - Kerberos error codes
597 krb5_error_code KRB5_CALLCONV
598 krb5_c_keylengths(krb5_context context, krb5_enctype enctype,
599 size_t *keybytes, size_t *keylength);
602 * Initialize a new cipher state.
604 * @param [in] context Library context
605 * @param [in] key Key
606 * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
607 * @param [out] new_state New cipher state
609 * @retval 0 Success; otherwise - Kerberos error codes
611 krb5_error_code KRB5_CALLCONV
612 krb5_c_init_state(krb5_context context, const krb5_keyblock *key,
613 krb5_keyusage usage, krb5_data *new_state);
616 * Free a cipher state previously allocated by krb5_c_init_state().
618 * @param [in] context Library context
619 * @param [in] key Key
620 * @param [in] state Cipher state to be freed
622 * @retval 0 Success; otherwise - Kerberos error codes
624 krb5_error_code KRB5_CALLCONV
625 krb5_c_free_state(krb5_context context, const krb5_keyblock *key,
629 * Generate enctype-specific pseudo-random bytes.
631 * @param [in] context Library context
632 * @param [in] keyblock Key
633 * @param [in] input Input data
634 * @param [out] output Output data
636 * This function selects a pseudo-random function based on @a keyblock and
637 * computes its value over @a input, placing the result into @a output.
638 * The caller must preinitialize @a output and allocate space for the
639 * result, using krb5_c_prf_length() to determine the required length.
641 * @retval 0 Success; otherwise - Kerberos error codes
643 krb5_error_code KRB5_CALLCONV
644 krb5_c_prf(krb5_context context, const krb5_keyblock *keyblock,
645 krb5_data *input, krb5_data *output);
648 * Get the output length of pseudo-random functions for an encryption type.
650 * @param [in] context Library context
651 * @param [in] enctype Encryption type
652 * @param [out] len Length of PRF output
654 * @retval 0 Success; otherwise - Kerberos error codes
656 krb5_error_code KRB5_CALLCONV
657 krb5_c_prf_length(krb5_context context, krb5_enctype enctype, size_t *len);
660 * Compute the KRB-FX-CF2 combination of two keys and pepper strings.
662 * @param [in] context Library context
663 * @param [in] k1 KDC contribution key
664 * @param [in] pepper1 String "PKINIT"
665 * @param [in] k2 Reply key
666 * @param [in] pepper2 String "KeyExchange"
667 * @param [out] out Output key
669 * This function computes the KRB-FX-CF2 function over its inputs and places
670 * the results in a newly allocated keyblock. This function is simple in that
671 * it assumes that @a pepper1 and @a pepper2 are C strings with no internal
672 * nulls and that the enctype of the result will be the same as that of @a k1.
673 * @a k1 and @a k2 may be of different enctypes.
675 * @retval 0 Success; otherwise - Kerberos error codes
677 krb5_error_code KRB5_CALLCONV
678 krb5_c_fx_cf2_simple(krb5_context context,
679 krb5_keyblock *k1, const char *pepper1,
680 krb5_keyblock *k2, const char *pepper2,
681 krb5_keyblock **out);
684 * Generate an enctype-specific random encryption key.
686 * @param [in] context Library context
687 * @param [in] enctype Encryption type of the generated key
688 * @param [out] k5_random_key An allocated and initialized keyblock
690 * Use krb5_free_keyblock_contents() to free @a k5_random_key when
693 * @retval 0 Success; otherwise - Kerberos error codes
695 krb5_error_code KRB5_CALLCONV
696 krb5_c_make_random_key(krb5_context context, krb5_enctype enctype,
697 krb5_keyblock *k5_random_key);
700 * Generate an enctype-specific key from random data.
702 * @param [in] context Library context
703 * @param [in] enctype Encryption type
704 * @param [in] random_data Random input data
705 * @param [out] k5_random_key Resulting key
707 * This function takes random input data @a random_data and produces a valid
708 * key @a k5_random_key for a given @a enctype.
710 * @note It is assumed that @a k5_random_key has already been initialized and
711 * @a k5_random_key->contents has been allocated with the correct length.
713 * @sa krb5_c_keylengths()
715 * @retval 0 Success; otherwise - Kerberos error codes
717 krb5_error_code KRB5_CALLCONV
718 krb5_c_random_to_key(krb5_context context, krb5_enctype enctype,
719 krb5_data *random_data, krb5_keyblock *k5_random_key);
722 * Add entropy to the pseudo-random number generator.
724 * @param [in] context Library context
725 * @param [in] randsource Entropy source (see KRB5_RANDSOURCE types)
726 * @param [in] data Data
728 * Contribute entropy to the PRNG used by krb5 crypto operations. This may or
729 * may not affect the output of the next crypto operation requiring random
732 * @retval 0 Success; otherwise - Kerberos error codes
734 krb5_error_code KRB5_CALLCONV
735 krb5_c_random_add_entropy(krb5_context context, unsigned int randsource,
736 const krb5_data *data);
739 * Generate pseudo-random bytes.
741 * @param [in] context Library context
742 * @param [out] data Random data
744 * Fills in @a data with bytes from the PRNG used by krb5 crypto operations.
745 * The caller must preinitialize @a data and allocate the desired amount of
748 * @retval 0 Success; otherwise - Kerberos error codes
750 krb5_error_code KRB5_CALLCONV
751 krb5_c_random_make_octets(krb5_context context, krb5_data *data);
754 * Collect entropy from the OS if possible.
756 * @param [in] context Library context
757 * @param [in] strong Strongest available source of entropy
758 * @param [out] success 1 if OS provides entropy, 0 otherwise
760 * If @a strong is non-zero, this function attempts to use the strongest
761 * available source of entropy. Setting this flag may cause the function to
762 * block on some operating systems. Good uses include seeding the PRNG for
763 * kadmind and realm setup.
765 * @retval 0 Success; otherwise - Kerberos error codes
767 krb5_error_code KRB5_CALLCONV
768 krb5_c_random_os_entropy(krb5_context context, int strong, int *success);
770 /** @deprecated Replaced by krb5_c_ API family. */
771 krb5_error_code KRB5_CALLCONV
772 krb5_c_random_seed(krb5_context context, krb5_data *data);
775 * Convert a string (such a password) to a key.
777 * @param [in] context Library context
778 * @param [in] enctype Encryption type
779 * @param [in] string String to be converted
780 * @param [in] salt Salt value
781 * @param [out] key Generated key
783 * This function converts @a string to a @a key of encryption type @a enctype,
784 * using the specified @a salt. The newly created @a key must be released by
785 * calling krb5_free_keyblock_contents() when it is no longer needed.
787 * @retval 0 Success; otherwise - Kerberos error codes
789 krb5_error_code KRB5_CALLCONV
790 krb5_c_string_to_key(krb5_context context, krb5_enctype enctype,
791 const krb5_data *string, const krb5_data *salt,
795 * Convert a string (such as a password) to a key with additional parameters.
797 * @param [in] context Library context
798 * @param [in] enctype Encryption type
799 * @param [in] string String to be converted
800 * @param [in] salt Salt value
801 * @param [in] params Parameters
802 * @param [out] key Generated key
804 * This function is similar to krb5_c_string_to_key(), but also takes
805 * parameters which may affect the algorithm in an enctype-dependent way. The
806 * newly created @a key must be released by calling
807 * krb5_free_keyblock_contents() when it is no longer needed.
809 * @retval 0 Success; otherwise - Kerberos error codes
811 krb5_error_code KRB5_CALLCONV
812 krb5_c_string_to_key_with_params(krb5_context context,
813 krb5_enctype enctype,
814 const krb5_data *string,
815 const krb5_data *salt,
816 const krb5_data *params,
820 * Compare two encryption types.
822 * @param [in] context Library context
823 * @param [in] e1 First encryption type
824 * @param [in] e2 Second encryption type
825 * @param [out] similar @c TRUE if types are similar, @c FALSE if not
827 * This function determines whether two encryption types use the same kind of
830 * @retval 0 Success; otherwise - Kerberos error codes
832 krb5_error_code KRB5_CALLCONV
833 krb5_c_enctype_compare(krb5_context context, krb5_enctype e1, krb5_enctype e2,
834 krb5_boolean *similar);
837 * Compute a checksum (operates on keyblock).
839 * @param [in] context Library context
840 * @param [in] cksumtype Checksum type (0 for mandatory type)
841 * @param [in] key Encryption key for a keyed checksum
842 * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
843 * @param [in] input Input data
844 * @param [out] cksum Generated checksum
846 * This function computes a checksum of type @a cksumtype over @a input, using
847 * @a key if the checksum type is a keyed checksum. If @a cksumtype is 0 and
848 * @a key is non-null, the checksum type will be the mandatory-to-implement
849 * checksum type for the key's encryption type. The actual checksum key will
850 * be derived from @a key and @a usage if key derivation is specified for the
851 * checksum type. The newly created @a cksum must be released by calling
852 * krb5_free_checksum_contents() when it is no longer needed.
854 * @note This function is similar to krb5_k_make_checksum(), but operates
855 * on keyblock @a key.
857 * @sa krb5_c_verify_checksum()
859 * @retval 0 Success; otherwise - Kerberos error codes
861 krb5_error_code KRB5_CALLCONV
862 krb5_c_make_checksum(krb5_context context, krb5_cksumtype cksumtype,
863 const krb5_keyblock *key, krb5_keyusage usage,
864 const krb5_data *input, krb5_checksum *cksum);
867 * Verify a checksum (operates on keyblock).
869 * @param [in] context Library context
870 * @param [in] key Encryption key for a keyed checksum
871 * @param [in] usage @a key usage
872 * @param [in] data Data to be used to compute a new checksum
873 * using @a key to compare @a cksum against
874 * @param [in] cksum Checksum to be verified
875 * @param [out] valid Non-zero for success, zero for failure
877 * This function verifies that @a cksum is a valid checksum for @a data. If
878 * the checksum type of @a cksum is a keyed checksum, @a key is used to verify
879 * the checksum. The actual checksum key will be derived from @a key and @a
880 * usage if key derivation is specified for the checksum type.
882 * @note This function is similar to krb5_k_verify_checksum(), but operates
883 * on keyblock @a key.
885 * @retval 0 Success; otherwise - Kerberos error codes
887 krb5_error_code KRB5_CALLCONV
888 krb5_c_verify_checksum(krb5_context context, const krb5_keyblock *key,
889 krb5_keyusage usage, const krb5_data *data,
890 const krb5_checksum *cksum, krb5_boolean *valid);
893 * Return the length of checksums for a checksum type.
895 * @param [in] context Library context
896 * @param [in] cksumtype Checksum type
897 * @param [out] length Checksum length
899 * @retval 0 Success; otherwise - Kerberos error codes
901 krb5_error_code KRB5_CALLCONV
902 krb5_c_checksum_length(krb5_context context, krb5_cksumtype cksumtype,
906 * Return a list of keyed checksum types usable with an encryption type.
908 * @param [in] context Library context
909 * @param [in] enctype Encryption type
910 * @param [out] count Count of allowable checksum types
911 * @param [out] cksumtypes Array of allowable checksum types
913 * Use krb5_free_cksumtypes() to free @a cksumtypes when it is no longer
916 * @retval 0 Success; otherwise - Kerberos error codes
918 krb5_error_code KRB5_CALLCONV
919 krb5_c_keyed_checksum_types(krb5_context context, krb5_enctype enctype,
920 unsigned int *count, krb5_cksumtype **cksumtypes);
922 /** @defgroup KRB5_KEYUSAGE KRB5_KEYUSAGE
925 #define KRB5_KEYUSAGE_AS_REQ_PA_ENC_TS 1
926 #define KRB5_KEYUSAGE_KDC_REP_TICKET 2
927 #define KRB5_KEYUSAGE_AS_REP_ENCPART 3
928 #define KRB5_KEYUSAGE_TGS_REQ_AD_SESSKEY 4
929 #define KRB5_KEYUSAGE_TGS_REQ_AD_SUBKEY 5
930 #define KRB5_KEYUSAGE_TGS_REQ_AUTH_CKSUM 6
931 #define KRB5_KEYUSAGE_TGS_REQ_AUTH 7
932 #define KRB5_KEYUSAGE_TGS_REP_ENCPART_SESSKEY 8
933 #define KRB5_KEYUSAGE_TGS_REP_ENCPART_SUBKEY 9
934 #define KRB5_KEYUSAGE_AP_REQ_AUTH_CKSUM 10
935 #define KRB5_KEYUSAGE_AP_REQ_AUTH 11
936 #define KRB5_KEYUSAGE_AP_REP_ENCPART 12
937 #define KRB5_KEYUSAGE_KRB_PRIV_ENCPART 13
938 #define KRB5_KEYUSAGE_KRB_CRED_ENCPART 14
939 #define KRB5_KEYUSAGE_KRB_SAFE_CKSUM 15
940 #define KRB5_KEYUSAGE_APP_DATA_ENCRYPT 16
941 #define KRB5_KEYUSAGE_APP_DATA_CKSUM 17
942 #define KRB5_KEYUSAGE_KRB_ERROR_CKSUM 18
943 #define KRB5_KEYUSAGE_AD_KDCISSUED_CKSUM 19
944 #define KRB5_KEYUSAGE_AD_MTE 20
945 #define KRB5_KEYUSAGE_AD_ITE 21
947 /* XXX need to register these */
949 #define KRB5_KEYUSAGE_GSS_TOK_MIC 22
950 #define KRB5_KEYUSAGE_GSS_TOK_WRAP_INTEG 23
951 #define KRB5_KEYUSAGE_GSS_TOK_WRAP_PRIV 24
953 /* Defined in hardware preauth draft */
955 #define KRB5_KEYUSAGE_PA_SAM_CHALLENGE_CKSUM 25
956 #define KRB5_KEYUSAGE_PA_SAM_CHALLENGE_TRACKID 26
957 #define KRB5_KEYUSAGE_PA_SAM_RESPONSE 27
959 /* Defined in KDC referrals draft */
961 * @note There is a conflict with the value of @c KRB5_KEYUSAGE_PA_REFERRAL:
962 * it is used for hardware Pre-athentication @a and KDC referrals.
964 #define KRB5_KEYUSAGE_PA_REFERRAL 26 /* XXX note conflict with above */
966 /* Defined in [MS-SFU] */
967 #define KRB5_KEYUSAGE_PA_S4U_X509_USER_REQUEST 26 /* XXX note conflict with above */
968 #define KRB5_KEYUSAGE_PA_S4U_X509_USER_REPLY 27 /* XXX note conflict with above */
970 #define KRB5_KEYUSAGE_AD_SIGNEDPATH -21
971 #define KRB5_KEYUSAGE_IAKERB_FINISHED 42
972 #define KRB5_KEYUSAGE_PA_PKINIT_KX 44
973 /* define in draft-ietf-krb-wg-preauth-framework*/
974 #define KRB5_KEYUSAGE_FAST_REQ_CHKSUM 50
975 #define KRB5_KEYUSAGE_FAST_ENC 51
976 #define KRB5_KEYUSAGE_FAST_REP 52
977 #define KRB5_KEYUSAGE_FAST_FINISHED 53
978 #define KRB5_KEYUSAGE_ENC_CHALLENGE_CLIENT 54
979 #define KRB5_KEYUSAGE_ENC_CHALLENGE_KDC 55
980 #define KRB5_KEYUSAGE_AS_REQ 56
981 /** @} */ /* end of KRB5_KEYUSAGE group */
984 * Verify that a specified encryption type is a valid Kerberos encryption type.
986 * @param [in] ktype Encryption type
988 * @return @c TRUE if @a ktype is valid, @c FALSE if not
990 krb5_boolean KRB5_CALLCONV
991 krb5_c_valid_enctype(krb5_enctype ktype);
994 * Verify that specified checksum type is a valid Kerberos checksum type.
996 * @param [in] ctype Checksum type
998 * @return @c TRUE if @a ctype is valid, @c FALSE if not
1000 krb5_boolean KRB5_CALLCONV
1001 krb5_c_valid_cksumtype(krb5_cksumtype ctype);
1004 * Test whether a checksum type is collision-proof.
1006 * @param [in] ctype Checksum type
1008 * @return @c TRUE if @a ctype is collision-proof, @c FALSE if it is not
1009 * collision-proof or not a valid checksum type.
1011 krb5_boolean KRB5_CALLCONV
1012 krb5_c_is_coll_proof_cksum(krb5_cksumtype ctype);
1015 * Test whether a checksum type is keyed.
1017 * @param [in] ctype Checksum type
1019 * @return @c TRUE if @a ctype is a keyed checksum type, @c FALSE otherwise.
1021 krb5_boolean KRB5_CALLCONV
1022 krb5_c_is_keyed_cksum(krb5_cksumtype ctype);
1025 /** @defgroup KRB5_CRYPTO_TYPE KRB5_CRYPTO_TYPE
1028 #define KRB5_CRYPTO_TYPE_EMPTY 0 /**< [in] ignored */
1029 #define KRB5_CRYPTO_TYPE_HEADER 1 /**< [out] header */
1030 #define KRB5_CRYPTO_TYPE_DATA 2 /**< [in, out] plaintext */
1031 #define KRB5_CRYPTO_TYPE_SIGN_ONLY 3 /**< [in] associated data */
1032 #define KRB5_CRYPTO_TYPE_PADDING 4 /**< [out] padding */
1033 #define KRB5_CRYPTO_TYPE_TRAILER 5 /**< [out] checksum for encrypt */
1034 #define KRB5_CRYPTO_TYPE_CHECKSUM 6 /**< [out] checksum for MIC */
1035 #define KRB5_CRYPTO_TYPE_STREAM 7 /**< [in] entire message without
1036 decomposing the structure into
1037 header, data and trailer buffers */
1038 /** @} */ /* end of KRB5_CRYPTO_TYPE group */
1041 * Fill in a checksum element in IOV array (operates on keyblock)
1043 * @param [in] context Library context
1044 * @param [in] cksumtype Checksum type (0 for mandatory type)
1045 * @param [in] key Encryption key for a keyed checksum
1046 * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
1047 * @param [in,out] data IOV array
1048 * @param [in] num_data Size of @a data
1050 * Create a checksum in the #KRB5_CRYPTO_TYPE_CHECKSUM element over
1051 * #KRB5_CRYPTO_TYPE_DATA and #KRB5_CRYPTO_TYPE_SIGN_ONLY chunks in @a data.
1052 * Only the #KRB5_CRYPTO_TYPE_CHECKSUM region is modified.
1054 * @note This function is similar to krb5_k_make_checksum_iov(), but operates
1055 * on keyblock @a key.
1057 * @sa krb5_c_verify_checksum_iov()
1059 * @retval 0 Success; otherwise - Kerberos error codes
1061 krb5_error_code KRB5_CALLCONV
1062 krb5_c_make_checksum_iov(krb5_context context, krb5_cksumtype cksumtype,
1063 const krb5_keyblock *key, krb5_keyusage usage,
1064 krb5_crypto_iov *data, size_t num_data);
1067 * Validate a checksum element in IOV array (operates on keyblock).
1069 * @param [in] context Library context
1070 * @param [in] cksumtype Checksum type (0 for mandatory type)
1071 * @param [in] key Encryption key for a keyed checksum
1072 * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
1073 * @param [in] data IOV array
1074 * @param [in] num_data Size of @a data
1075 * @param [out] valid Non-zero for success, zero for failure
1077 * Confirm that the checksum in the #KRB5_CRYPTO_TYPE_CHECKSUM element is a
1078 * valid checksum of the #KRB5_CRYPTO_TYPE_DATA and #KRB5_CRYPTO_TYPE_SIGN_ONLY
1079 * regions in the iov.
1081 * @note This function is similar to krb5_k_verify_checksum_iov(), but operates
1082 * on keyblock @a key.
1084 * @sa krb5_c_make_checksum_iov()
1086 * @retval 0 Success; otherwise - Kerberos error codes
1088 krb5_error_code KRB5_CALLCONV
1089 krb5_c_verify_checksum_iov(krb5_context context, krb5_cksumtype cksumtype,
1090 const krb5_keyblock *key, krb5_keyusage usage,
1091 const krb5_crypto_iov *data, size_t num_data,
1092 krb5_boolean *valid);
1095 * Encrypt data in place supporting AEAD (operates on keyblock).
1097 * @param [in] context Library context
1098 * @param [in] keyblock Encryption key
1099 * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
1100 * @param [in] cipher_state Cipher state; specify NULL if not needed
1101 * @param [in,out] data IOV array. Modified in-place.
1102 * @param [in] num_data Size of @a data
1104 * This function encrypts the data block @a data and stores the output in-place.
1105 * The actual encryption key will be derived from @a keyblock and @a usage
1106 * if key derivation is specified for the encryption type. If non-null, @a
1107 * cipher_state specifies the beginning state for the encryption operation, and
1108 * is updated with the state to be passed as input to the next operation.
1109 * The caller must allocate the right number of krb5_crypto_iov
1110 * structures before calling into this API.
1112 * @note On return from a krb5_c_encrypt_iov() call, the @a data->length in the
1113 * iov structure are adjusted to reflect actual lengths of the ciphertext used.
1114 * For example, if the padding length is too large, the length will be reduced.
1115 * Lengths are never increased.
1117 * @note This function is similar to krb5_k_encrypt_iov(), but operates
1118 * on keyblock @a keyblock.
1120 * @sa krb5_c_decrypt_iov()
1122 * @retval 0 Success; otherwise - Kerberos error codes
1124 krb5_error_code KRB5_CALLCONV
1125 krb5_c_encrypt_iov(krb5_context context, const krb5_keyblock *keyblock,
1126 krb5_keyusage usage, const krb5_data *cipher_state,
1127 krb5_crypto_iov *data, size_t num_data);
1130 * Decrypt data in place supporting AEAD (operates on keyblock).
1132 * @param [in] context Library context
1133 * @param [in] keyblock Encryption key
1134 * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
1135 * @param [in] cipher_state Cipher state; specify NULL if not needed
1136 * @param [in,out] data IOV array. Modified in-place.
1137 * @param [in] num_data Size of @a data
1139 * This function decrypts the data block @a data and stores the output in-place.
1140 * The actual decryption key will be derived from @a keyblock and @a usage
1141 * if key derivation is specified for the encryption type. If non-null, @a
1142 * cipher_state specifies the beginning state for the decryption operation, and
1143 * is updated with the state to be passed as input to the next operation.
1144 * The caller must allocate the right number of krb5_crypto_iov
1145 * structures before calling into this API.
1147 * @note On return from a krb5_c_decrypt_iov() call, the @a data->length in the
1148 * iov structure are adjusted to reflect actual lengths of the ciphertext used.
1149 * For example, if the padding length is too large, the length will be reduced.
1150 * Lengths are never increased.
1152 * @note This function is similar to krb5_k_decrypt_iov(), but operates
1153 * on keyblock @a keyblock.
1155 * @sa krb5_c_decrypt_iov()
1157 * @retval 0 Success; otherwise - Kerberos error codes
1159 krb5_error_code KRB5_CALLCONV
1160 krb5_c_decrypt_iov(krb5_context context, const krb5_keyblock *keyblock,
1161 krb5_keyusage usage, const krb5_data *cipher_state,
1162 krb5_crypto_iov *data, size_t num_data);
1165 * Return a length of a message field specific to the encryption type.
1167 * @param [in] context Library context
1168 * @param [in] enctype Encryption type
1169 * @param [in] type Type field (See @ref KRB5_CRYPTO_TYPE types)
1170 * @param [out] size Length of the @a type specific to @a enctype
1172 * @retval 0 Success; otherwise - Kerberos error codes
1174 krb5_error_code KRB5_CALLCONV
1175 krb5_c_crypto_length(krb5_context context, krb5_enctype enctype,
1176 krb5_cryptotype type, unsigned int *size);
1179 * Fill in lengths for header, trailer and padding in a IOV array.
1181 * @param [in] context Library context
1182 * @param [in] enctype Encryption type
1183 * @param [in,out] data IOV array
1184 * @param [in] num_data Size of @a data
1186 * Padding is set to the actual padding required based on the provided
1187 * @a data buffers. Typically this API is used after setting up the data
1188 * buffers and #KRB5_CRYPTO_TYPE_SIGN_ONLY buffers, but before actually
1189 * allocating header, trailer and padding.
1191 * @retval 0 Success; otherwise - Kerberos error codes
1193 krb5_error_code KRB5_CALLCONV
1194 krb5_c_crypto_length_iov(krb5_context context, krb5_enctype enctype,
1195 krb5_crypto_iov *data, size_t num_data);
1198 * Return a number of padding octets.
1200 * @param [in] context Library context
1201 * @param [in] enctype Encryption type
1202 * @param [in] data_length Length of the plaintext to pad
1203 * @param [out] size Number of padding octets
1205 * This function returns the number of the padding octets required to pad
1206 * @a data_length octets of plaintext.
1208 * @retval 0 Success; otherwise - KRB5_BAD_ENCTYPE
1210 krb5_error_code KRB5_CALLCONV
1211 krb5_c_padding_length(krb5_context context, krb5_enctype enctype,
1212 size_t data_length, unsigned int *size);
1215 * Create a krb5_key from the enctype and key data in a keyblock.
1217 * @param [in] context Library context
1218 * @param [in] key_data Keyblock
1219 * @param [out] out Opaque key
1221 * The reference count on a key @a out is set to 1.
1222 * Use krb5_k_free_key() to free @a out when it is no longer needed.
1224 * @retval 0 Success; otherwise - KRB5_BAD_ENCTYPE
1226 krb5_error_code KRB5_CALLCONV
1227 krb5_k_create_key(krb5_context context, const krb5_keyblock *key_data,
1230 /** Increment the reference count on a key. */
1232 krb5_k_reference_key(krb5_context context, krb5_key key);
1234 /** Decrement the reference count on a key and free it if it hits zero. */
1236 krb5_k_free_key(krb5_context context, krb5_key key);
1238 /** Retrieve a copy of the keyblock from a krb5_key structure. */
1239 krb5_error_code KRB5_CALLCONV
1240 krb5_k_key_keyblock(krb5_context context, krb5_key key,
1241 krb5_keyblock **key_data);
1243 /** Retrieve the enctype of a krb5_key structure. */
1244 krb5_enctype KRB5_CALLCONV
1245 krb5_k_key_enctype(krb5_context context, krb5_key key);
1248 * Encrypt data using a key (operates on opaque key).
1250 * @param [in] context Library context
1251 * @param [in] key Encryption key
1252 * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
1253 * @param [in,out] cipher_state Cipher state; specify NULL if not needed
1254 * @param [in] input Data to be encrypted
1255 * @param [out] output Encrypted data
1257 * This function encrypts the data block @a input and stores the output into @a
1258 * output. The actual encryption key will be derived from @a key and @a usage
1259 * if key derivation is specified for the encryption type. If non-null, @a
1260 * cipher_state specifies the beginning state for the encryption operation, and
1261 * is updated with the state to be passed as input to the next operation.
1263 * @note The caller must initialize @a output and allocate at least enough
1264 * space for the result (using krb5_c_encrypt_length() to determine the amount
1265 * of space needed). @a output->length will be set to the actual length of the
1268 * @retval 0 Success; otherwise - Kerberos error codes
1270 krb5_error_code KRB5_CALLCONV
1271 krb5_k_encrypt(krb5_context context, krb5_key key, krb5_keyusage usage,
1272 const krb5_data *cipher_state, const krb5_data *input,
1273 krb5_enc_data *output);
1276 * Encrypt data in place supporting AEAD (operates on opaque key).
1278 * @param [in] context Library context
1279 * @param [in] key Encryption key
1280 * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
1281 * @param [in] cipher_state Cipher state; specify NULL if not needed
1282 * @param [in,out] data IOV array. Modified in-place.
1283 * @param [in] num_data Size of @a data
1285 * This function encrypts the data block @a data and stores the output in-place.
1286 * The actual encryption key will be derived from @a key and @a usage
1287 * if key derivation is specified for the encryption type. If non-null, @a
1288 * cipher_state specifies the beginning state for the encryption operation, and
1289 * is updated with the state to be passed as input to the next operation.
1290 * The caller must allocate the right number of krb5_crypto_iov
1291 * structures before calling into this API.
1293 * @note On return from a krb5_c_encrypt_iov() call, the @a data->length in the
1294 * iov structure are adjusted to reflect actual lengths of the ciphertext used.
1295 * For example, if the padding length is too large, the length will be reduced.
1296 * Lengths are never increased.
1298 * @note This function is similar to krb5_c_encrypt_iov(), but operates
1299 * on opaque key @a key.
1301 * @sa krb5_k_decrypt_iov()
1303 * @retval 0 Success; otherwise - Kerberos error codes
1305 krb5_error_code KRB5_CALLCONV
1306 krb5_k_encrypt_iov(krb5_context context, krb5_key key, krb5_keyusage usage,
1307 const krb5_data *cipher_state, krb5_crypto_iov *data,
1311 * Decrypt data using a key (operates on opaque key).
1313 * @param [in] context Library context
1314 * @param [in] key Encryption key
1315 * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
1316 * @param [in,out] cipher_state Cipher state; specify NULL if not needed
1317 * @param [in] input Encrypted data
1318 * @param [out] output Decrypted data
1320 * This function decrypts the data block @a input and stores the output into @a
1321 * output. The actual decryption key will be derived from @a key and @a usage
1322 * if key derivation is specified for the encryption type. If non-null, @a
1323 * cipher_state specifies the beginning state for the decryption operation, and
1324 * is updated with the state to be passed as input to the next operation.
1326 * @note The caller must initialize @a output and allocate at least enough
1327 * space for the result. The usual practice is to allocate an output buffer as
1328 * long as the ciphertext, and let krb5_c_decrypt() trim @a output->length.
1329 * For some enctypes, the resulting @a output->length may include padding
1332 * @retval 0 Success; otherwise - Kerberos error codes
1334 krb5_error_code KRB5_CALLCONV
1335 krb5_k_decrypt(krb5_context context, krb5_key key, krb5_keyusage usage,
1336 const krb5_data *cipher_state, const krb5_enc_data *input,
1340 * Decrypt data in place supporting AEAD (operates on opaque key).
1342 * @param [in] context Library context
1343 * @param [in] key Encryption key
1344 * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
1345 * @param [in] cipher_state Cipher state; specify NULL if not needed
1346 * @param [in,out] data IOV array. Modified in-place.
1347 * @param [in] num_data Size of @a data
1349 * This function decrypts the data block @a data and stores the output in-place.
1350 * The actual decryption key will be derived from @a key and @a usage
1351 * if key derivation is specified for the encryption type. If non-null, @a
1352 * cipher_state specifies the beginning state for the decryption operation, and
1353 * is updated with the state to be passed as input to the next operation.
1354 * The caller must allocate the right number of krb5_crypto_iov
1355 * structures before calling into this API.
1357 * @note On return from a krb5_c_decrypt_iov() call, the @a data->length in the
1358 * iov structure are adjusted to reflect actual lengths of the ciphertext used.
1359 * For example, if the padding length is too large, the length will be reduced.
1360 * Lengths are never increased.
1362 * @note This function is similar to krb5_c_decrypt_iov(), but operates
1363 * on opaque key @a key.
1365 * @sa krb5_k_encrypt_iov()
1367 * @retval 0 Success; otherwise - Kerberos error codes
1369 krb5_error_code KRB5_CALLCONV
1370 krb5_k_decrypt_iov(krb5_context context, krb5_key key, krb5_keyusage usage,
1371 const krb5_data *cipher_state, krb5_crypto_iov *data,
1374 * Compute a checksum (operates on opaque key).
1376 * @param [in] context Library context
1377 * @param [in] cksumtype Checksum type (0 for mandatory type)
1378 * @param [in] key Encryption key for a keyed checksum
1379 * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
1380 * @param [in] input Input data
1381 * @param [out] cksum Generated checksum
1383 * This function computes a checksum of type @a cksumtype over @a input, using
1384 * @a key if the checksum type is a keyed checksum. If @a cksumtype is 0 and
1385 * @a key is non-null, the checksum type will be the mandatory-to-implement
1386 * checksum type for the key's encryption type. The actual checksum key will
1387 * be derived from @a key and @a usage if key derivation is specified for the
1388 * checksum type. The newly created @a cksum must be released by calling
1389 * krb5_free_checksum_contents() when it is no longer needed.
1391 * @note This function is similar to krb5_c_make_checksum(), but operates
1394 * @sa krb5_c_verify_checksum()
1396 * @retval 0 Success; otherwise - Kerberos error codes
1398 krb5_error_code KRB5_CALLCONV
1399 krb5_k_make_checksum(krb5_context context, krb5_cksumtype cksumtype,
1400 krb5_key key, krb5_keyusage usage, const krb5_data *input,
1401 krb5_checksum *cksum);
1404 * Fill in a checksum element in IOV array (operates on opaque key)
1406 * @param [in] context Library context
1407 * @param [in] cksumtype Checksum type (0 for mandatory type)
1408 * @param [in] key Encryption key for a keyed checksum
1409 * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
1410 * @param [in,out] data IOV array
1411 * @param [in] num_data Size of @a data
1413 * Create a checksum in the #KRB5_CRYPTO_TYPE_CHECKSUM element over
1414 * #KRB5_CRYPTO_TYPE_DATA and #KRB5_CRYPTO_TYPE_SIGN_ONLY chunks in @a data.
1415 * Only the #KRB5_CRYPTO_TYPE_CHECKSUM region is modified.
1417 * @note This function is similar to krb5_c_make_checksum_iov(), but operates
1420 * @sa krb5_k_verify_checksum_iov()
1422 * @retval 0 Success; otherwise - Kerberos error codes
1424 krb5_error_code KRB5_CALLCONV
1425 krb5_k_make_checksum_iov(krb5_context context, krb5_cksumtype cksumtype,
1426 krb5_key key, krb5_keyusage usage,
1427 krb5_crypto_iov *data, size_t num_data);
1430 * Verify a checksum (operates on opaque key).
1432 * @param [in] context Library context
1433 * @param [in] key Encryption key for a keyed checksum
1434 * @param [in] usage @a key usage
1435 * @param [in] data Data to be used to compute a new checksum
1436 * using @a key to compare @a cksum against
1437 * @param [in] cksum Checksum to be verified
1438 * @param [out] valid Non-zero for success, zero for failure
1440 * This function verifies that @a cksum is a valid checksum for @a data. If
1441 * the checksum type of @a cksum is a keyed checksum, @a key is used to verify
1442 * the checksum. The actual checksum key will be derived from @a key and @a
1443 * usage if key derivation is specified for the checksum type.
1445 * @note This function is similar to krb5_c_verify_checksum(), but operates
1448 * @retval 0 Success; otherwise - Kerberos error codes
1450 krb5_error_code KRB5_CALLCONV
1451 krb5_k_verify_checksum(krb5_context context, krb5_key key, krb5_keyusage usage,
1452 const krb5_data *data, const krb5_checksum *cksum,
1453 krb5_boolean *valid);
1456 * Validate a checksum element in IOV array (operates on opaque key).
1458 * @param [in] context Library context
1459 * @param [in] cksumtype Checksum type (0 for mandatory type)
1460 * @param [in] key Encryption key for a keyed checksum
1461 * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
1462 * @param [in] data IOV array
1463 * @param [in] num_data Size of @a data
1464 * @param [out] valid Non-zero for success, zero for failure
1466 * Confirm that the checksum in the #KRB5_CRYPTO_TYPE_CHECKSUM element is a
1467 * valid checksum of the #KRB5_CRYPTO_TYPE_DATA and #KRB5_CRYPTO_TYPE_SIGN_ONLY
1468 * regions in the iov.
1470 * @note This function is similar to krb5_c_verify_checksum_iov(), but operates
1473 * @sa krb5_k_make_checksum_iov()
1475 * @retval 0 Success; otherwise - Kerberos error codes
1477 krb5_error_code KRB5_CALLCONV
1478 krb5_k_verify_checksum_iov(krb5_context context, krb5_cksumtype cksumtype,
1479 krb5_key key, krb5_keyusage usage,
1480 const krb5_crypto_iov *data, size_t num_data,
1481 krb5_boolean *valid);
1484 * Generate enctype-specific pseudo-random bytes (operates on opaque key).
1486 * @param [in] context Library context
1487 * @param [in] key Key
1488 * @param [in] input Input data
1489 * @param [out] output Output data
1491 * This function selects a pseudo-random function based on @a key and
1492 * computes its value over @a input, placing the result into @a output.
1493 * The caller must preinitialize @a output and allocate space for the
1496 * @note This function is similar to krb5_c_prf(), but operates
1499 * @retval 0 Success; otherwise - Kerberos error codes
1501 krb5_error_code KRB5_CALLCONV
1502 krb5_k_prf(krb5_context context, krb5_key key, krb5_data *input, krb5_data *output);
1504 #ifdef KRB5_OLD_CRYPTO
1506 * old cryptosystem routine prototypes. These are now layered
1507 * on top of the functions above.
1509 /** @deprecated Replaced by krb5_c_ API family.*/
1510 krb5_error_code KRB5_CALLCONV
1511 krb5_encrypt(krb5_context context, krb5_const_pointer inptr,
1512 krb5_pointer outptr, size_t size, krb5_encrypt_block *eblock,
1515 /** @deprecated Replaced by krb5_c_ API family. */
1516 krb5_error_code KRB5_CALLCONV
1517 krb5_decrypt(krb5_context context, krb5_const_pointer inptr,
1518 krb5_pointer outptr, size_t size, krb5_encrypt_block *eblock,
1521 /** @deprecated Replaced by krb5_c_ API family. */
1522 krb5_error_code KRB5_CALLCONV
1523 krb5_process_key(krb5_context context, krb5_encrypt_block *eblock,
1524 const krb5_keyblock * key);
1526 /** @deprecated Replaced by krb5_c_ API family. */
1527 krb5_error_code KRB5_CALLCONV
1528 krb5_finish_key(krb5_context context, krb5_encrypt_block * eblock);
1530 /** @deprecated See krb5_c_string_to_key() */
1531 krb5_error_code KRB5_CALLCONV
1532 krb5_string_to_key(krb5_context context, const krb5_encrypt_block *eblock,
1533 krb5_keyblock * keyblock, const krb5_data *data,
1534 const krb5_data *salt);
1536 /** @deprecated Replaced by krb5_c_ API family. */
1537 krb5_error_code KRB5_CALLCONV
1538 krb5_init_random_key(krb5_context context, const krb5_encrypt_block *eblock,
1539 const krb5_keyblock *keyblock, krb5_pointer *ptr);
1541 /** @deprecated Replaced by krb5_c_ API family. */
1542 krb5_error_code KRB5_CALLCONV
1543 krb5_finish_random_key(krb5_context context, const krb5_encrypt_block *eblock,
1546 /** @deprecated Replaced by krb5_c_ API family. */
1547 krb5_error_code KRB5_CALLCONV
1548 krb5_random_key(krb5_context context, const krb5_encrypt_block *eblock,
1549 krb5_pointer ptr, krb5_keyblock **keyblock);
1551 /** @deprecated Replaced by krb5_c_ API family. */
1552 krb5_enctype KRB5_CALLCONV
1553 krb5_eblock_enctype(krb5_context context, const krb5_encrypt_block *eblock);
1555 /** @deprecated Replaced by krb5_c_ API family. */
1556 krb5_error_code KRB5_CALLCONV
1557 krb5_use_enctype(krb5_context context, krb5_encrypt_block *eblock,
1558 krb5_enctype enctype);
1560 /** @deprecated Replaced by krb5_c_ API family. */
1561 size_t KRB5_CALLCONV
1562 krb5_encrypt_size(size_t length, krb5_enctype crypto);
1564 /** @deprecated See krb5_c_checksum_length() */
1565 size_t KRB5_CALLCONV
1566 krb5_checksum_size(krb5_context context, krb5_cksumtype ctype);
1568 /** @deprecated See krb5_c_make_checksum() */
1569 krb5_error_code KRB5_CALLCONV
1570 krb5_calculate_checksum(krb5_context context, krb5_cksumtype ctype,
1571 krb5_const_pointer in, size_t in_length,
1572 krb5_const_pointer seed, size_t seed_length,
1573 krb5_checksum * outcksum);
1575 /** @deprecated See krb5_c_verify_checksum() */
1576 krb5_error_code KRB5_CALLCONV
1577 krb5_verify_checksum(krb5_context context, krb5_cksumtype ctype,
1578 const krb5_checksum * cksum, krb5_const_pointer in,
1579 size_t in_length, krb5_const_pointer seed,
1580 size_t seed_length);
1582 #endif /* KRB5_OLD_CRYPTO */
1585 * end "encryption.h"
1589 * begin "fieldbits.h"
1592 /* kdc_options for kdc_request */
1593 /* options is 32 bits; each host is responsible to put the 4 bytes
1594 representing these bits into net order before transmission */
1595 /* #define KDC_OPT_RESERVED 0x80000000 */
1596 #define KDC_OPT_FORWARDABLE 0x40000000
1597 #define KDC_OPT_FORWARDED 0x20000000
1598 #define KDC_OPT_PROXIABLE 0x10000000
1599 #define KDC_OPT_PROXY 0x08000000
1600 #define KDC_OPT_ALLOW_POSTDATE 0x04000000
1601 #define KDC_OPT_POSTDATED 0x02000000
1602 /* #define KDC_OPT_UNUSED 0x01000000 */
1603 #define KDC_OPT_RENEWABLE 0x00800000
1604 /* #define KDC_OPT_UNUSED 0x00400000 */
1605 /* #define KDC_OPT_RESERVED 0x00200000 */
1606 /* #define KDC_OPT_RESERVED 0x00100000 */
1607 /* #define KDC_OPT_RESERVED 0x00080000 */
1608 /* #define KDC_OPT_RESERVED 0x00040000 */
1609 #define KDC_OPT_CNAME_IN_ADDL_TKT 0x00020000
1610 #define KDC_OPT_CANONICALIZE 0x00010000
1611 #define KDC_OPT_REQUEST_ANONYMOUS 0x00008000
1612 /* #define KDC_OPT_RESERVED 0x00004000 */
1613 /* #define KDC_OPT_RESERVED 0x00002000 */
1614 /* #define KDC_OPT_RESERVED 0x00001000 */
1615 /* #define KDC_OPT_RESERVED 0x00000800 */
1616 /* #define KDC_OPT_RESERVED 0x00000400 */
1617 /* #define KDC_OPT_RESERVED 0x00000200 */
1618 /* #define KDC_OPT_RESERVED 0x00000100 */
1619 /* #define KDC_OPT_RESERVED 0x00000080 */
1620 /* #define KDC_OPT_RESERVED 0x00000040 */
1621 #define KDC_OPT_DISABLE_TRANSITED_CHECK 0x00000020
1622 #define KDC_OPT_RENEWABLE_OK 0x00000010
1623 #define KDC_OPT_ENC_TKT_IN_SKEY 0x00000008
1624 /* #define KDC_OPT_UNUSED 0x00000004 */
1625 #define KDC_OPT_RENEW 0x00000002
1626 #define KDC_OPT_VALIDATE 0x00000001
1629 * Mask of ticket flags in the TGT which should be converted into KDC
1630 * options when using the TGT to get derivitive tickets.
1632 * New mask = KDC_OPT_FORWARDABLE | KDC_OPT_PROXIABLE |
1633 * KDC_OPT_ALLOW_POSTDATE | KDC_OPT_RENEWABLE
1635 #define KDC_TKT_COMMON_MASK 0x54800000
1637 /* definitions for ap_options fields */
1639 /** @defgroup AP_OPTS AP_OPTS
1641 * ap_options are 32 bits; each host is responsible to put the 4 bytes
1642 * representing these bits into net order before transmission
1645 #define AP_OPTS_RESERVED 0x80000000
1646 #define AP_OPTS_USE_SESSION_KEY 0x40000000 /**< Use session key */
1647 #define AP_OPTS_MUTUAL_REQUIRED 0x20000000 /**< Perform a mutual
1648 authentication exchange */
1649 #define AP_OPTS_ETYPE_NEGOTIATION 0x00000002
1650 #define AP_OPTS_USE_SUBKEY 0x00000001 /**< Generate a subsession key
1651 from the current session key
1654 /* #define AP_OPTS_RESERVED 0x10000000 */
1655 /* #define AP_OPTS_RESERVED 0x08000000 */
1656 /* #define AP_OPTS_RESERVED 0x04000000 */
1657 /* #define AP_OPTS_RESERVED 0x02000000 */
1658 /* #define AP_OPTS_RESERVED 0x01000000 */
1659 /* #define AP_OPTS_RESERVED 0x00800000 */
1660 /* #define AP_OPTS_RESERVED 0x00400000 */
1661 /* #define AP_OPTS_RESERVED 0x00200000 */
1662 /* #define AP_OPTS_RESERVED 0x00100000 */
1663 /* #define AP_OPTS_RESERVED 0x00080000 */
1664 /* #define AP_OPTS_RESERVED 0x00040000 */
1665 /* #define AP_OPTS_RESERVED 0x00020000 */
1666 /* #define AP_OPTS_RESERVED 0x00010000 */
1667 /* #define AP_OPTS_RESERVED 0x00008000 */
1668 /* #define AP_OPTS_RESERVED 0x00004000 */
1669 /* #define AP_OPTS_RESERVED 0x00002000 */
1670 /* #define AP_OPTS_RESERVED 0x00001000 */
1671 /* #define AP_OPTS_RESERVED 0x00000800 */
1672 /* #define AP_OPTS_RESERVED 0x00000400 */
1673 /* #define AP_OPTS_RESERVED 0x00000200 */
1674 /* #define AP_OPTS_RESERVED 0x00000100 */
1675 /* #define AP_OPTS_RESERVED 0x00000080 */
1676 /* #define AP_OPTS_RESERVED 0x00000040 */
1677 /* #define AP_OPTS_RESERVED 0x00000020 */
1678 /* #define AP_OPTS_RESERVED 0x00000010 */
1679 /* #define AP_OPTS_RESERVED 0x00000008 */
1680 /* #define AP_OPTS_RESERVED 0x00000004 */
1683 #define AP_OPTS_WIRE_MASK 0xfffffff0
1684 /** @} */ /* end of AP_OPTS group */
1686 /* definitions for ad_type fields. */
1687 #define AD_TYPE_RESERVED 0x8000
1688 #define AD_TYPE_EXTERNAL 0x4000
1689 #define AD_TYPE_REGISTERED 0x2000
1691 #define AD_TYPE_FIELD_TYPE_MASK 0x1fff
1694 /* flags are 32 bits; each host is responsible to put the 4 bytes
1695 representing these bits into net order before transmission */
1696 /* #define TKT_FLG_RESERVED 0x80000000 */
1697 #define TKT_FLG_FORWARDABLE 0x40000000
1698 #define TKT_FLG_FORWARDED 0x20000000
1699 #define TKT_FLG_PROXIABLE 0x10000000
1700 #define TKT_FLG_PROXY 0x08000000
1701 #define TKT_FLG_MAY_POSTDATE 0x04000000
1702 #define TKT_FLG_POSTDATED 0x02000000
1703 #define TKT_FLG_INVALID 0x01000000
1704 #define TKT_FLG_RENEWABLE 0x00800000
1705 #define TKT_FLG_INITIAL 0x00400000
1706 #define TKT_FLG_PRE_AUTH 0x00200000
1707 #define TKT_FLG_HW_AUTH 0x00100000
1708 #define TKT_FLG_TRANSIT_POLICY_CHECKED 0x00080000
1709 #define TKT_FLG_OK_AS_DELEGATE 0x00040000
1710 #define TKT_FLG_ENC_PA_REP 0x00010000
1711 #define TKT_FLG_ANONYMOUS 0x00008000
1712 /* #define TKT_FLG_RESERVED 0x00004000 */
1713 /* #define TKT_FLG_RESERVED 0x00002000 */
1714 /* #define TKT_FLG_RESERVED 0x00001000 */
1715 /* #define TKT_FLG_RESERVED 0x00000800 */
1716 /* #define TKT_FLG_RESERVED 0x00000400 */
1717 /* #define TKT_FLG_RESERVED 0x00000200 */
1718 /* #define TKT_FLG_RESERVED 0x00000100 */
1719 /* #define TKT_FLG_RESERVED 0x00000080 */
1720 /* #define TKT_FLG_RESERVED 0x00000040 */
1721 /* #define TKT_FLG_RESERVED 0x00000020 */
1722 /* #define TKT_FLG_RESERVED 0x00000010 */
1723 /* #define TKT_FLG_RESERVED 0x00000008 */
1724 /* #define TKT_FLG_RESERVED 0x00000004 */
1725 /* #define TKT_FLG_RESERVED 0x00000002 */
1726 /* #define TKT_FLG_RESERVED 0x00000001 */
1728 /* definitions for lr_type fields. */
1729 #define LR_TYPE_THIS_SERVER_ONLY 0x8000
1731 #define LR_TYPE_INTERPRETATION_MASK 0x7fff
1733 /* definitions for msec direction bit for KRB_SAFE, KRB_PRIV */
1734 #define MSEC_DIRBIT 0x8000
1735 #define MSEC_VAL_MASK 0x7fff
1745 /** Protocol version number */
1750 #define KRB5_AS_REQ ((krb5_msgtype)10) /**< Initial authentication request */
1751 #define KRB5_AS_REP ((krb5_msgtype)11) /**< Response to AS request */
1752 #define KRB5_TGS_REQ ((krb5_msgtype)12) /**< Ticket granting server request */
1753 #define KRB5_TGS_REP ((krb5_msgtype)13) /**< Response to TGS request */
1754 #define KRB5_AP_REQ ((krb5_msgtype)14) /**< Auth req to application server */
1755 #define KRB5_AP_REP ((krb5_msgtype)15) /**< Response to mutual AP request */
1756 #define KRB5_SAFE ((krb5_msgtype)20) /**< Safe application message */
1757 #define KRB5_PRIV ((krb5_msgtype)21) /**< Private application message */
1758 #define KRB5_CRED ((krb5_msgtype)22) /**< Cred forwarding message */
1759 #define KRB5_ERROR ((krb5_msgtype)30) /**< Error response */
1762 #define KRB5_LRQ_NONE 0
1763 #define KRB5_LRQ_ALL_LAST_TGT 1
1764 #define KRB5_LRQ_ONE_LAST_TGT (-1)
1765 #define KRB5_LRQ_ALL_LAST_INITIAL 2
1766 #define KRB5_LRQ_ONE_LAST_INITIAL (-2)
1767 #define KRB5_LRQ_ALL_LAST_TGT_ISSUED 3
1768 #define KRB5_LRQ_ONE_LAST_TGT_ISSUED (-3)
1769 #define KRB5_LRQ_ALL_LAST_RENEWAL 4
1770 #define KRB5_LRQ_ONE_LAST_RENEWAL (-4)
1771 #define KRB5_LRQ_ALL_LAST_REQ 5
1772 #define KRB5_LRQ_ONE_LAST_REQ (-5)
1773 #define KRB5_LRQ_ALL_PW_EXPTIME 6
1774 #define KRB5_LRQ_ONE_PW_EXPTIME (-6)
1775 #define KRB5_LRQ_ALL_ACCT_EXPTIME 7
1776 #define KRB5_LRQ_ONE_ACCT_EXPTIME (-7)
1779 #define KRB5_PADATA_NONE 0
1780 #define KRB5_PADATA_AP_REQ 1
1781 #define KRB5_PADATA_TGS_REQ KRB5_PADATA_AP_REQ
1782 #define KRB5_PADATA_ENC_TIMESTAMP 2
1783 #define KRB5_PADATA_PW_SALT 3
1784 #if 0 /* Not used */
1785 #define KRB5_PADATA_ENC_ENCKEY 4 /* Key encrypted within itself */
1787 #define KRB5_PADATA_ENC_UNIX_TIME 5 /**< timestamp encrypted in key */
1788 #define KRB5_PADATA_ENC_SANDIA_SECURID 6 /**< SecurId passcode */
1789 #define KRB5_PADATA_SESAME 7 /**< Sesame project */
1790 #define KRB5_PADATA_OSF_DCE 8 /**< OSF DCE */
1791 #define KRB5_CYBERSAFE_SECUREID 9 /**< Cybersafe */
1792 #define KRB5_PADATA_AFS3_SALT 10 /**< Cygnus */
1793 #define KRB5_PADATA_ETYPE_INFO 11 /**< Etype info for preauth */
1794 #define KRB5_PADATA_SAM_CHALLENGE 12 /**< draft challenge system */
1795 #define KRB5_PADATA_SAM_RESPONSE 13 /**< draft challenge system response */
1796 #define KRB5_PADATA_PK_AS_REQ_OLD 14 /**< PKINIT */
1797 #define KRB5_PADATA_PK_AS_REP_OLD 15 /**< PKINIT */
1798 #define KRB5_PADATA_PK_AS_REQ 16 /**< PKINIT */
1799 #define KRB5_PADATA_PK_AS_REP 17 /**< PKINIT */
1800 #define KRB5_PADATA_ETYPE_INFO2 19
1801 #define KRB5_PADATA_USE_SPECIFIED_KVNO 20
1802 #define KRB5_PADATA_SVR_REFERRAL_INFO 20 /**< Windows 2000 referrals */
1803 #define KRB5_PADATA_SAM_REDIRECT 21
1804 #define KRB5_PADATA_GET_FROM_TYPED_DATA 22
1805 #define KRB5_PADATA_REFERRAL 25 /**< draft referral system */
1806 #define KRB5_PADATA_SAM_CHALLENGE_2 30 /**< draft challenge system, updated */
1807 #define KRB5_PADATA_SAM_RESPONSE_2 31 /**< draft challenge system, updated */
1808 #define KRB5_PADATA_PAC_REQUEST 128 /**< include Windows PAC */
1809 #define KRB5_PADATA_FOR_USER 129 /**< username protocol transition request */
1810 #define KRB5_PADATA_S4U_X509_USER 130 /**< certificate protocol transition request */
1811 #define KRB5_PADATA_FX_COOKIE 133
1812 #define KRB5_PADATA_FX_FAST 136
1813 #define KRB5_PADATA_FX_ERROR 137
1814 #define KRB5_PADATA_ENCRYPTED_CHALLENGE 138
1815 #define KRB5_PADATA_PKINIT_KX 147
1816 #define KRB5_ENCPADATA_REQ_ENC_PA_REP 149
1818 #define KRB5_SAM_USE_SAD_AS_KEY 0x80000000
1819 #define KRB5_SAM_SEND_ENCRYPTED_SAD 0x40000000
1820 #define KRB5_SAM_MUST_PK_ENCRYPT_SAD 0x20000000 /* currently must be zero */
1822 /** Transited encoding types */
1823 #define KRB5_DOMAIN_X500_COMPRESS 1
1825 /** alternate authentication types */
1826 #define KRB5_ALTAUTH_ATT_CHALLENGE_RESPONSE 64
1828 /* authorization data types. See RFC 4120 section 5.2.6 */
1830 /** @defgroup KRB5_AUTHDATA KRB5_AUTHDATA
1833 #define KRB5_AUTHDATA_IF_RELEVANT 1
1834 #define KRB5_AUTHDATA_KDC_ISSUED 4
1835 #define KRB5_AUTHDATA_AND_OR 5
1836 #define KRB5_AUTHDATA_MANDATORY_FOR_KDC 8
1837 #define KRB5_AUTHDATA_INITIAL_VERIFIED_CAS 9
1838 #define KRB5_AUTHDATA_OSF_DCE 64
1839 #define KRB5_AUTHDATA_SESAME 65
1840 #define KRB5_AUTHDATA_WIN2K_PAC 128
1841 #define KRB5_AUTHDATA_ETYPE_NEGOTIATION 129 /* RFC 4537 */
1842 #define KRB5_AUTHDATA_SIGNTICKET 512 /**< formerly 142 in krb5 1.8 */
1843 #define KRB5_AUTHDATA_FX_ARMOR 71
1844 /** @} */ /* end of KRB5_AUTHDATA group */
1846 /* password change constants */
1847 #define KRB5_KPASSWD_SUCCESS 0 /**< Success */
1848 #define KRB5_KPASSWD_MALFORMED 1 /**< Malformed request */
1849 #define KRB5_KPASSWD_HARDERROR 2 /**< Server error */
1850 #define KRB5_KPASSWD_AUTHERROR 3 /**< Authentication error */
1851 #define KRB5_KPASSWD_SOFTERROR 4 /**< Password change rejected */
1852 /* These are Microsoft's extensions in RFC 3244, and it looks like
1853 they'll become standardized, possibly with other additions. */
1854 #define KRB5_KPASSWD_ACCESSDENIED 5 /* unused */
1855 #define KRB5_KPASSWD_BAD_VERSION 6
1856 #define KRB5_KPASSWD_INITIAL_FLAG_NEEDED 7 /* unused */
1863 /** Ticket start time, end time, and renewal duration. */
1864 typedef struct _krb5_ticket_times {
1865 krb5_timestamp authtime; /**< Time at which KDC issued the initial ticket that corresponds to this ticket */
1866 /* XXX ? should ktime in KDC_REP == authtime
1867 in ticket? otherwise client can't get this */
1868 krb5_timestamp starttime; /**< optional in ticket, if not present, use @a authtime */
1869 krb5_timestamp endtime; /**< Ticket expiration time */
1870 krb5_timestamp renew_till; /**< Latest time at which renewal of ticket can be valid */
1871 } krb5_ticket_times;
1873 /** Structure for auth data */
1874 typedef struct _krb5_authdata {
1876 krb5_authdatatype ad_type; /**< ADTYPE */
1877 unsigned int length; /**< Length of data */
1878 krb5_octet *contents; /**< Data */
1881 /** Structure for transited encoding */
1882 typedef struct _krb5_transited {
1884 krb5_octet tr_type; /**< Transited encoding type */
1885 krb5_data tr_contents; /**< Contents */
1888 /** Encrypted part of ticket. */
1889 typedef struct _krb5_enc_tkt_part {
1891 /* to-be-encrypted portion */
1892 krb5_flags flags; /**< flags */
1893 krb5_keyblock *session; /**< session key: includes enctype */
1894 krb5_principal client; /**< client name/realm */
1895 krb5_transited transited; /**< list of transited realms */
1896 krb5_ticket_times times; /**< auth, start, end, renew_till */
1897 krb5_address **caddrs; /**< array of ptrs to addresses */
1898 krb5_authdata **authorization_data; /**< auth data */
1899 } krb5_enc_tkt_part;
1904 * The C representation of the ticket message, with a pointer to the
1905 * C representation of the encrypted part.
1907 typedef struct _krb5_ticket {
1909 /* cleartext portion */
1910 krb5_principal server; /**< server name/realm */
1911 krb5_enc_data enc_part; /**< encryption type, kvno, encrypted encoding */
1912 krb5_enc_tkt_part *enc_part2; /**< ptr to decrypted version, if available */
1915 /* the unencrypted version */
1917 * Ticket authenticator.
1919 * The C representation of an unencrypted authenticator.
1921 typedef struct _krb5_authenticator {
1923 krb5_principal client; /**< client name/realm */
1924 krb5_checksum *checksum; /**< checksum, includes type, optional */
1925 krb5_int32 cusec; /**< client usec portion */
1926 krb5_timestamp ctime; /**< client sec portion */
1927 krb5_keyblock *subkey; /**< true session key, optional */
1928 krb5_ui_4 seq_number; /**< sequence #, optional */
1929 krb5_authdata **authorization_data; /**< authoriazation data */
1930 } krb5_authenticator;
1932 /** Ticket authentication data. */
1933 typedef struct _krb5_tkt_authent {
1935 krb5_ticket *ticket;
1936 krb5_authenticator *authenticator;
1937 krb5_flags ap_options;
1940 /** Credentials structure including ticket, session key, and lifetime info. */
1941 typedef struct _krb5_creds {
1943 krb5_principal client; /**< client's principal identifier */
1944 krb5_principal server; /**< server's principal identifier */
1945 krb5_keyblock keyblock; /**< session encryption key info */
1946 krb5_ticket_times times; /**< lifetime info */
1947 krb5_boolean is_skey; /**< true if ticket is encrypted in
1948 another ticket's skey */
1949 krb5_flags ticket_flags; /**< flags in ticket */
1950 krb5_address **addresses; /**< addrs in ticket */
1951 krb5_data ticket; /**< ticket string itself */
1952 krb5_data second_ticket; /**< second ticket, if related to
1953 ticket (via DUPLICATE-SKEY or
1955 krb5_authdata **authdata; /**< authorization data */
1958 /** Last request entry */
1959 typedef struct _krb5_last_req_entry {
1961 krb5_int32 lr_type; /**< LR type */
1962 krb5_timestamp value; /**< Timestamp */
1963 } krb5_last_req_entry;
1965 /** Pre-authentication data */
1966 typedef struct _krb5_pa_data {
1968 krb5_preauthtype pa_type; /**< Preauthentication data type */
1969 unsigned int length; /**< Length of data */
1970 krb5_octet *contents; /**< Data */
1973 /* Don't use this; use krb5_pa_data instead. */
1974 typedef struct _krb5_typed_data {
1977 unsigned int length;
1981 /** C representation of KDC-REQ protocol message, including KDC-REQ-BODY */
1982 typedef struct _krb5_kdc_req {
1984 krb5_msgtype msg_type; /**< KRB5_AS_REQ or KRB5_TGS_REQ */
1985 krb5_pa_data **padata; /**< Preauthentication data */
1987 krb5_flags kdc_options; /**< Requested options */
1988 krb5_principal client; /**< Client principal and realm */
1989 krb5_principal server; /**< Server principal and realm */
1990 krb5_timestamp from; /**< Requested start time */
1991 krb5_timestamp till; /**< Requested end time */
1992 krb5_timestamp rtime; /**< Requested renewable end time */
1993 krb5_int32 nonce; /**< Nonce to match request andresponse */
1994 int nktypes; /**< Number of enctypes */
1995 krb5_enctype *ktype; /**< Requested enctypes */
1996 krb5_address **addresses; /**< Requested addresses (optional) */
1997 krb5_enc_data authorization_data; /**< Encrypted authz data (optional) */
1998 krb5_authdata **unenc_authdata; /**< Unencrypted authz data */
1999 krb5_ticket **second_ticket; /**< Second ticket array (optional) */
2003 * C representation of @c EncKDCRepPart protocol message.
2005 * This is the cleartext message that is encrypted and inserted in @c KDC-REP.
2007 typedef struct _krb5_enc_kdc_rep_part {
2009 /* encrypted part: */
2010 krb5_msgtype msg_type; /**< krb5 message type */
2011 krb5_keyblock *session; /**< Session key */
2012 krb5_last_req_entry **last_req; /**< Array of pointers to entries */
2013 krb5_int32 nonce; /**< Nonce from request */
2014 krb5_timestamp key_exp; /**< Expiration date */
2015 krb5_flags flags; /**< Ticket flags */
2016 krb5_ticket_times times; /**< Lifetime info */
2017 krb5_principal server; /**< Server's principal identifier */
2018 krb5_address **caddrs; /**< Array of ptrs to addrs, optional */
2019 krb5_pa_data **enc_padata; /**< Encrypted preauthentication data */
2020 } krb5_enc_kdc_rep_part;
2022 /** Representation of the @c KDC-REP protocol message. */
2023 typedef struct _krb5_kdc_rep {
2025 /* cleartext part: */
2026 krb5_msgtype msg_type; /**< KRB5_AS_REP or KRB5_KDC_REP */
2027 krb5_pa_data **padata; /**< Preauthentication data from KDC */
2028 krb5_principal client; /**< Client principal and realm */
2029 krb5_ticket *ticket; /**< Ticket */
2030 krb5_enc_data enc_part; /**< Encrypted part of reply */
2031 krb5_enc_kdc_rep_part *enc_part2; /**< Unencrypted version, if available */
2034 /** Error message structure */
2035 typedef struct _krb5_error {
2037 /* some of these may be meaningless in certain contexts */
2038 krb5_timestamp ctime; /**< Client sec portion; optional */
2039 krb5_int32 cusec; /**< Client usec portion; optional */
2040 krb5_int32 susec; /**< Server usec portion */
2041 krb5_timestamp stime; /**< Server sec portion */
2042 krb5_ui_4 error; /**< Error code (protocol error #'s) */
2043 krb5_principal client; /**< Client principal and realm */
2044 krb5_principal server; /**< Server principal and realm */
2045 krb5_data text; /**< Descriptive text */
2046 krb5_data e_data; /**< Additional error-describing data */
2049 /** Authentication header. */
2050 typedef struct _krb5_ap_req {
2052 krb5_flags ap_options; /**< Requested options */
2053 krb5_ticket *ticket; /**< Ticket */
2054 krb5_enc_data authenticator; /**< Encrypted authenticator */
2058 * C representaton of AP-REP message.
2060 * The server's response to a client's request for mutual authentication.
2062 typedef struct _krb5_ap_rep {
2064 krb5_enc_data enc_part; /**< Ciphertext of ApRepEncPart */
2067 /** Cleartext that is encrypted and put into @c _krb5_ap_rep. */
2068 typedef struct _krb5_ap_rep_enc_part {
2070 krb5_timestamp ctime; /**< Client time, seconds portion */
2071 krb5_int32 cusec; /**< Client time, microseconds portion */
2072 krb5_keyblock *subkey; /**< Subkey (optional) */
2073 krb5_ui_4 seq_number; /**< Sequence number */
2074 } krb5_ap_rep_enc_part;
2077 typedef struct _krb5_response {
2079 krb5_octet message_type;
2081 krb5_int32 expected_nonce;
2082 krb5_timestamp request_time;
2085 /** Credentials information inserted into @c EncKrbCredPart. */
2086 typedef struct _krb5_cred_info {
2088 krb5_keyblock *session; /**< Session key used to encrypt ticket */
2089 krb5_principal client; /**< Client principal and realm */
2090 krb5_principal server; /**< Server principal and realm */
2091 krb5_flags flags; /**< Ticket flags */
2092 krb5_ticket_times times; /**< Auth, start, end, renew_till */
2093 krb5_address **caddrs; /**< Array of pointers to addrs (optional) */
2096 /** Cleartext credentials information. */
2097 typedef struct _krb5_cred_enc_part {
2099 krb5_int32 nonce; /**< Nonce (optional) */
2100 krb5_timestamp timestamp; /**< Generation time, seconds portion */
2101 krb5_int32 usec; /**< Generation time, microseconds portion */
2102 krb5_address *s_address; /**< Sender address (optional) */
2103 krb5_address *r_address; /**< Recipient address (optional) */
2104 krb5_cred_info **ticket_info;
2105 } krb5_cred_enc_part;
2107 /** Credentials data structure.*/
2108 typedef struct _krb5_cred {
2110 krb5_ticket **tickets; /**< Tickets */
2111 krb5_enc_data enc_part; /**< Encrypted part */
2112 krb5_cred_enc_part *enc_part2; /**< Unencrypted version, if available */
2115 /* Unused, but here for API compatibility. */
2116 typedef struct _passwd_phrase_element {
2120 } passwd_phrase_element;
2122 /* Unused, but here for API compatibility. */
2123 typedef struct _krb5_pwd_data {
2126 passwd_phrase_element **element;
2129 /* Unused, but here for API compatibility. */
2130 typedef struct _krb5_pa_svr_referral_data {
2131 /** Referred name, only realm is required */
2132 krb5_principal principal;
2133 } krb5_pa_svr_referral_data;
2135 /* Unused, but here for API compatibility. */
2136 typedef struct _krb5_pa_server_referral_data {
2137 krb5_data *referred_realm;
2138 krb5_principal true_principal_name;
2139 krb5_principal requested_principal_name;
2140 krb5_timestamp referral_valid_until;
2141 krb5_checksum rep_cksum;
2142 } krb5_pa_server_referral_data;
2144 typedef struct _krb5_pa_pac_req {
2145 /** TRUE if a PAC should be included in TGS-REP */
2146 krb5_boolean include_pac;
2150 * begin "safepriv.h"
2153 /** @defgroup KRB5_AUTH_CONTEXT KRB5_AUTH_CONTEXT
2156 /** Prevent replays with timestamps and replay cache. */
2157 #define KRB5_AUTH_CONTEXT_DO_TIME 0x00000001
2158 /** Save timestamps for application. */
2159 #define KRB5_AUTH_CONTEXT_RET_TIME 0x00000002
2160 /** Prevent replays with sequence numbers. */
2161 #define KRB5_AUTH_CONTEXT_DO_SEQUENCE 0x00000004
2162 /** Save sequence numbers for application. */
2163 #define KRB5_AUTH_CONTEXT_RET_SEQUENCE 0x00000008
2164 #define KRB5_AUTH_CONTEXT_PERMIT_ALL 0x00000010
2165 #define KRB5_AUTH_CONTEXT_USE_SUBKEY 0x00000020
2166 /** @} */ /* end of KRB5_AUTH_CONTEXT group */
2171 * Sequence number and timestamp information output by krb5_rd_priv() and
2174 typedef struct krb5_replay_data {
2175 krb5_timestamp timestamp; /**< Timestamp, seconds portion */
2176 krb5_int32 usec; /**< Timestamp, microseconds portion */
2177 krb5_ui_4 seq; /**< Sequence number */
2180 /* Flags for krb5_auth_con_genaddrs(). */
2182 /** Generate the local network address. */
2183 #define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR 0x00000001
2184 /** Generate the remote network address. */
2185 #define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR 0x00000002
2186 /** Generate the local network address and the local port. */
2187 #define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR 0x00000004
2188 /** Generate the remote network address and the remote port. */
2189 #define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR 0x00000008
2191 /** Type of function used as a callback to generate checksum data for mk_req */
2192 typedef krb5_error_code
2193 (KRB5_CALLCONV * krb5_mk_req_checksum_func)(krb5_context, krb5_auth_context,
2194 void *, krb5_data **);
2205 /** Cursor for sequential lookup */
2206 typedef krb5_pointer krb5_cc_cursor;
2208 struct _krb5_ccache;
2209 typedef struct _krb5_ccache *krb5_ccache;
2210 struct _krb5_cc_ops;
2211 typedef struct _krb5_cc_ops krb5_cc_ops;
2213 struct _krb5_cccol_cursor;
2214 /** Cursor for iterating over all ccaches */
2215 typedef struct _krb5_cccol_cursor *krb5_cccol_cursor;
2217 /* Flags for krb5_cc_retrieve_cred. */
2218 /** The requested lifetime must be at least as great as the time specified. */
2219 #define KRB5_TC_MATCH_TIMES 0x00000001
2220 /** The is_skey field must match exactly. */
2221 #define KRB5_TC_MATCH_IS_SKEY 0x00000002
2222 /** All the flags set in the match credentials must be set. */
2223 #define KRB5_TC_MATCH_FLAGS 0x00000004
2224 /** All the time fields must match exactly. */
2225 #define KRB5_TC_MATCH_TIMES_EXACT 0x00000008
2226 /** All the flags must match exactly. */
2227 #define KRB5_TC_MATCH_FLAGS_EXACT 0x00000010
2228 /** The authorization data must match. */
2229 #define KRB5_TC_MATCH_AUTHDATA 0x00000020
2230 /** Only the name portion of the principal name must match. */
2231 #define KRB5_TC_MATCH_SRV_NAMEONLY 0x00000040
2232 /** The second ticket must match. */
2233 #define KRB5_TC_MATCH_2ND_TKT 0x00000080
2234 /** The encryption key type must match. */
2235 #define KRB5_TC_MATCH_KTYPE 0x00000100
2236 /** The supported key types must match. */
2237 #define KRB5_TC_SUPPORTED_KTYPES 0x00000200
2239 /* Flags for krb5_cc_set_flags and similar. */
2240 /** Open and close the file for each cache operation. */
2241 #define KRB5_TC_OPENCLOSE 0x00000001
2242 #define KRB5_TC_NOTICKET 0x00000002
2245 * Retrieve the name, but not type of a credential cache.
2247 * @param [in] context Library context
2248 * @param [in] cache Credential cache handle
2250 * @warning Returns the name of the credential cache. The result is an alias
2251 * into @a cache and should not be freed or modified by the caller. This name
2252 * does not include the cache type, so should not be used as input to
2253 * krb5_cc_resolve().
2256 * On success - the name of the credential cache.
2258 const char * KRB5_CALLCONV
2259 krb5_cc_get_name(krb5_context context, krb5_ccache cache);
2262 * Retrieve the full name of a credential cache.
2264 * @param [in] context Library context
2265 * @param [in] cache Credential cache handle
2266 * @param [out] fullname_out Full name of cache
2268 * @version First introduced in 1.10
2270 krb5_error_code KRB5_CALLCONV
2271 krb5_cc_get_full_name(krb5_context context, krb5_ccache cache,
2272 char **fullname_out);
2275 krb5_error_code KRB5_CALLCONV
2276 krb5_cc_gen_new(krb5_context context, krb5_ccache *cache);
2277 #endif /* KRB5_DEPRECATED */
2280 * Initialize a credential cache.
2282 * @param [in] context Library context
2283 * @param [in] cache Credential cache handle
2284 * @param [in] principal Default principal name
2286 * Destroy any existing contents of @a cache and initialize it for the default
2287 * principal @a principal.
2292 * System errors; Permission errors; Kerberos error codes
2294 krb5_error_code KRB5_CALLCONV
2295 krb5_cc_initialize(krb5_context context, krb5_ccache cache,
2296 krb5_principal principal);
2299 * Destroy a credential cache.
2301 * @param [in] context Library context
2302 * @param [in] cache Credential cache handle
2304 * This function destroys any existing contents of @a cache and closes the
2312 krb5_error_code KRB5_CALLCONV
2313 krb5_cc_destroy(krb5_context context, krb5_ccache cache);
2316 * Close a credential cache handle.
2318 * @param [in] context Library context
2319 * @param [in] cache Credential cache handle
2321 * This function closes a credential cache handle @a cache without affecting
2322 * the contents of the cache.
2327 * Kerberos error codes
2329 krb5_error_code KRB5_CALLCONV
2330 krb5_cc_close(krb5_context context, krb5_ccache cache);
2333 * Store credentials in a credential cache.
2335 * @param [in] context Library context
2336 * @param [in,out] cache Credential cache handle
2337 * @param [in] creds Credentials to be stored in cache
2339 * This function stores @a creds into @a cache. If @a creds->server and the
2340 * server in the decoded ticket @a creds->ticket differ, the credentials will
2341 * be stored under both server principal names.
2345 * @return Permission errors; storage failure errors; Kerberos error codes
2347 krb5_error_code KRB5_CALLCONV
2348 krb5_cc_store_cred(krb5_context context, krb5_ccache cache, krb5_creds *creds);
2351 * Retrieve a specified credentials from a credential cache.
2353 * @param [in] context Library context
2354 * @param [in] cache Credential cache handle
2355 * @param [in] flags Flags bit mask
2356 * @param [in] mcreds Credentials to match
2357 * @param [out] creds Credentials matching the requested value
2359 * This function searches a credential cache for credentials matching @a mcreds
2360 * and returns it if found.
2362 * Valid values for @a flags are:
2364 * @li #KRB5_TC_MATCH_TIMES The requested lifetime must be at least as
2365 * great as in @a mcreds .
2366 * @li #KRB5_TC_MATCH_IS_SKEY The @a is_skey field much match exactly.
2367 * @li #KRB5_TC_MATCH_FLAGS Flags set in @a mcreds must be set.
2368 * @li #KRB5_TC_MATCH_TIMES_EXACT The requested lifetime must match exactly.
2369 * @li #KRB5_TC_MATCH_FLAGS_EXACT Flags must match exactly.
2370 * @li #KRB5_TC_MATCH_AUTHDATA The authorization data must match.
2371 * @li #KRB5_TC_MATCH_SRV_NAMEONLY Only the name portion of the principal
2372 * name must match, not the realm.
2373 * @li #KRB5_TC_MATCH_2ND_TKT The second tickets must match.
2374 * @li #KRB5_TC_MATCH_KTYPE The encryption key types must match.
2375 * @li #KRB5_TC_SUPPORTED_KTYPES Check all matching entries that have any
2376 * supported encryption type and return the
2377 * one with the encryption type listed earliest.
2379 * Use krb5_free_cred_contents() to free @a creds when it is no longer needed.
2381 * @retval 0 Success; otherwise - Kerberos error codes
2383 krb5_error_code KRB5_CALLCONV
2384 krb5_cc_retrieve_cred(krb5_context context, krb5_ccache cache,
2385 krb5_flags flags, krb5_creds *mcreds,
2389 * Get the default principal of a credential cache.
2391 * @param [in] context Library context
2392 * @param [in] cache Credential cache handle
2393 * @param [out] principal Primary principal
2395 * Returns the default client principal of a credential cache as set by
2396 * krb5_cc_initialize().
2398 * Use krb5_free_principal() to free @a principal when it is no longer needed.
2403 * Kerberos error codes
2405 krb5_error_code KRB5_CALLCONV
2406 krb5_cc_get_principal(krb5_context context, krb5_ccache cache,
2407 krb5_principal *principal);
2410 * Prepare to sequentially read every credential in a credential cache.
2412 * @param [in] context Library context
2413 * @param [in] cache Credential cache handle
2414 * @param [out] cursor Cursor
2416 * krb5_cc_end_seq_get() must be called to complete the retrieve operation.
2418 * @note If @a cache is modified between the time of the call to this function
2419 * and the time of the final krb5_cc_end_seq_get(), the results are undefined.
2421 * @retval 0 Success; otherwise - Kerberos error codes
2423 krb5_error_code KRB5_CALLCONV
2424 krb5_cc_start_seq_get(krb5_context context, krb5_ccache cache,
2425 krb5_cc_cursor *cursor);
2428 * Retrieve the next entry from the credential cache.
2430 * @param [in] context Library context
2431 * @param [in] cache Credential cache handle
2432 * @param [in,out] cursor Cursor
2433 * @param [out] creds Next credential cache entry
2435 * This function fills in @a creds with the next entry in @a cache and advances
2438 * Use krb5_free_cred_contents() to free @a creds when it is no longer needed.
2440 * @sa krb5_cc_start_seq_get(), krb5_end_seq_get()
2442 * @retval 0 Success; otherwise - Kerberos error codes
2444 krb5_error_code KRB5_CALLCONV
2445 krb5_cc_next_cred(krb5_context context, krb5_ccache cache,
2446 krb5_cc_cursor *cursor, krb5_creds *creds);
2449 * Finish a series of sequential processing credential cache entries.
2451 * @param [in] context Library context
2452 * @param [in] cache Credential cache handle
2453 * @param [in,out] cursor Cursor
2455 * This function finishes processing credential cache entries and invalidates
2458 * @sa krb5_cc_start_seq_get(), krb5_cc_next_cred()
2460 * @retval 0 (always)
2462 krb5_error_code KRB5_CALLCONV
2463 krb5_cc_end_seq_get(krb5_context context, krb5_ccache cache,
2464 krb5_cc_cursor *cursor);
2467 * Remove credentials from a credential cache.
2469 * @param [in] context Library context
2470 * @param [in] cache Credential cache handle
2471 * @param [in] flags Bitwise-ORed search flags
2472 * @param [in] creds Credentials to be matched
2474 * @warning This function is not implemented for some cache types.
2476 * This function accepts the same flag values as krb5_cc_retrieve_cred().
2478 * @retval KRB5_CC_NOSUPP Not implemented for this cache type
2479 * @return No matches found; Data cannot be deleted; Kerberos error codes
2481 krb5_error_code KRB5_CALLCONV
2482 krb5_cc_remove_cred(krb5_context context, krb5_ccache cache, krb5_flags flags,
2486 * Set options flags on a credential cache.
2488 * @param [in] context Library context
2489 * @param [in,out] cache Credential cache handle
2490 * @param [in] flags Flag bit mask
2492 * This function resets @a cache flags to @a flags.
2494 * @retval 0 Success; otherwise - Kerberos error codes
2496 krb5_error_code KRB5_CALLCONV
2497 krb5_cc_set_flags(krb5_context context, krb5_ccache cache, krb5_flags flags);
2500 * Retrieve flags from a credential cache structure.
2502 * @param [in] context Library context
2503 * @param [in] cache Credential cache handle
2504 * @param [out] flags Flag bit mask
2506 * @warning For memory credential cache always returns a flag mask of 0.
2508 * @retval 0 Success; otherwise - Kerberos error codes
2510 krb5_error_code KRB5_CALLCONV
2511 krb5_cc_get_flags(krb5_context context, krb5_ccache cache, krb5_flags *flags);
2514 * Retrieve the type of a credential cache.
2516 * @param [in] context Library context
2517 * @param [in] cache Credential cache handle
2519 * @return The type of a credential cache as an alias that must not be modified
2520 * or freed by the caller.
2522 const char * KRB5_CALLCONV
2523 krb5_cc_get_type(krb5_context context, krb5_ccache cache);
2526 * Move a credential cache.
2528 * @param [in] context Library context
2529 * @param [in] src The credential cache to move the content from
2530 * @param [in] dst The credential cache to move the content to
2532 * This function reinitializes @a dst and populates it with the credentials and
2533 * default principal of @a src; then, if successful, destroys @a src.
2536 * 0 Success; @a src is closed.
2538 * Kerberos error codes; @a src is still allocated.
2540 krb5_error_code KRB5_CALLCONV
2541 krb5_cc_move(krb5_context context, krb5_ccache src, krb5_ccache dst);
2544 * Return a timestamp of the last modification to a credential cache.
2546 * @param [in] context Library context
2547 * @param [in] ccache Credential cache handle
2548 * @param [out] change_time The last change time of @a ccache
2550 * If an error occurs, @a change_time is set to 0.
2552 krb5_error_code KRB5_CALLCONV
2553 krb5_cc_last_change_time(krb5_context context, krb5_ccache ccache,
2554 krb5_timestamp *change_time);
2557 * Lock a credential cache.
2559 * @param [in] context Library context
2560 * @param [in] ccache Credential cache handle
2562 * Use krb5_cc_unlock() to unlock the lock.
2564 * @retval 0 Success; otherwise - Kerberos error codes
2566 krb5_error_code KRB5_CALLCONV
2567 krb5_cc_lock(krb5_context context, krb5_ccache ccache);
2570 * Unlock a credential cache.
2572 * @param [in] context Library context
2573 * @param [in] ccache Credential cache handle
2575 * This function unlocks the @a ccache locked by krb5_cc_lock().
2577 * @retval 0 Success; otherwise - Kerberos error codes
2579 krb5_error_code KRB5_CALLCONV
2580 krb5_cc_unlock(krb5_context context, krb5_ccache ccache);
2583 * Prepare to iterate over the collection of known credential caches.
2585 * @param [in] context Library context
2586 * @param [in,out] cursor Cursor
2588 * Get a new cache iteration @a cursor that will iterate over all known
2589 * credential caches independent of type.
2591 * Use krb5_cccol_cursor_free() to release @a cursor when it is no longer
2594 * @sa krb5_cccol_cursor_next()
2596 * @retval 0 Success; otherwise - Kerberos error codes
2598 krb5_error_code KRB5_CALLCONV
2599 krb5_cccol_cursor_new(krb5_context context, krb5_cccol_cursor *cursor);
2602 * Get the next credential cache in the collection.
2604 * @param [in] context Library context
2605 * @param [in,out] cursor Cursor
2606 * @param [out] ccache Credential cache handle
2608 * @note When all caches are iterated over and the end of the list is reached,
2609 * @a ccache is set to NULL.
2611 * Use krb5_cc_close() to close @a ccache when it is no longer needed.
2613 * @sa krb5_cccol_cursor_new(), krb5_cccol_cursor_free()
2615 * @retval 0 Success; otherwise - Kerberos error codes
2617 krb5_error_code KRB5_CALLCONV
2618 krb5_cccol_cursor_next(krb5_context context, krb5_cccol_cursor cursor,
2619 krb5_ccache *ccache);
2622 * Free a credential cache collection cursor.
2624 * @param [in] context Library context
2625 * @param [in] cursor Cursor
2627 * @sa krb5_cccol_cursor_new(), krb5_cccol_cursor_next()
2629 * @retval 0 Success; otherwise - Kerberos error codes
2631 krb5_error_code KRB5_CALLCONV
2632 krb5_cccol_cursor_free(krb5_context context, krb5_cccol_cursor *cursor);
2635 * Return a timestamp of the last modification of any known credential cache.
2637 * @param [in] context Library context
2638 * @param [out] change_time Last modification timestamp
2640 * This function returns the most recent modification time of any known
2641 * credential cache, ignoring any caches which cannot supply a last
2642 * modification time.
2644 * If there are no known credential caches, @a change_time is set to 0.
2646 * @retval 0 Success; otherwise - Kerberos error codes
2648 krb5_error_code KRB5_CALLCONV
2649 krb5_cccol_last_change_time(krb5_context context, krb5_timestamp *change_time);
2652 * Acquire a global lock for credential caches.
2654 * @param [in] context Library context
2656 * This function locks the global credential cache collection, ensuring
2657 * that no ccaches are added to or removed from it until the collection
2660 * Use krb5_cccol_unlock() to unlock the lock.
2662 * @retval 0 Success; otherwise - Kerberos error codes
2665 krb5_error_code KRB5_CALLCONV
2666 krb5_cccol_lock(krb5_context context);
2669 * Release a global lock for credential caches.
2671 * @param [in] context Library context
2673 * This function unlocks the lock from krb5_cccol_lock().
2675 * @retval 0 Success; otherwise - Kerberos error codes
2677 krb5_error_code KRB5_CALLCONV
2678 krb5_cccol_unlock(krb5_context context);
2681 * Create a new credential cache of the specified type with a unique name.
2683 * @param [in] context Library context
2684 * @param [in] type Credential cache type name
2685 * @param [in] hint Unused
2686 * @param [out] id Credential cache handle
2691 * Kerberos error codes
2693 krb5_error_code KRB5_CALLCONV
2694 krb5_cc_new_unique(krb5_context context, const char *type, const char *hint,
2706 typedef struct krb5_rc_st *krb5_rcache;
2718 #define MAX_KEYTAB_NAME_LEN 1100 /* Long enough for MAXPATHLEN + some extra */
2720 typedef krb5_pointer krb5_kt_cursor;
2722 /** A key table entry. */
2723 typedef struct krb5_keytab_entry_st {
2725 krb5_principal principal; /**< Principal of this key */
2726 krb5_timestamp timestamp; /**< Time entry written to keytable */
2727 krb5_kvno vno; /**< Key version number */
2728 krb5_keyblock key; /**< The secret key */
2729 } krb5_keytab_entry;
2732 typedef struct _krb5_kt *krb5_keytab;
2735 * Return the type of a key table.
2737 * @param [in] context Library context
2738 * @param [in] keytab Key table handle
2740 * @return The type of a key table as an alias that must not be modified or
2741 * freed by the caller.
2743 const char * KRB5_CALLCONV
2744 krb5_kt_get_type(krb5_context context, krb5_keytab keytab);
2747 * Get a key table name.
2749 * @param [in] context Library context
2750 * @param [in] keytab Key table handle
2751 * @param [out] name Key table name
2752 * @param [in] namelen Maximum length to fill in name
2754 * Fills in @a name with the name of @a keytab including the type and delimiter.
2756 * @sa MAX_KEYTAB_NAME_LEN
2761 * KRB5_KT_NAME_TOOLONG Key table name does not fit in @a namelen bytes
2764 * Kerberos error codes
2766 krb5_error_code KRB5_CALLCONV
2767 krb5_kt_get_name(krb5_context context, krb5_keytab keytab, char *name,
2768 unsigned int namelen);
2771 * Close a key table handle.
2773 * @param [in] context Library context
2774 * @param [in] keytab Key table handle
2778 krb5_error_code KRB5_CALLCONV
2779 krb5_kt_close(krb5_context context, krb5_keytab keytab);
2782 * Get an entry from a key table.
2784 * @param [in] context Library context
2785 * @param [in] keytab Key table handle
2786 * @param [in] principal Principal name
2787 * @param [in] vno Key version number (0 for highest available)
2788 * @param [in] enctype Encryption type (0 zero for any enctype)
2789 * @param [out] entry Returned entry from key table
2791 * Retrieve an entry from a key table which matches the @a keytab, @a
2792 * principal, @a vno, and @a enctype. If @a vno is zero, retrieve the
2793 * highest-numbered kvno matching the other fields. If @a enctype is 0, match
2796 * Use krb5_free_keytab_entry_contents() to free @a entry when it is no longer
2799 * @note If @a vno is zero, the function retrieves the highest-numbered-kvno
2800 * entry that matches the specified principal.
2805 * Kerberos error codes on failure
2807 krb5_error_code KRB5_CALLCONV
2808 krb5_kt_get_entry(krb5_context context, krb5_keytab keytab,
2809 krb5_const_principal principal, krb5_kvno vno,
2810 krb5_enctype enctype, krb5_keytab_entry *entry);
2813 * Start a sequential retrieval of key table entries.
2815 * @param [in] context Library context
2816 * @param [in] keytab Key table handle
2817 * @param [out] cursor Cursor
2819 * Prepare to read sequentially every key in the specified key table. Use
2820 * krb5_kt_end_seq_get() to release the cursor when it is no longer needed.
2822 * @sa krb5_kt_next_entry(), krb5_kt_end_seq_get()
2827 * Kerberos error codes
2829 krb5_error_code KRB5_CALLCONV
2830 krb5_kt_start_seq_get(krb5_context context, krb5_keytab keytab,
2831 krb5_kt_cursor *cursor);
2834 * Retrieve the next entry from the key table.
2836 * @param [in] context Library context
2837 * @param [in] keytab Key table handle
2838 * @param [out] entry Returned key table entry
2839 * @param [in,out] cursor Key table cursor
2841 * Return the next sequential entry in @a keytab and advance @a cursor.
2843 * @sa krb5_kt_start_seq_get(), krb5_kt_end_seq_get()
2848 * KRB5_KT_END - if the last entry was reached
2850 * Kerberos error codes
2852 krb5_error_code KRB5_CALLCONV
2853 krb5_kt_next_entry(krb5_context context, krb5_keytab keytab,
2854 krb5_keytab_entry *entry, krb5_kt_cursor *cursor);
2857 * Release a keytab cursor.
2859 * @param [in] context Library context
2860 * @param [in] keytab Key table handle
2861 * @param [out] cursor Cursor
2863 * This function should be called to release the cursor created by
2864 * krb5_kt_start_seq_get().
2869 * Kerberos error codes
2871 krb5_error_code KRB5_CALLCONV
2872 krb5_kt_end_seq_get(krb5_context context, krb5_keytab keytab,
2873 krb5_kt_cursor *cursor);
2880 * begin "func-proto.h"
2883 #define KRB5_INIT_CONTEXT_SECURE 0x1 /**< Use secure context configuration */
2884 #define KRB5_INIT_CONTEXT_KDC 0x2 /**< Use KDC configuration if available */
2887 * Create a krb5 library context.
2889 * @param [out] context Library context
2891 * The @a context must be released by calling krb5_free_context() when
2892 * it is no longer needed.
2894 * @warning Any program or module that needs the Kerberos code to not trust the
2895 * environment must use krb5_init_secure_context(), or clean out the
2901 * Kerberos error codes
2903 krb5_error_code KRB5_CALLCONV
2904 krb5_init_context(krb5_context *context);
2907 * Create a krb5 library context using only configuration files.
2909 * @param [out] context Library context
2911 * Create a context structure, using only system configuration files. All
2912 * information passed through the environment variables is ignored.
2914 * The @a context must be released by calling krb5_free_context() when
2915 * it is no longer needed.
2920 * Kerberos error codes
2922 krb5_error_code KRB5_CALLCONV
2923 krb5_init_secure_context(krb5_context *context);
2926 * Create a krb5 library context using a specified profile.
2928 * @param [in] profile Profile object (NULL to create default profile)
2929 * @param [in] flags Context initialization flags
2930 * @param [out] context Library context
2932 * Create a context structure, optionally using a specified profile and
2933 * initialization flags. If @a profile is NULL, the default profile will be
2934 * created from config files. If @a profile is non-null, a copy of it will be
2935 * made for the new context; the caller should still clean up its copy. Valid
2938 * @li #KRB5_INIT_CONTEXT_SECURE Ignore environment variables
2939 * @li #KRB5_INIT_CONTEXT_KDC Use KDC configuration if creating profile
2941 krb5_error_code KRB5_CALLCONV
2942 krb5_init_context_profile(struct _profile_t *profile, krb5_flags flags,
2943 krb5_context *context);
2946 * Free a krb5 library context.
2948 * @param [in] context Library context
2950 * This function frees a @a context that was created by krb5_init_context()
2951 * or krb5_init_secure_context().
2954 krb5_free_context(krb5_context context);
2957 * Copy a krb5_context structure.
2959 * @param [in] ctx Library context
2960 * @param [out] nctx_out New context structure
2962 * The newly created context must be released by calling krb5_free_context()
2963 * when it is no longer needed.
2968 * Kerberos error codes
2970 krb5_error_code KRB5_CALLCONV
2971 krb5_copy_context(krb5_context ctx, krb5_context *nctx_out);
2974 * Set default TGS encryption types in a krb5_context structure.
2976 * @param [in,out] context Library context
2977 * @param [in] etypes Encryption type(s) to set
2979 * This function sets the default enctype list for TGS requests
2980 * made using @a context to @a etypes.
2982 * @note This overrides the default list (from config file or built-in).
2987 * KRB5_PROG_ETYPE_NOSUPP Program lacks support for encryption type
2989 * Kerberos error codes
2991 krb5_error_code KRB5_CALLCONV
2992 krb5_set_default_tgs_enctypes(krb5_context context, const krb5_enctype *etypes);
2995 * Return a list of encryption types permitted for session keys.
2997 * @param [in] context Library context
2998 * @param [out] ktypes Zero-terminated list of encryption types
3000 * This function returns the list of encryption types permitted for session
3001 * keys within @a context, as determined by configuration or by a previous call
3002 * to krb5_set_default_tgs_enctypes().
3004 * @retval 0 Success; otherwise - Kerberos error codes
3006 krb5_error_code KRB5_CALLCONV
3007 krb5_get_permitted_enctypes(krb5_context context, krb5_enctype **ktypes);
3010 * Test whether the Kerberos library was built with multithread support.
3013 * TRUE if the library is threadsafe; FALSE otherwise
3015 krb5_boolean KRB5_CALLCONV
3016 krb5_is_thread_safe(void);
3021 * Decrypt a ticket using the specified key table.
3023 * @param [in] context Library context
3024 * @param [in] kt Key table
3025 * @param [in,out] ticket Ticket to be decrypted
3027 * This function takes a @a ticket as input and decrypts it using
3028 * key data from @a kt. The result is placed into @a ticket->enc_part2.
3030 * @retval 0 Success; otherwise - Kerberos error codes
3032 krb5_error_code KRB5_CALLCONV
3033 krb5_server_decrypt_ticket_keytab(krb5_context context, const krb5_keytab kt,
3034 krb5_ticket *ticket);
3037 * Free an array of credential structures.
3039 * @param [in] context Library context
3040 * @param [in] tgts Null-terminated array of credentials to free
3042 * @note The last entry in the array @a tgts must be a NULL pointer.
3045 krb5_free_tgt_creds(krb5_context context, krb5_creds **tgts);
3047 /** @defgroup KRB5_GC KRB5_GC
3050 #define KRB5_GC_USER_USER 1 /**< Want user-user ticket */
3051 #define KRB5_GC_CACHED 2 /**< Want cached ticket only */
3052 #define KRB5_GC_CANONICALIZE 4 /**< Set canonicalize KDC option */
3053 #define KRB5_GC_NO_STORE 8 /**< Do not store in credential cache */
3054 #define KRB5_GC_FORWARDABLE 16 /**< Acquire forwardable tickets */
3055 #define KRB5_GC_NO_TRANSIT_CHECK 32 /**< Disable transited check */
3056 #define KRB5_GC_CONSTRAINED_DELEGATION 64 /**< Constrained delegation */
3057 /** @} */ /* end of KRB5_GC group */
3060 * Get an additional ticket.
3062 * @param [in] context Library context
3063 * @param [in] options Options
3064 * @param [in,out] ccache Credential cache handle
3065 * @param [in] in_creds Input credentials
3066 * @param [out] out_creds Output updated credentials
3068 * Use @a ccache or a TGS exchange to get a service ticket matching @a
3071 * Valid values for @a options are:
3072 * @li #KRB5_GC_CACHED Search only credential cache for the ticket
3073 * @li #KRB5_GC_USER_USER Return a user to user authentication ticket
3075 * @a in_creds must be non-null. @a in_creds->client and @a in_creds->server
3076 * must be filled in to specify the client and the server respectively. If any
3077 * authorization data needs to be requested for the service ticket (such as
3078 * restrictions on how the ticket can be used), specify it in @a
3079 * in_creds->authdata; otherwise set @a in_creds->authdata to NULL. The
3080 * session key type is specified in @a in_creds->keyblock.enctype, if it is
3083 * The expiration date is specified in @a in_creds->times.endtime.
3084 * The KDC may return tickets with an earlier expiration date.
3085 * If @a in_creds->times.endtime is set to 0, the latest possible
3086 * expiration date will be requested.
3088 * Any returned ticket and intermediate ticket-granting tickets are stored
3091 * Use krb5_free_creds() to free @a out_creds when it is no longer needed.
3096 * Kerberos error codes
3098 krb5_error_code KRB5_CALLCONV
3099 krb5_get_credentials(krb5_context context, krb5_flags options,
3100 krb5_ccache ccache, krb5_creds *in_creds,
3101 krb5_creds **out_creds);
3103 /** @deprecated Replaced by krb5_get_validated_creds. */
3104 krb5_error_code KRB5_CALLCONV
3105 krb5_get_credentials_validate(krb5_context context, krb5_flags options,
3106 krb5_ccache ccache, krb5_creds *in_creds,
3107 krb5_creds **out_creds);
3109 /** @deprecated Replaced by krb5_get_renewed_creds. */
3110 krb5_error_code KRB5_CALLCONV
3111 krb5_get_credentials_renew(krb5_context context, krb5_flags options,
3112 krb5_ccache ccache, krb5_creds *in_creds,
3113 krb5_creds **out_creds);
3116 * Create a @c KRB_AP_REQ message.
3118 * @param [in] context Library context
3119 * @param [in,out] auth_context Pre-existing or newly created auth context
3120 * @param [in] ap_req_options @ref AP_OPTS options
3121 * @param [in] service Service name, or NULL to use @c "host"
3122 * @param [in] hostname Host name, or NULL to use local hostname
3123 * @param [in] in_data Application data to be checksummed in the
3124 * authenticator, or NULL
3125 * @param [in] ccache Credential cache used to obtain credentials
3126 * for the desired service.
3127 * @param [out] outbuf @c AP-REQ message
3129 * This function is similar to krb5_mk_req_extended() except that it uses a
3130 * given @a hostname, @a service, and @a ccache to construct a service
3131 * principal name and obtain credentials.
3133 * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
3135 * @retval 0 Success; otherwise - Kerberos error codes
3137 krb5_error_code KRB5_CALLCONV
3138 krb5_mk_req(krb5_context context, krb5_auth_context *auth_context,
3139 krb5_flags ap_req_options, char *service, char *hostname,
3140 krb5_data *in_data, krb5_ccache ccache, krb5_data *outbuf);
3143 * Create a @c KRB_AP_REQ message using supplied credentials.
3145 * @param [in] context Library context
3146 * @param [in,out] auth_context Pre-existing or newly created auth context
3147 * @param [in] ap_req_options @ref AP_OPTS options
3148 * @param [in] in_data Application data to be checksummed in the
3149 * authenticator, or NULL
3150 * @param [in] in_creds Credentials for the service with valid ticket
3152 * @param [out] outbuf @c AP-REQ message
3154 * Valid @a ap_req_options are:
3155 * @li #AP_OPTS_USE_SESSION_KEY - Use the session key when creating the
3156 * request used for user to user
3158 * @li #AP_OPTS_MUTUAL_REQUIRED - Request a mutual authentication packet from
3160 * @li #AP_OPTS_USE_SUBKEY - Generate a subsession key from the current
3161 * session key obtained from the credentials.
3163 * This function creates a KRB_AP_REQ message using supplied credentials @a
3164 * in_creds. @a auth_context may point to an existing auth context or to NULL,
3165 * in which case a new one will be created. If @a in_data is non-null, a
3166 * checksum of it will be included in the authenticator contained in the
3167 * KRB_AP_REQ message. Use krb5_free_data_contents() to free @a outbuf when it
3168 * is no longer needed.
3170 * On successful return, the authenticator is stored in @a auth_context with
3171 * the @a client and @a checksum fields nulled out. (This is to prevent
3172 * pointer-sharing problems; the caller should not need these fields anyway,
3173 * since the caller supplied them.)
3177 * @retval 0 Success; otherwise - Kerberos error codes
3179 krb5_error_code KRB5_CALLCONV
3180 krb5_mk_req_extended(krb5_context context, krb5_auth_context *auth_context,
3181 krb5_flags ap_req_options, krb5_data *in_data,
3182 krb5_creds *in_creds, krb5_data *outbuf);
3185 * Format and encrypt a @c KRB_AP_REP message.
3187 * @param [in] context Library context
3188 * @param [in,out] auth_context Authentication context
3189 * @param [out] outbuf @c AP-REP message
3191 * This function fills in @a outbuf with an AP-REP message using information
3192 * from @a auth_context.
3194 * If the flags in @a auth_context indicate that a sequence number should be
3195 * used (either #KRB5_AUTH_CONTEXT_DO_SEQUENCE or
3196 * #KRB5_AUTH_CONTEXT_RET_SEQUENCE) and the local sequence number in @a
3197 * auth_context is 0, a new number will be generated with
3198 * krb5_generate_seq_number().
3200 * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
3202 * @retval 0 Success; otherwise - Kerberos error codes
3204 krb5_error_code KRB5_CALLCONV
3205 krb5_mk_rep(krb5_context context, krb5_auth_context auth_context, krb5_data *outbuf);
3208 * Format and encrypt a @c KRB_AP_REP message for DCE RPC.
3210 * @param [in] context Library context
3211 * @param [in,out] auth_context Authentication context
3212 * @param [out] outbuf @c AP-REP message
3214 * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
3216 * @retval 0 Success; otherwise - Kerberos error codes
3218 krb5_error_code KRB5_CALLCONV
3219 krb5_mk_rep_dce(krb5_context context, krb5_auth_context auth_context, krb5_data *outbuf);
3222 * Parse and decrypt a @c KRB_AP_REP message.
3224 * @param [in] context Library context
3225 * @param [in,out] auth_context Authentication context
3226 * @param [in] inbuf AP-REP message
3227 * @param [out] repl Decrypted reply message
3229 * This function parses, decrypts and verifies a message from @a inbuf and
3230 * fills in @a repl with a pointer to allocated memory containing the fields
3231 * from the encrypted response.
3233 * Use krb5_free_ap_rep_enc_part() to free @a repl when it is no longer needed.
3235 * @retval 0 Success; otherwise - Kerberos error codes
3237 krb5_error_code KRB5_CALLCONV
3238 krb5_rd_rep(krb5_context context, krb5_auth_context auth_context,
3239 const krb5_data *inbuf, krb5_ap_rep_enc_part **repl);
3242 * Parse and decrypt a @c KRB_AP_REP message for DCE RPC.
3244 * @param [in] context Library context
3245 * @param [in,out] auth_context Authentication context
3246 * @param [in] inbuf AP-REP message
3247 * @param [out] nonce Sequence number from the decrypted reply
3249 * This function parses, decrypts and verifies a message from @a inbuf and
3250 * fills in @a nonce with a decrypted reply sequence number.
3252 * @retval 0 Success; otherwise - Kerberos error codes
3254 krb5_error_code KRB5_CALLCONV
3255 krb5_rd_rep_dce(krb5_context context, krb5_auth_context auth_context,
3256 const krb5_data *inbuf, krb5_ui_4 *nonce);
3259 * Format and encode a @c KRB_ERROR message.
3261 * @param [in] context Library context
3262 * @param [in] dec_err Error structure to be encoded
3263 * @param [out] enc_err Encoded error structure
3265 * This function creates a @c KRB_ERROR message in @a enc_err. Use
3266 * krb5_free_data_contents() to free @a enc_err when it is no longer needed.
3268 * @retval 0 Success; otherwise - Kerberos error codes
3270 krb5_error_code KRB5_CALLCONV
3271 krb5_mk_error(krb5_context context, const krb5_error *dec_err,
3272 krb5_data *enc_err);
3275 * Decode a @c KRB-ERROR message.
3277 * @param [in] context Library context
3278 * @param [in] enc_errbuf Encoded error message
3279 * @param [out] dec_error Decoded error message
3281 * This function processes @c KRB-ERROR message @a enc_errbuf and returns
3282 * an allocated structure @a dec_error containing the error message.
3283 * Use krb5_free_error() to free @a dec_error when it is no longer needed.
3285 * @retval 0 Success; otherwise - Kerberos error codes
3287 krb5_error_code KRB5_CALLCONV
3288 krb5_rd_error(krb5_context context, const krb5_data *enc_errbuf,
3289 krb5_error **dec_error);
3292 * Process @c KRB-SAFE message.
3294 * @param [in] context Library context
3295 * @param [in,out] auth_context Authentication structure
3296 * @param [in] inbuf @c KRB-SAFE message to be parsed
3297 * @param [out] outbuf Data parsed from @c KRB-SAFE message
3298 * @param [out] outdata Replay data. Specify NULL if not needed
3300 * This function parses a @c KRB-SAFE message, verifies its integrity, and
3301 * stores its data into @a outbuf.
3303 * @note The @a outdata argument is required if #KRB5_AUTH_CONTEXT_RET_TIME or
3304 * #KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in the @a auth_context.
3306 * @note @a auth_context must have a remote address set. This address will be
3307 * used to verify the sender address in the KRB-SAFE message. If @a
3308 * auth_context has a local address set, it will be used to verify the
3309 * receiver address in the KRB-SAFE message if the message contains one.
3310 * Both addresses must use type @c ADDRTYPE_ADDRPORT.
3312 * If the #KRB5_AUTH_CONTEXT_DO_SEQUENCE flag is set in @a auth_context, the
3313 * sequence number of the KRB-SAFE message is checked against the remote
3314 * sequence number field of @a auth_context. Otherwise, the sequence number is
3317 * If the #KRB5_AUTH_CONTEXT_DO_TIME flag is set in @a auth_context,
3318 * then two additional checks are performed:
3319 * @li The timestamp in the message must be within the permitted clock skew
3320 * (which is usually five minutes).
3321 * @li The message must not be a replayed message field in @a auth_context.
3323 * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
3325 * @retval 0 Success; otherwise - Kerberos error codes
3327 krb5_error_code KRB5_CALLCONV
3328 krb5_rd_safe(krb5_context context, krb5_auth_context auth_context,
3329 const krb5_data *inbuf, krb5_data *outbuf,
3330 krb5_replay_data *outdata);
3333 * Process a @c KRB-PRIV message.
3335 * @param [in] context Library context
3336 * @param [in,out] auth_context Authentication structure
3337 * @param [in] inbuf @c KRB-PRIV message to be parsed
3338 * @param [out] outbuf Data parsed from @c KRB-PRIV message
3339 * @param [out] outdata Replay data. Specify NULL if not needed
3341 * This function parses a @c KRB-PRIV message, verifies its integrity, and
3342 * stores its unencrypted data into @a outbuf.
3344 * @note If the #KRB5_AUTH_CONTEXT_RET_TIME or @c
3345 * #KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in @a auth_context, @a
3346 * outdata is required.
3348 * @note @a auth_context must have a remote address set. This address will be
3349 * used to verify the sender address in the KRB-PRIV message. If @a
3350 * auth_context has a local address set, it will be used to verify the
3351 * receiver address in the KRB-PRIV message if the message contains one.
3352 * Both addresses must use type @c ADDRTYPE_ADDRPORT.
3354 * If the #KRB5_AUTH_CONTEXT_DO_SEQUENCE flag is set in @a auth_context, the
3355 * sequence number of the KRB-SAFE message is checked against the remote
3356 * sequence number field of @a auth_context. Otherwise, the sequence number is
3359 * If the #KRB5_AUTH_CONTEXT_DO_TIME flag is set in @a auth_context,
3360 * then two additional checks are performed:
3361 * @li The timestamp in the message must be within the permitted clock skew
3362 * (which is usually five minutes).
3363 * @li The message must not be a replayed message field in @a auth_context.
3365 * @retval 0 Success; otherwise - Kerberos error codes
3367 krb5_error_code KRB5_CALLCONV
3368 krb5_rd_priv(krb5_context context, krb5_auth_context auth_context,
3369 const krb5_data *inbuf, krb5_data *outbuf,
3370 krb5_replay_data *outdata);
3373 * Convert a string principal name to a krb5_principal structure.
3375 * @param [in] context Library context
3376 * @param [in] name String representation of a principal name
3377 * @param [out] nprincipal Principal
3379 * Convert a string representation of a principal name to a krb5_principal
3382 * A string representation of a Kerberos name consists of one or more principal
3383 * name components, separated by slashes, optionally followed by the \@
3384 * character and a realm name. If the realm name is not specified, the local
3387 * To use the slash and \@ symbols as part of a component (quoted) instead of
3388 * using them as a component separator or as a realm prefix), put a backslash
3389 * (\) character in front of the symbol. Similarly, newline, tab, backspace,
3390 * and NULL characters can be included in a component by using @c n, @c t, @c b
3391 * or @c 0, respectively.
3393 * @note The realm in a Kerberos @a name cannot contain slash, colon,
3394 * or NULL characters.
3396 * Use krb5_free_principal() to free @a nprincipal when it is no longer needed.
3401 * Kerberos error codes
3403 krb5_error_code KRB5_CALLCONV
3404 krb5_parse_name(krb5_context context, const char *name, krb5_principal *nprincipal);
3406 #define KRB5_PRINCIPAL_PARSE_NO_REALM 0x1 /**< Error if realm is present */
3407 #define KRB5_PRINCIPAL_PARSE_REQUIRE_REALM 0x2 /**< Error if realm is not present */
3408 #define KRB5_PRINCIPAL_PARSE_ENTERPRISE 0x4 /**< Create single-component
3409 enterprise principle */
3412 * Convert a string principal name to a krb5_principal with flags
3414 * @param [in] context Library context
3415 * @param [in] name String representation of a principal name
3416 * @param [in] flags Flag
3417 * @param [out] nprincipal Principal
3419 * Similar to krb5_parse_name(), this function converts a single-string
3420 * representation of a principal name to a krb5_principal structure.
3422 * The following flags are valid:
3423 * @li #KRB5_PRINCIPAL_PARSE_NO_REALM - no realm must be present in @a name
3424 * @li #KRB5_PRINCIPAL_PARSE_REQUIRE_REALM - realm must be present in @a name
3425 * @li #KRB5_PRINCIPAL_PARSE_ENTERPRISE - create single-component enterprise
3428 * Use krb5_free_principal() to free @a nprincipal when it is no longer needed.
3433 * Kerberos error codes
3435 krb5_error_code KRB5_CALLCONV
3436 krb5_parse_name_flags(krb5_context context, const char *name,
3437 int flags, krb5_principal *nprincipal);
3440 * Convert a krb5_principal structure to a string representation.
3442 * @param [in] context Library context
3443 * @param [in] principal Principal
3444 * @param [out] name String representation of principal name
3446 * The resulting string representation uses the format and quoting conventions
3447 * described for krb5_parse_name().
3449 * Use krb5_free_unparsed_name() to free @a name when it is no longer needed.
3454 * Kerberos error codes
3456 krb5_error_code KRB5_CALLCONV
3457 krb5_unparse_name(krb5_context context, krb5_const_principal principal,
3458 register char **name);
3461 * Convert krb5_principal structure to string and length.
3463 * @param [in] context Library context
3464 * @param [in] principal Principal
3465 * @param [out] name String representation of principal name
3466 * @param [out] size Size of unparsed name
3468 * This function is similar to krb5_unparse_name(), but also returns the length
3469 * of the string representation.
3474 * Kerberos error codes. On failure @a name is set to NULL
3476 krb5_error_code KRB5_CALLCONV
3477 krb5_unparse_name_ext(krb5_context context, krb5_const_principal principal,
3478 char **name, unsigned int *size);
3480 #define KRB5_PRINCIPAL_UNPARSE_SHORT 0x1 /**< Omit realm if it is the local realm */
3481 #define KRB5_PRINCIPAL_UNPARSE_NO_REALM 0x2 /**< Omit realm always */
3482 #define KRB5_PRINCIPAL_UNPARSE_DISPLAY 0x4 /**< Don't escape special characters */
3485 * Convert krb5_principal structure to a string with flags.
3487 * @param [in] context Library context
3488 * @param [in] principal Principal
3489 * @param [in] flags Flags
3490 * @param [out] name String representation of principal name
3492 * Similar to krb5_unparse_name(), this function converts a krb5_principal
3493 * structure to a string representation.
3495 * The following flags are valid:
3496 * @li #KRB5_PRINCIPAL_UNPARSE_SHORT - omit realm if it is the local realm
3497 * @li #KRB5_PRINCIPAL_UNPARSE_NO_REALM - omit realm
3498 * @li #KRB5_PRINCIPAL_UNPARSE_DISPLAY - do not quote special characters
3500 * Use krb5_free_unparsed_name() to free @a name when it is no longer needed.
3505 * Kerberos error codes. On failure @a name is set to NULL
3507 krb5_error_code KRB5_CALLCONV
3508 krb5_unparse_name_flags(krb5_context context, krb5_const_principal principal,
3509 int flags, char **name);
3512 * Convert krb5_principal structure to string format with flags.
3514 * @param [in] context Library context
3515 * @param [in] principal Principal
3516 * @param [in] flags Flags
3517 * @param [out] name Single string format of principal name
3518 * @param [out] size Size of unparsed name buffer
3520 * @sa krb5_unparse_name() krb5_unparse_name_flags() krb5_unparse_name_ext()
3525 * Kerberos error codes. On failure @a name is set to NULL
3527 krb5_error_code KRB5_CALLCONV
3528 krb5_unparse_name_flags_ext(krb5_context context, krb5_const_principal principal,
3529 int flags, char **name, unsigned int *size);
3532 * Set the realm field of a principal
3534 * @param [in,out] context Library context
3535 * @param [in] principal Principal name
3536 * @param [in] realm Realm name
3538 * Set the realm name part of @a principal to @a realm, overwriting the
3544 * Kerberos error codes
3546 krb5_error_code KRB5_CALLCONV
3547 krb5_set_principal_realm(krb5_context context, krb5_principal principal,
3551 * Search a list of addresses for a specified address.
3553 * @param [in] context Library context
3554 * @param [in] addr Address to search for
3555 * @param [in] addrlist Address list to be searched (or NULL)
3557 * @note If @a addrlist contains only a NetBIOS addresses, it will be treated
3561 * TRUE if @a addr is listed in @a addrlist, or @c addrlist is NULL; FALSE
3564 krb5_boolean KRB5_CALLCONV_WRONG
3565 krb5_address_search(krb5_context context, const krb5_address *addr,
3566 krb5_address *const *addrlist);
3569 * Compare two Kerberos addresses.
3571 * @param [in] context Library context
3572 * @param [in] addr1 First address to be compared
3573 * @param [in] addr2 Second address to be compared
3576 * TRUE if the addresses are the same, FALSE otherwise
3578 krb5_boolean KRB5_CALLCONV
3579 krb5_address_compare(krb5_context context, const krb5_address *addr1,
3580 const krb5_address *addr2);
3583 * Return an ordering of the specified addresses.
3585 * @param [in] context Library context
3586 * @param [in] addr1 First address
3587 * @param [in] addr2 Second address
3590 * 0 The two addresses are the same
3592 * \< 0 First address is less than second
3594 * \> 0 First address is greater than second
3597 krb5_address_order(krb5_context context, const krb5_address *addr1,
3598 const krb5_address *addr2);
3601 * Compare the realms of two principals.
3603 * @param [in] context Library context
3604 * @param [in] princ1 First principal
3605 * @param [in] princ2 Second principal
3608 * TRUE if the realm names are the same; FALSE otherwise
3610 krb5_boolean KRB5_CALLCONV
3611 krb5_realm_compare(krb5_context context, krb5_const_principal princ1,
3612 krb5_const_principal princ2);
3615 * Compare two principals.
3617 * @param [in] context Library context
3618 * @param [in] princ1 First principal
3619 * @param [in] princ2 Second principal
3622 * TRUE if the principals are the same; FALSE otherwise
3624 krb5_boolean KRB5_CALLCONV
3625 krb5_principal_compare(krb5_context context,
3626 krb5_const_principal princ1,
3627 krb5_const_principal princ2);
3630 * Compare two principals ignoring realm components.
3632 * @param [in] context Library context
3633 * @param [in] princ1 First principal
3634 * @param [in] princ2 Second principal
3636 * Similar to krb5_principal_compare(), but do not compare the realm
3637 * components of the principals.
3640 * TRUE if the principals are the same; FALSE otherwise
3642 krb5_boolean KRB5_CALLCONV
3643 krb5_principal_compare_any_realm(krb5_context context,
3644 krb5_const_principal princ1,
3645 krb5_const_principal princ2);
3647 #define KRB5_PRINCIPAL_COMPARE_IGNORE_REALM 1 /**< ignore realm component */
3648 #define KRB5_PRINCIPAL_COMPARE_ENTERPRISE 2 /**< UPNs as real principals */
3649 #define KRB5_PRINCIPAL_COMPARE_CASEFOLD 4 /**< case-insensitive */
3650 #define KRB5_PRINCIPAL_COMPARE_UTF8 8 /**< treat principals as UTF-8 */
3653 * Compare two principals with additional flags.
3655 * @param [in] context Library context
3656 * @param [in] princ1 First principal
3657 * @param [in] princ2 Second principal
3658 * @param [in] flags Flags
3661 * @li #KRB5_PRINCIPAL_COMPARE_IGNORE_REALM - ignore realm component
3662 * @li #KRB5_PRINCIPAL_COMPARE_ENTERPRISE - UPNs as real principals
3663 * @li #KRB5_PRINCIPAL_COMPARE_CASEFOLD case-insensitive
3664 * @li #KRB5_PRINCIPAL_COMPARE_UTF8 - treat principals as UTF-8
3666 * @sa krb5_principal_compare()
3669 * TRUE if the principal names are the same; FALSE otherwise
3671 krb5_boolean KRB5_CALLCONV
3672 krb5_principal_compare_flags(krb5_context context,
3673 krb5_const_principal princ1,
3674 krb5_const_principal princ2,
3678 * Initialize an empty @c krb5_keyblock.
3680 * @param [in] context Library context
3681 * @param [in] enctype Encryption type
3682 * @param [in] length Length of keyblock (or 0)
3683 * @param [out] out New keyblock structure
3685 * Initialize a new keyblock and allocate storage for the contents of the key.
3686 * It is legal to pass in a length of 0, in which case contents are left
3687 * unallocated. Use krb5_free_keyblock() to free @a out when it is no longer
3690 * @note If @a length is set to 0, contents are left unallocated.
3692 * @retval 0 Success; otherwise - Kerberos error codes
3694 krb5_error_code KRB5_CALLCONV
3695 krb5_init_keyblock(krb5_context context, krb5_enctype enctype,
3696 size_t length, krb5_keyblock **out);
3701 * @param [in] context Library context
3702 * @param [in] from Keyblock to be copied
3703 * @param [out] to Copy of keyblock @a from
3705 * This function creates a new keyblock with the same contents as @a from. Use
3706 * krb5_free_keyblock() to free @a to when it is no longer needed.
3708 * @retval 0 Success; otherwise - Kerberos error codes
3710 krb5_error_code KRB5_CALLCONV
3711 krb5_copy_keyblock(krb5_context context, const krb5_keyblock *from,
3712 krb5_keyblock **to);
3715 * Copy the contents of a keyblock.
3717 * @param [in] context Library context
3718 * @param [in] from Key to be copied
3719 * @param [out] to Output key
3721 * This function copies the contents of @a from to @a to. Use
3722 * krb5_free_keyblock_contents() to free @a to when it is no longer needed.
3724 * @retval 0 Success; otherwise - Kerberos error codes
3726 krb5_error_code KRB5_CALLCONV
3727 krb5_copy_keyblock_contents(krb5_context context, const krb5_keyblock *from,
3731 * Copy a krb5_creds structure.
3733 * @param [in] context Library context
3734 * @param [in] incred Credentials structure to be copied
3735 * @param [out] outcred Copy of @a incred
3737 * This function creates a new credential with the contents of @a incred. Use
3738 * krb5_free_creds() to free @a outcred when it is no longer needed.
3740 * @retval 0 Success; otherwise - Kerberos error codes
3742 krb5_error_code KRB5_CALLCONV
3743 krb5_copy_creds(krb5_context context, const krb5_creds *incred, krb5_creds **outcred);
3746 * Copy a krb5_data object.
3748 * @param [in] context Library context
3749 * @param [in] indata Data object to be copied
3750 * @param [out] outdata Copy of @a indata
3752 * This function creates a new krb5_data object with the contents of @a indata.
3753 * Use krb5_free_data() to free @a outdata when it is no longer needed.
3755 * @retval 0 Success; otherwise - Kerberos error codes
3757 krb5_error_code KRB5_CALLCONV
3758 krb5_copy_data(krb5_context context, const krb5_data *indata, krb5_data **outdata);
3763 * @param [in] context Library context
3764 * @param [in] inprinc Principal to be copied
3765 * @param [out] outprinc Copy of @a inprinc
3767 * This function creates a new principal structure with the contents of @a
3768 * inprinc. Use krb5_free_principal() to free @a outprinc when it is no longer
3771 * @retval 0 Success; otherwise - Kerberos error codes
3773 krb5_error_code KRB5_CALLCONV
3774 krb5_copy_principal(krb5_context context, krb5_const_principal inprinc,
3775 krb5_principal *outprinc);
3778 * Copy an array of addresses.
3780 * @param [in] context Library context
3781 * @param [in] inaddr Array of addresses to be copied
3782 * @param [out] outaddr Copy of array of addresses
3784 * This function creates a new address array containing a copy of @a inaddr.
3785 * Use krb5_free_addresses() to free @a outaddr when it is no longer needed.
3787 * @retval 0 Success; otherwise - Kerberos error codes
3789 krb5_error_code KRB5_CALLCONV
3790 krb5_copy_addresses(krb5_context context, krb5_address *const *inaddr,
3791 krb5_address ***outaddr);
3794 * Copy a krb5_ticket structure.
3796 * @param [in] context Library context
3797 * @param [in] from Ticket to be copied
3798 * @param [out] pto Copy of ticket
3800 * This function creates a new krb5_ticket structure containing the contents of
3801 * @a from. Use krb5_free_ticket() to free @a pto when it is no longer needed.
3803 * @retval 0 Success; otherwise - Kerberos error codes
3805 krb5_error_code KRB5_CALLCONV
3806 krb5_copy_ticket(krb5_context context, const krb5_ticket *from, krb5_ticket **pto);
3809 * Copy an authorization data list.
3811 * @param [in] context Library context
3812 * @param [in] in_authdat List of @a krb5_authdata structures
3813 * @param [out] out New array of @a krb5_authdata structures
3815 * This function creates a new authorization data list containing a copy of @a
3816 * in_authdat, which must be null-terminated. Use krb5_free_authdata() to free
3817 * @a out when it is no longer needed.
3819 * @note The last array entry in @a in_authdat must be a NULL pointer.
3821 * @retval 0 Success; otherwise - Kerberos error codes
3823 krb5_error_code KRB5_CALLCONV
3824 krb5_copy_authdata(krb5_context context,
3825 krb5_authdata *const *in_authdat, krb5_authdata ***out);
3828 * Find authorization data elements.
3830 * @param [in] context Library context
3831 * @param [in] ticket_authdata Authorization data list from ticket
3832 * @param [in] ap_req_authdata Authorization data list from AP request
3833 * @param [in] ad_type Authorization data type to find
3834 * @param [out] results List of matching entries
3836 * This function searches @a ticket_authdata and @a ap_req_authdata for
3837 * elements of type @a ad_type. Either input list may be NULL, in which case
3838 * it will not be searched; otherwise, the input lists must be terminated by
3839 * NULL entries. This function will search inside AD-IF-RELEVANT containers if
3840 * found in either list. Use krb5_free_authdata() to free @a results when it
3841 * is no longer needed.
3843 * @version First introduced in 1.10
3845 krb5_error_code KRB5_CALLCONV
3846 krb5_find_authdata(krb5_context context, krb5_authdata *const *ticket_authdata,
3847 krb5_authdata *const *ap_req_authdata,
3848 krb5_authdatatype ad_type, krb5_authdata ***results);
3851 * Merge two authorization data lists into a new list.
3853 * @param [in] context Library context
3854 * @param [in] inauthdat1 First list of @a krb5_authdata structures
3855 * @param [in] inauthdat2 Second list of @a krb5_authdata structures
3856 * @param [out] outauthdat Merged list of @a krb5_authdata structures
3858 * Merge two authdata arrays, such as the array from a ticket
3859 * and authenticator.
3860 * Use krb5_free_authdata() to free @a outauthdat when it is no longer needed.
3862 * @note The last array entry in @a inauthdat1 and @a inauthdat2
3863 * must be a NULL pointer.
3865 * @retval 0 Success; otherwise - Kerberos error codes
3867 krb5_error_code KRB5_CALLCONV
3868 krb5_merge_authdata(krb5_context context,
3869 krb5_authdata *const *inauthdat1,
3870 krb5_authdata * const *inauthdat2,
3871 krb5_authdata ***outauthdat);
3874 * Copy a krb5_authenticator structure.
3876 * @param [in] context Library context
3877 * @param [in] authfrom krb5_authenticator structure to be copied
3878 * @param [out] authto Copy of krb5_authenticator structure
3880 * This function creates a new krb5_authenticator structure with the content of
3881 * @a authfrom. Use krb5_free_authenticator() to free @a authto when it is no
3884 * @retval 0 Success; otherwise - Kerberos error codes
3886 krb5_error_code KRB5_CALLCONV
3887 krb5_copy_authenticator(krb5_context context, const krb5_authenticator *authfrom,
3888 krb5_authenticator **authto);
3891 * Copy a krb5_checksum structure.
3893 * @param [in] context Library context
3894 * @param [in] ckfrom Checksum to be copied
3895 * @param [out] ckto Copy of krb5_checksum structure
3897 * This function creates a new krb5_checksum structure with the contents of @a
3898 * ckfrom. Use krb5_free_checksum() to free @a ckto when it is no longer
3901 * @retval 0 Success; otherwise - Kerberos error codes
3903 krb5_error_code KRB5_CALLCONV
3904 krb5_copy_checksum(krb5_context context, const krb5_checksum *ckfrom,
3905 krb5_checksum **ckto);
3908 * Generate a replay cache object for server use and open it.
3910 * @param [in] context Library context
3911 * @param [in] piece Unique identifier for replay cache
3912 * @param [out] rcptr Handle to an open rcache
3914 * This function generates a replay cache name based on @a piece and opens a
3915 * handle to it. Typically @a piece is the first component of the service
3916 * principal name. Use krb5_rc_close() to close @a rcptr when it is no longer
3919 * @retval 0 Success; otherwise - Kerberos error codes
3921 krb5_error_code KRB5_CALLCONV
3922 krb5_get_server_rcache(krb5_context context, const krb5_data *piece,
3923 krb5_rcache *rcptr);
3926 * Build a principal name using length-counted strings.
3928 * @param [in] context Library context
3929 * @param [out] princ Principal name
3930 * @param [in] rlen Realm name length
3931 * @param [in] realm Realm name
3932 * @param [in] ... List of unsigned int/char * components, followed by 0
3934 * This function creates a principal from a length-counted string and a
3935 * variable-length list of length-counted components. The list of components
3936 * ends with the first 0 length argument (so it is not possible to specify an
3937 * empty component with this function). Call krb5_free_principal() to free
3938 * allocated memory for principal when it is no longer needed.
3941 * Example of how to build principal WELLKNOWN/ANONYMOUS@R
3942 * krb5_build_principal_ext(context, &principal, strlen("R"), "R",
3943 * (unsigned int)strlen(KRB5_WELLKNOWN_NAMESTR),
3944 * KRB5_WELLKNOWN_NAMESTR,
3945 * (unsigned int)strlen(KRB5_ANONYMOUS_PRINCSTR),
3946 * KRB5_ANONYMOUS_PRINCSTR, 0);
3952 * Kerberos error codes
3954 krb5_error_code KRB5_CALLCONV_C
3955 krb5_build_principal_ext(krb5_context context, krb5_principal * princ,
3956 unsigned int rlen, const char * realm, ...);
3959 * Build a principal name using null-terminated strings.
3961 * @param [in] context Library context
3962 * @param [out] princ Principal name
3963 * @param [in] rlen Realm name length
3964 * @param [in] realm Realm name
3965 * @param [in] ... List of char * components, ending with NULL
3967 * Call krb5_free_principal() to free @a princ when it is no longer needed.
3969 * @note krb5_build_principal() and krb5_build_principal_alloc_va() perform the
3970 * same task. krb5_build_principal() takes variadic arguments.
3971 * krb5_build_principal_alloc_va() takes a pre-computed @a varargs pointer.
3974 * Example of how to build principal H/S@R
3975 * krb5_build_principal(context, &principal,
3976 * strlen("R"), "R", "H", "S", (char*)NULL);
3982 * Kerberos error codes
3984 krb5_error_code KRB5_CALLCONV_C
3985 krb5_build_principal(krb5_context context,
3986 krb5_principal * princ,
3988 const char * realm, ...)
3990 __attribute__ ((sentinel))
3994 /** @deprecated Replaced by krb5_build_principal_alloc_va(). */
3995 KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
3996 krb5_build_principal_va(krb5_context context,
3997 krb5_principal princ,
4004 * Build a principal name, using a precomputed variable argument list
4006 * @param [in] context Library context
4007 * @param [out] princ Principal structure
4008 * @param [in] rlen Realm name length
4009 * @param [in] realm Realm name
4010 * @param [in] ap List of char * components, ending with NULL
4012 * Similar to krb5_build_principal(), this function builds a principal name,
4013 * but its name components are specified as a va_list.
4015 * Use krb5_free_principal() to deallocate @a princ when it is no longer
4019 * Function usage example:
4021 * va_start(ap, realm);
4022 * krb5_build_principal_alloc_va(context, princ, rlen, realm, ap);
4029 * Kerberos error codes
4031 krb5_error_code KRB5_CALLCONV
4032 krb5_build_principal_alloc_va(krb5_context context,
4033 krb5_principal *princ,
4039 * Convert a Kerberos V4 principal to a Kerberos V5 principal.
4041 * @param [in] context Library context
4042 * @param [in] name V4 name
4043 * @param [in] instance V4 instance
4044 * @param [in] realm Realm
4045 * @param [out] princ V5 principal
4047 * This function builds a @a princ from V4 specification based on given input
4048 * @a name.instance\@realm.
4050 * Use krb5_free_principal() to free @a princ when it is no longer needed.
4052 * @retval 0 Success; otherwise - Kerberos error codes
4054 krb5_error_code KRB5_CALLCONV
4055 krb5_425_conv_principal(krb5_context context, const char *name,
4056 const char *instance, const char *realm,
4057 krb5_principal *princ);
4060 * Convert a Kerberos V5 principal to a Kerberos V4 principal.
4062 * @param [in] context Library context
4063 * @param [in] princ V5 Principal
4064 * @param [out] name V4 principal's name to be filled in
4065 * @param [out] inst V4 principal's instance name to be filled in
4066 * @param [out] realm Principal's realm name to be filled in
4068 * This function separates a V5 principal @a princ into @a name, @a instance,
4074 * KRB5_INVALID_PRINCIPAL Invalid principal name
4076 * KRB5_CONFIG_CANTOPEN Can't open or find Kerberos configuration file
4078 * Kerberos error codes
4080 krb5_error_code KRB5_CALLCONV
4081 krb5_524_conv_principal(krb5_context context, krb5_const_principal princ,
4082 char *name, char *inst, char *realm);
4089 * Convert a Kerberos V5 credentials to a Kerberos V4 credentials
4091 * @note Not implemented
4093 * @retval KRB524_KRB4_DISABLED (always)
4096 krb5_524_convert_creds(krb5_context context, krb5_creds *v5creds,
4097 struct credentials *v4creds);
4100 #define krb524_convert_creds_kdc krb5_524_convert_creds
4101 #define krb524_init_ets(x) (0)
4107 * Get a handle for a key table.
4109 * @param [in] context Library context
4110 * @param [in] name Name of the key table
4111 * @param [out] ktid Key table handle
4113 * Resolve the key table name @a name and fill in a handle identifying the key
4114 * table. The key table is not opened.
4116 * @note @a name must be of the form @c type:residual, where @a type must be a
4117 * type known to the library and @a residual portion should be specific to the
4118 * particular keytab type.
4120 * @sa krb5_kt_close()
4123 * Example: krb5_kt_resolve(context, "FILE:/tmp/filename",&ktid);
4129 * Kerberos error codes
4131 krb5_error_code KRB5_CALLCONV
4132 krb5_kt_resolve(krb5_context context, const char *name, krb5_keytab *ktid);
4135 * Get default key table name.
4137 * @param [in] context Library context
4138 * @param [in,out] name Key table name to be resolved
4139 * @param [in] name_size Size of @a name to return
4141 * Fill @a name with the first @a name_size bytes of the name of the default
4142 * key table for the current user.
4144 * @sa MAX_KEYTAB_NAME_LEN
4149 * KRB5_CONFIG_NOTENUFSPACE Buffer is too short
4151 * Kerberos error codes
4153 krb5_error_code KRB5_CALLCONV
4154 krb5_kt_default_name(krb5_context context, char *name, int name_size);
4157 * Resolve default key table.
4159 * @param [in] context Library context
4160 * @param [in,out] id Key table handle
4162 * Fill @a keytab with the default key table's @a handle.
4167 * Kerberos error codes
4169 krb5_error_code KRB5_CALLCONV
4170 krb5_kt_default(krb5_context context, krb5_keytab *id);
4173 * Free the contents of a key table entry.
4175 * @param [in] context Library context
4176 * @param [in] entry Key table entry whose contents are to be freed
4178 * @note The pointer is not freed.
4180 * @retval 0 Success; otherwise - Kerberos error codes
4182 krb5_error_code KRB5_CALLCONV
4183 krb5_free_keytab_entry_contents(krb5_context context, krb5_keytab_entry *entry);
4185 /** @deprecated Use krb5_free_keytab_entry_contents instead. */
4186 krb5_error_code KRB5_CALLCONV
4187 krb5_kt_free_entry(krb5_context context, krb5_keytab_entry *entry);
4190 /* remove and add are functions, so that they can return NOWRITE
4191 if not a writable keytab */
4194 * Remove an entry from a key table.
4196 * @param [in] context Library context
4197 * @param [in] id Key table handle
4198 * @param [in] entry Entry to remove from key table
4203 * KRB5_KT_NOWRITE Key table is not writable
4205 * Kerberos error codes
4207 krb5_error_code KRB5_CALLCONV
4208 krb5_kt_remove_entry(krb5_context context, krb5_keytab id, krb5_keytab_entry *entry);
4211 * Add a new entry to a key table.
4213 * @param [in] context Library context
4214 * @param [in] id Key table handle
4215 * @param [in] entry Entry to be added
4220 * ENOMEM Insufficient memory
4222 * KRB5_KT_NOWRITE Key table is not writeable
4224 * Kerberos error codes
4226 krb5_error_code KRB5_CALLCONV
4227 krb5_kt_add_entry(krb5_context context, krb5_keytab id, krb5_keytab_entry *entry);
4230 * Convert a principal name into the default salt for that principal.
4232 * @param [in] context Library context
4233 * @param [in] pr Principal name
4234 * @param [out] ret Default salt for @a pr to be filled in
4236 * @retval 0 Success; otherwise - Kerberos error codes
4238 krb5_error_code KRB5_CALLCONV_WRONG
4239 krb5_principal2salt(krb5_context context,
4240 register krb5_const_principal pr, krb5_data *ret);
4241 /* librc.spec--see rcache.h */
4246 * Resolve a credential cache name.
4248 * @param [in] context Library context
4249 * @param [in] name Credential cache name to be resolved
4250 * @param [out] cache Credential cache handle
4252 * Fills in @a cache with a @a cache handle that corresponds to the name in @a
4253 * name. @a name should be of the form @c type:residual, and @a type must be a
4254 * type known to the library. If the @a name does not contain a colon,
4255 * interpret it as a file name.
4258 * Example: krb5_cc_resolve(context, "MEMORY:C_", &cache);
4264 * Kerberos error codes
4266 krb5_error_code KRB5_CALLCONV
4267 krb5_cc_resolve(krb5_context context, const char *name, krb5_ccache *cache);
4270 * Duplicate ccache handle.
4272 * @param [in] context Library context
4273 * @param [in] in Credential cache handle to be duplicated
4274 * @param [out] out Credential cache handle
4276 * Create a new handle referring to the same cache as @a in.
4277 * The new handle and @a in can be closed independently.
4279 krb5_error_code KRB5_CALLCONV
4280 krb5_cc_dup(krb5_context context, krb5_ccache in, krb5_ccache *out);
4283 * Return the name of the default credential cache.
4285 * @param [in] context Library context
4287 * Try the environment variable @a KRB5CCNAME first then, if it is not set,
4288 * fall back on the default ccache name for the OS.
4291 * Name of default credential cache for the current user.
4293 const char *KRB5_CALLCONV
4294 krb5_cc_default_name(krb5_context context);
4297 * Set the default credential cache name.
4299 * @param [in,out] context Library context
4300 * @param [in] name Default credential cache name
4302 * This function frees the old default credential cache name and then sets it
4308 * KV5M_CONTEXT Bad magic number for @c _krb5_context structure
4310 * Kerberos error codes
4312 krb5_error_code KRB5_CALLCONV
4313 krb5_cc_set_default_name(krb5_context context, const char *name);
4316 * Resolve the default crendentials cache name.
4318 * @param [in,out] context Library context
4319 * @param [out] ccache Pointer to credential cache name
4324 * KV5M_CONTEXT Bad magic number for @c _krb5_context structure
4326 * KRB5_FCC_INTERNAL The name of the default credential cache cannot be
4329 * Kerberos error codes
4331 krb5_error_code KRB5_CALLCONV
4332 krb5_cc_default(krb5_context context, krb5_ccache *ccache);
4335 * Copy a credential cache.
4337 * @param [in] context Library context
4338 * @param [in] incc Credential cache to be copied
4339 * @param [out] outcc Copy of credential cache to be filled in
4341 * @retval 0 Success; otherwise - Kerberos error codes
4343 krb5_error_code KRB5_CALLCONV
4344 krb5_cc_copy_creds(krb5_context context, krb5_ccache incc, krb5_ccache outcc);
4347 * Get a configuration value from a credential cache.
4349 * @param [in] context Library context
4350 * @param [in] id Credential cache handle
4351 * @param [in] principal Configuration for this principal;
4352 * if NULL, global for the whole cache
4353 * @param [in] key Name of config variable
4354 * @param [out] data Data to be fetched
4356 * Use krb5_free_data_contents() to free @a data when it is no longer needed.
4361 * Kerberos error codes
4363 krb5_error_code KRB5_CALLCONV
4364 krb5_cc_get_config(krb5_context context, krb5_ccache id,
4365 krb5_const_principal principal,
4366 const char *key, krb5_data *data);
4369 * Store a configuration value in a credential cache.
4371 * @param [in] context Library context
4372 * @param [in] id Credential cache handle
4373 * @param [in] principal Configuration for a specific principal;
4374 * if NULL, global for the whole cache
4375 * @param [in] key Name of config variable
4376 * @param [in] data Data to store, or NULL to remove
4378 * @note Existing configuration under the same key is over-written.
4380 * @warning Before version 1.10 @a data was assumed to be always non-null.
4385 * Kerberos error codes
4387 krb5_error_code KRB5_CALLCONV
4388 krb5_cc_set_config(krb5_context context, krb5_ccache id,
4389 krb5_const_principal principal,
4390 const char *key, krb5_data *data);
4393 * Test whether a principal is a configuration principal.
4395 * @param [in] context Library context
4396 * @param [in] principal Principal to check
4399 * @c TRUE if the principal is a configuration principal (generated part of
4400 * krb5_cc_set_config()); @c FALSE otherwise.
4402 krb5_boolean KRB5_CALLCONV
4403 krb5_is_config_principal(krb5_context context, krb5_const_principal principal);
4406 * Make a credential cache the primary cache for its collection.
4408 * @param [in] context Library context
4409 * @param [in] cache Credential cache handle
4411 * If the type of @a cache supports it, set @a cache to be the primary
4412 * credential cache for the collection it belongs to.
4415 * 0 Success, or the type of @a cache doesn't support switching
4417 * Kerberos error codes
4419 krb5_error_code KRB5_CALLCONV
4420 krb5_cc_switch(krb5_context context, krb5_ccache cache);
4423 * Determine whether a credential cache type supports switching.
4425 * @param [in] context Library context
4426 * @param [in] type Credential cache type
4428 * @version First introduced in 1.10
4430 * @retval TRUE if @a type supports switching
4431 * @retval FALSE if it does not or is not a valid credential cache type.
4433 krb5_boolean KRB5_CALLCONV
4434 krb5_cc_support_switch(krb5_context context, const char *type);
4437 * Find a credential cache with a specified client principal.
4439 * @param [in] context Library context
4440 * @param [in] client Client principal
4441 * @param [out] cache_out Credential cache handle
4443 * Find a cache within the collection whose default principal is @a client.
4444 * Use @a krb5_cc_close to close @a ccache when it is no longer needed.
4447 * @retval KRB5_CC_NOTFOUND
4449 * @sa krb5_cccol_cursor_new
4451 * @version First introduced in 1.10
4453 krb5_error_code KRB5_CALLCONV
4454 krb5_cc_cache_match(krb5_context context, krb5_principal client,
4455 krb5_ccache *cache_out);
4458 * Select a credential cache to use with a server principal.
4460 * @param [in] context Library context
4461 * @param [in] server Server principal
4462 * @param [out] cache_out Credential cache handle
4463 * @param [out] princ_out Client principal
4465 * Select a cache within the collection containing credentials most appropriate
4466 * for use with @a server, according to configured rules and heuristics.
4468 * Use krb5_cc_close() to release @a cache_out when it is no longer needed.
4469 * Use krb5_free_principal() to release @a princ_out when it is no longer
4470 * needed. Note that @a princ_out is set in some error conditions.
4473 * If an appropriate cache is found, 0 is returned, @a cache_out is set to the
4474 * selected cache, and @a princ_out is set to the default principal of that
4477 * If the appropriate client principal can be authoritatively determined but
4478 * the cache collection contains no credentials for that principal, then
4479 * KRB5_CC_NOTFOUND is returned, @a cache_out is set to NULL, and @a princ_out
4480 * is set to the appropriate client principal.
4482 * If no configured mechanism can determine the appropriate cache or principal,
4483 * KRB5_CC_NOTFOUND is returned and @a cache_out and @a princ_out are set to
4486 * Any other error code indicates a fatal error in the processing of a cache
4487 * selection mechanism.
4489 * @version First introduced in 1.10
4491 krb5_error_code KRB5_CALLCONV
4492 krb5_cc_select(krb5_context context, krb5_principal server,
4493 krb5_ccache *cache_out, krb5_principal *princ_out);
4497 * Free the storage assigned to a principal.
4499 * @param [in] context Library context
4500 * @param [in] val Principal to be freed
4503 krb5_free_principal(krb5_context context, krb5_principal val);
4506 * Free a krb5_authenticator structure.
4508 * @param [in] context Library context
4509 * @param [in] val Authenticator structure to be freed
4511 * This function frees the contents of @a val and the structure itself.
4514 krb5_free_authenticator(krb5_context context, krb5_authenticator *val);
4517 * Free the data stored in array of addresses.
4519 * @param [in] context Library context
4520 * @param [in] val Array of addresses to be freed
4522 * This function frees the contents of @a val and the array itself.
4524 * @note The last entry in the array must be a NULL pointer.
4527 krb5_free_addresses(krb5_context context, krb5_address **val);
4530 * Free the storage assigned to array of authentication data.
4532 * @param [in] context Library context
4533 * @param [in] val Array of authentication data to be freed
4535 * This function frees the contents of @a val and the array itself.
4537 * @note The last entry in the array must be a NULL pointer.
4540 krb5_free_authdata(krb5_context context, krb5_authdata **val);
4545 * @param [in] context Library context
4546 * @param [in] val Ticket to be freed
4548 * This function frees the contents of @a val and the structure itself.
4551 krb5_free_ticket(krb5_context context, krb5_ticket *val);
4554 * Free an error allocated by krb5_read_error() or krb5_sendauth().
4556 * @param [in] context Library context
4557 * @param [in] val Error data structure to be freed
4559 * This function frees the contents of @a val and the structure itself.
4562 krb5_free_error(krb5_context context, register krb5_error *val);
4565 * Free a krb5_creds structure.
4567 * @param [in] context Library context
4568 * @param [in] val Credential structure to be freed.
4570 * This function frees the contents of @a val and the structure itself.
4573 krb5_free_creds(krb5_context context, krb5_creds *val);
4576 * Free the contents of a krb5_creds structure.
4578 * @param [in] context Library context
4579 * @param [in] val Credential structure to free contents of
4581 * This function frees the contents of @a val, but not the structure itself.
4584 krb5_free_cred_contents(krb5_context context, krb5_creds *val);
4587 * Free a krb5_checksum structure.
4589 * @param [in] context Library context
4590 * @param [in] val Checksum structure to be freed
4592 * This function frees the contents of @a val and the structure itself.
4595 krb5_free_checksum(krb5_context context, register krb5_checksum *val);
4598 * Free the contents of a krb5_checksum structure.
4600 * @param [in] context Library context
4601 * @param [in] val Checksum structure to free contents of
4603 * This function frees the contents of @a val, but not the structure itself.
4606 krb5_free_checksum_contents(krb5_context context, register krb5_checksum *val);
4609 * Free a krb5_keyblock structure.
4611 * @param [in] context Library context
4612 * @param [in] val Keyblock to be freed
4614 * This function frees the contents of @a val and the structure itself.
4617 krb5_free_keyblock(krb5_context context, register krb5_keyblock *val);
4620 * Free the contents of a krb5_keyblock structure.
4622 * @param [in] context Library context
4623 * @param [in] key Keyblock to be freed
4625 * This function frees the contents of @a key, but not the structure itself.
4628 krb5_free_keyblock_contents(krb5_context context, register krb5_keyblock *key);
4631 * Free a krb5_ap_rep_enc_part structure.
4633 * @param [in] context Library context
4634 * @param [in] val AP-REP enc part to be freed
4636 * This function frees the contents of @a val and the structure itself.
4639 krb5_free_ap_rep_enc_part(krb5_context context, krb5_ap_rep_enc_part *val);
4642 * Free a krb5_data structure.
4644 * @param [in] context Library context
4645 * @param [in] val Data structure to be freed
4647 * This function frees the contents of @a val and the structure itself.
4650 krb5_free_data(krb5_context context, krb5_data *val);
4652 /* Free a krb5_octet_data structure (should be unused). */
4654 krb5_free_octet_data(krb5_context context, krb5_octet_data *val);
4657 * Free the contents of a krb5_data structure and zero the data field.
4659 * @param [in] context Library context
4660 * @param [in] val Data structure to free contents of
4662 * This function frees the contents of @a val, but not the structure itself.
4665 krb5_free_data_contents(krb5_context context, krb5_data *val);
4668 * Free a string representation of a principal.
4670 * @param [in] context Library context
4671 * @param [in] val Name string to be freed
4674 krb5_free_unparsed_name(krb5_context context, char *val);
4677 * Free a string allocated by a krb5 function.
4679 * @param [in] context Library context
4680 * @param [in] val String to be freed
4682 * @version First introduced in 1.10
4685 krb5_free_string(krb5_context context, char *val);
4688 * Free an array of checksum types.
4690 * @param [in] context Library context
4691 * @param [in] val Array of checksum types to be freed
4694 krb5_free_cksumtypes(krb5_context context, krb5_cksumtype *val);
4696 /* From krb5/os, but needed by the outside world */
4698 * Retrieve the system time of day, in sec and ms, since the epoch.
4700 * @param [in] context Library context
4701 * @param [out] seconds System timeofday, seconds portion
4702 * @param [out] microseconds System timeofday, microseconds portion
4704 * This function retrieves the system time of day with the context
4705 * specific time offset adjustment.
4707 * @sa krb5_crypto_us_timeofday()
4712 * Kerberos error codes
4714 krb5_error_code KRB5_CALLCONV
4715 krb5_us_timeofday(krb5_context context,
4716 krb5_timestamp *seconds, krb5_int32 *microseconds);
4719 * Retrieve the current time with context specific time offset adjustment.
4721 * @param [in] context Library context
4722 * @param [in,out] timeret Timestamp to fill in
4724 * This function retrieves the system time of day with the context specific
4725 * time offset adjustment.
4730 * Kerberos error codes
4732 krb5_error_code KRB5_CALLCONV
4733 krb5_timeofday(krb5_context context, register krb5_timestamp *timeret);
4736 * Check if a timestamp is within the allowed clock skew of the current time.
4738 * @param [in] context Library context
4739 * @param [in] date Timestamp to check
4741 * This function checks if @a date is close enough to the current time
4742 * according to the configured allowable clock skew.
4744 * @version First introduced in 1.10
4747 * @retval KRB5KRB_AP_ERR_SKEW @a date is not within allowable clock skew
4749 krb5_error_code KRB5_CALLCONV
4750 krb5_check_clockskew(krb5_context context, krb5_timestamp date);
4753 * Return all interface addresses for this host.
4755 * @param [in] context Library context
4756 * @param [out] addr Array of krb5_address pointers, ending with
4759 * Use krb5_free_addresses() to free @a addr when it is no longer needed.
4761 * @retval 0 Success; otherwise - Kerberos error codes
4763 krb5_error_code KRB5_CALLCONV
4764 krb5_os_localaddr(krb5_context context, krb5_address ***addr);
4767 * Retrieve the default realm.
4769 * @param [in] context Library context
4770 * @param [out] lrealm Default realm name
4772 * Retrieves the default realm to be used if no user-specified realm is
4775 * Use krb5_free_default_realm() to free @a lrealm when it is no longer needed.
4780 * Kerberos error codes
4782 krb5_error_code KRB5_CALLCONV
4783 krb5_get_default_realm(krb5_context context, char **lrealm);
4786 * Override the default realm for the specified context.
4788 * @param [in] context Library context
4789 * @param [in] lrealm Realm name for the default realm
4791 * If @a lrealm is NULL, clear the default realm setting.
4796 * Kerberos error codes
4798 krb5_error_code KRB5_CALLCONV
4799 krb5_set_default_realm(krb5_context context, const char *lrealm);
4802 * Free a default realm string returned by krb5_get_default_realm().
4804 * @param [in] context Library context
4805 * @param [in] lrealm Realm to be freed
4808 krb5_free_default_realm(krb5_context context, char *lrealm);
4811 * Generate a full principal name from a service name.
4813 * @param [in] context Library context
4814 * @param [in] hostname Host name, or NULL to use local host
4815 * @param [in] sname Service name, or NULL to use @c "host"
4816 * @param [in] type Principal type
4817 * @param [out] ret_princ Generated principal
4819 * This function converts a @a hostname and @a sname into @a krb5_principal
4820 * structure @a ret_princ. The returned principal will be of the form @a
4821 * sname\/hostname\@REALM where REALM is determined by krb5_get_host_realm().
4822 * In some cases this may be the referral (empty) realm.
4824 * The @a type can be one of the following:
4826 * @li #KRB5_NT_SRV_HST canonicalizes the host name before looking up the
4827 * realm and generating the principal.
4829 * @li #KRB5_NT_UNKNOWN accepts the hostname as given, and does not
4832 * Use krb5_free_principal to free @a ret_princ when it is no longer needed.
4837 * Kerberos error codes
4839 krb5_error_code KRB5_CALLCONV
4840 krb5_sname_to_principal(krb5_context context, const char *hostname, const char *sname,
4841 krb5_int32 type, krb5_principal *ret_princ);
4844 * Test whether a principal matches a matching principal.
4846 * @param [in] context Library context
4847 * @param [in] matching Matching principal
4848 * @param [in] princ Principal to test
4850 * @note A matching principal is a host-based principal with an empty realm
4851 * and/or second data component (hostname). Profile configuration may cause
4852 * the hostname to be ignored even if it is present. A principal matches a
4853 * matching principal if the former has the same non-empty (and non-ignored)
4854 * components of the latter.
4856 * If @a matching is NULL, return TRUE. If @a matching is not a matching
4857 * principal, return the value of krb5_principal_compare(context, matching,
4861 * TRUE if @a princ matches @a matching, FALSE otherwise.
4863 krb5_boolean KRB5_CALLCONV
4864 krb5_sname_match(krb5_context context, krb5_const_principal matching,
4865 krb5_const_principal princ);
4868 * Change a password for an existing Kerberos account.
4870 * @param [in] context Library context
4871 * @param [in] creds Credentials for kadmin/changepw service
4872 * @param [in] newpw New password
4873 * @param [out] result_code Numeric error code from server
4874 * @param [out] result_code_string String equivalent to @a result_code
4875 * @param [out] result_string Change password response from the KDC
4877 * Change the password for the existing principal identified by @a creds.
4879 * The possible values of the output @a result_code are:
4881 * @li #KRB5_KPASSWD_SUCCESS (0) - success
4882 * @li #KRB5_KPASSWD_MALFORMED (1) - Malformed request error
4883 * @li #KRB5_KPASSWD_HARDERROR (2) - Server error
4884 * @li #KRB5_KPASSWD_AUTHERROR (3) - Authentication error
4885 * @li #KRB5_KPASSWD_SOFTERROR (4) - Password change rejected
4887 * @retval 0 Success; otherwise - Kerberos error codes
4889 krb5_error_code KRB5_CALLCONV
4890 krb5_change_password(krb5_context context, krb5_creds *creds, char *newpw,
4891 int *result_code, krb5_data *result_code_string,
4892 krb5_data *result_string);
4895 * Set a password for a principal using specified credentials.
4897 * @param [in] context Library context
4898 * @param [in] creds Credentials for kadmin/changepw service
4899 * @param [in] newpw New password
4900 * @param [in] change_password_for Change the password for this principal
4901 * @param [out] result_code Numeric error code from server
4902 * @param [out] result_code_string String equivalent to @a result_code
4903 * @param [out] result_string Data returned from the remote system
4905 * This function uses the credentials @a creds to set the password @a newpw for
4906 * the principal @a change_password_for. It implements the set password
4907 * operation of RFC 3244, for interoperability with Microsoft Windows
4910 * @note If @a change_password_for is NULL, the change is performed on the
4911 * current principal. If @a change_password_for is non-null, the change is
4912 * performed on the principal name passed in @a change_password_for.
4914 * The error code and strings are returned in @a result_code,
4915 * @a result_code_string and @a result_string.
4917 * @sa krb5_set_password_using_ccache()
4920 * 0 Success and result_code is set to #KRB5_KPASSWD_SUCCESS.
4922 * Kerberos error codes.
4924 krb5_error_code KRB5_CALLCONV
4925 krb5_set_password(krb5_context context, krb5_creds *creds, char *newpw,
4926 krb5_principal change_password_for, int *result_code,
4927 krb5_data *result_code_string, krb5_data *result_string);
4930 * Set a password for a principal using cached credentials.
4932 * @param [in] context Library context
4933 * @param [in] ccache Credential cache
4934 * @param [in] newpw New password
4935 * @param [in] change_password_for Change the password for this principal
4936 * @param [out] result_code Numeric error code from server
4937 * @param [out] result_code_string String equivalent to @a result_code
4938 * @param [out] result_string Data returned from the remote system
4940 * This function uses the cached credentials from @a ccache to set the password
4941 * @a newpw for the principal @a change_password_for. It implements RFC 3244
4942 * set password operation (interoperable with MS Windows implementations) using
4943 * the credential cache.
4945 * The error code and strings are returned in @a result_code,
4946 * @a result_code_string and @a result_string.
4948 * @note If @a change_password_for is set to NULL, the change is performed on
4949 * the default principal in @a ccache. If @a change_password_for is non null,
4950 * the change is performed on the specified principal.
4952 * @sa krb5_set_password()
4957 * Kerberos error codes
4959 krb5_error_code KRB5_CALLCONV
4960 krb5_set_password_using_ccache(krb5_context context, krb5_ccache ccache,
4961 char *newpw, krb5_principal change_password_for,
4962 int *result_code, krb5_data *result_code_string,
4963 krb5_data *result_string);
4966 * Get a result message for changing or setting a password.
4968 * @param [in] context Library context
4969 * @param [in] server_string Data returned from the remote system
4970 * @param [out] message_out A message displayable to the user
4972 * This function processes the @a server_string returned in the @a
4973 * result_string parameter of krb5_change_password(), krb5_set_password(), and
4974 * related functions, and returns a displayable string. If @a server_string
4975 * contains Active Directory structured policy information, it will be
4976 * converted into human-readable text.
4978 * Use krb5_free_string() to free @a message_out when it is no longer needed.
4983 * Kerberos error codes
4985 * @version First introduced in 1.11
4987 krb5_error_code KRB5_CALLCONV
4988 krb5_chpw_message(krb5_context context, const krb5_data *server_string,
4989 char **message_out);
4992 * Retrieve configuration profile from the context.
4994 * @param [in] context Library context
4995 * @param [out] profile Pointer to data read from a configuration file
4997 * This function creates a new @a profile object that reflects profile
4998 * in the supplied @a context.
5000 * The @a profile object may be freed with profile_release() function.
5001 * See profile.h and profile API for more details.
5006 * Kerberos error codes
5008 krb5_error_code KRB5_CALLCONV
5009 krb5_get_profile(krb5_context context, struct _profile_t ** profile);
5012 /** @deprecated Replaced by krb5_get_init_creds_password().*/
5013 KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
5014 krb5_get_in_tkt_with_password(krb5_context context, krb5_flags options,
5015 krb5_address *const *addrs, krb5_enctype *ktypes,
5016 krb5_preauthtype *pre_auth_types,
5017 const char *password, krb5_ccache ccache,
5018 krb5_creds *creds, krb5_kdc_rep **ret_as_reply);
5020 /** @deprecated Replaced by krb5_get_init_creds(). */
5021 KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
5022 krb5_get_in_tkt_with_skey(krb5_context context, krb5_flags options,
5023 krb5_address *const *addrs, krb5_enctype *ktypes,
5024 krb5_preauthtype *pre_auth_types,
5025 const krb5_keyblock *key, krb5_ccache ccache,
5026 krb5_creds *creds, krb5_kdc_rep **ret_as_reply);
5028 /** @deprecated Replaced by krb5_get_init_creds_keytab(). */
5029 KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
5030 krb5_get_in_tkt_with_keytab(krb5_context context, krb5_flags options,
5031 krb5_address *const *addrs, krb5_enctype *ktypes,
5032 krb5_preauthtype *pre_auth_types,
5033 krb5_keytab arg_keytab, krb5_ccache ccache,
5034 krb5_creds *creds, krb5_kdc_rep **ret_as_reply);
5036 #endif /* KRB5_DEPRECATED */
5039 * Parse and decrypt a @c KRB_AP_REQ message.
5041 * @param [in] context Library context
5042 * @param [in,out] auth_context Pre-existing or newly created auth context
5043 * @param [in] inbuf AP-REQ message to be parsed
5044 * @param [in] server Matching principal for server, or NULL to
5045 * allow any principal in keytab
5046 * @param [in] keytab Key table, or NULL to use the default
5047 * @param [out] ap_req_options If non-null, the AP-REQ flags on output
5048 * @param [out] ticket If non-null, ticket from the AP-REQ message
5050 * This function parses, decrypts and verifies a AP-REQ message from @a inbuf
5051 * and stores the authenticator in @a auth_context.
5053 * If a keyblock is present in the @a auth_context, it is used to decrypt the
5054 * ticket in AP-REQ message. (This is useful for user-to-user authentication.)
5055 * Otherwise, the decryption key is obtained from the @a keytab. If @a keytab
5056 * is iterable, all of its key entries it will be tried against the ticket;
5057 * otherwise, the server principal in the ticket will be looked up in the
5058 * keytab and that key will be tried.
5060 * The client specified in the decrypted authenticator must match the client
5061 * specified in the decrypted ticket. If @a server is non-null, the key in
5062 * which the ticket is encrypted must correspond to a principal in @a keytab
5063 * matching @a server according to the rules of krb5_sname_match().
5065 * If the @a remote_addr field of @a auth_context is set, the request must come
5066 * from that address.
5068 * If a replay cache handle is provided in the @a auth_context, the
5069 * authenticator and ticket are verified against it. If no conflict is found,
5070 * the new authenticator is then stored in the replay cash of @a auth_context.
5072 * Various other checks are performed on the decoded data, including
5073 * cross-realm policy, clockskew, and ticket validation times.
5075 * On success the authenticator, subkey, and remote sequence number of the
5076 * request are stored in @a auth_context. If the #AP_OPTS_MUTUAL_REQUIRED
5077 * bit is set, the local sequence number is XORed with the remote sequence
5078 * number in the request.
5080 * Use krb5_free_ticket() to free @a ticket when it is no longer needed.
5082 * @retval 0 Success; otherwise - Kerberos error codes
5084 krb5_error_code KRB5_CALLCONV
5085 krb5_rd_req(krb5_context context, krb5_auth_context *auth_context,
5086 const krb5_data *inbuf, krb5_const_principal server,
5087 krb5_keytab keytab, krb5_flags *ap_req_options,
5088 krb5_ticket **ticket);
5091 * Retrieve a service key from a key table.
5093 * @param [in] context Library context
5094 * @param [in] keyprocarg Name of a key table (NULL to use default name)
5095 * @param [in] principal Service principal
5096 * @param [in] vno Key version number (0 for highest available)
5097 * @param [in] enctype Encryption type (0 for any type)
5098 * @param [out] key Service key from key table
5100 * Open and search the specified key table for the entry identified by @a
5101 * principal, @a enctype, and @a vno. If no key is found, return an error code.
5103 * The default key table is used, unless @a keyprocarg is non-null.
5104 * @a keyprocarg designates a specific key table.
5106 * Use krb5_free_keyblock() to free @a key when it is no longer needed.
5110 * @return Kerberos error code if not found or @a keyprocarg is invalid.
5112 krb5_error_code KRB5_CALLCONV
5113 krb5_kt_read_service_key(krb5_context context, krb5_pointer keyprocarg,
5114 krb5_principal principal, krb5_kvno vno,
5115 krb5_enctype enctype, krb5_keyblock **key);
5118 * Format a @c KRB-SAFE message.
5120 * @param [in] context Library context
5121 * @param [in,out] auth_context Authentication context
5122 * @param [in] userdata User data in the message
5123 * @param [out] outbuf Formatted @c KRB-SAFE buffer
5124 * @param [out] outdata Replay data. Specify NULL if not needed
5126 * This function creates an integrity protected @c KRB-SAFE message
5127 * using data supplied by the application.
5129 * Fields in @a auth_context specify the checksum type, the keyblock that
5130 * can be used to seed the checksum, full addresses (host and port) for
5131 * the sender and receiver, and @ref KRB5_AUTH_CONTEXT flags.
5133 * The local address in @a auth_context must be set, and is used to form the
5134 * sender address used in the KRB-SAFE message. The remote address is
5135 * optional; if specified, it will be used to form the receiver address used in
5138 * If #KRB5_AUTH_CONTEXT_DO_TIME flag is set in the @a auth_context, an entry
5139 * describing the message is entered in the replay cache @a
5140 * auth_context->rcache which enables the caller to detect if this message is
5141 * reflected by an attacker. If #KRB5_AUTH_CONTEXT_DO_TIME is not set, the
5142 * replay cache is not used.
5144 * If either #KRB5_AUTH_CONTEXT_DO_SEQUENCE or
5145 * #KRB5_AUTH_CONTEXT_RET_SEQUENCE is set, the @a auth_context local sequence
5146 * number will be placed in @a outdata as its sequence number.
5148 * @note The @a outdata argument is required if #KRB5_AUTH_CONTEXT_RET_TIME or
5149 * #KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in the @a auth_context.
5151 * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
5153 * @retval 0 Success; otherwise - Kerberos error codes
5155 krb5_error_code KRB5_CALLCONV
5156 krb5_mk_safe(krb5_context context, krb5_auth_context auth_context,
5157 const krb5_data *userdata, krb5_data *outbuf,
5158 krb5_replay_data *outdata);
5161 * Format a @c KRB-PRIV message.
5163 * @param [in] context Library context
5164 * @param [in,out] auth_context Authentication context
5165 * @param [in] userdata User data for @c KRB-PRIV message
5166 * @param [out] outbuf Formatted @c KRB-PRIV message
5167 * @param [out] outdata Replay cache handle (NULL if not needed)
5169 * This function is similar to krb5_mk_safe(), but the message is encrypted and
5170 * integrity-protected, not just integrity-protected.
5172 * The local address in @a auth_context must be set, and is used to form the
5173 * sender address used in the KRB-SAFE message. The remote address is
5174 * optional; if specified, it will be used to form the receiver address used in
5177 * @note If the #KRB5_AUTH_CONTEXT_RET_TIME or
5178 * #KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in @a auth_context, the @a
5179 * outdata is required.
5181 * @note The flags from @a auth_context specify whether sequence numbers or
5182 * timestamps will be used to identify the message. Valid values are:
5184 * @li #KRB5_AUTH_CONTEXT_DO_TIME - Use timestamps in @a outdata
5185 * @li #KRB5_AUTH_CONTEXT_RET_TIME - Copy timestamp to @a outdata.
5186 * @li #KRB5_AUTH_CONTEXT_DO_SEQUENCE - Use local sequence numbers from
5187 * @a auth_context in replay cache.
5188 * @li #KRB5_AUTH_CONTEXT_RET_SEQUENCE - Use local sequence numbers from
5189 * @a auth_context as a sequence number
5190 * in the encrypted message @a outbuf.
5192 * @retval 0 Success; otherwise - Kerberos error codes
5194 krb5_error_code KRB5_CALLCONV
5195 krb5_mk_priv(krb5_context context, krb5_auth_context auth_context,
5196 const krb5_data *userdata, krb5_data *outbuf,
5197 krb5_replay_data *outdata);
5200 * Client function for @c sendauth protocol.
5202 * @param [in] context Library context
5203 * @param [in,out] auth_context Authentication context
5204 * @param [in] fd File descriptor that describes network socket
5205 * @param [in] appl_version Application protocol version to be matched
5206 * with the receiver's application version
5207 * @param [in] client Client principal
5208 * @param [in] server Server principal
5209 * @param [in] ap_req_options @ref AP_OPTS options
5210 * @param [in] in_data Data to be sent to the server
5211 * @param [in] in_creds Input credentials, or NULL to use @a ccache
5212 * @param [in] ccache Credential cache
5213 * @param [out] error If non-null, contains KRB_ERROR message
5214 * returned from server
5215 * @param [out] rep_result If non-null and @a ap_req_options is
5216 * #AP_OPTS_MUTUAL_REQUIRED, contains the result
5217 * of mutual authentication exchange
5218 * @param [out] out_creds If non-null, the retrieved credentials
5220 * This function performs the client side of a sendauth/recvauth exchange by
5221 * sending and receiving messages over @a fd.
5223 * Credentials may be specified in three ways:
5225 * @li If @a in_creds is NULL, credentials are obtained with
5226 * krb5_get_credentials() using the principals @a client and @a server. @a
5227 * server must be non-null; @a client may NULL to use the default principal of
5230 * @li If @a in_creds is non-null, but does not contain a ticket, credentials
5231 * for the exchange are obtained with krb5_get_credentials() using @a in_creds.
5232 * In this case, the values of @a client and @a server are unused.
5234 * @li If @a in_creds is a complete credentials structure, it used directly.
5235 * In this case, the values of @a client, @a server, and @a ccache are unused.
5237 * If the server is using a different application protocol than that specified
5238 * in @a appl_version, an error will be returned.
5240 * Use krb5_free_creds() to free @a out_creds, krb5_free_ap_rep_enc_part() to
5241 * free @a rep_result, and krb5_free_error() to free @a error when they are no
5244 * @sa krb5_recvauth()
5246 * @retval 0 Success; otherwise - Kerberos error codes
5248 krb5_error_code KRB5_CALLCONV
5249 krb5_sendauth(krb5_context context, krb5_auth_context *auth_context,
5250 krb5_pointer fd, char *appl_version, krb5_principal client,
5251 krb5_principal server, krb5_flags ap_req_options,
5252 krb5_data *in_data, krb5_creds *in_creds, krb5_ccache ccache,
5253 krb5_error **error, krb5_ap_rep_enc_part **rep_result,
5254 krb5_creds **out_creds);
5257 * Server function for @a sendauth protocol.
5259 * @param [in] context Library context
5260 * @param [in,out] auth_context Authentication context
5261 * @param [in] fd File descriptor
5262 * @param [in] appl_version Application protocol version to be matched
5263 * against the client's application version
5264 * @param [in] server Server principal (NULL for any in @a keytab)
5265 * @param [in] flags Additional specifications
5266 * @param [in] keytab Key table containing service keys
5267 * @param [out] ticket Ticket (NULL if not needed)
5269 * This function performs the srever side of a sendauth/recvauth exchange by
5270 * sending and receiving messages over @a fd.
5272 * Use krb5_free_ticket() to free @a ticket when it is no longer needed.
5274 * @sa krb5_sendauth()
5276 * @retval 0 Success; otherwise - Kerberos error codes
5278 krb5_error_code KRB5_CALLCONV
5279 krb5_recvauth(krb5_context context, krb5_auth_context *auth_context,
5280 krb5_pointer fd, char *appl_version, krb5_principal server,
5281 krb5_int32 flags, krb5_keytab keytab, krb5_ticket **ticket);
5284 * Server function for @a sendauth protocol with version parameter.
5286 * @param [in] context Library context
5287 * @param [in,out] auth_context Authentication context
5288 * @param [in] fd File descriptor
5289 * @param [in] server Server principal (NULL for any in @a keytab)
5290 * @param [in] flags Additional specifications
5291 * @param [in] keytab Decryption key
5292 * @param [out] ticket Ticket (NULL if not needed)
5293 * @param [out] version sendauth protocol version (NULL if not needed)
5295 * This function is similar to krb5_recvauth() with the additional output
5296 * information place into @a version.
5298 * @retval 0 Success; otherwise - Kerberos error codes
5300 krb5_error_code KRB5_CALLCONV
5301 krb5_recvauth_version(krb5_context context,
5302 krb5_auth_context *auth_context,
5304 krb5_principal server,
5307 krb5_ticket **ticket,
5308 krb5_data *version);
5311 * Format a @c KRB-CRED message for an array of credentials.
5313 * @param [in] context Library context
5314 * @param [in,out] auth_context Authentication context
5315 * @param [in] ppcreds Null-terminated array of credentials
5316 * @param [out] ppdata Encoded credentials
5317 * @param [out] outdata Replay cache information (NULL if not needed)
5319 * This function takes an array of credentials @a ppcreds and formats
5320 * a @c KRB-CRED message @a ppdata to pass to krb5_rd_cred().
5322 * @note If the #KRB5_AUTH_CONTEXT_RET_TIME or #KRB5_AUTH_CONTEXT_RET_SEQUENCE
5323 * flag is set in @a auth_context, @a outdata is required.
5325 * The message will be encrypted using the send subkey of @a auth_context if it
5326 * is present, or the session key otherwise.
5331 * ENOMEM Insufficient memory
5333 * KRB5_RC_REQUIRED Message replay detection requires @a rcache parameter
5335 * Kerberos error codes
5337 krb5_error_code KRB5_CALLCONV
5338 krb5_mk_ncred(krb5_context context, krb5_auth_context auth_context,
5339 krb5_creds **ppcreds, krb5_data **ppdata,
5340 krb5_replay_data *outdata);
5343 * Format a @c KRB-CRED message for a single set of credentials.
5345 * @param [in] context Library context
5346 * @param [in,out] auth_context Authentication context
5347 * @param [in] pcreds Pointer to credentials
5348 * @param [out] ppdata Encoded credentials
5349 * @param [out] outdata Replay cache data (NULL if not needed)
5351 * This is a convenience function that calls krb5_mk_ncred() with a single set
5357 * ENOMEM Insufficient memory
5359 * KRB5_RC_REQUIRED Message replay detection requires @a rcache parameter
5361 * Kerberos error codes
5363 krb5_error_code KRB5_CALLCONV
5364 krb5_mk_1cred(krb5_context context, krb5_auth_context auth_context,
5365 krb5_creds *pcreds, krb5_data **ppdata,
5366 krb5_replay_data *outdata);
5369 * Read and validate a @c KRB-CRED message.
5371 * @param [in] context Library context
5372 * @param [in,out] auth_context Authentication context
5373 * @param [in] pcreddata @c KRB-CRED message
5374 * @param [out] pppcreds Null-terminated array of forwarded credentials
5375 * @param [out] outdata Replay data (NULL if not needed)
5377 * @note The @a outdata argument is required if #KRB5_AUTH_CONTEXT_RET_TIME or
5378 * #KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in the @a auth_context.`
5380 * @a pcreddata will be decrypted using the receiving subkey if it is present
5381 * in @a auth_context, or the session key if the receiving subkey is not
5382 * present or fails to decrypt the message.
5384 * Use krb5_free_tgt_creds() to free @a pppcreds when it is no longer needed.
5386 * @retval 0 Success; otherwise - Kerberos error codes
5388 krb5_error_code KRB5_CALLCONV
5389 krb5_rd_cred(krb5_context context, krb5_auth_context auth_context,
5390 krb5_data *pcreddata, krb5_creds ***pppcreds,
5391 krb5_replay_data *outdata);
5394 * Get a forwarded TGT and format a @c KRB-CRED message.
5396 * @param [in] context Library context
5397 * @param [in] auth_context Authentication context
5398 * @param [in] rhost Remote host
5399 * @param [in] client Client principal of TGT
5400 * @param [in] server Principal of server to receive TGT
5401 * @param [in] cc Credential cache handle (NULL to use default)
5402 * @param [in] forwardable Whether TGT should be forwardable
5403 * @param [out] outbuf KRB-CRED message
5405 * Get a TGT for use at the remote host @a rhost and format it into a KRB-CRED
5406 * message. If @a rhost is NULL and @a server is of type #KRB5_NT_SRV_HST,
5407 * the second component of @a server will be used.
5412 * ENOMEM Insufficient memory
5414 * KRB5_PRINC_NOMATCH Requested principal and ticket do not match
5416 * KRB5_NO_TKT_SUPPLIED Request did not supply a ticket
5418 * KRB5_CC_BADNAME Credential cache name or principal name malformed
5420 * Kerberos error codes
5422 krb5_error_code KRB5_CALLCONV
5423 krb5_fwd_tgt_creds(krb5_context context, krb5_auth_context auth_context,
5424 char *rhost, krb5_principal client, krb5_principal server,
5425 krb5_ccache cc, int forwardable, krb5_data *outbuf);
5428 * Create and initialize an authentication context.
5430 * @param [in] context Library context
5431 * @param [out] auth_context Authentication context
5433 * This function creates an authentication context to hold configuration and
5434 * state relevant to krb5 functions for authenticating principals and
5435 * protecting messages once authentication has occurred.
5437 * By default, flags for the context are set to enable the use of the replay
5438 * cache (#KRB5_AUTH_CONTEXT_DO_TIME), but not sequence numbers. Use
5439 * krb5_auth_con_setflags() to change the flags.
5441 * The allocated @a auth_context must be freed with krb5_auth_con_free() when
5442 * it is no longer needed.
5444 * @retval 0 Success; otherwise - Kerberos error codes
5446 krb5_error_code KRB5_CALLCONV
5447 krb5_auth_con_init(krb5_context context, krb5_auth_context *auth_context);
5450 * Free a krb5_auth_context structure.
5452 * @param [in] context Library context
5453 * @param [in] auth_context Authentication context to be freed
5455 * This function frees an auth context allocated by krb5_auth_con_init().
5457 * @retval 0 (always)
5459 krb5_error_code KRB5_CALLCONV
5460 krb5_auth_con_free(krb5_context context, krb5_auth_context auth_context);
5463 * Set a flags field in a krb5_auth_context structure.
5465 * @param [in] context Library context
5466 * @param [in,out] auth_context Authentication context
5467 * @param [in] flags Flags bit mask
5469 * Valid values for @a flags are:
5470 * @li #KRB5_AUTH_CONTEXT_DO_TIME Use timestamps
5471 * @li #KRB5_AUTH_CONTEXT_RET_TIME Save timestamps
5472 * @li #KRB5_AUTH_CONTEXT_DO_SEQUENCE Use sequence numbers
5473 * @li #KRB5_AUTH_CONTEXT_RET_SEQUENCE Save sequence numbers
5475 * @retval 0 (always)
5477 krb5_error_code KRB5_CALLCONV
5478 krb5_auth_con_setflags(krb5_context context, krb5_auth_context auth_context, krb5_int32 flags);
5481 * Retrieve flags from a krb5_auth_context structure.
5483 * @param [in] context Library context
5484 * @param [in] auth_context Authentication context
5485 * @param [out] flags Flags bit mask
5487 * Valid values for @a flags are:
5488 * @li #KRB5_AUTH_CONTEXT_DO_TIME Use timestamps
5489 * @li #KRB5_AUTH_CONTEXT_RET_TIME Save timestamps
5490 * @li #KRB5_AUTH_CONTEXT_DO_SEQUENCE Use sequence numbers
5491 * @li #KRB5_AUTH_CONTEXT_RET_SEQUENCE Save sequence numbers
5493 * @retval 0 (always)
5495 krb5_error_code KRB5_CALLCONV
5496 krb5_auth_con_getflags(krb5_context context, krb5_auth_context auth_context,
5500 * Set a checksum callback in an auth context.
5502 * @param [in] context Library context
5503 * @param [in] auth_context Authentication context
5504 * @param [in] func Checksum callback
5505 * @param [in] data Callback argument
5507 * Set a callback to obtain checksum data in krb5_mk_req(). The callback will
5508 * be invoked after the subkey and local sequence number are stored in @a
5511 * @retval 0 (always)
5513 krb5_error_code KRB5_CALLCONV
5514 krb5_auth_con_set_checksum_func( krb5_context context,
5515 krb5_auth_context auth_context,
5516 krb5_mk_req_checksum_func func,
5520 * Get the checksum callback from an auth context.
5522 * @param [in] context Library context
5523 * @param [in] auth_context Authentication context
5524 * @param [out] func Checksum callback
5525 * @param [out] data Callback argument
5527 * @retval 0 (always)
5529 krb5_error_code KRB5_CALLCONV
5530 krb5_auth_con_get_checksum_func( krb5_context context,
5531 krb5_auth_context auth_context,
5532 krb5_mk_req_checksum_func *func,
5536 * Set the local and remote addresses in an auth context.
5538 * @param [in] context Library context
5539 * @param [in] auth_context Authentication context
5540 * @param [in] local_addr Local address
5541 * @param [in] remote_addr Remote address
5543 * This function releases the storage assigned to the contents of the local and
5544 * remote addresses of @a auth_context and then sets them to @a local_addr and
5545 * @a remote_addr respectively.
5547 * @sa krb5_auth_con_genaddrs()
5549 * @retval 0 Success; otherwise - Kerberos error codes
5551 krb5_error_code KRB5_CALLCONV_WRONG
5552 krb5_auth_con_setaddrs(krb5_context context, krb5_auth_context auth_context,
5553 krb5_address *local_addr, krb5_address *remote_addr);
5556 * Retrieve address fields from an auth context.
5558 * @param [in] context Library context
5559 * @param [in] auth_context Authentication context
5560 * @param [out] local_addr Local address (NULL if not needed)
5561 * @param [out] remote_addr Remote address (NULL if not needed)
5563 * @retval 0 Success; otherwise - Kerberos error codes
5565 krb5_error_code KRB5_CALLCONV
5566 krb5_auth_con_getaddrs(krb5_context context, krb5_auth_context auth_context,
5567 krb5_address **local_addr, krb5_address **remote_addr);
5570 * Set local and remote port fields in an auth context.
5572 * @param [in] context Library context
5573 * @param [in] auth_context Authentication context
5574 * @param [in] local_port Local port
5575 * @param [in] remote_port Remote port
5577 * This function releases the storage assigned to the contents of the local and
5578 * remote ports of @a auth_context and then sets them to @a local_port and @a
5579 * remote_port respectively.
5581 * @sa krb5_auth_con_genaddrs()
5583 * @retval 0 Success; otherwise - Kerberos error codes
5585 krb5_error_code KRB5_CALLCONV
5586 krb5_auth_con_setports(krb5_context context, krb5_auth_context auth_context,
5587 krb5_address *local_port, krb5_address *remote_port);
5590 * Set the session key in an auth context.
5592 * @param [in] context Library context
5593 * @param [in] auth_context Authentication context
5594 * @param [in] keyblock User key
5596 * @retval 0 Success; otherwise - Kerberos error codes
5598 krb5_error_code KRB5_CALLCONV
5599 krb5_auth_con_setuseruserkey(krb5_context context, krb5_auth_context auth_context,
5600 krb5_keyblock *keyblock);
5603 * Retrieve the session key from an auth context as a keyblock.
5605 * @param [in] context Library context
5606 * @param [in] auth_context Authentication context
5607 * @param [out] keyblock Session key
5609 * This function creates a keyblock containing the session key from @a
5610 * auth_context. Use krb5_free_keyblock() to free @a keyblock when it is no
5613 * @retval 0 Success. Otherwise - Kerberos error codes
5615 krb5_error_code KRB5_CALLCONV
5616 krb5_auth_con_getkey(krb5_context context, krb5_auth_context auth_context,
5617 krb5_keyblock **keyblock);
5620 * Retrieve the session key from an auth context.
5622 * @param [in] context Library context
5623 * @param [in] auth_context Authentication context
5624 * @param [out] key Session key
5626 * This function sets @a key to the session key from @a auth_context. Use
5627 * krb5_k_free_key() to release @a key when it is no longer needed.
5629 * @retval 0 (always)
5631 krb5_error_code KRB5_CALLCONV
5632 krb5_auth_con_getkey_k(krb5_context context, krb5_auth_context auth_context,
5636 * Retrieve the send subkey from an auth context as a keyblock.
5638 * @param [in] ctx Library context
5639 * @param [in] ac Authentication context
5640 * @param [out] keyblock Send subkey
5642 * This function creates a keyblock containing the send subkey from @a
5643 * auth_context. Use krb5_free_keyblock() to free @a keyblock when it is no
5646 * @retval 0 Success; otherwise - Kerberos error codes
5648 krb5_error_code KRB5_CALLCONV
5649 krb5_auth_con_getsendsubkey(krb5_context ctx, krb5_auth_context ac, krb5_keyblock **keyblock);
5652 * Retrieve the send subkey from an auth context.
5654 * @param [in] ctx Library context
5655 * @param [in] ac Authentication context
5656 * @param [out] key Send subkey
5658 * This function sets @a key to the send subkey from @a auth_context. Use
5659 * krb5_k_free_key() to release @a key when it is no longer needed.
5661 * @retval 0 Success; otherwise - Kerberos error codes
5663 krb5_error_code KRB5_CALLCONV
5664 krb5_auth_con_getsendsubkey_k(krb5_context ctx, krb5_auth_context ac,
5668 * Retrieve the receiving subkey from an auth context as a keyblock.
5670 * @param [in] ctx Library context
5671 * @param [in] ac Authentication context
5672 * @param [out] keyblock Receiving subkey
5674 * This function creates a keyblock containing the receiving subkey from @a
5675 * auth_context. Use krb5_free_keyblock() to free @a keyblock when it is no
5678 * @retval 0 Success; otherwise - Kerberos error codes
5680 krb5_error_code KRB5_CALLCONV
5681 krb5_auth_con_getrecvsubkey(krb5_context ctx, krb5_auth_context ac, krb5_keyblock **keyblock);
5684 * Retrieve the receiving subkey from an auth context as a keyblock.
5686 * @param [in] ctx Library context
5687 * @param [in] ac Authentication context
5688 * @param [out] key Receiving subkey
5690 * This function sets @a key to the receiving subkey from @a auth_context. Use
5691 * krb5_k_free_key() to release @a key when it is no longer needed.
5693 * @retval 0 Success; otherwise - Kerberos error codes
5695 krb5_error_code KRB5_CALLCONV
5696 krb5_auth_con_getrecvsubkey_k(krb5_context ctx, krb5_auth_context ac, krb5_key *key);
5699 * Set the send subkey in an auth context with a keyblock.
5701 * @param [in] ctx Library context
5702 * @param [in] ac Authentication context
5703 * @param [in] keyblock Send subkey
5705 * This function sets the send subkey in @a ac to a copy of @a keyblock.
5707 * @retval 0 Success. Otherwise - Kerberos error codes
5709 krb5_error_code KRB5_CALLCONV
5710 krb5_auth_con_setsendsubkey(krb5_context ctx, krb5_auth_context ac,
5711 krb5_keyblock *keyblock);
5714 * Set the send subkey in an auth context.
5716 * @param [in] ctx Library context
5717 * @param [in] ac Authentication context
5718 * @param [out] key Send subkey
5720 * This function sets the send subkey in @a ac to @a key, incrementing its
5723 * @version First introduced in 1.9
5725 * @retval 0 Success; otherwise - Kerberos error codes
5727 krb5_error_code KRB5_CALLCONV
5728 krb5_auth_con_setsendsubkey_k(krb5_context ctx, krb5_auth_context ac, krb5_key key);
5731 * Set the receiving subkey in an auth context with a keyblock.
5733 * @param [in] ctx Library context
5734 * @param [in] ac Authentication context
5735 * @param [in] keyblock Receiving subkey
5737 * This function sets the receiving subkey in @a ac to a copy of @a keyblock.
5739 * @retval 0 Success; otherwise - Kerberos error codes
5741 krb5_error_code KRB5_CALLCONV
5742 krb5_auth_con_setrecvsubkey(krb5_context ctx, krb5_auth_context ac,
5743 krb5_keyblock *keyblock);
5746 * Set the receiving subkey in an auth context.
5748 * @param [in] ctx Library context
5749 * @param [in] ac Authentication context
5750 * @param [in] key Receiving subkey
5752 * This function sets the receiving subkey in @a ac to @a key, incrementing its
5755 * @version First introduced in 1.9
5757 * @retval 0 Success; otherwise - Kerberos error codes
5759 krb5_error_code KRB5_CALLCONV
5760 krb5_auth_con_setrecvsubkey_k(krb5_context ctx, krb5_auth_context ac,
5764 /** @deprecated Replaced by krb5_auth_con_getsendsubkey(). */
5765 KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
5766 krb5_auth_con_getlocalsubkey(krb5_context context, krb5_auth_context auth_context,
5767 krb5_keyblock **keyblock);
5769 /** @deprecated Replaced by krb5_auth_con_getrecvsubkey(). */
5770 KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
5771 krb5_auth_con_getremotesubkey(krb5_context context, krb5_auth_context auth_context,
5772 krb5_keyblock **keyblock);
5776 * Retrieve the local sequence number from an auth context.
5778 * @param [in] context Library context
5779 * @param [in] auth_context Authentication context
5780 * @param [out] seqnumber Local sequence number
5782 * Retrieve the local sequence number from @a auth_context and return it in @a
5783 * seqnumber. The #KRB5_AUTH_CONTEXT_DO_SEQUENCE flag must be set in @a
5784 * auth_context for this function to be useful.
5786 * @retval 0 Success; otherwise - Kerberos error codes
5788 krb5_error_code KRB5_CALLCONV
5789 krb5_auth_con_getlocalseqnumber(krb5_context context, krb5_auth_context auth_context,
5790 krb5_int32 *seqnumber);
5793 * Retrieve the remote sequence number from an auth context.
5795 * @param [in] context Library context
5796 * @param [in] auth_context Authentication context
5797 * @param [out] seqnumber Remote sequence number
5799 * Retrieve the remote sequence number from @a auth_context and return it in @a
5800 * seqnumber. The #KRB5_AUTH_CONTEXT_DO_SEQUENCE flag must be set in @a
5801 * auth_context for this function to be useful.
5803 * @retval 0 Success; otherwise - Kerberos error codes
5805 krb5_error_code KRB5_CALLCONV
5806 krb5_auth_con_getremoteseqnumber(krb5_context context, krb5_auth_context auth_context,
5807 krb5_int32 *seqnumber);
5810 /** @deprecated Not replaced.
5812 * RFC 4120 doesn't have anything like the initvector concept;
5813 * only really old protocols may need this API.
5815 KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
5816 krb5_auth_con_initivector(krb5_context context, krb5_auth_context auth_context);
5820 * Set the replay cache in an auth context.
5822 * @param [in] context Library context
5823 * @param [in] auth_context Authentication context
5824 * @param [in] rcache Replay cache haddle
5826 * This function sets the replay cache in @a auth_context to @a rcache. @a
5827 * rcache will be closed when @a auth_context is freed, so the caller should
5828 * relinguish that responsibility.
5830 * @retval 0 Success; otherwise - Kerberos error codes
5832 krb5_error_code KRB5_CALLCONV
5833 krb5_auth_con_setrcache(krb5_context context, krb5_auth_context auth_context,
5834 krb5_rcache rcache);
5837 * Retrieve the replay cache from an auth context.
5839 * @param [in] context Library context
5840 * @param [in] auth_context Authentication context
5841 * @param [out] rcache Replay cache handle
5843 * This function fetches the replay cache from @a auth_context. The caller
5844 * should not close @a rcache.
5846 * @retval 0 (always)
5848 krb5_error_code KRB5_CALLCONV_WRONG
5849 krb5_auth_con_getrcache(krb5_context context, krb5_auth_context auth_context,
5850 krb5_rcache *rcache);
5853 * Retrieve the authenticator from an auth context.
5855 * @param [in] context Library context
5856 * @param [in] auth_context Authentication context
5857 * @param [out] authenticator Authenticator
5859 * Use krb5_free_authenticator() to free @a authenticator when it is no longer
5862 * @retval 0 Success. Otherwise - Kerberos error codes
5864 krb5_error_code KRB5_CALLCONV
5865 krb5_auth_con_getauthenticator(krb5_context context, krb5_auth_context auth_context,
5866 krb5_authenticator **authenticator);
5869 * Set checksum type in an an auth context.
5871 * @param [in] context Library context
5872 * @param [in] auth_context Authentication context
5873 * @param [in] cksumtype Checksum type
5875 * This function sets the checksum type in @a auth_context to be used by
5876 * krb5_mk_req() for the authenticator checksum.
5878 * @retval 0 Success. Otherwise - Kerberos error codes
5880 krb5_error_code KRB5_CALLCONV
5881 krb5_auth_con_set_req_cksumtype(krb5_context context, krb5_auth_context auth_context,
5882 krb5_cksumtype cksumtype);
5884 #define KRB5_REALM_BRANCH_CHAR '.'
5887 * end "func-proto.h"
5891 * begin stuff from libos.h
5895 * @brief Read a password from keyboard input.
5897 * @param [in] context Library context
5898 * @param [in] prompt First user prompt when reading password
5899 * @param [in] prompt2 Second user prompt (NULL to prompt only once)
5900 * @param [out] return_pwd Returned password
5901 * @param [in,out] size_return On input, maximum size of password; on output,
5902 * size of password read
5904 * This function reads a password from keyboard input and stores it in @a
5905 * return_pwd. @a size_return should be set by the caller to the amount of
5906 * storage space available in @a return_pwd; on successful return, it will be
5907 * set to the length of the password read.
5909 * @a prompt is printed to the terminal, followed by ": ", and then a password
5910 * is read from the keyboard.
5912 * If @a prompt2 is NULL, the password is read only once. Otherwise, @a
5913 * prompt2 is printed to the terminal and a second password is read. If the
5914 * two passwords entered are not identical, KRB5_LIBOS_BADPWDMATCH is returned.
5916 * Echoing is turned off when the password is read.
5921 * Error in reading or verifying the password
5923 * Kerberos error codes
5925 krb5_error_code KRB5_CALLCONV
5926 krb5_read_password(krb5_context context,
5927 const char *prompt, const char *prompt2,
5928 char *return_pwd, unsigned int *size_return);
5931 * Convert a principal name to a local name.
5933 * @param [in] context Library context
5934 * @param [in] aname Principal name
5935 * @param [in] lnsize_in Space available in @a lname
5936 * @param [out] lname Local name buffer to be filled in
5938 * If @a aname does not correspond to any local account, KRB5_LNAME_NOTRANS is
5939 * returned. If @a lnsize_in is too small for the local name,
5940 * KRB5_CONFIG_NOTENUFSPACE is returned.
5942 * Local names, rather than principal names, can be used by programs that
5943 * translate to an environment-specific name (for example, a user account
5951 * Kerberos error codes
5953 krb5_error_code KRB5_CALLCONV
5954 krb5_aname_to_localname(krb5_context context, krb5_const_principal aname,
5955 int lnsize_in, char *lname);
5958 * Get the Kerberos realm names for a host.
5960 * @param [in] context Library context
5961 * @param [in] host Host name (or NULL)
5962 * @param [out] realmsp Null-terminated list of realm names
5964 * Fill in @a realmsp with a pointer to a null-terminated list of realm names.
5965 * If there are no known realms for the host, a list containing the referral
5966 * (empty) realm is returned.
5968 * If @a host is NULL, the local host's realms are determined.
5970 * Use krb5_free_host_realm() to release @a realmsp when it is no longer
5976 * ENOMEM Insufficient memory
5978 * Kerberos error codes
5980 krb5_error_code KRB5_CALLCONV
5981 krb5_get_host_realm(krb5_context context, const char *host, char ***realmsp);
5985 * @param [in] context Library context
5986 * @param [in] hdata Host name (or NULL)
5987 * @param [out] realmsp Null-terminated list of realm names
5989 * Fill in @a realmsp with a pointer to a null-terminated list of realm names
5990 * obtained through heuristics or insecure resolution methods which have lower
5991 * priority than KDC referrals.
5993 * If @a host is NULL, the local host's realms are determined.
5995 * Use krb5_free_host_realm() to release @a realmsp when it is no longer
5998 krb5_error_code KRB5_CALLCONV
5999 krb5_get_fallback_host_realm(krb5_context context,
6000 krb5_data *hdata, char ***realmsp);
6003 * Free the memory allocated by krb5_get_host_realm().
6005 * @param [in] context Library context
6006 * @param [in] realmlist List of realm names to be released
6011 * Kerberos error codes
6013 krb5_error_code KRB5_CALLCONV
6014 krb5_free_host_realm(krb5_context context, char *const *realmlist);
6017 * Determine if a principal is authorized to log in as a local user.
6019 * @param [in] context Library context
6020 * @param [in] principal Principal name
6021 * @param [in] luser Local username
6023 * Determine whether @a principal is authorized to log in as a local user @a
6027 * TRUE Principal is authorized to log in as user; FALSE otherwise.
6029 krb5_boolean KRB5_CALLCONV
6030 krb5_kuserok(krb5_context context, krb5_principal principal, const char *luser);
6033 * Generate auth context addresses from a connected socket.
6035 * @param [in] context Library context
6036 * @param [in] auth_context Authentication context
6037 * @param [in] infd Connected socket descriptor
6038 * @param [in] flags Flags
6040 * This function sets the local and/or remote addresses in @a auth_context
6041 * based on the local and remote endpoints of the socket @a infd. The
6042 * following flags determine the operations performed:
6044 * @li #KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR Generate local address.
6045 * @li #KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR Generate remote address.
6046 * @li #KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR Generate local address and port.
6047 * @li #KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR Generate remote address and port.
6049 * @retval 0 Success; otherwise - Kerberos error codes
6051 krb5_error_code KRB5_CALLCONV
6052 krb5_auth_con_genaddrs(krb5_context context, krb5_auth_context auth_context,
6053 int infd, int flags);
6056 * Set time offset field in a krb5_context structure.
6058 * @param [in] context Library context
6059 * @param [in] seconds Real time, seconds portion
6060 * @param [in] microseconds Real time, microseconds portion
6062 * This function sets the time offset in @a context to the difference between
6063 * the system time and the real time as determined by @a seconds and @a
6066 * @retval 0 Success; otherwise - Kerberos error codes
6068 krb5_error_code KRB5_CALLCONV
6069 krb5_set_real_time(krb5_context context, krb5_timestamp seconds,
6070 krb5_int32 microseconds);
6073 * Return the time offsets from the os context.
6075 * @param [in] context Library context
6076 * @param [out] seconds Time offset, seconds portion
6077 * @param [out] microseconds Time offset, microseconds portion
6079 * This function returns the time offsets in @a context.
6081 * @retval 0 Success; otherwise - Kerberos error codes
6083 krb5_error_code KRB5_CALLCONV
6084 krb5_get_time_offsets(krb5_context context, krb5_timestamp *seconds, krb5_int32 *microseconds);
6088 * Convert a string to an encryption type.
6090 * @param [in] string String to convert to an encryption type
6091 * @param [out] enctypep Encryption type
6093 * @retval 0 Success; otherwise - EINVAL
6095 krb5_error_code KRB5_CALLCONV
6096 krb5_string_to_enctype(char *string, krb5_enctype *enctypep);
6099 * Convert a string to a salt type.
6101 * @param [in] string String to convert to an encryption type
6102 * @param [out] salttypep Salt type to be filled in
6104 * @retval 0 Success; otherwise - EINVAL
6106 krb5_error_code KRB5_CALLCONV
6107 krb5_string_to_salttype(char *string, krb5_int32 *salttypep);
6110 * Convert a string to a checksum type.
6112 * @param [in] string String to be converted
6113 * @param [out] cksumtypep Checksum type to be filled in
6115 * @retval 0 Success; otherwise - EINVAL
6117 krb5_error_code KRB5_CALLCONV
6118 krb5_string_to_cksumtype(char *string, krb5_cksumtype *cksumtypep);
6121 * Convert a string to a timestamp.
6123 * @param [in] string String to be converted
6124 * @param [out] timestampp Pointer to timestamp
6126 * @retval 0 Success; otherwise - EINVAL
6128 krb5_error_code KRB5_CALLCONV
6129 krb5_string_to_timestamp(char *string, krb5_timestamp *timestampp);
6132 * Convert a string to a delta time value.
6134 * @param [in] string String to be converted
6135 * @param [out] deltatp Delta time to be filled in
6137 * @retval 0 Success; otherwise - KRB5_DELTAT_BADFORMAT
6139 krb5_error_code KRB5_CALLCONV
6140 krb5_string_to_deltat(char *string, krb5_deltat *deltatp);
6143 * Convert an encryption type to a string.
6145 * @param [in] enctype Encryption type
6146 * @param [out] buffer Buffer to hold encryption type string
6147 * @param [in] buflen Storage available in @a buffer
6149 * @retval 0 Success; otherwise - Kerberos error codes
6151 krb5_error_code KRB5_CALLCONV
6152 krb5_enctype_to_string(krb5_enctype enctype, char *buffer, size_t buflen);
6155 * Convert an encryption type to a name or alias.
6157 * @param [in] enctype Encryption type
6158 * @param [in] shortest Flag
6159 * @param [out] buffer Buffer to hold encryption type string
6160 * @param [in] buflen Storage available in @a buffer
6162 * If @a shortest is FALSE, this function returns the enctype's canonical name
6163 * (like "aes128-cts-hmac-sha1-96"). If @a shortest is TRUE, it return the
6164 * enctype's shortest alias (like "aes128-cts").
6166 * @version First introduced in 1.9
6168 * @retval 0 Success; otherwise - Kerberos error codes
6170 krb5_error_code KRB5_CALLCONV
6171 krb5_enctype_to_name(krb5_enctype enctype, krb5_boolean shortest,
6172 char *buffer, size_t buflen);
6175 * Convert a salt type to a string.
6177 * @param [in] salttype Salttype to convert
6178 * @param [out] buffer Buffer to receive the converted string
6179 * @param [in] buflen Storage available in @a buffer
6181 * @retval 0 Success; otherwise - Kerberos error codes
6183 krb5_error_code KRB5_CALLCONV
6184 krb5_salttype_to_string(krb5_int32 salttype, char *buffer, size_t buflen);
6187 * Convert a checksum type to a string.
6189 * @param [in] cksumtype Checksum type
6190 * @param [out] buffer Buffer to hold converted checksum type
6191 * @param [in] buflen Storage available in @a buffer
6193 * @retval 0 Success; otherwise - Kerberos error codes
6195 krb5_error_code KRB5_CALLCONV
6196 krb5_cksumtype_to_string(krb5_cksumtype cksumtype, char *buffer, size_t buflen);
6199 * Convert a timestamp to a string.
6201 * @param [in] timestamp Timestamp to convert
6202 * @param [out] buffer Buffer to hold converted timestamp
6203 * @param [in] buflen Storage available in @a buffer
6205 * The string is returned in the locale's appropriate date and time
6208 * @retval 0 Success; otherwise - Kerberos error codes
6210 krb5_error_code KRB5_CALLCONV
6211 krb5_timestamp_to_string(krb5_timestamp timestamp, char *buffer, size_t buflen);
6214 * Convert a timestamp to a string, with optional output padding
6216 * @param [in] timestamp Timestamp to convert
6217 * @param [out] buffer Buffer to hold the converted timestamp
6218 * @param [in] buflen Length of buffer
6219 * @param [in] pad Optional value to pad @a buffer if converted
6220 * timestamp does not fill it
6222 * If @a pad is not NULL, @a buffer is padded out to @a buflen - 1 characters
6223 * with the value of *@a pad.
6225 * @retval 0 Success; otherwise - Kerberos error codes
6227 krb5_error_code KRB5_CALLCONV
6228 krb5_timestamp_to_sfstring(krb5_timestamp timestamp, char *buffer,
6229 size_t buflen, char *pad);
6232 * Convert a relative time value to a string.
6234 * @param [in] deltat Relative time value to convert
6235 * @param [out] buffer Buffer to hold time string
6236 * @param [in] buflen Storage available in @a buffer
6238 * @retval 0 Success; otherwise - Kerberos error codes
6240 krb5_error_code KRB5_CALLCONV
6241 krb5_deltat_to_string(krb5_deltat deltat, char *buffer, size_t buflen);
6243 /* The name of the Kerberos ticket granting service... and its size */
6244 #define KRB5_TGS_NAME "krbtgt"
6245 #define KRB5_TGS_NAME_SIZE 6
6247 /* flags for recvauth */
6248 #define KRB5_RECVAUTH_SKIP_VERSION 0x0001
6249 #define KRB5_RECVAUTH_BADAUTHVERS 0x0002
6250 /* initial ticket api functions */
6252 /** Text for prompt used in prompter callback function. */
6253 typedef struct _krb5_prompt {
6254 char *prompt; /**< The prompt to show to the user */
6255 int hidden; /**< Boolean; informative prompt or hidden (e.g. PIN) */
6256 krb5_data *reply; /**< Must be allocated before call to prompt routine */
6259 /** Pointer to a prompter callback function. */
6260 typedef krb5_error_code
6261 (KRB5_CALLCONV *krb5_prompter_fct)(krb5_context context, void *data,
6262 const char *name, const char *banner,
6263 int num_prompts, krb5_prompt prompts[]);
6266 * Prompt user for password.
6268 * @param [in] context Library context
6269 * @param data Unused (callback argument)
6270 * @param [in] name Name to output during prompt
6271 * @param [in] banner Banner to output during prompt
6272 * @param [in] num_prompts Number of prompts in @a prompts
6273 * @param [in,out] prompts Array of output prompts and replies
6275 * This function is intended to be used as a prompter callback for
6276 * krb5_get_init_creds_password() or krb5_init_creds_init().
6278 * Writes @a name and @a banner to stdout, each followed by a newline, then
6279 * writes each prompt field in the @a prompts array, followed by ": ", and sets
6280 * the reply field of the entry to a line of input read from stdin. If the
6281 * hidden flag is set for a prompt, then terminal echoing is turned off when
6287 * Kerberos error codes
6290 krb5_error_code KRB5_CALLCONV
6291 krb5_prompter_posix(krb5_context context, void *data, const char *name,
6292 const char *banner, int num_prompts,
6293 krb5_prompt prompts[]);
6295 /** Store options for @c _krb5_get_init_creds */
6296 typedef struct _krb5_get_init_creds_opt {
6298 krb5_deltat tkt_life;
6299 krb5_deltat renew_life;
6302 krb5_enctype *etype_list;
6303 int etype_list_length;
6304 krb5_address **address_list;
6305 krb5_preauthtype *preauth_list;
6306 int preauth_list_length;
6308 } krb5_get_init_creds_opt;
6310 #define KRB5_GET_INIT_CREDS_OPT_TKT_LIFE 0x0001
6311 #define KRB5_GET_INIT_CREDS_OPT_RENEW_LIFE 0x0002
6312 #define KRB5_GET_INIT_CREDS_OPT_FORWARDABLE 0x0004
6313 #define KRB5_GET_INIT_CREDS_OPT_PROXIABLE 0x0008
6314 #define KRB5_GET_INIT_CREDS_OPT_ETYPE_LIST 0x0010
6315 #define KRB5_GET_INIT_CREDS_OPT_ADDRESS_LIST 0x0020
6316 #define KRB5_GET_INIT_CREDS_OPT_PREAUTH_LIST 0x0040
6317 #define KRB5_GET_INIT_CREDS_OPT_SALT 0x0080
6318 #define KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT 0x0100
6319 #define KRB5_GET_INIT_CREDS_OPT_CANONICALIZE 0x0200
6320 #define KRB5_GET_INIT_CREDS_OPT_ANONYMOUS 0x0400
6324 * Allocate a new initial credential options structure.
6326 * @param [in] context Library context
6327 * @param [out] opt New options structure
6329 * This function is the preferred way to create an options structure for
6330 * getting initial credentials, and is required to make use of certain options.
6331 * Use krb5_get_init_creds_opt_free() to free @a opt when it is no longer
6334 * @retval 0 - Success; Kerberos errors otherwise.
6336 krb5_error_code KRB5_CALLCONV
6337 krb5_get_init_creds_opt_alloc(krb5_context context,
6338 krb5_get_init_creds_opt **opt);
6341 * Free initial credential options.
6343 * @param [in] context Library context
6344 * @param [in] opt Options structure to free
6346 * @sa krb5_get_init_creds_opt_alloc()
6349 krb5_get_init_creds_opt_free(krb5_context context,
6350 krb5_get_init_creds_opt *opt);
6352 /** @deprecated Use krb5_get_init_creds_opt_alloc() instead. */
6354 krb5_get_init_creds_opt_init(krb5_get_init_creds_opt *opt);
6357 * Set the ticket lifetime in initial credential options.
6359 * @param [in] opt Options structure
6360 * @param [in] tkt_life Ticket lifetime
6363 krb5_get_init_creds_opt_set_tkt_life(krb5_get_init_creds_opt *opt,
6364 krb5_deltat tkt_life);
6367 * Set the ticket renewal lifetime in initial credential options.
6369 * @param [in] opt Pointer to @a options field
6370 * @param [in] renew_life Ticket renewal lifetime
6373 krb5_get_init_creds_opt_set_renew_life(krb5_get_init_creds_opt *opt,
6374 krb5_deltat renew_life);
6377 * Set or unset the forwardable flag in initial credential options.
6379 * @param [in] opt Options structure
6380 * @param [in] forwardable Whether credentials should be forwardable
6383 krb5_get_init_creds_opt_set_forwardable(krb5_get_init_creds_opt *opt,
6387 * Set or unset the proxiable flag in initial credential options.
6389 * @param [in] opt Options structure
6390 * @param [in] proxiable Whether credentials should be proxiable
6393 krb5_get_init_creds_opt_set_proxiable(krb5_get_init_creds_opt *opt,
6397 * Set or unset the canonicalize flag in initial credential options.
6399 * @param [in] opt Options structure
6400 * @param [in] canonicalize Whether to canonicalize client principal
6403 krb5_get_init_creds_opt_set_canonicalize(krb5_get_init_creds_opt *opt,
6407 * Set or unset the anonymous flag in initial credential options.
6409 * @param [in] opt Options structure
6410 * @param [in] anonymous Whether to make an anonymous request
6412 * This function may be used to request anonymous credentials from the KDC by
6413 * setting @a anonymous to non-zero. Note that anonymous credentials are only
6414 * a request; clients must verify that credentials are anonymous if that is a
6418 krb5_get_init_creds_opt_set_anonymous(krb5_get_init_creds_opt *opt,
6422 * Set allowable encryption types in initial credential options.
6424 * @param [in] opt Options structure
6425 * @param [in] etype_list Array of encryption types
6426 * @param [in] etype_list_length Length of @a etype_list
6429 krb5_get_init_creds_opt_set_etype_list(krb5_get_init_creds_opt *opt,
6430 krb5_enctype *etype_list,
6431 int etype_list_length);
6434 * Set address restrictions in initial credential options.
6436 * @param [in] opt Options structure
6437 * @param [in] addresses Null-terminated array of addresses
6440 krb5_get_init_creds_opt_set_address_list(krb5_get_init_creds_opt *opt,
6441 krb5_address **addresses);
6444 * Set preauthentication types in initial credential options.
6446 * @param [in] opt Options structure
6447 * @param [in] preauth_list Array of preauthentication types
6448 * @param [in] preauth_list_length Length of @a preauth_list
6450 * This function can be used to perform optimistic preauthentication when
6451 * getting initial credentials, in combination with
6452 * krb5_get_init_creds_opt_set_salt() and krb5_get_init_creds_opt_set_pa().
6455 krb5_get_init_creds_opt_set_preauth_list(krb5_get_init_creds_opt *opt,
6456 krb5_preauthtype *preauth_list,
6457 int preauth_list_length);
6460 * Set salt for optimistic preauthentication in initial credential options.
6462 * @param [in] opt Options structure
6463 * @param [in] salt Salt data
6465 * When getting initial credentials with a password, a salt string it used to
6466 * convert the password to a key. Normally this salt is obtained from the
6467 * first KDC reply, but when performing optimistic preauthentication, the
6468 * client may need to supply the salt string with this function.
6471 krb5_get_init_creds_opt_set_salt(krb5_get_init_creds_opt *opt,
6475 * Set or unset change-password-prompt flag in initial credential options.
6477 * @param [in] opt Options structure
6478 * @param [in] prompt Whether to prompt to change password
6480 * This flag is on by default. It controls whether
6481 * krb5_get_init_creds_password() will react to an expired-password error by
6482 * prompting for a new password and attempting to change the old one.
6485 krb5_get_init_creds_opt_set_change_password_prompt(krb5_get_init_creds_opt *opt,
6488 /** Generic preauth option attribute/value pairs */
6489 typedef struct _krb5_gic_opt_pa_data {
6492 } krb5_gic_opt_pa_data;
6495 * Supply options for preauthentication in initial credential options.
6497 * @param [in] context Library context
6498 * @param [in] opt Options structure
6499 * @param [in] attr Preauthentication option name
6500 * @param [in] value Preauthentication option value
6502 * This function allows the caller to supply options for preauthentication.
6503 * The values of @a attr and @a value are supplied to each preauthentication
6504 * module available within @a context.
6506 krb5_error_code KRB5_CALLCONV
6507 krb5_get_init_creds_opt_set_pa(krb5_context context,
6508 krb5_get_init_creds_opt *opt, const char *attr,
6512 * Set location of FAST armor ccache in initial credential options.
6514 * @param [in] context Library context
6515 * @param [in] opt Options
6516 * @param [in] fast_ccache_name Credential cache name
6518 * Sets the location of a credential cache containing an armor ticket to
6519 * protect an initial credential exchange using the FAST protocol extension.
6521 * In version 1.7, setting an armor ccache requires that FAST be used for the
6522 * exchange. In version 1.8 or later, setting the armor ccache causes FAST to
6523 * be used if the KDC supports it; krb5_get_init_creds_opt_set_fast_flags()
6524 * must be used to require that FAST be used.
6526 krb5_error_code KRB5_CALLCONV
6527 krb5_get_init_creds_opt_set_fast_ccache_name(krb5_context context,
6528 krb5_get_init_creds_opt *opt,
6529 const char *fast_ccache_name);
6532 * Set FAST armor cache in initial credential options.
6534 * @param [in] context Library context
6535 * @param [in] opt Options
6536 * @param [in] ccache Credential cache handle
6538 * This function is similar to krb5_get_init_creds_opt_set_fast_ccache_name(),
6539 * but uses a credential cache handle instead of a name.
6541 * @version First introduced in 1.9
6543 krb5_error_code KRB5_CALLCONV
6544 krb5_get_init_creds_opt_set_fast_ccache(krb5_context context,
6545 krb5_get_init_creds_opt *opt,
6546 krb5_ccache ccache);
6549 * Set an output credential cache in initial credential options.
6551 * @param [in] context Library context
6552 * @param [in] opt Options
6553 * @param [in] ccache Credential cache handle
6555 * If an output credential cache is set, then the krb5_get_init_creds family of
6556 * APIs will write credentials to it. Setting an output ccache is desirable
6557 * both because it simplifies calling code and because it permits the
6558 * krb5_get_init_creds APIs to write out configuration information about the
6559 * realm to the ccache.
6561 krb5_error_code KRB5_CALLCONV
6562 krb5_get_init_creds_opt_set_out_ccache(krb5_context context,
6563 krb5_get_init_creds_opt *opt,
6564 krb5_ccache ccache);
6567 * Set FAST flags in initial credential options.
6569 * @param [in] context Library context
6570 * @param [in] opt Options
6571 * @param [in] flags FAST flags
6573 * The following flag values are valid:
6574 * @li #KRB5_FAST_REQUIRED - Require FAST to be used
6577 * 0 - Success; Kerberos errors otherwise.
6579 krb5_error_code KRB5_CALLCONV
6580 krb5_get_init_creds_opt_set_fast_flags(krb5_context context,
6581 krb5_get_init_creds_opt *opt,
6585 * Retrieve FAST flags from initial credential options.
6587 * @param [in] context Library context
6588 * @param [in] opt Options
6589 * @param [out] out_flags FAST flags
6592 * 0 - Success; Kerberos errors otherwise.
6594 krb5_error_code KRB5_CALLCONV
6595 krb5_get_init_creds_opt_get_fast_flags(krb5_context context,
6596 krb5_get_init_creds_opt *opt,
6597 krb5_flags *out_flags);
6600 #define KRB5_FAST_REQUIRED 1l<<0 /**< Require KDC to support FAST*/
6603 (KRB5_CALLCONV *krb5_expire_callback_func)(krb5_context context, void *data,
6604 krb5_timestamp password_expiration,
6605 krb5_timestamp account_expiration,
6606 krb5_boolean is_last_req);
6609 * Set an expiration callback in initial credential options.
6611 * @param [in] context Library context
6612 * @param [in] opt Options structure
6613 * @param [in] cb Callback function
6614 * @param [in] data Callback argument
6616 * Set a callback to receive password and account expiration times.
6618 * This option only applies to krb5_get_init_creds_password(). @a cb will be
6619 * invoked if and only if credentials are successfully acquired. The callback
6620 * will receive the @a context from the krb5_get_init_creds_password() call and
6621 * the @a data argument supplied with this API. The remaining arguments should
6622 * be interpreted as follows:
6624 * If @a is_last_req is true, then the KDC reply contained last-req entries
6625 * which unambiguously indicated the password expiration, account expiration,
6626 * or both. (If either value was not present, the corresponding argument will
6627 * be 0.) Furthermore, a non-zero @a password_expiration should be taken as a
6628 * suggestion from the KDC that a warning be displayed.
6630 * If @a is_last_req is false, then @a account_expiration will be 0 and @a
6631 * password_expiration will contain the expiration time of either the password
6632 * or account, or 0 if no expiration time was indicated in the KDC reply. The
6633 * callback should independently decide whether to display a password
6634 * expiration warning.
6636 * Note that @a cb may be invoked even if credentials are being acquired for
6637 * the kadmin/changepw service in order to change the password. It is the
6638 * caller's responsibility to avoid displaying a password expiry warning in
6641 * @warning Setting an expire callback with this API will cause
6642 * krb5_get_init_creds_password() not to send password expiry warnings to the
6643 * prompter, as it ordinarily may.
6645 * @version First introduced in 1.9
6647 krb5_error_code KRB5_CALLCONV
6648 krb5_get_init_creds_opt_set_expire_callback(krb5_context context,
6649 krb5_get_init_creds_opt *opt,
6650 krb5_expire_callback_func cb,
6654 * Get initial credentials using a password.
6656 * @param [in] context Library context
6657 * @param [out] creds New credentials
6658 * @param [in] client Client principal
6659 * @param [in] password Password (or NULL)
6660 * @param [in] prompter Prompter function
6661 * @param [in] data Prompter callback data
6662 * @param [in] start_time Time when ticket becomes valid (0 for now)
6663 * @param [in] in_tkt_service Service name of initial credentials (or NULL)
6664 * @param [in] k5_gic_options Initial credential options
6666 * This function requests KDC for an initial credentials for @a client using @a
6667 * password. If @a password is NULL, a password will be prompted for using @a
6668 * prompter if necessary. If @a in_tkt_service is specified, it is parsed as a
6669 * principal name (with the realm ignored) and used as the service principal
6670 * for the request; otherwise the ticket-granting service is used.
6672 * @sa krb5_verify_init_creds()
6677 * EINVAL Invalid argument
6679 * KRB5_KDC_UNREACH Cannot contact any KDC for requested realm
6681 * KRB5_PREAUTH_FAILED Generic Pre-athentication failure
6683 * KRB5_LIBOS_PWDINTR Password read interrupted
6685 * KRB5_REALM_CANT_RESOLVE Cannot resolve network address for KDC in requested realm
6687 * KRB5KDC_ERR_KEY_EXP Password has expired
6689 * KRB5_LIBOS_BADPWDMATCH Password mismatch
6691 * KRB5_CHPW_PWDNULL New password cannot be zero length
6693 * KRB5_CHPW_FAIL Password change failed
6695 * Kerberos error codes
6697 krb5_error_code KRB5_CALLCONV
6698 krb5_get_init_creds_password(krb5_context context, krb5_creds *creds,
6699 krb5_principal client, const char *password,
6700 krb5_prompter_fct prompter, void *data,
6701 krb5_deltat start_time,
6702 const char *in_tkt_service,
6703 krb5_get_init_creds_opt *k5_gic_options);
6705 struct _krb5_init_creds_context;
6706 typedef struct _krb5_init_creds_context *krb5_init_creds_context;
6708 #define KRB5_INIT_CREDS_STEP_FLAG_CONTINUE 0x1 /**< More responses needed */
6711 * Free an initial credentials context.
6713 * @param [in] context Library context
6714 * @param [in] ctx Initial credentials context
6717 krb5_init_creds_free(krb5_context context, krb5_init_creds_context ctx);
6720 * Acquire credentials using an initial credentials context.
6722 * @param [in] context Library context
6723 * @param [in] ctx Initial credentials context
6725 * This function synchronously obtains credentials using a context created by
6726 * krb5_init_creds_init(). On successful return, the credentials can be
6727 * retrieved with krb5_init_creds_get_creds().
6729 * @retval 0 Success; otherwise - Kerberos error codes
6731 krb5_error_code KRB5_CALLCONV
6732 krb5_init_creds_get(krb5_context context, krb5_init_creds_context ctx);
6735 * Retrieve acquired credentials from an initial credentials context.
6737 * @param [in] context Library context
6738 * @param [in] ctx Initial credentials context
6739 * @param [out] creds Acquired credentials
6741 * This function copies the acquired initial credentials from @a ctx into @a
6742 * creds, after the successful completion of krb5_init_creds_get() or
6743 * krb5_init_creds_step(). Use krb5_free_cred_contents() to free @a creds when
6744 * it is no longer needed.
6746 * @retval 0 Success; otherwise - Kerberos error codes
6748 krb5_error_code KRB5_CALLCONV
6749 krb5_init_creds_get_creds(krb5_context context, krb5_init_creds_context ctx,
6753 * Get the last error from KDC from an initial credentials context.
6755 * @param [in] context Library context
6756 * @param [in] ctx Initial credentials context
6757 * @param [out] error Error from KDC, or NULL if none was received
6759 * @retval 0 Success; otherwise - Kerberos error codes
6761 krb5_error_code KRB5_CALLCONV
6762 krb5_init_creds_get_error(krb5_context context, krb5_init_creds_context ctx,
6763 krb5_error **error);
6766 * Create a context for acquiring initial credentials.
6768 * @param [in] context Library context
6769 * @param [in] client Client principal to get initial creds for
6770 * @param [in] prompter Prompter callback
6771 * @param [in] data Prompter callback argument
6772 * @param [in] start_time Time when credentials become valid (0 for now)
6773 * @param [in] options Options structure (NULL for default)
6774 * @param [out] ctx New initial credentials context
6776 * This function creates a new context for acquiring initial credentials. Use
6777 * krb5_init_creds_free() to free @a ctx when it is no longer needed.
6779 * @retval 0 Success; otherwise - Kerberos error codes
6781 krb5_error_code KRB5_CALLCONV
6782 krb5_init_creds_init(krb5_context context, krb5_principal client,
6783 krb5_prompter_fct prompter, void *data,
6784 krb5_deltat start_time, krb5_get_init_creds_opt *options,
6785 krb5_init_creds_context *ctx);
6788 * Specify a keytab to use for acquiring initial credentials.
6790 * @param [in] context Library context
6791 * @param [in] ctx Initial credentials context
6792 * @param [in] keytab Key table handle
6794 * This function supplies a keytab containing the client key for an initial
6795 * credentials request.
6797 * @retval 0 Success; otherwise - Kerberos error codes
6799 krb5_error_code KRB5_CALLCONV
6800 krb5_init_creds_set_keytab(krb5_context context, krb5_init_creds_context ctx,
6801 krb5_keytab keytab);
6804 * Get the next KDC request for acquiring initial credentials.
6806 * @param [in] context Library context
6807 * @param [in] ctx Initial credentials context
6808 * @param [in] in KDC response (empty on the first call)
6809 * @param [out] out Next KDC request
6810 * @param [out] realm Realm for next KDC request
6811 * @param [out] flags Output flags
6813 * This function constructs the next KDC request in an initial credential
6814 * exchange, allowing the caller to control the transport of KDC requests and
6815 * replies. On the first call, @a in should be set to an empty buffer; on
6816 * subsequent calls, it should be set to the KDC's reply to the previous
6819 * If more requests are needed, @a flags will be set to
6820 * #KRB5_INIT_CREDS_STEP_FLAG_CONTINUE and the next request will be placed in
6821 * @a out. If no more requests are needed, @a flags will not contain
6822 * #KRB5_INIT_CREDS_STEP_FLAG_CONTINUE and @a out will be empty.
6824 * If this function returns @c KRB5KRB_ERR_RESPONSE_TOO_BIG, the caller should
6825 * transmit the next request using TCP rather than UDP. If this function
6826 * returns any other error, the initial credential exchange has failed.
6828 * @retval 0 Success; otherwise - Kerberos error codes
6830 krb5_error_code KRB5_CALLCONV
6831 krb5_init_creds_step(krb5_context context, krb5_init_creds_context ctx,
6832 krb5_data *in, krb5_data *out, krb5_data *realm,
6833 unsigned int *flags);
6836 * Set a password for acquiring initial credentials.
6838 * @param [in] context Library context
6839 * @param [in] ctx Initial credentials context
6840 * @param [in] password Password
6842 * This function supplies a password to be used to construct the client key for
6843 * an initial credentials request.
6845 * @retval 0 Success; otherwise - Kerberos error codes
6847 krb5_error_code KRB5_CALLCONV
6848 krb5_init_creds_set_password(krb5_context context, krb5_init_creds_context ctx,
6849 const char *password);
6852 * Specify a service principal for acquiring initial credentials.
6854 * @param [in] context Library context
6855 * @param [in] ctx Initial credentials context
6856 * @param [in] service Service principal string
6858 * This function supplies a service principal string to acquire initial
6859 * credentials for instead of the default krbtgt service. @a service is parsed
6860 * as a principal name; any realm part is ignored.
6862 * @retval 0 Success; otherwise - Kerberos error codes
6864 krb5_error_code KRB5_CALLCONV
6865 krb5_init_creds_set_service(krb5_context context, krb5_init_creds_context ctx,
6866 const char *service);
6869 * Retrieve ticket times from an initial credentials context.
6871 * @param [in] context Library context
6872 * @param [in] ctx Initial credentials context
6873 * @param [out] times Ticket times for acquired credentials
6875 * The initial credentials context must have completed obtaining credentials
6876 * via either krb5_init_creds_get() or krb5_init_creds_step().
6878 * @retval 0 Success; otherwise - Kerberos error codes
6880 krb5_error_code KRB5_CALLCONV
6881 krb5_init_creds_get_times(krb5_context context, krb5_init_creds_context ctx,
6882 krb5_ticket_times *times);
6884 struct _krb5_tkt_creds_context;
6885 typedef struct _krb5_tkt_creds_context *krb5_tkt_creds_context;
6888 * Create a context to get credentials from a KDC's Ticket Granting Service.
6890 * @param[in] context Library context
6891 * @param[in] ccache Credential cache handle
6892 * @param[in] creds Input credentials
6893 * @param[in] options @ref KRB5_GC options for this request.
6894 * @param[out] ctx New TGS request context
6896 * This function prepares to obtain credentials matching @a creds, either by
6897 * retrieving them from @a ccache or by making requests to ticket-granting
6898 * services beginning with a ticket-granting ticket for the client principal's
6901 * The resulting TGS acquisition context can be used asynchronously with
6902 * krb5_tkt_creds_step() or synchronously with krb5_tkt_creds_get(). See also
6903 * krb5_get_credentials() for synchronous use.
6905 * Use krb5_tkt_creds_free() to free @a ctx when it is no longer needed.
6907 * @version First introduced in 1.9
6909 * @retval 0 Success; otherwise - Kerberos error codes
6911 krb5_error_code KRB5_CALLCONV
6912 krb5_tkt_creds_init(krb5_context context, krb5_ccache ccache,
6913 krb5_creds *creds, krb5_flags options,
6914 krb5_tkt_creds_context *ctx);
6917 * Synchronously obtain credentials using a TGS request context.
6919 * @param[in] context Library context
6920 * @param[in] ctx TGS request context
6922 * This function synchronously obtains credentials using a context created by
6923 * krb5_tkt_creds_init(). On successful return, the credentials can be
6924 * retrieved with krb5_tkt_creds_get_creds().
6926 * @version First introduced in 1.9
6928 * @retval 0 Success; otherwise - Kerberos error codes
6930 krb5_error_code KRB5_CALLCONV
6931 krb5_tkt_creds_get(krb5_context context, krb5_tkt_creds_context ctx);
6934 * Retrieve acquired credentials from a TGS request context.
6936 * @param[in] context Library context
6937 * @param[in] ctx TGS request context
6938 * @param[out] creds Acquired credentials
6940 * This function copies the acquired initial credentials from @a ctx into @a
6941 * creds, after the successful completion of krb5_tkt_creds_get() or
6942 * krb5_tkt_creds_step(). Use krb5_free_cred_contents() to free @a creds when
6943 * it is no longer needed.
6945 * @version First introduced in 1.9
6947 * @retval 0 Success; otherwise - Kerberos error codes
6949 krb5_error_code KRB5_CALLCONV
6950 krb5_tkt_creds_get_creds(krb5_context context, krb5_tkt_creds_context ctx,
6954 * Free a TGS request context.
6956 * @param[in] context Library context
6957 * @param[in] ctx TGS request context
6959 * @version First introduced in 1.9
6962 krb5_tkt_creds_free(krb5_context context, krb5_tkt_creds_context ctx);
6964 #define KRB5_TKT_CREDS_STEP_FLAG_CONTINUE 0x1 /**< More responses needed */
6967 * Get the next KDC request in a TGS exchange.
6969 * @param[in] context Library context
6970 * @param[in] ctx TGS request context
6971 * @param[in] in KDC response (empty on the first call)
6972 * @param[out] out Next KDC request
6973 * @param[out] realm Realm for next KDC request
6974 * @param[out] flags Output flags
6976 * This function constructs the next KDC request for a TGS exchange, allowing
6977 * the caller to control the transport of KDC requests and replies. On the
6978 * first call, @a in should be set to an empty buffer; on subsequent calls, it
6979 * should be set to the KDC's reply to the previous request.
6981 * If more requests are needed, @a flags will be set to
6982 * #KRB5_TKT_CREDS_STEP_FLAG_CONTINUE and the next request will be placed in @a
6983 * out. If no more requests are needed, @a flags will not contain
6984 * #KRB5_TKT_CREDS_STEP_FLAG_CONTINUE and @a out will be empty.
6986 * If this function returns @c KRB5KRB_ERR_RESPONSE_TOO_BIG, the caller should
6987 * transmit the next request using TCP rather than UDP. If this function
6988 * returns any other error, the TGS exchange has failed.
6990 * @version First introduced in 1.9
6992 * @retval 0 Success; otherwise - Kerberos error codes
6994 krb5_error_code KRB5_CALLCONV
6995 krb5_tkt_creds_step(krb5_context context, krb5_tkt_creds_context ctx,
6996 krb5_data *in, krb5_data *out, krb5_data *realm,
6997 unsigned int *flags);
7000 * Retrieve ticket times from a TGS request context.
7002 * @param[in] context Library context
7003 * @param[in] ctx TGS request context
7004 * @param[out] times Ticket times for acquired credentials
7006 * The TGS request context must have completed obtaining credentials via either
7007 * krb5_tkt_creds_get() or krb5_tkt_creds_step().
7009 * @version First introduced in 1.9
7011 * @retval 0 Success; otherwise - Kerberos error codes
7013 krb5_error_code KRB5_CALLCONV
7014 krb5_tkt_creds_get_times(krb5_context context, krb5_tkt_creds_context ctx,
7015 krb5_ticket_times *times);
7018 * Get initial credentials using a key table.
7020 * @param [in] context Library context
7021 * @param [out] creds New credentials
7022 * @param [in] client Client principal
7023 * @param [in] arg_keytab Key table handle
7024 * @param [in] start_time Time when ticket becomes valid (0 for now)
7025 * @param [in] in_tkt_service Service name of initial credentials (or NLUL)
7026 * @param [in] k5_gic_options Initial credential options
7028 * This function requests KDC for an initial credentials for @a client using a
7029 * client key stored in @a arg_keytab. If @a in_tkt_service is specified, it
7030 * is parsed as a principal name (with the realm ignored) and used as the
7031 * service principal for the request; otherwise the ticket-granting service is
7034 * @sa krb5_verify_init_creds()
7039 * Kerberos error codes
7041 krb5_error_code KRB5_CALLCONV
7042 krb5_get_init_creds_keytab(krb5_context context, krb5_creds *creds,
7043 krb5_principal client, krb5_keytab arg_keytab,
7044 krb5_deltat start_time, const char *in_tkt_service,
7045 krb5_get_init_creds_opt *k5_gic_options);
7047 typedef struct _krb5_verify_init_creds_opt {
7049 int ap_req_nofail; /**< boolean */
7050 } krb5_verify_init_creds_opt;
7052 #define KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL 0x0001
7055 * Initialize a credential verification options structure.
7057 * @param [in] k5_vic_options Verification options structure
7060 krb5_verify_init_creds_opt_init(krb5_verify_init_creds_opt *k5_vic_options);
7063 * Set whether credential verification is required.
7065 * @param [in] k5_vic_options Verification options structure
7066 * @param [in] ap_req_nofail Whether to require successful verification
7068 * This function determines how krb5_verify_init_creds() behaves if no keytab
7069 * information is available. If @a ap_req_nofail is @c FALSE, verification
7070 * will be skipped in this case and krb5_verify_init_creds() will return
7071 * successfully. If @a ap_req_nofail is @c TRUE, krb5_verify_init_creds() will
7072 * not return successfully unless verification can be performed.
7074 * If this function is not used, the behavior of krb5_verify_init_creds() is
7075 * determined through configuration.
7078 krb5_verify_init_creds_opt_set_ap_req_nofail(krb5_verify_init_creds_opt * k5_vic_options,
7082 * Verify initial credentials against a keytab.
7084 * @param [in] context Library context
7085 * @param [in] creds Initial credentials to be verified
7086 * @param [in] server Server principal (or NULL)
7087 * @param [in] keytab Key table (NULL to use default keytab)
7088 * @param [in,out] ccache Credential cache for fetched creds (or NULL)
7089 * @param [in] options Verification options (NULL for default options)
7091 * This function attempts to verify that @a creds were obtained from a KDC with
7092 * knowledge of a key in @a keytab, or the default keytab if @a keytab is NULL.
7093 * If @a server is provided, the highest-kvno key entry for that principal name
7094 * is used to verify the credentials; otherwise, all unique "host" service
7095 * principals in the keytab are tried.
7097 * If the specified keytab does not exist, or is empty, or cannot be read, or
7098 * does not contain an entry for @a server, then credential verification may be
7099 * skipped unless configuration demands that it succeed. The caller can
7100 * control this behavior by providing a verification options structure; see
7101 * krb5_verify_init_creds_opt_init() and
7102 * krb5_verify_init_creds_opt_set_ap_req_nofail().
7104 * If @a ccache is NULL, any additional credentials fetched during the
7105 * verification process will be destroyed. If @a ccache points to NULL, a
7106 * memory ccache will be created for the additional credentials and returned in
7107 * @a ccache. If @a ccache points to a valid credential cache handle, the
7108 * additional credentials will be stored in that cache.
7110 * @retval 0 Success; otherwise - Kerberos error codes
7112 krb5_error_code KRB5_CALLCONV
7113 krb5_verify_init_creds(krb5_context context, krb5_creds *creds,
7114 krb5_principal server, krb5_keytab keytab,
7115 krb5_ccache *ccache,
7116 krb5_verify_init_creds_opt *options);
7119 * Get validated credentials from the KDC.
7121 * @param [in] context Library context
7122 * @param [out] creds Validated credentials
7123 * @param [in] client Client principal name
7124 * @param [in] ccache Credential cache
7125 * @param [in] in_tkt_service Server principal string (or NULL)
7127 * This function gets a validated credential using a postdated credential from
7128 * @a ccache. If @a in_tkt_service is specified, it is parsed (with the realm
7129 * part ignored) and used as the server principal of the credential;
7130 * otherwise, the ticket-granting service is used.
7132 * If successful, the validated credential is placed in @a creds.
7134 * @sa krb5_get_renewed_creds()
7139 * KRB5_NO_2ND_TKT Request missing second ticket
7141 * KRB5_NO_TKT_SUPPLIED Request did not supply a ticket
7143 * KRB5_PRINC_NOMATCH Requested principal and ticket do not match
7145 * KRB5_KDCREP_MODIFIED KDC reply did not match expectations
7147 * KRB5_KDCREP_SKEW Clock skew too great in KDC reply
7149 * Kerberos error codes
7151 krb5_error_code KRB5_CALLCONV
7152 krb5_get_validated_creds(krb5_context context, krb5_creds *creds,
7153 krb5_principal client, krb5_ccache ccache,
7154 const char *in_tkt_service);
7157 * Get renewed credential from KDC using an existing credential.
7159 * @param [in] context Library context
7160 * @param [out] creds Renewed credentials
7161 * @param [in] client Client principal name
7162 * @param [in] ccache Credential cache
7163 * @param [in] in_tkt_service Server principal string (or NULL)
7165 * This function gets a renewed credential using an existing one from @a
7166 * ccache. If @a in_tkt_service is specified, it is parsed (with the realm
7167 * part ignored) and used as the server principal of the credential; otherwise,
7168 * the ticket-granting service is used.
7170 * If successful, the renewed credential is placed in @a creds.
7175 * Kerberos error codes
7177 krb5_error_code KRB5_CALLCONV
7178 krb5_get_renewed_creds(krb5_context context, krb5_creds *creds,
7179 krb5_principal client, krb5_ccache ccache,
7180 const char *in_tkt_service);
7183 * Decode an ASN.1-formatted ticket.
7185 * @param [in] code ASN.1-formatted ticket
7186 * @param [out] rep Decoded ticket information
7188 * @retval 0 Success; otherwise - Kerberos error codes
7190 krb5_error_code KRB5_CALLCONV
7191 krb5_decode_ticket(const krb5_data *code, krb5_ticket **rep);
7194 * Retrieve a string value from the appdefaults section of krb5.conf.
7196 * @param [in] context Library context
7197 * @param [in] appname Application name
7198 * @param [in] realm Realm name
7199 * @param [in] option Option to be checked
7200 * @param [in] default_value Default value to return if no match is found
7201 * @param [out] ret_value String value of @a option
7203 * This function gets the application defaults for @a option based on the given
7204 * @a appname and/or @a realm.
7206 * @sa krb5_appdefault_boolean()
7209 krb5_appdefault_string(krb5_context context, const char *appname,
7210 const krb5_data *realm, const char *option,
7211 const char *default_value, char ** ret_value);
7214 * Retrieve a boolean value from the appdefaults section of krb5.conf.
7216 * @param [in] context Library context
7217 * @param [in] appname Application name
7218 * @param [in] realm Realm name
7219 * @param [in] option Option to be checked
7220 * @param [in] default_value Default value to return if no match is found
7221 * @param [out] ret_value Boolean value of @a option
7223 * This function gets the application defaults for @a option based on the given
7224 * @a appname and/or @a realm.
7226 * @sa krb5_appdefault_string()
7229 krb5_appdefault_boolean(krb5_context context, const char *appname,
7230 const krb5_data *realm, const char *option,
7231 int default_value, int *ret_value);
7234 * Prompter enhancements
7236 /** Prompt for password */
7237 #define KRB5_PROMPT_TYPE_PASSWORD 0x1
7238 /** Prompt for new password (during password change) */
7239 #define KRB5_PROMPT_TYPE_NEW_PASSWORD 0x2
7240 /** Prompt for new password again */
7241 #define KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN 0x3
7242 /** Prompt for preauthentication data (such as an OTP value) */
7243 #define KRB5_PROMPT_TYPE_PREAUTH 0x4
7245 typedef krb5_int32 krb5_prompt_type;
7248 * Get prompt types array from a context.
7250 * @param [in] context Library context
7253 * Pointer to an array of prompt types corresponding to the prompter's @a
7254 * prompts arguments. Each type has one of the following values:
7255 * @li #KRB5_PROMPT_TYPE_PASSWORD
7256 * @li #KRB5_PROMPT_TYPE_NEW_PASSWORD
7257 * @li #KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN
7258 * @li #KRB5_PROMPT_TYPE_PREAUTH
7260 krb5_prompt_type* KRB5_CALLCONV
7261 krb5_get_prompt_types(krb5_context context);
7263 /* Error reporting */
7265 * Set an extended error message for an error code.
7267 * @param [in] ctx Library context
7268 * @param [in] code Error code
7269 * @param [in] fmt Error string for the error code
7270 * @param [in] ... printf(3) style parameters
7272 void KRB5_CALLCONV_C
7273 krb5_set_error_message(krb5_context ctx, krb5_error_code code, const char *fmt, ...)
7274 #if !defined(__cplusplus) && (__GNUC__ > 2)
7275 __attribute__((__format__(__printf__, 3, 4)))
7280 * Set an extended error message for an error code using a va_list.
7282 * @param [in] ctx Library context
7283 * @param [in] code Error code
7284 * @param [in] fmt Error string for the error code
7285 * @param [in] args List of vprintf(3) style arguments
7288 krb5_vset_error_message(krb5_context ctx, krb5_error_code code,
7289 const char *fmt, va_list args)
7290 #if !defined(__cplusplus) && (__GNUC__ > 2)
7291 __attribute__((__format__(__printf__, 3, 0)))
7296 * Copy the most recent extended error message from one context to another.
7298 * @param [in] dest_ctx Library context to copy message to
7299 * @param [in] src_ctx Library context with current message
7302 krb5_copy_error_message(krb5_context dest_ctx, krb5_context src_ctx);
7305 * Get the (possibly extended) error message for a code.
7307 * @param [in] ctx Library context
7308 * @param [in] code Error code
7310 * The behavior of krb5_get_error_message() is only defined the first time it
7311 * is called after a failed call to a krb5 function using the same context, and
7312 * only when the error code passed in is the same as that returned by the krb5
7315 * This function never returns NULL, so its result may be used unconditionally
7318 * The string returned by this function must be freed using
7319 * krb5_free_error_message()
7321 * @note Future versions may return the same string for the second
7322 * and following calls.
7324 const char * KRB5_CALLCONV
7325 krb5_get_error_message(krb5_context ctx, krb5_error_code code);
7328 * Free an error message generated by krb5_get_error_message().
7330 * @param [in] ctx Library context
7331 * @param [in] msg Pointer to error message
7334 krb5_free_error_message(krb5_context ctx, const char *msg);
7337 * Clear the extended error message in a context.
7339 * @param [in] ctx Library context
7341 * This function unsets the extended error message in a context, to ensure that
7342 * it is not mistakenly applied to another occurrence of the same error code.
7345 krb5_clear_error_message(krb5_context ctx);
7348 * Unwrap authorization data.
7350 * @param [in] context Library context
7351 * @param [in] type @ref KRB5_AUTHDATA type of @a container
7352 * @param [in] container Authorization data to be decoded
7353 * @param [out] authdata List of decoded authorization data
7355 * @sa krb5_encode_authdata_container()
7357 * @retval 0 Success; otherwise - Kerberos error codes
7359 krb5_error_code KRB5_CALLCONV
7360 krb5_decode_authdata_container(krb5_context context,
7361 krb5_authdatatype type,
7362 const krb5_authdata *container,
7363 krb5_authdata ***authdata);
7365 * Wrap authorization data in a container.
7367 * @param [in] context Library context
7368 * @param [in] type @ref KRB5_AUTHDATA type of @a container
7369 * @param [in] authdata List of authorization data to be encoded
7370 * @param [out] container List of encoded authorization data
7372 * The result is returned in @a container as a single-element list.
7374 * @sa krb5_decode_authdata_container()
7376 * @retval 0 Success; otherwise - Kerberos error codes
7378 krb5_error_code KRB5_CALLCONV
7379 krb5_encode_authdata_container(krb5_context context,
7380 krb5_authdatatype type,
7381 krb5_authdata * const*authdata,
7382 krb5_authdata ***container);
7388 * Encode and sign AD-KDCIssued authorization data.
7390 * @param [in] context Library context
7391 * @param [in] key Session key
7392 * @param [in] issuer The name of the issuing principal
7393 * @param [in] authdata List of authorization data to be signed
7394 * @param [out] ad_kdcissued List containing AD-KDCIssued authdata
7396 * This function wraps a list of authorization data entries @a authdata in an
7397 * AD-KDCIssued container (see RFC 4120 section 5.2.6.2) signed with @a key.
7398 * The result is returned in @a ad_kdcissued as a single-element list.
7400 krb5_error_code KRB5_CALLCONV
7401 krb5_make_authdata_kdc_issued(krb5_context context,
7402 const krb5_keyblock *key,
7403 krb5_const_principal issuer,
7404 krb5_authdata *const *authdata,
7405 krb5_authdata ***ad_kdcissued);
7408 * Unwrap and verify AD-KDCIssued authorization data.
7410 * @param [in] context Library context
7411 * @param [in] key Session key
7412 * @param [in] ad_kdcissued AD-KDCIssued authorization data to be unwrapped
7413 * @param [out] issuer Name of issuing principal (or NULL)
7414 * @param [out] authdata Unwrapped list of authorization data
7416 * This function unwraps an AD-KDCIssued authdatum (see RFC 4120 section
7417 * 5.2.6.2) and verifies its signature against @a key. The issuer field of the
7418 * authdatum element is returned in @a issuer, and the unwrapped list of
7419 * authdata is returned in @a authdata.
7421 krb5_error_code KRB5_CALLCONV
7422 krb5_verify_authdata_kdc_issued(krb5_context context,
7423 const krb5_keyblock *key,
7424 const krb5_authdata *ad_kdcissued,
7425 krb5_principal *issuer,
7426 krb5_authdata ***authdata);
7432 /* Microsoft defined types of data */
7433 #define KRB5_PAC_LOGON_INFO 1 /**< Logon information */
7434 #define KRB5_PAC_CREDENTIALS_INFO 2 /**< Credentials information */
7435 #define KRB5_PAC_SERVER_CHECKSUM 6 /**< Server checksum */
7436 #define KRB5_PAC_PRIVSVR_CHECKSUM 7 /**< KDC checksum */
7437 #define KRB5_PAC_CLIENT_INFO 10 /**< Client name and ticket info */
7438 #define KRB5_PAC_DELEGATION_INFO 11 /**< Constrained delegation info */
7439 #define KRB5_PAC_UPN_DNS_INFO 12 /**< User principal name and DNS info */
7441 struct krb5_pac_data;
7442 /** PAC data structure to convey authorization information */
7443 typedef struct krb5_pac_data *krb5_pac;
7446 * Add a buffer to a PAC handle.
7448 * @param [in] context Library context
7449 * @param [in] pac PAC handle
7450 * @param [in] type Buffer type
7451 * @param [in] data contents
7453 * This function adds a buffer of type @a type and contents @a data to @a pac
7454 * if there isn't already a buffer of this type present.
7456 * The valid values of @a type is one of the following:
7457 * @li #KRB5_PAC_LOGON_INFO - Logon information
7458 * @li #KRB5_PAC_CREDENTIALS_INFO - Credentials information
7459 * @li #KRB5_PAC_SERVER_CHECKSUM - Server checksum
7460 * @li #KRB5_PAC_PRIVSVR_CHECKSUM - KDC checksum
7461 * @li #KRB5_PAC_CLIENT_INFO - Client name and ticket information
7462 * @li #KRB5_PAC_DELEGATION_INFO - Constrained delegation information
7463 * @li #KRB5_PAC_UPN_DNS_INFO - User principal name and DNS information
7465 * @retval 0 Success; otherwise - Kerberos error codes
7467 krb5_error_code KRB5_CALLCONV
7468 krb5_pac_add_buffer(krb5_context context, krb5_pac pac, krb5_ui_4 type,
7469 const krb5_data *data);
7472 * Free a PAC handle.
7474 * @param [in] context Library context
7475 * @param [in] pac PAC to be freed
7477 * This function frees the contents of @a pac and the structure itself.
7480 krb5_pac_free(krb5_context context, krb5_pac pac);
7483 * Retrieve a buffer value from a PAC.
7485 * @param [in] context Library context
7486 * @param [in] pac PAC handle
7487 * @param [in] type Type of buffer to retrieve
7488 * @param [out] data Buffer value
7490 * Use krb5_free_data_contents() to free @a data when it is no longer needed.
7492 * @retval 0 Success; otherwise - Kerberos error codes
7494 krb5_error_code KRB5_CALLCONV
7495 krb5_pac_get_buffer(krb5_context context, krb5_pac pac, krb5_ui_4 type,
7499 * Return an array of buffer types in a PAC handle.
7501 * @param [in] context Library context
7502 * @param [in] pac PAC handle
7503 * @param [out] len Number of entries in @a types
7504 * @param [out] types Array of buffer types
7506 * @retval 0 Success; otherwise - Kerberos error codes
7508 krb5_error_code KRB5_CALLCONV
7509 krb5_pac_get_types(krb5_context context, krb5_pac pac, size_t *len,
7513 * Create an empty Privilege Attribute Certificate (PAC) handle.
7515 * @param [in] context Library context
7516 * @param [out] pac New PAC handle
7518 * Use krb5_pac_free() to free @a pac when it is no longer needed.
7520 * @retval 0 Success; otherwise - Kerberos error codes
7522 krb5_error_code KRB5_CALLCONV
7523 krb5_pac_init(krb5_context context, krb5_pac *pac);
7526 * Unparse an encoded PAC into a new handle.
7528 * @param [in] context Library context
7529 * @param [in] ptr PAC buffer
7530 * @param [in] len Length of @a ptr
7531 * @param [out] pac PAC handle
7533 * Use krb5_pac_free() to free @a pac when it is no longer needed.
7535 * @retval 0 Success; otherwise - Kerberos error codes
7537 krb5_error_code KRB5_CALLCONV
7538 krb5_pac_parse(krb5_context context, const void *ptr, size_t len,
7544 * @param [in] context Library context
7545 * @param [in] pac PAC handle
7546 * @param [in] authtime Expected timestamp
7547 * @param [in] principal Expected principal name (or NULL)
7548 * @param [in] server Key to validate server checksum (or NULL)
7549 * @param [in] privsvr Key to validate KDC checksum (or NULL)
7551 * This function validates @a pac against the supplied @a server, @a privsvr,
7552 * @a principal and @a authtime. If @a principal is NULL, the principal and
7553 * authtime are not verified. If @a server or @a privsvr is NULL, the
7554 * corresponding checksum is not verified.
7556 * If successful, @a pac is marked as verified.
7558 * @note A checksum mismatch can occur if the PAC was copied from a cross-realm
7559 * TGT by an ignorant KDC; also Apple Mac OS X Server Open Directory (as of
7560 * 10.6) generates PACs with no server checksum at all. One should consider
7561 * not failing the whole authentication because of this reason, but, instead,
7562 * treating the ticket as if it did not contain a PAC or marking the PAC
7563 * information as non-verified.
7565 * @retval 0 Success; otherwise - Kerberos error codes
7567 krb5_error_code KRB5_CALLCONV
7568 krb5_pac_verify(krb5_context context, const krb5_pac pac,
7569 krb5_timestamp authtime, krb5_const_principal principal,
7570 const krb5_keyblock *server, const krb5_keyblock *privsvr);
7575 * @param [in] context Library context
7576 * @param [in] pac PAC handle
7577 * @param [in] authtime Expected timestamp
7578 * @param [in] principal Expected principal name (or NULL)
7579 * @param [in] server_key Key for server checksum
7580 * @param [in] privsvr_key Key for KDC checksum
7581 * @param [out] data Signed PAC encoding
7583 * This function signs @a pac using the keys @a server_key and @a privsvr_key
7584 * and returns the signed encoding in @a data. @a pac is modified to include
7585 * the server and KDC checksum buffers. Use krb5_free_data_contents() to free
7586 * @a data when it is no longer needed.
7588 * @version First introduced in 1.10
7590 krb5_error_code KRB5_CALLCONV
7591 krb5_pac_sign(krb5_context context, krb5_pac pac, krb5_timestamp authtime,
7592 krb5_const_principal principal, const krb5_keyblock *server_key,
7593 const krb5_keyblock *privsvr_key, krb5_data *data);
7596 * Allow the appplication to override the profile's allow_weak_crypto setting.
7598 * @param [in] context Library context
7599 * @param [in] enable Boolean flag
7601 * This function allows an application to override the allow_weak_crypto
7602 * setting. It is primarily for use by aklog.
7604 * @retval 0 (always)
7606 krb5_error_code KRB5_CALLCONV
7607 krb5_allow_weak_crypto(krb5_context context, krb5_boolean enable);
7609 /* This structure may be extended to contain more fields in the future. */
7610 struct krb5_trace_info {
7611 const char *message;
7615 (KRB5_CALLCONV *krb5_trace_callback)(krb5_context context,
7616 const struct krb5_trace_info *info,
7620 * Specify a callback function for trace events.
7622 * @param [in] context Library context
7623 * @param [in] fn Callback function
7624 * @param [in] cb_data Callback data
7626 * Specify a callback for trace events occurring in krb5 operations performed
7627 * within @a context. @a fn will be invoked with @a context as the first
7628 * argument, @a cb_data as the last argument, and a pointer to a struct
7629 * krb5_trace_info as the second argument. If the trace callback is reset via
7630 * this function or @a context is destroyed, @a fn will be invoked with a NULL
7631 * second argument so it can clean up @a cb_data. Supply a NULL value for @a
7632 * fn to disable trace callbacks within @a context.
7634 * @note This function overrides the information passed through the
7635 * @a KRB5_TRACE environment variable.
7637 * @version First introduced in 1.9
7639 * @return Returns KRB5_TRACE_NOSUPP if tracing is not supported in the library
7640 * (unless @a fn is NULL).
7642 krb5_error_code KRB5_CALLCONV
7643 krb5_set_trace_callback(krb5_context context, krb5_trace_callback fn,
7647 * Specify a file name for directing trace events.
7649 * @param [in] context Library context
7650 * @param [in] filename File name
7652 * Open @a filename for appending (creating it, if necessary) and set up a
7653 * callback to write trace events to it.
7655 * @note This function overrides the information passed through the
7656 * @a KRB5_TRACE environment variable.
7658 * @version First introduced in 1.9
7660 * @retval KRB5_TRACE_NOSUPP Tracing is not supported in the library.
7662 krb5_error_code KRB5_CALLCONV
7663 krb5_set_trace_filename(krb5_context context, const char *filename);
7671 /* Don't use this! We're going to phase it out. It's just here to keep
7672 applications from breaking right away. */
7673 #define krb5_const const
7675 #undef KRB5_ATTR_DEPRECATED
7677 /** @} */ /* end of KRB5_H group */
7679 #endif /* KRB5_GENERAL__ */