-/* -*- c -*-
- * include/krb5.h
- *
- * Copyright 1989,1990,1995,2001, 2003, 2007 by the Massachusetts Institute of Technology.
- * All Rights Reserved.
+/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/* General definitions for Kerberos version 5. */
+/*
+ * Copyright 1989, 1990, 1995, 2001, 2003, 2007, 2011 by the Massachusetts
+ * Institute of Technology. All Rights Reserved.
*
* Export of this software from the United States of America may
* require a specific license from the United States Government.
* It is the responsibility of any person or organization contemplating
* export to obtain such a license before exporting.
- *
+ *
* WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
* distribute this software and its documentation for any purpose and
* without fee is hereby granted, provided that the above copyright
* this permission notice appear in supporting documentation, and that
* the name of M.I.T. not be used in advertising or publicity pertaining
* to distribution of the software without specific, written prior
- * permission. Furthermore if you modify this software you must label
+ * permission. Furthermore if you modify this software you must label
* your software as modified software and not distribute it in such a
* fashion that it might be confused with the original M.I.T. software.
* M.I.T. makes no representations about the suitability of
* this software for any purpose. It is provided "as is" without express
* or implied warranty.
- *
- *
- * General definitions for Kerberos version 5.
*/
-
/*
* Copyright (C) 1998 by the FundsXpress, INC.
- *
+ *
* All rights reserved.
- *
+ *
* Export of this software from the United States of America may require
* a specific license from the United States Government. It is the
* responsibility of any person or organization contemplating export to
* obtain such a license before exporting.
- *
+ *
* WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
* distribute this software and its documentation for any purpose and
* without fee is hereby granted, provided that the above copyright
* permission. FundsXpress makes no representations about the suitability of
* this software for any purpose. It is provided "as is" without express
* or implied warranty.
- *
+ *
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
* IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
* WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
#ifndef KRB5_GENERAL__
#define KRB5_GENERAL__
-/* By default, do not expose deprecated interfaces. */
+/** @defgroup KRB5_H krb5 library API
+ * @{
+ */
+
+ /* By default, do not expose deprecated interfaces. */
#ifndef KRB5_DEPRECATED
#define KRB5_DEPRECATED 0
#endif
#if defined(__MACH__) && defined(__APPLE__)
-# include <TargetConditionals.h>
+# include <TargetConditionals.h>
# if TARGET_RT_MAC_CFM
-# error "Use KfM 4.0 SDK headers for CFM compilation."
+# error "Use KfM 4.0 SDK headers for CFM compilation."
# endif
#endif
#define KRB5_OLD_CRYPTO
#include <stdlib.h>
-#include <limits.h> /* for *_MAX */
+#include <limits.h> /* for *_MAX */
#include <stdarg.h>
#ifndef KRB5INT_BEGIN_DECLS
#if defined(__cplusplus)
-#define KRB5INT_BEGIN_DECLS extern "C" {
-#define KRB5INT_END_DECLS }
+#define KRB5INT_BEGIN_DECLS extern "C" {
+#define KRB5INT_END_DECLS }
#else
#define KRB5INT_BEGIN_DECLS
#define KRB5INT_END_DECLS
* Word-size related definition.
*/
-typedef unsigned char krb5_octet;
+typedef unsigned char krb5_octet;
#if INT_MAX == 0x7fff
-typedef int krb5_int16;
-typedef unsigned int krb5_ui_2;
+typedef int krb5_int16;
+typedef unsigned int krb5_ui_2;
#elif SHRT_MAX == 0x7fff
-typedef short krb5_int16;
-typedef unsigned short krb5_ui_2;
+typedef short krb5_int16;
+typedef unsigned short krb5_ui_2;
#else
#error undefined 16 bit type
#endif
#if INT_MAX == 0x7fffffffL
-typedef int krb5_int32;
-typedef unsigned int krb5_ui_4;
+typedef int krb5_int32;
+typedef unsigned int krb5_ui_4;
#elif LONG_MAX == 0x7fffffffL
-typedef long krb5_int32;
-typedef unsigned long krb5_ui_4;
+typedef long krb5_int32;
+typedef unsigned long krb5_ui_4;
#elif SHRT_MAX == 0x7fffffffL
-typedef short krb5_int32;
-typedef unsigned short krb5_ui_4;
+typedef short krb5_int32;
+typedef unsigned short krb5_ui_4;
#else
#error: undefined 32 bit type
#endif
-#define VALID_INT_BITS INT_MAX
-#define VALID_UINT_BITS UINT_MAX
+#define VALID_INT_BITS INT_MAX
+#define VALID_UINT_BITS UINT_MAX
-#define KRB5_INT32_MAX 2147483647
+#define KRB5_INT32_MAX 2147483647
/* this strange form is necessary since - is a unary operator, not a sign
indicator */
-#define KRB5_INT32_MIN (-KRB5_INT32_MAX-1)
+#define KRB5_INT32_MIN (-KRB5_INT32_MAX-1)
-#define KRB5_INT16_MAX 65535
+#define KRB5_INT16_MAX 65535
/* this strange form is necessary since - is a unary operator, not a sign
indicator */
-#define KRB5_INT16_MIN (-KRB5_INT16_MAX-1)
+#define KRB5_INT16_MIN (-KRB5_INT16_MAX-1)
/*
* end wordsize.h
*/
#ifndef FALSE
-#define FALSE 0
+#define FALSE 0
#endif
#ifndef TRUE
-#define TRUE 1
+#define TRUE 1
#endif
-typedef unsigned int krb5_boolean;
-typedef unsigned int krb5_msgtype;
-typedef unsigned int krb5_kvno;
+typedef unsigned int krb5_boolean;
+typedef unsigned int krb5_msgtype;
+typedef unsigned int krb5_kvno;
-typedef krb5_int32 krb5_addrtype;
+typedef krb5_int32 krb5_addrtype;
typedef krb5_int32 krb5_enctype;
typedef krb5_int32 krb5_cksumtype;
typedef krb5_int32 krb5_authdatatype;
typedef krb5_int32 krb5_keyusage;
typedef krb5_int32 krb5_cryptotype;
-typedef krb5_int32 krb5_preauthtype; /* This may change, later on */
-typedef krb5_int32 krb5_flags;
-typedef krb5_int32 krb5_timestamp;
-typedef krb5_int32 krb5_error_code;
-typedef krb5_int32 krb5_deltat;
+typedef krb5_int32 krb5_preauthtype; /* This may change, later on */
+typedef krb5_int32 krb5_flags;
+typedef krb5_int32 krb5_timestamp;
+typedef krb5_int32 krb5_error_code;
+typedef krb5_int32 krb5_deltat;
-typedef krb5_error_code krb5_magic;
+typedef krb5_error_code krb5_magic;
typedef struct _krb5_data {
- krb5_magic magic;
- unsigned int length;
- char *data;
+ krb5_magic magic;
+ unsigned int length;
+ char *data;
} krb5_data;
+/* Originally introduced for PKINIT; now unused. Do not use this. */
typedef struct _krb5_octet_data {
- krb5_magic magic;
- unsigned int length;
- krb5_octet *data;
+ krb5_magic magic;
+ unsigned int length;
+ krb5_octet *data;
} krb5_octet_data;
-/*
- * Hack length for crypto library to use the afs_string_to_key It is
- * equivalent to -1 without possible sign extension
- * We also overload for an unset salt type length - which is also -1, but
- * hey, why not....
-*/
+/* Originally used to recognize AFS and default salts. No longer used. */
#define SALT_TYPE_AFS_LENGTH UINT_MAX
#define SALT_TYPE_NO_LENGTH UINT_MAX
-typedef void * krb5_pointer;
+typedef void * krb5_pointer;
typedef void const * krb5_const_pointer;
typedef struct krb5_principal_data {
krb5_magic magic;
krb5_data realm;
- krb5_data *data; /* An array of strings */
+ krb5_data *data; /**< An array of strings */
krb5_int32 length;
krb5_int32 type;
} krb5_principal_data;
-typedef krb5_principal_data * krb5_principal;
+typedef krb5_principal_data * krb5_principal;
/*
* Per V5 spec on definition of principal types
*/
-/* Name type not known */
-#define KRB5_NT_UNKNOWN 0
-/* Just the name of the principal as in DCE, or for users */
-#define KRB5_NT_PRINCIPAL 1
-/* Service and other unique instance (krbtgt) */
-#define KRB5_NT_SRV_INST 2
-/* Service with host name as instance (telnet, rcommands) */
-#define KRB5_NT_SRV_HST 3
-/* Service with host as remaining components */
-#define KRB5_NT_SRV_XHST 4
-/* Unique ID */
-#define KRB5_NT_UID 5
-/* PKINIT */
-#define KRB5_NT_X500_PRINCIPAL 6
-/* Name in form of SMTP email name */
-#define KRB5_NT_SMTP_NAME 7
-/* Windows 2000 UPN */
-#define KRB5_NT_ENTERPRISE_PRINCIPAL 10
-/* Windows 2000 UPN and SID */
-#define KRB5_NT_MS_PRINCIPAL -128
-/* NT 4 style name */
-#define KRB5_NT_MS_PRINCIPAL_AND_ID -129
-/* NT 4 style name and SID */
-#define KRB5_NT_ENT_PRINCIPAL_AND_ID -130
-
-/* constant version thereof: */
+#define KRB5_NT_UNKNOWN 0 /**< Name type not known */
+#define KRB5_NT_PRINCIPAL 1 /**< Just the name of the principal
+ as in DCE, or for users */
+#define KRB5_NT_SRV_INST 2 /**< Service and other unique instance (krbtgt) */
+#define KRB5_NT_SRV_HST 3 /**< Service with host name as instance
+ (telnet, rcommands) */
+#define KRB5_NT_SRV_XHST 4 /**< Service with host as remaining components */
+#define KRB5_NT_UID 5 /**< Unique ID */
+#define KRB5_NT_X500_PRINCIPAL 6 /**< PKINIT */
+#define KRB5_NT_SMTP_NAME 7 /**< Name in form of SMTP email name */
+#define KRB5_NT_ENTERPRISE_PRINCIPAL 10 /**< Windows 2000 UPN */
+#define KRB5_NT_WELLKNOWN 11 /**< Well-known (special) principal */
+#define KRB5_WELLKNOWN_NAMESTR "WELLKNOWN" /**< First component of
+ NT_WELLKNOWN principals */
+#define KRB5_NT_MS_PRINCIPAL -128 /**< Windows 2000 UPN and SID */
+#define KRB5_NT_MS_PRINCIPAL_AND_ID -129 /**< NT 4 style name */
+#define KRB5_NT_ENT_PRINCIPAL_AND_ID -130 /**< NT 4 style name and SID */
+
+/** Constant version of krb5_principal_data */
typedef const krb5_principal_data *krb5_const_principal;
#define krb5_princ_realm(context, princ) (&(princ)->realm)
#define krb5_princ_set_realm(context, princ,value) ((princ)->realm = *(value))
#define krb5_princ_set_realm_length(context, princ,value) (princ)->realm.length = (value)
#define krb5_princ_set_realm_data(context, princ,value) (princ)->realm.data = (value)
-#define krb5_princ_size(context, princ) (princ)->length
-#define krb5_princ_type(context, princ) (princ)->type
-#define krb5_princ_name(context, princ) (princ)->data
-#define krb5_princ_component(context, princ,i) \
- (((i) < krb5_princ_size(context, princ)) \
- ? (princ)->data + (i) \
- : NULL)
+#define krb5_princ_size(context, princ) (princ)->length
+#define krb5_princ_type(context, princ) (princ)->type
+#define krb5_princ_name(context, princ) (princ)->data
+#define krb5_princ_component(context, princ,i) \
+ (((i) < krb5_princ_size(context, princ)) \
+ ? (princ)->data + (i) \
+ : NULL)
-/*
- * Constants for realm referrals.
- */
-#define KRB5_REFERRAL_REALM ""
+/** Constant for realm referrals. */
+#define KRB5_REFERRAL_REALM ""
/*
* Referral-specific functions.
*/
-krb5_boolean KRB5_CALLCONV krb5_is_referral_realm(const krb5_data *);
+/**
+ * Check for a match with KRB5_REFERRAL_REALM.
+ *
+ * @param [in] r Realm to check
+ *
+ * @return @c TRUE if @a r is zero-length, @c FALSE otherwise
+ */
+krb5_boolean KRB5_CALLCONV
+krb5_is_referral_realm(const krb5_data *r);
+
+/**
+ * Return an anonymous realm data.
+ *
+ * This function returns constant storage that must not be freed.
+ *
+ * @sa #KRB5_ANONYMOUS_REALMSTR
+ */
+const krb5_data *KRB5_CALLCONV
+krb5_anonymous_realm(void);
+
+/**
+ * Build an anonymous principal.
+ *
+ * This function returns constant storage that must not be freed.
+ *
+ * @sa #KRB5_ANONYMOUS_PRINCSTR
+ */
+krb5_const_principal KRB5_CALLCONV
+krb5_anonymous_principal(void);
+
+#define KRB5_ANONYMOUS_REALMSTR "WELLKNOWN:ANONYMOUS" /**< Anonymous realm */
+#define KRB5_ANONYMOUS_PRINCSTR "ANONYMOUS" /**< Anonymous principal name */
/*
* end "base-defs.h"
*/
* begin "hostaddr.h"
*/
-/* structure for address */
+/** Structure for address */
typedef struct _krb5_address {
krb5_magic magic;
krb5_addrtype addrtype;
} krb5_address;
/* per Kerberos v5 protocol spec */
-#define ADDRTYPE_INET 0x0002
-#define ADDRTYPE_CHAOS 0x0005
-#define ADDRTYPE_XNS 0x0006
-#define ADDRTYPE_ISO 0x0007
-#define ADDRTYPE_DDP 0x0010
-#define ADDRTYPE_NETBIOS 0x0014
-#define ADDRTYPE_INET6 0x0018
+#define ADDRTYPE_INET 0x0002
+#define ADDRTYPE_CHAOS 0x0005
+#define ADDRTYPE_XNS 0x0006
+#define ADDRTYPE_ISO 0x0007
+#define ADDRTYPE_DDP 0x0010
+#define ADDRTYPE_NETBIOS 0x0014
+#define ADDRTYPE_INET6 0x0018
/* not yet in the spec... */
-#define ADDRTYPE_ADDRPORT 0x0100
-#define ADDRTYPE_IPPORT 0x0101
+#define ADDRTYPE_ADDRPORT 0x0100
+#define ADDRTYPE_IPPORT 0x0101
/* macros to determine if a type is a local type */
#define ADDRTYPE_IS_LOCAL(addrtype) (addrtype & 0x8000)
* begin "encryption.h"
*/
+/** Exposed contents of a key. */
typedef struct _krb5_keyblock {
krb5_magic magic;
krb5_enctype enctype;
krb5_octet *contents;
} krb5_keyblock;
+struct krb5_key_st;
+/**
+ * Opaque identifier for a key.
+ *
+ * Use with the krb5_k APIs for better performance for repeated operations with
+ * the same key and usage. Key identifiers must not be used simultaneously
+ * within multiple threads, as they may contain mutable internal state and are
+ * not mutex-protected.
+ */
+typedef struct krb5_key_st *krb5_key;
+
#ifdef KRB5_OLD_CRYPTO
typedef struct _krb5_encrypt_block {
krb5_magic magic;
- krb5_enctype crypto_entry; /* to call krb5_encrypt_size, you need
- this. it was a pointer, but it
- doesn't have to be. gross. */
+ krb5_enctype crypto_entry; /* to call krb5_encrypt_size, you need
+ this. it was a pointer, but it
+ doesn't have to be. gross. */
krb5_keyblock *key;
} krb5_encrypt_block;
#endif
typedef struct _krb5_checksum {
krb5_magic magic;
- krb5_cksumtype checksum_type; /* checksum type */
+ krb5_cksumtype checksum_type; /* checksum type */
unsigned int length;
krb5_octet *contents;
} krb5_checksum;
krb5_data ciphertext;
} krb5_enc_data;
+/**
+ * Structure to describe a region of text to be encrypted or decrypted.
+ *
+ * The @a flags member describes the type of the iov.
+ * The @a data member points to the memory that will be manipulated.
+ * All iov APIs take a pointer to the first element of an array of krb5_crypto_iov's
+ * along with the size of that array. Buffer contents are manipulated in-place;
+ * data is overwritten. Callers must allocate the right number of krb5_crypto_iov
+ * structures before calling into an iov API.
+ */
typedef struct _krb5_crypto_iov {
- krb5_cryptotype flags;
+ krb5_cryptotype flags; /**< @ref KRB5_CRYPTO_TYPE type of the iov */
krb5_data data;
} krb5_crypto_iov;
/* per Kerberos v5 protocol spec */
-#define ENCTYPE_NULL 0x0000
-#define ENCTYPE_DES_CBC_CRC 0x0001 /* DES cbc mode with CRC-32 */
-#define ENCTYPE_DES_CBC_MD4 0x0002 /* DES cbc mode with RSA-MD4 */
-#define ENCTYPE_DES_CBC_MD5 0x0003 /* DES cbc mode with RSA-MD5 */
-#define ENCTYPE_DES_CBC_RAW 0x0004 /* DES cbc mode raw */
-/* XXX deprecated? */
-#define ENCTYPE_DES3_CBC_SHA 0x0005 /* DES-3 cbc mode with NIST-SHA */
-#define ENCTYPE_DES3_CBC_RAW 0x0006 /* DES-3 cbc mode raw */
-#define ENCTYPE_DES_HMAC_SHA1 0x0008
+#define ENCTYPE_NULL 0x0000
+#define ENCTYPE_DES_CBC_CRC 0x0001 /**< DES cbc mode with CRC-32 */
+#define ENCTYPE_DES_CBC_MD4 0x0002 /**< DES cbc mode with RSA-MD4 */
+#define ENCTYPE_DES_CBC_MD5 0x0003 /**< DES cbc mode with RSA-MD5 */
+#define ENCTYPE_DES_CBC_RAW 0x0004 /**< @deprecated DES cbc mode raw */
+#define ENCTYPE_DES3_CBC_SHA 0x0005 /**< @deprecated DES-3 cbc with SHA1 */
+#define ENCTYPE_DES3_CBC_RAW 0x0006 /**< @deprecated DES-3 cbc mode raw */
+#define ENCTYPE_DES_HMAC_SHA1 0x0008 /**< @deprecated */
/* PKINIT */
-#define ENCTYPE_DSA_SHA1_CMS 0x0009 /* DSA with SHA1, CMS signature */
-#define ENCTYPE_MD5_RSA_CMS 0x000a /* MD5 with RSA, CMS signature */
-#define ENCTYPE_SHA1_RSA_CMS 0x000b /* SHA1 with RSA, CMS signature */
-#define ENCTYPE_RC2_CBC_ENV 0x000c /* RC2 cbc mode, CMS enveloped data */
-#define ENCTYPE_RSA_ENV 0x000d /* RSA encryption, CMS enveloped data */
-#define ENCTYPE_RSA_ES_OAEP_ENV 0x000e /* RSA w/OEAP encryption, CMS enveloped data */
-#define ENCTYPE_DES3_CBC_ENV 0x000f /* DES-3 cbc mode, CMS enveloped data */
-
-#define ENCTYPE_DES3_CBC_SHA1 0x0010
-#define ENCTYPE_AES128_CTS_HMAC_SHA1_96 0x0011
-#define ENCTYPE_AES256_CTS_HMAC_SHA1_96 0x0012
-#define ENCTYPE_ARCFOUR_HMAC 0x0017
-#define ENCTYPE_ARCFOUR_HMAC_EXP 0x0018
-#define ENCTYPE_UNKNOWN 0x01ff
-
-#define CKSUMTYPE_CRC32 0x0001
-#define CKSUMTYPE_RSA_MD4 0x0002
-#define CKSUMTYPE_RSA_MD4_DES 0x0003
-#define CKSUMTYPE_DESCBC 0x0004
+#define ENCTYPE_DSA_SHA1_CMS 0x0009 /**< DSA with SHA1, CMS signature */
+#define ENCTYPE_MD5_RSA_CMS 0x000a /**< MD5 with RSA, CMS signature */
+#define ENCTYPE_SHA1_RSA_CMS 0x000b /**< SHA1 with RSA, CMS signature */
+#define ENCTYPE_RC2_CBC_ENV 0x000c /**< RC2 cbc mode, CMS enveloped data */
+#define ENCTYPE_RSA_ENV 0x000d /**< RSA encryption, CMS enveloped data */
+#define ENCTYPE_RSA_ES_OAEP_ENV 0x000e /**< RSA w/OEAP encryption, CMS enveloped data */
+#define ENCTYPE_DES3_CBC_ENV 0x000f /**< DES-3 cbc mode, CMS enveloped data */
+
+#define ENCTYPE_DES3_CBC_SHA1 0x0010
+#define ENCTYPE_AES128_CTS_HMAC_SHA1_96 0x0011 /**< RFC 3962 */
+#define ENCTYPE_AES256_CTS_HMAC_SHA1_96 0x0012 /**< RFC 3962 */
+#define ENCTYPE_ARCFOUR_HMAC 0x0017
+#define ENCTYPE_ARCFOUR_HMAC_EXP 0x0018
+#define ENCTYPE_UNKNOWN 0x01ff
+
+#define CKSUMTYPE_CRC32 0x0001
+#define CKSUMTYPE_RSA_MD4 0x0002
+#define CKSUMTYPE_RSA_MD4_DES 0x0003
+#define CKSUMTYPE_DESCBC 0x0004
/* des-mac-k */
/* rsa-md4-des-k */
-#define CKSUMTYPE_RSA_MD5 0x0007
-#define CKSUMTYPE_RSA_MD5_DES 0x0008
-#define CKSUMTYPE_NIST_SHA 0x0009
-#define CKSUMTYPE_HMAC_SHA1_DES3 0x000c
-#define CKSUMTYPE_HMAC_SHA1_96_AES128 0x000f
-#define CKSUMTYPE_HMAC_SHA1_96_AES256 0x0010
+#define CKSUMTYPE_RSA_MD5 0x0007
+#define CKSUMTYPE_RSA_MD5_DES 0x0008
+#define CKSUMTYPE_NIST_SHA 0x0009
+#define CKSUMTYPE_HMAC_SHA1_DES3 0x000c
+#define CKSUMTYPE_HMAC_SHA1_96_AES128 0x000f /**< RFC 3962. Used with
+ ENCTYPE_AES128_CTS_HMAC_SHA1_96 */
+#define CKSUMTYPE_HMAC_SHA1_96_AES256 0x0010 /**< RFC 3962. Used with
+ ENCTYPE_AES256_CTS_HMAC_SHA1_96 */
#define CKSUMTYPE_MD5_HMAC_ARCFOUR -137 /*Microsoft netlogon cksumtype*/
#define CKSUMTYPE_HMAC_MD5_ARCFOUR -138 /*Microsoft md5 hmac cksumtype*/
-/* The following are entropy source designations. Whenever
- * krb5_C_random_add_entropy is called, one of these source ids is passed
- * in. This allows the library to better estimate bits of
- * entropy in the sample and to keep track of what sources of entropy have
- * contributed enough entropy. Sources marked internal MUST NOT be
- * used by applications outside the Kerberos library
-*/
+/*
+ * The following are entropy source designations. Whenever
+ * krb5_C_random_add_entropy is called, one of these source ids is passed in.
+ * This allows the library to better estimate bits of entropy in the sample and
+ * to keep track of what sources of entropy have contributed enough entropy.
+ * Sources marked internal MUST NOT be used by applications outside the
+ * Kerberos library
+ */
enum {
- KRB5_C_RANDSOURCE_OLDAPI = 0, /*calls to krb5_C_RANDOM_SEED (INTERNAL)*/
- KRB5_C_RANDSOURCE_OSRAND = 1, /* /dev/random or equivalent (internal)*/
- KRB5_C_RANDSOURCE_TRUSTEDPARTY = 2, /* From KDC or other trusted party*/
- /*This source should be used carefully; data in this category
- * should be from a third party trusted to give random bits
- * For example keys issued by the KDC in the application server.
- */
- KRB5_C_RANDSOURCE_TIMING = 3, /* Timing of operations*/
- KRB5_C_RANDSOURCE_EXTERNAL_PROTOCOL = 4, /*Protocol data possibly from attacker*/
- KRB5_C_RANDSOURCE_MAX = 5 /*Do not use; maximum source ID*/
+ KRB5_C_RANDSOURCE_OLDAPI = 0, /*calls to krb5_C_RANDOM_SEED (INTERNAL)*/
+ KRB5_C_RANDSOURCE_OSRAND = 1, /* /dev/random or equivalent (internal)*/
+ KRB5_C_RANDSOURCE_TRUSTEDPARTY = 2, /* From KDC or other trusted party*/
+ /*
+ * This source should be used carefully; data in this category
+ * should be from a third party trusted to give random bits
+ * For example keys issued by the KDC in the application server.
+ */
+ KRB5_C_RANDSOURCE_TIMING = 3, /* Timing of operations*/
+ KRB5_C_RANDSOURCE_EXTERNAL_PROTOCOL = 4, /*Protocol data possibly from attacker*/
+ KRB5_C_RANDSOURCE_MAX = 5 /*Do not use; maximum source ID*/
};
#ifndef krb5_roundup
#define krb5_xc(ptr,args) ((*(ptr)) args)
#endif
+/**
+ * Encrypt data using a key (operates on keyblock).
+ *
+ * @param [in] context Library context
+ * @param [in] key Encryption key
+ * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
+ * @param [in,out] cipher_state Cipher state; specify NULL if not needed
+ * @param [in] input Data to be encrypted
+ * @param [out] output Encrypted data
+ *
+ * This function encrypts the data block @a input and stores the output into @a
+ * output. The actual encryption key will be derived from @a key and @a usage
+ * if key derivation is specified for the encryption type. If non-null, @a
+ * cipher_state specifies the beginning state for the encryption operation, and
+ * is updated with the state to be passed as input to the next operation.
+ *
+ * @note The caller must initialize @a output and allocate at least enough
+ * space for the result (using krb5_c_encrypt_length() to determine the amount
+ * of space needed). @a output->length will be set to the actual length of the
+ * ciphertext.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
- krb5_c_encrypt
- (krb5_context context, const krb5_keyblock *key,
- krb5_keyusage usage, const krb5_data *cipher_state,
- const krb5_data *input, krb5_enc_data *output);
+krb5_c_encrypt(krb5_context context, const krb5_keyblock *key,
+ krb5_keyusage usage, const krb5_data *cipher_state,
+ const krb5_data *input, krb5_enc_data *output);
+/**
+ * Decrypt data using a key (operates on keyblock).
+ *
+ * @param [in] context Library context
+ * @param [in] key Encryption key
+ * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
+ * @param [in,out] cipher_state Cipher state; specify NULL if not needed
+ * @param [in] input Encrypted data
+ * @param [out] output Decrypted data
+ *
+ * This function decrypts the data block @a input and stores the output into @a
+ * output. The actual decryption key will be derived from @a key and @a usage
+ * if key derivation is specified for the encryption type. If non-null, @a
+ * cipher_state specifies the beginning state for the decryption operation, and
+ * is updated with the state to be passed as input to the next operation.
+ *
+ * @note The caller must initialize @a output and allocate at least enough
+ * space for the result. The usual practice is to allocate an output buffer as
+ * long as the ciphertext, and let krb5_c_decrypt() trim @a output->length.
+ * For some enctypes, the resulting @a output->length may include padding
+ * bytes.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
- krb5_c_decrypt
- (krb5_context context, const krb5_keyblock *key,
- krb5_keyusage usage, const krb5_data *cipher_state,
- const krb5_enc_data *input, krb5_data *output);
+krb5_c_decrypt(krb5_context context, const krb5_keyblock *key,
+ krb5_keyusage usage, const krb5_data *cipher_state,
+ const krb5_enc_data *input, krb5_data *output);
+/**
+ * Compute encrypted data length.
+ *
+ * @param [in] context Library context
+ * @param [in] enctype Encryption type
+ * @param [in] inputlen Length of the data to be encrypted
+ * @param [out] length Length of the encrypted data
+ *
+ * This function computes the length of the ciphertext produced by encrypting
+ * @a inputlen bytes including padding, confounder, and checksum.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
- krb5_c_encrypt_length
- (krb5_context context, krb5_enctype enctype,
- size_t inputlen, size_t *length);
+krb5_c_encrypt_length(krb5_context context, krb5_enctype enctype,
+ size_t inputlen, size_t *length);
+/**
+ * Return cipher block size.
+ *
+ * @param [in] context Library context
+ * @param [in] enctype Encryption type
+ * @param [out] blocksize Block size for @a enctype
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
- krb5_c_block_size
- (krb5_context context, krb5_enctype enctype,
- size_t *blocksize);
+krb5_c_block_size(krb5_context context, krb5_enctype enctype,
+ size_t *blocksize);
+/**
+ * Return length of the specified key in bytes.
+ *
+ * @param [in] context Library context
+ * @param [in] enctype Encryption type
+ * @param [out] keybytes Number of bytes required to make a key
+ * @param [out] keylength Length of final key
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
- krb5_c_keylengths
- (krb5_context context, krb5_enctype enctype,
- size_t *keybytes, size_t *keylength);
+krb5_c_keylengths(krb5_context context, krb5_enctype enctype,
+ size_t *keybytes, size_t *keylength);
+/**
+ * Initialize a new cipher state.
+ *
+ * @param [in] context Library context
+ * @param [in] key Key
+ * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
+ * @param [out] new_state New cipher state
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
- krb5_c_init_state
-(krb5_context context,
-const krb5_keyblock *key, krb5_keyusage usage,
-krb5_data *new_state);
+krb5_c_init_state(krb5_context context, const krb5_keyblock *key,
+ krb5_keyusage usage, krb5_data *new_state);
+/**
+ * Free a cipher state previously allocated by krb5_c_init_state().
+ *
+ * @param [in] context Library context
+ * @param [in] key Key
+ * @param [in] state Cipher state to be freed
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
- krb5_c_free_state
-(krb5_context context, const krb5_keyblock *key, krb5_data *state);
+krb5_c_free_state(krb5_context context, const krb5_keyblock *key,
+ krb5_data *state);
+/**
+ * Generate enctype-specific pseudo-random bytes.
+ *
+ * @param [in] context Library context
+ * @param [in] keyblock Key
+ * @param [in] input Input data
+ * @param [out] output Output data
+ *
+ * This function selects a pseudo-random function based on @a keyblock and
+ * computes its value over @a input, placing the result into @a output.
+ * The caller must preinitialize @a output and allocate space for the
+ * result, using krb5_c_prf_length() to determine the required length.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
- krb5_c_prf (krb5_context, const krb5_keyblock *,
- krb5_data *in, krb5_data *out);
+krb5_c_prf(krb5_context context, const krb5_keyblock *keyblock,
+ krb5_data *input, krb5_data *output);
+/**
+ * Get the output length of pseudo-random functions for an encryption type.
+ *
+ * @param [in] context Library context
+ * @param [in] enctype Encryption type
+ * @param [out] len Length of PRF output
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
- krb5_c_prf_length (krb5_context, krb5_enctype, size_t *outlen);
+krb5_c_prf_length(krb5_context context, krb5_enctype enctype, size_t *len);
+
+/**
+ * Compute the KRB-FX-CF2 combination of two keys and pepper strings.
+ *
+ * @param [in] context Library context
+ * @param [in] k1 KDC contribution key
+ * @param [in] pepper1 String "PKINIT"
+ * @param [in] k2 Reply key
+ * @param [in] pepper2 String "KeyExchange"
+ * @param [out] out Output key
+ *
+ * This function computes the KRB-FX-CF2 function over its inputs and places
+ * the results in a newly allocated keyblock. This function is simple in that
+ * it assumes that @a pepper1 and @a pepper2 are C strings with no internal
+ * nulls and that the enctype of the result will be the same as that of @a k1.
+ * @a k1 and @a k2 may be of different enctypes.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
krb5_c_fx_cf2_simple(krb5_context context,
- krb5_keyblock *k1, const char *pepper1,
- krb5_keyblock *k2, const char *pepper2,
- krb5_keyblock **out);
- /* Returns KRB-FX-CF2 in a newly allocated
- * keyblock on success or an error code on error.
- * This function is simple in that it assumes
- * pepper1 and pepper2 are C strings with no
- * internal nulls and that the enctype of the
- * result will be the same as that of k1. Both
- * of these assumptions are true of current
- * specs.
- */
+ krb5_keyblock *k1, const char *pepper1,
+ krb5_keyblock *k2, const char *pepper2,
+ krb5_keyblock **out);
+
+/**
+ * Generate an enctype-specific random encryption key.
+ *
+ * @param [in] context Library context
+ * @param [in] enctype Encryption type of the generated key
+ * @param [out] k5_random_key An allocated and initialized keyblock
+ *
+ * Use krb5_free_keyblock_contents() to free @a k5_random_key when
+ * no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_c_make_random_key(krb5_context context, krb5_enctype enctype,
+ krb5_keyblock *k5_random_key);
+
+/**
+ * Generate an enctype-specific key from random data.
+ *
+ * @param [in] context Library context
+ * @param [in] enctype Encryption type
+ * @param [in] random_data Random input data
+ * @param [out] k5_random_key Resulting key
+ *
+ * This function takes random input data @a random_data and produces a valid
+ * key @a k5_random_key for a given @a enctype.
+ *
+ * @note It is assumed that @a k5_random_key has already been initialized and
+ * @a k5_random_key->contents has been allocated with the correct length.
+ *
+ * @sa krb5_c_keylengths()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_c_random_to_key(krb5_context context, krb5_enctype enctype,
+ krb5_data *random_data, krb5_keyblock *k5_random_key);
+/**
+ * Add entropy to the pseudo-random number generator.
+ *
+ * @param [in] context Library context
+ * @param [in] randsource Entropy source (see KRB5_RANDSOURCE types)
+ * @param [in] data Data
+ *
+ * Contribute entropy to the PRNG used by krb5 crypto operations. This may or
+ * may not affect the output of the next crypto operation requiring random
+ * data.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_c_random_add_entropy(krb5_context context, unsigned int randsource,
+ const krb5_data *data);
+/**
+ * Generate pseudo-random bytes.
+ *
+ * @param [in] context Library context
+ * @param [out] data Random data
+ *
+ * Fills in @a data with bytes from the PRNG used by krb5 crypto operations.
+ * The caller must preinitialize @a data and allocate the desired amount of
+ * space.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
- krb5_c_make_random_key
- (krb5_context context, krb5_enctype enctype,
- krb5_keyblock *k5_random_key);
+krb5_c_random_make_octets(krb5_context context, krb5_data *data);
+/**
+ * Collect entropy from the OS if possible.
+ *
+ * @param [in] context Library context
+ * @param [in] strong Strongest available source of entropy
+ * @param [out] success 1 if OS provides entropy, 0 otherwise
+ *
+ * If @a strong is non-zero, this function attempts to use the strongest
+ * available source of entropy. Setting this flag may cause the function to
+ * block on some operating systems. Good uses include seeding the PRNG for
+ * kadmind and realm setup.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
- krb5_c_random_to_key
- (krb5_context context, krb5_enctype enctype,
- krb5_data *random_data, krb5_keyblock *k5_random_key);
+krb5_c_random_os_entropy(krb5_context context, int strong, int *success);
-/* Register a new entropy sample with the PRNG. may cause
-* the PRNG to be reseeded, although this is not guaranteed. See previous randsource definitions
-* for information on how each source should be used.
-*/
+/** @deprecated Replaced by krb5_c_ API family. */
krb5_error_code KRB5_CALLCONV
- krb5_c_random_add_entropy
-(krb5_context context, unsigned int randsource_id, const krb5_data *data);
+krb5_c_random_seed(krb5_context context, krb5_data *data);
+/**
+ * Convert a string (such a password) to a key.
+ *
+ * @param [in] context Library context
+ * @param [in] enctype Encryption type
+ * @param [in] string String to be converted
+ * @param [in] salt Salt value
+ * @param [out] key Generated key
+ *
+ * This function converts @a string to a @a key of encryption type @a enctype,
+ * using the specified @a salt. The newly created @a key must be released by
+ * calling krb5_free_keyblock_contents() when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_c_string_to_key(krb5_context context, krb5_enctype enctype,
+ const krb5_data *string, const krb5_data *salt,
+ krb5_keyblock *key);
+/**
+ * Convert a string (such as a password) to a key with additional parameters.
+ *
+ * @param [in] context Library context
+ * @param [in] enctype Encryption type
+ * @param [in] string String to be converted
+ * @param [in] salt Salt value
+ * @param [in] params Parameters
+ * @param [out] key Generated key
+ *
+ * This function is similar to krb5_c_string_to_key(), but also takes
+ * parameters which may affect the algorithm in an enctype-dependent way. The
+ * newly created @a key must be released by calling
+ * krb5_free_keyblock_contents() when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
- krb5_c_random_make_octets
- (krb5_context context, krb5_data *data);
+krb5_c_string_to_key_with_params(krb5_context context,
+ krb5_enctype enctype,
+ const krb5_data *string,
+ const krb5_data *salt,
+ const krb5_data *params,
+ krb5_keyblock *key);
+
+/**
+ * Compare two encryption types.
+ *
+ * @param [in] context Library context
+ * @param [in] e1 First encryption type
+ * @param [in] e2 Second encryption type
+ * @param [out] similar @c TRUE if types are similar, @c FALSE if not
+ *
+ * This function determines whether two encryption types use the same kind of
+ * keys.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_c_enctype_compare(krb5_context context, krb5_enctype e1, krb5_enctype e2,
+ krb5_boolean *similar);
-/*
-* Collect entropy from the OS if possible. strong requests that as strong
-* of a source of entropy as available be used. Setting strong may
-* increase the probability of blocking and should not be used for normal
-* applications. Good uses include seeding the PRNG for kadmind
-* and realm setup.
-* If successful is non-null, then successful is set to 1 if the OS provided
-* entropy else zero.
-*/
+/**
+ * Compute a checksum (operates on keyblock).
+ *
+ * @param [in] context Library context
+ * @param [in] cksumtype Checksum type (0 for mandatory type)
+ * @param [in] key Encryption key for a keyed checksum
+ * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
+ * @param [in] input Input data
+ * @param [out] cksum Generated checksum
+ *
+ * This function computes a checksum of type @a cksumtype over @a input, using
+ * @a key if the checksum type is a keyed checksum. If @a cksumtype is 0 and
+ * @a key is non-null, the checksum type will be the mandatory-to-implement
+ * checksum type for the key's encryption type. The actual checksum key will
+ * be derived from @a key and @a usage if key derivation is specified for the
+ * checksum type. The newly created @a cksum must be released by calling
+ * krb5_free_checksum_contents() when it is no longer needed.
+ *
+ * @note This function is similar to krb5_k_make_checksum(), but operates
+ * on keyblock @a key.
+ *
+ * @sa krb5_c_verify_checksum()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_c_random_os_entropy
-(krb5_context context, int strong, int *success);
+krb5_c_make_checksum(krb5_context context, krb5_cksumtype cksumtype,
+ const krb5_keyblock *key, krb5_keyusage usage,
+ const krb5_data *input, krb5_checksum *cksum);
-/*deprecated*/ krb5_error_code KRB5_CALLCONV
- krb5_c_random_seed
- (krb5_context context, krb5_data *data);
+/**
+ * Verify a checksum (operates on keyblock).
+ *
+ * @param [in] context Library context
+ * @param [in] key Encryption key for a keyed checksum
+ * @param [in] usage @a key usage
+ * @param [in] data Data to be used to compute a new checksum
+ * using @a key to compare @a cksum against
+ * @param [in] cksum Checksum to be verified
+ * @param [out] valid Non-zero for success, zero for failure
+ *
+ * This function verifies that @a cksum is a valid checksum for @a data. If
+ * the checksum type of @a cksum is a keyed checksum, @a key is used to verify
+ * the checksum. The actual checksum key will be derived from @a key and @a
+ * usage if key derivation is specified for the checksum type.
+ *
+ * @note This function is similar to krb5_k_verify_checksum(), but operates
+ * on keyblock @a key.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_c_verify_checksum(krb5_context context, const krb5_keyblock *key,
+ krb5_keyusage usage, const krb5_data *data,
+ const krb5_checksum *cksum, krb5_boolean *valid);
+/**
+ * Return the length of checksums for a checksum type.
+ *
+ * @param [in] context Library context
+ * @param [in] cksumtype Checksum type
+ * @param [out] length Checksum length
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
- krb5_c_string_to_key
- (krb5_context context, krb5_enctype enctype,
- const krb5_data *string, const krb5_data *salt,
- krb5_keyblock *key);
+krb5_c_checksum_length(krb5_context context, krb5_cksumtype cksumtype,
+ size_t *length);
+
+/**
+ * Return a list of keyed checksum types usable with an encryption type.
+ *
+ * @param [in] context Library context
+ * @param [in] enctype Encryption type
+ * @param [out] count Count of allowable checksum types
+ * @param [out] cksumtypes Array of allowable checksum types
+ *
+ * Use krb5_free_cksumtypes() to free @a cksumtypes when it is no longer
+ * needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_c_string_to_key_with_params(krb5_context context,
- krb5_enctype enctype,
- const krb5_data *string,
- const krb5_data *salt,
- const krb5_data *params,
- krb5_keyblock *key);
-
-krb5_error_code KRB5_CALLCONV
- krb5_c_enctype_compare
- (krb5_context context, krb5_enctype e1, krb5_enctype e2,
- krb5_boolean *similar);
-
-krb5_error_code KRB5_CALLCONV
- krb5_c_make_checksum
- (krb5_context context, krb5_cksumtype cksumtype,
- const krb5_keyblock *key, krb5_keyusage usage,
- const krb5_data *input, krb5_checksum *cksum);
-
-krb5_error_code KRB5_CALLCONV
- krb5_c_verify_checksum
- (krb5_context context,
- const krb5_keyblock *key, krb5_keyusage usage,
- const krb5_data *data,
- const krb5_checksum *cksum,
- krb5_boolean *valid);
-
-krb5_error_code KRB5_CALLCONV
- krb5_c_checksum_length
- (krb5_context context, krb5_cksumtype cksumtype,
- size_t *length);
-
-krb5_error_code KRB5_CALLCONV
- krb5_c_keyed_checksum_types
- (krb5_context context, krb5_enctype enctype,
- unsigned int *count, krb5_cksumtype **cksumtypes);
-
-#define KRB5_KEYUSAGE_AS_REQ_PA_ENC_TS 1
-#define KRB5_KEYUSAGE_KDC_REP_TICKET 2
-#define KRB5_KEYUSAGE_AS_REP_ENCPART 3
-#define KRB5_KEYUSAGE_TGS_REQ_AD_SESSKEY 4
-#define KRB5_KEYUSAGE_TGS_REQ_AD_SUBKEY 5
-#define KRB5_KEYUSAGE_TGS_REQ_AUTH_CKSUM 6
-#define KRB5_KEYUSAGE_TGS_REQ_AUTH 7
-#define KRB5_KEYUSAGE_TGS_REP_ENCPART_SESSKEY 8
-#define KRB5_KEYUSAGE_TGS_REP_ENCPART_SUBKEY 9
-#define KRB5_KEYUSAGE_AP_REQ_AUTH_CKSUM 10
-#define KRB5_KEYUSAGE_AP_REQ_AUTH 11
-#define KRB5_KEYUSAGE_AP_REP_ENCPART 12
-#define KRB5_KEYUSAGE_KRB_PRIV_ENCPART 13
-#define KRB5_KEYUSAGE_KRB_CRED_ENCPART 14
-#define KRB5_KEYUSAGE_KRB_SAFE_CKSUM 15
-#define KRB5_KEYUSAGE_APP_DATA_ENCRYPT 16
-#define KRB5_KEYUSAGE_APP_DATA_CKSUM 17
-#define KRB5_KEYUSAGE_KRB_ERROR_CKSUM 18
-#define KRB5_KEYUSAGE_AD_KDCISSUED_CKSUM 19
-#define KRB5_KEYUSAGE_AD_MTE 20
-#define KRB5_KEYUSAGE_AD_ITE 21
+krb5_c_keyed_checksum_types(krb5_context context, krb5_enctype enctype,
+ unsigned int *count, krb5_cksumtype **cksumtypes);
+
+/** @defgroup KRB5_KEYUSAGE KRB5_KEYUSAGE
+ * @{
+ */
+#define KRB5_KEYUSAGE_AS_REQ_PA_ENC_TS 1
+#define KRB5_KEYUSAGE_KDC_REP_TICKET 2
+#define KRB5_KEYUSAGE_AS_REP_ENCPART 3
+#define KRB5_KEYUSAGE_TGS_REQ_AD_SESSKEY 4
+#define KRB5_KEYUSAGE_TGS_REQ_AD_SUBKEY 5
+#define KRB5_KEYUSAGE_TGS_REQ_AUTH_CKSUM 6
+#define KRB5_KEYUSAGE_TGS_REQ_AUTH 7
+#define KRB5_KEYUSAGE_TGS_REP_ENCPART_SESSKEY 8
+#define KRB5_KEYUSAGE_TGS_REP_ENCPART_SUBKEY 9
+#define KRB5_KEYUSAGE_AP_REQ_AUTH_CKSUM 10
+#define KRB5_KEYUSAGE_AP_REQ_AUTH 11
+#define KRB5_KEYUSAGE_AP_REP_ENCPART 12
+#define KRB5_KEYUSAGE_KRB_PRIV_ENCPART 13
+#define KRB5_KEYUSAGE_KRB_CRED_ENCPART 14
+#define KRB5_KEYUSAGE_KRB_SAFE_CKSUM 15
+#define KRB5_KEYUSAGE_APP_DATA_ENCRYPT 16
+#define KRB5_KEYUSAGE_APP_DATA_CKSUM 17
+#define KRB5_KEYUSAGE_KRB_ERROR_CKSUM 18
+#define KRB5_KEYUSAGE_AD_KDCISSUED_CKSUM 19
+#define KRB5_KEYUSAGE_AD_MTE 20
+#define KRB5_KEYUSAGE_AD_ITE 21
/* XXX need to register these */
-#define KRB5_KEYUSAGE_GSS_TOK_MIC 22
-#define KRB5_KEYUSAGE_GSS_TOK_WRAP_INTEG 23
-#define KRB5_KEYUSAGE_GSS_TOK_WRAP_PRIV 24
+#define KRB5_KEYUSAGE_GSS_TOK_MIC 22
+#define KRB5_KEYUSAGE_GSS_TOK_WRAP_INTEG 23
+#define KRB5_KEYUSAGE_GSS_TOK_WRAP_PRIV 24
/* Defined in hardware preauth draft */
-#define KRB5_KEYUSAGE_PA_SAM_CHALLENGE_CKSUM 25
-#define KRB5_KEYUSAGE_PA_SAM_CHALLENGE_TRACKID 26
-#define KRB5_KEYUSAGE_PA_SAM_RESPONSE 27
+#define KRB5_KEYUSAGE_PA_SAM_CHALLENGE_CKSUM 25
+#define KRB5_KEYUSAGE_PA_SAM_CHALLENGE_TRACKID 26
+#define KRB5_KEYUSAGE_PA_SAM_RESPONSE 27
/* Defined in KDC referrals draft */
-#define KRB5_KEYUSAGE_PA_REFERRAL 26 /* XXX note conflict with above */
+/*
+ * @note There is a conflict with the value of @c KRB5_KEYUSAGE_PA_REFERRAL:
+ * it is used for hardware Pre-athentication @a and KDC referrals.
+ */
+#define KRB5_KEYUSAGE_PA_REFERRAL 26 /* XXX note conflict with above */
/* Defined in [MS-SFU] */
-#define KRB5_KEYUSAGE_PA_S4U_X509_USER_REQUEST 26 /* XXX note conflict with above */
-#define KRB5_KEYUSAGE_PA_S4U_X509_USER_REPLY 27 /* XXX note conflict with above */
+#define KRB5_KEYUSAGE_PA_S4U_X509_USER_REQUEST 26 /* XXX note conflict with above */
+#define KRB5_KEYUSAGE_PA_S4U_X509_USER_REPLY 27 /* XXX note conflict with above */
+#define KRB5_KEYUSAGE_AD_SIGNEDPATH -21
+#define KRB5_KEYUSAGE_IAKERB_FINISHED 42
+#define KRB5_KEYUSAGE_PA_PKINIT_KX 44
/* define in draft-ietf-krb-wg-preauth-framework*/
#define KRB5_KEYUSAGE_FAST_REQ_CHKSUM 50
#define KRB5_KEYUSAGE_FAST_ENC 51
#define KRB5_KEYUSAGE_FAST_FINISHED 53
#define KRB5_KEYUSAGE_ENC_CHALLENGE_CLIENT 54
#define KRB5_KEYUSAGE_ENC_CHALLENGE_KDC 55
+#define KRB5_KEYUSAGE_AS_REQ 56
+/** @} */ /* end of KRB5_KEYUSAGE group */
-#define KRB5_KEYUSAGE_FAST_REP 52
-krb5_boolean KRB5_CALLCONV krb5_c_valid_enctype
- (krb5_enctype ktype);
-krb5_boolean KRB5_CALLCONV krb5_c_valid_cksumtype
- (krb5_cksumtype ctype);
-krb5_boolean KRB5_CALLCONV krb5_c_is_coll_proof_cksum
- (krb5_cksumtype ctype);
-krb5_boolean KRB5_CALLCONV krb5_c_is_keyed_cksum
- (krb5_cksumtype ctype);
-
-/* AEAD APIs */
-#define KRB5_CRYPTO_TYPE_EMPTY 0 /* [in] ignored */
-#define KRB5_CRYPTO_TYPE_HEADER 1 /* [out] header */
-#define KRB5_CRYPTO_TYPE_DATA 2 /* [in, out] plaintext */
-#define KRB5_CRYPTO_TYPE_SIGN_ONLY 3 /* [in] associated data */
-#define KRB5_CRYPTO_TYPE_PADDING 4 /* [out] padding */
-#define KRB5_CRYPTO_TYPE_TRAILER 5 /* [out] checksum for encrypt */
-#define KRB5_CRYPTO_TYPE_CHECKSUM 6 /* [out] checksum for MIC */
-#define KRB5_CRYPTO_TYPE_STREAM 7 /* [in] entire message */
+/**
+ * Verify that a specified encryption type is a valid Kerberos encryption type.
+ *
+ * @param [in] ktype Encryption type
+ *
+ * @return @c TRUE if @a ktype is valid, @c FALSE if not
+ */
+krb5_boolean KRB5_CALLCONV
+krb5_c_valid_enctype(krb5_enctype ktype);
-krb5_error_code KRB5_CALLCONV
- krb5_c_make_checksum_iov
- (krb5_context context, krb5_cksumtype cksumtype,
- const krb5_keyblock *key, krb5_keyusage usage,
- krb5_crypto_iov *data, size_t num_data);
+/**
+ * Verify that specified checksum type is a valid Kerberos checksum type.
+ *
+ * @param [in] ctype Checksum type
+ *
+ * @return @c TRUE if @a ctype is valid, @c FALSE if not
+ */
+krb5_boolean KRB5_CALLCONV
+krb5_c_valid_cksumtype(krb5_cksumtype ctype);
-krb5_error_code KRB5_CALLCONV
- krb5_c_verify_checksum_iov
- (krb5_context context,
- krb5_cksumtype cksumtype,
- const krb5_keyblock *key, krb5_keyusage usage,
- const krb5_crypto_iov *data, size_t num_data,
- krb5_boolean *valid);
+/**
+ * Test whether a checksum type is collision-proof.
+ *
+ * @param [in] ctype Checksum type
+ *
+ * @return @c TRUE if @a ctype is collision-proof, @c FALSE if it is not
+ * collision-proof or not a valid checksum type.
+ */
+krb5_boolean KRB5_CALLCONV
+krb5_c_is_coll_proof_cksum(krb5_cksumtype ctype);
-krb5_error_code KRB5_CALLCONV
- krb5_c_encrypt_iov
- (krb5_context context, const krb5_keyblock *key,
- krb5_keyusage usage, const krb5_data *cipher_state,
- krb5_crypto_iov *data, size_t num_data);
+/**
+ * Test whether a checksum type is keyed.
+ *
+ * @param [in] ctype Checksum type
+ *
+ * @return @c TRUE if @a ctype is a keyed checksum type, @c FALSE otherwise.
+ */
+krb5_boolean KRB5_CALLCONV
+krb5_c_is_keyed_cksum(krb5_cksumtype ctype);
+/* AEAD APIs */
+/** @defgroup KRB5_CRYPTO_TYPE KRB5_CRYPTO_TYPE
+ * @{
+ */
+#define KRB5_CRYPTO_TYPE_EMPTY 0 /**< [in] ignored */
+#define KRB5_CRYPTO_TYPE_HEADER 1 /**< [out] header */
+#define KRB5_CRYPTO_TYPE_DATA 2 /**< [in, out] plaintext */
+#define KRB5_CRYPTO_TYPE_SIGN_ONLY 3 /**< [in] associated data */
+#define KRB5_CRYPTO_TYPE_PADDING 4 /**< [out] padding */
+#define KRB5_CRYPTO_TYPE_TRAILER 5 /**< [out] checksum for encrypt */
+#define KRB5_CRYPTO_TYPE_CHECKSUM 6 /**< [out] checksum for MIC */
+#define KRB5_CRYPTO_TYPE_STREAM 7 /**< [in] entire message without
+ decomposing the structure into
+ header, data and trailer buffers */
+/** @} */ /* end of KRB5_CRYPTO_TYPE group */
+
+/**
+ * Fill in a checksum element in IOV array (operates on keyblock)
+ *
+ * @param [in] context Library context
+ * @param [in] cksumtype Checksum type (0 for mandatory type)
+ * @param [in] key Encryption key for a keyed checksum
+ * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
+ * @param [in,out] data IOV array
+ * @param [in] num_data Size of @a data
+ *
+ * Create a checksum in the #KRB5_CRYPTO_TYPE_CHECKSUM element over
+ * #KRB5_CRYPTO_TYPE_DATA and #KRB5_CRYPTO_TYPE_SIGN_ONLY chunks in @a data.
+ * Only the #KRB5_CRYPTO_TYPE_CHECKSUM region is modified.
+ *
+ * @note This function is similar to krb5_k_make_checksum_iov(), but operates
+ * on keyblock @a key.
+ *
+ * @sa krb5_c_verify_checksum_iov()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
- krb5_c_decrypt_iov
- (krb5_context context, const krb5_keyblock *key,
- krb5_keyusage usage, const krb5_data *cipher_state,
- krb5_crypto_iov *data, size_t num_data);
+krb5_c_make_checksum_iov(krb5_context context, krb5_cksumtype cksumtype,
+ const krb5_keyblock *key, krb5_keyusage usage,
+ krb5_crypto_iov *data, size_t num_data);
+/**
+ * Validate a checksum element in IOV array (operates on keyblock).
+ *
+ * @param [in] context Library context
+ * @param [in] cksumtype Checksum type (0 for mandatory type)
+ * @param [in] key Encryption key for a keyed checksum
+ * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
+ * @param [in] data IOV array
+ * @param [in] num_data Size of @a data
+ * @param [out] valid Non-zero for success, zero for failure
+ *
+ * Confirm that the checksum in the #KRB5_CRYPTO_TYPE_CHECKSUM element is a
+ * valid checksum of the #KRB5_CRYPTO_TYPE_DATA and #KRB5_CRYPTO_TYPE_SIGN_ONLY
+ * regions in the iov.
+ *
+ * @note This function is similar to krb5_k_verify_checksum_iov(), but operates
+ * on keyblock @a key.
+ *
+ * @sa krb5_c_make_checksum_iov()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
- krb5_c_crypto_length
- (krb5_context context, krb5_enctype enctype,
- krb5_cryptotype type, unsigned int *size);
+krb5_c_verify_checksum_iov(krb5_context context, krb5_cksumtype cksumtype,
+ const krb5_keyblock *key, krb5_keyusage usage,
+ const krb5_crypto_iov *data, size_t num_data,
+ krb5_boolean *valid);
+/**
+ * Encrypt data in place supporting AEAD (operates on keyblock).
+ *
+ * @param [in] context Library context
+ * @param [in] keyblock Encryption key
+ * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
+ * @param [in] cipher_state Cipher state; specify NULL if not needed
+ * @param [in,out] data IOV array. Modified in-place.
+ * @param [in] num_data Size of @a data
+ *
+ * This function encrypts the data block @a data and stores the output in-place.
+ * The actual encryption key will be derived from @a keyblock and @a usage
+ * if key derivation is specified for the encryption type. If non-null, @a
+ * cipher_state specifies the beginning state for the encryption operation, and
+ * is updated with the state to be passed as input to the next operation.
+ * The caller must allocate the right number of krb5_crypto_iov
+ * structures before calling into this API.
+ *
+ * @note On return from a krb5_c_encrypt_iov() call, the @a data->length in the
+ * iov structure are adjusted to reflect actual lengths of the ciphertext used.
+ * For example, if the padding length is too large, the length will be reduced.
+ * Lengths are never increased.
+ *
+ * @note This function is similar to krb5_k_encrypt_iov(), but operates
+ * on keyblock @a keyblock.
+ *
+ * @sa krb5_c_decrypt_iov()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
- krb5_c_crypto_length_iov
- (krb5_context context, krb5_enctype enctype,
- krb5_crypto_iov *data, size_t num_data);
+krb5_c_encrypt_iov(krb5_context context, const krb5_keyblock *keyblock,
+ krb5_keyusage usage, const krb5_data *cipher_state,
+ krb5_crypto_iov *data, size_t num_data);
+/**
+ * Decrypt data in place supporting AEAD (operates on keyblock).
+ *
+ * @param [in] context Library context
+ * @param [in] keyblock Encryption key
+ * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
+ * @param [in] cipher_state Cipher state; specify NULL if not needed
+ * @param [in,out] data IOV array. Modified in-place.
+ * @param [in] num_data Size of @a data
+ *
+ * This function decrypts the data block @a data and stores the output in-place.
+ * The actual decryption key will be derived from @a keyblock and @a usage
+ * if key derivation is specified for the encryption type. If non-null, @a
+ * cipher_state specifies the beginning state for the decryption operation, and
+ * is updated with the state to be passed as input to the next operation.
+ * The caller must allocate the right number of krb5_crypto_iov
+ * structures before calling into this API.
+ *
+ * @note On return from a krb5_c_decrypt_iov() call, the @a data->length in the
+ * iov structure are adjusted to reflect actual lengths of the ciphertext used.
+ * For example, if the padding length is too large, the length will be reduced.
+ * Lengths are never increased.
+ *
+ * @note This function is similar to krb5_k_decrypt_iov(), but operates
+ * on keyblock @a keyblock.
+ *
+ * @sa krb5_c_decrypt_iov()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
- krb5_c_padding_length
- (krb5_context context, krb5_enctype enctype,
- size_t data_length, unsigned int *size);
+krb5_c_decrypt_iov(krb5_context context, const krb5_keyblock *keyblock,
+ krb5_keyusage usage, const krb5_data *cipher_state,
+ krb5_crypto_iov *data, size_t num_data);
-#ifdef KRB5_OLD_CRYPTO
-/*
- * old cryptosystem routine prototypes. These are now layered
- * on top of the functions above.
+/**
+ * Return a length of a message field specific to the encryption type.
+ *
+ * @param [in] context Library context
+ * @param [in] enctype Encryption type
+ * @param [in] type Type field (See @ref KRB5_CRYPTO_TYPE types)
+ * @param [out] size Length of the @a type specific to @a enctype
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
*/
-krb5_error_code KRB5_CALLCONV krb5_encrypt
- (krb5_context context,
- krb5_const_pointer inptr,
- krb5_pointer outptr,
- size_t size,
- krb5_encrypt_block * eblock,
- krb5_pointer ivec);
-krb5_error_code KRB5_CALLCONV krb5_decrypt
- (krb5_context context,
- krb5_const_pointer inptr,
- krb5_pointer outptr,
- size_t size,
- krb5_encrypt_block * eblock,
- krb5_pointer ivec);
-krb5_error_code KRB5_CALLCONV krb5_process_key
- (krb5_context context,
- krb5_encrypt_block * eblock,
- const krb5_keyblock * key);
-krb5_error_code KRB5_CALLCONV krb5_finish_key
- (krb5_context context,
- krb5_encrypt_block * eblock);
-krb5_error_code KRB5_CALLCONV krb5_string_to_key
- (krb5_context context,
- const krb5_encrypt_block * eblock,
- krb5_keyblock * keyblock,
- const krb5_data * data,
- const krb5_data * salt);
-krb5_error_code KRB5_CALLCONV krb5_init_random_key
- (krb5_context context,
- const krb5_encrypt_block * eblock,
- const krb5_keyblock * keyblock,
- krb5_pointer * ptr);
-krb5_error_code KRB5_CALLCONV krb5_finish_random_key
- (krb5_context context,
- const krb5_encrypt_block * eblock,
- krb5_pointer * ptr);
-krb5_error_code KRB5_CALLCONV krb5_random_key
- (krb5_context context,
- const krb5_encrypt_block * eblock,
- krb5_pointer ptr,
- krb5_keyblock ** keyblock);
-krb5_enctype KRB5_CALLCONV krb5_eblock_enctype
- (krb5_context context,
- const krb5_encrypt_block * eblock);
-krb5_error_code KRB5_CALLCONV krb5_use_enctype
- (krb5_context context,
- krb5_encrypt_block * eblock,
- krb5_enctype enctype);
-size_t KRB5_CALLCONV krb5_encrypt_size
- (size_t length,
- krb5_enctype crypto);
-size_t KRB5_CALLCONV krb5_checksum_size
- (krb5_context context,
- krb5_cksumtype ctype);
-krb5_error_code KRB5_CALLCONV krb5_calculate_checksum
- (krb5_context context,
- krb5_cksumtype ctype,
- krb5_const_pointer in, size_t in_length,
- krb5_const_pointer seed, size_t seed_length,
- krb5_checksum * outcksum);
-krb5_error_code KRB5_CALLCONV krb5_verify_checksum
- (krb5_context context,
- krb5_cksumtype ctype,
- const krb5_checksum * cksum,
- krb5_const_pointer in, size_t in_length,
- krb5_const_pointer seed, size_t seed_length);
-
-#endif /* KRB5_OLD_CRYPTO */
+krb5_error_code KRB5_CALLCONV
+krb5_c_crypto_length(krb5_context context, krb5_enctype enctype,
+ krb5_cryptotype type, unsigned int *size);
-/*
- * end "encryption.h"
+/**
+ * Fill in lengths for header, trailer and padding in a IOV array.
+ *
+ * @param [in] context Library context
+ * @param [in] enctype Encryption type
+ * @param [in,out] data IOV array
+ * @param [in] num_data Size of @a data
+ *
+ * Padding is set to the actual padding required based on the provided
+ * @a data buffers. Typically this API is used after setting up the data
+ * buffers and #KRB5_CRYPTO_TYPE_SIGN_ONLY buffers, but before actually
+ * allocating header, trailer and padding.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
*/
+krb5_error_code KRB5_CALLCONV
+krb5_c_crypto_length_iov(krb5_context context, krb5_enctype enctype,
+ krb5_crypto_iov *data, size_t num_data);
-/*
- * begin "fieldbits.h"
+/**
+ * Return a number of padding octets.
+ *
+ * @param [in] context Library context
+ * @param [in] enctype Encryption type
+ * @param [in] data_length Length of the plaintext to pad
+ * @param [out] size Number of padding octets
+ *
+ * This function returns the number of the padding octets required to pad
+ * @a data_length octets of plaintext.
+ *
+ * @retval 0 Success; otherwise - KRB5_BAD_ENCTYPE
*/
+krb5_error_code KRB5_CALLCONV
+krb5_c_padding_length(krb5_context context, krb5_enctype enctype,
+ size_t data_length, unsigned int *size);
-/* kdc_options for kdc_request */
-/* options is 32 bits; each host is responsible to put the 4 bytes
- representing these bits into net order before transmission */
-/* #define KDC_OPT_RESERVED 0x80000000 */
-#define KDC_OPT_FORWARDABLE 0x40000000
-#define KDC_OPT_FORWARDED 0x20000000
-#define KDC_OPT_PROXIABLE 0x10000000
-#define KDC_OPT_PROXY 0x08000000
-#define KDC_OPT_ALLOW_POSTDATE 0x04000000
-#define KDC_OPT_POSTDATED 0x02000000
-/* #define KDC_OPT_UNUSED 0x01000000 */
-#define KDC_OPT_RENEWABLE 0x00800000
-/* #define KDC_OPT_UNUSED 0x00400000 */
-/* #define KDC_OPT_RESERVED 0x00200000 */
-/* #define KDC_OPT_RESERVED 0x00100000 */
-/* #define KDC_OPT_RESERVED 0x00080000 */
-/* #define KDC_OPT_RESERVED 0x00040000 */
-#define KDC_OPT_REQUEST_ANONYMOUS 0x00020000
-#define KDC_OPT_CNAME_IN_ADDL_TKT 0x00020000
-#define KDC_OPT_CANONICALIZE 0x00010000
-/* #define KDC_OPT_RESERVED 0x00008000 */
-/* #define KDC_OPT_RESERVED 0x00004000 */
-/* #define KDC_OPT_RESERVED 0x00002000 */
-/* #define KDC_OPT_RESERVED 0x00001000 */
-/* #define KDC_OPT_RESERVED 0x00000800 */
-/* #define KDC_OPT_RESERVED 0x00000400 */
-/* #define KDC_OPT_RESERVED 0x00000200 */
-/* #define KDC_OPT_RESERVED 0x00000100 */
-/* #define KDC_OPT_RESERVED 0x00000080 */
-/* #define KDC_OPT_RESERVED 0x00000040 */
-#define KDC_OPT_DISABLE_TRANSITED_CHECK 0x00000020
-#define KDC_OPT_RENEWABLE_OK 0x00000010
-#define KDC_OPT_ENC_TKT_IN_SKEY 0x00000008
-/* #define KDC_OPT_UNUSED 0x00000004 */
-#define KDC_OPT_RENEW 0x00000002
-#define KDC_OPT_VALIDATE 0x00000001
-
-/*
- * Mask of ticket flags in the TGT which should be converted into KDC
- * options when using the TGT to get derivitive tickets.
- *
- * New mask = KDC_OPT_FORWARDABLE | KDC_OPT_PROXIABLE |
- * KDC_OPT_ALLOW_POSTDATE | KDC_OPT_RENEWABLE
+/**
+ * Create a krb5_key from the enctype and key data in a keyblock.
+ *
+ * @param [in] context Library context
+ * @param [in] key_data Keyblock
+ * @param [out] out Opaque key
+ *
+ * The reference count on a key @a out is set to 1.
+ * Use krb5_k_free_key() to free @a out when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - KRB5_BAD_ENCTYPE
*/
-#define KDC_TKT_COMMON_MASK 0x54800000
-
-/* definitions for ap_options fields */
-/* ap_options are 32 bits; each host is responsible to put the 4 bytes
- representing these bits into net order before transmission */
-#define AP_OPTS_RESERVED 0x80000000
-#define AP_OPTS_USE_SESSION_KEY 0x40000000
-#define AP_OPTS_MUTUAL_REQUIRED 0x20000000
-/* #define AP_OPTS_RESERVED 0x10000000 */
-/* #define AP_OPTS_RESERVED 0x08000000 */
-/* #define AP_OPTS_RESERVED 0x04000000 */
-/* #define AP_OPTS_RESERVED 0x02000000 */
-/* #define AP_OPTS_RESERVED 0x01000000 */
-/* #define AP_OPTS_RESERVED 0x00800000 */
-/* #define AP_OPTS_RESERVED 0x00400000 */
-/* #define AP_OPTS_RESERVED 0x00200000 */
-/* #define AP_OPTS_RESERVED 0x00100000 */
-/* #define AP_OPTS_RESERVED 0x00080000 */
-/* #define AP_OPTS_RESERVED 0x00040000 */
-/* #define AP_OPTS_RESERVED 0x00020000 */
-/* #define AP_OPTS_RESERVED 0x00010000 */
-/* #define AP_OPTS_RESERVED 0x00008000 */
-/* #define AP_OPTS_RESERVED 0x00004000 */
-/* #define AP_OPTS_RESERVED 0x00002000 */
-/* #define AP_OPTS_RESERVED 0x00001000 */
-/* #define AP_OPTS_RESERVED 0x00000800 */
-/* #define AP_OPTS_RESERVED 0x00000400 */
-/* #define AP_OPTS_RESERVED 0x00000200 */
-/* #define AP_OPTS_RESERVED 0x00000100 */
-/* #define AP_OPTS_RESERVED 0x00000080 */
-/* #define AP_OPTS_RESERVED 0x00000040 */
-/* #define AP_OPTS_RESERVED 0x00000020 */
-/* #define AP_OPTS_RESERVED 0x00000010 */
-/* #define AP_OPTS_RESERVED 0x00000008 */
-/* #define AP_OPTS_RESERVED 0x00000004 */
-#define AP_OPTS_ETYPE_NEGOTIATION 0x00000002
-#define AP_OPTS_USE_SUBKEY 0x00000001
-
-#define AP_OPTS_WIRE_MASK 0xfffffff0
-
-/* definitions for ad_type fields. */
-#define AD_TYPE_RESERVED 0x8000
-#define AD_TYPE_EXTERNAL 0x4000
-#define AD_TYPE_REGISTERED 0x2000
-
-#define AD_TYPE_FIELD_TYPE_MASK 0x1fff
+krb5_error_code KRB5_CALLCONV
+krb5_k_create_key(krb5_context context, const krb5_keyblock *key_data,
+ krb5_key *out);
-/* Ticket flags */
-/* flags are 32 bits; each host is responsible to put the 4 bytes
- representing these bits into net order before transmission */
-/* #define TKT_FLG_RESERVED 0x80000000 */
-#define TKT_FLG_FORWARDABLE 0x40000000
-#define TKT_FLG_FORWARDED 0x20000000
-#define TKT_FLG_PROXIABLE 0x10000000
-#define TKT_FLG_PROXY 0x08000000
-#define TKT_FLG_MAY_POSTDATE 0x04000000
-#define TKT_FLG_POSTDATED 0x02000000
-#define TKT_FLG_INVALID 0x01000000
-#define TKT_FLG_RENEWABLE 0x00800000
-#define TKT_FLG_INITIAL 0x00400000
-#define TKT_FLG_PRE_AUTH 0x00200000
-#define TKT_FLG_HW_AUTH 0x00100000
-#define TKT_FLG_TRANSIT_POLICY_CHECKED 0x00080000
-#define TKT_FLG_OK_AS_DELEGATE 0x00040000
-#define TKT_FLG_ANONYMOUS 0x00020000
-/* #define TKT_FLG_RESERVED 0x00010000 */
-/* #define TKT_FLG_RESERVED 0x00008000 */
-/* #define TKT_FLG_RESERVED 0x00004000 */
-/* #define TKT_FLG_RESERVED 0x00002000 */
-/* #define TKT_FLG_RESERVED 0x00001000 */
-/* #define TKT_FLG_RESERVED 0x00000800 */
-/* #define TKT_FLG_RESERVED 0x00000400 */
-/* #define TKT_FLG_RESERVED 0x00000200 */
-/* #define TKT_FLG_RESERVED 0x00000100 */
-/* #define TKT_FLG_RESERVED 0x00000080 */
-/* #define TKT_FLG_RESERVED 0x00000040 */
-/* #define TKT_FLG_RESERVED 0x00000020 */
-/* #define TKT_FLG_RESERVED 0x00000010 */
-/* #define TKT_FLG_RESERVED 0x00000008 */
-/* #define TKT_FLG_RESERVED 0x00000004 */
-/* #define TKT_FLG_RESERVED 0x00000002 */
-/* #define TKT_FLG_RESERVED 0x00000001 */
+/** Increment the reference count on a key. */
+void KRB5_CALLCONV
+krb5_k_reference_key(krb5_context context, krb5_key key);
-/* definitions for lr_type fields. */
-#define LR_TYPE_THIS_SERVER_ONLY 0x8000
+/** Decrement the reference count on a key and free it if it hits zero. */
+void KRB5_CALLCONV
+krb5_k_free_key(krb5_context context, krb5_key key);
-#define LR_TYPE_INTERPRETATION_MASK 0x7fff
+/** Retrieve a copy of the keyblock from a krb5_key structure. */
+krb5_error_code KRB5_CALLCONV
+krb5_k_key_keyblock(krb5_context context, krb5_key key,
+ krb5_keyblock **key_data);
-/* definitions for msec direction bit for KRB_SAFE, KRB_PRIV */
-#define MSEC_DIRBIT 0x8000
-#define MSEC_VAL_MASK 0x7fff
+/** Retrieve the enctype of a krb5_key structure. */
+krb5_enctype KRB5_CALLCONV
+krb5_k_key_enctype(krb5_context context, krb5_key key);
-/*
- * end "fieldbits.h"
+/**
+ * Encrypt data using a key (operates on opaque key).
+ *
+ * @param [in] context Library context
+ * @param [in] key Encryption key
+ * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
+ * @param [in,out] cipher_state Cipher state; specify NULL if not needed
+ * @param [in] input Data to be encrypted
+ * @param [out] output Encrypted data
+ *
+ * This function encrypts the data block @a input and stores the output into @a
+ * output. The actual encryption key will be derived from @a key and @a usage
+ * if key derivation is specified for the encryption type. If non-null, @a
+ * cipher_state specifies the beginning state for the encryption operation, and
+ * is updated with the state to be passed as input to the next operation.
+ *
+ * @note The caller must initialize @a output and allocate at least enough
+ * space for the result (using krb5_c_encrypt_length() to determine the amount
+ * of space needed). @a output->length will be set to the actual length of the
+ * ciphertext.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
*/
+krb5_error_code KRB5_CALLCONV
+krb5_k_encrypt(krb5_context context, krb5_key key, krb5_keyusage usage,
+ const krb5_data *cipher_state, const krb5_data *input,
+ krb5_enc_data *output);
-/*
- * begin "proto.h"
+/**
+ * Encrypt data in place supporting AEAD (operates on opaque key).
+ *
+ * @param [in] context Library context
+ * @param [in] key Encryption key
+ * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
+ * @param [in] cipher_state Cipher state; specify NULL if not needed
+ * @param [in,out] data IOV array. Modified in-place.
+ * @param [in] num_data Size of @a data
+ *
+ * This function encrypts the data block @a data and stores the output in-place.
+ * The actual encryption key will be derived from @a key and @a usage
+ * if key derivation is specified for the encryption type. If non-null, @a
+ * cipher_state specifies the beginning state for the encryption operation, and
+ * is updated with the state to be passed as input to the next operation.
+ * The caller must allocate the right number of krb5_crypto_iov
+ * structures before calling into this API.
+ *
+ * @note On return from a krb5_c_encrypt_iov() call, the @a data->length in the
+ * iov structure are adjusted to reflect actual lengths of the ciphertext used.
+ * For example, if the padding length is too large, the length will be reduced.
+ * Lengths are never increased.
+ *
+ * @note This function is similar to krb5_c_encrypt_iov(), but operates
+ * on opaque key @a key.
+ *
+ * @sa krb5_k_decrypt_iov()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
*/
+krb5_error_code KRB5_CALLCONV
+krb5_k_encrypt_iov(krb5_context context, krb5_key key, krb5_keyusage usage,
+ const krb5_data *cipher_state, krb5_crypto_iov *data,
+ size_t num_data);
-/* Protocol version number */
-#define KRB5_PVNO 5
-
-/* Message types */
-
-#define KRB5_AS_REQ ((krb5_msgtype)10) /* Req for initial authentication */
-#define KRB5_AS_REP ((krb5_msgtype)11) /* Response to KRB_AS_REQ request */
-#define KRB5_TGS_REQ ((krb5_msgtype)12) /* TGS request to server */
-#define KRB5_TGS_REP ((krb5_msgtype)13) /* Response to KRB_TGS_REQ req */
-#define KRB5_AP_REQ ((krb5_msgtype)14) /* application request to server */
-#define KRB5_AP_REP ((krb5_msgtype)15) /* Response to KRB_AP_REQ_MUTUAL */
-#define KRB5_SAFE ((krb5_msgtype)20) /* Safe application message */
-#define KRB5_PRIV ((krb5_msgtype)21) /* Private application message */
-#define KRB5_CRED ((krb5_msgtype)22) /* Credential forwarding message */
-#define KRB5_ERROR ((krb5_msgtype)30) /* Error response */
+/**
+ * Decrypt data using a key (operates on opaque key).
+ *
+ * @param [in] context Library context
+ * @param [in] key Encryption key
+ * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
+ * @param [in,out] cipher_state Cipher state; specify NULL if not needed
+ * @param [in] input Encrypted data
+ * @param [out] output Decrypted data
+ *
+ * This function decrypts the data block @a input and stores the output into @a
+ * output. The actual decryption key will be derived from @a key and @a usage
+ * if key derivation is specified for the encryption type. If non-null, @a
+ * cipher_state specifies the beginning state for the decryption operation, and
+ * is updated with the state to be passed as input to the next operation.
+ *
+ * @note The caller must initialize @a output and allocate at least enough
+ * space for the result. The usual practice is to allocate an output buffer as
+ * long as the ciphertext, and let krb5_c_decrypt() trim @a output->length.
+ * For some enctypes, the resulting @a output->length may include padding
+ * bytes.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_k_decrypt(krb5_context context, krb5_key key, krb5_keyusage usage,
+ const krb5_data *cipher_state, const krb5_enc_data *input,
+ krb5_data *output);
+
+/**
+ * Decrypt data in place supporting AEAD (operates on opaque key).
+ *
+ * @param [in] context Library context
+ * @param [in] key Encryption key
+ * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
+ * @param [in] cipher_state Cipher state; specify NULL if not needed
+ * @param [in,out] data IOV array. Modified in-place.
+ * @param [in] num_data Size of @a data
+ *
+ * This function decrypts the data block @a data and stores the output in-place.
+ * The actual decryption key will be derived from @a key and @a usage
+ * if key derivation is specified for the encryption type. If non-null, @a
+ * cipher_state specifies the beginning state for the decryption operation, and
+ * is updated with the state to be passed as input to the next operation.
+ * The caller must allocate the right number of krb5_crypto_iov
+ * structures before calling into this API.
+ *
+ * @note On return from a krb5_c_decrypt_iov() call, the @a data->length in the
+ * iov structure are adjusted to reflect actual lengths of the ciphertext used.
+ * For example, if the padding length is too large, the length will be reduced.
+ * Lengths are never increased.
+ *
+ * @note This function is similar to krb5_c_decrypt_iov(), but operates
+ * on opaque key @a key.
+ *
+ * @sa krb5_k_encrypt_iov()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_k_decrypt_iov(krb5_context context, krb5_key key, krb5_keyusage usage,
+ const krb5_data *cipher_state, krb5_crypto_iov *data,
+ size_t num_data);
+/**
+ * Compute a checksum (operates on opaque key).
+ *
+ * @param [in] context Library context
+ * @param [in] cksumtype Checksum type (0 for mandatory type)
+ * @param [in] key Encryption key for a keyed checksum
+ * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
+ * @param [in] input Input data
+ * @param [out] cksum Generated checksum
+ *
+ * This function computes a checksum of type @a cksumtype over @a input, using
+ * @a key if the checksum type is a keyed checksum. If @a cksumtype is 0 and
+ * @a key is non-null, the checksum type will be the mandatory-to-implement
+ * checksum type for the key's encryption type. The actual checksum key will
+ * be derived from @a key and @a usage if key derivation is specified for the
+ * checksum type. The newly created @a cksum must be released by calling
+ * krb5_free_checksum_contents() when it is no longer needed.
+ *
+ * @note This function is similar to krb5_c_make_checksum(), but operates
+ * on opaque @a key.
+ *
+ * @sa krb5_c_verify_checksum()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_k_make_checksum(krb5_context context, krb5_cksumtype cksumtype,
+ krb5_key key, krb5_keyusage usage, const krb5_data *input,
+ krb5_checksum *cksum);
+
+/**
+ * Fill in a checksum element in IOV array (operates on opaque key)
+ *
+ * @param [in] context Library context
+ * @param [in] cksumtype Checksum type (0 for mandatory type)
+ * @param [in] key Encryption key for a keyed checksum
+ * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
+ * @param [in,out] data IOV array
+ * @param [in] num_data Size of @a data
+ *
+ * Create a checksum in the #KRB5_CRYPTO_TYPE_CHECKSUM element over
+ * #KRB5_CRYPTO_TYPE_DATA and #KRB5_CRYPTO_TYPE_SIGN_ONLY chunks in @a data.
+ * Only the #KRB5_CRYPTO_TYPE_CHECKSUM region is modified.
+ *
+ * @note This function is similar to krb5_c_make_checksum_iov(), but operates
+ * on opaque @a key.
+ *
+ * @sa krb5_k_verify_checksum_iov()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_k_make_checksum_iov(krb5_context context, krb5_cksumtype cksumtype,
+ krb5_key key, krb5_keyusage usage,
+ krb5_crypto_iov *data, size_t num_data);
+
+/**
+ * Verify a checksum (operates on opaque key).
+ *
+ * @param [in] context Library context
+ * @param [in] key Encryption key for a keyed checksum
+ * @param [in] usage @a key usage
+ * @param [in] data Data to be used to compute a new checksum
+ * using @a key to compare @a cksum against
+ * @param [in] cksum Checksum to be verified
+ * @param [out] valid Non-zero for success, zero for failure
+ *
+ * This function verifies that @a cksum is a valid checksum for @a data. If
+ * the checksum type of @a cksum is a keyed checksum, @a key is used to verify
+ * the checksum. The actual checksum key will be derived from @a key and @a
+ * usage if key derivation is specified for the checksum type.
+ *
+ * @note This function is similar to krb5_c_verify_checksum(), but operates
+ * on opaque @a key.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_k_verify_checksum(krb5_context context, krb5_key key, krb5_keyusage usage,
+ const krb5_data *data, const krb5_checksum *cksum,
+ krb5_boolean *valid);
+
+/**
+ * Validate a checksum element in IOV array (operates on opaque key).
+ *
+ * @param [in] context Library context
+ * @param [in] cksumtype Checksum type (0 for mandatory type)
+ * @param [in] key Encryption key for a keyed checksum
+ * @param [in] usage Key usage (see @ref KRB5_KEYUSAGE types)
+ * @param [in] data IOV array
+ * @param [in] num_data Size of @a data
+ * @param [out] valid Non-zero for success, zero for failure
+ *
+ * Confirm that the checksum in the #KRB5_CRYPTO_TYPE_CHECKSUM element is a
+ * valid checksum of the #KRB5_CRYPTO_TYPE_DATA and #KRB5_CRYPTO_TYPE_SIGN_ONLY
+ * regions in the iov.
+ *
+ * @note This function is similar to krb5_c_verify_checksum_iov(), but operates
+ * on opaque @a key.
+ *
+ * @sa krb5_k_make_checksum_iov()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_k_verify_checksum_iov(krb5_context context, krb5_cksumtype cksumtype,
+ krb5_key key, krb5_keyusage usage,
+ const krb5_crypto_iov *data, size_t num_data,
+ krb5_boolean *valid);
+
+/**
+ * Generate enctype-specific pseudo-random bytes (operates on opaque key).
+ *
+ * @param [in] context Library context
+ * @param [in] key Key
+ * @param [in] input Input data
+ * @param [out] output Output data
+ *
+ * This function selects a pseudo-random function based on @a key and
+ * computes its value over @a input, placing the result into @a output.
+ * The caller must preinitialize @a output and allocate space for the
+ * result.
+ *
+ * @note This function is similar to krb5_c_prf(), but operates
+ * on opaque @a key.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_k_prf(krb5_context context, krb5_key key, krb5_data *input, krb5_data *output);
+
+#ifdef KRB5_OLD_CRYPTO
+/*
+ * old cryptosystem routine prototypes. These are now layered
+ * on top of the functions above.
+ */
+/** @deprecated Replaced by krb5_c_ API family.*/
+krb5_error_code KRB5_CALLCONV
+krb5_encrypt(krb5_context context, krb5_const_pointer inptr,
+ krb5_pointer outptr, size_t size, krb5_encrypt_block *eblock,
+ krb5_pointer ivec);
+
+/** @deprecated Replaced by krb5_c_ API family. */
+krb5_error_code KRB5_CALLCONV
+krb5_decrypt(krb5_context context, krb5_const_pointer inptr,
+ krb5_pointer outptr, size_t size, krb5_encrypt_block *eblock,
+ krb5_pointer ivec);
+
+/** @deprecated Replaced by krb5_c_ API family. */
+krb5_error_code KRB5_CALLCONV
+krb5_process_key(krb5_context context, krb5_encrypt_block *eblock,
+ const krb5_keyblock * key);
+
+/** @deprecated Replaced by krb5_c_ API family. */
+krb5_error_code KRB5_CALLCONV
+krb5_finish_key(krb5_context context, krb5_encrypt_block * eblock);
+
+/** @deprecated See krb5_c_string_to_key() */
+krb5_error_code KRB5_CALLCONV
+krb5_string_to_key(krb5_context context, const krb5_encrypt_block *eblock,
+ krb5_keyblock * keyblock, const krb5_data *data,
+ const krb5_data *salt);
+
+/** @deprecated Replaced by krb5_c_ API family. */
+krb5_error_code KRB5_CALLCONV
+krb5_init_random_key(krb5_context context, const krb5_encrypt_block *eblock,
+ const krb5_keyblock *keyblock, krb5_pointer *ptr);
+
+/** @deprecated Replaced by krb5_c_ API family. */
+krb5_error_code KRB5_CALLCONV
+krb5_finish_random_key(krb5_context context, const krb5_encrypt_block *eblock,
+ krb5_pointer *ptr);
+
+/** @deprecated Replaced by krb5_c_ API family. */
+krb5_error_code KRB5_CALLCONV
+krb5_random_key(krb5_context context, const krb5_encrypt_block *eblock,
+ krb5_pointer ptr, krb5_keyblock **keyblock);
+
+/** @deprecated Replaced by krb5_c_ API family. */
+krb5_enctype KRB5_CALLCONV
+krb5_eblock_enctype(krb5_context context, const krb5_encrypt_block *eblock);
+
+/** @deprecated Replaced by krb5_c_ API family. */
+krb5_error_code KRB5_CALLCONV
+krb5_use_enctype(krb5_context context, krb5_encrypt_block *eblock,
+ krb5_enctype enctype);
+
+/** @deprecated Replaced by krb5_c_ API family. */
+size_t KRB5_CALLCONV
+krb5_encrypt_size(size_t length, krb5_enctype crypto);
+
+/** @deprecated See krb5_c_checksum_length() */
+size_t KRB5_CALLCONV
+krb5_checksum_size(krb5_context context, krb5_cksumtype ctype);
+
+/** @deprecated See krb5_c_make_checksum() */
+krb5_error_code KRB5_CALLCONV
+krb5_calculate_checksum(krb5_context context, krb5_cksumtype ctype,
+ krb5_const_pointer in, size_t in_length,
+ krb5_const_pointer seed, size_t seed_length,
+ krb5_checksum * outcksum);
+
+/** @deprecated See krb5_c_verify_checksum() */
+krb5_error_code KRB5_CALLCONV
+krb5_verify_checksum(krb5_context context, krb5_cksumtype ctype,
+ const krb5_checksum * cksum, krb5_const_pointer in,
+ size_t in_length, krb5_const_pointer seed,
+ size_t seed_length);
+
+#endif /* KRB5_OLD_CRYPTO */
+
+/*
+ * end "encryption.h"
+ */
+
+/*
+ * begin "fieldbits.h"
+ */
+
+/* kdc_options for kdc_request */
+/* options is 32 bits; each host is responsible to put the 4 bytes
+ representing these bits into net order before transmission */
+/* #define KDC_OPT_RESERVED 0x80000000 */
+#define KDC_OPT_FORWARDABLE 0x40000000
+#define KDC_OPT_FORWARDED 0x20000000
+#define KDC_OPT_PROXIABLE 0x10000000
+#define KDC_OPT_PROXY 0x08000000
+#define KDC_OPT_ALLOW_POSTDATE 0x04000000
+#define KDC_OPT_POSTDATED 0x02000000
+/* #define KDC_OPT_UNUSED 0x01000000 */
+#define KDC_OPT_RENEWABLE 0x00800000
+/* #define KDC_OPT_UNUSED 0x00400000 */
+/* #define KDC_OPT_RESERVED 0x00200000 */
+/* #define KDC_OPT_RESERVED 0x00100000 */
+/* #define KDC_OPT_RESERVED 0x00080000 */
+/* #define KDC_OPT_RESERVED 0x00040000 */
+#define KDC_OPT_CNAME_IN_ADDL_TKT 0x00020000
+#define KDC_OPT_CANONICALIZE 0x00010000
+#define KDC_OPT_REQUEST_ANONYMOUS 0x00008000
+/* #define KDC_OPT_RESERVED 0x00004000 */
+/* #define KDC_OPT_RESERVED 0x00002000 */
+/* #define KDC_OPT_RESERVED 0x00001000 */
+/* #define KDC_OPT_RESERVED 0x00000800 */
+/* #define KDC_OPT_RESERVED 0x00000400 */
+/* #define KDC_OPT_RESERVED 0x00000200 */
+/* #define KDC_OPT_RESERVED 0x00000100 */
+/* #define KDC_OPT_RESERVED 0x00000080 */
+/* #define KDC_OPT_RESERVED 0x00000040 */
+#define KDC_OPT_DISABLE_TRANSITED_CHECK 0x00000020
+#define KDC_OPT_RENEWABLE_OK 0x00000010
+#define KDC_OPT_ENC_TKT_IN_SKEY 0x00000008
+/* #define KDC_OPT_UNUSED 0x00000004 */
+#define KDC_OPT_RENEW 0x00000002
+#define KDC_OPT_VALIDATE 0x00000001
+
+/*
+ * Mask of ticket flags in the TGT which should be converted into KDC
+ * options when using the TGT to get derivitive tickets.
+ *
+ * New mask = KDC_OPT_FORWARDABLE | KDC_OPT_PROXIABLE |
+ * KDC_OPT_ALLOW_POSTDATE | KDC_OPT_RENEWABLE
+ */
+#define KDC_TKT_COMMON_MASK 0x54800000
+
+/* definitions for ap_options fields */
+
+/** @defgroup AP_OPTS AP_OPTS
+ *
+ * ap_options are 32 bits; each host is responsible to put the 4 bytes
+ * representing these bits into net order before transmission
+ * @{
+ */
+#define AP_OPTS_RESERVED 0x80000000
+#define AP_OPTS_USE_SESSION_KEY 0x40000000 /**< Use session key */
+#define AP_OPTS_MUTUAL_REQUIRED 0x20000000 /**< Perform a mutual
+ authentication exchange */
+#define AP_OPTS_ETYPE_NEGOTIATION 0x00000002
+#define AP_OPTS_USE_SUBKEY 0x00000001 /**< Generate a subsession key
+ from the current session key
+ obtained from the
+ credentials */
+/* #define AP_OPTS_RESERVED 0x10000000 */
+/* #define AP_OPTS_RESERVED 0x08000000 */
+/* #define AP_OPTS_RESERVED 0x04000000 */
+/* #define AP_OPTS_RESERVED 0x02000000 */
+/* #define AP_OPTS_RESERVED 0x01000000 */
+/* #define AP_OPTS_RESERVED 0x00800000 */
+/* #define AP_OPTS_RESERVED 0x00400000 */
+/* #define AP_OPTS_RESERVED 0x00200000 */
+/* #define AP_OPTS_RESERVED 0x00100000 */
+/* #define AP_OPTS_RESERVED 0x00080000 */
+/* #define AP_OPTS_RESERVED 0x00040000 */
+/* #define AP_OPTS_RESERVED 0x00020000 */
+/* #define AP_OPTS_RESERVED 0x00010000 */
+/* #define AP_OPTS_RESERVED 0x00008000 */
+/* #define AP_OPTS_RESERVED 0x00004000 */
+/* #define AP_OPTS_RESERVED 0x00002000 */
+/* #define AP_OPTS_RESERVED 0x00001000 */
+/* #define AP_OPTS_RESERVED 0x00000800 */
+/* #define AP_OPTS_RESERVED 0x00000400 */
+/* #define AP_OPTS_RESERVED 0x00000200 */
+/* #define AP_OPTS_RESERVED 0x00000100 */
+/* #define AP_OPTS_RESERVED 0x00000080 */
+/* #define AP_OPTS_RESERVED 0x00000040 */
+/* #define AP_OPTS_RESERVED 0x00000020 */
+/* #define AP_OPTS_RESERVED 0x00000010 */
+/* #define AP_OPTS_RESERVED 0x00000008 */
+/* #define AP_OPTS_RESERVED 0x00000004 */
+
+
+#define AP_OPTS_WIRE_MASK 0xfffffff0
+/** @} */ /* end of AP_OPTS group */
+
+/* definitions for ad_type fields. */
+#define AD_TYPE_RESERVED 0x8000
+#define AD_TYPE_EXTERNAL 0x4000
+#define AD_TYPE_REGISTERED 0x2000
+
+#define AD_TYPE_FIELD_TYPE_MASK 0x1fff
+
+/* Ticket flags */
+/* flags are 32 bits; each host is responsible to put the 4 bytes
+ representing these bits into net order before transmission */
+/* #define TKT_FLG_RESERVED 0x80000000 */
+#define TKT_FLG_FORWARDABLE 0x40000000
+#define TKT_FLG_FORWARDED 0x20000000
+#define TKT_FLG_PROXIABLE 0x10000000
+#define TKT_FLG_PROXY 0x08000000
+#define TKT_FLG_MAY_POSTDATE 0x04000000
+#define TKT_FLG_POSTDATED 0x02000000
+#define TKT_FLG_INVALID 0x01000000
+#define TKT_FLG_RENEWABLE 0x00800000
+#define TKT_FLG_INITIAL 0x00400000
+#define TKT_FLG_PRE_AUTH 0x00200000
+#define TKT_FLG_HW_AUTH 0x00100000
+#define TKT_FLG_TRANSIT_POLICY_CHECKED 0x00080000
+#define TKT_FLG_OK_AS_DELEGATE 0x00040000
+#define TKT_FLG_ENC_PA_REP 0x00010000
+#define TKT_FLG_ANONYMOUS 0x00008000
+/* #define TKT_FLG_RESERVED 0x00004000 */
+/* #define TKT_FLG_RESERVED 0x00002000 */
+/* #define TKT_FLG_RESERVED 0x00001000 */
+/* #define TKT_FLG_RESERVED 0x00000800 */
+/* #define TKT_FLG_RESERVED 0x00000400 */
+/* #define TKT_FLG_RESERVED 0x00000200 */
+/* #define TKT_FLG_RESERVED 0x00000100 */
+/* #define TKT_FLG_RESERVED 0x00000080 */
+/* #define TKT_FLG_RESERVED 0x00000040 */
+/* #define TKT_FLG_RESERVED 0x00000020 */
+/* #define TKT_FLG_RESERVED 0x00000010 */
+/* #define TKT_FLG_RESERVED 0x00000008 */
+/* #define TKT_FLG_RESERVED 0x00000004 */
+/* #define TKT_FLG_RESERVED 0x00000002 */
+/* #define TKT_FLG_RESERVED 0x00000001 */
+
+/* definitions for lr_type fields. */
+#define LR_TYPE_THIS_SERVER_ONLY 0x8000
+
+#define LR_TYPE_INTERPRETATION_MASK 0x7fff
+
+/* definitions for msec direction bit for KRB_SAFE, KRB_PRIV */
+#define MSEC_DIRBIT 0x8000
+#define MSEC_VAL_MASK 0x7fff
+
+/*
+ * end "fieldbits.h"
+ */
+
+/*
+ * begin "proto.h"
+ */
+
+/** Protocol version number */
+#define KRB5_PVNO 5
+
+/* Message types */
+
+#define KRB5_AS_REQ ((krb5_msgtype)10) /**< Initial authentication request */
+#define KRB5_AS_REP ((krb5_msgtype)11) /**< Response to AS request */
+#define KRB5_TGS_REQ ((krb5_msgtype)12) /**< Ticket granting server request */
+#define KRB5_TGS_REP ((krb5_msgtype)13) /**< Response to TGS request */
+#define KRB5_AP_REQ ((krb5_msgtype)14) /**< Auth req to application server */
+#define KRB5_AP_REP ((krb5_msgtype)15) /**< Response to mutual AP request */
+#define KRB5_SAFE ((krb5_msgtype)20) /**< Safe application message */
+#define KRB5_PRIV ((krb5_msgtype)21) /**< Private application message */
+#define KRB5_CRED ((krb5_msgtype)22) /**< Cred forwarding message */
+#define KRB5_ERROR ((krb5_msgtype)30) /**< Error response */
/* LastReq types */
-#define KRB5_LRQ_NONE 0
-#define KRB5_LRQ_ALL_LAST_TGT 1
-#define KRB5_LRQ_ONE_LAST_TGT (-1)
-#define KRB5_LRQ_ALL_LAST_INITIAL 2
-#define KRB5_LRQ_ONE_LAST_INITIAL (-2)
-#define KRB5_LRQ_ALL_LAST_TGT_ISSUED 3
-#define KRB5_LRQ_ONE_LAST_TGT_ISSUED (-3)
-#define KRB5_LRQ_ALL_LAST_RENEWAL 4
-#define KRB5_LRQ_ONE_LAST_RENEWAL (-4)
-#define KRB5_LRQ_ALL_LAST_REQ 5
-#define KRB5_LRQ_ONE_LAST_REQ (-5)
-#define KRB5_LRQ_ALL_PW_EXPTIME 6
-#define KRB5_LRQ_ONE_PW_EXPTIME (-6)
+#define KRB5_LRQ_NONE 0
+#define KRB5_LRQ_ALL_LAST_TGT 1
+#define KRB5_LRQ_ONE_LAST_TGT (-1)
+#define KRB5_LRQ_ALL_LAST_INITIAL 2
+#define KRB5_LRQ_ONE_LAST_INITIAL (-2)
+#define KRB5_LRQ_ALL_LAST_TGT_ISSUED 3
+#define KRB5_LRQ_ONE_LAST_TGT_ISSUED (-3)
+#define KRB5_LRQ_ALL_LAST_RENEWAL 4
+#define KRB5_LRQ_ONE_LAST_RENEWAL (-4)
+#define KRB5_LRQ_ALL_LAST_REQ 5
+#define KRB5_LRQ_ONE_LAST_REQ (-5)
+#define KRB5_LRQ_ALL_PW_EXPTIME 6
+#define KRB5_LRQ_ONE_PW_EXPTIME (-6)
+#define KRB5_LRQ_ALL_ACCT_EXPTIME 7
+#define KRB5_LRQ_ONE_ACCT_EXPTIME (-7)
/* PADATA types */
-#define KRB5_PADATA_NONE 0
-#define KRB5_PADATA_AP_REQ 1
-#define KRB5_PADATA_TGS_REQ KRB5_PADATA_AP_REQ
-#define KRB5_PADATA_ENC_TIMESTAMP 2
-#define KRB5_PADATA_PW_SALT 3
-#if 0 /* Not used */
-#define KRB5_PADATA_ENC_ENCKEY 4 /* Key encrypted within itself */
+#define KRB5_PADATA_NONE 0
+#define KRB5_PADATA_AP_REQ 1
+#define KRB5_PADATA_TGS_REQ KRB5_PADATA_AP_REQ
+#define KRB5_PADATA_ENC_TIMESTAMP 2
+#define KRB5_PADATA_PW_SALT 3
+#if 0 /* Not used */
+#define KRB5_PADATA_ENC_ENCKEY 4 /* Key encrypted within itself */
#endif
-#define KRB5_PADATA_ENC_UNIX_TIME 5 /* timestamp encrypted in key */
-#define KRB5_PADATA_ENC_SANDIA_SECURID 6 /* SecurId passcode */
-#define KRB5_PADATA_SESAME 7 /* Sesame project */
-#define KRB5_PADATA_OSF_DCE 8 /* OSF DCE */
-#define KRB5_CYBERSAFE_SECUREID 9 /* Cybersafe */
-#define KRB5_PADATA_AFS3_SALT 10 /* Cygnus */
-#define KRB5_PADATA_ETYPE_INFO 11 /* Etype info for preauth */
-#define KRB5_PADATA_SAM_CHALLENGE 12 /* draft challenge system */
-#define KRB5_PADATA_SAM_RESPONSE 13 /* draft challenge system response */
-#define KRB5_PADATA_PK_AS_REQ_OLD 14 /* PKINIT */
-#define KRB5_PADATA_PK_AS_REP_OLD 15 /* PKINIT */
-#define KRB5_PADATA_PK_AS_REQ 16 /* PKINIT */
-#define KRB5_PADATA_PK_AS_REP 17 /* PKINIT */
-#define KRB5_PADATA_ETYPE_INFO2 19
-#define KRB5_PADATA_USE_SPECIFIED_KVNO 20
-#define KRB5_PADATA_SVR_REFERRAL_INFO 20 /* Windows 2000 referrals */
-#define KRB5_PADATA_SAM_REDIRECT 21
-#define KRB5_PADATA_GET_FROM_TYPED_DATA 22
-#define KRB5_PADATA_REFERRAL 25 /* draft referral system */
-#define KRB5_PADATA_SAM_CHALLENGE_2 30 /* draft challenge system, updated */
-#define KRB5_PADATA_SAM_RESPONSE_2 31 /* draft challenge system, updated */
-#define KRB5_PADATA_PAC_REQUEST 128 /* include Windows PAC */
-#define KRB5_PADATA_FOR_USER 129 /* username protocol transition request */
-#define KRB5_PADATA_S4U_X509_USER 130 /* certificate protocol transition request */
-#define KRB5_PADATA_FX_COOKIE 133
-#define KRB5_PADATA_FX_FAST 136
-#define KRB5_PADATA_FX_ERROR 137
+#define KRB5_PADATA_ENC_UNIX_TIME 5 /**< timestamp encrypted in key */
+#define KRB5_PADATA_ENC_SANDIA_SECURID 6 /**< SecurId passcode */
+#define KRB5_PADATA_SESAME 7 /**< Sesame project */
+#define KRB5_PADATA_OSF_DCE 8 /**< OSF DCE */
+#define KRB5_CYBERSAFE_SECUREID 9 /**< Cybersafe */
+#define KRB5_PADATA_AFS3_SALT 10 /**< Cygnus */
+#define KRB5_PADATA_ETYPE_INFO 11 /**< Etype info for preauth */
+#define KRB5_PADATA_SAM_CHALLENGE 12 /**< draft challenge system */
+#define KRB5_PADATA_SAM_RESPONSE 13 /**< draft challenge system response */
+#define KRB5_PADATA_PK_AS_REQ_OLD 14 /**< PKINIT */
+#define KRB5_PADATA_PK_AS_REP_OLD 15 /**< PKINIT */
+#define KRB5_PADATA_PK_AS_REQ 16 /**< PKINIT */
+#define KRB5_PADATA_PK_AS_REP 17 /**< PKINIT */
+#define KRB5_PADATA_ETYPE_INFO2 19
+#define KRB5_PADATA_USE_SPECIFIED_KVNO 20
+#define KRB5_PADATA_SVR_REFERRAL_INFO 20 /**< Windows 2000 referrals */
+#define KRB5_PADATA_SAM_REDIRECT 21
+#define KRB5_PADATA_GET_FROM_TYPED_DATA 22
+#define KRB5_PADATA_REFERRAL 25 /**< draft referral system */
+#define KRB5_PADATA_SAM_CHALLENGE_2 30 /**< draft challenge system, updated */
+#define KRB5_PADATA_SAM_RESPONSE_2 31 /**< draft challenge system, updated */
+#define KRB5_PADATA_PAC_REQUEST 128 /**< include Windows PAC */
+#define KRB5_PADATA_FOR_USER 129 /**< username protocol transition request */
+#define KRB5_PADATA_S4U_X509_USER 130 /**< certificate protocol transition request */
+#define KRB5_PADATA_FX_COOKIE 133
+#define KRB5_PADATA_FX_FAST 136
+#define KRB5_PADATA_FX_ERROR 137
#define KRB5_PADATA_ENCRYPTED_CHALLENGE 138
+#define KRB5_PADATA_PKINIT_KX 147
+#define KRB5_ENCPADATA_REQ_ENC_PA_REP 149
-#define KRB5_SAM_USE_SAD_AS_KEY 0x80000000
-#define KRB5_SAM_SEND_ENCRYPTED_SAD 0x40000000
-#define KRB5_SAM_MUST_PK_ENCRYPT_SAD 0x20000000 /* currently must be zero */
+#define KRB5_SAM_USE_SAD_AS_KEY 0x80000000
+#define KRB5_SAM_SEND_ENCRYPTED_SAD 0x40000000
+#define KRB5_SAM_MUST_PK_ENCRYPT_SAD 0x20000000 /* currently must be zero */
-/* Reserved for SPX pre-authentication. */
-#define KRB5_PADATA_DASS 16
+/** Transited encoding types */
+#define KRB5_DOMAIN_X500_COMPRESS 1
-/* Transited encoding types */
-#define KRB5_DOMAIN_X500_COMPRESS 1
+/** alternate authentication types */
+#define KRB5_ALTAUTH_ATT_CHALLENGE_RESPONSE 64
-/* alternate authentication types */
-#define KRB5_ALTAUTH_ATT_CHALLENGE_RESPONSE 64
+/* authorization data types. See RFC 4120 section 5.2.6 */
-/* authorization data types */
+/** @defgroup KRB5_AUTHDATA KRB5_AUTHDATA
+ * @{
+ */
#define KRB5_AUTHDATA_IF_RELEVANT 1
#define KRB5_AUTHDATA_KDC_ISSUED 4
-#define KRB5_AUTHDATA_AND_OR 5
-#define KRB5_AUTHDATA_MANDATORY_FOR_KDC 8
-#define KRB5_AUTHDATA_INITIAL_VERIFIED_CAS 9
-#define KRB5_AUTHDATA_OSF_DCE 64
-#define KRB5_AUTHDATA_SESAME 65
-#define KRB5_AUTHDATA_WIN2K_PAC 128
-#define KRB5_AUTHDATA_ETYPE_NEGOTIATION 129 /* RFC 4537 */
+#define KRB5_AUTHDATA_AND_OR 5
+#define KRB5_AUTHDATA_MANDATORY_FOR_KDC 8
+#define KRB5_AUTHDATA_INITIAL_VERIFIED_CAS 9
+#define KRB5_AUTHDATA_OSF_DCE 64
+#define KRB5_AUTHDATA_SESAME 65
+#define KRB5_AUTHDATA_WIN2K_PAC 128
+#define KRB5_AUTHDATA_ETYPE_NEGOTIATION 129 /* RFC 4537 */
+#define KRB5_AUTHDATA_SIGNTICKET 512 /**< formerly 142 in krb5 1.8 */
#define KRB5_AUTHDATA_FX_ARMOR 71
-/* password change constants */
+/** @} */ /* end of KRB5_AUTHDATA group */
-#define KRB5_KPASSWD_SUCCESS 0
-#define KRB5_KPASSWD_MALFORMED 1
-#define KRB5_KPASSWD_HARDERROR 2
-#define KRB5_KPASSWD_AUTHERROR 3
-#define KRB5_KPASSWD_SOFTERROR 4
+/* password change constants */
+#define KRB5_KPASSWD_SUCCESS 0 /**< Success */
+#define KRB5_KPASSWD_MALFORMED 1 /**< Malformed request */
+#define KRB5_KPASSWD_HARDERROR 2 /**< Server error */
+#define KRB5_KPASSWD_AUTHERROR 3 /**< Authentication error */
+#define KRB5_KPASSWD_SOFTERROR 4 /**< Password change rejected */
/* These are Microsoft's extensions in RFC 3244, and it looks like
they'll become standardized, possibly with other additions. */
-#define KRB5_KPASSWD_ACCESSDENIED 5 /* unused */
-#define KRB5_KPASSWD_BAD_VERSION 6
-#define KRB5_KPASSWD_INITIAL_FLAG_NEEDED 7 /* unused */
+#define KRB5_KPASSWD_ACCESSDENIED 5 /* unused */
+#define KRB5_KPASSWD_BAD_VERSION 6
+#define KRB5_KPASSWD_INITIAL_FLAG_NEEDED 7 /* unused */
/*
* end "proto.h"
*/
/* Time set */
+/** Ticket start time, end time, and renewal duration. */
typedef struct _krb5_ticket_times {
- krb5_timestamp authtime; /* XXX ? should ktime in KDC_REP == authtime
- in ticket? otherwise client can't get this */
- krb5_timestamp starttime; /* optional in ticket, if not present,
- use authtime */
- krb5_timestamp endtime;
- krb5_timestamp renew_till;
+ krb5_timestamp authtime; /**< Time at which KDC issued the initial ticket that corresponds to this ticket */
+ /* XXX ? should ktime in KDC_REP == authtime
+ in ticket? otherwise client can't get this */
+ krb5_timestamp starttime; /**< optional in ticket, if not present, use @a authtime */
+ krb5_timestamp endtime; /**< Ticket expiration time */
+ krb5_timestamp renew_till; /**< Latest time at which renewal of ticket can be valid */
} krb5_ticket_times;
-/* structure for auth data */
+/** Structure for auth data */
typedef struct _krb5_authdata {
krb5_magic magic;
- krb5_authdatatype ad_type;
- unsigned int length;
- krb5_octet *contents;
+ krb5_authdatatype ad_type; /**< ADTYPE */
+ unsigned int length; /**< Length of data */
+ krb5_octet *contents; /**< Data */
} krb5_authdata;
-/* structure for transited encoding */
+/** Structure for transited encoding */
typedef struct _krb5_transited {
krb5_magic magic;
- krb5_octet tr_type;
- krb5_data tr_contents;
+ krb5_octet tr_type; /**< Transited encoding type */
+ krb5_data tr_contents; /**< Contents */
} krb5_transited;
+/** Encrypted part of ticket. */
typedef struct _krb5_enc_tkt_part {
krb5_magic magic;
/* to-be-encrypted portion */
- krb5_flags flags; /* flags */
- krb5_keyblock *session; /* session key: includes enctype */
- krb5_principal client; /* client name/realm */
- krb5_transited transited; /* list of transited realms */
- krb5_ticket_times times; /* auth, start, end, renew_till */
- krb5_address **caddrs; /* array of ptrs to addresses */
- krb5_authdata **authorization_data; /* auth data */
+ krb5_flags flags; /**< flags */
+ krb5_keyblock *session; /**< session key: includes enctype */
+ krb5_principal client; /**< client name/realm */
+ krb5_transited transited; /**< list of transited realms */
+ krb5_ticket_times times; /**< auth, start, end, renew_till */
+ krb5_address **caddrs; /**< array of ptrs to addresses */
+ krb5_authdata **authorization_data; /**< auth data */
} krb5_enc_tkt_part;
+/**
+ * Ticket structure.
+ *
+ * The C representation of the ticket message, with a pointer to the
+ * C representation of the encrypted part.
+ */
typedef struct _krb5_ticket {
krb5_magic magic;
/* cleartext portion */
- krb5_principal server; /* server name/realm */
- krb5_enc_data enc_part; /* encryption type, kvno, encrypted
- encoding */
- krb5_enc_tkt_part *enc_part2; /* ptr to decrypted version, if
- available */
+ krb5_principal server; /**< server name/realm */
+ krb5_enc_data enc_part; /**< encryption type, kvno, encrypted encoding */
+ krb5_enc_tkt_part *enc_part2; /**< ptr to decrypted version, if available */
} krb5_ticket;
/* the unencrypted version */
+/**
+ * Ticket authenticator.
+ *
+ * The C representation of an unencrypted authenticator.
+ */
typedef struct _krb5_authenticator {
krb5_magic magic;
- krb5_principal client; /* client name/realm */
- krb5_checksum *checksum; /* checksum, includes type, optional */
- krb5_int32 cusec; /* client usec portion */
- krb5_timestamp ctime; /* client sec portion */
- krb5_keyblock *subkey; /* true session key, optional */
- krb5_ui_4 seq_number; /* sequence #, optional */
- krb5_authdata **authorization_data; /* New add by Ari, auth data */
+ krb5_principal client; /**< client name/realm */
+ krb5_checksum *checksum; /**< checksum, includes type, optional */
+ krb5_int32 cusec; /**< client usec portion */
+ krb5_timestamp ctime; /**< client sec portion */
+ krb5_keyblock *subkey; /**< true session key, optional */
+ krb5_ui_4 seq_number; /**< sequence #, optional */
+ krb5_authdata **authorization_data; /**< authoriazation data */
} krb5_authenticator;
+/** Ticket authentication data. */
typedef struct _krb5_tkt_authent {
krb5_magic magic;
krb5_ticket *ticket;
krb5_flags ap_options;
} krb5_tkt_authent;
-/* credentials: Ticket, session key, etc. */
+/** Credentials structure including ticket, session key, and lifetime info. */
typedef struct _krb5_creds {
krb5_magic magic;
- krb5_principal client; /* client's principal identifier */
- krb5_principal server; /* server's principal identifier */
- krb5_keyblock keyblock; /* session encryption key info */
- krb5_ticket_times times; /* lifetime info */
- krb5_boolean is_skey; /* true if ticket is encrypted in
- another ticket's skey */
- krb5_flags ticket_flags; /* flags in ticket */
- krb5_address **addresses; /* addrs in ticket */
- krb5_data ticket; /* ticket string itself */
- krb5_data second_ticket; /* second ticket, if related to
- ticket (via DUPLICATE-SKEY or
- ENC-TKT-IN-SKEY) */
- krb5_authdata **authdata; /* authorization data */
+ krb5_principal client; /**< client's principal identifier */
+ krb5_principal server; /**< server's principal identifier */
+ krb5_keyblock keyblock; /**< session encryption key info */
+ krb5_ticket_times times; /**< lifetime info */
+ krb5_boolean is_skey; /**< true if ticket is encrypted in
+ another ticket's skey */
+ krb5_flags ticket_flags; /**< flags in ticket */
+ krb5_address **addresses; /**< addrs in ticket */
+ krb5_data ticket; /**< ticket string itself */
+ krb5_data second_ticket; /**< second ticket, if related to
+ ticket (via DUPLICATE-SKEY or
+ ENC-TKT-IN-SKEY) */
+ krb5_authdata **authdata; /**< authorization data */
} krb5_creds;
-/* Last request fields */
+/** Last request entry */
typedef struct _krb5_last_req_entry {
krb5_magic magic;
- krb5_int32 lr_type;
- krb5_timestamp value;
+ krb5_int32 lr_type; /**< LR type */
+ krb5_timestamp value; /**< Timestamp */
} krb5_last_req_entry;
-/* pre-authentication data */
+/** Pre-authentication data */
typedef struct _krb5_pa_data {
krb5_magic magic;
- krb5_preauthtype pa_type;
- unsigned int length;
- krb5_octet *contents;
+ krb5_preauthtype pa_type; /**< Preauthentication data type */
+ unsigned int length; /**< Length of data */
+ krb5_octet *contents; /**< Data */
} krb5_pa_data;
+/* Don't use this; use krb5_pa_data instead. */
+typedef struct _krb5_typed_data {
+ krb5_magic magic;
+ krb5_int32 type;
+ unsigned int length;
+ krb5_octet *data;
+} krb5_typed_data;
+
+/** C representation of KDC-REQ protocol message, including KDC-REQ-BODY */
typedef struct _krb5_kdc_req {
krb5_magic magic;
- krb5_msgtype msg_type; /* AS_REQ or TGS_REQ? */
- krb5_pa_data **padata; /* e.g. encoded AP_REQ */
+ krb5_msgtype msg_type; /**< KRB5_AS_REQ or KRB5_TGS_REQ */
+ krb5_pa_data **padata; /**< Preauthentication data */
/* real body */
- krb5_flags kdc_options; /* requested options */
- krb5_principal client; /* includes realm; optional */
- krb5_principal server; /* includes realm (only used if no
- client) */
- krb5_timestamp from; /* requested starttime */
- krb5_timestamp till; /* requested endtime */
- krb5_timestamp rtime; /* (optional) requested renew_till */
- krb5_int32 nonce; /* nonce to match request/response */
- int nktypes; /* # of ktypes, must be positive */
- krb5_enctype *ktype; /* requested enctype(s) */
- krb5_address **addresses; /* requested addresses, optional */
- krb5_enc_data authorization_data; /* encrypted auth data; OPTIONAL */
- krb5_authdata **unenc_authdata; /* unencrypted auth data,
- if available */
- krb5_ticket **second_ticket;/* second ticket array; OPTIONAL */
- /* the following field is added in March 2009; it is a hack so
- * that FAST state can be carried to pre-authentication plugins.
- * A new plugin interface may be a better long-term approach. It
- * is believed to be safe to extend this structure because it is
- * not found in any public APIs.
- */
- void * kdc_state;
+ krb5_flags kdc_options; /**< Requested options */
+ krb5_principal client; /**< Client principal and realm */
+ krb5_principal server; /**< Server principal and realm */
+ krb5_timestamp from; /**< Requested start time */
+ krb5_timestamp till; /**< Requested end time */
+ krb5_timestamp rtime; /**< Requested renewable end time */
+ krb5_int32 nonce; /**< Nonce to match request andresponse */
+ int nktypes; /**< Number of enctypes */
+ krb5_enctype *ktype; /**< Requested enctypes */
+ krb5_address **addresses; /**< Requested addresses (optional) */
+ krb5_enc_data authorization_data; /**< Encrypted authz data (optional) */
+ krb5_authdata **unenc_authdata; /**< Unencrypted authz data */
+ krb5_ticket **second_ticket; /**< Second ticket array (optional) */
} krb5_kdc_req;
+/**
+ * C representation of @c EncKDCRepPart protocol message.
+ *
+ * This is the cleartext message that is encrypted and inserted in @c KDC-REP.
+ */
typedef struct _krb5_enc_kdc_rep_part {
krb5_magic magic;
/* encrypted part: */
- krb5_msgtype msg_type; /* krb5 message type */
- krb5_keyblock *session; /* session key */
- krb5_last_req_entry **last_req; /* array of ptrs to entries */
- krb5_int32 nonce; /* nonce from request */
- krb5_timestamp key_exp; /* expiration date */
- krb5_flags flags; /* ticket flags */
- krb5_ticket_times times; /* lifetime info */
- krb5_principal server; /* server's principal identifier */
- krb5_address **caddrs; /* array of ptrs to addresses,
- optional */
- krb5_pa_data **enc_padata; /* Windows 2000 compat */
+ krb5_msgtype msg_type; /**< krb5 message type */
+ krb5_keyblock *session; /**< Session key */
+ krb5_last_req_entry **last_req; /**< Array of pointers to entries */
+ krb5_int32 nonce; /**< Nonce from request */
+ krb5_timestamp key_exp; /**< Expiration date */
+ krb5_flags flags; /**< Ticket flags */
+ krb5_ticket_times times; /**< Lifetime info */
+ krb5_principal server; /**< Server's principal identifier */
+ krb5_address **caddrs; /**< Array of ptrs to addrs, optional */
+ krb5_pa_data **enc_padata; /**< Encrypted preauthentication data */
} krb5_enc_kdc_rep_part;
+/** Representation of the @c KDC-REP protocol message. */
typedef struct _krb5_kdc_rep {
krb5_magic magic;
/* cleartext part: */
- krb5_msgtype msg_type; /* AS_REP or KDC_REP? */
- krb5_pa_data **padata; /* preauthentication data from KDC */
- krb5_principal client; /* client's principal identifier */
- krb5_ticket *ticket; /* ticket */
- krb5_enc_data enc_part; /* encryption type, kvno, encrypted
- encoding */
- krb5_enc_kdc_rep_part *enc_part2;/* unencrypted version, if available */
+ krb5_msgtype msg_type; /**< KRB5_AS_REP or KRB5_KDC_REP */
+ krb5_pa_data **padata; /**< Preauthentication data from KDC */
+ krb5_principal client; /**< Client principal and realm */
+ krb5_ticket *ticket; /**< Ticket */
+ krb5_enc_data enc_part; /**< Encrypted part of reply */
+ krb5_enc_kdc_rep_part *enc_part2; /**< Unencrypted version, if available */
} krb5_kdc_rep;
-/* error message structure */
+/** Error message structure */
typedef struct _krb5_error {
krb5_magic magic;
/* some of these may be meaningless in certain contexts */
- krb5_timestamp ctime; /* client sec portion; optional */
- krb5_int32 cusec; /* client usec portion; optional */
- krb5_int32 susec; /* server usec portion */
- krb5_timestamp stime; /* server sec portion */
- krb5_ui_4 error; /* error code (protocol error #'s) */
- krb5_principal client; /* client's principal identifier;
- optional */
- krb5_principal server; /* server's principal identifier */
- krb5_data text; /* descriptive text */
- krb5_data e_data; /* additional error-describing data */
+ krb5_timestamp ctime; /**< Client sec portion; optional */
+ krb5_int32 cusec; /**< Client usec portion; optional */
+ krb5_int32 susec; /**< Server usec portion */
+ krb5_timestamp stime; /**< Server sec portion */
+ krb5_ui_4 error; /**< Error code (protocol error #'s) */
+ krb5_principal client; /**< Client principal and realm */
+ krb5_principal server; /**< Server principal and realm */
+ krb5_data text; /**< Descriptive text */
+ krb5_data e_data; /**< Additional error-describing data */
} krb5_error;
+/** Authentication header. */
typedef struct _krb5_ap_req {
krb5_magic magic;
- krb5_flags ap_options; /* requested options */
- krb5_ticket *ticket; /* ticket */
- krb5_enc_data authenticator; /* authenticator (already encrypted) */
+ krb5_flags ap_options; /**< Requested options */
+ krb5_ticket *ticket; /**< Ticket */
+ krb5_enc_data authenticator; /**< Encrypted authenticator */
} krb5_ap_req;
+/**
+ * C representaton of AP-REP message.
+ *
+ * The server's response to a client's request for mutual authentication.
+ */
typedef struct _krb5_ap_rep {
krb5_magic magic;
- krb5_enc_data enc_part;
+ krb5_enc_data enc_part; /**< Ciphertext of ApRepEncPart */
} krb5_ap_rep;
+/** Cleartext that is encrypted and put into @c _krb5_ap_rep. */
typedef struct _krb5_ap_rep_enc_part {
krb5_magic magic;
- krb5_timestamp ctime; /* client time, seconds portion */
- krb5_int32 cusec; /* client time, microseconds portion */
- krb5_keyblock *subkey; /* true session key, optional */
- krb5_ui_4 seq_number; /* sequence #, optional */
+ krb5_timestamp ctime; /**< Client time, seconds portion */
+ krb5_int32 cusec; /**< Client time, microseconds portion */
+ krb5_keyblock *subkey; /**< Subkey (optional) */
+ krb5_ui_4 seq_number; /**< Sequence number */
} krb5_ap_rep_enc_part;
+/* Unused */
typedef struct _krb5_response {
krb5_magic magic;
krb5_octet message_type;
krb5_data response;
- krb5_int32 expected_nonce; /* The expected nonce for KDC_REP messages */
- krb5_timestamp request_time; /* When we made the request */
+ krb5_int32 expected_nonce;
+ krb5_timestamp request_time;
} krb5_response;
+/** Credentials information inserted into @c EncKrbCredPart. */
typedef struct _krb5_cred_info {
krb5_magic magic;
- krb5_keyblock *session; /* session key used to encrypt */
- /* ticket */
- krb5_principal client; /* client name/realm, optional */
- krb5_principal server; /* server name/realm, optional */
- krb5_flags flags; /* ticket flags, optional */
- krb5_ticket_times times; /* auth, start, end, renew_till, */
- /* optional */
- krb5_address **caddrs; /* array of ptrs to addresses */
+ krb5_keyblock *session; /**< Session key used to encrypt ticket */
+ krb5_principal client; /**< Client principal and realm */
+ krb5_principal server; /**< Server principal and realm */
+ krb5_flags flags; /**< Ticket flags */
+ krb5_ticket_times times; /**< Auth, start, end, renew_till */
+ krb5_address **caddrs; /**< Array of pointers to addrs (optional) */
} krb5_cred_info;
+/** Cleartext credentials information. */
typedef struct _krb5_cred_enc_part {
krb5_magic magic;
- krb5_int32 nonce; /* nonce, optional */
- krb5_timestamp timestamp; /* client time */
- krb5_int32 usec; /* microsecond portion of time */
- krb5_address *s_address; /* sender address, optional */
- krb5_address *r_address; /* recipient address, optional */
+ krb5_int32 nonce; /**< Nonce (optional) */
+ krb5_timestamp timestamp; /**< Generation time, seconds portion */
+ krb5_int32 usec; /**< Generation time, microseconds portion */
+ krb5_address *s_address; /**< Sender address (optional) */
+ krb5_address *r_address; /**< Recipient address (optional) */
krb5_cred_info **ticket_info;
-} krb5_cred_enc_part;
+} krb5_cred_enc_part;
+/** Credentials data structure.*/
typedef struct _krb5_cred {
krb5_magic magic;
- krb5_ticket **tickets; /* tickets */
- krb5_enc_data enc_part; /* encrypted part */
- krb5_cred_enc_part *enc_part2; /* unencrypted version, if available*/
+ krb5_ticket **tickets; /**< Tickets */
+ krb5_enc_data enc_part; /**< Encrypted part */
+ krb5_cred_enc_part *enc_part2; /**< Unencrypted version, if available */
} krb5_cred;
-/* Sandia password generation structures */
+/* Unused, but here for API compatibility. */
typedef struct _passwd_phrase_element {
krb5_magic magic;
krb5_data *passwd;
krb5_data *phrase;
} passwd_phrase_element;
+/* Unused, but here for API compatibility. */
typedef struct _krb5_pwd_data {
krb5_magic magic;
int sequence_count;
passwd_phrase_element **element;
} krb5_pwd_data;
-/* these need to be here so the typedefs are available for the prototypes */
-/*
- * Note for Windows 2000 compatibility this is encoded
- * in the enc_padata field of the krb5_enc_kdc_rep_part.
- */
+/* Unused, but here for API compatibility. */
typedef struct _krb5_pa_svr_referral_data {
- /* Referred name, only realm is required */
+ /** Referred name, only realm is required */
krb5_principal principal;
} krb5_pa_svr_referral_data;
+/* Unused, but here for API compatibility. */
typedef struct _krb5_pa_server_referral_data {
krb5_data *referred_realm;
krb5_principal true_principal_name;
} krb5_pa_server_referral_data;
typedef struct _krb5_pa_pac_req {
- /* TRUE if a PAC should be included in TGS-REP */
+ /** TRUE if a PAC should be included in TGS-REP */
krb5_boolean include_pac;
} krb5_pa_pac_req;
* begin "safepriv.h"
*/
-#define KRB5_AUTH_CONTEXT_DO_TIME 0x00000001
-#define KRB5_AUTH_CONTEXT_RET_TIME 0x00000002
-#define KRB5_AUTH_CONTEXT_DO_SEQUENCE 0x00000004
-#define KRB5_AUTH_CONTEXT_RET_SEQUENCE 0x00000008
-#define KRB5_AUTH_CONTEXT_PERMIT_ALL 0x00000010
-#define KRB5_AUTH_CONTEXT_USE_SUBKEY 0x00000020
-
-typedef struct krb5_replay_data {
- krb5_timestamp timestamp;
- krb5_int32 usec;
- krb5_ui_4 seq;
+/** @defgroup KRB5_AUTH_CONTEXT KRB5_AUTH_CONTEXT
+ * @{
+ */
+/** Prevent replays with timestamps and replay cache. */
+#define KRB5_AUTH_CONTEXT_DO_TIME 0x00000001
+/** Save timestamps for application. */
+#define KRB5_AUTH_CONTEXT_RET_TIME 0x00000002
+/** Prevent replays with sequence numbers. */
+#define KRB5_AUTH_CONTEXT_DO_SEQUENCE 0x00000004
+/** Save sequence numbers for application. */
+#define KRB5_AUTH_CONTEXT_RET_SEQUENCE 0x00000008
+#define KRB5_AUTH_CONTEXT_PERMIT_ALL 0x00000010
+#define KRB5_AUTH_CONTEXT_USE_SUBKEY 0x00000020
+/** @} */ /* end of KRB5_AUTH_CONTEXT group */
+
+/**
+ * Replay data.
+ *
+ * Sequence number and timestamp information output by krb5_rd_priv() and
+ * krb5_rd_safe().
+ */
+typedef struct krb5_replay_data {
+ krb5_timestamp timestamp; /**< Timestamp, seconds portion */
+ krb5_int32 usec; /**< Timestamp, microseconds portion */
+ krb5_ui_4 seq; /**< Sequence number */
} krb5_replay_data;
-/* flags for krb5_auth_con_genaddrs() */
-#define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR 0x00000001
-#define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR 0x00000002
-#define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR 0x00000004
-#define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR 0x00000008
+/* Flags for krb5_auth_con_genaddrs(). */
-/* type of function used as a callback to generate checksum data for
- * mk_req */
+/** Generate the local network address. */
+#define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR 0x00000001
+/** Generate the remote network address. */
+#define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR 0x00000002
+/** Generate the local network address and the local port. */
+#define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR 0x00000004
+/** Generate the remote network address and the remote port. */
+#define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR 0x00000008
-typedef krb5_error_code
-(KRB5_CALLCONV * krb5_mk_req_checksum_func) (krb5_context, krb5_auth_context , void *,
- krb5_data **);
+/** Type of function used as a callback to generate checksum data for mk_req */
+typedef krb5_error_code
+(KRB5_CALLCONV * krb5_mk_req_checksum_func)(krb5_context, krb5_auth_context,
+ void *, krb5_data **);
/*
* end "safepriv.h"
* begin "ccache.h"
*/
-typedef krb5_pointer krb5_cc_cursor; /* cursor for sequential lookup */
+/** Cursor for sequential lookup */
+typedef krb5_pointer krb5_cc_cursor;
struct _krb5_ccache;
typedef struct _krb5_ccache *krb5_ccache;
struct _krb5_cc_ops;
typedef struct _krb5_cc_ops krb5_cc_ops;
-/*
- * Cursor for iterating over all ccaches
- */
struct _krb5_cccol_cursor;
+/** Cursor for iterating over all ccaches */
typedef struct _krb5_cccol_cursor *krb5_cccol_cursor;
-/* for retrieve_cred */
-#define KRB5_TC_MATCH_TIMES 0x00000001
-#define KRB5_TC_MATCH_IS_SKEY 0x00000002
-#define KRB5_TC_MATCH_FLAGS 0x00000004
-#define KRB5_TC_MATCH_TIMES_EXACT 0x00000008
-#define KRB5_TC_MATCH_FLAGS_EXACT 0x00000010
-#define KRB5_TC_MATCH_AUTHDATA 0x00000020
-#define KRB5_TC_MATCH_SRV_NAMEONLY 0x00000040
-#define KRB5_TC_MATCH_2ND_TKT 0x00000080
-#define KRB5_TC_MATCH_KTYPE 0x00000100
-#define KRB5_TC_SUPPORTED_KTYPES 0x00000200
-
-/* for set_flags and other functions */
-#define KRB5_TC_OPENCLOSE 0x00000001
-#define KRB5_TC_NOTICKET 0x00000002
-
+/* Flags for krb5_cc_retrieve_cred. */
+/** The requested lifetime must be at least as great as the time specified. */
+#define KRB5_TC_MATCH_TIMES 0x00000001
+/** The is_skey field must match exactly. */
+#define KRB5_TC_MATCH_IS_SKEY 0x00000002
+/** All the flags set in the match credentials must be set. */
+#define KRB5_TC_MATCH_FLAGS 0x00000004
+/** All the time fields must match exactly. */
+#define KRB5_TC_MATCH_TIMES_EXACT 0x00000008
+/** All the flags must match exactly. */
+#define KRB5_TC_MATCH_FLAGS_EXACT 0x00000010
+/** The authorization data must match. */
+#define KRB5_TC_MATCH_AUTHDATA 0x00000020
+/** Only the name portion of the principal name must match. */
+#define KRB5_TC_MATCH_SRV_NAMEONLY 0x00000040
+/** The second ticket must match. */
+#define KRB5_TC_MATCH_2ND_TKT 0x00000080
+/** The encryption key type must match. */
+#define KRB5_TC_MATCH_KTYPE 0x00000100
+/** The supported key types must match. */
+#define KRB5_TC_SUPPORTED_KTYPES 0x00000200
+
+/* Flags for krb5_cc_set_flags and similar. */
+/** Open and close the file for each cache operation. */
+#define KRB5_TC_OPENCLOSE 0x00000001
+#define KRB5_TC_NOTICKET 0x00000002
+
+/**
+ * Retrieve the name, but not type of a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in] cache Credential cache handle
+ *
+ * @warning Returns the name of the credential cache. The result is an alias
+ * into @a cache and should not be freed or modified by the caller. This name
+ * does not include the cache type, so should not be used as input to
+ * krb5_cc_resolve().
+ *
+ * @return
+ * On success - the name of the credential cache.
+ */
const char * KRB5_CALLCONV
-krb5_cc_get_name (krb5_context context, krb5_ccache cache);
+krb5_cc_get_name(krb5_context context, krb5_ccache cache);
+
+/**
+ * Retrieve the full name of a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in] cache Credential cache handle
+ * @param [out] fullname_out Full name of cache
+ *
+ * @version First introduced in 1.10
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_cc_get_full_name(krb5_context context, krb5_ccache cache,
+ char **fullname_out);
+#if KRB5_DEPRECATED
krb5_error_code KRB5_CALLCONV
-krb5_cc_gen_new (krb5_context context, krb5_ccache *cache);
+krb5_cc_gen_new(krb5_context context, krb5_ccache *cache);
+#endif /* KRB5_DEPRECATED */
+/**
+ * Initialize a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in] cache Credential cache handle
+ * @param [in] principal Default principal name
+ *
+ * Destroy any existing contents of @a cache and initialize it for the default
+ * principal @a principal.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * System errors; Permission errors; Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
krb5_cc_initialize(krb5_context context, krb5_ccache cache,
- krb5_principal principal);
+ krb5_principal principal);
+/**
+ * Destroy a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in] cache Credential cache handle
+ *
+ * This function destroys any existing contents of @a cache and closes the
+ * handle to it.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Permission errors
+ */
krb5_error_code KRB5_CALLCONV
-krb5_cc_destroy (krb5_context context, krb5_ccache cache);
+krb5_cc_destroy(krb5_context context, krb5_ccache cache);
+/**
+ * Close a credential cache handle.
+ *
+ * @param [in] context Library context
+ * @param [in] cache Credential cache handle
+ *
+ * This function closes a credential cache handle @a cache without affecting
+ * the contents of the cache.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_cc_close (krb5_context context, krb5_ccache cache);
+krb5_cc_close(krb5_context context, krb5_ccache cache);
+/**
+ * Store credentials in a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in,out] cache Credential cache handle
+ * @param [in] creds Credentials to be stored in cache
+ *
+ * This function stores @a creds into @a cache. If @a creds->server and the
+ * server in the decoded ticket @a creds->ticket differ, the credentials will
+ * be stored under both server principal names.
+ *
+ * @retval
+ * 0 Success
+ * @return Permission errors; storage failure errors; Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_cc_store_cred (krb5_context context, krb5_ccache cache,
- krb5_creds *creds);
+krb5_cc_store_cred(krb5_context context, krb5_ccache cache, krb5_creds *creds);
+/**
+ * Retrieve a specified credentials from a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in] cache Credential cache handle
+ * @param [in] flags Flags bit mask
+ * @param [in] mcreds Credentials to match
+ * @param [out] creds Credentials matching the requested value
+ *
+ * This function searches a credential cache for credentials matching @a mcreds
+ * and returns it if found.
+ *
+ * Valid values for @a flags are:
+ *
+ * @li #KRB5_TC_MATCH_TIMES The requested lifetime must be at least as
+ * great as in @a mcreds .
+ * @li #KRB5_TC_MATCH_IS_SKEY The @a is_skey field much match exactly.
+ * @li #KRB5_TC_MATCH_FLAGS Flags set in @a mcreds must be set.
+ * @li #KRB5_TC_MATCH_TIMES_EXACT The requested lifetime must match exactly.
+ * @li #KRB5_TC_MATCH_FLAGS_EXACT Flags must match exactly.
+ * @li #KRB5_TC_MATCH_AUTHDATA The authorization data must match.
+ * @li #KRB5_TC_MATCH_SRV_NAMEONLY Only the name portion of the principal
+ * name must match, not the realm.
+ * @li #KRB5_TC_MATCH_2ND_TKT The second tickets must match.
+ * @li #KRB5_TC_MATCH_KTYPE The encryption key types must match.
+ * @li #KRB5_TC_SUPPORTED_KTYPES Check all matching entries that have any
+ * supported encryption type and return the
+ * one with the encryption type listed earliest.
+ *
+ * Use krb5_free_cred_contents() to free @a creds when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_cc_retrieve_cred (krb5_context context, krb5_ccache cache,
- krb5_flags flags, krb5_creds *mcreds,
- krb5_creds *creds);
+krb5_cc_retrieve_cred(krb5_context context, krb5_ccache cache,
+ krb5_flags flags, krb5_creds *mcreds,
+ krb5_creds *creds);
+/**
+ * Get the default principal of a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in] cache Credential cache handle
+ * @param [out] principal Primary principal
+ *
+ * Returns the default client principal of a credential cache as set by
+ * krb5_cc_initialize().
+ *
+ * Use krb5_free_principal() to free @a principal when it is no longer needed.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_cc_get_principal (krb5_context context, krb5_ccache cache,
- krb5_principal *principal);
+krb5_cc_get_principal(krb5_context context, krb5_ccache cache,
+ krb5_principal *principal);
+/**
+ * Prepare to sequentially read every credential in a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in] cache Credential cache handle
+ * @param [out] cursor Cursor
+ *
+ * krb5_cc_end_seq_get() must be called to complete the retrieve operation.
+ *
+ * @note If @a cache is modified between the time of the call to this function
+ * and the time of the final krb5_cc_end_seq_get(), the results are undefined.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_cc_start_seq_get (krb5_context context, krb5_ccache cache,
- krb5_cc_cursor *cursor);
+krb5_cc_start_seq_get(krb5_context context, krb5_ccache cache,
+ krb5_cc_cursor *cursor);
+/**
+ * Retrieve the next entry from the credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in] cache Credential cache handle
+ * @param [in,out] cursor Cursor
+ * @param [out] creds Next credential cache entry
+ *
+ * This function fills in @a creds with the next entry in @a cache and advances
+ * @a cursor.
+ *
+ * Use krb5_free_cred_contents() to free @a creds when it is no longer needed.
+ *
+ * @sa krb5_cc_start_seq_get(), krb5_end_seq_get()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_cc_next_cred (krb5_context context, krb5_ccache cache,
- krb5_cc_cursor *cursor, krb5_creds *creds);
+krb5_cc_next_cred(krb5_context context, krb5_ccache cache,
+ krb5_cc_cursor *cursor, krb5_creds *creds);
+/**
+ * Finish a series of sequential processing credential cache entries.
+ *
+ * @param [in] context Library context
+ * @param [in] cache Credential cache handle
+ * @param [in,out] cursor Cursor
+ *
+ * This function finishes processing credential cache entries and invalidates
+ * @a cursor.
+ *
+ * @sa krb5_cc_start_seq_get(), krb5_cc_next_cred()
+ *
+ * @retval 0 (always)
+ */
krb5_error_code KRB5_CALLCONV
-krb5_cc_end_seq_get (krb5_context context, krb5_ccache cache,
- krb5_cc_cursor *cursor);
+krb5_cc_end_seq_get(krb5_context context, krb5_ccache cache,
+ krb5_cc_cursor *cursor);
+/**
+ * Remove credentials from a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in] cache Credential cache handle
+ * @param [in] flags Bitwise-ORed search flags
+ * @param [in] creds Credentials to be matched
+ *
+ * @warning This function is not implemented for some cache types.
+ *
+ * This function accepts the same flag values as krb5_cc_retrieve_cred().
+ *
+ * @retval KRB5_CC_NOSUPP Not implemented for this cache type
+ * @return No matches found; Data cannot be deleted; Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_cc_remove_cred (krb5_context context, krb5_ccache cache, krb5_flags flags,
- krb5_creds *creds);
+krb5_cc_remove_cred(krb5_context context, krb5_ccache cache, krb5_flags flags,
+ krb5_creds *creds);
+/**
+ * Set options flags on a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in,out] cache Credential cache handle
+ * @param [in] flags Flag bit mask
+ *
+ * This function resets @a cache flags to @a flags.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_cc_set_flags (krb5_context context, krb5_ccache cache, krb5_flags flags);
+krb5_cc_set_flags(krb5_context context, krb5_ccache cache, krb5_flags flags);
+/**
+ * Retrieve flags from a credential cache structure.
+ *
+ * @param [in] context Library context
+ * @param [in] cache Credential cache handle
+ * @param [out] flags Flag bit mask
+ *
+ * @warning For memory credential cache always returns a flag mask of 0.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_cc_get_flags (krb5_context context, krb5_ccache cache, krb5_flags *flags);
+krb5_cc_get_flags(krb5_context context, krb5_ccache cache, krb5_flags *flags);
+/**
+ * Retrieve the type of a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in] cache Credential cache handle
+ *
+ * @return The type of a credential cache as an alias that must not be modified
+ * or freed by the caller.
+ */
const char * KRB5_CALLCONV
-krb5_cc_get_type (krb5_context context, krb5_ccache cache);
+krb5_cc_get_type(krb5_context context, krb5_ccache cache);
+/**
+ * Move a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in] src The credential cache to move the content from
+ * @param [in] dst The credential cache to move the content to
+ *
+ * This function reinitializes @a dst and populates it with the credentials and
+ * default principal of @a src; then, if successful, destroys @a src.
+ *
+ * @retval
+ * 0 Success; @a src is closed.
+ * @return
+ * Kerberos error codes; @a src is still allocated.
+ */
krb5_error_code KRB5_CALLCONV
-krb5_cc_move (krb5_context context, krb5_ccache src, krb5_ccache dst);
+krb5_cc_move(krb5_context context, krb5_ccache src, krb5_ccache dst);
+/**
+ * Return a timestamp of the last modification to a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in] ccache Credential cache handle
+ * @param [out] change_time The last change time of @a ccache
+ *
+ * If an error occurs, @a change_time is set to 0.
+ */
krb5_error_code KRB5_CALLCONV
-krb5_cc_last_change_time (
- krb5_context context,
- krb5_ccache ccache,
- krb5_timestamp *change_time);
+krb5_cc_last_change_time(krb5_context context, krb5_ccache ccache,
+ krb5_timestamp *change_time);
+/**
+ * Lock a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in] ccache Credential cache handle
+ *
+ * Use krb5_cc_unlock() to unlock the lock.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_cc_lock (krb5_context context, krb5_ccache ccache);
+krb5_cc_lock(krb5_context context, krb5_ccache ccache);
+/**
+ * Unlock a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in] ccache Credential cache handle
+ *
+ * This function unlocks the @a ccache locked by krb5_cc_lock().
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_cc_unlock (krb5_context context, krb5_ccache ccache);
-
+krb5_cc_unlock(krb5_context context, krb5_ccache ccache);
+/**
+ * Prepare to iterate over the collection of known credential caches.
+ *
+ * @param [in] context Library context
+ * @param [in,out] cursor Cursor
+ *
+ * Get a new cache iteration @a cursor that will iterate over all known
+ * credential caches independent of type.
+ *
+ * Use krb5_cccol_cursor_free() to release @a cursor when it is no longer
+ * needed.
+ *
+ * @sa krb5_cccol_cursor_next()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
krb5_cccol_cursor_new(krb5_context context, krb5_cccol_cursor *cursor);
-krb5_error_code KRB5_CALLCONV
-krb5_cccol_cursor_next(
- krb5_context context,
- krb5_cccol_cursor cursor,
- krb5_ccache *ccache);
-
-krb5_error_code KRB5_CALLCONV
+/**
+ * Get the next credential cache in the collection.
+ *
+ * @param [in] context Library context
+ * @param [in,out] cursor Cursor
+ * @param [out] ccache Credential cache handle
+ *
+ * @note When all caches are iterated over and the end of the list is reached,
+ * @a ccache is set to NULL.
+ *
+ * Use krb5_cc_close() to close @a ccache when it is no longer needed.
+ *
+ * @sa krb5_cccol_cursor_new(), krb5_cccol_cursor_free()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_cccol_cursor_next(krb5_context context, krb5_cccol_cursor cursor,
+ krb5_ccache *ccache);
+
+/**
+ * Free a credential cache collection cursor.
+ *
+ * @param [in] context Library context
+ * @param [in] cursor Cursor
+ *
+ * @sa krb5_cccol_cursor_new(), krb5_cccol_cursor_next()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
krb5_cccol_cursor_free(krb5_context context, krb5_cccol_cursor *cursor);
+/**
+ * Return a timestamp of the last modification of any known credential cache.
+ *
+ * @param [in] context Library context
+ * @param [out] change_time Last modification timestamp
+ *
+ * This function returns the most recent modification time of any known
+ * credential cache, ignoring any caches which cannot supply a last
+ * modification time.
+ *
+ * If there are no known credential caches, @a change_time is set to 0.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
krb5_cccol_last_change_time(krb5_context context, krb5_timestamp *change_time);
+/**
+ * Acquire a global lock for credential caches.
+ *
+ * @param [in] context Library context
+ *
+ * This function locks the global credential cache collection, ensuring
+ * that no ccaches are added to or removed from it until the collection
+ * lock is released.
+ *
+ * Use krb5_cccol_unlock() to unlock the lock.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+
krb5_error_code KRB5_CALLCONV
krb5_cccol_lock(krb5_context context);
+/**
+ * Release a global lock for credential caches.
+ *
+ * @param [in] context Library context
+ *
+ * This function unlocks the lock from krb5_cccol_lock().
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
krb5_cccol_unlock(krb5_context context);
+/**
+ * Create a new credential cache of the specified type with a unique name.
+ *
+ * @param [in] context Library context
+ * @param [in] type Credential cache type name
+ * @param [in] hint Unused
+ * @param [out] id Credential cache handle
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_cc_new_unique(
- krb5_context context,
- const char *type,
- const char *hint,
- krb5_ccache *id);
+krb5_cc_new_unique(krb5_context context, const char *type, const char *hint,
+ krb5_ccache *id);
/*
* end "ccache.h"
/* XXX */
#define MAX_KEYTAB_NAME_LEN 1100 /* Long enough for MAXPATHLEN + some extra */
-typedef krb5_pointer krb5_kt_cursor; /* XXX */
+typedef krb5_pointer krb5_kt_cursor;
+/** A key table entry. */
typedef struct krb5_keytab_entry_st {
krb5_magic magic;
- krb5_principal principal; /* principal of this key */
- krb5_timestamp timestamp; /* time entry written to keytable */
- krb5_kvno vno; /* key version number */
- krb5_keyblock key; /* the secret key */
+ krb5_principal principal; /**< Principal of this key */
+ krb5_timestamp timestamp; /**< Time entry written to keytable */
+ krb5_kvno vno; /**< Key version number */
+ krb5_keyblock key; /**< The secret key */
} krb5_keytab_entry;
struct _krb5_kt;
typedef struct _krb5_kt *krb5_keytab;
+/**
+ * Return the type of a key table.
+ *
+ * @param [in] context Library context
+ * @param [in] keytab Key table handle
+ *
+ * @return The type of a key table as an alias that must not be modified or
+ * freed by the caller.
+ */
const char * KRB5_CALLCONV
-krb5_kt_get_type (krb5_context, krb5_keytab keytab);
+krb5_kt_get_type(krb5_context context, krb5_keytab keytab);
+
+/**
+ * Get a key table name.
+ *
+ * @param [in] context Library context
+ * @param [in] keytab Key table handle
+ * @param [out] name Key table name
+ * @param [in] namelen Maximum length to fill in name
+ *
+ * Fills in @a name with the name of @a keytab including the type and delimiter.
+ *
+ * @sa MAX_KEYTAB_NAME_LEN
+ *
+ * @retval
+ * 0 Success
+ * @retval
+ * KRB5_KT_NAME_TOOLONG Key table name does not fit in @a namelen bytes
+ *
+ * @return
+ * Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
krb5_kt_get_name(krb5_context context, krb5_keytab keytab, char *name,
- unsigned int namelen);
+ unsigned int namelen);
+
+/**
+ * Close a key table handle.
+ *
+ * @param [in] context Library context
+ * @param [in] keytab Key table handle
+ *
+ * @retval 0
+ */
krb5_error_code KRB5_CALLCONV
krb5_kt_close(krb5_context context, krb5_keytab keytab);
+
+/**
+ * Get an entry from a key table.
+ *
+ * @param [in] context Library context
+ * @param [in] keytab Key table handle
+ * @param [in] principal Principal name
+ * @param [in] vno Key version number (0 for highest available)
+ * @param [in] enctype Encryption type (0 zero for any enctype)
+ * @param [out] entry Returned entry from key table
+ *
+ * Retrieve an entry from a key table which matches the @a keytab, @a
+ * principal, @a vno, and @a enctype. If @a vno is zero, retrieve the
+ * highest-numbered kvno matching the other fields. If @a enctype is 0, match
+ * any enctype.
+ *
+ * Use krb5_free_keytab_entry_contents() to free @a entry when it is no longer
+ * needed.
+ *
+ * @note If @a vno is zero, the function retrieves the highest-numbered-kvno
+ * entry that matches the specified principal.
+ *
+ * @retval
+ * 0 Success
+ * @retval
+ * Kerberos error codes on failure
+ */
krb5_error_code KRB5_CALLCONV
krb5_kt_get_entry(krb5_context context, krb5_keytab keytab,
- krb5_const_principal principal, krb5_kvno vno,
- krb5_enctype enctype, krb5_keytab_entry *entry);
+ krb5_const_principal principal, krb5_kvno vno,
+ krb5_enctype enctype, krb5_keytab_entry *entry);
+
+/**
+ * Start a sequential retrieval of key table entries.
+ *
+ * @param [in] context Library context
+ * @param [in] keytab Key table handle
+ * @param [out] cursor Cursor
+ *
+ * Prepare to read sequentially every key in the specified key table. Use
+ * krb5_kt_end_seq_get() to release the cursor when it is no longer needed.
+ *
+ * @sa krb5_kt_next_entry(), krb5_kt_end_seq_get()
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
krb5_kt_start_seq_get(krb5_context context, krb5_keytab keytab,
- krb5_kt_cursor *cursor);
+ krb5_kt_cursor *cursor);
+
+/**
+ * Retrieve the next entry from the key table.
+ *
+ * @param [in] context Library context
+ * @param [in] keytab Key table handle
+ * @param [out] entry Returned key table entry
+ * @param [in,out] cursor Key table cursor
+ *
+ * Return the next sequential entry in @a keytab and advance @a cursor.
+ *
+ * @sa krb5_kt_start_seq_get(), krb5_kt_end_seq_get()
+ *
+ * @retval
+ * 0 Success
+ * @retval
+ * KRB5_KT_END - if the last entry was reached
+ * @return
+ * Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
krb5_kt_next_entry(krb5_context context, krb5_keytab keytab,
- krb5_keytab_entry *entry, krb5_kt_cursor *cursor);
+ krb5_keytab_entry *entry, krb5_kt_cursor *cursor);
+
+/**
+ * Release a keytab cursor.
+ *
+ * @param [in] context Library context
+ * @param [in] keytab Key table handle
+ * @param [out] cursor Cursor
+ *
+ * This function should be called to release the cursor created by
+ * krb5_kt_start_seq_get().
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
krb5_kt_end_seq_get(krb5_context context, krb5_keytab keytab,
- krb5_kt_cursor *cursor);
+ krb5_kt_cursor *cursor);
/*
* end "keytab.h"
* begin "func-proto.h"
*/
-krb5_error_code KRB5_CALLCONV krb5_init_context
- (krb5_context *);
-krb5_error_code KRB5_CALLCONV krb5_init_secure_context
- (krb5_context *);
-void KRB5_CALLCONV krb5_free_context
- (krb5_context);
-krb5_error_code KRB5_CALLCONV krb5_copy_context
- (krb5_context, krb5_context *);
+#define KRB5_INIT_CONTEXT_SECURE 0x1 /**< Use secure context configuration */
+#define KRB5_INIT_CONTEXT_KDC 0x2 /**< Use KDC configuration if available */
-krb5_error_code KRB5_CALLCONV
-krb5_set_default_tgs_enctypes
- (krb5_context,
- const krb5_enctype *);
+/**
+ * Create a krb5 library context.
+ *
+ * @param [out] context Library context
+ *
+ * The @a context must be released by calling krb5_free_context() when
+ * it is no longer needed.
+ *
+ * @warning Any program or module that needs the Kerberos code to not trust the
+ * environment must use krb5_init_secure_context(), or clean out the
+ * environment.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_init_context(krb5_context *context);
-krb5_error_code KRB5_CALLCONV krb5_get_permitted_enctypes
- (krb5_context, krb5_enctype **);
+/**
+ * Create a krb5 library context using only configuration files.
+ *
+ * @param [out] context Library context
+ *
+ * Create a context structure, using only system configuration files. All
+ * information passed through the environment variables is ignored.
+ *
+ * The @a context must be released by calling krb5_free_context() when
+ * it is no longer needed.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_init_secure_context(krb5_context *context);
-krb5_boolean KRB5_CALLCONV krb5_is_thread_safe(void);
+/**
+ * Create a krb5 library context using a specified profile.
+ *
+ * @param [in] profile Profile object (NULL to create default profile)
+ * @param [in] flags Context initialization flags
+ * @param [out] context Library context
+ *
+ * Create a context structure, optionally using a specified profile and
+ * initialization flags. If @a profile is NULL, the default profile will be
+ * created from config files. If @a profile is non-null, a copy of it will be
+ * made for the new context; the caller should still clean up its copy. Valid
+ * flag values are:
+ *
+ * @li #KRB5_INIT_CONTEXT_SECURE Ignore environment variables
+ * @li #KRB5_INIT_CONTEXT_KDC Use KDC configuration if creating profile
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_init_context_profile(struct _profile_t *profile, krb5_flags flags,
+ krb5_context *context);
-/* libkrb.spec */
+/**
+ * Free a krb5 library context.
+ *
+ * @param [in] context Library context
+ *
+ * This function frees a @a context that was created by krb5_init_context()
+ * or krb5_init_secure_context().
+ */
+void KRB5_CALLCONV
+krb5_free_context(krb5_context context);
+/**
+ * Copy a krb5_context structure.
+ *
+ * @param [in] ctx Library context
+ * @param [out] nctx_out New context structure
+ *
+ * The newly created context must be released by calling krb5_free_context()
+ * when it is no longer needed.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_server_decrypt_ticket_keytab
- (krb5_context context,
- const krb5_keytab kt,
- krb5_ticket *ticket);
-
-void KRB5_CALLCONV krb5_free_tgt_creds
- (krb5_context,
- krb5_creds **); /* XXX too hard to do with const */
-
-#define KRB5_GC_USER_USER 1 /* want user-user ticket */
-#define KRB5_GC_CACHED 2 /* want cached ticket only */
-#define KRB5_GC_CANONICALIZE 4 /* set canonicalize KDC option */
-#define KRB5_GC_NO_STORE 8 /* do not store in credentials cache */
-#define KRB5_GC_FORWARDABLE 16 /* acquire forwardable tickets */
-#define KRB5_GC_NO_TRANSIT_CHECK 32 /* disable transited check */
-#define KRB5_GC_CONSTRAINED_DELEGATION 64 /* constrained delegation */
-
-krb5_error_code KRB5_CALLCONV krb5_get_credentials
- (krb5_context,
- krb5_flags,
- krb5_ccache,
- krb5_creds *,
- krb5_creds **);
-krb5_error_code KRB5_CALLCONV krb5_get_credentials_validate
- (krb5_context,
- krb5_flags,
- krb5_ccache,
- krb5_creds *,
- krb5_creds **);
-krb5_error_code KRB5_CALLCONV krb5_get_credentials_renew
- (krb5_context,
- krb5_flags,
- krb5_ccache,
- krb5_creds *,
- krb5_creds **);
-krb5_error_code KRB5_CALLCONV krb5_mk_req
- (krb5_context,
- krb5_auth_context *,
- krb5_flags,
- char *,
- char *,
- krb5_data *,
- krb5_ccache,
- krb5_data * );
-krb5_error_code KRB5_CALLCONV krb5_mk_req_extended
- (krb5_context,
- krb5_auth_context *,
- krb5_flags,
- krb5_data *,
- krb5_creds *,
- krb5_data * );
-krb5_error_code KRB5_CALLCONV krb5_mk_rep
- (krb5_context,
- krb5_auth_context,
- krb5_data *);
-krb5_error_code KRB5_CALLCONV krb5_mk_rep_dce
- (krb5_context,
- krb5_auth_context,
- krb5_data *);
-krb5_error_code KRB5_CALLCONV krb5_rd_rep
- (krb5_context,
- krb5_auth_context,
- const krb5_data *,
- krb5_ap_rep_enc_part **);
-krb5_error_code KRB5_CALLCONV krb5_rd_rep_dce
- (krb5_context,
- krb5_auth_context,
- const krb5_data *,
- krb5_ui_4 *);
-krb5_error_code KRB5_CALLCONV krb5_mk_error
- (krb5_context,
- const krb5_error *,
- krb5_data * );
-krb5_error_code KRB5_CALLCONV krb5_rd_error
- (krb5_context,
- const krb5_data *,
- krb5_error ** );
-krb5_error_code KRB5_CALLCONV krb5_rd_safe
- (krb5_context,
- krb5_auth_context,
- const krb5_data *,
- krb5_data *,
- krb5_replay_data *);
-krb5_error_code KRB5_CALLCONV krb5_rd_priv
- (krb5_context,
- krb5_auth_context,
- const krb5_data *,
- krb5_data *,
- krb5_replay_data *);
-krb5_error_code KRB5_CALLCONV krb5_parse_name
- (krb5_context,
- const char *,
- krb5_principal * );
-#define KRB5_PRINCIPAL_PARSE_NO_REALM 0x1
-#define KRB5_PRINCIPAL_PARSE_REQUIRE_REALM 0x2
-#define KRB5_PRINCIPAL_PARSE_ENTERPRISE 0x4
-krb5_error_code KRB5_CALLCONV krb5_parse_name_flags
- (krb5_context,
- const char *,
- int,
- krb5_principal * );
-krb5_error_code KRB5_CALLCONV krb5_unparse_name
- (krb5_context,
- krb5_const_principal,
- char ** );
-krb5_error_code KRB5_CALLCONV krb5_unparse_name_ext
- (krb5_context,
- krb5_const_principal,
- char **,
- unsigned int *);
-#define KRB5_PRINCIPAL_UNPARSE_SHORT 0x1
-#define KRB5_PRINCIPAL_UNPARSE_NO_REALM 0x2
-#define KRB5_PRINCIPAL_UNPARSE_DISPLAY 0x4
-krb5_error_code KRB5_CALLCONV krb5_unparse_name_flags
- (krb5_context,
- krb5_const_principal,
- int,
- char **);
-krb5_error_code KRB5_CALLCONV krb5_unparse_name_flags_ext
- (krb5_context,
- krb5_const_principal,
- int,
- char **,
- unsigned int *);
-
-krb5_error_code KRB5_CALLCONV krb5_set_principal_realm
- (krb5_context, krb5_principal, const char *);
-
-krb5_boolean KRB5_CALLCONV_WRONG krb5_address_search
- (krb5_context,
- const krb5_address *,
- krb5_address * const *);
-krb5_boolean KRB5_CALLCONV krb5_address_compare
- (krb5_context,
- const krb5_address *,
- const krb5_address *);
-int KRB5_CALLCONV krb5_address_order
- (krb5_context,
- const krb5_address *,
- const krb5_address *);
-krb5_boolean KRB5_CALLCONV krb5_realm_compare
- (krb5_context,
- krb5_const_principal,
- krb5_const_principal);
-krb5_boolean KRB5_CALLCONV krb5_principal_compare
- (krb5_context,
- krb5_const_principal,
- krb5_const_principal);
-krb5_boolean KRB5_CALLCONV krb5_principal_compare_any_realm
- (krb5_context,
- krb5_const_principal,
- krb5_const_principal);
-#define KRB5_PRINCIPAL_COMPARE_IGNORE_REALM 1
-#define KRB5_PRINCIPAL_COMPARE_ENTERPRISE 2 /* compare UPNs as real principals */
-#define KRB5_PRINCIPAL_COMPARE_CASEFOLD 4 /* case-insensitive comparison */
-#define KRB5_PRINCIPAL_COMPARE_UTF8 8 /* treat principals as UTF-8 */
-
-krb5_boolean KRB5_CALLCONV krb5_principal_compare_flags
- (krb5_context,
- krb5_const_principal,
- krb5_const_principal,
- int);
-krb5_error_code KRB5_CALLCONV krb5_init_keyblock
- (krb5_context, krb5_enctype enctype,
- size_t length, krb5_keyblock **out);
- /* Initialize a new keyblock and allocate storage
- * for the contents of the key, which will be freed along
- * with the keyblock when krb5_free_keyblock is called.
- * It is legal to pass in a length of 0, in which
- * case contents are left unallocated.
- */
-krb5_error_code KRB5_CALLCONV krb5_copy_keyblock
- (krb5_context,
- const krb5_keyblock *,
- krb5_keyblock **);
-krb5_error_code KRB5_CALLCONV krb5_copy_keyblock_contents
- (krb5_context,
- const krb5_keyblock *,
- krb5_keyblock *);
-krb5_error_code KRB5_CALLCONV krb5_copy_creds
- (krb5_context,
- const krb5_creds *,
- krb5_creds **);
-krb5_error_code KRB5_CALLCONV krb5_copy_data
- (krb5_context,
- const krb5_data *,
- krb5_data **);
-krb5_error_code KRB5_CALLCONV krb5_copy_principal
- (krb5_context,
- krb5_const_principal,
- krb5_principal *);
-krb5_error_code KRB5_CALLCONV krb5_copy_addresses
- (krb5_context,
- krb5_address * const *,
- krb5_address ***);
-krb5_error_code KRB5_CALLCONV krb5_copy_ticket
- (krb5_context,
- const krb5_ticket *,
- krb5_ticket **);
-krb5_error_code KRB5_CALLCONV krb5_copy_authdata
- (krb5_context,
- krb5_authdata * const *,
- krb5_authdata ***);
-krb5_error_code KRB5_CALLCONV krb5_merge_authdata
- (krb5_context,
- krb5_authdata * const *,
- krb5_authdata *const *,
- krb5_authdata ***);
-/* Merge two authdata arrays, such as the array from a ticket
- * and authenticator */
-
-krb5_error_code KRB5_CALLCONV krb5_copy_authenticator
- (krb5_context,
- const krb5_authenticator *,
- krb5_authenticator **);
-krb5_error_code KRB5_CALLCONV krb5_copy_checksum
- (krb5_context,
- const krb5_checksum *,
- krb5_checksum **);
-krb5_error_code KRB5_CALLCONV krb5_get_server_rcache
- (krb5_context,
- const krb5_data *, krb5_rcache *);
-krb5_error_code KRB5_CALLCONV_C krb5_build_principal_ext
- (krb5_context, krb5_principal *, unsigned int, const char *, ...);
-krb5_error_code KRB5_CALLCONV_C krb5_build_principal
- (krb5_context, krb5_principal *, unsigned int, const char *, ...)
-#if __GNUC__ >= 4
- __attribute__ ((sentinel))
-#endif
- ;
-#if KRB5_DEPRECATED
-KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV krb5_build_principal_va
- (krb5_context,
- krb5_principal, unsigned int, const char *, va_list);
-#endif
-
-/* Version of krb5_build_principal_va which allocates krb5_principal_data */
-krb5_error_code KRB5_CALLCONV krb5_build_principal_alloc_va
- (krb5_context, krb5_principal *, unsigned int, const char *, va_list);
+krb5_copy_context(krb5_context ctx, krb5_context *nctx_out);
-krb5_error_code KRB5_CALLCONV krb5_425_conv_principal
- (krb5_context,
- const char *name,
- const char *instance, const char *realm,
- krb5_principal *princ);
+/**
+ * Set default TGS encryption types in a krb5_context structure.
+ *
+ * @param [in,out] context Library context
+ * @param [in] etypes Encryption type(s) to set
+ *
+ * This function sets the default enctype list for TGS requests
+ * made using @a context to @a etypes.
+ *
+ * @note This overrides the default list (from config file or built-in).
+ *
+ * @retval
+ * 0 Success
+ * @retval
+ * KRB5_PROG_ETYPE_NOSUPP Program lacks support for encryption type
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_set_default_tgs_enctypes(krb5_context context, const krb5_enctype *etypes);
-krb5_error_code KRB5_CALLCONV krb5_524_conv_principal
- (krb5_context context, krb5_const_principal princ,
- char *name, char *inst, char *realm);
+/**
+ * Return a list of encryption types permitted for session keys.
+ *
+ * @param [in] context Library context
+ * @param [out] ktypes Zero-terminated list of encryption types
+ *
+ * This function returns the list of encryption types permitted for session
+ * keys within @a context, as determined by configuration or by a previous call
+ * to krb5_set_default_tgs_enctypes().
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_permitted_enctypes(krb5_context context, krb5_enctype **ktypes);
-struct credentials;
-int KRB5_CALLCONV krb5_524_convert_creds
- (krb5_context context, krb5_creds *v5creds,
- struct credentials *v4creds);
-#if KRB5_DEPRECATED
-#define krb524_convert_creds_kdc krb5_524_convert_creds
-#define krb524_init_ets(x) (0)
-#endif
+/**
+ * Test whether the Kerberos library was built with multithread support.
+ *
+ * @retval
+ * TRUE if the library is threadsafe; FALSE otherwise
+ */
+krb5_boolean KRB5_CALLCONV
+krb5_is_thread_safe(void);
-/* libkt.spec */
-krb5_error_code KRB5_CALLCONV krb5_kt_resolve
- (krb5_context,
- const char *,
- krb5_keytab * );
-krb5_error_code KRB5_CALLCONV krb5_kt_default_name
- (krb5_context,
- char *,
- int );
-krb5_error_code KRB5_CALLCONV krb5_kt_default
- (krb5_context,
- krb5_keytab * );
-krb5_error_code KRB5_CALLCONV krb5_free_keytab_entry_contents
- (krb5_context,
- krb5_keytab_entry * );
-/* remove and add are functions, so that they can return NOWRITE
- if not a writable keytab */
-krb5_error_code KRB5_CALLCONV krb5_kt_remove_entry
- (krb5_context,
- krb5_keytab,
- krb5_keytab_entry * );
-krb5_error_code KRB5_CALLCONV krb5_kt_add_entry
- (krb5_context,
- krb5_keytab,
- krb5_keytab_entry * );
-krb5_error_code KRB5_CALLCONV_WRONG krb5_principal2salt
- (krb5_context,
- krb5_const_principal, krb5_data *);
-/* librc.spec--see rcache.h */
+/* libkrb.spec */
-/* libcc.spec */
-krb5_error_code KRB5_CALLCONV krb5_cc_resolve
- (krb5_context,
- const char *,
- krb5_ccache * );
-const char * KRB5_CALLCONV krb5_cc_default_name
- (krb5_context);
-krb5_error_code KRB5_CALLCONV krb5_cc_set_default_name
- (krb5_context, const char *);
-krb5_error_code KRB5_CALLCONV krb5_cc_default
- (krb5_context,
- krb5_ccache *);
-
-krb5_error_code KRB5_CALLCONV krb5_cc_copy_creds
- (krb5_context context,
- krb5_ccache incc,
- krb5_ccache outcc);
+/**
+ * Decrypt a ticket using the specified key table.
+ *
+ * @param [in] context Library context
+ * @param [in] kt Key table
+ * @param [in,out] ticket Ticket to be decrypted
+ *
+ * This function takes a @a ticket as input and decrypts it using
+ * key data from @a kt. The result is placed into @a ticket->enc_part2.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_server_decrypt_ticket_keytab(krb5_context context, const krb5_keytab kt,
+ krb5_ticket *ticket);
+/**
+ * Free an array of credential structures.
+ *
+ * @param [in] context Library context
+ * @param [in] tgts Null-terminated array of credentials to free
+ *
+ * @note The last entry in the array @a tgts must be a NULL pointer.
+ */
+void KRB5_CALLCONV
+krb5_free_tgt_creds(krb5_context context, krb5_creds **tgts);
-/* krb5_free.c */
-void KRB5_CALLCONV krb5_free_principal
- (krb5_context, krb5_principal );
-void KRB5_CALLCONV krb5_free_authenticator
- (krb5_context, krb5_authenticator * );
-void KRB5_CALLCONV krb5_free_addresses
- (krb5_context, krb5_address ** );
-void KRB5_CALLCONV krb5_free_authdata
- (krb5_context, krb5_authdata ** );
-void KRB5_CALLCONV krb5_free_ticket
- (krb5_context, krb5_ticket * );
-void KRB5_CALLCONV krb5_free_error
- (krb5_context, krb5_error * );
-void KRB5_CALLCONV krb5_free_creds
- (krb5_context, krb5_creds *);
-void KRB5_CALLCONV krb5_free_cred_contents
- (krb5_context, krb5_creds *);
-void KRB5_CALLCONV krb5_free_checksum
- (krb5_context, krb5_checksum *);
-void KRB5_CALLCONV krb5_free_checksum_contents
- (krb5_context, krb5_checksum *);
-void KRB5_CALLCONV krb5_free_keyblock
- (krb5_context, krb5_keyblock *);
-void KRB5_CALLCONV krb5_free_keyblock_contents
- (krb5_context, krb5_keyblock *);
-void KRB5_CALLCONV krb5_free_ap_rep_enc_part
- (krb5_context, krb5_ap_rep_enc_part *);
-void KRB5_CALLCONV krb5_free_data
- (krb5_context, krb5_data *);
-void KRB5_CALLCONV krb5_free_data_contents
- (krb5_context, krb5_data *);
-void KRB5_CALLCONV krb5_free_unparsed_name
- (krb5_context, char *);
-void KRB5_CALLCONV krb5_free_cksumtypes
- (krb5_context, krb5_cksumtype *);
-
-/* From krb5/os but needed but by the outside world */
-krb5_error_code KRB5_CALLCONV krb5_us_timeofday
- (krb5_context,
- krb5_timestamp *,
- krb5_int32 * );
-krb5_error_code KRB5_CALLCONV krb5_timeofday
- (krb5_context,
- krb5_timestamp * );
- /* get all the addresses of this host */
-krb5_error_code KRB5_CALLCONV krb5_os_localaddr
- (krb5_context,
- krb5_address ***);
-krb5_error_code KRB5_CALLCONV krb5_get_default_realm
- (krb5_context,
- char ** );
-krb5_error_code KRB5_CALLCONV krb5_set_default_realm
- (krb5_context,
- const char * );
-void KRB5_CALLCONV krb5_free_default_realm
- (krb5_context,
- char * );
-krb5_error_code KRB5_CALLCONV krb5_sname_to_principal
- (krb5_context,
- const char *,
- const char *,
- krb5_int32,
- krb5_principal *);
-krb5_error_code KRB5_CALLCONV
-krb5_change_password
- (krb5_context context, krb5_creds *creds, char *newpw,
- int *result_code, krb5_data *result_code_string,
- krb5_data *result_string);
-krb5_error_code KRB5_CALLCONV
-krb5_set_password
- (krb5_context context, krb5_creds *creds, char *newpw, krb5_principal change_password_for,
- int *result_code, krb5_data *result_code_string, krb5_data *result_string);
-krb5_error_code KRB5_CALLCONV
-krb5_set_password_using_ccache
- (krb5_context context, krb5_ccache ccache, char *newpw, krb5_principal change_password_for,
- int *result_code, krb5_data *result_code_string, krb5_data *result_string);
-
-krb5_error_code KRB5_CALLCONV
-krb5_get_profile
- (krb5_context, struct _profile_t * /* profile_t */ *);
+/** @defgroup KRB5_GC KRB5_GC
+ * @{
+ */
+#define KRB5_GC_USER_USER 1 /**< Want user-user ticket */
+#define KRB5_GC_CACHED 2 /**< Want cached ticket only */
+#define KRB5_GC_CANONICALIZE 4 /**< Set canonicalize KDC option */
+#define KRB5_GC_NO_STORE 8 /**< Do not store in credential cache */
+#define KRB5_GC_FORWARDABLE 16 /**< Acquire forwardable tickets */
+#define KRB5_GC_NO_TRANSIT_CHECK 32 /**< Disable transited check */
+#define KRB5_GC_CONSTRAINED_DELEGATION 64 /**< Constrained delegation */
+/** @} */ /* end of KRB5_GC group */
+
+/**
+ * Get an additional ticket.
+ *
+ * @param [in] context Library context
+ * @param [in] options Options
+ * @param [in,out] ccache Credential cache handle
+ * @param [in] in_creds Input credentials
+ * @param [out] out_creds Output updated credentials
+ *
+ * Use @a ccache or a TGS exchange to get a service ticket matching @a
+ * in_creds.
+ *
+ * Valid values for @a options are:
+ * @li #KRB5_GC_CACHED Search only credential cache for the ticket
+ * @li #KRB5_GC_USER_USER Return a user to user authentication ticket
+ *
+ * @a in_creds must be non-null. @a in_creds->client and @a in_creds->server
+ * must be filled in to specify the client and the server respectively. If any
+ * authorization data needs to be requested for the service ticket (such as
+ * restrictions on how the ticket can be used), specify it in @a
+ * in_creds->authdata; otherwise set @a in_creds->authdata to NULL. The
+ * session key type is specified in @a in_creds->keyblock.enctype, if it is
+ * nonzero.
+ *
+ * The expiration date is specified in @a in_creds->times.endtime.
+ * The KDC may return tickets with an earlier expiration date.
+ * If @a in_creds->times.endtime is set to 0, the latest possible
+ * expiration date will be requested.
+ *
+ * Any returned ticket and intermediate ticket-granting tickets are stored
+ * in @a ccache.
+ *
+ * Use krb5_free_creds() to free @a out_creds when it is no longer needed.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_credentials(krb5_context context, krb5_flags options,
+ krb5_ccache ccache, krb5_creds *in_creds,
+ krb5_creds **out_creds);
-#if KRB5_DEPRECATED
-KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV krb5_get_in_tkt
- (krb5_context,
- krb5_flags,
- krb5_address * const *,
- krb5_enctype *,
- krb5_preauthtype *,
- krb5_error_code ( * )(krb5_context,
- krb5_enctype,
- krb5_data *,
- krb5_const_pointer,
- krb5_keyblock **),
- krb5_const_pointer,
- krb5_error_code ( * )(krb5_context,
- const krb5_keyblock *,
- krb5_const_pointer,
- krb5_kdc_rep * ),
- krb5_const_pointer,
- krb5_creds *,
- krb5_ccache,
- krb5_kdc_rep ** );
-
-KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV krb5_get_in_tkt_with_password
- (krb5_context,
- krb5_flags,
- krb5_address * const *,
- krb5_enctype *,
- krb5_preauthtype *,
- const char *,
- krb5_ccache,
- krb5_creds *,
- krb5_kdc_rep ** );
-
-KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV krb5_get_in_tkt_with_skey
- (krb5_context,
- krb5_flags,
- krb5_address * const *,
- krb5_enctype *,
- krb5_preauthtype *,
- const krb5_keyblock *,
- krb5_ccache,
- krb5_creds *,
- krb5_kdc_rep ** );
-
-KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV krb5_get_in_tkt_with_keytab
- (krb5_context,
- krb5_flags,
- krb5_address * const *,
- krb5_enctype *,
- krb5_preauthtype *,
- krb5_keytab,
- krb5_ccache,
- krb5_creds *,
- krb5_kdc_rep ** );
-#endif /* KRB5_DEPRECATED */
+/** @deprecated Replaced by krb5_get_validated_creds. */
+krb5_error_code KRB5_CALLCONV
+krb5_get_credentials_validate(krb5_context context, krb5_flags options,
+ krb5_ccache ccache, krb5_creds *in_creds,
+ krb5_creds **out_creds);
-krb5_error_code KRB5_CALLCONV krb5_rd_req
- (krb5_context,
- krb5_auth_context *,
- const krb5_data *,
- krb5_const_principal,
- krb5_keytab,
- krb5_flags *,
- krb5_ticket **);
-
-krb5_error_code KRB5_CALLCONV krb5_kt_read_service_key
- (krb5_context,
- krb5_pointer,
- krb5_principal,
- krb5_kvno,
- krb5_enctype,
- krb5_keyblock **);
-krb5_error_code KRB5_CALLCONV krb5_mk_safe
- (krb5_context,
- krb5_auth_context,
- const krb5_data *,
- krb5_data *,
- krb5_replay_data *);
-krb5_error_code KRB5_CALLCONV krb5_mk_priv
- (krb5_context,
- krb5_auth_context,
- const krb5_data *,
- krb5_data *,
- krb5_replay_data *);
-
-krb5_error_code KRB5_CALLCONV krb5_sendauth
- (krb5_context,
- krb5_auth_context *,
- krb5_pointer,
- char *,
- krb5_principal,
- krb5_principal,
- krb5_flags,
- krb5_data *,
- krb5_creds *,
- krb5_ccache,
- krb5_error **,
- krb5_ap_rep_enc_part **,
- krb5_creds **);
-
-krb5_error_code KRB5_CALLCONV krb5_recvauth
- (krb5_context,
- krb5_auth_context *,
- krb5_pointer,
- char *,
- krb5_principal,
- krb5_int32,
- krb5_keytab,
- krb5_ticket **);
-krb5_error_code KRB5_CALLCONV krb5_recvauth_version
- (krb5_context,
- krb5_auth_context *,
- krb5_pointer,
- krb5_principal,
- krb5_int32,
- krb5_keytab,
- krb5_ticket **,
- krb5_data *);
-
-krb5_error_code KRB5_CALLCONV krb5_mk_ncred
- (krb5_context,
- krb5_auth_context,
- krb5_creds **,
- krb5_data **,
- krb5_replay_data *);
-
-krb5_error_code KRB5_CALLCONV krb5_mk_1cred
- (krb5_context,
- krb5_auth_context,
- krb5_creds *,
- krb5_data **,
- krb5_replay_data *);
-
-krb5_error_code KRB5_CALLCONV krb5_rd_cred
- (krb5_context,
- krb5_auth_context,
- krb5_data *,
- krb5_creds ***,
- krb5_replay_data *);
-
-krb5_error_code KRB5_CALLCONV krb5_fwd_tgt_creds
- (krb5_context,
- krb5_auth_context,
- char *,
- krb5_principal,
- krb5_principal,
- krb5_ccache,
- int forwardable,
- krb5_data *);
-
-krb5_error_code KRB5_CALLCONV krb5_auth_con_init
- (krb5_context,
- krb5_auth_context *);
-
-krb5_error_code KRB5_CALLCONV krb5_auth_con_free
- (krb5_context,
- krb5_auth_context);
-
-krb5_error_code KRB5_CALLCONV krb5_auth_con_setflags
- (krb5_context,
- krb5_auth_context,
- krb5_int32);
-
-krb5_error_code KRB5_CALLCONV krb5_auth_con_getflags
- (krb5_context,
- krb5_auth_context,
- krb5_int32 *);
-
-krb5_error_code KRB5_CALLCONV
-krb5_auth_con_set_checksum_func (krb5_context, krb5_auth_context,
- krb5_mk_req_checksum_func, void *);
-
-krb5_error_code KRB5_CALLCONV
-krb5_auth_con_get_checksum_func( krb5_context, krb5_auth_context,
- krb5_mk_req_checksum_func *, void **);
-
-krb5_error_code KRB5_CALLCONV_WRONG krb5_auth_con_setaddrs
- (krb5_context,
- krb5_auth_context,
- krb5_address *,
- krb5_address *);
-
-krb5_error_code KRB5_CALLCONV krb5_auth_con_getaddrs
- (krb5_context,
- krb5_auth_context,
- krb5_address **,
- krb5_address **);
-
-krb5_error_code KRB5_CALLCONV krb5_auth_con_setports
- (krb5_context,
- krb5_auth_context,
- krb5_address *,
- krb5_address *);
-
-krb5_error_code KRB5_CALLCONV krb5_auth_con_setuseruserkey
- (krb5_context,
- krb5_auth_context,
- krb5_keyblock *);
-
-krb5_error_code KRB5_CALLCONV krb5_auth_con_getkey
- (krb5_context,
- krb5_auth_context,
- krb5_keyblock **);
-
-krb5_error_code KRB5_CALLCONV krb5_auth_con_getsendsubkey(
- krb5_context, krb5_auth_context, krb5_keyblock **);
-
-krb5_error_code KRB5_CALLCONV krb5_auth_con_getrecvsubkey(
- krb5_context, krb5_auth_context, krb5_keyblock **);
-
-krb5_error_code KRB5_CALLCONV krb5_auth_con_setsendsubkey(
- krb5_context, krb5_auth_context, krb5_keyblock *);
-
-krb5_error_code KRB5_CALLCONV krb5_auth_con_setrecvsubkey(
- krb5_context, krb5_auth_context, krb5_keyblock *);
+/** @deprecated Replaced by krb5_get_renewed_creds. */
+krb5_error_code KRB5_CALLCONV
+krb5_get_credentials_renew(krb5_context context, krb5_flags options,
+ krb5_ccache ccache, krb5_creds *in_creds,
+ krb5_creds **out_creds);
-#if KRB5_DEPRECATED
-KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV krb5_auth_con_getlocalsubkey
- (krb5_context,
- krb5_auth_context,
- krb5_keyblock **);
-
-KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV krb5_auth_con_getremotesubkey
- (krb5_context,
- krb5_auth_context,
- krb5_keyblock **);
-#endif
+/**
+ * Create a @c KRB_AP_REQ message.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Pre-existing or newly created auth context
+ * @param [in] ap_req_options @ref AP_OPTS options
+ * @param [in] service Service name, or NULL to use @c "host"
+ * @param [in] hostname Host name, or NULL to use local hostname
+ * @param [in] in_data Application data to be checksummed in the
+ * authenticator, or NULL
+ * @param [in] ccache Credential cache used to obtain credentials
+ * for the desired service.
+ * @param [out] outbuf @c AP-REQ message
+ *
+ * This function is similar to krb5_mk_req_extended() except that it uses a
+ * given @a hostname, @a service, and @a ccache to construct a service
+ * principal name and obtain credentials.
+ *
+ * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_mk_req(krb5_context context, krb5_auth_context *auth_context,
+ krb5_flags ap_req_options, char *service, char *hostname,
+ krb5_data *in_data, krb5_ccache ccache, krb5_data *outbuf);
-krb5_error_code KRB5_CALLCONV krb5_auth_con_getlocalseqnumber
- (krb5_context,
- krb5_auth_context,
- krb5_int32 *);
+/**
+ * Create a @c KRB_AP_REQ message using supplied credentials.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Pre-existing or newly created auth context
+ * @param [in] ap_req_options @ref AP_OPTS options
+ * @param [in] in_data Application data to be checksummed in the
+ * authenticator, or NULL
+ * @param [in] in_creds Credentials for the service with valid ticket
+ * and key
+ * @param [out] outbuf @c AP-REQ message
+ *
+ * Valid @a ap_req_options are:
+ * @li #AP_OPTS_USE_SESSION_KEY - Use the session key when creating the
+ * request used for user to user
+ * authentication.
+ * @li #AP_OPTS_MUTUAL_REQUIRED - Request a mutual authentication packet from
+ * the reciever.
+ * @li #AP_OPTS_USE_SUBKEY - Generate a subsession key from the current
+ * session key obtained from the credentials.
+ *
+ * This function creates a KRB_AP_REQ message using supplied credentials @a
+ * in_creds. @a auth_context may point to an existing auth context or to NULL,
+ * in which case a new one will be created. If @a in_data is non-null, a
+ * checksum of it will be included in the authenticator contained in the
+ * KRB_AP_REQ message. Use krb5_free_data_contents() to free @a outbuf when it
+ * is no longer needed.
+ *
+ * On successful return, the authenticator is stored in @a auth_context with
+ * the @a client and @a checksum fields nulled out. (This is to prevent
+ * pointer-sharing problems; the caller should not need these fields anyway,
+ * since the caller supplied them.)
+ *
+ * @sa krb5_mk_req()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_mk_req_extended(krb5_context context, krb5_auth_context *auth_context,
+ krb5_flags ap_req_options, krb5_data *in_data,
+ krb5_creds *in_creds, krb5_data *outbuf);
-krb5_error_code KRB5_CALLCONV krb5_auth_con_getremoteseqnumber
- (krb5_context,
- krb5_auth_context,
- krb5_int32 *);
+/**
+ * Format and encrypt a @c KRB_AP_REP message.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [out] outbuf @c AP-REP message
+ *
+ * This function fills in @a outbuf with an AP-REP message using information
+ * from @a auth_context.
+ *
+ * If the flags in @a auth_context indicate that a sequence number should be
+ * used (either #KRB5_AUTH_CONTEXT_DO_SEQUENCE or
+ * #KRB5_AUTH_CONTEXT_RET_SEQUENCE) and the local sequence number in @a
+ * auth_context is 0, a new number will be generated with
+ * krb5_generate_seq_number().
+ *
+ * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_mk_rep(krb5_context context, krb5_auth_context auth_context, krb5_data *outbuf);
-#if KRB5_DEPRECATED
-KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV krb5_auth_con_initivector
- (krb5_context,
- krb5_auth_context);
-#endif
+/**
+ * Format and encrypt a @c KRB_AP_REP message for DCE RPC.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [out] outbuf @c AP-REP message
+ *
+ * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_mk_rep_dce(krb5_context context, krb5_auth_context auth_context, krb5_data *outbuf);
-krb5_error_code KRB5_CALLCONV krb5_auth_con_setrcache
- (krb5_context,
- krb5_auth_context,
- krb5_rcache);
+/**
+ * Parse and decrypt a @c KRB_AP_REP message.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in] inbuf AP-REP message
+ * @param [out] repl Decrypted reply message
+ *
+ * This function parses, decrypts and verifies a message from @a inbuf and
+ * fills in @a repl with a pointer to allocated memory containing the fields
+ * from the encrypted response.
+ *
+ * Use krb5_free_ap_rep_enc_part() to free @a repl when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_rd_rep(krb5_context context, krb5_auth_context auth_context,
+ const krb5_data *inbuf, krb5_ap_rep_enc_part **repl);
-krb5_error_code KRB5_CALLCONV_WRONG krb5_auth_con_getrcache
- (krb5_context,
- krb5_auth_context,
- krb5_rcache *);
+/**
+ * Parse and decrypt a @c KRB_AP_REP message for DCE RPC.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in] inbuf AP-REP message
+ * @param [out] nonce Sequence number from the decrypted reply
+ *
+ * This function parses, decrypts and verifies a message from @a inbuf and
+ * fills in @a nonce with a decrypted reply sequence number.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_rd_rep_dce(krb5_context context, krb5_auth_context auth_context,
+ const krb5_data *inbuf, krb5_ui_4 *nonce);
-krb5_error_code KRB5_CALLCONV krb5_auth_con_getauthenticator
- (krb5_context,
- krb5_auth_context,
- krb5_authenticator **);
+/**
+ * Format and encode a @c KRB_ERROR message.
+ *
+ * @param [in] context Library context
+ * @param [in] dec_err Error structure to be encoded
+ * @param [out] enc_err Encoded error structure
+ *
+ * This function creates a @c KRB_ERROR message in @a enc_err. Use
+ * krb5_free_data_contents() to free @a enc_err when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_mk_error(krb5_context context, const krb5_error *dec_err,
+ krb5_data *enc_err);
-#define KRB5_REALM_BRANCH_CHAR '.'
+/**
+ * Decode a @c KRB-ERROR message.
+ *
+ * @param [in] context Library context
+ * @param [in] enc_errbuf Encoded error message
+ * @param [out] dec_error Decoded error message
+ *
+ * This function processes @c KRB-ERROR message @a enc_errbuf and returns
+ * an allocated structure @a dec_error containing the error message.
+ * Use krb5_free_error() to free @a dec_error when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_rd_error(krb5_context context, const krb5_data *enc_errbuf,
+ krb5_error **dec_error);
-/*
- * end "func-proto.h"
+/**
+ * Process @c KRB-SAFE message.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Authentication structure
+ * @param [in] inbuf @c KRB-SAFE message to be parsed
+ * @param [out] outbuf Data parsed from @c KRB-SAFE message
+ * @param [out] outdata Replay data. Specify NULL if not needed
+ *
+ * This function parses a @c KRB-SAFE message, verifies its integrity, and
+ * stores its data into @a outbuf.
+ *
+ * @note The @a outdata argument is required if #KRB5_AUTH_CONTEXT_RET_TIME or
+ * #KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in the @a auth_context.
+ *
+ * @note @a auth_context must have a remote address set. This address will be
+ * used to verify the sender address in the KRB-SAFE message. If @a
+ * auth_context has a local address set, it will be used to verify the
+ * receiver address in the KRB-SAFE message if the message contains one.
+ * Both addresses must use type @c ADDRTYPE_ADDRPORT.
+ *
+ * If the #KRB5_AUTH_CONTEXT_DO_SEQUENCE flag is set in @a auth_context, the
+ * sequence number of the KRB-SAFE message is checked against the remote
+ * sequence number field of @a auth_context. Otherwise, the sequence number is
+ * not used.
+ *
+ * If the #KRB5_AUTH_CONTEXT_DO_TIME flag is set in @a auth_context,
+ * then two additional checks are performed:
+ * @li The timestamp in the message must be within the permitted clock skew
+ * (which is usually five minutes).
+ * @li The message must not be a replayed message field in @a auth_context.
+ *
+ * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
*/
+krb5_error_code KRB5_CALLCONV
+krb5_rd_safe(krb5_context context, krb5_auth_context auth_context,
+ const krb5_data *inbuf, krb5_data *outbuf,
+ krb5_replay_data *outdata);
-/*
- * begin stuff from libos.h
+/**
+ * Process a @c KRB-PRIV message.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Authentication structure
+ * @param [in] inbuf @c KRB-PRIV message to be parsed
+ * @param [out] outbuf Data parsed from @c KRB-PRIV message
+ * @param [out] outdata Replay data. Specify NULL if not needed
+ *
+ * This function parses a @c KRB-PRIV message, verifies its integrity, and
+ * stores its unencrypted data into @a outbuf.
+ *
+ * @note If the #KRB5_AUTH_CONTEXT_RET_TIME or @c
+ * #KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in @a auth_context, @a
+ * outdata is required.
+ *
+ * @note @a auth_context must have a remote address set. This address will be
+ * used to verify the sender address in the KRB-PRIV message. If @a
+ * auth_context has a local address set, it will be used to verify the
+ * receiver address in the KRB-PRIV message if the message contains one.
+ * Both addresses must use type @c ADDRTYPE_ADDRPORT.
+ *
+ * If the #KRB5_AUTH_CONTEXT_DO_SEQUENCE flag is set in @a auth_context, the
+ * sequence number of the KRB-SAFE message is checked against the remote
+ * sequence number field of @a auth_context. Otherwise, the sequence number is
+ * not used.
+ *
+ * If the #KRB5_AUTH_CONTEXT_DO_TIME flag is set in @a auth_context,
+ * then two additional checks are performed:
+ * @li The timestamp in the message must be within the permitted clock skew
+ * (which is usually five minutes).
+ * @li The message must not be a replayed message field in @a auth_context.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
*/
+krb5_error_code KRB5_CALLCONV
+krb5_rd_priv(krb5_context context, krb5_auth_context auth_context,
+ const krb5_data *inbuf, krb5_data *outbuf,
+ krb5_replay_data *outdata);
-krb5_error_code KRB5_CALLCONV krb5_read_password
- (krb5_context,
- const char *,
- const char *,
- char *,
- unsigned int * );
-krb5_error_code KRB5_CALLCONV krb5_aname_to_localname
- (krb5_context,
- krb5_const_principal,
- int,
- char * );
-krb5_error_code KRB5_CALLCONV krb5_get_host_realm
- (krb5_context,
- const char *,
- char *** );
-krb5_error_code KRB5_CALLCONV krb5_get_fallback_host_realm
- (krb5_context,
- krb5_data *,
- char *** );
-krb5_error_code KRB5_CALLCONV krb5_free_host_realm
- (krb5_context,
- char * const * );
-krb5_boolean KRB5_CALLCONV krb5_kuserok
- (krb5_context,
- krb5_principal, const char *);
-krb5_error_code KRB5_CALLCONV krb5_auth_con_genaddrs
- (krb5_context,
- krb5_auth_context,
- int, int);
-krb5_error_code KRB5_CALLCONV krb5_set_real_time
- (krb5_context, krb5_timestamp, krb5_int32);
-
-krb5_error_code KRB5_CALLCONV krb5_get_time_offsets
- (krb5_context, krb5_timestamp *, krb5_int32 *);
+/**
+ * Convert a string principal name to a krb5_principal structure.
+ *
+ * @param [in] context Library context
+ * @param [in] name String representation of a principal name
+ * @param [out] nprincipal Principal
+ *
+ * Convert a string representation of a principal name to a krb5_principal
+ * structure.
+ *
+ * A string representation of a Kerberos name consists of one or more principal
+ * name components, separated by slashes, optionally followed by the \@
+ * character and a realm name. If the realm name is not specified, the local
+ * realm is used.
+ *
+ * To use the slash and \@ symbols as part of a component (quoted) instead of
+ * using them as a component separator or as a realm prefix), put a backslash
+ * (\) character in front of the symbol. Similarly, newline, tab, backspace,
+ * and NULL characters can be included in a component by using @c n, @c t, @c b
+ * or @c 0, respectively.
+ *
+ * @note The realm in a Kerberos @a name cannot contain slash, colon,
+ * or NULL characters.
+ *
+ * Use krb5_free_principal() to free @a nprincipal when it is no longer needed.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_parse_name(krb5_context context, const char *name, krb5_principal *nprincipal);
-/* str_conv.c */
-krb5_error_code KRB5_CALLCONV krb5_string_to_enctype
- (char *, krb5_enctype *);
-krb5_error_code KRB5_CALLCONV krb5_string_to_salttype
- (char *, krb5_int32 *);
-krb5_error_code KRB5_CALLCONV krb5_string_to_cksumtype
- (char *, krb5_cksumtype *);
-krb5_error_code KRB5_CALLCONV krb5_string_to_timestamp
- (char *, krb5_timestamp *);
-krb5_error_code KRB5_CALLCONV krb5_string_to_deltat
- (char *, krb5_deltat *);
-krb5_error_code KRB5_CALLCONV krb5_enctype_to_string
- (krb5_enctype, char *, size_t);
-krb5_error_code KRB5_CALLCONV krb5_salttype_to_string
- (krb5_int32, char *, size_t);
-krb5_error_code KRB5_CALLCONV krb5_cksumtype_to_string
- (krb5_cksumtype, char *, size_t);
-krb5_error_code KRB5_CALLCONV krb5_timestamp_to_string
- (krb5_timestamp, char *, size_t);
-krb5_error_code KRB5_CALLCONV krb5_timestamp_to_sfstring
- (krb5_timestamp, char *, size_t, char *);
-krb5_error_code KRB5_CALLCONV krb5_deltat_to_string
- (krb5_deltat, char *, size_t);
+#define KRB5_PRINCIPAL_PARSE_NO_REALM 0x1 /**< Error if realm is present */
+#define KRB5_PRINCIPAL_PARSE_REQUIRE_REALM 0x2 /**< Error if realm is not present */
+#define KRB5_PRINCIPAL_PARSE_ENTERPRISE 0x4 /**< Create single-component
+ enterprise principle */
+/**
+ * Convert a string principal name to a krb5_principal with flags
+ *
+ * @param [in] context Library context
+ * @param [in] name String representation of a principal name
+ * @param [in] flags Flag
+ * @param [out] nprincipal Principal
+ *
+ * Similar to krb5_parse_name(), this function converts a single-string
+ * representation of a principal name to a krb5_principal structure.
+ *
+ * The following flags are valid:
+ * @li #KRB5_PRINCIPAL_PARSE_NO_REALM - no realm must be present in @a name
+ * @li #KRB5_PRINCIPAL_PARSE_REQUIRE_REALM - realm must be present in @a name
+ * @li #KRB5_PRINCIPAL_PARSE_ENTERPRISE - create single-component enterprise
+ * principal
+ *
+ * Use krb5_free_principal() to free @a nprincipal when it is no longer needed.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_parse_name_flags(krb5_context context, const char *name,
+ int flags, krb5_principal *nprincipal);
+/**
+ * Convert a krb5_principal structure to a string representation.
+ *
+ * @param [in] context Library context
+ * @param [in] principal Principal
+ * @param [out] name String representation of principal name
+ *
+ * The resulting string representation uses the format and quoting conventions
+ * described for krb5_parse_name().
+ *
+ * Use krb5_free_unparsed_name() to free @a name when it is no longer needed.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_unparse_name(krb5_context context, krb5_const_principal principal,
+ register char **name);
-/* The name of the Kerberos ticket granting service... and its size */
-#define KRB5_TGS_NAME "krbtgt"
-#define KRB5_TGS_NAME_SIZE 6
+/**
+ * Convert krb5_principal structure to string and length.
+ *
+ * @param [in] context Library context
+ * @param [in] principal Principal
+ * @param [out] name String representation of principal name
+ * @param [out] size Size of unparsed name
+ *
+ * This function is similar to krb5_unparse_name(), but also returns the length
+ * of the string representation.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes. On failure @a name is set to NULL
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_unparse_name_ext(krb5_context context, krb5_const_principal principal,
+ char **name, unsigned int *size);
-/* flags for recvauth */
-#define KRB5_RECVAUTH_SKIP_VERSION 0x0001
-#define KRB5_RECVAUTH_BADAUTHVERS 0x0002
-/* initial ticket api functions */
+#define KRB5_PRINCIPAL_UNPARSE_SHORT 0x1 /**< Omit realm if it is the local realm */
+#define KRB5_PRINCIPAL_UNPARSE_NO_REALM 0x2 /**< Omit realm always */
+#define KRB5_PRINCIPAL_UNPARSE_DISPLAY 0x4 /**< Don't escape special characters */
-typedef struct _krb5_prompt {
- char *prompt;
- int hidden;
- krb5_data *reply;
+/**
+ * Convert krb5_principal structure to a string with flags.
+ *
+ * @param [in] context Library context
+ * @param [in] principal Principal
+ * @param [in] flags Flags
+ * @param [out] name String representation of principal name
+ *
+ * Similar to krb5_unparse_name(), this function converts a krb5_principal
+ * structure to a string representation.
+ *
+ * The following flags are valid:
+ * @li #KRB5_PRINCIPAL_UNPARSE_SHORT - omit realm if it is the local realm
+ * @li #KRB5_PRINCIPAL_UNPARSE_NO_REALM - omit realm
+ * @li #KRB5_PRINCIPAL_UNPARSE_DISPLAY - do not quote special characters
+ *
+ * Use krb5_free_unparsed_name() to free @a name when it is no longer needed.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes. On failure @a name is set to NULL
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_unparse_name_flags(krb5_context context, krb5_const_principal principal,
+ int flags, char **name);
+
+/**
+ * Convert krb5_principal structure to string format with flags.
+ *
+ * @param [in] context Library context
+ * @param [in] principal Principal
+ * @param [in] flags Flags
+ * @param [out] name Single string format of principal name
+ * @param [out] size Size of unparsed name buffer
+ *
+ * @sa krb5_unparse_name() krb5_unparse_name_flags() krb5_unparse_name_ext()
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes. On failure @a name is set to NULL
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_unparse_name_flags_ext(krb5_context context, krb5_const_principal principal,
+ int flags, char **name, unsigned int *size);
+
+/**
+ * Set the realm field of a principal
+ *
+ * @param [in,out] context Library context
+ * @param [in] principal Principal name
+ * @param [in] realm Realm name
+ *
+ * Set the realm name part of @a principal to @a realm, overwriting the
+ * previous realm.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_set_principal_realm(krb5_context context, krb5_principal principal,
+ const char *realm);
+
+/**
+ * Search a list of addresses for a specified address.
+ *
+ * @param [in] context Library context
+ * @param [in] addr Address to search for
+ * @param [in] addrlist Address list to be searched (or NULL)
+ *
+ * @note If @a addrlist contains only a NetBIOS addresses, it will be treated
+ * as a null list.
+ *
+ * @return
+ * TRUE if @a addr is listed in @a addrlist, or @c addrlist is NULL; FALSE
+ * otherwise
+ */
+krb5_boolean KRB5_CALLCONV_WRONG
+krb5_address_search(krb5_context context, const krb5_address *addr,
+ krb5_address *const *addrlist);
+
+/**
+ * Compare two Kerberos addresses.
+ *
+ * @param [in] context Library context
+ * @param [in] addr1 First address to be compared
+ * @param [in] addr2 Second address to be compared
+ *
+ * @return
+ * TRUE if the addresses are the same, FALSE otherwise
+ */
+krb5_boolean KRB5_CALLCONV
+krb5_address_compare(krb5_context context, const krb5_address *addr1,
+ const krb5_address *addr2);
+
+/**
+ * Return an ordering of the specified addresses.
+ *
+ * @param [in] context Library context
+ * @param [in] addr1 First address
+ * @param [in] addr2 Second address
+ *
+ * @retval
+ * 0 The two addresses are the same
+ * @retval
+ * \< 0 First address is less than second
+ * @retval
+ * \> 0 First address is greater than second
+ */
+int KRB5_CALLCONV
+krb5_address_order(krb5_context context, const krb5_address *addr1,
+ const krb5_address *addr2);
+
+/**
+ * Compare the realms of two principals.
+ *
+ * @param [in] context Library context
+ * @param [in] princ1 First principal
+ * @param [in] princ2 Second principal
+ *
+ * @retval
+ * TRUE if the realm names are the same; FALSE otherwise
+ */
+krb5_boolean KRB5_CALLCONV
+krb5_realm_compare(krb5_context context, krb5_const_principal princ1,
+ krb5_const_principal princ2);
+
+/**
+ * Compare two principals.
+ *
+ * @param [in] context Library context
+ * @param [in] princ1 First principal
+ * @param [in] princ2 Second principal
+ *
+ * @retval
+ * TRUE if the principals are the same; FALSE otherwise
+ */
+krb5_boolean KRB5_CALLCONV
+krb5_principal_compare(krb5_context context,
+ krb5_const_principal princ1,
+ krb5_const_principal princ2);
+
+/**
+ * Compare two principals ignoring realm components.
+ *
+ * @param [in] context Library context
+ * @param [in] princ1 First principal
+ * @param [in] princ2 Second principal
+ *
+ * Similar to krb5_principal_compare(), but do not compare the realm
+ * components of the principals.
+ *
+ * @retval
+ * TRUE if the principals are the same; FALSE otherwise
+ */
+krb5_boolean KRB5_CALLCONV
+krb5_principal_compare_any_realm(krb5_context context,
+ krb5_const_principal princ1,
+ krb5_const_principal princ2);
+
+#define KRB5_PRINCIPAL_COMPARE_IGNORE_REALM 1 /**< ignore realm component */
+#define KRB5_PRINCIPAL_COMPARE_ENTERPRISE 2 /**< UPNs as real principals */
+#define KRB5_PRINCIPAL_COMPARE_CASEFOLD 4 /**< case-insensitive */
+#define KRB5_PRINCIPAL_COMPARE_UTF8 8 /**< treat principals as UTF-8 */
+
+/**
+ * Compare two principals with additional flags.
+ *
+ * @param [in] context Library context
+ * @param [in] princ1 First principal
+ * @param [in] princ2 Second principal
+ * @param [in] flags Flags
+ *
+ * Valid flags are:
+ * @li #KRB5_PRINCIPAL_COMPARE_IGNORE_REALM - ignore realm component
+ * @li #KRB5_PRINCIPAL_COMPARE_ENTERPRISE - UPNs as real principals
+ * @li #KRB5_PRINCIPAL_COMPARE_CASEFOLD case-insensitive
+ * @li #KRB5_PRINCIPAL_COMPARE_UTF8 - treat principals as UTF-8
+ *
+ * @sa krb5_principal_compare()
+ *
+ * @retval
+ * TRUE if the principal names are the same; FALSE otherwise
+ */
+krb5_boolean KRB5_CALLCONV
+krb5_principal_compare_flags(krb5_context context,
+ krb5_const_principal princ1,
+ krb5_const_principal princ2,
+ int flags);
+
+/**
+ * Initialize an empty @c krb5_keyblock.
+ *
+ * @param [in] context Library context
+ * @param [in] enctype Encryption type
+ * @param [in] length Length of keyblock (or 0)
+ * @param [out] out New keyblock structure
+ *
+ * Initialize a new keyblock and allocate storage for the contents of the key.
+ * It is legal to pass in a length of 0, in which case contents are left
+ * unallocated. Use krb5_free_keyblock() to free @a out when it is no longer
+ * needed.
+ *
+ * @note If @a length is set to 0, contents are left unallocated.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_init_keyblock(krb5_context context, krb5_enctype enctype,
+ size_t length, krb5_keyblock **out);
+
+/**
+ * Copy a keyblock.
+ *
+ * @param [in] context Library context
+ * @param [in] from Keyblock to be copied
+ * @param [out] to Copy of keyblock @a from
+ *
+ * This function creates a new keyblock with the same contents as @a from. Use
+ * krb5_free_keyblock() to free @a to when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_copy_keyblock(krb5_context context, const krb5_keyblock *from,
+ krb5_keyblock **to);
+
+/**
+ * Copy the contents of a keyblock.
+ *
+ * @param [in] context Library context
+ * @param [in] from Key to be copied
+ * @param [out] to Output key
+ *
+ * This function copies the contents of @a from to @a to. Use
+ * krb5_free_keyblock_contents() to free @a to when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_copy_keyblock_contents(krb5_context context, const krb5_keyblock *from,
+ krb5_keyblock *to);
+
+/**
+ * Copy a krb5_creds structure.
+ *
+ * @param [in] context Library context
+ * @param [in] incred Credentials structure to be copied
+ * @param [out] outcred Copy of @a incred
+ *
+ * This function creates a new credential with the contents of @a incred. Use
+ * krb5_free_creds() to free @a outcred when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_copy_creds(krb5_context context, const krb5_creds *incred, krb5_creds **outcred);
+
+/**
+ * Copy a krb5_data object.
+ *
+ * @param [in] context Library context
+ * @param [in] indata Data object to be copied
+ * @param [out] outdata Copy of @a indata
+ *
+ * This function creates a new krb5_data object with the contents of @a indata.
+ * Use krb5_free_data() to free @a outdata when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_copy_data(krb5_context context, const krb5_data *indata, krb5_data **outdata);
+
+/**
+ * Copy a principal.
+ *
+ * @param [in] context Library context
+ * @param [in] inprinc Principal to be copied
+ * @param [out] outprinc Copy of @a inprinc
+ *
+ * This function creates a new principal structure with the contents of @a
+ * inprinc. Use krb5_free_principal() to free @a outprinc when it is no longer
+ * needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_copy_principal(krb5_context context, krb5_const_principal inprinc,
+ krb5_principal *outprinc);
+
+/**
+ * Copy an array of addresses.
+ *
+ * @param [in] context Library context
+ * @param [in] inaddr Array of addresses to be copied
+ * @param [out] outaddr Copy of array of addresses
+ *
+ * This function creates a new address array containing a copy of @a inaddr.
+ * Use krb5_free_addresses() to free @a outaddr when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_copy_addresses(krb5_context context, krb5_address *const *inaddr,
+ krb5_address ***outaddr);
+
+/**
+ * Copy a krb5_ticket structure.
+ *
+ * @param [in] context Library context
+ * @param [in] from Ticket to be copied
+ * @param [out] pto Copy of ticket
+ *
+ * This function creates a new krb5_ticket structure containing the contents of
+ * @a from. Use krb5_free_ticket() to free @a pto when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_copy_ticket(krb5_context context, const krb5_ticket *from, krb5_ticket **pto);
+
+/**
+ * Copy an authorization data list.
+ *
+ * @param [in] context Library context
+ * @param [in] in_authdat List of @a krb5_authdata structures
+ * @param [out] out New array of @a krb5_authdata structures
+ *
+ * This function creates a new authorization data list containing a copy of @a
+ * in_authdat, which must be null-terminated. Use krb5_free_authdata() to free
+ * @a out when it is no longer needed.
+ *
+ * @note The last array entry in @a in_authdat must be a NULL pointer.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_copy_authdata(krb5_context context,
+ krb5_authdata *const *in_authdat, krb5_authdata ***out);
+
+/**
+ * Find authorization data elements.
+ *
+ * @param [in] context Library context
+ * @param [in] ticket_authdata Authorization data list from ticket
+ * @param [in] ap_req_authdata Authorization data list from AP request
+ * @param [in] ad_type Authorization data type to find
+ * @param [out] results List of matching entries
+ *
+ * This function searches @a ticket_authdata and @a ap_req_authdata for
+ * elements of type @a ad_type. Either input list may be NULL, in which case
+ * it will not be searched; otherwise, the input lists must be terminated by
+ * NULL entries. This function will search inside AD-IF-RELEVANT containers if
+ * found in either list. Use krb5_free_authdata() to free @a results when it
+ * is no longer needed.
+ *
+ * @version First introduced in 1.10
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_find_authdata(krb5_context context, krb5_authdata *const *ticket_authdata,
+ krb5_authdata *const *ap_req_authdata,
+ krb5_authdatatype ad_type, krb5_authdata ***results);
+
+/**
+ * Merge two authorization data lists into a new list.
+ *
+ * @param [in] context Library context
+ * @param [in] inauthdat1 First list of @a krb5_authdata structures
+ * @param [in] inauthdat2 Second list of @a krb5_authdata structures
+ * @param [out] outauthdat Merged list of @a krb5_authdata structures
+ *
+ * Merge two authdata arrays, such as the array from a ticket
+ * and authenticator.
+ * Use krb5_free_authdata() to free @a outauthdat when it is no longer needed.
+ *
+ * @note The last array entry in @a inauthdat1 and @a inauthdat2
+ * must be a NULL pointer.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_merge_authdata(krb5_context context,
+ krb5_authdata *const *inauthdat1,
+ krb5_authdata * const *inauthdat2,
+ krb5_authdata ***outauthdat);
+
+/**
+ * Copy a krb5_authenticator structure.
+ *
+ * @param [in] context Library context
+ * @param [in] authfrom krb5_authenticator structure to be copied
+ * @param [out] authto Copy of krb5_authenticator structure
+ *
+ * This function creates a new krb5_authenticator structure with the content of
+ * @a authfrom. Use krb5_free_authenticator() to free @a authto when it is no
+ * longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_copy_authenticator(krb5_context context, const krb5_authenticator *authfrom,
+ krb5_authenticator **authto);
+
+/**
+ * Copy a krb5_checksum structure.
+ *
+ * @param [in] context Library context
+ * @param [in] ckfrom Checksum to be copied
+ * @param [out] ckto Copy of krb5_checksum structure
+ *
+ * This function creates a new krb5_checksum structure with the contents of @a
+ * ckfrom. Use krb5_free_checksum() to free @a ckto when it is no longer
+ * needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_copy_checksum(krb5_context context, const krb5_checksum *ckfrom,
+ krb5_checksum **ckto);
+
+/**
+ * Generate a replay cache object for server use and open it.
+ *
+ * @param [in] context Library context
+ * @param [in] piece Unique identifier for replay cache
+ * @param [out] rcptr Handle to an open rcache
+ *
+ * This function generates a replay cache name based on @a piece and opens a
+ * handle to it. Typically @a piece is the first component of the service
+ * principal name. Use krb5_rc_close() to close @a rcptr when it is no longer
+ * needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_server_rcache(krb5_context context, const krb5_data *piece,
+ krb5_rcache *rcptr);
+
+/**
+ * Build a principal name using length-counted strings.
+ *
+ * @param [in] context Library context
+ * @param [out] princ Principal name
+ * @param [in] rlen Realm name length
+ * @param [in] realm Realm name
+ * @param [in] ... List of unsigned int/char * components, followed by 0
+ *
+ * This function creates a principal from a length-counted string and a
+ * variable-length list of length-counted components. The list of components
+ * ends with the first 0 length argument (so it is not possible to specify an
+ * empty component with this function). Call krb5_free_principal() to free
+ * allocated memory for principal when it is no longer needed.
+ *
+ * @code
+ * Example of how to build principal WELLKNOWN/ANONYMOUS@R
+ * krb5_build_principal_ext(context, &principal, strlen("R"), "R",
+ * (unsigned int)strlen(KRB5_WELLKNOWN_NAMESTR),
+ * KRB5_WELLKNOWN_NAMESTR,
+ * (unsigned int)strlen(KRB5_ANONYMOUS_PRINCSTR),
+ * KRB5_ANONYMOUS_PRINCSTR, 0);
+ * @endcode
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV_C
+krb5_build_principal_ext(krb5_context context, krb5_principal * princ,
+ unsigned int rlen, const char * realm, ...);
+
+/**
+ * Build a principal name using null-terminated strings.
+ *
+ * @param [in] context Library context
+ * @param [out] princ Principal name
+ * @param [in] rlen Realm name length
+ * @param [in] realm Realm name
+ * @param [in] ... List of char * components, ending with NULL
+ *
+ * Call krb5_free_principal() to free @a princ when it is no longer needed.
+ *
+ * @note krb5_build_principal() and krb5_build_principal_alloc_va() perform the
+ * same task. krb5_build_principal() takes variadic arguments.
+ * krb5_build_principal_alloc_va() takes a pre-computed @a varargs pointer.
+ *
+ * @code
+ * Example of how to build principal H/S@R
+ * krb5_build_principal(context, &principal,
+ * strlen("R"), "R", "H", "S", (char*)NULL);
+ * @endcode
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV_C
+krb5_build_principal(krb5_context context,
+ krb5_principal * princ,
+ unsigned int rlen,
+ const char * realm, ...)
+#if __GNUC__ >= 4
+ __attribute__ ((sentinel))
+#endif
+ ;
+#if KRB5_DEPRECATED
+/** @deprecated Replaced by krb5_build_principal_alloc_va(). */
+KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
+krb5_build_principal_va(krb5_context context,
+ krb5_principal princ,
+ unsigned int rlen,
+ const char *realm,
+ va_list ap);
+#endif
+
+/**
+ * Build a principal name, using a precomputed variable argument list
+ *
+ * @param [in] context Library context
+ * @param [out] princ Principal structure
+ * @param [in] rlen Realm name length
+ * @param [in] realm Realm name
+ * @param [in] ap List of char * components, ending with NULL
+ *
+ * Similar to krb5_build_principal(), this function builds a principal name,
+ * but its name components are specified as a va_list.
+ *
+ * Use krb5_free_principal() to deallocate @a princ when it is no longer
+ * needed.
+ *
+ * @code
+ * Function usage example:
+ * va_list ap;
+ * va_start(ap, realm);
+ * krb5_build_principal_alloc_va(context, princ, rlen, realm, ap);
+ * va_end(ap);
+ * @endcode
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_build_principal_alloc_va(krb5_context context,
+ krb5_principal *princ,
+ unsigned int rlen,
+ const char *realm,
+ va_list ap);
+
+/**
+ * Convert a Kerberos V4 principal to a Kerberos V5 principal.
+ *
+ * @param [in] context Library context
+ * @param [in] name V4 name
+ * @param [in] instance V4 instance
+ * @param [in] realm Realm
+ * @param [out] princ V5 principal
+ *
+ * This function builds a @a princ from V4 specification based on given input
+ * @a name.instance\@realm.
+ *
+ * Use krb5_free_principal() to free @a princ when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_425_conv_principal(krb5_context context, const char *name,
+ const char *instance, const char *realm,
+ krb5_principal *princ);
+
+/**
+ * Convert a Kerberos V5 principal to a Kerberos V4 principal.
+ *
+ * @param [in] context Library context
+ * @param [in] princ V5 Principal
+ * @param [out] name V4 principal's name to be filled in
+ * @param [out] inst V4 principal's instance name to be filled in
+ * @param [out] realm Principal's realm name to be filled in
+ *
+ * This function separates a V5 principal @a princ into @a name, @a instance,
+ * and @a realm.
+ *
+ * @retval
+ * 0 Success
+ * @retval
+ * KRB5_INVALID_PRINCIPAL Invalid principal name
+ * @retval
+ * KRB5_CONFIG_CANTOPEN Can't open or find Kerberos configuration file
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_524_conv_principal(krb5_context context, krb5_const_principal princ,
+ char *name, char *inst, char *realm);
+/**
+ *@deprecated
+ */
+struct credentials;
+
+/**
+ * Convert a Kerberos V5 credentials to a Kerberos V4 credentials
+ *
+ * @note Not implemented
+ *
+ * @retval KRB524_KRB4_DISABLED (always)
+ */
+int KRB5_CALLCONV
+krb5_524_convert_creds(krb5_context context, krb5_creds *v5creds,
+ struct credentials *v4creds);
+
+#if KRB5_DEPRECATED
+#define krb524_convert_creds_kdc krb5_524_convert_creds
+#define krb524_init_ets(x) (0)
+#endif
+
+/* libkt.spec */
+
+/**
+ * Get a handle for a key table.
+ *
+ * @param [in] context Library context
+ * @param [in] name Name of the key table
+ * @param [out] ktid Key table handle
+ *
+ * Resolve the key table name @a name and fill in a handle identifying the key
+ * table. The key table is not opened.
+ *
+ * @note @a name must be of the form @c type:residual, where @a type must be a
+ * type known to the library and @a residual portion should be specific to the
+ * particular keytab type.
+ *
+ * @sa krb5_kt_close()
+ *
+ * @code
+ * Example: krb5_kt_resolve(context, "FILE:/tmp/filename",&ktid);
+ * @endcode
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_kt_resolve(krb5_context context, const char *name, krb5_keytab *ktid);
+
+/**
+ * Get default key table name.
+ *
+ * @param [in] context Library context
+ * @param [in,out] name Key table name to be resolved
+ * @param [in] name_size Size of @a name to return
+ *
+ * Fill @a name with the first @a name_size bytes of the name of the default
+ * key table for the current user.
+ *
+ * @sa MAX_KEYTAB_NAME_LEN
+ *
+ * @retval
+ * 0 Success
+ * @retval
+ * KRB5_CONFIG_NOTENUFSPACE Buffer is too short
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_kt_default_name(krb5_context context, char *name, int name_size);
+
+/**
+ * Resolve default key table.
+ *
+ * @param [in] context Library context
+ * @param [in,out] id Key table handle
+ *
+ * Fill @a keytab with the default key table's @a handle.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_kt_default(krb5_context context, krb5_keytab *id);
+
+/**
+ * Free the contents of a key table entry.
+ *
+ * @param [in] context Library context
+ * @param [in] entry Key table entry whose contents are to be freed
+ *
+ * @note The pointer is not freed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_free_keytab_entry_contents(krb5_context context, krb5_keytab_entry *entry);
+
+/** @deprecated Use krb5_free_keytab_entry_contents instead. */
+krb5_error_code KRB5_CALLCONV
+krb5_kt_free_entry(krb5_context context, krb5_keytab_entry *entry);
+
+
+/* remove and add are functions, so that they can return NOWRITE
+ if not a writable keytab */
+
+/**
+ * Remove an entry from a key table.
+ *
+ * @param [in] context Library context
+ * @param [in] id Key table handle
+ * @param [in] entry Entry to remove from key table
+ *
+ * @retval
+ * 0 Success
+ * @retval
+ * KRB5_KT_NOWRITE Key table is not writable
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_kt_remove_entry(krb5_context context, krb5_keytab id, krb5_keytab_entry *entry);
+
+/**
+ * Add a new entry to a key table.
+ *
+ * @param [in] context Library context
+ * @param [in] id Key table handle
+ * @param [in] entry Entry to be added
+ *
+ * @retval
+ * 0 Success
+ * @retval
+ * ENOMEM Insufficient memory
+ * @retval
+ * KRB5_KT_NOWRITE Key table is not writeable
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_kt_add_entry(krb5_context context, krb5_keytab id, krb5_keytab_entry *entry);
+
+/**
+ * Convert a principal name into the default salt for that principal.
+ *
+ * @param [in] context Library context
+ * @param [in] pr Principal name
+ * @param [out] ret Default salt for @a pr to be filled in
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV_WRONG
+krb5_principal2salt(krb5_context context,
+ register krb5_const_principal pr, krb5_data *ret);
+/* librc.spec--see rcache.h */
+
+/* libcc.spec */
+
+/**
+ * Resolve a credential cache name.
+ *
+ * @param [in] context Library context
+ * @param [in] name Credential cache name to be resolved
+ * @param [out] cache Credential cache handle
+ *
+ * Fills in @a cache with a @a cache handle that corresponds to the name in @a
+ * name. @a name should be of the form @c type:residual, and @a type must be a
+ * type known to the library. If the @a name does not contain a colon,
+ * interpret it as a file name.
+ *
+ * @code
+ * Example: krb5_cc_resolve(context, "MEMORY:C_", &cache);
+ * @endcode
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_cc_resolve(krb5_context context, const char *name, krb5_ccache *cache);
+
+/**
+ * Duplicate ccache handle.
+ *
+ * @param [in] context Library context
+ * @param [in] in Credential cache handle to be duplicated
+ * @param [out] out Credential cache handle
+ *
+ * Create a new handle referring to the same cache as @a in.
+ * The new handle and @a in can be closed independently.
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_cc_dup(krb5_context context, krb5_ccache in, krb5_ccache *out);
+
+/**
+ * Return the name of the default credential cache.
+ *
+ * @param [in] context Library context
+ *
+ * Try the environment variable @a KRB5CCNAME first then, if it is not set,
+ * fall back on the default ccache name for the OS.
+ *
+ * @return
+ * Name of default credential cache for the current user.
+ */
+const char *KRB5_CALLCONV
+krb5_cc_default_name(krb5_context context);
+
+/**
+ * Set the default credential cache name.
+ *
+ * @param [in,out] context Library context
+ * @param [in] name Default credential cache name
+ *
+ * This function frees the old default credential cache name and then sets it
+ * to @a name.
+ *
+ * @retval
+ * 0 Success
+ * @retval
+ * KV5M_CONTEXT Bad magic number for @c _krb5_context structure
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_cc_set_default_name(krb5_context context, const char *name);
+
+/**
+ * Resolve the default crendentials cache name.
+ *
+ * @param [in,out] context Library context
+ * @param [out] ccache Pointer to credential cache name
+ *
+ * @retval
+ * 0 Success
+ * @retval
+ * KV5M_CONTEXT Bad magic number for @c _krb5_context structure
+ * @retval
+ * KRB5_FCC_INTERNAL The name of the default credential cache cannot be
+ * obtained
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_cc_default(krb5_context context, krb5_ccache *ccache);
+
+/**
+ * Copy a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in] incc Credential cache to be copied
+ * @param [out] outcc Copy of credential cache to be filled in
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_cc_copy_creds(krb5_context context, krb5_ccache incc, krb5_ccache outcc);
+
+/**
+ * Get a configuration value from a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in] id Credential cache handle
+ * @param [in] principal Configuration for this principal;
+ * if NULL, global for the whole cache
+ * @param [in] key Name of config variable
+ * @param [out] data Data to be fetched
+ *
+ * Use krb5_free_data_contents() to free @a data when it is no longer needed.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_cc_get_config(krb5_context context, krb5_ccache id,
+ krb5_const_principal principal,
+ const char *key, krb5_data *data);
+
+/**
+ * Store a configuration value in a credential cache.
+ *
+ * @param [in] context Library context
+ * @param [in] id Credential cache handle
+ * @param [in] principal Configuration for a specific principal;
+ * if NULL, global for the whole cache
+ * @param [in] key Name of config variable
+ * @param [in] data Data to store, or NULL to remove
+ *
+ * @note Existing configuration under the same key is over-written.
+ *
+ * @warning Before version 1.10 @a data was assumed to be always non-null.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_cc_set_config(krb5_context context, krb5_ccache id,
+ krb5_const_principal principal,
+ const char *key, krb5_data *data);
+
+/**
+ * Test whether a principal is a configuration principal.
+ *
+ * @param [in] context Library context
+ * @param [in] principal Principal to check
+ *
+ * @return
+ * @c TRUE if the principal is a configuration principal (generated part of
+ * krb5_cc_set_config()); @c FALSE otherwise.
+ */
+krb5_boolean KRB5_CALLCONV
+krb5_is_config_principal(krb5_context context, krb5_const_principal principal);
+
+/**
+ * Make a credential cache the primary cache for its collection.
+ *
+ * @param [in] context Library context
+ * @param [in] cache Credential cache handle
+ *
+ * If the type of @a cache supports it, set @a cache to be the primary
+ * credential cache for the collection it belongs to.
+ *
+ * @retval
+ * 0 Success, or the type of @a cache doesn't support switching
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_cc_switch(krb5_context context, krb5_ccache cache);
+
+/**
+ * Determine whether a credential cache type supports switching.
+ *
+ * @param [in] context Library context
+ * @param [in] type Credential cache type
+ *
+ * @version First introduced in 1.10
+ *
+ * @retval TRUE if @a type supports switching
+ * @retval FALSE if it does not or is not a valid credential cache type.
+ */
+krb5_boolean KRB5_CALLCONV
+krb5_cc_support_switch(krb5_context context, const char *type);
+
+/**
+ * Find a credential cache with a specified client principal.
+ *
+ * @param [in] context Library context
+ * @param [in] client Client principal
+ * @param [out] cache_out Credential cache handle
+ *
+ * Find a cache within the collection whose default principal is @a client.
+ * Use @a krb5_cc_close to close @a ccache when it is no longer needed.
+ *
+ * @retval 0 Success
+ * @retval KRB5_CC_NOTFOUND
+ *
+ * @sa krb5_cccol_cursor_new
+ *
+ * @version First introduced in 1.10
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_cc_cache_match(krb5_context context, krb5_principal client,
+ krb5_ccache *cache_out);
+
+/**
+ * Select a credential cache to use with a server principal.
+ *
+ * @param [in] context Library context
+ * @param [in] server Server principal
+ * @param [out] cache_out Credential cache handle
+ * @param [out] princ_out Client principal
+ *
+ * Select a cache within the collection containing credentials most appropriate
+ * for use with @a server, according to configured rules and heuristics.
+ *
+ * Use krb5_cc_close() to release @a cache_out when it is no longer needed.
+ * Use krb5_free_principal() to release @a princ_out when it is no longer
+ * needed. Note that @a princ_out is set in some error conditions.
+ *
+ * @return
+ * If an appropriate cache is found, 0 is returned, @a cache_out is set to the
+ * selected cache, and @a princ_out is set to the default principal of that
+ * cache.
+ *
+ * If the appropriate client principal can be authoritatively determined but
+ * the cache collection contains no credentials for that principal, then
+ * KRB5_CC_NOTFOUND is returned, @a cache_out is set to NULL, and @a princ_out
+ * is set to the appropriate client principal.
+ *
+ * If no configured mechanism can determine the appropriate cache or principal,
+ * KRB5_CC_NOTFOUND is returned and @a cache_out and @a princ_out are set to
+ * NULL.
+ *
+ * Any other error code indicates a fatal error in the processing of a cache
+ * selection mechanism.
+ *
+ * @version First introduced in 1.10
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_cc_select(krb5_context context, krb5_principal server,
+ krb5_ccache *cache_out, krb5_principal *princ_out);
+
+/* krb5_free.c */
+/**
+ * Free the storage assigned to a principal.
+ *
+ * @param [in] context Library context
+ * @param [in] val Principal to be freed
+ */
+void KRB5_CALLCONV
+krb5_free_principal(krb5_context context, krb5_principal val);
+
+/**
+ * Free a krb5_authenticator structure.
+ *
+ * @param [in] context Library context
+ * @param [in] val Authenticator structure to be freed
+ *
+ * This function frees the contents of @a val and the structure itself.
+ */
+void KRB5_CALLCONV
+krb5_free_authenticator(krb5_context context, krb5_authenticator *val);
+
+/**
+ * Free the data stored in array of addresses.
+ *
+ * @param [in] context Library context
+ * @param [in] val Array of addresses to be freed
+ *
+ * This function frees the contents of @a val and the array itself.
+ *
+ * @note The last entry in the array must be a NULL pointer.
+ */
+void KRB5_CALLCONV
+krb5_free_addresses(krb5_context context, krb5_address **val);
+
+/**
+ * Free the storage assigned to array of authentication data.
+ *
+ * @param [in] context Library context
+ * @param [in] val Array of authentication data to be freed
+ *
+ * This function frees the contents of @a val and the array itself.
+ *
+ * @note The last entry in the array must be a NULL pointer.
+ */
+void KRB5_CALLCONV
+krb5_free_authdata(krb5_context context, krb5_authdata **val);
+
+/**
+ * Free a ticket.
+ *
+ * @param [in] context Library context
+ * @param [in] val Ticket to be freed
+ *
+ * This function frees the contents of @a val and the structure itself.
+ */
+void KRB5_CALLCONV
+krb5_free_ticket(krb5_context context, krb5_ticket *val);
+
+/**
+ * Free an error allocated by krb5_read_error() or krb5_sendauth().
+ *
+ * @param [in] context Library context
+ * @param [in] val Error data structure to be freed
+ *
+ * This function frees the contents of @a val and the structure itself.
+ */
+void KRB5_CALLCONV
+krb5_free_error(krb5_context context, register krb5_error *val);
+
+/**
+ * Free a krb5_creds structure.
+ *
+ * @param [in] context Library context
+ * @param [in] val Credential structure to be freed.
+ *
+ * This function frees the contents of @a val and the structure itself.
+ */
+void KRB5_CALLCONV
+krb5_free_creds(krb5_context context, krb5_creds *val);
+
+/**
+ * Free the contents of a krb5_creds structure.
+ *
+ * @param [in] context Library context
+ * @param [in] val Credential structure to free contents of
+ *
+ * This function frees the contents of @a val, but not the structure itself.
+ */
+void KRB5_CALLCONV
+krb5_free_cred_contents(krb5_context context, krb5_creds *val);
+
+/**
+ * Free a krb5_checksum structure.
+ *
+ * @param [in] context Library context
+ * @param [in] val Checksum structure to be freed
+ *
+ * This function frees the contents of @a val and the structure itself.
+ */
+void KRB5_CALLCONV
+krb5_free_checksum(krb5_context context, register krb5_checksum *val);
+
+/**
+ * Free the contents of a krb5_checksum structure.
+ *
+ * @param [in] context Library context
+ * @param [in] val Checksum structure to free contents of
+ *
+ * This function frees the contents of @a val, but not the structure itself.
+ */
+void KRB5_CALLCONV
+krb5_free_checksum_contents(krb5_context context, register krb5_checksum *val);
+
+/**
+ * Free a krb5_keyblock structure.
+ *
+ * @param [in] context Library context
+ * @param [in] val Keyblock to be freed
+ *
+ * This function frees the contents of @a val and the structure itself.
+ */
+void KRB5_CALLCONV
+krb5_free_keyblock(krb5_context context, register krb5_keyblock *val);
+
+/**
+ * Free the contents of a krb5_keyblock structure.
+ *
+ * @param [in] context Library context
+ * @param [in] key Keyblock to be freed
+ *
+ * This function frees the contents of @a key, but not the structure itself.
+ */
+void KRB5_CALLCONV
+krb5_free_keyblock_contents(krb5_context context, register krb5_keyblock *key);
+
+/**
+ * Free a krb5_ap_rep_enc_part structure.
+ *
+ * @param [in] context Library context
+ * @param [in] val AP-REP enc part to be freed
+ *
+ * This function frees the contents of @a val and the structure itself.
+ */
+void KRB5_CALLCONV
+krb5_free_ap_rep_enc_part(krb5_context context, krb5_ap_rep_enc_part *val);
+
+/**
+ * Free a krb5_data structure.
+ *
+ * @param [in] context Library context
+ * @param [in] val Data structure to be freed
+ *
+ * This function frees the contents of @a val and the structure itself.
+ */
+void KRB5_CALLCONV
+krb5_free_data(krb5_context context, krb5_data *val);
+
+/* Free a krb5_octet_data structure (should be unused). */
+void KRB5_CALLCONV
+krb5_free_octet_data(krb5_context context, krb5_octet_data *val);
+
+/**
+ * Free the contents of a krb5_data structure and zero the data field.
+ *
+ * @param [in] context Library context
+ * @param [in] val Data structure to free contents of
+ *
+ * This function frees the contents of @a val, but not the structure itself.
+ */
+void KRB5_CALLCONV
+krb5_free_data_contents(krb5_context context, krb5_data *val);
+
+/**
+ * Free a string representation of a principal.
+ *
+ * @param [in] context Library context
+ * @param [in] val Name string to be freed
+ */
+void KRB5_CALLCONV
+krb5_free_unparsed_name(krb5_context context, char *val);
+
+/**
+ * Free a string allocated by a krb5 function.
+ *
+ * @param [in] context Library context
+ * @param [in] val String to be freed
+ *
+ * @version First introduced in 1.10
+ */
+void KRB5_CALLCONV
+krb5_free_string(krb5_context context, char *val);
+
+/**
+ * Free an array of checksum types.
+ *
+ * @param [in] context Library context
+ * @param [in] val Array of checksum types to be freed
+ */
+void KRB5_CALLCONV
+krb5_free_cksumtypes(krb5_context context, krb5_cksumtype *val);
+
+/* From krb5/os, but needed by the outside world */
+/**
+ * Retrieve the system time of day, in sec and ms, since the epoch.
+ *
+ * @param [in] context Library context
+ * @param [out] seconds System timeofday, seconds portion
+ * @param [out] microseconds System timeofday, microseconds portion
+ *
+ * This function retrieves the system time of day with the context
+ * specific time offset adjustment.
+ *
+ * @sa krb5_crypto_us_timeofday()
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_us_timeofday(krb5_context context,
+ krb5_timestamp *seconds, krb5_int32 *microseconds);
+
+/**
+ * Retrieve the current time with context specific time offset adjustment.
+ *
+ * @param [in] context Library context
+ * @param [in,out] timeret Timestamp to fill in
+ *
+ * This function retrieves the system time of day with the context specific
+ * time offset adjustment.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_timeofday(krb5_context context, register krb5_timestamp *timeret);
+
+/**
+ * Check if a timestamp is within the allowed clock skew of the current time.
+ *
+ * @param [in] context Library context
+ * @param [in] date Timestamp to check
+ *
+ * This function checks if @a date is close enough to the current time
+ * according to the configured allowable clock skew.
+ *
+ * @version First introduced in 1.10
+ *
+ * @retval 0 Success
+ * @retval KRB5KRB_AP_ERR_SKEW @a date is not within allowable clock skew
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_check_clockskew(krb5_context context, krb5_timestamp date);
+
+/**
+ * Return all interface addresses for this host.
+ *
+ * @param [in] context Library context
+ * @param [out] addr Array of krb5_address pointers, ending with
+ * NULL
+ *
+ * Use krb5_free_addresses() to free @a addr when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_os_localaddr(krb5_context context, krb5_address ***addr);
+
+/**
+ * Retrieve the default realm.
+ *
+ * @param [in] context Library context
+ * @param [out] lrealm Default realm name
+ *
+ * Retrieves the default realm to be used if no user-specified realm is
+ * available.
+ *
+ * Use krb5_free_default_realm() to free @a lrealm when it is no longer needed.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_default_realm(krb5_context context, char **lrealm);
+
+/**
+ * Override the default realm for the specified context.
+ *
+ * @param [in] context Library context
+ * @param [in] lrealm Realm name for the default realm
+ *
+ * If @a lrealm is NULL, clear the default realm setting.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_set_default_realm(krb5_context context, const char *lrealm);
+
+/**
+ * Free a default realm string returned by krb5_get_default_realm().
+ *
+ * @param [in] context Library context
+ * @param [in] lrealm Realm to be freed
+ */
+void KRB5_CALLCONV
+krb5_free_default_realm(krb5_context context, char *lrealm);
+
+/**
+ * Generate a full principal name from a service name.
+ *
+ * @param [in] context Library context
+ * @param [in] hostname Host name, or NULL to use local host
+ * @param [in] sname Service name, or NULL to use @c "host"
+ * @param [in] type Principal type
+ * @param [out] ret_princ Generated principal
+ *
+ * This function converts a @a hostname and @a sname into @a krb5_principal
+ * structure @a ret_princ. The returned principal will be of the form @a
+ * sname\/hostname\@REALM where REALM is determined by krb5_get_host_realm().
+ * In some cases this may be the referral (empty) realm.
+ *
+ * The @a type can be one of the following:
+ *
+ * @li #KRB5_NT_SRV_HST canonicalizes the host name before looking up the
+ * realm and generating the principal.
+ *
+ * @li #KRB5_NT_UNKNOWN accepts the hostname as given, and does not
+ * canonicalize it.
+ *
+ * Use krb5_free_principal to free @a ret_princ when it is no longer needed.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_sname_to_principal(krb5_context context, const char *hostname, const char *sname,
+ krb5_int32 type, krb5_principal *ret_princ);
+
+/**
+ * Test whether a principal matches a matching principal.
+ *
+ * @param [in] context Library context
+ * @param [in] matching Matching principal
+ * @param [in] princ Principal to test
+ *
+ * @note A matching principal is a host-based principal with an empty realm
+ * and/or second data component (hostname). Profile configuration may cause
+ * the hostname to be ignored even if it is present. A principal matches a
+ * matching principal if the former has the same non-empty (and non-ignored)
+ * components of the latter.
+ *
+ * If @a matching is NULL, return TRUE. If @a matching is not a matching
+ * principal, return the value of krb5_principal_compare(context, matching,
+ * princ).
+ *
+ * @return
+ * TRUE if @a princ matches @a matching, FALSE otherwise.
+ */
+krb5_boolean KRB5_CALLCONV
+krb5_sname_match(krb5_context context, krb5_const_principal matching,
+ krb5_const_principal princ);
+
+/**
+ * Change a password for an existing Kerberos account.
+ *
+ * @param [in] context Library context
+ * @param [in] creds Credentials for kadmin/changepw service
+ * @param [in] newpw New password
+ * @param [out] result_code Numeric error code from server
+ * @param [out] result_code_string String equivalent to @a result_code
+ * @param [out] result_string Change password response from the KDC
+ *
+ * Change the password for the existing principal identified by @a creds.
+ *
+ * The possible values of the output @a result_code are:
+ *
+ * @li #KRB5_KPASSWD_SUCCESS (0) - success
+ * @li #KRB5_KPASSWD_MALFORMED (1) - Malformed request error
+ * @li #KRB5_KPASSWD_HARDERROR (2) - Server error
+ * @li #KRB5_KPASSWD_AUTHERROR (3) - Authentication error
+ * @li #KRB5_KPASSWD_SOFTERROR (4) - Password change rejected
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_change_password(krb5_context context, krb5_creds *creds, char *newpw,
+ int *result_code, krb5_data *result_code_string,
+ krb5_data *result_string);
+
+/**
+ * Set a password for a principal using specified credentials.
+ *
+ * @param [in] context Library context
+ * @param [in] creds Credentials for kadmin/changepw service
+ * @param [in] newpw New password
+ * @param [in] change_password_for Change the password for this principal
+ * @param [out] result_code Numeric error code from server
+ * @param [out] result_code_string String equivalent to @a result_code
+ * @param [out] result_string Data returned from the remote system
+ *
+ * This function uses the credentials @a creds to set the password @a newpw for
+ * the principal @a change_password_for. It implements the set password
+ * operation of RFC 3244, for interoperability with Microsoft Windows
+ * implementations.
+ *
+ * @note If @a change_password_for is NULL, the change is performed on the
+ * current principal. If @a change_password_for is non-null, the change is
+ * performed on the principal name passed in @a change_password_for.
+ *
+ * The error code and strings are returned in @a result_code,
+ * @a result_code_string and @a result_string.
+ *
+ * @sa krb5_set_password_using_ccache()
+ *
+ * @retval
+ * 0 Success and result_code is set to #KRB5_KPASSWD_SUCCESS.
+ * @return
+ * Kerberos error codes.
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_set_password(krb5_context context, krb5_creds *creds, char *newpw,
+ krb5_principal change_password_for, int *result_code,
+ krb5_data *result_code_string, krb5_data *result_string);
+
+/**
+ * Set a password for a principal using cached credentials.
+ *
+ * @param [in] context Library context
+ * @param [in] ccache Credential cache
+ * @param [in] newpw New password
+ * @param [in] change_password_for Change the password for this principal
+ * @param [out] result_code Numeric error code from server
+ * @param [out] result_code_string String equivalent to @a result_code
+ * @param [out] result_string Data returned from the remote system
+ *
+ * This function uses the cached credentials from @a ccache to set the password
+ * @a newpw for the principal @a change_password_for. It implements RFC 3244
+ * set password operation (interoperable with MS Windows implementations) using
+ * the credential cache.
+ *
+ * The error code and strings are returned in @a result_code,
+ * @a result_code_string and @a result_string.
+ *
+ * @note If @a change_password_for is set to NULL, the change is performed on
+ * the default principal in @a ccache. If @a change_password_for is non null,
+ * the change is performed on the specified principal.
+ *
+ * @sa krb5_set_password()
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_set_password_using_ccache(krb5_context context, krb5_ccache ccache,
+ char *newpw, krb5_principal change_password_for,
+ int *result_code, krb5_data *result_code_string,
+ krb5_data *result_string);
+
+/**
+ * Retrieve configuration profile from the context.
+ *
+ * @param [in] context Library context
+ * @param [out] profile Pointer to data read from a configuration file
+ *
+ * This function creates a new @a profile object that reflects profile
+ * in the supplied @a context.
+ *
+ * The @a profile object may be freed with profile_release() function.
+ * See profile.h and profile API for more details.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_profile(krb5_context context, struct _profile_t ** profile);
+
+#if KRB5_DEPRECATED
+/** @deprecated Replaced by krb5_get_init_creds_password().*/
+KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
+krb5_get_in_tkt_with_password(krb5_context context, krb5_flags options,
+ krb5_address *const *addrs, krb5_enctype *ktypes,
+ krb5_preauthtype *pre_auth_types,
+ const char *password, krb5_ccache ccache,
+ krb5_creds *creds, krb5_kdc_rep **ret_as_reply);
+
+/** @deprecated Replaced by krb5_get_init_creds(). */
+KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
+krb5_get_in_tkt_with_skey(krb5_context context, krb5_flags options,
+ krb5_address *const *addrs, krb5_enctype *ktypes,
+ krb5_preauthtype *pre_auth_types,
+ const krb5_keyblock *key, krb5_ccache ccache,
+ krb5_creds *creds, krb5_kdc_rep **ret_as_reply);
+
+/** @deprecated Replaced by krb5_get_init_creds_keytab(). */
+KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
+krb5_get_in_tkt_with_keytab(krb5_context context, krb5_flags options,
+ krb5_address *const *addrs, krb5_enctype *ktypes,
+ krb5_preauthtype *pre_auth_types,
+ krb5_keytab arg_keytab, krb5_ccache ccache,
+ krb5_creds *creds, krb5_kdc_rep **ret_as_reply);
+
+#endif /* KRB5_DEPRECATED */
+
+/**
+ * Parse and decrypt a @c KRB_AP_REQ message.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Pre-existing or newly created auth context
+ * @param [in] inbuf AP-REQ message to be parsed
+ * @param [in] server Matching principal for server, or NULL to
+ * allow any principal in keytab
+ * @param [in] keytab Key table, or NULL to use the default
+ * @param [out] ap_req_options If non-null, the AP-REQ flags on output
+ * @param [out] ticket If non-null, ticket from the AP-REQ message
+ *
+ * This function parses, decrypts and verifies a AP-REQ message from @a inbuf
+ * and stores the authenticator in @a auth_context.
+ *
+ * If a keyblock is present in the @a auth_context, it is used to decrypt the
+ * ticket in AP-REQ message. (This is useful for user-to-user authentication.)
+ * Otherwise, the decryption key is obtained from the @a keytab. If @a keytab
+ * is iterable, all of its key entries it will be tried against the ticket;
+ * otherwise, the server principal in the ticket will be looked up in the
+ * keytab and that key will be tried.
+ *
+ * The client specified in the decrypted authenticator must match the client
+ * specified in the decrypted ticket. If @a server is non-null, the key in
+ * which the ticket is encrypted must correspond to a principal in @a keytab
+ * matching @a server according to the rules of krb5_sname_match().
+ *
+ * If the @a remote_addr field of @a auth_context is set, the request must come
+ * from that address.
+ *
+ * If a replay cache handle is provided in the @a auth_context, the
+ * authenticator and ticket are verified against it. If no conflict is found,
+ * the new authenticator is then stored in the replay cash of @a auth_context.
+ *
+ * Various other checks are performed on the decoded data, including
+ * cross-realm policy, clockskew, and ticket validation times.
+ *
+ * On success the authenticator, subkey, and remote sequence number of the
+ * request are stored in @a auth_context. If the #AP_OPTS_MUTUAL_REQUIRED
+ * bit is set, the local sequence number is XORed with the remote sequence
+ * number in the request.
+ *
+ * Use krb5_free_ticket() to free @a ticket when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_rd_req(krb5_context context, krb5_auth_context *auth_context,
+ const krb5_data *inbuf, krb5_const_principal server,
+ krb5_keytab keytab, krb5_flags *ap_req_options,
+ krb5_ticket **ticket);
+
+/**
+ * Retrieve a service key from a key table.
+ *
+ * @param [in] context Library context
+ * @param [in] keyprocarg Name of a key table (NULL to use default name)
+ * @param [in] principal Service principal
+ * @param [in] vno Key version number (0 for highest available)
+ * @param [in] enctype Encryption type (0 for any type)
+ * @param [out] key Service key from key table
+ *
+ * Open and search the specified key table for the entry identified by @a
+ * principal, @a enctype, and @a vno. If no key is found, return an error code.
+ *
+ * The default key table is used, unless @a keyprocarg is non-null.
+ * @a keyprocarg designates a specific key table.
+ *
+ * Use krb5_free_keyblock() to free @a key when it is no longer needed.
+ *
+ * @retval
+ * 0 Success
+ * @return Kerberos error code if not found or @a keyprocarg is invalid.
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_kt_read_service_key(krb5_context context, krb5_pointer keyprocarg,
+ krb5_principal principal, krb5_kvno vno,
+ krb5_enctype enctype, krb5_keyblock **key);
+
+/**
+ * Format a @c KRB-SAFE message.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in] userdata User data in the message
+ * @param [out] outbuf Formatted @c KRB-SAFE buffer
+ * @param [out] outdata Replay data. Specify NULL if not needed
+ *
+ * This function creates an integrity protected @c KRB-SAFE message
+ * using data supplied by the application.
+ *
+ * Fields in @a auth_context specify the checksum type, the keyblock that
+ * can be used to seed the checksum, full addresses (host and port) for
+ * the sender and receiver, and @ref KRB5_AUTH_CONTEXT flags.
+ *
+ * The local address in @a auth_context must be set, and is used to form the
+ * sender address used in the KRB-SAFE message. The remote address is
+ * optional; if specified, it will be used to form the receiver address used in
+ * the message.
+ *
+ * If #KRB5_AUTH_CONTEXT_DO_TIME flag is set in the @a auth_context, an entry
+ * describing the message is entered in the replay cache @a
+ * auth_context->rcache which enables the caller to detect if this message is
+ * reflected by an attacker. If #KRB5_AUTH_CONTEXT_DO_TIME is not set, the
+ * replay cache is not used.
+ *
+ * If either #KRB5_AUTH_CONTEXT_DO_SEQUENCE or
+ * #KRB5_AUTH_CONTEXT_RET_SEQUENCE is set, the @a auth_context local sequence
+ * number will be placed in @a outdata as its sequence number.
+ *
+ * @note The @a outdata argument is required if #KRB5_AUTH_CONTEXT_RET_TIME or
+ * #KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in the @a auth_context.
+ *
+ * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_mk_safe(krb5_context context, krb5_auth_context auth_context,
+ const krb5_data *userdata, krb5_data *outbuf,
+ krb5_replay_data *outdata);
+
+/**
+ * Format a @c KRB-PRIV message.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in] userdata User data for @c KRB-PRIV message
+ * @param [out] outbuf Formatted @c KRB-PRIV message
+ * @param [out] outdata Replay cache handle (NULL if not needed)
+ *
+ * This function is similar to krb5_mk_safe(), but the message is encrypted and
+ * integrity-protected, not just integrity-protected.
+ *
+ * The local address in @a auth_context must be set, and is used to form the
+ * sender address used in the KRB-SAFE message. The remote address is
+ * optional; if specified, it will be used to form the receiver address used in
+ * the message.
+ *
+ * @note If the #KRB5_AUTH_CONTEXT_RET_TIME or
+ * #KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in @a auth_context, the @a
+ * outdata is required.
+ *
+ * @note The flags from @a auth_context specify whether sequence numbers or
+ * timestamps will be used to identify the message. Valid values are:
+ *
+ * @li #KRB5_AUTH_CONTEXT_DO_TIME - Use timestamps in @a outdata
+ * @li #KRB5_AUTH_CONTEXT_RET_TIME - Copy timestamp to @a outdata.
+ * @li #KRB5_AUTH_CONTEXT_DO_SEQUENCE - Use local sequence numbers from
+ * @a auth_context in replay cache.
+ * @li #KRB5_AUTH_CONTEXT_RET_SEQUENCE - Use local sequence numbers from
+ * @a auth_context as a sequence number
+ * in the encrypted message @a outbuf.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_mk_priv(krb5_context context, krb5_auth_context auth_context,
+ const krb5_data *userdata, krb5_data *outbuf,
+ krb5_replay_data *outdata);
+
+/**
+ * Client function for @c sendauth protocol.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in] fd File descriptor that describes network socket
+ * @param [in] appl_version Application protocol version to be matched
+ * with the receiver's application version
+ * @param [in] client Client principal
+ * @param [in] server Server principal
+ * @param [in] ap_req_options @ref AP_OPTS options
+ * @param [in] in_data Data to be sent to the server
+ * @param [in] in_creds Input credentials, or NULL to use @a ccache
+ * @param [in] ccache Credential cache
+ * @param [out] error If non-null, contains KRB_ERROR message
+ * returned from server
+ * @param [out] rep_result If non-null and @a ap_req_options is
+ * #AP_OPTS_MUTUAL_REQUIRED, contains the result
+ * of mutual authentication exchange
+ * @param [out] out_creds If non-null, the retrieved credentials
+ *
+ * This function performs the client side of a sendauth/recvauth exchange by
+ * sending and receiving messages over @a fd.
+ *
+ * Credentials may be specified in three ways:
+ *
+ * @li If @a in_creds is NULL, credentials are obtained with
+ * krb5_get_credentials() using the principals @a client and @a server. @a
+ * server must be non-null; @a client may NULL to use the default principal of
+ * @a ccache.
+ *
+ * @li If @a in_creds is non-null, but does not contain a ticket, credentials
+ * for the exchange are obtained with krb5_get_credentials() using @a in_creds.
+ * In this case, the values of @a client and @a server are unused.
+ *
+ * @li If @a in_creds is a complete credentials structure, it used directly.
+ * In this case, the values of @a client, @a server, and @a ccache are unused.
+ *
+ * If the server is using a different application protocol than that specified
+ * in @a appl_version, an error will be returned.
+ *
+ * Use krb5_free_creds() to free @a out_creds, krb5_free_ap_rep_enc_part() to
+ * free @a rep_result, and krb5_free_error() to free @a error when they are no
+ * longer needed.
+ *
+ * @sa krb5_recvauth()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_sendauth(krb5_context context, krb5_auth_context *auth_context,
+ krb5_pointer fd, char *appl_version, krb5_principal client,
+ krb5_principal server, krb5_flags ap_req_options,
+ krb5_data *in_data, krb5_creds *in_creds, krb5_ccache ccache,
+ krb5_error **error, krb5_ap_rep_enc_part **rep_result,
+ krb5_creds **out_creds);
+
+/**
+ * Server function for @a sendauth protocol.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in] fd File descriptor
+ * @param [in] appl_version Application protocol version to be matched
+ * against the client's application version
+ * @param [in] server Server principal (NULL for any in @a keytab)
+ * @param [in] flags Additional specifications
+ * @param [in] keytab Key table containing service keys
+ * @param [out] ticket Ticket (NULL if not needed)
+ *
+ * This function performs the srever side of a sendauth/recvauth exchange by
+ * sending and receiving messages over @a fd.
+ *
+ * Use krb5_free_ticket() to free @a ticket when it is no longer needed.
+ *
+ * @sa krb5_sendauth()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_recvauth(krb5_context context, krb5_auth_context *auth_context,
+ krb5_pointer fd, char *appl_version, krb5_principal server,
+ krb5_int32 flags, krb5_keytab keytab, krb5_ticket **ticket);
+
+/**
+ * Server function for @a sendauth protocol with version parameter.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in] fd File descriptor
+ * @param [in] server Server principal (NULL for any in @a keytab)
+ * @param [in] flags Additional specifications
+ * @param [in] keytab Decryption key
+ * @param [out] ticket Ticket (NULL if not needed)
+ * @param [out] version sendauth protocol version (NULL if not needed)
+ *
+ * This function is similar to krb5_recvauth() with the additional output
+ * information place into @a version.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_recvauth_version(krb5_context context,
+ krb5_auth_context *auth_context,
+ krb5_pointer fd,
+ krb5_principal server,
+ krb5_int32 flags,
+ krb5_keytab keytab,
+ krb5_ticket **ticket,
+ krb5_data *version);
+
+/**
+ * Format a @c KRB-CRED message for an array of credentials.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in] ppcreds Null-terminated array of credentials
+ * @param [out] ppdata Encoded credentials
+ * @param [out] outdata Replay cache information (NULL if not needed)
+ *
+ * This function takes an array of credentials @a ppcreds and formats
+ * a @c KRB-CRED message @a ppdata to pass to krb5_rd_cred().
+ *
+ * @note If the #KRB5_AUTH_CONTEXT_RET_TIME or #KRB5_AUTH_CONTEXT_RET_SEQUENCE
+ * flag is set in @a auth_context, @a outdata is required.
+ *
+ * The message will be encrypted using the send subkey of @a auth_context if it
+ * is present, or the session key otherwise.
+ *
+ * @retval
+ * 0 Success
+ * @retval
+ * ENOMEM Insufficient memory
+ * @retval
+ * KRB5_RC_REQUIRED Message replay detection requires @a rcache parameter
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_mk_ncred(krb5_context context, krb5_auth_context auth_context,
+ krb5_creds **ppcreds, krb5_data **ppdata,
+ krb5_replay_data *outdata);
+
+/**
+ * Format a @c KRB-CRED message for a single set of credentials.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in] pcreds Pointer to credentials
+ * @param [out] ppdata Encoded credentials
+ * @param [out] outdata Replay cache data (NULL if not needed)
+ *
+ * This is a convenience function that calls krb5_mk_ncred() with a single set
+ * of credentials.
+ *
+ * @retval
+ * 0 Success
+ * @retval
+ * ENOMEM Insufficient memory
+ * @retval
+ * KRB5_RC_REQUIRED Message replay detection requires @a rcache parameter
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_mk_1cred(krb5_context context, krb5_auth_context auth_context,
+ krb5_creds *pcreds, krb5_data **ppdata,
+ krb5_replay_data *outdata);
+
+/**
+ * Read and validate a @c KRB-CRED message.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in] pcreddata @c KRB-CRED message
+ * @param [out] pppcreds Null-terminated array of forwarded credentials
+ * @param [out] outdata Replay data (NULL if not needed)
+ *
+ * @note The @a outdata argument is required if #KRB5_AUTH_CONTEXT_RET_TIME or
+ * #KRB5_AUTH_CONTEXT_RET_SEQUENCE flag is set in the @a auth_context.`
+ *
+ * @a pcreddata will be decrypted using the receiving subkey if it is present
+ * in @a auth_context, or the session key if the receiving subkey is not
+ * present or fails to decrypt the message.
+ *
+ * Use krb5_free_tgt_creds() to free @a pppcreds when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_rd_cred(krb5_context context, krb5_auth_context auth_context,
+ krb5_data *pcreddata, krb5_creds ***pppcreds,
+ krb5_replay_data *outdata);
+
+/**
+ * Get a forwarded TGT and format a @c KRB-CRED message.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context
+ * @param [in] rhost Remote host
+ * @param [in] client Client principal of TGT
+ * @param [in] server Principal of server to receive TGT
+ * @param [in] cc Credential cache handle (NULL to use default)
+ * @param [in] forwardable Whether TGT should be forwardable
+ * @param [out] outbuf KRB-CRED message
+ *
+ * Get a TGT for use at the remote host @a rhost and format it into a KRB-CRED
+ * message. If @a rhost is NULL and @a server is of type #KRB5_NT_SRV_HST,
+ * the second component of @a server will be used.
+ *
+ * @retval
+ * 0 Success
+ * @retval
+ * ENOMEM Insufficient memory
+ * @retval
+ * KRB5_PRINC_NOMATCH Requested principal and ticket do not match
+ * @retval
+ * KRB5_NO_TKT_SUPPLIED Request did not supply a ticket
+ * @retval
+ * KRB5_CC_BADNAME Credential cache name or principal name malformed
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_fwd_tgt_creds(krb5_context context, krb5_auth_context auth_context,
+ char *rhost, krb5_principal client, krb5_principal server,
+ krb5_ccache cc, int forwardable, krb5_data *outbuf);
+
+/**
+ * Create and initialize an authentication context.
+ *
+ * @param [in] context Library context
+ * @param [out] auth_context Authentication context
+ *
+ * This function creates an authentication context to hold configuration and
+ * state relevant to krb5 functions for authenticating principals and
+ * protecting messages once authentication has occurred.
+ *
+ * By default, flags for the context are set to enable the use of the replay
+ * cache (#KRB5_AUTH_CONTEXT_DO_TIME), but not sequence numbers. Use
+ * krb5_auth_con_setflags() to change the flags.
+ *
+ * The allocated @a auth_context must be freed with krb5_auth_con_free() when
+ * it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_init(krb5_context context, krb5_auth_context *auth_context);
+
+/**
+ * Free a krb5_auth_context structure.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context to be freed
+ *
+ * This function frees an auth context allocated by krb5_auth_con_init().
+ *
+ * @retval 0 (always)
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_free(krb5_context context, krb5_auth_context auth_context);
+
+/**
+ * Set a flags field in a krb5_auth_context structure.
+ *
+ * @param [in] context Library context
+ * @param [in,out] auth_context Authentication context
+ * @param [in] flags Flags bit mask
+ *
+ * Valid values for @a flags are:
+ * @li #KRB5_AUTH_CONTEXT_DO_TIME Use timestamps
+ * @li #KRB5_AUTH_CONTEXT_RET_TIME Save timestamps
+ * @li #KRB5_AUTH_CONTEXT_DO_SEQUENCE Use sequence numbers
+ * @li #KRB5_AUTH_CONTEXT_RET_SEQUENCE Save sequence numbers
+ *
+ * @retval 0 (always)
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_setflags(krb5_context context, krb5_auth_context auth_context, krb5_int32 flags);
+
+/**
+ * Retrieve flags from a krb5_auth_context structure.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context
+ * @param [out] flags Flags bit mask
+ *
+ * Valid values for @a flags are:
+ * @li #KRB5_AUTH_CONTEXT_DO_TIME Use timestamps
+ * @li #KRB5_AUTH_CONTEXT_RET_TIME Save timestamps
+ * @li #KRB5_AUTH_CONTEXT_DO_SEQUENCE Use sequence numbers
+ * @li #KRB5_AUTH_CONTEXT_RET_SEQUENCE Save sequence numbers
+ *
+ * @retval 0 (always)
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_getflags(krb5_context context, krb5_auth_context auth_context,
+ krb5_int32 *flags);
+
+/**
+ * Set a checksum callback in an auth context.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context
+ * @param [in] func Checksum callback
+ * @param [in] data Callback argument
+ *
+ * Set a callback to obtain checksum data in krb5_mk_req(). The callback will
+ * be invoked after the subkey and local sequence number are stored in @a
+ * auth_context.
+ *
+ * @retval 0 (always)
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_set_checksum_func( krb5_context context,
+ krb5_auth_context auth_context,
+ krb5_mk_req_checksum_func func,
+ void *data);
+
+/**
+ * Get the checksum callback from an auth context.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context
+ * @param [out] func Checksum callback
+ * @param [out] data Callback argument
+ *
+ * @retval 0 (always)
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_get_checksum_func( krb5_context context,
+ krb5_auth_context auth_context,
+ krb5_mk_req_checksum_func *func,
+ void **data);
+
+/**
+ * Set the local and remote addresses in an auth context.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context
+ * @param [in] local_addr Local address
+ * @param [in] remote_addr Remote address
+ *
+ * This function releases the storage assigned to the contents of the local and
+ * remote addresses of @a auth_context and then sets them to @a local_addr and
+ * @a remote_addr respectively.
+ *
+ * @sa krb5_auth_con_genaddrs()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV_WRONG
+krb5_auth_con_setaddrs(krb5_context context, krb5_auth_context auth_context,
+ krb5_address *local_addr, krb5_address *remote_addr);
+
+/**
+ * Retrieve address fields from an auth context.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context
+ * @param [out] local_addr Local address (NULL if not needed)
+ * @param [out] remote_addr Remote address (NULL if not needed)
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_getaddrs(krb5_context context, krb5_auth_context auth_context,
+ krb5_address **local_addr, krb5_address **remote_addr);
+
+/**
+ * Set local and remote port fields in an auth context.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context
+ * @param [in] local_port Local port
+ * @param [in] remote_port Remote port
+ *
+ * This function releases the storage assigned to the contents of the local and
+ * remote ports of @a auth_context and then sets them to @a local_port and @a
+ * remote_port respectively.
+ *
+ * @sa krb5_auth_con_genaddrs()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_setports(krb5_context context, krb5_auth_context auth_context,
+ krb5_address *local_port, krb5_address *remote_port);
+
+/**
+ * Set the session key in an auth context.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context
+ * @param [in] keyblock User key
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_setuseruserkey(krb5_context context, krb5_auth_context auth_context,
+ krb5_keyblock *keyblock);
+
+/**
+ * Retrieve the session key from an auth context as a keyblock.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context
+ * @param [out] keyblock Session key
+ *
+ * This function creates a keyblock containing the session key from @a
+ * auth_context. Use krb5_free_keyblock() to free @a keyblock when it is no
+ * longer needed
+ *
+ * @retval 0 Success. Otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_getkey(krb5_context context, krb5_auth_context auth_context,
+ krb5_keyblock **keyblock);
+
+/**
+ * Retrieve the session key from an auth context.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context
+ * @param [out] key Session key
+ *
+ * This function sets @a key to the session key from @a auth_context. Use
+ * krb5_k_free_key() to release @a key when it is no longer needed.
+ *
+ * @retval 0 (always)
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_getkey_k(krb5_context context, krb5_auth_context auth_context,
+ krb5_key *key);
+
+/**
+ * Retrieve the send subkey from an auth context as a keyblock.
+ *
+ * @param [in] ctx Library context
+ * @param [in] ac Authentication context
+ * @param [out] keyblock Send subkey
+ *
+ * This function creates a keyblock containing the send subkey from @a
+ * auth_context. Use krb5_free_keyblock() to free @a keyblock when it is no
+ * longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_getsendsubkey(krb5_context ctx, krb5_auth_context ac, krb5_keyblock **keyblock);
+
+/**
+ * Retrieve the send subkey from an auth context.
+ *
+ * @param [in] ctx Library context
+ * @param [in] ac Authentication context
+ * @param [out] key Send subkey
+ *
+ * This function sets @a key to the send subkey from @a auth_context. Use
+ * krb5_k_free_key() to release @a key when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_getsendsubkey_k(krb5_context ctx, krb5_auth_context ac,
+ krb5_key *key);
+
+/**
+ * Retrieve the receiving subkey from an auth context as a keyblock.
+ *
+ * @param [in] ctx Library context
+ * @param [in] ac Authentication context
+ * @param [out] keyblock Receiving subkey
+ *
+ * This function creates a keyblock containing the receiving subkey from @a
+ * auth_context. Use krb5_free_keyblock() to free @a keyblock when it is no
+ * longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_getrecvsubkey(krb5_context ctx, krb5_auth_context ac, krb5_keyblock **keyblock);
+
+/**
+ * Retrieve the receiving subkey from an auth context as a keyblock.
+ *
+ * @param [in] ctx Library context
+ * @param [in] ac Authentication context
+ * @param [out] key Receiving subkey
+ *
+ * This function sets @a key to the receiving subkey from @a auth_context. Use
+ * krb5_k_free_key() to release @a key when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_getrecvsubkey_k(krb5_context ctx, krb5_auth_context ac, krb5_key *key);
+
+/**
+ * Set the send subkey in an auth context with a keyblock.
+ *
+ * @param [in] ctx Library context
+ * @param [in] ac Authentication context
+ * @param [in] keyblock Send subkey
+ *
+ * This function sets the send subkey in @a ac to a copy of @a keyblock.
+ *
+ * @retval 0 Success. Otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_setsendsubkey(krb5_context ctx, krb5_auth_context ac,
+ krb5_keyblock *keyblock);
+
+/**
+ * Set the send subkey in an auth context.
+ *
+ * @param [in] ctx Library context
+ * @param [in] ac Authentication context
+ * @param [out] key Send subkey
+ *
+ * This function sets the send subkey in @a ac to @a key, incrementing its
+ * reference count.
+ *
+ * @version First introduced in 1.9
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_setsendsubkey_k(krb5_context ctx, krb5_auth_context ac, krb5_key key);
+
+/**
+ * Set the receiving subkey in an auth context with a keyblock.
+ *
+ * @param [in] ctx Library context
+ * @param [in] ac Authentication context
+ * @param [in] keyblock Receiving subkey
+ *
+ * This function sets the receiving subkey in @a ac to a copy of @a keyblock.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_setrecvsubkey(krb5_context ctx, krb5_auth_context ac,
+ krb5_keyblock *keyblock);
+
+/**
+ * Set the receiving subkey in an auth context.
+ *
+ * @param [in] ctx Library context
+ * @param [in] ac Authentication context
+ * @param [in] key Receiving subkey
+ *
+ * This function sets the receiving subkey in @a ac to @a key, incrementing its
+ * reference count.
+ *
+ * @version First introduced in 1.9
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_setrecvsubkey_k(krb5_context ctx, krb5_auth_context ac,
+ krb5_key key);
+
+#if KRB5_DEPRECATED
+/** @deprecated Replaced by krb5_auth_con_getsendsubkey(). */
+KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
+krb5_auth_con_getlocalsubkey(krb5_context context, krb5_auth_context auth_context,
+ krb5_keyblock **keyblock);
+
+/** @deprecated Replaced by krb5_auth_con_getrecvsubkey(). */
+KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
+krb5_auth_con_getremotesubkey(krb5_context context, krb5_auth_context auth_context,
+ krb5_keyblock **keyblock);
+#endif
+
+/**
+ * Retrieve the local sequence number from an auth context.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context
+ * @param [out] seqnumber Local sequence number
+ *
+ * Retrieve the local sequence number from @a auth_context and return it in @a
+ * seqnumber. The #KRB5_AUTH_CONTEXT_DO_SEQUENCE flag must be set in @a
+ * auth_context for this function to be useful.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_getlocalseqnumber(krb5_context context, krb5_auth_context auth_context,
+ krb5_int32 *seqnumber);
+
+/**
+ * Retrieve the remote sequence number from an auth context.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context
+ * @param [out] seqnumber Remote sequence number
+ *
+ * Retrieve the remote sequence number from @a auth_context and return it in @a
+ * seqnumber. The #KRB5_AUTH_CONTEXT_DO_SEQUENCE flag must be set in @a
+ * auth_context for this function to be useful.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_getremoteseqnumber(krb5_context context, krb5_auth_context auth_context,
+ krb5_int32 *seqnumber);
+
+#if KRB5_DEPRECATED
+/** @deprecated Not replaced.
+ *
+ * RFC 4120 doesn't have anything like the initvector concept;
+ * only really old protocols may need this API.
+ */
+KRB5_ATTR_DEPRECATED krb5_error_code KRB5_CALLCONV
+krb5_auth_con_initivector(krb5_context context, krb5_auth_context auth_context);
+#endif
+
+/**
+ * Set the replay cache in an auth context.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context
+ * @param [in] rcache Replay cache haddle
+ *
+ * This function sets the replay cache in @a auth_context to @a rcache. @a
+ * rcache will be closed when @a auth_context is freed, so the caller should
+ * relinguish that responsibility.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_setrcache(krb5_context context, krb5_auth_context auth_context,
+ krb5_rcache rcache);
+
+/**
+ * Retrieve the replay cache from an auth context.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context
+ * @param [out] rcache Replay cache handle
+ *
+ * This function fetches the replay cache from @a auth_context. The caller
+ * should not close @a rcache.
+ *
+ * @retval 0 (always)
+ */
+krb5_error_code KRB5_CALLCONV_WRONG
+krb5_auth_con_getrcache(krb5_context context, krb5_auth_context auth_context,
+ krb5_rcache *rcache);
+
+/**
+ * Retrieve the authenticator from an auth context.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context
+ * @param [out] authenticator Authenticator
+ *
+ * Use krb5_free_authenticator() to free @a authenticator when it is no longer
+ * needed.
+ *
+ * @retval 0 Success. Otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_getauthenticator(krb5_context context, krb5_auth_context auth_context,
+ krb5_authenticator **authenticator);
+
+/**
+ * Set checksum type in an an auth context.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context
+ * @param [in] cksumtype Checksum type
+ *
+ * This function sets the checksum type in @a auth_context to be used by
+ * krb5_mk_req() for the authenticator checksum.
+ *
+ * @retval 0 Success. Otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_set_req_cksumtype(krb5_context context, krb5_auth_context auth_context,
+ krb5_cksumtype cksumtype);
+
+#define KRB5_REALM_BRANCH_CHAR '.'
+
+/*
+ * end "func-proto.h"
+ */
+
+/*
+ * begin stuff from libos.h
+ */
+
+/**
+ * @brief Read a password from keyboard input.
+ *
+ * @param [in] context Library context
+ * @param [in] prompt First user prompt when reading password
+ * @param [in] prompt2 Second user prompt (NULL to prompt only once)
+ * @param [out] return_pwd Returned password
+ * @param [in,out] size_return On input, maximum size of password; on output,
+ * size of password read
+ *
+ * This function reads a password from keyboard input and stores it in @a
+ * return_pwd. @a size_return should be set by the caller to the amount of
+ * storage space available in @a return_pwd; on successful return, it will be
+ * set to the length of the password read.
+ *
+ * @a prompt is printed to the terminal, followed by ": ", and then a password
+ * is read from the keyboard.
+ *
+ * If @a prompt2 is NULL, the password is read only once. Otherwise, @a
+ * prompt2 is printed to the terminal and a second password is read. If the
+ * two passwords entered are not identical, KRB5_LIBOS_BADPWDMATCH is returned.
+ *
+ * Echoing is turned off when the password is read.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Error in reading or verifying the password
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_read_password(krb5_context context,
+ const char *prompt, const char *prompt2,
+ char *return_pwd, unsigned int *size_return);
+
+/**
+ * Convert a principal name to a local name.
+ *
+ * @param [in] context Library context
+ * @param [in] aname Principal name
+ * @param [in] lnsize_in Space available in @a lname
+ * @param [out] lname Local name buffer to be filled in
+ *
+ * If @a aname does not correspond to any local account, KRB5_LNAME_NOTRANS is
+ * returned. If @a lnsize_in is too small for the local name,
+ * KRB5_CONFIG_NOTENUFSPACE is returned.
+ *
+ * Local names, rather than principal names, can be used by programs that
+ * translate to an environment-specific name (for example, a user account
+ * name).
+ *
+ * @retval
+ * 0 Success
+ * @retval
+ * System errors
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_aname_to_localname(krb5_context context, krb5_const_principal aname,
+ int lnsize_in, char *lname);
+
+/**
+ * Get the Kerberos realm names for a host.
+ *
+ * @param [in] context Library context
+ * @param [in] host Host name (or NULL)
+ * @param [out] realmsp Null-terminated list of realm names
+ *
+ * Fill in @a realmsp with a pointer to a null-terminated list of realm names.
+ * If there are no known realms for the host, a list containing the referral
+ * (empty) realm is returned.
+ *
+ * If @a host is NULL, the local host's realms are determined.
+ *
+ * Use krb5_free_host_realm() to release @a realmsp when it is no longer
+ * needed.
+ *
+ * @retval
+ * 0 Success
+ * @retval
+ * ENOMEM Insufficient memory
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_host_realm(krb5_context context, const char *host, char ***realmsp);
+
+/**
+ *
+ * @param [in] context Library context
+ * @param [in] hdata Host name (or NULL)
+ * @param [out] realmsp Null-terminated list of realm names
+ *
+ * Fill in @a realmsp with a pointer to a null-terminated list of realm names
+ * obtained through heuristics or insecure resolution methods which have lower
+ * priority than KDC referrals.
+ *
+ * If @a host is NULL, the local host's realms are determined.
+ *
+ * Use krb5_free_host_realm() to release @a realmsp when it is no longer
+ * needed.
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_fallback_host_realm(krb5_context context,
+ krb5_data *hdata, char ***realmsp);
+
+/**
+ * Free the memory allocated by krb5_get_host_realm().
+ *
+ * @param [in] context Library context
+ * @param [in] realmlist List of realm names to be released
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_free_host_realm(krb5_context context, char *const *realmlist);
+
+/**
+ * Determine if a principal is authorized to log in as a local user.
+ *
+ * @param [in] context Library context
+ * @param [in] principal Principal name
+ * @param [in] luser Local username
+ *
+ * Determine whether @a principal is authorized to log in as a local user @a
+ * luser.
+ *
+ * @retval
+ * TRUE Principal is authorized to log in as user; FALSE otherwise.
+ */
+krb5_boolean KRB5_CALLCONV
+krb5_kuserok(krb5_context context, krb5_principal principal, const char *luser);
+
+/**
+ * Generate auth context addresses from a connected socket.
+ *
+ * @param [in] context Library context
+ * @param [in] auth_context Authentication context
+ * @param [in] infd Connected socket descriptor
+ * @param [in] flags Flags
+ *
+ * This function sets the local and/or remote addresses in @a auth_context
+ * based on the local and remote endpoints of the socket @a infd. The
+ * following flags determine the operations performed:
+ *
+ * @li #KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR Generate local address.
+ * @li #KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR Generate remote address.
+ * @li #KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR Generate local address and port.
+ * @li #KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR Generate remote address and port.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_auth_con_genaddrs(krb5_context context, krb5_auth_context auth_context,
+ int infd, int flags);
+
+/**
+ * Set time offset field in a krb5_context structure.
+ *
+ * @param [in] context Library context
+ * @param [in] seconds Real time, seconds portion
+ * @param [in] microseconds Real time, microseconds portion
+ *
+ * This function sets the time offset in @a context to the difference between
+ * the system time and the real time as determined by @a seconds and @a
+ * microseconds.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_set_real_time(krb5_context context, krb5_timestamp seconds,
+ krb5_int32 microseconds);
+
+/**
+ * Return the time offsets from the os context.
+ *
+ * @param [in] context Library context
+ * @param [out] seconds Time offset, seconds portion
+ * @param [out] microseconds Time offset, microseconds portion
+ *
+ * This function returns the time offsets in @a context.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_time_offsets(krb5_context context, krb5_timestamp *seconds, krb5_int32 *microseconds);
+
+/* str_conv.c */
+/**
+ * Convert a string to an encryption type.
+ *
+ * @param [in] string String to convert to an encryption type
+ * @param [out] enctypep Encryption type
+ *
+ * @retval 0 Success; otherwise - EINVAL
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_string_to_enctype(char *string, krb5_enctype *enctypep);
+
+/**
+ * Convert a string to a salt type.
+ *
+ * @param [in] string String to convert to an encryption type
+ * @param [out] salttypep Salt type to be filled in
+ *
+ * @retval 0 Success; otherwise - EINVAL
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_string_to_salttype(char *string, krb5_int32 *salttypep);
+
+/**
+ * Convert a string to a checksum type.
+ *
+ * @param [in] string String to be converted
+ * @param [out] cksumtypep Checksum type to be filled in
+ *
+ * @retval 0 Success; otherwise - EINVAL
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_string_to_cksumtype(char *string, krb5_cksumtype *cksumtypep);
+
+/**
+ * Convert a string to a timestamp.
+ *
+ * @param [in] string String to be converted
+ * @param [out] timestampp Pointer to timestamp
+ *
+ * @retval 0 Success; otherwise - EINVAL
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_string_to_timestamp(char *string, krb5_timestamp *timestampp);
+
+/**
+ * Convert a string to a delta time value.
+ *
+ * @param [in] string String to be converted
+ * @param [out] deltatp Delta time to be filled in
+ *
+ * @retval 0 Success; otherwise - KRB5_DELTAT_BADFORMAT
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_string_to_deltat(char *string, krb5_deltat *deltatp);
+
+/**
+ * Convert an encryption type to a string.
+ *
+ * @param [in] enctype Encryption type
+ * @param [out] buffer Buffer to hold encryption type string
+ * @param [in] buflen Storage available in @a buffer
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_enctype_to_string(krb5_enctype enctype, char *buffer, size_t buflen);
+
+/**
+ * Convert an encryption type to a name or alias.
+ *
+ * @param [in] enctype Encryption type
+ * @param [in] shortest Flag
+ * @param [out] buffer Buffer to hold encryption type string
+ * @param [in] buflen Storage available in @a buffer
+ *
+ * If @a shortest is FALSE, this function returns the enctype's canonical name
+ * (like "aes128-cts-hmac-sha1-96"). If @a shortest is TRUE, it return the
+ * enctype's shortest alias (like "aes128-cts").
+ *
+ * @version First introduced in 1.9
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_enctype_to_name(krb5_enctype enctype, krb5_boolean shortest,
+ char *buffer, size_t buflen);
+
+/**
+ * Convert a salt type to a string.
+ *
+ * @param [in] salttype Salttype to convert
+ * @param [out] buffer Buffer to receive the converted string
+ * @param [in] buflen Storage available in @a buffer
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_salttype_to_string(krb5_int32 salttype, char *buffer, size_t buflen);
+
+/**
+ * Convert a checksum type to a string.
+ *
+ * @param [in] cksumtype Checksum type
+ * @param [out] buffer Buffer to hold converted checksum type
+ * @param [in] buflen Storage available in @a buffer
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_cksumtype_to_string(krb5_cksumtype cksumtype, char *buffer, size_t buflen);
+
+/**
+ * Convert a timestamp to a string.
+ *
+ * @param [in] timestamp Timestamp to convert
+ * @param [out] buffer Buffer to hold converted timestamp
+ * @param [in] buflen Storage available in @a buffer
+ *
+ * The string is returned in the locale's appropriate date and time
+ * representation.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_timestamp_to_string(krb5_timestamp timestamp, char *buffer, size_t buflen);
+
+/**
+ * Convert a timestamp to a string, with optional output padding
+ *
+ * @param [in] timestamp Timestamp to convert
+ * @param [out] buffer Buffer to hold the converted timestamp
+ * @param [in] buflen Length of buffer
+ * @param [in] pad Optional value to pad @a buffer if converted
+ * timestamp does not fill it
+ *
+ * If @a pad is not NULL, @a buffer is padded out to @a buflen - 1 characters
+ * with the value of *@a pad.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_timestamp_to_sfstring(krb5_timestamp timestamp, char *buffer,
+ size_t buflen, char *pad);
+
+/**
+ * Convert a relative time value to a string.
+ *
+ * @param [in] deltat Relative time value to convert
+ * @param [out] buffer Buffer to hold time string
+ * @param [in] buflen Storage available in @a buffer
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_deltat_to_string(krb5_deltat deltat, char *buffer, size_t buflen);
+
+/* The name of the Kerberos ticket granting service... and its size */
+#define KRB5_TGS_NAME "krbtgt"
+#define KRB5_TGS_NAME_SIZE 6
+
+/* flags for recvauth */
+#define KRB5_RECVAUTH_SKIP_VERSION 0x0001
+#define KRB5_RECVAUTH_BADAUTHVERS 0x0002
+/* initial ticket api functions */
+
+/** Text for prompt used in prompter callback function. */
+typedef struct _krb5_prompt {
+ char *prompt; /**< The prompt to show to the user */
+ int hidden; /**< Boolean; informative prompt or hidden (e.g. PIN) */
+ krb5_data *reply; /**< Must be allocated before call to prompt routine */
} krb5_prompt;
-typedef krb5_error_code (KRB5_CALLCONV *krb5_prompter_fct)(krb5_context context,
- void *data,
- const char *name,
- const char *banner,
- int num_prompts,
- krb5_prompt prompts[]);
+/** Pointer to a prompter callback function. */
+typedef krb5_error_code
+(KRB5_CALLCONV *krb5_prompter_fct)(krb5_context context, void *data,
+ const char *name, const char *banner,
+ int num_prompts, krb5_prompt prompts[]);
+
+/**
+ * Prompt user for password.
+ *
+ * @param [in] context Library context
+ * @param data Unused (callback argument)
+ * @param [in] name Name to output during prompt
+ * @param [in] banner Banner to output during prompt
+ * @param [in] num_prompts Number of prompts in @a prompts
+ * @param [in,out] prompts Array of output prompts and replies
+ *
+ * This function is intended to be used as a prompter callback for
+ * krb5_get_init_creds_password() or krb5_init_creds_init().
+ *
+ * Writes @a name and @a banner to stdout, each followed by a newline, then
+ * writes each prompt field in the @a prompts array, followed by ": ", and sets
+ * the reply field of the entry to a line of input read from stdin. If the
+ * hidden flag is set for a prompt, then terminal echoing is turned off when
+ * input is read.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ *
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_prompter_posix(krb5_context context, void *data, const char *name,
+ const char *banner, int num_prompts,
+ krb5_prompt prompts[]);
+
+/** Store options for @c _krb5_get_init_creds */
+typedef struct _krb5_get_init_creds_opt {
+ krb5_flags flags;
+ krb5_deltat tkt_life;
+ krb5_deltat renew_life;
+ int forwardable;
+ int proxiable;
+ krb5_enctype *etype_list;
+ int etype_list_length;
+ krb5_address **address_list;
+ krb5_preauthtype *preauth_list;
+ int preauth_list_length;
+ krb5_data *salt;
+} krb5_get_init_creds_opt;
+
+#define KRB5_GET_INIT_CREDS_OPT_TKT_LIFE 0x0001
+#define KRB5_GET_INIT_CREDS_OPT_RENEW_LIFE 0x0002
+#define KRB5_GET_INIT_CREDS_OPT_FORWARDABLE 0x0004
+#define KRB5_GET_INIT_CREDS_OPT_PROXIABLE 0x0008
+#define KRB5_GET_INIT_CREDS_OPT_ETYPE_LIST 0x0010
+#define KRB5_GET_INIT_CREDS_OPT_ADDRESS_LIST 0x0020
+#define KRB5_GET_INIT_CREDS_OPT_PREAUTH_LIST 0x0040
+#define KRB5_GET_INIT_CREDS_OPT_SALT 0x0080
+#define KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT 0x0100
+#define KRB5_GET_INIT_CREDS_OPT_CANONICALIZE 0x0200
+#define KRB5_GET_INIT_CREDS_OPT_ANONYMOUS 0x0400
+
+
+/**
+ * Allocate a new initial credential options structure.
+ *
+ * @param [in] context Library context
+ * @param [out] opt New options structure
+ *
+ * This function is the preferred way to create an options structure for
+ * getting initial credentials, and is required to make use of certain options.
+ * Use krb5_get_init_creds_opt_free() to free @a opt when it is no longer
+ * needed.
+ *
+ * @retval 0 - Success; Kerberos errors otherwise.
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_init_creds_opt_alloc(krb5_context context,
+ krb5_get_init_creds_opt **opt);
+
+/**
+ * Free initial credential options.
+ *
+ * @param [in] context Library context
+ * @param [in] opt Options structure to free
+ *
+ * @sa krb5_get_init_creds_opt_alloc()
+ */
+void KRB5_CALLCONV
+krb5_get_init_creds_opt_free(krb5_context context,
+ krb5_get_init_creds_opt *opt);
+
+/** @deprecated Use krb5_get_init_creds_opt_alloc() instead. */
+void KRB5_CALLCONV
+krb5_get_init_creds_opt_init(krb5_get_init_creds_opt *opt);
+
+/**
+ * Set the ticket lifetime in initial credential options.
+ *
+ * @param [in] opt Options structure
+ * @param [in] tkt_life Ticket lifetime
+ */
+void KRB5_CALLCONV
+krb5_get_init_creds_opt_set_tkt_life(krb5_get_init_creds_opt *opt,
+ krb5_deltat tkt_life);
+
+/**
+ * Set the ticket renewal lifetime in initial credential options.
+ *
+ * @param [in] opt Pointer to @a options field
+ * @param [in] renew_life Ticket renewal lifetime
+ */
+void KRB5_CALLCONV
+krb5_get_init_creds_opt_set_renew_life(krb5_get_init_creds_opt *opt,
+ krb5_deltat renew_life);
+
+/**
+ * Set or unset the forwardable flag in initial credential options.
+ *
+ * @param [in] opt Options structure
+ * @param [in] forwardable Whether credentials should be forwardable
+ */
+void KRB5_CALLCONV
+krb5_get_init_creds_opt_set_forwardable(krb5_get_init_creds_opt *opt,
+ int forwardable);
+
+/**
+ * Set or unset the proxiable flag in initial credential options.
+ *
+ * @param [in] opt Options structure
+ * @param [in] proxiable Whether credentials should be proxiable
+ */
+void KRB5_CALLCONV
+krb5_get_init_creds_opt_set_proxiable(krb5_get_init_creds_opt *opt,
+ int proxiable);
+
+/**
+ * Set or unset the canonicalize flag in initial credential options.
+ *
+ * @param [in] opt Options structure
+ * @param [in] canonicalize Whether to canonicalize client principal
+ */
+void KRB5_CALLCONV
+krb5_get_init_creds_opt_set_canonicalize(krb5_get_init_creds_opt *opt,
+ int canonicalize);
+
+/**
+ * Set or unset the anonymous flag in initial credential options.
+ *
+ * @param [in] opt Options structure
+ * @param [in] anonymous Whether to make an anonymous request
+ *
+ * This function may be used to request anonymous credentials from the KDC by
+ * setting @a anonymous to non-zero. Note that anonymous credentials are only
+ * a request; clients must verify that credentials are anonymous if that is a
+ * requirement.
+ */
+void KRB5_CALLCONV
+krb5_get_init_creds_opt_set_anonymous(krb5_get_init_creds_opt *opt,
+ int anonymous);
+
+/**
+ * Set allowable encryption types in initial credential options.
+ *
+ * @param [in] opt Options structure
+ * @param [in] etype_list Array of encryption types
+ * @param [in] etype_list_length Length of @a etype_list
+ */
+void KRB5_CALLCONV
+krb5_get_init_creds_opt_set_etype_list(krb5_get_init_creds_opt *opt,
+ krb5_enctype *etype_list,
+ int etype_list_length);
+
+/**
+ * Set address restrictions in initial credential options.
+ *
+ * @param [in] opt Options structure
+ * @param [in] addresses Null-terminated array of addresses
+ */
+void KRB5_CALLCONV
+krb5_get_init_creds_opt_set_address_list(krb5_get_init_creds_opt *opt,
+ krb5_address **addresses);
+
+/**
+ * Set preauthentication types in initial credential options.
+ *
+ * @param [in] opt Options structure
+ * @param [in] preauth_list Array of preauthentication types
+ * @param [in] preauth_list_length Length of @a preauth_list
+ *
+ * This function can be used to perform optimistic preauthentication when
+ * getting initial credentials, in combination with
+ * krb5_get_init_creds_opt_set_salt() and krb5_get_init_creds_opt_set_pa().
+ */
+void KRB5_CALLCONV
+krb5_get_init_creds_opt_set_preauth_list(krb5_get_init_creds_opt *opt,
+ krb5_preauthtype *preauth_list,
+ int preauth_list_length);
+
+/**
+ * Set salt for optimistic preauthentication in initial credential options.
+ *
+ * @param [in] opt Options structure
+ * @param [in] salt Salt data
+ *
+ * When getting initial credentials with a password, a salt string it used to
+ * convert the password to a key. Normally this salt is obtained from the
+ * first KDC reply, but when performing optimistic preauthentication, the
+ * client may need to supply the salt string with this function.
+ */
+void KRB5_CALLCONV
+krb5_get_init_creds_opt_set_salt(krb5_get_init_creds_opt *opt,
+ krb5_data *salt);
+
+/**
+ * Set or unset change-password-prompt flag in initial credential options.
+ *
+ * @param [in] opt Options structure
+ * @param [in] prompt Whether to prompt to change password
+ *
+ * This flag is on by default. It controls whether
+ * krb5_get_init_creds_password() will react to an expired-password error by
+ * prompting for a new password and attempting to change the old one.
+ */
+void KRB5_CALLCONV
+krb5_get_init_creds_opt_set_change_password_prompt(krb5_get_init_creds_opt *opt,
+ int prompt);
+
+/** Generic preauth option attribute/value pairs */
+typedef struct _krb5_gic_opt_pa_data {
+ char *attr;
+ char *value;
+} krb5_gic_opt_pa_data;
+
+/**
+ * Supply options for preauthentication in initial credential options.
+ *
+ * @param [in] context Library context
+ * @param [in] opt Options structure
+ * @param [in] attr Preauthentication option name
+ * @param [in] value Preauthentication option value
+ *
+ * This function allows the caller to supply options for preauthentication.
+ * The values of @a attr and @a value are supplied to each preauthentication
+ * module available within @a context.
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_init_creds_opt_set_pa(krb5_context context,
+ krb5_get_init_creds_opt *opt, const char *attr,
+ const char *value);
+
+/**
+ * Set location of FAST armor ccache in initial credential options.
+ *
+ * @param [in] context Library context
+ * @param [in] opt Options
+ * @param [in] fast_ccache_name Credential cache name
+ *
+ * Sets the location of a credential cache containing an armor ticket to
+ * protect an initial credential exchange using the FAST protocol extension.
+ *
+ * In version 1.7, setting an armor ccache requires that FAST be used for the
+ * exchange. In version 1.8 or later, setting the armor ccache causes FAST to
+ * be used if the KDC supports it; krb5_get_init_creds_opt_set_fast_flags()
+ * must be used to require that FAST be used.
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_init_creds_opt_set_fast_ccache_name(krb5_context context,
+ krb5_get_init_creds_opt *opt,
+ const char *fast_ccache_name);
+
+/**
+ * Set FAST armor cache in initial credential options.
+ *
+ * @param [in] context Library context
+ * @param [in] opt Options
+ * @param [in] ccache Credential cache handle
+ *
+ * This function is similar to krb5_get_init_creds_opt_set_fast_ccache_name(),
+ * but uses a credential cache handle instead of a name.
+ *
+ * @version First introduced in 1.9
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_init_creds_opt_set_fast_ccache(krb5_context context,
+ krb5_get_init_creds_opt *opt,
+ krb5_ccache ccache);
+
+/**
+ * Set an output credential cache in initial credential options.
+ *
+ * @param [in] context Library context
+ * @param [in] opt Options
+ * @param [in] ccache Credential cache handle
+ *
+ * If an output credential cache is set, then the krb5_get_init_creds family of
+ * APIs will write credentials to it. Setting an output ccache is desirable
+ * both because it simplifies calling code and because it permits the
+ * krb5_get_init_creds APIs to write out configuration information about the
+ * realm to the ccache.
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_init_creds_opt_set_out_ccache(krb5_context context,
+ krb5_get_init_creds_opt *opt,
+ krb5_ccache ccache);
+
+/**
+ * Set FAST flags in initial credential options.
+ *
+ * @param [in] context Library context
+ * @param [in] opt Options
+ * @param [in] flags FAST flags
+ *
+ * The following flag values are valid:
+ * @li #KRB5_FAST_REQUIRED - Require FAST to be used
+ *
+ * @retval
+ * 0 - Success; Kerberos errors otherwise.
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_init_creds_opt_set_fast_flags(krb5_context context,
+ krb5_get_init_creds_opt *opt,
+ krb5_flags flags);
+
+/**
+ * Retrieve FAST flags from initial credential options.
+ *
+ * @param [in] context Library context
+ * @param [in] opt Options
+ * @param [out] out_flags FAST flags
+ *
+ * @retval
+ * 0 - Success; Kerberos errors otherwise.
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_init_creds_opt_get_fast_flags(krb5_context context,
+ krb5_get_init_creds_opt *opt,
+ krb5_flags *out_flags);
+
+/* Fast flags*/
+#define KRB5_FAST_REQUIRED 1l<<0 /**< Require KDC to support FAST*/
+
+typedef void
+(KRB5_CALLCONV *krb5_expire_callback_func)(krb5_context context, void *data,
+ krb5_timestamp password_expiration,
+ krb5_timestamp account_expiration,
+ krb5_boolean is_last_req);
+
+/**
+ * Set an expiration callback in initial credential options.
+ *
+ * @param [in] context Library context
+ * @param [in] opt Options structure
+ * @param [in] cb Callback function
+ * @param [in] data Callback argument
+ *
+ * Set a callback to receive password and account expiration times.
+ *
+ * This option only applies to krb5_get_init_creds_password(). @a cb will be
+ * invoked if and only if credentials are successfully acquired. The callback
+ * will receive the @a context from the krb5_get_init_creds_password() call and
+ * the @a data argument supplied with this API. The remaining arguments should
+ * be interpreted as follows:
+ *
+ * If @a is_last_req is true, then the KDC reply contained last-req entries
+ * which unambiguously indicated the password expiration, account expiration,
+ * or both. (If either value was not present, the corresponding argument will
+ * be 0.) Furthermore, a non-zero @a password_expiration should be taken as a
+ * suggestion from the KDC that a warning be displayed.
+ *
+ * If @a is_last_req is false, then @a account_expiration will be 0 and @a
+ * password_expiration will contain the expiration time of either the password
+ * or account, or 0 if no expiration time was indicated in the KDC reply. The
+ * callback should independently decide whether to display a password
+ * expiration warning.
+ *
+ * Note that @a cb may be invoked even if credentials are being acquired for
+ * the kadmin/changepw service in order to change the password. It is the
+ * caller's responsibility to avoid displaying a password expiry warning in
+ * this case.
+ *
+ * @warning Setting an expire callback with this API will cause
+ * krb5_get_init_creds_password() not to send password expiry warnings to the
+ * prompter, as it ordinarily may.
+ *
+ * @version First introduced in 1.9
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_init_creds_opt_set_expire_callback(krb5_context context,
+ krb5_get_init_creds_opt *opt,
+ krb5_expire_callback_func cb,
+ void *data);
+
+/**
+ * Get initial credentials using a password.
+ *
+ * @param [in] context Library context
+ * @param [out] creds New credentials
+ * @param [in] client Client principal
+ * @param [in] password Password (or NULL)
+ * @param [in] prompter Prompter function
+ * @param [in] data Prompter callback data
+ * @param [in] start_time Time when ticket becomes valid (0 for now)
+ * @param [in] in_tkt_service Service name of initial credentials (or NULL)
+ * @param [in] k5_gic_options Initial credential options
+ *
+ * This function requests KDC for an initial credentials for @a client using @a
+ * password. If @a password is NULL, a password will be prompted for using @a
+ * prompter if necessary. If @a in_tkt_service is specified, it is parsed as a
+ * principal name (with the realm ignored) and used as the service principal
+ * for the request; otherwise the ticket-granting service is used.
+ *
+ * @sa krb5_verify_init_creds()
+ *
+ * @retval
+ * 0 Success
+ * @retval
+ * EINVAL Invalid argument
+ * @retval
+ * KRB5_KDC_UNREACH Cannot contact any KDC for requested realm
+ * @retval
+ * KRB5_PREAUTH_FAILED Generic Pre-athentication failure
+ * @retval
+ * KRB5_LIBOS_PWDINTR Password read interrupted
+ * @retval
+ * KRB5_REALM_CANT_RESOLVE Cannot resolve network address for KDC in requested realm
+ * @retval
+ * KRB5KDC_ERR_KEY_EXP Password has expired
+ * @retval
+ * KRB5_LIBOS_BADPWDMATCH Password mismatch
+ * @retval
+ * KRB5_CHPW_PWDNULL New password cannot be zero length
+ * @retval
+ * KRB5_CHPW_FAIL Password change failed
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_init_creds_password(krb5_context context, krb5_creds *creds,
+ krb5_principal client, char *password,
+ krb5_prompter_fct prompter, void *data,
+ krb5_deltat start_time, char *in_tkt_service,
+ krb5_get_init_creds_opt *k5_gic_options);
+
+struct _krb5_init_creds_context;
+typedef struct _krb5_init_creds_context *krb5_init_creds_context;
+
+#define KRB5_INIT_CREDS_STEP_FLAG_CONTINUE 0x1 /**< More responses needed */
+/**
+ * Free an initial credentials context.
+ *
+ * @param [in] context Library context
+ * @param [in] ctx Initial credentials context
+ */
+void KRB5_CALLCONV
+krb5_init_creds_free(krb5_context context, krb5_init_creds_context ctx);
+/**
+ * Acquire credentials using an initial credentials context.
+ *
+ * @param [in] context Library context
+ * @param [in] ctx Initial credentials context
+ *
+ * This function synchronously obtains credentials using a context created by
+ * krb5_init_creds_init(). On successful return, the credentials can be
+ * retrieved with krb5_init_creds_get_creds().
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_prompter_posix (krb5_context context,
- void *data,
- const char *name,
- const char *banner,
- int num_prompts,
- krb5_prompt prompts[]);
-
-typedef struct _krb5_get_init_creds_opt {
- krb5_flags flags;
- krb5_deltat tkt_life;
- krb5_deltat renew_life;
- int forwardable;
- int proxiable;
- krb5_enctype *etype_list;
- int etype_list_length;
- krb5_address **address_list;
- krb5_preauthtype *preauth_list;
- int preauth_list_length;
- krb5_data *salt;
-} krb5_get_init_creds_opt;
+krb5_init_creds_get(krb5_context context, krb5_init_creds_context ctx);
-#define KRB5_GET_INIT_CREDS_OPT_TKT_LIFE 0x0001
-#define KRB5_GET_INIT_CREDS_OPT_RENEW_LIFE 0x0002
-#define KRB5_GET_INIT_CREDS_OPT_FORWARDABLE 0x0004
-#define KRB5_GET_INIT_CREDS_OPT_PROXIABLE 0x0008
-#define KRB5_GET_INIT_CREDS_OPT_ETYPE_LIST 0x0010
-#define KRB5_GET_INIT_CREDS_OPT_ADDRESS_LIST 0x0020
-#define KRB5_GET_INIT_CREDS_OPT_PREAUTH_LIST 0x0040
-#define KRB5_GET_INIT_CREDS_OPT_SALT 0x0080
-#define KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT 0x0100
-#define KRB5_GET_INIT_CREDS_OPT_CANONICALIZE 0x0200
+/**
+ * Retrieve acquired credentials from an initial credentials context.
+ *
+ * @param [in] context Library context
+ * @param [in] ctx Initial credentials context
+ * @param [out] creds Acquired credentials
+ *
+ * This function copies the acquired initial credentials from @a ctx into @a
+ * creds, after the successful completion of krb5_init_creds_get() or
+ * krb5_init_creds_step(). Use krb5_free_cred_contents() to free @a creds when
+ * it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_init_creds_get_creds(krb5_context context, krb5_init_creds_context ctx,
+ krb5_creds *creds);
+/**
+ * Get the last error from KDC from an initial credentials context.
+ *
+ * @param [in] context Library context
+ * @param [in] ctx Initial credentials context
+ * @param [out] error Error from KDC, or NULL if none was received
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_init_creds_get_error(krb5_context context, krb5_init_creds_context ctx,
+ krb5_error **error);
+/**
+ * Create a context for acquiring initial credentials.
+ *
+ * @param [in] context Library context
+ * @param [in] client Client principal to get initial creds for
+ * @param [in] prompter Prompter callback
+ * @param [in] data Prompter callback argument
+ * @param [in] start_time Time when credentials become valid (0 for now)
+ * @param [in] options Options structure (NULL for default)
+ * @param [out] ctx New initial credentials context
+ *
+ * This function creates a new context for acquiring initial credentials. Use
+ * krb5_init_creds_free() to free @a ctx when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_get_init_creds_opt_alloc
-(krb5_context context,
- krb5_get_init_creds_opt **opt);
+krb5_init_creds_init(krb5_context context, krb5_principal client,
+ krb5_prompter_fct prompter, void *data,
+ krb5_deltat start_time, krb5_get_init_creds_opt *options,
+ krb5_init_creds_context *ctx);
-void KRB5_CALLCONV
-krb5_get_init_creds_opt_free
-(krb5_context context,
- krb5_get_init_creds_opt *opt);
+/**
+ * Specify a keytab to use for acquiring initial credentials.
+ *
+ * @param [in] context Library context
+ * @param [in] ctx Initial credentials context
+ * @param [in] keytab Key table handle
+ *
+ * This function supplies a keytab containing the client key for an initial
+ * credentials request.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_init_creds_set_keytab(krb5_context context, krb5_init_creds_context ctx,
+ krb5_keytab keytab);
-void KRB5_CALLCONV
-krb5_get_init_creds_opt_init
-(krb5_get_init_creds_opt *opt);
+/**
+ * Get the next KDC request for acquiring initial credentials.
+ *
+ * @param [in] context Library context
+ * @param [in] ctx Initial credentials context
+ * @param [in] in KDC response (empty on the first call)
+ * @param [out] out Next KDC request
+ * @param [out] realm Realm for next KDC request
+ * @param [out] flags Output flags
+ *
+ * This function constructs the next KDC request in an initial credential
+ * exchange, allowing the caller to control the transport of KDC requests and
+ * replies. On the first call, @a in should be set to an empty buffer; on
+ * subsequent calls, it should be set to the KDC's reply to the previous
+ * request.
+ *
+ * If more requests are needed, @a flags will be set to
+ * #KRB5_INIT_CREDS_STEP_FLAG_CONTINUE and the next request will be placed in
+ * @a out. If no more requests are needed, @a flags will not contain
+ * #KRB5_INIT_CREDS_STEP_FLAG_CONTINUE and @a out will be empty.
+ *
+ * If this function returns @c KRB5KRB_ERR_RESPONSE_TOO_BIG, the caller should
+ * transmit the next request using TCP rather than UDP. If this function
+ * returns any other error, the initial credential exchange has failed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_init_creds_step(krb5_context context, krb5_init_creds_context ctx,
+ krb5_data *in, krb5_data *out, krb5_data *realm,
+ unsigned int *flags);
-void KRB5_CALLCONV
-krb5_get_init_creds_opt_set_tkt_life
-(krb5_get_init_creds_opt *opt,
- krb5_deltat tkt_life);
+/**
+ * Set a password for acquiring initial credentials.
+ *
+ * @param [in] context Library context
+ * @param [in] ctx Initial credentials context
+ * @param [in] password Password
+ *
+ * This function supplies a password to be used to construct the client key for
+ * an initial credentials request.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_init_creds_set_password(krb5_context context, krb5_init_creds_context ctx,
+ const char *password);
-void KRB5_CALLCONV
-krb5_get_init_creds_opt_set_renew_life
-(krb5_get_init_creds_opt *opt,
- krb5_deltat renew_life);
+/**
+ * Specify a service principal for acquiring initial credentials.
+ *
+ * @param [in] context Library context
+ * @param [in] ctx Initial credentials context
+ * @param [in] service Service principal string
+ *
+ * This function supplies a service principal string to acquire initial
+ * credentials for instead of the default krbtgt service. @a service is parsed
+ * as a principal name; any realm part is ignored.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_init_creds_set_service(krb5_context context, krb5_init_creds_context ctx,
+ const char *service);
-void KRB5_CALLCONV
-krb5_get_init_creds_opt_set_forwardable
-(krb5_get_init_creds_opt *opt,
- int forwardable);
+/**
+ * Retrieve ticket times from an initial credentials context.
+ *
+ * @param [in] context Library context
+ * @param [in] ctx Initial credentials context
+ * @param [out] times Ticket times for acquired credentials
+ *
+ * The initial credentials context must have completed obtaining credentials
+ * via either krb5_init_creds_get() or krb5_init_creds_step().
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_init_creds_get_times(krb5_context context, krb5_init_creds_context ctx,
+ krb5_ticket_times *times);
-void KRB5_CALLCONV
-krb5_get_init_creds_opt_set_proxiable
-(krb5_get_init_creds_opt *opt,
- int proxiable);
+struct _krb5_tkt_creds_context;
+typedef struct _krb5_tkt_creds_context *krb5_tkt_creds_context;
-void KRB5_CALLCONV
-krb5_get_init_creds_opt_set_canonicalize
-(krb5_get_init_creds_opt *opt,
- int canonicalize);
+/**
+ * Create a context to get credentials from a KDC's Ticket Granting Service.
+ *
+ * @param[in] context Library context
+ * @param[in] ccache Credential cache handle
+ * @param[in] creds Input credentials
+ * @param[in] options @ref KRB5_GC options for this request.
+ * @param[out] ctx New TGS request context
+ *
+ * This function prepares to obtain credentials matching @a creds, either by
+ * retrieving them from @a ccache or by making requests to ticket-granting
+ * services beginning with a ticket-granting ticket for the client principal's
+ * realm.
+ *
+ * The resulting TGS acquisition context can be used asynchronously with
+ * krb5_tkt_creds_step() or synchronously with krb5_tkt_creds_get(). See also
+ * krb5_get_credentials() for synchronous use.
+ *
+ * Use krb5_tkt_creds_free() to free @a ctx when it is no longer needed.
+ *
+ * @version First introduced in 1.9
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_tkt_creds_init(krb5_context context, krb5_ccache ccache,
+ krb5_creds *creds, krb5_flags options,
+ krb5_tkt_creds_context *ctx);
-void KRB5_CALLCONV
-krb5_get_init_creds_opt_set_etype_list
-(krb5_get_init_creds_opt *opt,
- krb5_enctype *etype_list,
- int etype_list_length);
+/**
+ * Synchronously obtain credentials using a TGS request context.
+ *
+ * @param[in] context Library context
+ * @param[in] ctx TGS request context
+ *
+ * This function synchronously obtains credentials using a context created by
+ * krb5_tkt_creds_init(). On successful return, the credentials can be
+ * retrieved with krb5_tkt_creds_get_creds().
+ *
+ * @version First introduced in 1.9
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_tkt_creds_get(krb5_context context, krb5_tkt_creds_context ctx);
-void KRB5_CALLCONV
-krb5_get_init_creds_opt_set_address_list
-(krb5_get_init_creds_opt *opt,
- krb5_address **addresses);
+/**
+ * Retrieve acquired credentials from a TGS request context.
+ *
+ * @param[in] context Library context
+ * @param[in] ctx TGS request context
+ * @param[out] creds Acquired credentials
+ *
+ * This function copies the acquired initial credentials from @a ctx into @a
+ * creds, after the successful completion of krb5_tkt_creds_get() or
+ * krb5_tkt_creds_step(). Use krb5_free_cred_contents() to free @a creds when
+ * it is no longer needed.
+ *
+ * @version First introduced in 1.9
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_tkt_creds_get_creds(krb5_context context, krb5_tkt_creds_context ctx,
+ krb5_creds *creds);
+/**
+ * Free a TGS request context.
+ *
+ * @param[in] context Library context
+ * @param[in] ctx TGS request context
+ *
+ * @version First introduced in 1.9
+ */
void KRB5_CALLCONV
-krb5_get_init_creds_opt_set_preauth_list
-(krb5_get_init_creds_opt *opt,
- krb5_preauthtype *preauth_list,
- int preauth_list_length);
+krb5_tkt_creds_free(krb5_context context, krb5_tkt_creds_context ctx);
-void KRB5_CALLCONV
-krb5_get_init_creds_opt_set_salt
-(krb5_get_init_creds_opt *opt,
- krb5_data *salt);
+#define KRB5_TKT_CREDS_STEP_FLAG_CONTINUE 0x1 /**< More responses needed */
-void KRB5_CALLCONV
-krb5_get_init_creds_opt_set_change_password_prompt
-(krb5_get_init_creds_opt *opt,
- int prompt);
+/**
+ * Get the next KDC request in a TGS exchange.
+ *
+ * @param[in] context Library context
+ * @param[in] ctx TGS request context
+ * @param[in] in KDC response (empty on the first call)
+ * @param[out] out Next KDC request
+ * @param[out] realm Realm for next KDC request
+ * @param[out] flags Output flags
+ *
+ * This function constructs the next KDC request for a TGS exchange, allowing
+ * the caller to control the transport of KDC requests and replies. On the
+ * first call, @a in should be set to an empty buffer; on subsequent calls, it
+ * should be set to the KDC's reply to the previous request.
+ *
+ * If more requests are needed, @a flags will be set to
+ * #KRB5_TKT_CREDS_STEP_FLAG_CONTINUE and the next request will be placed in @a
+ * out. If no more requests are needed, @a flags will not contain
+ * #KRB5_TKT_CREDS_STEP_FLAG_CONTINUE and @a out will be empty.
+ *
+ * If this function returns @c KRB5KRB_ERR_RESPONSE_TOO_BIG, the caller should
+ * transmit the next request using TCP rather than UDP. If this function
+ * returns any other error, the TGS exchange has failed.
+ *
+ * @version First introduced in 1.9
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_tkt_creds_step(krb5_context context, krb5_tkt_creds_context ctx,
+ krb5_data *in, krb5_data *out, krb5_data *realm,
+ unsigned int *flags);
-/* Generic preauth option attribute/value pairs */
-typedef struct _krb5_gic_opt_pa_data {
- char *attr;
- char *value;
-} krb5_gic_opt_pa_data;
+/**
+ * Retrieve ticket times from a TGS request context.
+ *
+ * @param[in] context Library context
+ * @param[in] ctx TGS request context
+ * @param[out] times Ticket times for acquired credentials
+ *
+ * The TGS request context must have completed obtaining credentials via either
+ * krb5_tkt_creds_get() or krb5_tkt_creds_step().
+ *
+ * @version First introduced in 1.9
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_tkt_creds_get_times(krb5_context context, krb5_tkt_creds_context ctx,
+ krb5_ticket_times *times);
-/*
- * This function allows the caller to supply options to preauth
- * plugins. Preauth plugin modules are given a chance to look
- * at each option at the time this function is called in ordre
- * to check the validity of the option.
- * The 'opt' pointer supplied to this function must have been
- * obtained using krb5_get_init_creds_opt_alloc()
- */
-krb5_error_code KRB5_CALLCONV
-krb5_get_init_creds_opt_set_pa
- (krb5_context context,
- krb5_get_init_creds_opt *opt,
- const char *attr,
- const char *value);
-
-krb5_error_code KRB5_CALLCONV krb5_get_init_creds_opt_set_fast_ccache_name
-(krb5_context context, krb5_get_init_creds_opt *opt,
- const char * fast_ccache_name);
- /* This API sets a ccache name that will contain some TGT on
- calls to get_init_creds functions. If set, this ccache will
- be used for FAST (draft-ietf-krb-wg-preauth-framework) to
- protect the AS-REQ from observation and active attack. If
- the fast_ccache_name is set, then FAST may be required by the
- client library. In this version FAST is required.*/
-krb5_error_code KRB5_CALLCONV
-krb5_get_init_creds_password
-(krb5_context context,
- krb5_creds *creds,
- krb5_principal client,
- char *password,
- krb5_prompter_fct prompter,
- void *data,
- krb5_deltat start_time,
- char *in_tkt_service,
- krb5_get_init_creds_opt *k5_gic_options);
-
-krb5_error_code KRB5_CALLCONV
-krb5_get_init_creds_keytab
-(krb5_context context,
- krb5_creds *creds,
- krb5_principal client,
- krb5_keytab arg_keytab,
- krb5_deltat start_time,
- char *in_tkt_service,
- krb5_get_init_creds_opt *k5_gic_options);
+/**
+ * Get initial credentials using a key table.
+ *
+ * @param [in] context Library context
+ * @param [out] creds New credentials
+ * @param [in] client Client principal
+ * @param [in] arg_keytab Key table handle
+ * @param [in] start_time Time when ticket becomes valid (0 for now)
+ * @param [in] in_tkt_service Service name of initial credentials (or NLUL)
+ * @param [in] k5_gic_options Initial credential options
+ *
+ * This function requests KDC for an initial credentials for @a client using a
+ * client key stored in @a arg_keytab. If @a in_tkt_service is specified, it
+ * is parsed as a principal name (with the realm ignored) and used as the
+ * service principal for the request; otherwise the ticket-granting service is
+ * used.
+ *
+ * @sa krb5_verify_init_creds()
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_get_init_creds_keytab(krb5_context context, krb5_creds *creds,
+ krb5_principal client, krb5_keytab arg_keytab,
+ krb5_deltat start_time, char *in_tkt_service,
+ krb5_get_init_creds_opt *k5_gic_options);
typedef struct _krb5_verify_init_creds_opt {
krb5_flags flags;
- int ap_req_nofail;
+ int ap_req_nofail; /**< boolean */
} krb5_verify_init_creds_opt;
-#define KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL 0x0001
+#define KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL 0x0001
+/**
+ * Initialize a credential verification options structure.
+ *
+ * @param [in] k5_vic_options Verification options structure
+ */
void KRB5_CALLCONV
-krb5_verify_init_creds_opt_init
-(krb5_verify_init_creds_opt *k5_vic_options);
+krb5_verify_init_creds_opt_init(krb5_verify_init_creds_opt *k5_vic_options);
+
+/**
+ * Set whether credential verification is required.
+ *
+ * @param [in] k5_vic_options Verification options structure
+ * @param [in] ap_req_nofail Whether to require successful verification
+ *
+ * This function determines how krb5_verify_init_creds() behaves if no keytab
+ * information is available. If @a ap_req_nofail is @c FALSE, verification
+ * will be skipped in this case and krb5_verify_init_creds() will return
+ * successfully. If @a ap_req_nofail is @c TRUE, krb5_verify_init_creds() will
+ * not return successfully unless verification can be performed.
+ *
+ * If this function is not used, the behavior of krb5_verify_init_creds() is
+ * determined through configuration.
+ */
void KRB5_CALLCONV
-krb5_verify_init_creds_opt_set_ap_req_nofail
-(krb5_verify_init_creds_opt *k5_vic_options,
- int ap_req_nofail);
+krb5_verify_init_creds_opt_set_ap_req_nofail(krb5_verify_init_creds_opt * k5_vic_options,
+ int ap_req_nofail);
+/**
+ * Verify initial credentials against a keytab.
+ *
+ * @param [in] context Library context
+ * @param [in] creds Initial credentials to be verified
+ * @param [in] server_arg Server principal (or NULL)
+ * @param [in] keytab_arg Key table (NULL to use default keytab)
+ * @param [in,out] ccache_arg Credential cache for fetched creds (or NULL)
+ * @param [in] options Verification options (NULL for default options)
+ *
+ * This function attempts to verify that @a creds were obtained from a KDC with
+ * knowledge of a key in @a keytab_arg. If @a server_arg is provided, the
+ * highest-kvno key entry for that principal name is used to verify the
+ * credentials; otherwise, the highest-kvno key entry for the first principal
+ * listed in @a keytab_arg is used.
+ *
+ * If the specified keytab does not exist, or is empty, or cannot be read, or
+ * does not contain an entry for @a server_arg, then credential verification
+ * may be skipped unless configuration demands that it succeed. The caller can
+ * control this behavior by providing a verification options structure; see
+ * krb5_verify_init_creds_opt_init() and
+ * krb5_verify_init_creds_opt_set_ap_req_nofail().
+ *
+ * If @a ccache_arg is NULL, any additional credentials fetched during the
+ * verification process will be destroyed. If @a ccache_arg points to NULL, a
+ * memory ccache will be created for the additional credentials and returned in
+ * @a ccache_arg. If @a ccache_arg points to a valid credential cache handle,
+ * the additional credentials will be stored in that cache.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_verify_init_creds
-(krb5_context context,
- krb5_creds *creds,
- krb5_principal ap_req_server,
- krb5_keytab ap_req_keytab,
- krb5_ccache *ccache,
- krb5_verify_init_creds_opt *k5_vic_options);
+krb5_verify_init_creds(krb5_context context, krb5_creds *creds,
+ krb5_principal server_arg, krb5_keytab keytab_arg,
+ krb5_ccache *ccache_arg, krb5_verify_init_creds_opt *options);
+/**
+ * Get validated credentials from the KDC.
+ *
+ * @param [in] context Library context
+ * @param [out] creds Validated credentials
+ * @param [in] client Client principal name
+ * @param [in] ccache Credential cache
+ * @param [in] in_tkt_service Server principal string (or NULL)
+ *
+ * This function gets a validated credential using a postdated credential from
+ * @a ccache. If @a in_tkt_service is specified, it is parsed (with the realm
+ * part ignored) and used as the server principal of the credential;
+ * otherwise, the ticket-granting service is used.
+ *
+ * If successful, the validated credential is placed in @a creds.
+ *
+ * @sa krb5_get_renewed_creds()
+ *
+ * @retval
+ * 0 Success
+ * @retval
+ * KRB5_NO_2ND_TKT Request missing second ticket
+ * @retval
+ * KRB5_NO_TKT_SUPPLIED Request did not supply a ticket
+ * @retval
+ * KRB5_PRINC_NOMATCH Requested principal and ticket do not match
+ * @retval
+ * KRB5_KDCREP_MODIFIED KDC reply did not match expectations
+ * @retval
+ * KRB5_KDCREP_SKEW Clock skew too great in KDC reply
+ * @return
+ * Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_get_validated_creds
-(krb5_context context,
- krb5_creds *creds,
- krb5_principal client,
- krb5_ccache ccache,
- char *in_tkt_service);
+krb5_get_validated_creds(krb5_context context, krb5_creds *creds,
+ krb5_principal client, krb5_ccache ccache,
+ char *in_tkt_service);
+/**
+ * Get renewed credential from KDC using an existing credential.
+ *
+ * @param [in] context Library context
+ * @param [out] creds Renewed credentials
+ * @param [in] client Client principal name
+ * @param [in] ccache Credential cache
+ * @param [in] in_tkt_service Server principal string (or NULL)
+ *
+ * This function gets a renewed credential using an existing one from @a
+ * ccache. If @a in_tkt_service is specified, it is parsed (with the realm
+ * part ignored) and used as the server principal of the credential; otherwise,
+ * the ticket-granting service is used.
+ *
+ * If successful, the renewed credential is placed in @a creds.
+ *
+ * @retval
+ * 0 Success
+ * @return
+ * Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_get_renewed_creds
-(krb5_context context,
- krb5_creds *creds,
- krb5_principal client,
- krb5_ccache ccache,
- char *in_tkt_service);
+krb5_get_renewed_creds(krb5_context context, krb5_creds *creds,
+ krb5_principal client, krb5_ccache ccache,
+ char *in_tkt_service);
+/**
+ * Decode an ASN.1-formatted ticket.
+ *
+ * @param [in] code ASN.1-formatted ticket
+ * @param [out] rep Decoded ticket information
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_decode_ticket
-(const krb5_data *code,
- krb5_ticket **rep);
+krb5_decode_ticket(const krb5_data *code, krb5_ticket **rep);
+/**
+ * Retrieve a string value from the appdefaults section of krb5.conf.
+ *
+ * @param [in] context Library context
+ * @param [in] appname Application name
+ * @param [in] realm Realm name
+ * @param [in] option Option to be checked
+ * @param [in] default_value Default value to return if no match is found
+ * @param [out] ret_value String value of @a option
+ *
+ * This function gets the application defaults for @a option based on the given
+ * @a appname and/or @a realm.
+ *
+ * @sa krb5_appdefault_boolean()
+ */
void KRB5_CALLCONV
-krb5_appdefault_string
-(krb5_context context,
- const char *appname,
- const krb5_data *realm,
- const char *option,
- const char *default_value,
- char ** ret_value);
+krb5_appdefault_string(krb5_context context, const char *appname,
+ const krb5_data *realm, const char *option,
+ const char *default_value, char ** ret_value);
+/**
+ * Retrieve a boolean value from the appdefaults section of krb5.conf.
+ *
+ * @param [in] context Library context
+ * @param [in] appname Application name
+ * @param [in] realm Realm name
+ * @param [in] option Option to be checked
+ * @param [in] default_value Default value to return if no match is found
+ * @param [out] ret_value Boolean value of @a option
+ *
+ * This function gets the application defaults for @a option based on the given
+ * @a appname and/or @a realm.
+ *
+ * @sa krb5_appdefault_string()
+ */
void KRB5_CALLCONV
-krb5_appdefault_boolean
-(krb5_context context,
- const char *appname,
- const krb5_data *realm,
- const char *option,
- int default_value,
- int *ret_value);
+krb5_appdefault_boolean(krb5_context context, const char *appname,
+ const krb5_data *realm, const char *option,
+ int default_value, int *ret_value);
/*
* Prompter enhancements
*/
-
+/** Prompt for password */
#define KRB5_PROMPT_TYPE_PASSWORD 0x1
+/** Prompt for new password (during password change) */
#define KRB5_PROMPT_TYPE_NEW_PASSWORD 0x2
+/** Prompt for new password again */
#define KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN 0x3
+/** Prompt for preauthentication data (such as an OTP value) */
#define KRB5_PROMPT_TYPE_PREAUTH 0x4
typedef krb5_int32 krb5_prompt_type;
-krb5_prompt_type* KRB5_CALLCONV krb5_get_prompt_types
- (krb5_context context);
+/**
+ * Get prompt types array from a context.
+ *
+ * @param [in] context Library context
+ *
+ * @return
+ * Pointer to an array of prompt types corresponding to the prompter's @a
+ * prompts arguments. Each type has one of the following values:
+ * @li #KRB5_PROMPT_TYPE_PASSWORD
+ * @li #KRB5_PROMPT_TYPE_NEW_PASSWORD
+ * @li #KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN
+ * @li #KRB5_PROMPT_TYPE_PREAUTH
+ */
+krb5_prompt_type* KRB5_CALLCONV
+krb5_get_prompt_types(krb5_context context);
/* Error reporting */
+/**
+ * Set an extended error message for an error code.
+ *
+ * @param [in] ctx Library context
+ * @param [in] code Error code
+ * @param [in] fmt Error string for the error code
+ * @param [in] ... printf(3) style parameters
+ */
void KRB5_CALLCONV_C
-krb5_set_error_message (krb5_context, krb5_error_code, const char *, ...)
+krb5_set_error_message(krb5_context ctx, krb5_error_code code, const char *fmt, ...)
#if !defined(__cplusplus) && (__GNUC__ > 2)
__attribute__((__format__(__printf__, 3, 4)))
#endif
;
+
+/**
+ * Set an extended error message for an error code using a va_list.
+ *
+ * @param [in] ctx Library context
+ * @param [in] code Error code
+ * @param [in] fmt Error string for the error code
+ * @param [in] args List of vprintf(3) style arguments
+ */
void KRB5_CALLCONV
-krb5_vset_error_message (krb5_context, krb5_error_code, const char *, va_list)
+krb5_vset_error_message(krb5_context ctx, krb5_error_code code,
+ const char *fmt, va_list args)
#if !defined(__cplusplus) && (__GNUC__ > 2)
__attribute__((__format__(__printf__, 3, 0)))
#endif
;
+
+/**
+ * Copy the most recent extended error message from one context to another.
+ *
+ * @param [in] dest_ctx Library context to copy message to
+ * @param [in] src_ctx Library context with current message
+ */
void KRB5_CALLCONV
-krb5_copy_error_message (krb5_context, krb5_context);
+krb5_copy_error_message(krb5_context dest_ctx, krb5_context src_ctx);
-/*
- * The behavior of krb5_get_error_message is only defined the first
- * time it is called after a failed call to a krb5 function using the
- * same context, and only when the error code passed in is the same as
- * that returned by the krb5 function. Future versions may return the
- * same string for the second and following calls.
+/**
+ * Get the (possibly extended) error message for a code.
+ *
+ * @param [in] ctx Library context
+ * @param [in] code Error code
+ *
+ * The behavior of krb5_get_error_message() is only defined the first time it
+ * is called after a failed call to a krb5 function using the same context, and
+ * only when the error code passed in is the same as that returned by the krb5
+ * function.
+ *
+ * This function never returns NULL, so its result may be used unconditionally
+ * as a C string.
*
* The string returned by this function must be freed using
- * krb5_free_error_message.
+ * krb5_free_error_message()
+ *
+ * @note Future versions may return the same string for the second
+ * and following calls.
*/
const char * KRB5_CALLCONV
-krb5_get_error_message (krb5_context, krb5_error_code);
+krb5_get_error_message(krb5_context ctx, krb5_error_code code);
+
+/**
+ * Free an error message generated by krb5_get_error_message().
+ *
+ * @param [in] ctx Library context
+ * @param [in] msg Pointer to error message
+ */
void KRB5_CALLCONV
-krb5_free_error_message (krb5_context, const char *);
+krb5_free_error_message(krb5_context ctx, const char *msg);
+
+/**
+ * Clear the extended error message in a context.
+ *
+ * @param [in] ctx Library context
+ *
+ * This function unsets the extended error message in a context, to ensure that
+ * it is not mistakenly applied to another occurrence of the same error code.
+ */
void KRB5_CALLCONV
-krb5_clear_error_message (krb5_context);
+krb5_clear_error_message(krb5_context ctx);
+/**
+ * Unwrap authorization data.
+ *
+ * @param [in] context Library context
+ * @param [in] type @ref KRB5_AUTHDATA type of @a container
+ * @param [in] container Authorization data to be decoded
+ * @param [out] authdata List of decoded authorization data
+ *
+ * @sa krb5_encode_authdata_container()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
krb5_decode_authdata_container(krb5_context context,
- krb5_authdatatype type,
- const krb5_authdata *container,
- krb5_authdata ***authdata);
+ krb5_authdatatype type,
+ const krb5_authdata *container,
+ krb5_authdata ***authdata);
+/**
+ * Wrap authorization data in a container.
+ *
+ * @param [in] context Library context
+ * @param [in] type @ref KRB5_AUTHDATA type of @a container
+ * @param [in] authdata List of authorization data to be encoded
+ * @param [out] container List of encoded authorization data
+ *
+ * The result is returned in @a container as a single-element list.
+ *
+ * @sa krb5_decode_authdata_container()
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
krb5_encode_authdata_container(krb5_context context,
- krb5_authdatatype type,
- krb5_authdata * const*authdata,
- krb5_authdata ***container);
+ krb5_authdatatype type,
+ krb5_authdata * const*authdata,
+ krb5_authdata ***container);
/*
* AD-KDCIssued
*/
+/**
+ * Encode and sign AD-KDCIssued authorization data.
+ *
+ * @param [in] context Library context
+ * @param [in] key Session key
+ * @param [in] issuer The name of the issuing principal
+ * @param [in] authdata List of authorization data to be signed
+ * @param [out] ad_kdcissued List containing AD-KDCIssued authdata
+ *
+ * This function wraps a list of authorization data entries @a authdata in an
+ * AD-KDCIssued container (see RFC 4120 section 5.2.6.2) signed with @a key.
+ * The result is returned in @a ad_kdcissued as a single-element list.
+ */
krb5_error_code KRB5_CALLCONV
krb5_make_authdata_kdc_issued(krb5_context context,
- const krb5_keyblock *key,
- krb5_const_principal issuer,
- krb5_authdata *const *authdata,
- krb5_authdata ***ad_kdcissued);
+ const krb5_keyblock *key,
+ krb5_const_principal issuer,
+ krb5_authdata *const *authdata,
+ krb5_authdata ***ad_kdcissued);
+
+/**
+ * Unwrap and verify AD-KDCIssued authorization data.
+ *
+ * @param [in] context Library context
+ * @param [in] key Session key
+ * @param [in] ad_kdcissued AD-KDCIssued authorization data to be unwrapped
+ * @param [out] issuer Name of issuing principal (or NULL)
+ * @param [out] authdata Unwrapped list of authorization data
+ *
+ * This function unwraps an AD-KDCIssued authdatum (see RFC 4120 section
+ * 5.2.6.2) and verifies its signature against @a key. The issuer field of the
+ * authdatum element is returned in @a issuer, and the unwrapped list of
+ * authdata is returned in @a authdata.
+ */
krb5_error_code KRB5_CALLCONV
krb5_verify_authdata_kdc_issued(krb5_context context,
- const krb5_keyblock *key,
- const krb5_authdata *ad_kdcissued,
- krb5_principal *issuer,
- krb5_authdata ***authdata);
+ const krb5_keyblock *key,
+ const krb5_authdata *ad_kdcissued,
+ krb5_principal *issuer,
+ krb5_authdata ***authdata);
/*
* Windows PAC
*/
+
+/* Microsoft defined types of data */
+#define KRB5_PAC_LOGON_INFO 1 /**< Logon information */
+#define KRB5_PAC_CREDENTIALS_INFO 2 /**< Credentials information */
+#define KRB5_PAC_SERVER_CHECKSUM 6 /**< Server checksum */
+#define KRB5_PAC_PRIVSVR_CHECKSUM 7 /**< KDC checksum */
+#define KRB5_PAC_CLIENT_INFO 10 /**< Client name and ticket info */
+#define KRB5_PAC_DELEGATION_INFO 11 /**< Constrained delegation info */
+#define KRB5_PAC_UPN_DNS_INFO 12 /**< User principal name and DNS info */
+
struct krb5_pac_data;
+/** PAC data structure to convey authorization information */
typedef struct krb5_pac_data *krb5_pac;
+/**
+ * Add a buffer to a PAC handle.
+ *
+ * @param [in] context Library context
+ * @param [in] pac PAC handle
+ * @param [in] type Buffer type
+ * @param [in] data contents
+ *
+ * This function adds a buffer of type @a type and contents @a data to @a pac
+ * if there isn't already a buffer of this type present.
+ *
+ * The valid values of @a type is one of the following:
+ * @li #KRB5_PAC_LOGON_INFO - Logon information
+ * @li #KRB5_PAC_CREDENTIALS_INFO - Credentials information
+ * @li #KRB5_PAC_SERVER_CHECKSUM - Server checksum
+ * @li #KRB5_PAC_PRIVSVR_CHECKSUM - KDC checksum
+ * @li #KRB5_PAC_CLIENT_INFO - Client name and ticket information
+ * @li #KRB5_PAC_DELEGATION_INFO - Constrained delegation information
+ * @li #KRB5_PAC_UPN_DNS_INFO - User principal name and DNS information
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_pac_add_buffer
-(krb5_context context,
- krb5_pac pac,
- krb5_ui_4 type,
- const krb5_data *data);
+krb5_pac_add_buffer(krb5_context context, krb5_pac pac, krb5_ui_4 type,
+ const krb5_data *data);
+/**
+ * Free a PAC handle.
+ *
+ * @param [in] context Library context
+ * @param [in] pac PAC to be freed
+ *
+ * This function frees the contents of @a pac and the structure itself.
+ */
void KRB5_CALLCONV
-krb5_pac_free
-(krb5_context context,
- krb5_pac pac);
+krb5_pac_free(krb5_context context, krb5_pac pac);
+
+/**
+ * Retrieve a buffer value from a PAC.
+ *
+ * @param [in] context Library context
+ * @param [in] pac PAC handle
+ * @param [in] type Type of buffer to retrieve
+ * @param [out] data Buffer value
+ *
+ * Use krb5_free_data_contents() to free @a data when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_pac_get_buffer(krb5_context context, krb5_pac pac, krb5_ui_4 type,
+ krb5_data *data);
+
+/**
+ * Return an array of buffer types in a PAC handle.
+ *
+ * @param [in] context Library context
+ * @param [in] pac PAC handle
+ * @param [out] len Number of entries in @a types
+ * @param [out] types Array of buffer types
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_pac_get_types(krb5_context context, krb5_pac pac, size_t *len,
+ krb5_ui_4 **types);
+
+/**
+ * Create an empty Privilege Attribute Certificate (PAC) handle.
+ *
+ * @param [in] context Library context
+ * @param [out] pac New PAC handle
+ *
+ * Use krb5_pac_free() to free @a pac when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_pac_init(krb5_context context, krb5_pac *pac);
+
+/**
+ * Unparse an encoded PAC into a new handle.
+ *
+ * @param [in] context Library context
+ * @param [in] ptr PAC buffer
+ * @param [in] len Length of @a ptr
+ * @param [out] pac PAC handle
+ *
+ * Use krb5_pac_free() to free @a pac when it is no longer needed.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_pac_parse(krb5_context context, const void *ptr, size_t len,
+ krb5_pac *pac);
+/**
+ * Verify a PAC.
+ *
+ * @param [in] context Library context
+ * @param [in] pac PAC handle
+ * @param [in] authtime Expected timestamp
+ * @param [in] principal Expected principal name (or NULL)
+ * @param [in] server Key to validate server checksum (or NULL)
+ * @param [in] privsvr Key to validate KDC checksum (or NULL)
+ *
+ * This function validates @a pac against the supplied @a server, @a privsvr,
+ * @a principal and @a authtime. If @a principal is NULL, the principal and
+ * authtime are not verified. If @a server or @a privsvr is NULL, the
+ * corresponding checksum is not verified.
+ *
+ * If successful, @a pac is marked as verified.
+ *
+ * @note A checksum mismatch can occur if the PAC was copied from a cross-realm
+ * TGT by an ignorant KDC; also Apple Mac OS X Server Open Directory (as of
+ * 10.6) generates PACs with no server checksum at all. One should consider
+ * not failing the whole authentication because of this reason, but, instead,
+ * treating the ticket as if it did not contain a PAC or marking the PAC
+ * information as non-verified.
+ *
+ * @retval 0 Success; otherwise - Kerberos error codes
+ */
krb5_error_code KRB5_CALLCONV
-krb5_pac_get_buffer
-(krb5_context context,
- krb5_pac pac,
- krb5_ui_4 type,
- krb5_data *data);
+krb5_pac_verify(krb5_context context, const krb5_pac pac,
+ krb5_timestamp authtime, krb5_const_principal principal,
+ const krb5_keyblock *server, const krb5_keyblock *privsvr);
+/**
+ * Sign a PAC.
+ *
+ * @param [in] context Library context
+ * @param [in] pac PAC handle
+ * @param [in] authtime Expected timestamp
+ * @param [in] principal Expected principal name (or NULL)
+ * @param [in] server_key Key for server checksum
+ * @param [in] privsvr_key Key for KDC checksum
+ * @param [out] data Signed PAC encoding
+ *
+ * This function signs @a pac using the keys @a server_key and @a privsvr_key
+ * and returns the signed encoding in @a data. @a pac is modified to include
+ * the server and KDC checksum buffers. Use krb5_free_data_contents() to free
+ * @a data when it is no longer needed.
+ *
+ * @version First introduced in 1.10
+ */
krb5_error_code KRB5_CALLCONV
-krb5_pac_get_types
-(krb5_context context,
- krb5_pac pac,
- size_t *len,
- krb5_ui_4 **types);
+krb5_pac_sign(krb5_context context, krb5_pac pac, krb5_timestamp authtime,
+ krb5_const_principal principal, const krb5_keyblock *server_key,
+ const krb5_keyblock *privsvr_key, krb5_data *data);
+/**
+ * Allow the appplication to override the profile's allow_weak_crypto setting.
+ *
+ * @param [in] context Library context
+ * @param [in] enable Boolean flag
+ *
+ * This function allows an application to override the allow_weak_crypto
+ * setting. It is primarily for use by aklog.
+ *
+ * @retval 0 (always)
+ */
krb5_error_code KRB5_CALLCONV
-krb5_pac_init
-(krb5_context context,
- krb5_pac *pac);
+krb5_allow_weak_crypto(krb5_context context, krb5_boolean enable);
+/* This structure may be extended to contain more fields in the future. */
+struct krb5_trace_info {
+ const char *message;
+};
+
+typedef void
+(KRB5_CALLCONV *krb5_trace_callback)(krb5_context context,
+ const struct krb5_trace_info *info,
+ void *cb_data);
+
+/**
+ * Specify a callback function for trace events.
+ *
+ * @param [in] context Library context
+ * @param [in] fn Callback function
+ * @param [in] cb_data Callback data
+ *
+ * Specify a callback for trace events occurring in krb5 operations performed
+ * within @a context. @a fn will be invoked with @a context as the first
+ * argument, @a cb_data as the last argument, and a pointer to a struct
+ * krb5_trace_info as the second argument. If the trace callback is reset via
+ * this function or @a context is destroyed, @a fn will be invoked with a NULL
+ * second argument so it can clean up @a cb_data. Supply a NULL value for @a
+ * fn to disable trace callbacks within @a context.
+ *
+ * @note This function overrides the information passed through the
+ * @a KRB5_TRACE environment variable.
+ *
+ * @version First introduced in 1.9
+ *
+ * @return Returns KRB5_TRACE_NOSUPP if tracing is not supported in the library
+ * (unless @a fn is NULL).
+ */
krb5_error_code KRB5_CALLCONV
-krb5_pac_parse
-(krb5_context context,
- const void *ptr,
- size_t len,
- krb5_pac *pac);
+krb5_set_trace_callback(krb5_context context, krb5_trace_callback fn,
+ void *cb_data);
+/**
+ * Specify a file name for directing trace events.
+ *
+ * @param [in] context Library context
+ * @param [in] filename File name
+ *
+ * Open @a filename for appending (creating it, if necessary) and set up a
+ * callback to write trace events to it.
+ *
+ * @note This function overrides the information passed through the
+ * @a KRB5_TRACE environment variable.
+ *
+ * @version First introduced in 1.9
+ *
+ * @retval KRB5_TRACE_NOSUPP Tracing is not supported in the library.
+ */
krb5_error_code KRB5_CALLCONV
-krb5_pac_verify
-(krb5_context context,
- const krb5_pac pac,
- krb5_timestamp authtime,
- krb5_const_principal principal,
- const krb5_keyblock *server,
- const krb5_keyblock *privsvr);
+krb5_set_trace_filename(krb5_context context, const char *filename);
#if TARGET_OS_MAC
# pragma pack(pop)
#undef KRB5_ATTR_DEPRECATED
+/** @} */ /* end of KRB5_H group */
+
#endif /* KRB5_GENERAL__ */
projects / krb5.git / blobdiff