Updated documentation for PAC API. Moved PAC type definitions into krb5.hin

[krb5.git] / src / include / krb5 / krb5.hin

/* -*- 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
 * notice appear in all copies and that both that copyright notice and
 * 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
 * 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.
 */
/*
 * 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
 * notice appear in all copies and that both that copyright notice and
 * this permission notice appear in supporting documentation, and that
 * the name of FundsXpress. not be used in advertising or publicity pertaining
 * to distribution of the software without specific, written prior
 * 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. */
#ifndef KRB5_DEPRECATED
#define KRB5_DEPRECATED 0
#endif

#if defined(__MACH__) && defined(__APPLE__)
#       include <TargetConditionals.h>
#    if TARGET_RT_MAC_CFM
#       error "Use KfM 4.0 SDK headers for CFM compilation."
#    endif
#endif

#if defined(_MSDOS) || defined(_WIN32)
#include <win-mac.h>
#endif

#ifndef KRB5_CONFIG__
#ifndef KRB5_CALLCONV
#define KRB5_CALLCONV
#define KRB5_CALLCONV_C
#endif /* !KRB5_CALLCONV */
#endif /* !KRB5_CONFIG__ */

#ifndef KRB5_CALLCONV_WRONG
#define KRB5_CALLCONV_WRONG
#endif

#ifndef THREEPARAMOPEN
#define THREEPARAMOPEN(x,y,z) open(x,y,z)
#endif

#define KRB5_OLD_CRYPTO

#include <stdlib.h>
#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       }
#else
#define KRB5INT_BEGIN_DECLS
#define KRB5INT_END_DECLS
#endif
#endif

KRB5INT_BEGIN_DECLS

#if TARGET_OS_MAC
#    pragma pack(push,2)
#endif

#if (__GNUC__ * 10000 + __GNUC_MINOR__ * 100 + __GNUC_PATCHLEVEL__) >= 30203
# define KRB5_ATTR_DEPRECATED __attribute__((deprecated))
#elif defined _WIN32
# define KRB5_ATTR_DEPRECATED __declspec(deprecated)
#else
# define KRB5_ATTR_DEPRECATED
#endif

/* from profile.h */
struct _profile_t;
/* typedef struct _profile_t *profile_t; */

/*
 * begin wordsize.h
 */

/*
 * Word-size related definition.
 */

typedef unsigned char   krb5_octet;

#if INT_MAX == 0x7fff
typedef int     krb5_int16;
typedef unsigned int    krb5_ui_2;
#elif SHRT_MAX == 0x7fff
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;
#elif LONG_MAX == 0x7fffffffL
typedef long    krb5_int32;
typedef unsigned long   krb5_ui_4;
#elif SHRT_MAX == 0x7fffffffL
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 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_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)

/*
 * end wordsize.h
 */

/*
 * begin "base-defs.h"
 */

/*
 * Basic definitions for Kerberos V5 library
 */

#ifndef FALSE
#define FALSE   0
#endif
#ifndef TRUE
#define TRUE    1
#endif

typedef unsigned int krb5_boolean;
typedef unsigned int krb5_msgtype;
typedef unsigned int krb5_kvno;

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_error_code krb5_magic;

typedef struct _krb5_data {
    krb5_magic magic;
    unsigned int length;
    char *data;
} krb5_data;

typedef struct _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....
 */
#define SALT_TYPE_AFS_LENGTH UINT_MAX
#define SALT_TYPE_NO_LENGTH  UINT_MAX

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_int32 length;
    krb5_int32 type;
} krb5_principal_data;

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
#define KRB5_NT_WELLKNOWN               11
/* First component of NT_WELLKNOWN principals */
#define KRB5_WELLKNOWN_NAMESTR          "WELLKNOWN"
/* 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: */
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)

/** Constant for realm referrals. */
#define        KRB5_REFERRAL_REALM      ""

/*
 * Referral-specific functions.
 */

/** Check for a match with KRB5_REFERRAL_REALM.
 *
 * @param [in] r  Realm to check
 *
 * @retval TRUE if @a r is zero-length; Otherwise - FALSE
 */
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 @c 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"
#define KRB5_ANONYMOUS_PRINCSTR "ANONYMOUS" /* wellknown name type */
/*
 * end "base-defs.h"
 */

/*
 * begin "hostaddr.h"
 */

/** structure for address */
typedef struct _krb5_address {
    krb5_magic magic;
    krb5_addrtype addrtype;
    unsigned int length;
    krb5_octet *contents;
} 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
/* not yet in the spec... */
#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)

/*
 * end "hostaddr.h"
 */


struct _krb5_context;
typedef struct _krb5_context * krb5_context;

struct _krb5_auth_context;
typedef struct _krb5_auth_context * krb5_auth_context;

struct _krb5_cryptosystem_entry;

/*
 * begin "encryption.h"
 */

/** Exposed contents of a key. */
typedef struct _krb5_keyblock {
    krb5_magic magic;
    krb5_enctype enctype;
    unsigned int length;
    krb5_octet *contents;
} krb5_keyblock;

/** Opaque identifier for a key.
 *
 * Use with the krb5_k APIs for better
 * performance for repeated operations with the same key usage.  Key
 * identifiers must not be used simultaneously within multiple
 * threads, as they may contain mutable internal state and are not
 * mutex-protected.
 */
struct krb5_key_st;
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_keyblock *key;
} krb5_encrypt_block;
#endif

typedef struct _krb5_checksum {
    krb5_magic magic;
    krb5_cksumtype checksum_type;       /* checksum type */
    unsigned int length;
    krb5_octet *contents;
} krb5_checksum;

typedef struct _krb5_enc_data {
    krb5_magic magic;
    krb5_enctype enctype;
    krb5_kvno kvno;
    krb5_data ciphertext;
} krb5_enc_data;

typedef struct _krb5_crypto_iov {
    krb5_cryptotype flags;
    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  /**< @deprecated DES cbc mode raw */
#define ENCTYPE_DES3_CBC_SHA    0x0005  /**< @deprecated DES-3 cbc mode with NIST-SHA */
#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
/* 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_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
 */

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*/
};

#ifndef krb5_roundup
/* round x up to nearest multiple of y */
#define krb5_roundup(x, y) ((((x) + (y) - 1)/(y))*(y))
#endif /* roundup */

/* macro function definitions to help clean up code */

#if 1
#define krb5_x(ptr,args) ((ptr)?((*(ptr)) args):(abort(),1))
#define krb5_xc(ptr,args) ((ptr)?((*(ptr)) args):(abort(),(char*)0))
#else
#define krb5_x(ptr,args) ((*(ptr)) args)
#define krb5_xc(ptr,args) ((*(ptr)) args)
#endif

 /**
 * @brief Encrypt data using a key.
 *
 * @param context                 Context structure [input, output]
 * @param key                     Key value from key table, ticket, etc. [input]
 * @param usage                   Key usage [input]
 * @param cipher_state            Cipher state [input]
 * @param input                   Data to be encrypted [input]
 * @param output                  Encrypted data [output]
 *
 * @retval
 *  0     Success
 * @retval
 * KRB5_BAD_ENCTYPE      Bad encryption type
 * @return
 * Kerberos error codes
 *
 * @sa enctype
 *
 */
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);

/**
 * @brief Decrypt data using a key.
 *
 * @param context           Context structure [input, output]
 * @param key               Key value from key table, ticket, etc. [input]
 * @param usage             Key usage [input]
 * @param cipher_state      Cipher state [input]
 * @param input             Encrypted data [input]
 * @param output            Decrypted data [output]
 *
 * @retval
 * 0 Success
 * @retval
 * KRB5_BAD_ENCTYPE      Bad encryption type
 * @return
 * Kerberos error codes
 *
 * @sa keyusage
 */

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);

/**
 * @brief Compute the length of the ciphertext produced by encrypting @a inputlen bytes.
 *
 * @param context               Context structure [input, output]
 * @param enctype               Encryption type [input]
 * @param inputlen              Length of encrypted data [input]
 * @param length                Length of unecrypted data [output]
 *
 * @retval
 * 0    Success
 * @retval
 * KRB5_BAD_ENCTYPE      Bad encryption type
 * @return
 * Kerberos error codes
 */

krb5_error_code KRB5_CALLCONV
krb5_c_encrypt_length(krb5_context context, krb5_enctype enctype,
                      size_t inputlen, size_t *length);

/**
 * @brief Write the block size for the specified encryption type into the @a size_t pointed to by @a blocksize.
 *
 * @param context         Context structure [input, output]
 * @param enctype         Encryption type [input]
 * @param blocksize       Attribute of encryption system [output]
 *
 * @retval
 *  0   Success
 * @retval
 *  KRB5_BAD_ENCTYPE         Bad encryption type
 * @retval
 *  ENOMEM                   Insufficient memory
 * @return
 * Kerberos error codes
 *
 * @sa enctype
 */
krb5_error_code KRB5_CALLCONV
krb5_c_block_size(krb5_context context, krb5_enctype enctype,
                  size_t *blocksize);

/**
 * @brief Write the length of the specified key to keylength.
 *
 * @param context              Context structure [input, output]
 * @param enctype              Encryption type [input]
 * @param keybytes             Number of bytes required to make a key [input]
 * @param keylength            Length of final key
 *
 * @retval
 *  0  Success
 * @return
 * Kerberos error codes
 */
krb5_error_code KRB5_CALLCONV
krb5_c_keylengths(krb5_context context, krb5_enctype enctype,
                  size_t *keybytes, size_t *keylength);

/**
 * @brief Initialize a new cipher state for @a enc_type in the specified @c _krb5_keyblock.
 *
 * @param context             Context structure [input, output]
 * @param key                 Key [input]
 * @param usage               Usage [input]
 * @param new_state           New cipher state [output]
 *
 * @note @a new_state contains the new cipher state.
 *
 * @retval
 *  0  Success
 * @return
 * 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);

/**
 * @brief  Free a cipher state previously allocated by krb5_c_init_state().
 *
 * @param context           Context structure [input, output]
 * @param key               Key [input]
 * @param state             Cipher state to be freed [input]
 *
 * @retval
 *  0  Success
 * @return
 * Kerberos error codes
 */

krb5_error_code KRB5_CALLCONV
krb5_c_free_state(krb5_context context, const krb5_keyblock *key,
                  krb5_data *state);

/**
 * @brief Generate pseudo-random bytes from @a input.
 *
 * @param context           Context structure [input, output]
 * @param keyblock          Key [input]
 * @param input             Input data [input]
 * @param output            Output data [output]
 *
 * @retval
 *  0  Success
 * @return
 * Kerberos error codes
 */

krb5_error_code KRB5_CALLCONV
krb5_c_prf(krb5_context context, const krb5_keyblock *keyblock, krb5_data *input, krb5_data *output);

/**
 * @brief Get the number of pseudo-random bytes output by krb5_c_prf() for the specified @a enctype.
 *
 * @param context           Context structure [input, output]
 * @param enctype           Encryption type [input]
 * @param len               Number of bytes for @a enctype [output]
 *
 * Make sure to free the allocated memory when it is no longer needed.
 *
 * @retval
 *  0  Success
 * @return
 * Kerberos error codes
 */

krb5_error_code KRB5_CALLCONV
krb5_c_prf_length(krb5_context context, krb5_enctype enctype, size_t *len);

/**
 * @return 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_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);

/**
 * @brief Create a key from @a random_key.
 *
 * @param context               Context structure [input, output]
 * @param enctype               Encryption type [input]
 * @param k5_random_key         Pointer to an allocated and initialized keyblock [output]
 *
 * The @a length field in @c _krb5_c_keylength ensures that @a random_key->contents points to an allocated buffer
 * of the correct length.
 *
 * Make sure to free the allocated memory when it is no longer needed.
 *
 * @retval
 *  0  Success
 * @retval
 *  KRB5_BAD_ENCTYPE         Bad encryption type
 * @retval
 *  ENOMEM                   Insufficient memory
 * @return
 * Kerberos error codes
 */

krb5_error_code KRB5_CALLCONV
krb5_c_make_random_key(krb5_context context, krb5_enctype enctype,
                       krb5_keyblock *k5_random_key);

/**
 * @param context               Context structure [input, output]
 * @param enctype               Encryption type [input]
 * @param random_data           Pointer to @c _krb5_data structure [input]
 * @param k5_random_key         Pointer to an allocated and initialized keyblock [output]
 *
 * @retval
 * 0  Success
 * @return
 * 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);

/**
 * @brief Add entropy to the pseudo-random number generator.
 *
 * @param context               Context structure [input, output]
 * @param randsource            Entropy source [input]
 * @param data                  Data [input, output]
 *
 * @note  This might cause the @c PRNG to be reseeded, although this is not guaranteed.
 *
 * @retval
 *  0  Success
 * @return
 * Kerberos error codes
 *
 * @sa randsource
 */
krb5_error_code KRB5_CALLCONV
krb5_c_random_add_entropy(krb5_context context, unsigned int randsource,
                          const krb5_data *data);

/**
 * @brief Generate pseudo-random bytes using entropy from OS.
 *
 * @param context           Context structure [input, output]
 * @param data              Random data [output]
 *
 * @a data->length specifies the number of bytes to generate and @a data->data points to an allocated buffer of the correct length.
 *
 * @retval
 *  0                            Success
 * @retval
 *  KRB5_CRYPTO_INTERNAL         Cryptosystem internal error
 * @return
 * Kerberos error codes
 */
krb5_error_code KRB5_CALLCONV
krb5_c_random_make_octets(krb5_context context, krb5_data *data);

/**
 * @brief Collect entropy from the OS if possible.
 *
 * @a strong requests that as strong
 * of a source of entropy  as available be used.  Setting @a 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.
 *
 * @param context            Context structure [input, output]
 * @param strong             Strongest available source of entropy [input]
 * @param success            1 if OS provides entropy, 0 if OS did not provide entropy [output]
 *
 * @note If @a strong is non-zero, this function attempts to use the strongest available source of entropy.
 *
 * @return
 *  If the OS provided and @a success is non-null,@a success is set to 1
 *
 * @return
 * Kerberos error codes
 */
krb5_error_code KRB5_CALLCONV
krb5_c_random_os_entropy(krb5_context context, int strong, int *success);

/** @deprecated Replaced by krb5_c_ API family. */
krb5_error_code KRB5_CALLCONV
krb5_c_random_seed(krb5_context context, krb5_data *data);

/**
 * @brief Convert the specified string to a key, using the specified encryption type, salt value, and parameters.
 *
 * @param context                       Context structure [input, output]
 * @param enctype                       Encryption type [input]
 * @param string                        String to be converted [input]
 * @param salt                          Salt value [input]
 * @param key                           Generated key [output]
 *
 * @retval
 *  0    Success
 * @retval
 *  KRB5_BAD_ENCTYPE                Bad encryption type
 *  @retval
 *  KRB5_CRYPTO_INTERNAL            Cryptosystem internal error
 *  @retval
 * ENOMEM                          Insufficient memory
 * @return
 * Kerberos error codes
 *
 * @sa enctype
 * @sa salt
 */
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);

/**
 * @brief  Convert a string representation of a key into a @c _krb5_keyblock structure using a specified group of parameters.
 *
 * @param context           Context structure [input, output]
 * @param enctype           Encryption type [input]
 * @param string            String form of the key [input]
 * @param salt              Salt value used in the encryption [input]
 * @param params            Parameters to be used for this conversion [input]
 * @param key               Keyblock [output]
 *
 * @retval
 * 0 Success
 * @retval
 *  KRB5_BAD_ENCTYPE Bad encryption type
 * @retval
 *  KRB5_CRYPTO_INTERNAL Cryptosystem internal error
 * @retval
 *  ENOMEM Insufficient memory
 * @return
 * Kerberos error codes
 *
 * @sa enctype
 * @sa salt
 */
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);

/**
 * @brief Compare two encryption types.
 *
 * @param context            Context structure [input, output]
 * @param e1                 First encryption type [input]
 * @param e2                 Second encryption type [input]
 * @param similar            @c TRUE if types are similar, @c FALSE if types are different [output]
 *
 * @retval
 * TRUE  @a enctypes are similar
 * @retval
 * FALSE @a enctypes are different
 * @retval
 * KRB5_BAD_ENCTYPE     Bad encryption type
 * @return
 * Kerberos error codes
 *
 * @sa enctype
 */
krb5_error_code KRB5_CALLCONV
krb5_c_enctype_compare(krb5_context context, krb5_enctype e1, krb5_enctype e2,
                       krb5_boolean *similar);

/**
 * @brief Compute a checksum.
 *
 * @param context                  Context structure [input, output]
 * @param cksumtype                Checksum type [input]
 * @param key                      Encryption key [input]
 * @param usage                    Usage [input]
 * @param input                    Input data [input]
 * @param cksum                    Checksum [output]
 *
 * @retval
 * 0 Success
 * @retval
 *  KRB5_BAD_ENCTYPE Bad encryption type
 * @retval
 *  ENOMEM Insufficient memory
 * @return
 * Kerberos error codes
 *
 * @sa cksumtype
 */
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);

/**
 * @brief Verify the checksum of data in @a cksum that was created with a @a key using the specified key usage.
 *
 * @param context              Context structure [input, output]
 * @param key                  Encryption key [input]
 * @param usage                Usage [input]
 * @param data                 Data [input]
 * @param cksum                Checksum to be verified [input]
 * @param valid                Non-zero for success, zero for failure [output]
 *
 * @retval
 * Non-zero Success
 * @retval
 *  0  Failure
 * @retval
 *  KRB5_BAD_ENCTYPE    Bad encryption type
 * @retval
 *  KRB5_BAD_MSIZE      Message size is incompatible with encryption type
 * @return
 * Kerberos error codes
 *
 * @sa keyusage
 */
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);

/**
 * @brief Output the checksum length produced by the specified checksum type.
 *
 * @param context               Context structure [input, output]
 * @param cksumtype             Checksum type [input]
 * @param length                Checksum length [output]
 *
 * @retval
 *  0                    Success
 * @retval
 *  KRB5_BAD_ENCTYPE      Bad encryption type
 * @return
 * Kerberos error codes
 *
 * @sa cksumtype
 */
krb5_error_code KRB5_CALLCONV
krb5_c_checksum_length(krb5_context context, krb5_cksumtype cksumtype,
                       size_t *length);

/**
 * @brief Get list of checksum types that match a specified encryption type.
 *
 * @param context           Context structure [input, output]
 * @param enctype           Encryption type [input]
 * @param count             Count of checksums matching the encryption type [output]
 * @param cksumtypes        List of matching checksums [output]
 *
 * This returns only the checksum types that use key derivation.
 *
 * Make sure to free the allocated memory when it is no longer needed.
 *
 * @retval
 *  0   Success
 * @retval
 *  ENOMEM Insufficient memory
 * @return
 * Kerberos error codes
 *
 * @sa enctype
 * @sa cksumtype
 */
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

/* 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

/* 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

/* Defined in KDC referrals draft */
/**
 * @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_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_REP 52
#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

/**
 * @brief Verify that the specified encryption type is a valid Kerberos encryption type.
 *
 * @param ktype           Encryption type [input]
 *
 * @retval
 *  0 invalid
 * @retval
 *  1  valid
 *
 * @sa enctype
 */
krb5_boolean KRB5_CALLCONV
krb5_c_valid_enctype(krb5_enctype ktype);

/**
 * @brief Verify that specified checksum type is a valid Kerberos checksum type.
 *
 * @param ctype                        Checksum type [input]
 *
 * @retval
 *  0 invalid
 * @retval
 *  1  valid
 *
 * @sa cksumtype
 */
krb5_boolean KRB5_CALLCONV
krb5_c_valid_cksumtype(krb5_cksumtype ctype);

/**
 * @brief Test whether a checksum type is collision-proof.
 *
 * @param ctype                        Checksum type [input]
 *
 * @retval
 *   0 Not collision-proof, or checksum type is not in the list
 * @retval
 * 1  Success
 */
krb5_boolean KRB5_CALLCONV
krb5_c_is_coll_proof_cksum(krb5_cksumtype ctype);

/**
 * @brief Test whether a checksum type is keyed.
 *
 * @param ctype                    Checksum type [input]
 *
 * @retval
 *  0       Checksum does not use derived keys, or checksum type is not in the list
 * @retval
 *  1       Checksum uses derived keys
 */
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 */

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);

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);

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);

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_error_code KRB5_CALLCONV
krb5_c_crypto_length(krb5_context context, krb5_enctype enctype,
                     krb5_cryptotype type, unsigned int *size);

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_error_code KRB5_CALLCONV
krb5_c_padding_length(krb5_context context, krb5_enctype enctype,
                      size_t data_length, unsigned int *size);

krb5_error_code KRB5_CALLCONV
krb5_k_create_key(krb5_context context, const krb5_keyblock *key_data,
                  krb5_key *out);

/**
 * Keys are logically immutable and can be "copied" by reference count.
 */
void KRB5_CALLCONV
krb5_k_reference_key(krb5_context context, krb5_key key);

/**
 * @brief 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);

/** 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);

/** Retrieve the enctype of a krb5_key structure.  */

krb5_enctype KRB5_CALLCONV
krb5_k_key_enctype(krb5_context context, krb5_key key);

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);

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);

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);

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);

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);

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);

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);

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);

krb5_error_code KRB5_CALLCONV
krb5_k_prf(krb5_context context, krb5_key key, krb5_data *in, krb5_data *out);

#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 */
/* 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

/* 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) /**< 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 */

/* 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_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 */
#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_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 */

/** Transited encoding types */
#define KRB5_DOMAIN_X500_COMPRESS               1

/** alternate authentication types */
#define KRB5_ALTAUTH_ATT_CHALLENGE_RESPONSE     64

/* authorization data types */
#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_SIGNTICKET        512     /**< formerly 142 in krb5 1.8 */
#define KRB5_AUTHDATA_FX_ARMOR 71

/* password change constants */
#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
/* 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 */

/*
 * end "proto.h"
 */

/* Time set */
/** Ticket start time, end time, and renewal duration. */
typedef struct _krb5_ticket_times {
    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 */
typedef struct _krb5_authdata {
    krb5_magic magic;
    krb5_authdatatype ad_type; /**< ADTYPE */
    unsigned int length;       /**< Length of data  */
    krb5_octet *contents;      /**< Data */
} krb5_authdata;

/** Structure for transited encoding */
typedef struct _krb5_transited {
    krb5_magic magic;
    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_enc_tkt_part;

/**
 * Ticket structure.
 *
 * Ticket structure that holds the C representation of the ticket protocol
 * message and a pointer to the representation of @c _krb5_enc_tkt_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_ticket;

/* the unencrypted version */
/**
 * Ticket authenticator.
 *
 * Ticket authenticator: the @c c representation of @c AP-REQ message with decrypted 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_authenticator;

/*
 * Ticket authentication data.
 */
typedef struct _krb5_tkt_authent {
    krb5_magic magic;
    krb5_ticket *ticket;
    krb5_authenticator *authenticator;
    krb5_flags ap_options;
} krb5_tkt_authent;

/** 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_creds;

/** Last request entry */
typedef struct _krb5_last_req_entry {
    krb5_magic magic;
    krb5_int32 lr_type;   /**< LR type */
    krb5_timestamp value;  /**< Timestamp */
} krb5_last_req_entry;

/** Pre-authentication data */
typedef struct _krb5_pa_data {
    krb5_magic magic;
    krb5_preauthtype  pa_type; /**< Preauthentication data type */
    unsigned int length;       /**< Length of data   */
    krb5_octet *contents;       /**< Data   */
} krb5_pa_data;

/** Typed data.
 *
 * The FAST error handling logic currently assumes that this structure and
 * krb5_pa_data * can be safely cast to each other if this structure changes,
 * that code needs to be updated to copy.
 */
typedef struct _krb5_typed_data {
    krb5_magic magic;
    krb5_int32  type;
    unsigned int length;
    krb5_octet *data;
} krb5_typed_data;

/** Representation of KDC-REQ protocol message. */
typedef struct _krb5_kdc_req {
    krb5_magic magic;
    krb5_msgtype msg_type;              /**< krb5_kdc_req AS_REQ or TGS_REQ? */
    krb5_pa_data **padata;              /**< krb5_kdc_req e.g. encoded AP_REQ */
    /* 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_kdc_req;

/** 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_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_kdc_rep;

/** 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_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_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;             /**< 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_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_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_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_cred_info **ticket_info;
} 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_cred;

/*
 * Sandia password generation structure
 * Used by internal functions only
 */
typedef struct _passwd_phrase_element {
    krb5_magic magic;
    krb5_data *passwd;
    krb5_data *phrase;
} passwd_phrase_element;

/*
 * Password data.
 * Used by internal functions only
 */
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.
 */
typedef struct _krb5_pa_svr_referral_data {
    /** Referred name, only realm is required */
    krb5_principal     principal;
} krb5_pa_svr_referral_data;

typedef struct _krb5_pa_server_referral_data {
    krb5_data          *referred_realm;
    krb5_principal     true_principal_name;
    krb5_principal     requested_principal_name;
    krb5_timestamp     referral_valid_until;
    krb5_checksum      rep_cksum;
} krb5_pa_server_referral_data;

typedef struct _krb5_pa_pac_req {
    /** 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 /**< set timestamp in the message */
#define KRB5_AUTH_CONTEXT_RET_TIME      0x00000002
#define KRB5_AUTH_CONTEXT_DO_SEQUENCE   0x00000004 /**< set sequence number in the message */
#define KRB5_AUTH_CONTEXT_RET_SEQUENCE  0x00000008
#define KRB5_AUTH_CONTEXT_PERMIT_ALL    0x00000010
#define KRB5_AUTH_CONTEXT_USE_SUBKEY    0x00000020

/** Replay data.
 *
 * Sequence number and timestamp information output by krb5_read_priv() and
 * krb5_read_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 /**< Generate the local network address  */
#define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR      0x00000002 /**< Generate the remote network address.  */
#define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR  0x00000004 /**< Generate the local network address and the local port.  */
#define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR 0x00000008 /**< Generate the remote network address and the remote port  */

/* 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 */

struct _krb5_ccache;
typedef struct _krb5_ccache *krb5_ccache;
struct _krb5_cc_ops;
typedef struct _krb5_cc_ops krb5_cc_ops;

/**
 * @brief Cursor for iterating over all ccaches
 */
struct _krb5_cccol_cursor;
typedef struct _krb5_cccol_cursor *krb5_cccol_cursor;

/* for retrieve_cred */
#define KRB5_TC_MATCH_TIMES        0x00000001 /**< The requested lifetime must be
                                                   at least as great as that specified */
#define KRB5_TC_MATCH_IS_SKEY      0x00000002 /**< The is_skey field must match exactly */
#define KRB5_TC_MATCH_FLAGS        0x00000004 /**< All the flags set in the match credentials
                                                   must be set in the cache credentials */
#define KRB5_TC_MATCH_TIMES_EXACT  0x00000008 /**< All the time fields must match exactly */
#define KRB5_TC_MATCH_FLAGS_EXACT  0x00000010 /**< All the flags must match exactly */
#define KRB5_TC_MATCH_AUTHDATA     0x00000020 /**< The authorization data must match */
#define KRB5_TC_MATCH_SRV_NAMEONLY 0x00000040 /**< Only the name portion
                                                   of the principal name must match */
#define KRB5_TC_MATCH_2ND_TKT      0x00000080 /**< The second ticket must match */
#define KRB5_TC_MATCH_KTYPE        0x00000100 /**< The encryption key type must match */
#define KRB5_TC_SUPPORTED_KTYPES   0x00000200 /**< The supported key types must match */

/* for set_flags and other functions */
#define KRB5_TC_OPENCLOSE          0x00000001 /**< Open and close the cache each time a
                                                   credentials cache routine is called */
#define KRB5_TC_NOTICKET           0x00000002

/** Retrieve the name but not type of a credential cache.
 *
 * @param [in] context          Context structure
 * @param [in] cache            Credentials cache handle
 *
 * @warning Returns the name of the credential cache as an alias that
 * should not be freed or modified by the caller.  This name does not
 * include the type portion, so cannot 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);

#if KRB5_DEPRECATED
/** Generate a new handle for a specified (unopened) credentials cache.
 *
 * @param [in]  context           Context structure
 * @param [in,out] cache          Credentials cache handle
 *
 * @deprecated Replaced by krb5_cc_new_unique()
 *
 * This function generate a new credential chache whose name is guaranteed to be unique.
 *
 * @note In the case the credential file, the cache stays unopen, but the new filename is reserved.
 *
 * @retval 0  Success; Otherwise - Kerberos error codes
 */
krb5_error_code KRB5_CALLCONV
krb5_cc_gen_new(krb5_context context, krb5_ccache *cache);
#endif /* KRB5_DEPRECATED */

/** Initialize credentials cache.
 *
 * @param [in] context       Context structure
 * @param [in] cache         Credentials cache handle
 * @param [in] principal     Default principal name for the credentials cache
 *
 * Destroy an existing credentials cache and create a new credentials cache
 * by the same name, as specifed by @a cache for specified @a principal.
 *
 * @note This function also modifies the specified credentials cache.
 *
 * @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);

/** Destroy a credentials cache.
 *
 * @param [in] context          Context structure
 * @param [in] cache            Credentials cache handle
 *
 * This function closes and deletes @a cache and releases any other resources
 * acquired during use of the credentials cache.
 * @a cache must identify a valid credentials cache.
 *
 * @note After completion, @a cache may not be used. It may be reinitialized
 * with krb5_cc_resolve() or krb5_cc_gen_new().
 *
 * @retval
 * 0  Success
 * @return
 * Permission errors
 */
krb5_error_code KRB5_CALLCONV
krb5_cc_destroy(krb5_context context, krb5_ccache cache);

/** Close a credentials cache and invalidate its handle.
 *
 * @param [in] context                Context structure
 * @param [in] cache                  Credentials cache handle
 *
 * @a cache may be reinitialized with krb5_cc_resolve() or krb5_cc_gen_new().
 *
 * @sa KRB5_TC_OPENCLOSE flag
 *
 * @retval
 * 0  Success
 * @return
 * Kerberos error codes
 */
krb5_error_code KRB5_CALLCONV
krb5_cc_close(krb5_context context, krb5_ccache cache);

/** Store credentials in a specified credentials cache.
 *
 * @param [in]     context            Context structure
 * @param [in,out] cache              Credentials 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, both principals will be stored.
 *
 * @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);

/** Retrieve a specified credentials from a credentials cache.
 *
 * @param [in]  context  Context structure
 * @param [in]  cache    Credentials cache handle
 * @param [in]  flags    Flags bit mask
 * @param [in]  mcreds   Credentials to match
 * @param [out] creds    Credentials that match the requested value
 *
 * This function searches a credentials cache for credentials matching @a mcreds
 * and returns it if found.
 *
 * Valid values for @a flags are:
 *
 * @li @c KRB5_TC_MATCH_TIMES        The requested lifetime must be
 *                                   at least as great as that specified.
 * @li @c KRB5_TC_MATCH_IS_SKEY      The @a is_skey field much match exactly.
 * @li @c KRB5_TC_MATCH_FLAGS        The flags in @a mcreds and @a creds must match
 * @li @c KRB5_TC_MATCH_TIMES_EXACT  The requested lifetime must match exactly.
 * @li @c KRB5_TC_MATCH_FLAGS_EXACT  Flags in @a mcreds and @a creds must match exactly.
 * @li @c KRB5_TC_MATCH_AUTHDATA     The authorization data must match.
 * @li @c KRB5_TC_MATCH_SRV_NAMEONLY Only the name portion of the principal name must
 *                                   match. The realm field can be different.
 *                                   If this flag is not set, the entire principal
 *                                   name must match.
 * @li @c KRB5_TC_MATCH_2ND_TKT      The second tickets must match.
 * @li @c KRB5_TC_MATCH_KTYPE        The encryption key types must match.
 * @li @c KRB5_TC_MATCH_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);

/** Get the primary principal of a credentials cache.
 *
 * @param [in]  context            Context structure
 * @param [in]  cache              Credentials cache handle
 * @param [out] principal          Primary principal
 *
 * @note The primary principal is set by calling 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);

/** Prepare to sequentially read every credential in a credentials cache.
 *
 * @param [in]  context           Context structure
 * @param [in]  cache             Credentials cache handle
 * @param [out] cursor            Cursor
 *
 * krb5_cc_end_seq_get() must be called to complete the retreive operation.
 *
 * @note If @a cache was 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);

/** Retrieve the next entry from the credentials cache.
 *
 * @param [in]     context           Context structure
 * @param [in]     cache             Credentials cache handle
 * @param [in,out] cursor            Cursor
 * @param [out]    creds             Credentials cache entry corresponding to the cursor
 *
 * @note The cursor value is updated upon successful completion of this function.
 * Subsequent calls to krb5_cc_next_cred() use the updated value.
 *
 * 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);

/** Finish a series of sequential processing credentials cache entries.
 *
 * @param [in]     context           Context structure
 * @param [in]     cache             Credentials cache handle
 * @param [in,out] cursor            Cursor that was created by krb5_cc_start_seq_get()
 *
 * This function finishes processing credentials cache entries and invalidates @a cursor.
 *
 * @sa 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);

/** Remove credentials from a credentials cache.
 *
 * @param [in] context               Context structure
 * @param [in] cache                 Credentials cache handle
 * @param [in] flags                 Bitwise-ORed search flags
 * @param [in] creds                 Credentials to be matched
 *
 * @warning  This function is not implemented on UNIX'es. Returns KRB5_CC_NOSUPP.
 *
 * Valid values for search flags are:
 * @li @c KRB5_TC_MATCH_TIMES         The requested lifetime is required to be at least
 *                                    as great as that specified.
 * @li @c KRB5_TC_MATCH_IS_SKEY       The @a is_skey field much match exactly.
 * @li @c KRB5_TC_MATCH_FLAGS         The set bits in @a mcreds must match in @a creds.
 * @li @c KRB5_TC_MATCH_TIMES_EXACT   The requested lifetime must match exactly.
 * @li @c KRB5_TC_MATCH_FLAGS_EXACT   All bits in @a mcreds must match exactly.
 * @li @c KRB5_TC_MATCH_AUTHDATA      The authentication data must match.
 * @li @c KRB5_TC_MATCH_SRV_NAMEONLY  Only the name portion of the principal name must match.
 *                                    The realm field can be different. By default,
 *                                    the entire principal name must match.
 * @li @c KRB5_TC_MATCH_2ND_TKT       The second tickets must match.
 * @li @c KRB5_TC_MATCH_KTYPE         The encryption key types must match.
 * @li @c KRB5_TC_MATCH_SUPPORTED_KTYPES   Check all matching entries that have
 *                                         any supported encryption 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);

/** Set options flags on a credentials cache.
 *
 * @param [in]     context   Context structure
 * @param [in,out] cache     Credentials 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);

/** Retrieve flags from a credentials cache structure.
 *
 * @param [in]  context          Context structure
 * @param [in]  cache            Credentials cache handle returned by
 *                               krb5_cc_resolve() or krb5_cc_generate_new()
 * @param [out] flags            Flag bit mask
 *
 * @warning For memory credential cache always returns KRB5_OK.
 *
 * @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);

/** Retrieve the type of a credential cache.
 *
 * @param [in] context           Context structure
 * @param [in] cache             Credentials cache handle
 *
 * @return The type of a credential cache as an alias that should not be
 * modified or freed by the caller.
 */
const char * KRB5_CALLCONV
krb5_cc_get_type(krb5_context context, krb5_ccache cache);

/** Move a credential cache.
 *
 * @param [in] context       Context structure
 * @param [in] src           The credential cache to move the content from
 * @param [in] dst           The credential cache to move the content to
 *
 * This function re-initializes @a dst and populates it with the credentials
 * and default principal of @a src, and then, if successful, destroys @a src.
 *
 * krb5_ccache objects are locked internally, so no data corruption
 * will result if this routine is called on the same credential caches
 * in multiple threads.
 *
 * @retval
 * 0 Sucess; @a src is freed.
 * @return
 * Kerberos error codes; @a src is still allocated, while @a dst is freed.
 */
krb5_error_code KRB5_CALLCONV
krb5_cc_move(krb5_context context, krb5_ccache src, krb5_ccache dst);

/** Return a timestamp of the last modification of the credentials cache.
 *
 * @param [in]  context            Context structure
 * @param [in]  ccache             Credentials 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_error_code KRB5_CALLCONV
krb5_cc_lock(krb5_context context, krb5_ccache ccache);

krb5_error_code KRB5_CALLCONV
krb5_cc_unlock(krb5_context context, krb5_ccache ccache);

/** Prepare to iterate over a collection of credentials caches.
 *
 * @param [in]     context           Context structure
 * @param [in,out] cursor            Cursor
 *
 * Get a new cache iteration @a cursor that will iterate over all
 * credentials 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);

/** Get the next credentials cache in the collection.
 *
 * @param [in]     context           Context structure
 * @param [in,out] cursor            Cursor
 * @param [out]    ccache            Credentials 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 credentials cache collection cursor.
 *
 * @param [in] context           Context structure
 * @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 for the cache collection.
 *
 * @param [in]  context            Context structure
 * @param [out] change_time        Last modification timestamp
 *
 * This function will go through the whole list of the credentials caches.
 * If the last modification time is successfully retrieved for the credentials
 * in the collection, it will be evaluated for being the most recent timestamp.
 * Otherwise, that particular cache will be ignored.
 *
 * If there are no credentials in the 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);

krb5_error_code KRB5_CALLCONV
krb5_cccol_lock(krb5_context context);

krb5_error_code KRB5_CALLCONV
krb5_cccol_unlock(krb5_context context);

/** Create a new unique credentials cache of the specified type.
 *
 * @param [in]  context           Context structure
 * @param [in]  type              Credentials cache type name
 * @param [in]  hint              Unused
 * @param [out] id                Credentials 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);

/*
 * end "ccache.h"
 */

/*
 * begin "rcache.h"
 */

struct krb5_rc_st;
typedef struct krb5_rc_st *krb5_rcache;

/*
 * end "rcache.h"
 */

/*
 * begin "keytab.h"
 */


/* XXX */
#define MAX_KEYTAB_NAME_LEN 1100 /* Long enough for MAXPATHLEN + some extra */

typedef krb5_pointer krb5_kt_cursor;    /* XXX */

/** 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_keytab_entry;

struct _krb5_kt;
typedef struct _krb5_kt *krb5_keytab;

/** Return a type of a key table.
 *
 * @param [in] context           Context structure
 * @param [in] keytab            Type of key table handle
 *
 * The possible results might be  "FILE", "MEMORY" etc
 *
 * @warning The returned value must not be freed by the caller.
 *
 * @return
 * The key table prefix string.
 */
const char * KRB5_CALLCONV
krb5_kt_get_type(krb5_context context, krb5_keytab keytab);

/** Get a key table name
 *
 * @param [in]  context           Context structure
 * @param [in]  keytab            Key table handle
 * @param [out] name              Key table name
 * @param [in]  namelen           Maximum length to fill in name
 *
 * Zeroes @a name and then copies the key table name including
 * its prefix and trailing delimeter.
 *
 * @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);

/** Close a key table.
 *
 * @param [in] context           Context structure
 * @param [in] keytab            Key table handle
 *
 * Close a key table, invalidate its handle, and release any other resources
 * acquired during use of the key table.
 * Undo anything done by krb5_kt_resolve().
 *
 * @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       Context structure
 * @param [in]  keytab        Key table handle
 * @param [in]  principal     Principal name
 * @param [in]  vno           Key version number
 * @param [in]  enctype       Encryption type. Use zero for any enctype.
 * @param [out] entry         Returned entry from key table
 *
 * Retrieve an entry from a key table that matches the @a keytab, @a principal,
 * and @a vno.
 * The @a entry must be freed with krb5_kt_free_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);

/** Start a sequential retrieve of key table entries.
 *
 * @param [in]  context           Context structure
 * @param [in]  keytab            Key table handle
 * @param [out] cursor            Cursor
 *
 * Prepare to read sequentially every key in the specified key table.
 * @a cursor is incremented for next call to krb5_kt_next_entry().
 * The function krb5_kt_end_seq_get() should be called to release the cursor.
 *
 * @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);

/** Retrieve the next entry from the key table.
 *
 * @param [in]  context           Context structure
 * @param [in]  keytab            Key table handle
 * @param [out] entry             Returned key table entry
 * @param [in,out] cursor         The cursor created by krb5_kt_start_seq_get()
 *                                and updated by successful runs of this routine
 *
 * Return the next sequential entry in the specified key table and update @a cursor for
 * the next request.
 * If the key table changes during the sequential get, an error is guaranteed.
 *
 * @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);

/** Complete a series of sequential key table entry retrievals and invalidate @a cursor.
 *
 * @param [in]  context           Context structure
 * @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);

/*
 * end "keytab.h"
 */

/*
 * begin "func-proto.h"
 */

/** Create and intialize a krb5_context structure.
 *
 * @param [out] context           Context structure
 *
 * 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);

/** Create and initialize a krb5_context structure using only configuration files.
 *
 * @param [out] context           Context structure
 *
 * Initialize a context structure, using only configuration files that
 * are safe for a @c setuid program.
 * 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);

/** Free a krb5_context structure.
 *
 * @param [in] context           Context structure
 *
 * 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           Context structure
 * @param [out] nctx_out      New "cloned" 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_copy_context(krb5_context ctx, krb5_context *nctx_out);

/** Set default TGS encryption types in a krb5_context structure.
 *
 * @param [in,out] context              Context structure
 * @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);

/** Return a list of supported encryption types.
 *
 * @param [in]  context           Context structure
 * @param [out] ktypes            Zero-terminated list of encryption types
 *
 * This function returns the content of  @a context->tgs_etypes if it is non-NULL.
 * Otherwise, the libdefaults profile string of permitted_enctypes, if it exists.
 * Otherwise, the default enctype list that is defined as follows:
 *     ENCTYPE_AES256_CTS_HMAC_SHA1_96, ENCTYPE_AES128_CTS_HMAC_SHA1_96,
 *     ENCTYPE_DES3_CBC_SHA1, ENCTYPE_ARCFOUR_HMAC,
 *     ENCTYPE_DES_CBC_CRC, ENCTYPE_DES_CBC_MD5, ENCTYPE_DES_CBC_MD4.
 *
 * Use krb5_free_ktypes() to free @a ktypes when it is no longer needed.
 *
 * @retval 0 Success; Otherwise - Kerberos error codes
 */
krb5_error_code KRB5_CALLCONV
krb5_get_permitted_enctypes(krb5_context context, krb5_enctype **ktypes);

/** 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);

/* libkrb.spec */

/** Decrypt a ticket using the specified key table.
 *
 * @param [in]     context           Context structure
 * @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 the
 * provided 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 the storage assigned to array of credentials.
 *
 * @param [in] context           Context structure
 * @param [in] tgts              Array of credentials to be freed
 *
 * @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);

#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 */

/** Get an additional ticket.
 *
 * @param [in]     context       Context structure
 * @param [in]     options       Options
 * @param [in,out] ccache        Credentials cache handle
 * @param [in]     in_creds      Input credentials
 * @param [out]    out_creds     Output updated credentials
 *
 * Use the specified credentials cache or a TGS exchange to get an additional
 * ticket for the client identified by @a in_creds->client.
 *
 * Valid values for @a options are:
 * @li @c KRB5_GC_CACHED   Search only credentials cache for the ticket
 * @li @c KRB5_GC_USER_USER   Return a full 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 special  data needs to be included in the ticket (such as restrictions
 * on how the ticket can be used), specify it in @a in_creds->authdata.
 * If there is no special data to be passed, set @a in_creds->authdata to NULL.
 * The session key type is specified in @a in_creds->keyblock.keytype,
 * 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);

/**
 * @brief Contact the KDC to validate a credential.
 *
 * @param context             Context structure [input, output]
 * @param options             Unused
 * @param ccache              Credentials cache handle [input, output]
 * @param in_creds            Input credentials [input]
 * @param out_creds           Output credentials [output]
 *
 * Make sure to free the allocated memory when it is no longer needed.
 * @retval
 *  0  Success
 * @retval
 *  ENOMEM Insufficient memory
 * @retval
 *  KRB5_PROG_ETYPE_NOSUPP Encryption type is not supported
 * @retval
 *  KRB5_KDCREP_MODIFIED KDC reply did not match expectations
 * @return
 *  Kerberos error codes
 *
 */
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);

/**
 * @brief Contact the KDC to renew credentials for a context.
 *
 * @param context           Context structure [input, output]
 * @param options           Unused
 * @param ccache            Credentials cache handle [input, output]
 * @param in_creds          Input credentials [input]
 * @param out_creds         Output credentials [output]
 *
 * Make sure to free the allocated memory when it is no longer needed.
 *
 * @retval
 *  0  Success
 * @retval
 *  ENOMEM Insufficient memory
 * @retval
 *  KRB5_PROG_ETYPE_NOSUPP Encryption type is not supported
 * @retval
 *  KRB5_KDCREP_MODIFIED KDC reply did not match expectations
 * @return
 *  Kerberos error codes
 *
 */
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);

/** Format a @c KRB_AP_REQ message.
 *
 * @param [in]     context        Context structure
 * @param [in,out] auth_context   Authentication context, containing the checksum
 *                                method to be used; a new authentication
 *                                context is returned if NULL is specified.
 * @param [in]     ap_req_options AP_OPTS_ options
 * @param [in]     service        Service name, or NULL to use string @c host
 * @param [in]     hostname       Host name, or NULL to use local host
 * @param [in]     in_data        Application data's checksum to be
 *                                included in the authenticator; specify NULL
 *                                if no checksum is to be included
 * @param [in]     ccache         Credentials cache that is to be used to obtain
 *                                credentials to the desired service.
 * @param [out]    outbuf         @c AP-REQ message
 *
 * Valid @a ap_req_options are:
 * @li @c AP_OPTS_USE_SESSION_KEY - Use the session key when creating the
 *                                  request used for user to user authentication.
 * @li @c AP_OPTS_MUTUAL_REQUIRED - Request a mutual authentication packet from
 *                                  the reciever.
 * @li @c AP_OPTS_USE_SUBKEY      - Generate a subsession key from the current
 *                                  session key obtained from the credentials.

 * This function is similar to krb5_mk_req_extended() except that it
 * uses a given @a hostname, @a service and @a ccache to construct 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);

/** Format a @c KRB_AP_REQ message using supplied credentials.
 *
 * @param [in]     context        Context structure
 * @param [in,out] auth_context   Authentication context, containing the checksum
 *                                method to be used; a new authentication
 *                                context is returned if NULL is specified.
 * @param [in]     ap_req_options AP_OPTS_ options
 * @param [in]     in_data        Application data's checksum to be
 *                                included in the authenticator; specify NULL
 *                                if no checksum is to be included
 * @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 @c AP_OPTS_USE_SESSION_KEY - Use the session key when creating the
 *                                  request used for user to user authentication.
 * @li @c AP_OPTS_MUTUAL_REQUIRED - Request a mutual authentication packet from
 *                                  the reciever.
 * @li @c 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. The checksum @a in_data is included in the authenticator that
 * is part of the KRB_AP_REQ message.
 * Use krb5_free_data_contents() to free @a outbuf when it is no longer needed.
 *
 * @note A newly generated authenticator is stored in @a auth_context with the
 * @a client and @a checksum fields nulled out, unless an error is returned.
 * (This is to prevent pointer-sharing problems; the caller should not need
 * these fields anyway, since the caller supplied them.)
 * The old @a auth_context->key is overwritten by keyblock from @a in_creds.
 *
 * @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);

/** Format and encrypt a @c KRB_AP_REP message.
 *
 * @param [in]     context           Context structure
 * @param [in,out] auth_context      Authentication context
 * @param [out]    outbuf            @c AP-REP message
 *
 * The @c AP-REP message includes the data in the @a authentp field of @a
 * auth_context, and it is encrypted using the @a key field from @a auth_context.
 *
 * When successful, @a outbuf->length and @a outbuf->data are filled in with the
 * length of the @c AP-REQ message and the allocated data holding it.
 *
 * If the flags in @a auth_context indicate that a sequence number should be used
 * (either @c KRB5_AUTH_CONTEXT_DO_SEQUENCE or @c 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);

/** Format and encrypt a @c KRB_AP_REP message for DCE RPC.
 *
 * @param [in]     context           Context structure
 * @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);

/**
 * @brief Parse and decrypt a @c KRB5_AP_REP message.
 *
 * @param context            Context structure [input, output]
 * @param auth_context       Authentication context [input, output]
 * @param inbuf              AP-REP message [input]
 * @param repl               Parsed message [output]
 *
 * The keyblock stored in @c _krb5_auth_context is used to decrypt the message
 * after establishing any key preprocessing with krb5_process_key().
 *
 * Make sure to free the allocated memory when it is no longer needed.
 *
 * @retval
 * 0 Success
 * @return
 * 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
krb5_rd_rep_dce(krb5_context context, krb5_auth_context auth_context,
                const krb5_data *inbuf, krb5_ui_4 *nonce);

/** Format and encode a @c KRB_ERROR message.
 *
 * @param [in]  context           Context structure
 * @param [in]  dec_err           Error structure to be encoded
 * @param [out] enc_err           Encoded error structure
 *
 * This function creates a @c KRB_ERROR message @a enc_err suitable to be
 * sent to the remote partner instead of sending a reply message.
 * Use krb5_free_data_contents() for 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);

/**
 * @brief Decode a @c KRB-ERROR message.
 *
 * @param context           Context structure [input, output]
 * @param enc_errbuf        Encoded error message [input]
 * @param dec_error         Decoded error message [output]
 *
 * @retval
 * 0 Success
 * @return
 * Kerberos error codes
 *
 */
krb5_error_code KRB5_CALLCONV
krb5_rd_error(krb5_context context, const krb5_data *enc_errbuf,
              krb5_error **dec_error);

/**
 * @brief Parse a @c KRB-SAFE message, verify its integrity, and store its data in the specified buffer.
 *
 * @param context           Context structure [input, output]
 * @param auth_context      Authentication structure [input, output]
 * @param inbuf             @c KRB-SAFE message to be parsed [input]
 * @param outbuf            Data parsed from @c KRB-SAFE message [output]
 * @param outdata           Sequence numbers if @c krb5_auth_context includes @c KRB5_AUTHCONTEXT_RET_SEQUENCE [input, output]
 *
 * The keyblock used to verify the integrity of the message is taken from the fields
 * @a local_subkey, @a remote_subkey, or @a keyblock in @c _krb5_auth_context. The @a keyblock
 * is chosen in the preceding order by the first one that is non-null.
 *
 * @a remote_addr and @a localaddr in @c _krb5_auth_context specify
 * the full addresses (host and port) of the sender and receiver, and must be of
 * type @c ADDRTYPE_ADDRPORT.
 *
 * The @a remote_addr argument is @a mandatory.  It specifies the address of the sender.
 * If the address of the sender in the message does not match @a remote_addr, the
 * error @c KRB5KRB_AP_ERR_BADADDR will be returned.
 *
 * If @a local_addr is non-null, then the address of the receiver in the message must
 * match it. If it is NULL, the receiver address in the message will be checked against the
 * list of local addresses as returned by krb5_os_localaddr(). If the check fails,
 * @c KRB5KRB_AP_ERR_BADARRD is returned.
 *
 * If the @a flags field in @c _krb5_auth_context indicates that sequence numbers
 * are to be used (if @c KRB5_AUTH_CONTEXT_DOSEQUENCE is set in it), the @c remote_seq_number field
 * of @c _krb5_auth_context is compared to the sequence number for the message, and
 * @c KRB5_KRB_AP_ERR_BADORDER is returned if it does not match. Otherwise, the sequence
 * number is not used.
 *
 * If timestamps are to be used (if @c KRB5_AUTH_CONTEXT_DO_TIME is set in @c _krb5_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), or @c KRB5KRB_AP_ERR_SKEW is returned.
 * @li The message must not be a replayed message, according to @a rcache.
 *
 * Make sure to free the allocated memory when it is no longer needed
 *
 * @retval
 * 0 Success
 * @return
 * 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);

/**
 * @brief Decode and decrypt a @c KRB-PRIV message.
 *
 * @param context           Context structure [input, output]
 * @param auth_context      Authentication context [input, output]
 * @param inbuf             @c KRB-PRIV message[input]
 * @param outbuf            Application data stored in @c KRB_PRIV message [output]
 * @param outdata          Sequence numbers [input, output]
 *
 * The @a remote_addr field of @c _krb5_auth_context set by krb5_auth_con_setaddrs() is
 * @a mandatory; it specifies the address of the sender. If the address of the sender in the
 * message does not match the @a remote_addr, @c KRB5KRB_AP_ERR_BADADDR is returned.
 *
 * If @c local_addr field of @c _krb5_auth_context is non-null, the address of the
 * receiver in the message must match it. If @a local_addr is NULL, the receiver address in the
 * message will be checked against the list of local addresses as returned by krb5_os_localaddr().
 *
 * The @a keyblock field of @c _krb5_auth_context specifies the key to be used to decrypt the message.
 * If the @a i_vector field is non-null, it is used as an initialization vector
 * for the decryption (if the encryption type of the message supports initialization vectors)
 * and its contents are replaced with the last block of encrypted data in the message.
 *
 * @a flags in @c _krb5_auth_context specify if timestamps (@c KRB5_AUTH_CONTEXT_DO_TIME)
 * and sequence numbers (@c KRB5_AUTH_CONTEXT_DO_SEQUENCE, @c KRB5_AUTHCONTEXT_RET_SEQUENCE) are used.
 *
 * @retval
 * 0 Success
 * @return
 * 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);

/** Convert a single-string principal name to a krb5_principal structure.
 *
 * @param [in]  context    Context structure
 * @param [in]  name       Single string representation of a principal name
 * @param [out] nprincipal Principal
 *
 * Convert a single-string representation of a principal name to a
 * krb5_principal structure.
 *
 * A single-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 @a n, @a t,@a b or @a 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);

#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 single-string principal name to a krb5_principal with restrictions.
 *
 * @param [in]  context    Context structure
 * @param [in]  name       Single 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;
 * takes the additional flags.
 *
 * The following flags are valid:
 * @li @c KRB5_PRINCIPAL_PARSE_NO_REALM - no realm must be present in @a name
 * @li @c KRB5_PRINCIPAL_PARSE_MUST_REALM - realm must be present in @a name
 * @li @c 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 single-string representation.
 *
 * @param [in]  context    Context structure
 * @param [in]  principal  Principal
 * @param [out] name       Single string representation of a Kerberos principal name
 *
 * The resulting single-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);

/** Convert krb5_principal structure to string format.
 *
 * @param [in]  context           Context structure
 * @param [in]  principal         Principal
 * @param [out] name              Single string format of principal name
 * @param [out] size              Size of unparsed name buffer
 *
 * @sa krb5_unparse_name()
 *
 * @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);

#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 */

/** Convert krb5_principal structure to a single-string with restrictions.
 *
 * @param [in]  context    Context structure
 * @param [in]  principal  Principal
 * @param [in]  flags      Flags
 * @param [out] name       Single string representation of a Kerberos principal name
 *
 * Similar to krb5_unparse_name(), this function converts a krb5_principal structure
 * to a single-string representation; takes the additional flags.
 *
 * The following flags are valid:
 * @li @c KRB5_PRINCIPAL_UNPARSE_SHORT -  omit realm if it is the local realm
 * @li @c KRB5_PRINCIPAL_UNPARSE_NO_REALM - omit realm in the principal name @a name
 * @li @c KRB5_PRINCIPAL_UNPARSE_DISPLAY - no quoting in the principal name @a name
 *
 * 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 restrictions.
 *
 * @param [in]  context           Context structure
 * @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 in the current context.
 *
 * @param [in,out] context           Context structure
 * @param [in]     principal         Principal name
 * @param [in]     realm             Realm name
 *
 * Set the realm name part of @a principal to @a realm.
 *
 * @note This function frees the previous realm of @a principal.
 *
 * @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 context                Context structure
 * @param [in] addr              Address to search for
 * @param [in] addrlist          Address list to be searched.
 *                               Specify NULL if there is no address list
 *
 * @note If @a addrlist contains only a NetBIOS addresses,
 *       it will be treated as empty list.
 *
 * @retval
 * 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 context                Context structure
 * @param [in] addr1             First address to be compared
 * @param [in] addr2             Second address to be compared
 *
 * @retval
 *  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 context                Context structure
 * @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           Context structure
 * @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           Context structure
 * @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           Context structure
 * @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           Context structure
 * @param [in] princ1            First principal
 * @param [in] princ2            Second principal
 * @param [in] flags             Flags
 *
 * Valid flags are:
 * @li @c KRB5_PRINCIPAL_COMPARE_IGNORE_REALM - ignore realm component
 * @li @c KRB5_PRINCIPAL_COMPARE_ENTERPRISE - UPNs as real principals
 * @li @c KRB5_PRINCIPAL_COMPARE_CASEFOLD case-insensitive
 * @li @c 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           Context structure
 * @param [in]  enctype           Encryption type
 * @param [in]  length            Length of keyblock
 * @param [out] out               Pointer to empty keyblock
 *
 * 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.
 * 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           Context structure
 * @param [in]  from              Keyblock to be copied
 * @param [out] to                Copy of keyblock @a from
 *
 * This function copies the content of @a from to @a to
 * 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           Context structure
 * @param [in]  from              Key to be copied
 * @param [out] to                Output key
 *
 * This function copies @a from->contents to @a to.
 * Use krb5_free_keyblock_contents() to zero out and 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           Context structure
 * @param [in]  incred            Credentials structure to be copied
 * @param [out] outcred           Copy of @a incred
 *
 * This function copies the content of @a incred to @a outcred
 * 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           Context structure
 * @param [in]  indata            Data object to be copied
 * @param [out] outdata           Copy of @a indata
 *
 * This function copies the content of @a indata to @a outdata
 * 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           Context structure
 * @param [in]  inprinc           Principal to be copied
 * @param [out] outprinc          Copy of @a inprinc
 *
 * This function copies the content of @a inprinc to @a outprinc
 * 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           Context structure
 * @param [in]  inaddr            Array of addresses to be copied
 * @param [out] outaddr           Copy of array of addresses
 *
 * This function copies the content of @a inaddr to @a outaddr.
 * 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           Context structure
 * @param [in]  from              Ticket to be copied
 * @param [out] pto               Copy of ticket
 *
 * This function copies the content of @a from to @a pto
 * 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 array of authorization data structures.
 *
 * @param [in]  context          Context structure
 * @param [in]  in_authdat       Array of @a krb5_authdata structures
 * @param [out] out              New array of @a krb5_authdata structures
 *
 * This function copies the content of @a in_authdat to @a out
 * 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);

/** Merge two authdata arrays with fresh allocation.
 *
 * @param [in]  context          Context structure
 * @param [in]  inauthdat1       1st array of @a krb5_authdata structures
 * @param [in]  inauthdat2       2d array of @a krb5_authdata structures
 * @param [out] outauthdat       New array 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 srtucture.
 *
 * @param [in]  context           Context structure
 * @param [in]  authfrom          krb5_authenticator structure to be copied
 * @param [out] authto            Copy of krb5_authenticator structure
 *
 * This function copies the content of @a authfrom to @a authto
 * 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           Context structure
 * @param [in]  ckfrom            Checksum to be copied
 * @param [out] ckto              Copy of krb5_checksum structure
 *
 * This function copies the content of @a ckfrom to @a ckto
 * 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           Context structure
 * @param [in]  piece             Unique identifier for replay cache
 * @param [out] rcptr             Handle to an open rcache
 *
 * This function generates a replay cache name, allocates memory for its
 * handle @a rcptr, and then opens it. Unique identifier @a piece is used
 * to differentiate this replay cache from the others on the system and
 * typically it is the first component of the principal name of the caller.
 * The handle @a rcptr should be closed with krb5_rc_close().
 * Use krb5_rc_destroy() to destroy @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  Context structure
 * @param [out] princ    Principal name
 * @param [in]  rlen     Realm name length
 * @param [in]  realm    Realm name
 * @param [in]  ...      List of arguments specifying length and content for each argument
 *
 * Call krb5_free_principal() to free allocated memory for principal when it is no longer needed.
 *
 * @note krb5_build_principal() and krb5_build_principal_va() perform the same task.
 * krb5_build_principal() takes variadic arguments.
 * krb5_build_principal_va() takes a pre-computed @a varargs pointer.
 *
 * @code
 * Example of how to build principal WELLKNOWN/ANONYMOUS@R
 *     krb5_build_principal_ext(context, &principal, strlen("R"), "R",
 *         strlen(KRB5_WELLKNOWN_NAMESTR), KRB5_WELLKNOWN_NAMESTR,
 *         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           Context structure
 * @param [out] princ             Principal name
 * @param [in]  rlen              Realm name length
 * @param [in]  realm             Realm name
 * @param [in]  ...               List of len1, sl1, len2, sl2...
 *
 * Call krb5_free_principal() to free @a princ when it is no longer needed.
 *
 * @note krb5_build_principal() and krb5_build_principal_va() perform the same task.
 * krb5_build_principal() takes variadic arguments.
 * krb5_build_principal_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
/**
 * @param [in]  context           Context structure
 * @param [out] princ             Principal structure
 * @param [in]  rlen              Realm name length
 * @param [in]  realm             Realm name
 * @param [in]  ap                @c va_list of argument
 *
 * @deprecated Replaced by krb5_build_principal() and krb5_build_principal_va().
 *
 * Build a principal name, using a precomputed @c va_list.
 *
 * @note krb5_build_principal() and krb5_build_principal_va() perform the same task.
 * krb5_build_principal() takes variadic arguments.
 * krb5_build_principal_va() takes a pre-computed @a varargs pointer.
 *
 * Use krb5_free_principal() to free @a princ when it is no longer needed.
 *
 * @retval 0 Success; otherwise - Kerberos error codes
 */
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           Context structure
 * @param [out] princ             Principal structure. Locally allocated.
 * @param [in]  rlen              Realm name length
 * @param [in]  realm             Realm name
 * @param [in]  ap                @c va_list of arguments
 *
 * Similar to krb5_build_principal() this function builds a principal name,
 * but its name components are specified as va_list.
 *
 * Use krb5_free_principal() to deallocate the @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           Context structure
 * @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           Context structure
 * @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           Context structure
 * @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           Context structure
 * @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. The name is obtained either
 * from the environment variable KRB5_KTNAME or from @a default_keytab_name
 * entry in @a libdefaults section of krb5 configuration file or
 * falls back on the default keytab name for the OS.
 *
 * @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           Context structure
 * @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           Context structure
 * @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);

/** Free the contents of a key table entry.
 *
 * @param [in] context           Context structure
 * @param [in] entry             Key table entry to be freed
 *
 * @warning  Use krb5_free_keytab_entry_contents instead; this does the same
 * thing but is misnamed and retained for backward compatability.
 */
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           Context structure
 * @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           Context structure
 * @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           Context structure
 * @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 credentials cache name.
 *
 * @param [in]  context          Context structure
 * @param [in]  name             Credentials cache name to be resolved
 * @param [out] cache            Credentials 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          Context structure
 * @param [in]  in               Credentials cache handle to be duplicated
 * @param [out] out              Credentials 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 credentials cache.
 *
 * @param [in] context       Context structure
 *
 * Try the environment variable KRB5CCNAME first then, if it is not set,
 * fall back on the default ccache name for the OS.
 *
 * @return
 * Name of default credentials cache for the current user.
 */
const char *KRB5_CALLCONV
krb5_cc_default_name(krb5_context context);

/** Set the default credentials cache name.
 *
 * @param [in,out]  context           Context structure
 * @param [in]      name              Default credentials cache name
 *
 * This function frees the old default credentials 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          Context structure
 * @param [out]    ccache            Pointer to credentials 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 credentials cache cannot be obtained
 * @return
 * Kerberos error codes
 */
krb5_error_code KRB5_CALLCONV
krb5_cc_default(krb5_context context, krb5_ccache *ccache);

/** Copy a credentials cache.
 *
 * @param [in]  context           Context structure
 * @param [in]  incc              Credentials cache to be copied
 * @param [out] outcc             Copy of credentials 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 some configuration for the credential cache in the cache.
 *
 * @param [in]     context     Context structure
 * @param [in]     id          The credential cache to store the data for
 * @param [in]     principal   Configuration for this principal;
 *                             if NULL, global for the whole cache.
 * @param [in]     key         Name under which the configuraion is stored
 * @param [in,out] data        Data to be fetched; free with krb5_free_data_contents()
 *
 * @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 some configuration for the credential cache in the cache.
 *
 * @param [in,out] context         a Keberos context
 * @param [in]     id              the credential cache to store the data for.
 * @param [in]     principal       configuration for a specific principal;
 *                                 if NULL, global for the whole cache.
 * @param [in]     key             name under which the configuraion is stored.
 * @param [in]     data            data to store. If NULL, old configuration is removed.
 *
 * @note Existing configuration under the same key is over-written.
 *
 * @warning Before version 1.10 @a data was assumed to be always non-zero
 *
 * @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        a Keberos context
 * @param [in] principal      principal to check if it a configuration principal
 *
 * @return
 *  TRUE (non zero) if the principal is a configuration principal
 * (generated part of krb5_cc_set_config()); FALSE (zero) otherwise.
 */
krb5_boolean KRB5_CALLCONV
krb5_is_config_principal(krb5_context context, krb5_const_principal principal);

/* krb5_free.c */
/** Free the storage assigned to a principal.
 *
 * @param [in] context           Context structure
 * @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      context           Context structure
 * @param [in] val               Pointer to authenticator structure to be freed
 *
 * This function frees the storage assigned to @a krb5_authenticator
 * structure, and then @a val itself is released.
 */
void KRB5_CALLCONV
krb5_free_authenticator(krb5_context context, krb5_authenticator *val);

/** Free the data stored in array of addresses.
 *
 * @param      context           Context structure
 * @param [in] val               Array of addresses to be freed
 *
 * This function frees the storage assigned to array of @a krb5_address
 * structures, and then @a val itself is released.
 *
 * @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      context           Context structure
 * @param [in] val               Array of authentication data to be freed
 *
 * This function frees the storage assigned to array of @a krb5_authdata
 * structures, and then @a val itself is released.
 *
 * @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           Context structure
 * @param [in] val               Ticket to be freed
 *
 * This function frees the storage assigned to @a krb5_ticket
 * structure, and then @a val itself is released.
 */
void KRB5_CALLCONV
krb5_free_ticket(krb5_context context, krb5_ticket *val);

/** Free an error allocated by either krb5_read_error() or krb5_sendauth().
 *
 * @param [in] context           Context structure
 * @param [in] val               Error data structure to be freed
 *
 * This function frees the storage assigned to @a krb5_error
 * structure, and then @a val itself is released.
 */
void KRB5_CALLCONV
krb5_free_error(krb5_context context, register krb5_error *val);

/** Free a credentials structure and invalidate its pointer.
 *
 * @param [in] context           Context structure
 * @param [in] val               Pointer to data structure to be freed
 *
 * This function frees the storage assigned to @a krb5_creds
 * structure, and then @a val itself is released.
 */
void KRB5_CALLCONV
krb5_free_creds(krb5_context context, krb5_creds *val);

/** Zero out the session key and free the credentials structure.
 *
 * @param [in]     context           Context structure
 * @param [in,out] val               Pointer to the data structure to be freed
 *
 * @note The pointer to @a val is not freed.
 */
void KRB5_CALLCONV
krb5_free_cred_contents(krb5_context context, krb5_creds *val);

/** Free a krb5_checksum structure.
 *
 * @param      context           Context structure
 * @param [in] val               Pointer to data structure to be freed
 *
 * This function frees the contents of a @a val and then releases @a val itself.
 */
void KRB5_CALLCONV
krb5_free_checksum(krb5_context context, register krb5_checksum *val);

/** Free the contents of a krb5_checksum structure.
 *
 * @param      context           Context structure
 * @param [in] val               Checksum structure to be released
 *
 * @note The pointer to @a val itself is not freed.
 */
void KRB5_CALLCONV
krb5_free_checksum_contents(krb5_context context, register krb5_checksum *val);

/** Free the storage assigned to a keyblock.
 *
 * @param [in] context           Context structure
 * @param [in] val               Keyblock to be freed
 *
 * This function zeros out and frees the contents of a @a val and then
 * releases @a val itself.
 */
void KRB5_CALLCONV
krb5_free_keyblock(krb5_context context, register krb5_keyblock *val);

/** Zero out and free the contents of a keyblock.
 *
 * @param [in] context           Context structure
 * @param [in] key               Keyblock to be freed
 *
 * @note The pointer to @a key itself is not freed.
 */
void KRB5_CALLCONV
krb5_free_keyblock_contents(krb5_context context, register krb5_keyblock *key);

/** Free the subkey keyblock.
 *
 * @param [in] context           Context structure
 * @param [in] val               Pointer to data structure to be freed
 *
 * This function frees the storage assigned to the decrypted portion of an AP-REP
 * message, and then @a val itself is released.
 */
void KRB5_CALLCONV
krb5_free_ap_rep_enc_part(krb5_context context, krb5_ap_rep_enc_part *val);

/** Free the storage assigned to a krb5_data object
 *
 * @param      context           Context structure
 * @param [in] val               Pointer to data structure to be freed
 *
 * This function zeros out and frees the contents field of @a val and then
 * frees @a val itself.
 */
void KRB5_CALLCONV
krb5_free_data(krb5_context context, krb5_data *val);

/** Zero out and free the contents of a krb5_data object
 *
 * @param      context           Context structure
 * @param [in] val               Pointer to data structure to be freed
 *
 * @note The pointer to @a val itself is not freed.
 */
void KRB5_CALLCONV
krb5_free_data_contents(krb5_context context, krb5_data *val);

/** Free a simple character name string returned by krb5_unparse_name().
 *
 * @param      context           Context structure
 * @param [in] val               Pointer to name string to be freed
 *
 * @note The pointer to @a val itself is not freed.
 */
void KRB5_CALLCONV
krb5_free_unparsed_name(krb5_context context, char *val);

/** Free an array of checksum types.
 *
 * @param      context           Context structure
 * @param [in] val               Array of checksum types to be freed
 *
 * @note Make sure the checksum contents have already been freed.
 */
void KRB5_CALLCONV
krb5_free_cksumtypes(krb5_context context, krb5_cksumtype *val);

/* From krb5/os but needed but by the outside world */
/** Retrieve the system time of day, in sec and ms, since the epoch.
 *
 * @param [in]  context           Context structure
 * @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     Context structure
 * @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);

/** Return all protocol addresses for this host.
 *
 * @param [in]  context       Context structure
 * @param [out] addr          Array of krb5_address pointers.
 *                            The last entry is a NULL pointer
 *
 * Compile-time configuration flags indicate which protocol family addresses
 * can be returned. Both AF_INET and AF_INET6 are currently supported.
 *
 * 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   Context structure
 * @param [out] lrealm    Pointer to default realm for the host
 *
 * 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,out] context           Context structure
 * @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 the default realm string returned by krb5_get_default_realm().
 *
 * @param      context           Context structure
 * @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   Context structure
 * @param [in]  hostname  Host name, or NULL to use local host
 * @param [in]  sname     Service name, or NULL to use string @c host
 * @param [in]  type      Principal type: @c KRB5_NT_SRV_HST or @c KRB5_NT_UNKNOWN
 * @param [out] ret_princ Generated principal
 *
 * This function converts a given @a hostname and @a sname into @a krb5_principal
 * structure @a ret_princ.
 *
 * The @a type can be one of the following:
 *
 * @li @c KRB5_NT_SRV_HOST canonicalizes the host name (a fully
 * qualified lowercase @a hostname using the primary name and the
 * domain name), \b before @a ret_princ is generated in the form
 * sname//hostname\@LOCAL.REALM. Most applications should use @a KRB5_NT_SRV_HOST.
 *
 * @li @c KRB5_NT_UNKNOWN generates a  principal name with
 * the form @a sname\/hostname\@LOCAL.REALM, but the @a hostname \b will \b not be
 * canonicalized first. It will appear exactly as it was passed in @a hostname.
 *
 * 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        Context structure
 * @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                 Context structure
 * @param [in]  creds                   Kerberos credentials to the kadmin/changepw service
 * @param [in]  newpw                   New password
 * @param [out] result_code             A numeric error code
 * @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,out] context            Context structure
 * @param [in]  creds                 Credentials
 * @param [in]  newpw                 New password
 * @param [in]  change_password_for   Change the password for this principal
 * @param [out] result_code           Numeric error code returned by the remote system
 * @param [out] result_code_string    Error code translated into a readable message
 * @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,out] context            Context structure
 * @param [in]  ccache                Credentials cache
 * @param [in]  newpw                 New password
 * @param [in]  change_password_for   Change the password for this principal
 * @param [out] result_code           Numeric error code returned by the remote system
 * @param [out] result_code_string    Error code translated into a readable message
 * @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 credentials cache.
 *
 * The error code and strings are returned in @a result_code,
 * @a result_code_string and @a result_string.
 *
 * @sa krb5_set_password()
 *
 * @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.
 *
 * @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 data from the context.
 *
 * @param [in]  context         Context structure
 * @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 */

/**
 * @brief Parse a @c KRB5-AP-REQ message and return its contents.
 *
 * @param context           Context structure [input, output]
 * @param auth_context      Authentication context [input, output]
 * @param inbuf             Holds the KRB-AP-REQ message to be parsed [input]
 * @param server            Expected server's principal name for the ticket
 * @param keytab            Key table containing decryption key [input]
 * @param ap_req_options    If non-null, the AP-REQ flags on output [input, output]
 * @param ticket            Returned ticket from the AP-REQ message. Use NULL to specify no ticket [output]
 *
 * If @a ticket is set to non-null, it is modified to point to the ticket information.
 *
 * If @c _krb5_auth_context is set to NULL, an @c _krb5_auth_context is generated and freed internally
 * by the function.
 *
 * If @a server is set to NULL, any server name with an appropriate key will be accepted.
 *  Make sure to verify that the server principal name matches some trust
 * criterion.
 *
 * If @a server is set to non-null and a @a replay detection cache has not
 * been established with @c _krb5_auth_context, an @c _krb5_auth_context is generated.
 *
 * If a @a keyblock is present in the @c _krb5_auth_context, it is used to decrypt the ticket
 * request and then must be freed with krb5_free_keyblock(). This is useful for
 * user-to-user authentication.
 *
 * If no @a keyblock is specified, the key table uses an entry matching the requested @a keytype,
 * @a server, and @a version @a number.
 *
 * The authenticator in the request is decrypted and stored in @c _krb5_auth_context.
 * The client specified in the decrypted authenticator is compared to the client
 * specified in the decoded ticket to ensure that the compare was performed.
 *
 * If the @a remote_addr field of @c _krb5_auth_context is set, this routine checks
 * whether the request came from the right client.
 *
 * The replay cache is checked to see if the ticket and authenticator have been seen
 * and, if so, returns an error. If not, the ticket and authenticator are entered into
 * the replay cache.
 *
 * Various other checks are performed on the decoded data, including cross-realm policy,
 * clockskew, and ticket validation times.
 *
 * The @a keyblock, @a subkey, and @a sequence @a number of the request are
 * stored in @c _krb5_auth_context for future use.
 *
 * If the @c AP_OPTS_MUTUAL_REQUIRED bit is set, the local sequence number
 * is XORed with the remote sequence number in the request.
 *
 * @note  A new authentication context is returned if NULL is specified.
 *
 * @note If @a keytab is set to NULL, the default key table is used.
 *
 * @retval
 *  0    Success
 * @retval
 *  KRB5KRB-AP-ERRR-BADADDR Invalid address
 * @return
 * 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     Context structure
 * @param [in]  keyprocarg  Name of a key table or NULL to use default key table
 * @param [in]  principal   Service principal
 * @param [in]  vno         Key version number; use 0 to specify the key with
 *                          the highest version number
 * @param [in]  enctype     Key encryption type; use a keytype of 0 if
 *                          encryption type does not matter
 * @param [out] key         Returned service key
 *
 * 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       Context structure
 * @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 KRB5_AUTH_CONTEXT_ flags.
 *
 * The @a local_addr field of @a auth_context is used to
 * form the addresses used in the KRB-SAFE message. The remote_addr is optional;
 * if the receiver's address is unknown, it can be replaced by NULL.
 *
 * @note The @a local_addr argument is mandatory.
 *
 * @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.`
 *
 * If @c 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 sent back by an attacker.
 * If @c KRB5_AUTH_CONTEXT_DO_TIME is not set, the replay cache is not used.
 *
 * If either @c KRB5_AUTH_CONTEXT_DO_SEQUENCE or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE
 * is set, the @a auth_context local sequence number will be placed in the
 * @a outdata as its sequence number.
 *
 * @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               Context structure
 * @param [in,out] auth_context          Authentication context
 * @param [in]     serdata               User data for @c KRB-PRIV message
 * @param [out]    outbuf                Formatted @c KRB-PRIV message
 * @param [out]    outdata               Replay cache handle
 *
 * This function is similar to krb5_mk_safe(), but the message is encrypted and
 * integrity-protected, not just integrity-protected.
 *
 * The @a remote_addr and @a remote_port fields of @a auth_context are
 * optional; @a local_addr, is mandatory. If the receiver's address is unknown,
 * it can be replaced by NULL.
 *
 * The encryption type is taken either from  @a send_subkey or, if NULL,
 * from @a key field of @a auth_context.
 *
 * If the @a i_vector field in @a auth_context is non-null, it is used
 * as an initialization vector for the encryption (if the chosen encryption
 * type supports initialization vectors), and its contents are replaced with
 * the last block of encrypted data upon return.
 *
 * @note If the @c KRB5_AUTH_CONTEXT_RET_TIME or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE
 * flag is set in @a auth_context, the @a outdata is required. Otherwise it can be
 * NULL.
 *
 * @note The flags from @a auth_context specify whether sequence numbers or
 * timestamps will be used to identify the message.
 * Valid values are:
 * @li @c KRB5_AUTH_CONTEXT_DO_TIME      - Use timestamps in @a outdata
 * @li @c KRB5_AUTH_CONTEXT_RET_TIME     - Copy timestamp to @a outdata.
 * @li @c KRB5_AUTH_CONTEXT_DO_SEQUENCE  - Use local sequence numbers from
 *                                         @a auth_context in replay cache.
 * @li @c 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);

 /**
 * @brief Send an authenticated message.
 *
 * @param context            Context structure [input, output]
 * @param auth_context       Authentication context [input, output}
 * @param fd                 Pointer to file descriptor that describes network socket [input]
 * @param appl_version       String that describes the application protocol version client is expected to use [input]
 * @param client             Client principal name; ignored if @a in_creds is non-null [input]
 * @param server             Server principal name; ignored if @a in_creds is non-null [input]
 * @param ap_req_options     Specifies @c KRB-AP-REQ flags [input]
 * @param in_data            Data to be sent to the server [input]
 * @param in_creds           Input credentials, or NULL [input]
 * @param ccache             Credentials cache [input, output]
 * @param error              If non-null, contains error packet returned from server [output]
 * @param rep_result         If non-null, contains result of mutual authentication exchange [output]
 * @param out_creds         If non-null, the retrieved credentials [output]
 *
 * Send an authenticated message from a client program to a server
 * program using the network connection specified by @a fd. In the MIT UNIX and
 * OpenVMS implementations, @a fd is a pointer to a network socket file descriptor.
 *
 * Valid values for @a ap_req_options are:
 * @li @c  AP_OPTS_USE_SESSION_KEY
 * @li @c AP_OPTS_MUTUAL_REQUIRED  Perform a mutual authentication exchange
 * @li @c AP_OPTS_USE_SUBKEY
 *
 * If @a in_creds is NULL:
 * @li @a server must be non-null
 * @li @a client can be NULL. If @a client is NULL, the credentials cache default principal is used.
 *
 * If @a in_creds is non-null, @a in_creds->client and @a in_creds->server must be
 * filled in. If the other structure fields are filled in with valid credentials,
 * @a in_creds->ticket.length must be zero.
 *
 * If @a rep_result is non-null, it is filled in with the result of the mutual
 * authentication exchange.
 *
 * If @a in_creds->ticket.length is nonzero, @a in_creds is used
 * as the credentials to send to the server, and @a ccache is ignored. Otherwise,
 * @a ccache is used.
 *
 * If @a out_creds, is non-null, it is filled in with the retrieved credentials.
 *
 * @a ccache specifies the credential cache to use @a only when @a in_creds is
 * NULL or @a in_creds->ticket.length is zero.
 *
 * If @a in_creds is NULL or @a in_creds->ticket.length is zero and @a ccache is NULL,
 * If the default credential cache does not contain the needed credentials,
 * the credentials will be retrieved from the KDC and stored in the credential cache.
 *
 * If mutual authentication is used and @a rep_result is non-null, the sequence number
 * for the server is in *rep_result-\>seq_number. If mutual authentication is not
 * used, there is no way to negotiate a sequence number for the server.
 *
 * If the server is using a different application protocol than that specified in
 * @a appl_version, an error will be returned.
 *
 * If an error occurs during the authenticated message exchange and @a error is non-null,
 * the error packet (if any)  sent from the server will be placed in it.
 *
 * Make sure to free the allocated memory when it is no longer needed.
 *
 * @retval
 *  0   Success
 * @return
 * 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);

/**
 * @brief Receive an authenticated message.
 *
 * @param context            Context structure [input, output]
 * @param auth_context       Authentication context [input, output}
 * @param fd                 Pointer to file descriptor of network socket [input]
 * @param appl_version       String describing the expected application protocol version. [input]
 * @param server             Server principal [input]
 * @param flags              Additional specifications; nonlibrary callers should use 0. [input]
 * @param keytab            Decryption key [input]
 * @param ticket              Ticket (optional); only filled in with client ticket data if non-null [output]
 *
 * This routine, paired with krb5_sendauth(), provides a way for client and server programs to
 * send authenticated messages to one another through network connections.
 *
 * krb5_recvauth() engages in an authentication dialog with the client program running krb5_sendauth()
 * to authenticate the client to the server.
 *
 * Upon request from the client, krb5_recvauth() provides mutual authentication
 * to ensure the legitimacy of the server represented by krb5_recvauth().
 *
 * The @a fd argument is a pointer to the network connection. As in krb5_sendauth()
 * in the MIT UNIX and OpenVMS implementations, @a fd is a pointer to a file descriptor.
 *
 * @a server, @c _krb5_auth_context, and @a keytab are used to obtain the server's private key.
 *
 * @note
 * @li  if client uses a different application protocol than that specified in @a appl_version,
 * an error is returned and the authentication exchange is aborted.
 *
 * Make sure to free the allocated memory when it is no longer needed.
 *
 * @retval
 *  0   Success
 * @return
 * Kerberos error codes
 *
 * @todo link to flags?
 */
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);

/**
 * @brief Send authentication messages between client and server using the network.
 *
 * @param context           Context structure [input, output]
 * @param auth_context       Authentication context [input, output}
 * @param fd                Socket from which to read the client response [input]
 * @param server            Verify the server principal is the same as  requested by client; if NULL, an error is returned and the exchange is aborted [input]
 * @param flags
 * @param keytab            Decryption key [input]
 * @param ticket            Optional, if non-null, filled with ticket data sent by the client [output]
 * @param version           Pointer to application version string [output]
 *
 * This routine provides a convenient means for client and server programs to send authenticated messages to
 * one another through network connections. (k5b5_sendauth() is the matching routine to krb5_recvauth_version() for the server.)
 *
 * krb5_recvauth_version() engages in an authentication dialog with the client program running
 * krb5_sendauth() to authenticate the client to the server. In addition, if requested by the client,
 * krb5_recvauth_version() provides mutual authentication to prove to the client that the server represented by
 * krb5_recvauth_version() is legitimate.
 *
 * @a fd  is a pointer to the network connection. As in krb5_sendauth(), in the MIT UNIX and
 * OpenVMS implementations, @a fd is a pointer to a file descriptor.
 *
 * The arguments @a server, @c _krb5_auth_context, and @a keytab are used by @c krb5_rd_req() to obtain the
 * server's private key.
 *
 * If server is non-null, the principal component of it is used to determine
 * the replay cache to use. Otherwise, @c krb5_recvauth_version uses the default
 * replay cache.
 *
 * Make sure to free the allocated memory when it is no longer needed.
 *
 * @retval
 * 0 Success
 * @retval
 * KRB5_SENDAUTH_BADAUTHVERS Bad sendauth version was sent
 * @retval
 * KRB5_SENDAUTH_BADAPPLVERS Bad application version was sent
 * @return
 * Kerberos error codes
 */
krb5_error_code KRB5_CALLCONV
krb5_recvauth_version(krb5_context context,
                      krb5_auth_context *auth_context,
                      /* IN */
                      krb5_pointer fd,
                      krb5_principal server,
                      krb5_int32 flags,
                      krb5_keytab keytab,
                      /* OUT */
                      krb5_ticket **ticket,
                      krb5_data *version);

/** Format a @c KRB-CRED message for an array of credentials.
 *
 * @param [in]     context            Context structure
 * @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 handle
 *
 * 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 @c KRB5_AUTH_CONTEXT_RET_TIME or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE
 * flag is set in @a auth_context, the @a outdata is required. Otherwise it can be
 * NULL.
 *
 * @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           Context structure
 * @param [in,out] auth_context      Authentication context
 * @param [in]     pcreds            Pointer to credentials
 * @param [out]    ppdata            Encoded credentials
 * @param [out]    outdata           Replay cache handle
 *
 * This is a convenience function that calls krb5_mk_ncred() with a single set
 * of credentials.
 *
 * @note If the @c KRB5_AUTH_CONTEXT_RET_TIME or @c KRB5_AUTH_CONTEXT_RET_SEQUENCE
 * flag is set in @a auth_context, the @a outdata is required. Otherwise it can be
 * NULL.
 *
 * @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);

/**
 * @brief Read a @c KRB-CRED message, validate it, and output the nonce and an array of the forwarded credentials.
 *
 * @param context            Context structure [input, output]
 * @param auth_context       Authentication context [input, output}
 * @param pcreddata          @c KRB-CRED message [input]
 * @param pppcreds           Array of forwarded credentials [output]
 * @param outdata            Replay data information [output]
 *
 * Make sure to free the allocated memory when it is no longer needed.
 *
 * @retval
 * 0 Success
 * @retval
 *  KRB5_RC_REQUIRED Message replay detection requires @a rcache parameter
 *  @retval
 *  KRB5KRB-AP-ERR-SKEW Clock skew too great
 * @retval
 *  KRB5KRB-AP-ERR-BADORDER Message out of order
 * @retval
 *  ENOMEM Insufficient memory
 * @return
 * 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      Context structure
 * @param [in] auth_context Authentication context with the key to encrypt @a outbuf
 * @param [in] rhost        Remote host
 * @param [in] client       Client principal for the TGT
 * @param [in] server       Server principal for the TGT
 * @param [in] cc           Credentials cache handle.
 * @param [in] forwardable  Boolean indicating whether TGT should be forwardable
 * @param [out] outbuf      Output buffer containing the TGT to be filled in
 *
 * Get a TGT for use at the remote host @a rhost.
 * If @a rhost is NULL, @a server service principal will be used.
 * If @a cc is NULL, the default credential cache 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           Context structure
 * @param [out] auth_context      Authentication context
 *
 * The @c _krb5_auth_context contains all data pertinent to the various authentication routines.
 *
 * By default, @a 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 @c _krb5_auth_context structure.
 *
 * @param [in] context           Context structure
 * @param [in] auth_context      Authentication context to be freed
 *
 * This function frees @a 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          context           Context structure
 * @param [in,out] auth_context      Authentication context
 * @param [in]     flags             Flags bit mask
 *
 * Valid values for @a flags are:
 * @li @c KRB5_AUTH_CONTEXT_DO_TIME  Use timestamps
 * @li @c KRB5_AUTH_CONTEXT_RET_TIME Save timestamps to output structure
 * @li @c KRB5_AUTH_CONTEXT_DO_SEQUENCE  Use sequence numbers
 * @li @c KRB5_AUTH_RET_SEQUENCE  Copy sequence numbers to output structure
 *
 * @retval 0 (always)
 */
krb5_error_code KRB5_CALLCONV
krb5_auth_con_setflags(krb5_context context, krb5_auth_context auth_context, krb5_int32 flags);

/** Retrieve a flags field from a krb5_auth_context structure.
 *
 * @param          context          Context structure
 * @param [in]     auth_context     Authentication context
 * @param [out]    flags            Flags bit mask
 *
 * Valid values for @a flags are:
 * @li @c KRB5_AUTH_CONTEXT_DO_TIME      Use timestamps in the message
 * @li @c KRB5_AUTH_CONTEXT_RET_TIME     Save timestamps to output structure.
 * @li @c KRB5_AUTH_CONTEXT_DO_SEQUENCE  Use sequence numbers in the message
 * @li @c KRB5_AUTH_RET_SEQUENCE         Copy sequence numbers to output structure.
 *
 *
 * @retval 0 (always)
 */
krb5_error_code KRB5_CALLCONV
krb5_auth_con_getflags(krb5_context context, krb5_auth_context auth_context, krb5_int32 *flags);

/** Set checksum_function related fields in krb5_auth_contex structure.
 *
 * @param context                   Context structure
 * @param [in,out] auth_context     Authentication context
 * @param [in]     func             Function to perform the checksum
 * @param [in]     data             Pointer to arbitrary to be received by @a func
 *
 * The checksum data is received when krb5_mk_req_extended() calls it.
 *
 * @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 checksum_function related fields from krb5_auth_contex structure.
 *
 * @param context                Context structure
 * @param [in]  auth_context      Authentication context
 * @param [out] func              Pointer to krb5 function that performs the checksum
 * @param [out] data              Pointer to data
 *
 * @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);

/** Sep the local and remote addresses in a krb5_auth_context structure.
 *
 * @param [in]     context            Context structure
 * @param [in,out] 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 structure 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 a krb5_auth_con structure.
 *
 * @param [in]  context           Context structure
 * @param [in]  auth_context      Authentication context
 * @param [out] local_addr        Local address; if NULL - not requested
 * @param [out] remote_addr       Remote address; if NULL - not requested
 *
 * If @a local_addr or @a remote_addr is non-null, the buffers are freed and
 * then newly allocated.
 *
 * @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 a krb5_auth_context structure.
 *
 * @param [in]     context           Context structure
 * @param [in,out] 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 structure 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 an encryption key field in a krb5_auth_context structure.
 *
 * @param [in]     context          Context structure
 * @param [in,out] auth_context     Authentication context
 * @param [in]     keyblock         User key
 *
 * Use before calling krb5_rd_req_decode() for user-to-user
 * authentication when the server has the key and needs it to decrypt
 * the incoming request. Once decrypted, the temporary key is no longer
 * valid, and it is overwritten by the session key sent by the client.
 *
 * @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 an encryption key from a krb5_auth_context structure.
 *
 * @param [in]  context            Context structure
 * @param [in]  auth_context       Authentication context
 * @param [out] keyblock           Keyblock structure containing a key
 *
 * This function allocates the output @a keyblock and populates it with the
 * content of @a ac->send_key.
 * Use krb5_free_keyblock() to free @a keyblock when it it 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);

/** Get a copy of an encryption key from a krb5_auth_context structure.
 *
 * @param          context             Context structure
 * @param [in]     auth_context        Authentication context
 * @param [in,out] key                 Output key structure to be filled in
 *
 * This function populates the output @a key with the
 * content of @a auth_context->send_subkey.
 *
 * @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 a send_subkey keyblock from a krb5_auth_context structure.
 *
 * @param [in]  context       Context structure
 * @param [in]  ac            Authentication context
 * @param [out] keyblock      Key block structure.
 *
 * This function allocates the output @a keyblock and populates it with the
 * content of @a ac->send_subkey.
 * 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);

/** Get a copy of a send_subkey key from a krb5_auth_context structure.
 *
 * @param          ctx       Context structure
 * @param [in]     ac        Authentication context
 * @param [in,out] key       Key structure to be filled in
 *
 * This function populates the output @a key with the
 * content of @a auth_context->send_subkey.
 *
 * @retval 0 (always)
 */
krb5_error_code KRB5_CALLCONV
krb5_auth_con_getsendsubkey_k(krb5_context ctx, krb5_auth_context ac,
                              krb5_key *key);

/** Retrieve a recv_subkey keyblock from a krb5_auth_context structure.
 *
 * @param       ctx            Context structure
 * @param [in]  ac             Authentication context
 * @param [out] keyblock       Key block structure
 *
 * This function populates the output @a keyblock with the
 * content of @a auth_context->recv_subkey.
 * 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);

/** Get a copy of a recv_subkey key from a krb5_auth_context structure.
 *
 * @param          ctx       Context structure
 * @param [in]     ac        Authentication context
 * @param [in,out] key       Key block structure to be filled in
 *
 * This function populates the output @a key with the
 * content of @a auth_context->recv_subkey.
 *
 * @retval 0 (always)
 */
krb5_error_code KRB5_CALLCONV
krb5_auth_con_getrecvsubkey_k(krb5_context ctx, krb5_auth_context ac, krb5_key *key);

/** Set a send_subkey field in a krb5_auth_context structure.
 *
 * @param [in]     ctx             Context structure
 * @param [in,out] ac              Authentication context
 * @param [in]     keyblock        Key to be stored in @a ac->send_subkey
 *
 * The old  @a ac->send_subkey is freed.
 *
 * @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);

/** Assign send_subkey field in a krb5_auth_context structure to a given key.
 *
 * @param [in]     ctx           Context structure
 * @param [in,out] ac            Authentication context
 * @param [in]     key           Key to be assigned to @a ac->send_subkey
 *
 * The old  @a ac->send_subkey is freed.
 * The @a key reference count is incremented.
 *
 * @retval 0  (always)
 */
krb5_error_code KRB5_CALLCONV
krb5_auth_con_setsendsubkey_k(krb5_context ctx, krb5_auth_context ac, krb5_key key);

/** Set a recv_subkey field in a krb5_auth_context structure.
 *
 * @param [in]     ctx           Context structure
 * @param [in,out] ac            Authentication context
 * @param [in]     keyblock      Keyblock to be stored in @a ac->recv_subkey
 *
 * The old  @a ac->recv_subkey is freed.
 *
 * @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);

/** Assign recv_subkey field in a krb5_auth_context structure to a given key.
 *
 * @param [in]     ctx           Context structure
 * @param [in,out] ac            Authentication context
 * @param [in]     key           Key to be assigned to @a ac->send_subkey
 *
 * The old  @a ac->recv_subkey is freed.
 * The @a key reference count is incremented.
 *
 * @retval 0  (always)
 */
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 a local sequence number from a krb5_auth_context structure.
 *
 * @param          context           Context structure
 * @param [in]     auth_context      Authentication context
 * @param [in,out] seqnumber         Local sequence number to be filled in
 *
 * Retrieve the local sequence number used during authentication and store
 * it in the @a seqnumber.
 * The @c KRB5_AUTH_CONTEXT_DO_SEQUENCE flag must be set in @a auth_context
 * for this function to have an effect.
 *
 * @retval 0 (always)
 */
krb5_error_code KRB5_CALLCONV
krb5_auth_con_getlocalseqnumber(krb5_context context, krb5_auth_context auth_context,
                                krb5_int32 *seqnumber);

/** Retrieve a remote sequence number from a krb5_auth_context structure.
 *
 * @param          context           Context structure
 * @param [in]     auth_context      Authentication context
 * @param [in,out] seqnumber         Remote sequence number to be filled in
 *
 * Retrieve the remote sequence number used during authentication and store
 * it in the @a seqnumber.
 * The @c KRB5_AUTH_CONTEXT_DO_SEQUENCE flag must be set in @a auth_context
 * for this function to have an effect.
 *
 * @retval 0 (always)
 */
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 field in a krb5_auth_context structure.
 *
 * @param context                     Context structure
 * @param [in,out] auth_context       Authentication context
 * @param [in]     rcache             Replay cache haddle
 *
 * @retval 0 (always)
 */
krb5_error_code KRB5_CALLCONV
krb5_auth_con_setrcache(krb5_context context, krb5_auth_context auth_context,
                        krb5_rcache rcache);

/** Retrieve rcache field from a krb5_auth_context structure.
 *
 * @param          context          Context structure
 * @param [in]     auth_context     Authentication context
 * @param [out]    rcache           Replay cache handle
 *
 * Set the output @a rcache to @a auth_context->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 an authenticator from the authentication context.
 *
 * @param [in]  context           Context structure
 * @param [in]  auth_context      Authentication context
 * @param [out] authenticator     Authenticator
 *
 * Use krb5_free_authenticator() to free @a authenticator when it is no longer needed
 *
 * @sa krb5_copy_authenticator()
 *
 * @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 a checksum types field in a krb5_auth_context structure.
 *
 * @param context                     Context structure
 * @param [in,out]  auth_context      Authentication context
 * @param [in]      cksumtype         Checksun type
 *
 * Sets @a auth_context->req_cksumtype field to @a cksumtype.
 * This function is used to override the default checksum types defined in the
 * configuration file.
 *
 * @retval 0 (always)
 */
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 the keyboard input.
 *
 * @param context           Context structure [input]
 * @param prompt            First user prompt when reading password [input]
 * @param prompt2           Second user prompt, or NULL to read password only once [input]
 * @param return_pwd        Returned password [output]
 * @param size_return       During input, maximum size of password;
 * during output, total number of bytes in @a return_pwd [input, output]
 *
 * The first *size_return bytes of the password entered are
 * returned in @a return_pwd. If fewer than *size_return bytes are entered as a password,
 * the remainder of @a return_pwd is zeroed.
 * Upon success, the total number of bytes filled in is stored in *size_return.
 *
 * @a prompt is the prompt for the first reading of a password. It is printed
 * to the terminal, and then a password is read from the keyboard. No newlines
 * or spaces are emitted between the prompt and the cursor, unless the newline/space
 * is included in the prompt.
 *
 * If @a prompt2 is a NULL pointer, the password is read only once.
 *
 * If @a prompt2 is set, it is used as a prompt to read another
 * password in the same manner as described for the first password. After the
 * second password is read, the two passwords are compared, and an error is returned if they are not identical.
 *
 * 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           Context structure
 * @param [in]  aname             Principal name
 * @param [in]  lnsize_in         Maximum length name to be filled into @a lname
 * @param [out] lname             Local name buffer to be filled in
 *
 * If @a aname isn't in one of the local realms an error is returned.
 * If @a lnsize_in of @a lname is to small, an error 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). The translation is null-terminated in all non-error returns.
 *
 * @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           Context structure
 * @param [in]  host              Host name
 * @param [out] realmsp           Pointer to list of realm names
 *
 * Fill in @a realmsp with a pointer to an @c argv style list of names,
 * terminated with a NULL pointer.
 * If there are no known realms for the host, the filled-in pointer is set to NULL.
 *
 * 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 context           Context structure [input, output]
 * @param hdata
 * @param realmsp
 *
 * @todo part of referrals support? param descriptions? added pointer descr.
 *
 */
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      context           Context structure
 * @param [in] realmlist         List of the 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 the principal is authorized to log in as a local user.
 *
 * @param [in] context           Context structure
 * @param [in] principal         Principal name
 * @param [in] luser             Local username
 *
 * Determine whether the @a principal is authorized to log in
 * as a local user @a luser
 *
 * If there is either no local account for @a luser or @a principal does not
 * match luser@realm for any default relam or it is not recorded in the existing
 * .k5login, the @a luser is not authorized to log into an account.
 *
 * @retval
 * TRUE User is authorized to log in; FALSE otherwise
 */
krb5_boolean KRB5_CALLCONV
krb5_kuserok(krb5_context context, krb5_principal principal, const char *luser);

/** Generate a full IP address from @a address and port.
 *
 * @param [in]     context      Context structure
 * @param [in,out] auth_context Authentication context to be updated with
 *                              new local and remote addresses.
 * @param [in]     infd         Input socket file descriptor
 * @param [in]     flags        Input flags, defined in @c KRB\$ROOT:[INCLUDE]KRB5.
 *
 * The values for the symbols can be OR'd together. Valid values are:
 *
 * @li @c KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR
 * @li @c KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR
 * @li @c KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR
 * @li @c KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR
 *
 * @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           Context structure
 * @param [in] seconds           Number of seconds to set in @c time_offset
 *                               field in @a context
 * @param [in] microseconds      Number of microseconds to set in @c usec_offset
 *                               field in @a context
 *
 * Take the @a real @a time as input, and set the time offset fields in the
 * context structure so the @c krb5_time routines return the correct time,
 * as corrected by the difference between the system time and the @a real @a time as passed to this routine.
 *
 * Make sure to free the allocated memory when it is no longer needed.
 *
 * @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           Context structure
 * @param [out] seconds           Time offset from the OS context, seconds portion
 * @param [out] microseconds      Time offset from the OS context, microseconds portion
 *
 * This function returns the time offsets from @a context->os_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 to be filled in
 *
 * @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 a Kerberos encryption type value to a string.
 *
 * @param [in]  enctype  Encrytion type value to convert
 * @param [out] buffer   Buffer to hold encryption type string
 * @param [in]  buflen   Maximum length of the string that can fit 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 a Kerberos encryption type value to a name
 *
 * @param [in]  enctype  Encrytion type value to convert
 * @param [in]  shortest Flag
 * @param [out] buffer   Buffer to hold encryption type string
 * @param [in]  buflen   Maximum length of the string that can fit 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").
 *
 * @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 @a salttype to a string.
 *
 * @param [in]  salttype          Salttype to convert
 * @param [out] buffer            Buffer to receive the converted string
 * @param [in]  buflen            Length of @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 to be converted
 * @param [out] buffer            Buffer to hold converted checksum type
 * @param [in]  buflen            Maximum length of @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_cksumtype_to_string(krb5_cksumtype cksumtype, char *buffer, size_t buflen);

/** Convert a timestamp to a string.
 *
 * @param [in]  timestamp         Timestamp to be converted
 * @param [out] buffer            Buffer to hold converted timestamp
 * @param [in]  buflen            Maximum length of 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, allowing optional padding in the output buffer.
 *
 * @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
 *
 * This function also tries multiple possible formats if the default
 * locale-specific fails.
 *
 * @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            Maximum length of string that fits 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 (as for PIN or OTP) */
    krb5_data *reply;  /**< must be allocated before call to any prompt routine */
} krb5_prompt;

/**
 * @brief 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[]);

/**
 * @brief Prompt user for password.
 *
 * @param context           Context structure [input, output]
 * @param data              Unused
 * @param name              Name to output during prompt [input]
 * @param banner            Banner to output during prompt [input]
 * @param num_prompts       Number of prompts passed in @a prompts [input]
 * @param prompts           Array of krb5_prompt structures containing output prompts and replies [input, output]
 *
 * Prompt the user for the  password associated with the given principal name,
 * and set the reply field of the @a prompts argument to the password input. The hidden
 * flag in the @c prompts structure controls whether the password input is echoed back
 * to the terminal.
 *
 * @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[]);

 /**
  * @brief 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 extended krb5_get_init_creds_opt structure.
 *
 * @param [in,out] context  Context structure
 * @param [out]  opt  Pointer to @c _krb5_get_init_creds_opt structure to be allocated
 *
 * The caller of this function must call 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 an extended krb5_get_init_creds_opt structure.
 *
 * @param      context   Context structure
 * @param [in] opt       Pointer to @c _krb5_get_init_creds_opt structure to be freed
 *
 * @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);

/** Initialize a krb5_get_init_creds_opt structure.
 *
 * @param [in,out] opt   Pointer to krb5_get_init_creds_opt structure to be initialized
 *
 * @warning Callers MUST NOT call krb5_get_init_creds_opt_init() after allocating an
 * krb5_get_init_creds_opt structure using krb5_get_init_creds_opt_alloc().
 * To do so will introduce memory leaks.
 *
 * Sets @a opt->flag to KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT
 */
void KRB5_CALLCONV
krb5_get_init_creds_opt_init(krb5_get_init_creds_opt *opt);

/** Initialize the ticket lifetime field in krb5_get_init_creds_opt structure.
 *
 * @param [in,out] opt           Options
 * @param [in]     tkt_life      Ticket lifetime
 *
 * Sets KRB5_GET_INIT_CREDS_OPT_TKT_LIFE flag in @a opt
 *
 * The @a opt pointer supplied to this function must have been
 * obtained using krb5_get_init_creds_opt_alloc()
 */
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 field in krb5_get_init_creds_opt structure.
 *
 * @param [in,out] opt               Pointer to @a options field
 * @param [in]     renew_life        Ticket renewal lifetime
 *
 * Sets KRB5_GET_INIT_CREDS_OPT_iRENEW_LIFE flag in @a opt
 *
 * The @a opt pointer supplied to this function must have been
 * obtained using krb5_get_init_creds_opt_alloc()
 */
void KRB5_CALLCONV
krb5_get_init_creds_opt_set_renew_life(krb5_get_init_creds_opt *opt,
                                       krb5_deltat renew_life);

/** Set the forwardable field in krb5_get_init_creds_opt structure.
 *
 * @param [in,out] opt          Options
 * @param [in]     forwardable  Flag indicating whether credentials are forwardable
 *
 * Sets KRB5_GET_INIT_CREDS_OPT_FORWARDABLE flag in @a opt
 * The @a opt pointer supplied to this function must have been
 * obtained using krb5_get_init_creds_opt_alloc()
 */
void KRB5_CALLCONV
krb5_get_init_creds_opt_set_forwardable(krb5_get_init_creds_opt *opt,
                                        int forwardable);

/** Set the proxiable field in krb5_get_init_creds_opt structure.
 *
 * @param [in,out] opt           Options
 * @param [in]     proxiable     Flag indicating whether credentials are proxiable
 *
 * Sets KRB5_GET_INIT_CREDS_OPT_PROXYABLE flag in @a opt
 * The @a opt pointer supplied to this function must have been
 * obtained using krb5_get_init_creds_opt_alloc()
 */
void KRB5_CALLCONV
krb5_get_init_creds_opt_set_proxiable(krb5_get_init_creds_opt *opt,
                                      int proxiable);

/** Set canonicalize flag in krb5_get_init_creds_opt structure.
 *
 * @param [in,out] opt               Options
 * @param [in]     canonicalize      Boolean flag
 *
 * Sets KRB5_GET_INIT_CREDS_OPT_CANONICALIZE flag in @a opt
 *
 * The @a opt pointer supplied to this function must have been
 * obtained using krb5_get_init_creds_opt_alloc()
 */
void KRB5_CALLCONV
krb5_get_init_creds_opt_set_canonicalize(krb5_get_init_creds_opt *opt,
                                         int canonicalize);

/** Set an anonymous flag in krb5_get_init_creds_opt structure.
 *
 * @param [in,out] opt               Options
 * @param [in]     anonymous         Boolean flag
 *
 * 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.
 *
 * Sets KRB5_GET_INIT_CREDS_OPT_ANONYMOUS flag in @a opt.
 *
 * The @a opt pointer supplied to this function must have been
 * obtained using krb5_get_init_creds_opt_alloc()
 */
void KRB5_CALLCONV
krb5_get_init_creds_opt_set_anonymous(krb5_get_init_creds_opt *opt,
                                      int anonymous);

/** Set an encryption list field in the krb5_get_init_creds_opt structure.
 *
 * @param [in,out] opt                    Options
 * @param [in]     etype_list             Pointer to the encryption type to set
 * @param [in]     etype_list_length      Length of the etype_list field
 *
 * The @a opt pointer supplied to this function must have been
 * obtained using krb5_get_init_creds_opt_alloc()
 */
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 an address list field in krb5_get_init_creds_opt structure.
 *
 * @param [in,out] opt               Options
 * @param [in]     addresses         Addresses to be stored in the ticket
 *
 * Sets KRB5_GET_INIT_CREDS_OPT_ADDRESS_LIST flag in @a opt
 */
void KRB5_CALLCONV
krb5_get_init_creds_opt_set_address_list(krb5_get_init_creds_opt *opt,
                                         krb5_address **addresses);

/** Set the preauth_list field in krb5_get_init_creds_opt structure.
 *
 * @param [in,out] opt                    Options
 * @param [in]     preauth_list           Pointer to Pre-athentication type
 * @param [in]     preauth_list_length    Length of @a preauth_list field
 *
 * Sets KRB5_GET_INIT_CREDS_OPT_PREAUTH_LIST flag in @a opt
 *
 * The @a opt pointer supplied to this function must have been
 * obtained using krb5_get_init_creds_opt_alloc()
 */
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 prompt for a salt field in krb5_get_init_creds_opt structure.
 *
 * @param [in,out] opt          Options
 * @param [in]     salt         Salt data
 *
 * Sets KRB5_GET_INIT_CREDS_OPT_SALT flag in @a opt.
 */
void KRB5_CALLCONV
krb5_get_init_creds_opt_set_salt(krb5_get_init_creds_opt *opt,
                                 krb5_data *salt);

/** Set prompt for a password flag in krb5_get_init_creds_opt structure.
 *
 * @param [in,out] opt            Options
 * @param [in]     prompt         Boolean prompt to change password
 *
 * Sets KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT flag in @a opt.
 */
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;

/** Feed preauth plugins with the given options.
 *
 * @param [in,out] context           Context structure
 * @param [in]     opt               Pre options
 * @param [in]     attr              Pre attribute
 * @param [in]     value             Pre value
 *
 * 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 order
 * to check the validity of the option.
 * The @a 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);

/** Set a location of FAST cache containing TGT based on cache name.
 *
 * @param [in,out] context             Context structure
 * @param [in,out] opt                 Options
 * @param [in]     fast_ccache_name    Credential cache name
 *
 * If the @a fast_ccache_name is set, then FAST may be
 * required by the client library. Starting from MIT Kerberos version 1.8
 * FAST is used if available; krb5_get_init_creds_opt_set_fast_flags()
 * may be used to require that the request fail is FAST is unavailable.
 * In version 1.7 setting the fast ccache at all required that FAST
 * be present or the request would fail.
 * The @a 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_fast_ccache_name(krb5_context context,
                                             krb5_get_init_creds_opt *opt,
                                             const char *fast_ccache_name);

/** Set a location of FAST cache containing TGT based on krb5_ccache object.
 *
 * @param [in,out] context             Context structure
 * @param [in,out] opt                 Options
 * @param [in]     fast_ccache_name    Credential cache handle
 *
 * Set the FAST ccache name as in krb5_get_init_creds_opt_set_fast_ccache_name(),
 * but using a krb5_ccache rather than a name.
 * The @a 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_fast_ccache(krb5_context context,
                                        krb5_get_init_creds_opt *opt,
                                        krb5_ccache fast_ccache_name);

/** Set an output credentials cache in krb5_get_init_creds_opt structure.
 *
 * @param [in,out] context       Context structure
 * @param [in,out] opt           Options
 * @param [in]     ccache        Credential cache to use
 *
 * If set, then the krb5_get_init_creds family of APIs will write out credentials
 * to the given ccache. 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);

/** Store FAST flags in krb5_get_init_creds_opt structure.
 *
 * @param [in,out] context       Context structure
 * @param [in,out] opt           Options
 * @param [in]     flags         FAST flags (for example, KRB5_FAST_REQUIRED)
 *
 * This function may be used to require that the request fail if FAST is unavailable.
 *
 * @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);

/** Obtain FAST flags from krb5_get_init_creds_opt structure.
 *
 * @param [in,out] context       Context structure
 * @param [in]     opt           Options
 * @param [out]    out_flags     FAST flags
 *
 * Get FAST @a out_flags from @a opt
 * This function may be used to verify if KDC supports FAST.
 *
 * @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 expire callback in extended krb5_get_init_creds_opt structure.
 *
 * @param [in,out] context       Context structure
 * @param [in,out] opt           Options structure
 * @param [in]     cb            Callback function
 * @param [in]     data          Data
 *
 * 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.
 */
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           Context structure
 * @param [in,out] creds             Credentials structure to be filled in
 * @param [in]     client            Client principal
 * @param [in]     password          Password associated with initial credentials
 * @param [in]     prompter          Pointer to password prompt routine
 * @param [in]     data              Data for password prompt routine
 * @param [in]     start_time        Time when a ticket should become valid; 0 means from now
 * @param [in]     in_tkt_service    Service name to use while getting initial credentials
 * @param [in]     k5_gic_options    Flags and options
 *
 * This function requests KDC for an initial credentials for @a client using
 * @a password.
 *
 * @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 asynchronous context.
 *
 * @param [in] context      A krb5 library context
 * @param [in] ctx          Initial credentials context to free.
 */
void KRB5_CALLCONV
krb5_init_creds_free(krb5_context context, krb5_init_creds_context ctx);

/** Acquire credentials asynchronously.
 *
 * @param [in]     context      A krb5 library context
 * @param [in,out] ctx          Initial credentials context
 *
 * @retval 0 Success; Otherwise - Kerberos error codes
 */
krb5_error_code KRB5_CALLCONV
krb5_init_creds_get(krb5_context context, krb5_init_creds_context ctx);

/** Copy the acquired initial credentials contents.
 *
 * @param [in]  context       A krb5 library context
 * @param [in]  ctx           Initial credentials context
 * @param [out] creds         Copy of @a ctx->cred
 *
 * This function copies the acquired initial credentials from
 * @a ctx->cred into @a creds.
 * 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 data from KDC while acquiring initial credentials.
 *
 * @param [in]  context  A krb5 library context
 * @param [in]  ctx      Initial credentials context
 * @param [out] error    If non-null, contains error packet returned from KDC
 *
 * @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      A krb5 library context
 * @param [in]  client       Client principal to get initial credentials for.
 *                           If NULL - the default principal is used
 * @param [in]  prompter     Prompter
 * @param [in]  data         Prompter data
 * @param [in]  start_time   Time when credentials should become valid;
 *                           0 means from now
 * @param [in]  options      KRB5_GET_INIT_CREDS_OPT_ options for this request.
 *                           If NULL - the default options are used
 *                           (see krb5_get_init_creds_opt_init())
 * @param [out] ctx          A new initial credentials context.
 *
 * This function initializes a new context for acquiring initial credentials
 * asynchronously.
 * 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_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);

/** Specify a keytab to use for acquiring initial credentials.
 *
 * @param [in]      context  A krb5 library context
 * @param [in,out]  ctx      Initial credentials context
 * @param [in]      keytab   Key table handle
 *
 * @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);

/** Perform the next step of asynchronous initial credentials acquisition.
 *
 * @param [in]     context  A krb5 library context
 * @param [in,out] ctx      Initial credentials context
 * @param [in]     in       KDC response (empty on the first call)
 * @param [out]    out      Buffer to be sent by the caller to the KDC
 *                          for the indicated @a realm.
 * @param [out]    realm    The realm for which the next request should be sent
 * @param [out]    flags    Indicates whether more responses are needed
 *                          (see KRB5_INIT_CREDS_STEP_FLAG_CONTINUE )
 *
 * Once the credentials have been acquired, the @a out buffer is empty and
 * @a flags is set to 0. If the request should be retried with TCP,
 * KRB5KRB_ERR_RESPONSE_TOO_BIG is returned.
 *
 * @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);

/** Set a password for acquiring initial credentials.
 *
 * @param [in]      context       A krb5 library context
 * @param [in,out]  ctx           Initial credentials context
 * @param [in]      password      Password
 *
 * @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);

/** Specify a requested service for the initial credentials.
 *
 * @param [in]      context       A krb5 library context
 * @param [in,out]  ctx           Initial credentials context
 * @param [in]      service       Requested service
 *
 * The old @a ctx->in_tkt_service is overriden by the new @a service.
 *
 * @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);

/** Retrieve the ticket times from the initial credentials context.
 *
 * @param [in]  context       A krb5 library context
 * @param [in]  ctx           Initial credentials context
 * @param [out] times         Ticket times for the acquired credentials
 *
 * @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);

struct _krb5_tkt_creds_context;
typedef struct _krb5_tkt_creds_context *krb5_tkt_creds_context;

/**
 * Create a context to get credentials from a KDC's Ticket Granting Service.
 *
 * @param[in]  context  A krb5 library context (see krb5_init_context())
 * @param[in]  ccache   A credentials cache containing the desired credentials
 *                      or a Ticket Granting Ticket (TGT) for the client realm.
 *                      TGT and service credentials may be stored into this
 *                      cache as they are acquired.
 * @param[in]  creds    Input credentials
 * @param[in]  options  KRB5_GC_* options for this request.
 * @param[out] ctx      The TGS acquisition context.
 *
 * 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.
 *
 * @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);

/**
 * Synchronously obtain credentials within an acquisition context.
 *
 * @param[in]  context  A krb5 library context (see krb5_init_context())
 * @param[in]  ctx      A TGS acquisition context (see krb5_tkt_creds_init())
 *
 * This function repeatedly generates requests, sends them to the appropriate
 * realms' KDCs, and processes the replies until credentials are available for
 * retrieval with krb5_tkt_creds_get_creds().
 *
 * @retval 0  Success; Otherwise - Kerberos error codes
 */
krb5_error_code KRB5_CALLCONV
krb5_tkt_creds_get(krb5_context context, krb5_tkt_creds_context ctx);

/**
 * Retrieve credentials from an acquisition context, filling in @a creds.
 *
 * @param[in]  context  A krb5 library context (see krb5_init_context())
 * @param[in]  ctx      A TGS acquisition context (see krb5_tkt_creds_init())
 * @param[out] creds    The acquired credentials
 *
 * The acquisition context must have completed obtaining credentials via either
 * krb5_tkt_creds_get() or krb5_tkt_creds_step().
 *
 * @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);

/**
 * Release the resources used by an acquisition context.
 *
 * @param[in]  context  A krb5 library context (see krb5_init_context())
 * @param[in]  ctx      A TGS acquisition context (see krb5_tkt_creds_init())
 */
void KRB5_CALLCONV
krb5_tkt_creds_free(krb5_context context, krb5_tkt_creds_context ctx);

#define KRB5_TKT_CREDS_STEP_FLAG_CONTINUE 0x1  /* More responses needed. */

/**
 * Process a response and generate the next request to acquire credentials.
 *
 * @param[in]  context  A krb5 library context (see krb5_init_context())
 * @param[in]  ctx      A TGS acquisition context (see krb5_tkt_creds_init())
 * @param[in]  in       The last response (empty or NULL for first call)
 * @param[out] out      The next request to be sent
 * @param[out] realm    The realm to which the next request should be sent
 * @param[out] flags    Indicates whether more responses are needed
 *
 * On the first call, @a in should be empty or NULL.  If more responses are
 * needed, the @a flags output parameter will contain @a
 * KRB5_TKT_CREDS_STEP_FLAG_CONTINUE.  In that case, the caller must transport
 * @a out to a KDC for @a realm and receive a response, which should be
 * provided as @a in to the next call.
 *
 * @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);

/**
 * Retrieve ticket times for obtained credentials, filling in @a times.
 *
 * @param[in]  context  A krb5 library context (see krb5_init_context())
 * @param[in]  ctx      A TGS acquisition context (see krb5_tkt_creds_init())
 * @param[out] times    Ticket times for the acquired credentials
 *
 * The acquisition context must have completed obtaining credentials via either
 * krb5_tkt_creds_get() or krb5_tkt_creds_step().
 *
 * @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);

/** Get initial credentials using a key table.
 *
 * @param [in]  context           Context structure
 * @param [in,out] creds          Credentials structure to be filled in
 * @param [in]  client            Client principal to get initial credentials for
 * @param [in]  arg_keytab        Key table handle
 * @param [in]  start_time        Time when a ticket should become valid; 0 means from now
 * @param [in]  in_tkt_service    Service name to use while getting initial credentials
 * @param [in]  k5_gic_options    Flags and options
 *
 * This function requests initial credentials for @a client from KDC using a key
 * stored in @a arg_keytab, or from the default keytab if @a arg_keytab is NULL.
 *
 * @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; /**< boolean */
} krb5_verify_init_creds_opt;

#define KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL        0x0001

/** Initialize a @a flags field in krb5_verify_init_creds_opt structure.
 *
 * @param [out] k5_vic_options Pointer to krb5_verify_init_creds_opt structure
 *
 * Sets @a k5_vic_options flags fiels to zero.
 */
void KRB5_CALLCONV
krb5_verify_init_creds_opt_init(krb5_verify_init_creds_opt *k5_vic_options);

/** Set a @a ap_req_nofail field in krb5_verify_init_creds_opt structure.
 *
 * @param [out] k5_vic_options  Pointer to krb5_verify_init_creds_opt structure
 * @param [in]  ap_req_nofail   Boolean value to set for the ap_req_nofail field
 *
 * This function sets KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL flag and
 * ap_req_nofail field to @a ap_req_nofail in @a k5_vic_options.
 * If @a ap_req_nofail is FALSE and keytab is missing (empty or unreadable),
 * krb5_verify_init_creds() will succeed even though verification cannot be
 * performed.
 * This function may be used to override the krb5 configuration setting for
 * verify_ap_req_nofail attribute.
 */
void KRB5_CALLCONV
krb5_verify_init_creds_opt_set_ap_req_nofail(krb5_verify_init_creds_opt * k5_vic_options,
                                             int ap_req_nofail);

/** Verify initial credentials and store them in the credentials cache.
 *
 * @param [in]  context        Context structure
 * @param [in]  creds          Initial credentials to be verified
 * @param [in]  server_arg     Server principal;
 *                             if NULL - use a principal name from @a keytab_arg
 * @param [in]  keytab_arg     Key table to verify @a creds against
 * @param [out] ccache_arg     Credentials cache to store all fetched from KDC credentials
 *                             if NULL - memory credential will be used and then destroyed.
 * @param [in]  options        Pointer to krb5_verify_init_creds_opt structure
 *
 *
 * @sa krb5_verify_init_creds_opt_set_ap_req_nofail() and
 *     krb5_verify_init_creds_opt_init()
 *
 * @retval 0  Success; Otherwise - Kerberos error codes
 */
krb5_error_code KRB5_CALLCONV
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,out] context           Context structure
 * @param [out]    creds             Credential structure to fill in
 * @param [in]     client            Client principal name
 * @param [in]     ccache            Credentials cache
 * @param [in]     in_tkt_service    Principal name of requesting server
 *
 * This function gets a validated single service ticket, that is specified as
 * @a in_tkt_service parameter, from KDC.
 * It uses credentials provided by @a client and @a in_tkt_service to retrieve the
 * old existing credentials from @a ccache so they can be used to get a validated
 * credential from KDC.
 * If @a in_tkt_service is NULL, the TGT name for the client's realm will be used.
 * The result 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);

/** Get renewed credential from KDC using the existing one.
 *
 * @param [in,out] context           Context structure
 * @param [out]    creds             Credentials structure to fill in
 * @param [in]     client            Client principal name
 * @param [in]     ccache            Credentials cache
 * @param [in]     in_tkt_service    Principal name of requesting server
 *
 * This function gets a renewed single service ticket, that is specified as
 * @a in_tkt_service parameter, from KDC.
 * It uses credentials provided by @a client and @a in_tkt_service to retrieve the
 * old existing credentials from @a ccache so they can be used to get a new
 * credential from KDC.
 * If @a in_tkt_service is NULL, the TGT name for the client's realm will be used.
 * The result is placed in @a creds.
 *
 * @sa krb5_get_validated_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);

/**
 * @brief Decode a formatted ticket.
 *
 * @param code          Formatted ticket [input]
 * @param rep           Decoded ticket information [output]
 *
 * @retval
 *  0 Success
 * @retval
 *   KRB5KDC_ERR_BAD_PVNO Bad key version number
 * @return
 * Kerberos error codes
 *
 */
krb5_error_code KRB5_CALLCONV
krb5_decode_ticket(const krb5_data *code, krb5_ticket **rep);

/** Retrieve an attribute value from @a appdefaults section of krb5.conf.
 *
 * @param [in]  context           Context structure
 * @param [in]  appname           Application name
 * @param [in]  realm             Realm name
 * @param [in]  option            Option to be checked
 * @param [in]  default_value     Default Boolean 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);

/** Retrieve a booloean attribute value from @a appdefaults section of krb5.conf.
 *
 * @param [in]  context           Context structure
 * @param [in]  appname           Application name
 * @param [in]  realm             Realm name
 * @param [in]  option            Option to be checked
 * @param [in]  default_value     Default Boolean 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);

/*
 * Prompter enhancements
 */

#define KRB5_PROMPT_TYPE_PASSWORD            0x1
#define KRB5_PROMPT_TYPE_NEW_PASSWORD        0x2
#define KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN  0x3
#define KRB5_PROMPT_TYPE_PREAUTH             0x4

typedef krb5_int32 krb5_prompt_type;

/** Get @a prompt_types field from a context.
 *
 * @param [in] context           Context structure
 *
 * @return
 * Pointer to the @a krb5_prompt_type field, which contains one
 * of the following values:
 *  @li  @c KRB5_PROMPT_TYPE_PASSWORD
 *  @li  @c KRB5_PROMPT_TYPE_NEW_PASSWORD
 *  @li  @c KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN
 *  @li  @c KRB5_PROMPT_TYPE_PREAUTH
*/
krb5_prompt_type* KRB5_CALLCONV
krb5_get_prompt_types(krb5_context context);

/* Error reporting */
/** Set error message state in a context structure.
 *
 * @param [in,out] ctx           Context structure
 * @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 ctx, krb5_error_code code, const char *fmt, ...)
#if !defined(__cplusplus) && (__GNUC__ > 2)
    __attribute__((__format__(__printf__, 3, 4)))
#endif
    ;

/** Set error message state in a context structure using a precomputed va_list.
 *
 * @param [in,out] ctx           Context structure
 * @param [in]     code          Error code
 * @param [in]     fmt           Error string for the error code
 * @param [in]     args          @c va_list of arguments
 */
void KRB5_CALLCONV
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
    ;

/** Set the error message state of dest_ctx to that of src_ctx.
 *
 * @param [in] dest_ctx    Context structure where the error message state is copied to
 * @param [in] src_ctx     Context structure where the error message state is copied from
 */
void KRB5_CALLCONV
krb5_copy_error_message(krb5_context dest_ctx, krb5_context src_ctx);

/** Get error message state specific to the context.
 *
 * @param [in] ctx           Context structure
 * @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()
 *
 * @note Future versions may return the same string for the second
 * and following calls.
 */
const char * KRB5_CALLCONV
krb5_get_error_message(krb5_context ctx, krb5_error_code code);

/** Free an error message state generated by krb5_get_error_message.
 *
 * @param [in] ctx           Context structure
 * @param [in] msg           Pointer to error message
 */
void KRB5_CALLCONV
krb5_free_error_message(krb5_context cxt, const char *msg);

/** Clear the error message state.
 *
 * @param [in,out] ctx           Context structure
 *
 * Similar to krb5_free_error_message() but @a ctx->msg is set to NULL.
 */
void KRB5_CALLCONV
krb5_clear_error_message(krb5_context ctx);

krb5_error_code KRB5_CALLCONV
krb5_decode_authdata_container(krb5_context context,
                               krb5_authdatatype type,
                               const krb5_authdata *container,
                               krb5_authdata ***authdata);

krb5_error_code KRB5_CALLCONV
krb5_encode_authdata_container(krb5_context context,
                               krb5_authdatatype type,
                               krb5_authdata * const*authdata,
                               krb5_authdata ***container);

/*
 * AD-KDCIssued
 */
/** This function both encodes and signs AD-KDCIssued authorization data.
 *
 * @param [in] context        Context structure
 * @param [in] key            Session key
 * @param [in] issuer         The name of the issuing principal
 * @param [in] authdata       Authorization data to be signed
 * @param [out] ad_kdcissued  Authorization data to be filled in
 *
 * This function both encodes and signs AD-KDCIssued authorization data @a authdata
 * (RFC 4120 section 5.2.6.2). A set of authorization data @a ad_kdcissued containing
 * a single AD-KDCIssued element is returned to the caller.
 */
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);

/** Decode and verify AD-KDCIssued authorization data.
 *
 * @param [in] context      Context structure
 * @param [in] key          Session key
 * @param [in] ad_kdcissued KDC issued authorization data to be verified
 * @param [out] issuer      The name of the issuing principal to be filled in (optional)
 * @param [out] authdata    Authorization data to be filled in
 *
 * This function both decodes and verifies AD-KDCIssued authorization data @a ad_kdcissued
 * (RFC 4120 section 5.2.6.2). The @a issuer and unwrapped authorization data @a authdata
 * are returned to the caller.
 */
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);

/*
 * Windows PAC
 */

/* Microsoft defined types of data */
#define PAC_LOGON_INFO        1  /**< Logon information */
#define PAC_CREDENTIALS_INFO  2  /**< Credentials information */
#define PAC_SERVER_CHECKSUM   6  /**< Server checksum */
#define PAC_PRIVSVR_CHECKSUM  7  /**< KDC checksum */
#define PAC_CLIENT_INFO       10 /**< Client name and ticket information */
#define PAC_DELEGATION_INFO   11 /**< Client name and ticket information */
#define PAC_UPN_DNS_INFO      12 /**< User principal name and DNS information */


/** PAC data structure to convey authorization information */
struct krb5_pac_data;
typedef struct krb5_pac_data *krb5_pac;

/** Add a buffer to the provided PAC and update header.
 *
 * @param [in]     context         Context structure
 * @param [in,out] pac             PAC handle
 * @param [in]     type            Type of data contained in @a data
 * @param [in]     data            Buffer to add
 *
 * This function adds a new @a data to @a pac if there isn't already a buffer
 * of this type in @a pac.
 *
 * The valid values of @type is one of the following:
 * @li @c PAC_LOGON_INFO         -  Logon information
 * @li @c PAC_CREDENTIALS_INFO   -  Credentials information
 * @li @c PAC_SERVER_CHECKSUM    -  Server checksum
 * @li @c PAC_PRIVSVR_CHECKSUM   -  KDC checksum
 * @li @c PAC_CLIENT_INFO        -  Client name and ticket information
 * @li @c PAC_DELEGATION_INFO    -  Constrained delegation information
 * @li @c 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);

/** Free the storage assigned to a PAC.
 *
 * @param      context         Context structure
 * @param [in] pac             PAC to be freed
 *
 * This function zeros out and frees the content of a @a pac and then
 * releases @a pac itself.
 */
void KRB5_CALLCONV
krb5_pac_free(krb5_context context, krb5_pac pac);

/** Find a buffer in a PAC and copy data into output buffer.
 *
 * @param [in]     context     Context structure
 * @param [in]     pac         PAC handle
 * @param [in]     type        Type of the buffer to be copied
 * @param [out]    data        Copy of a buffer to be filled in
 *
 * 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 the types of data in the PAC.
 *
 * @param [in]     context         Context structure
 * @param [in,out] pac             PAC handle
 * @param [out]    len             Number of entries in the @a types array.
 * @param [out]    types           If non-null, contains an array of types
 *
 * Free @a types when it is no linger needed.
 *
 * @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 and initialize Privilege Attribute Certificate (PAC).
 *
 * @param [in]  context         Context structure
 * @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_init(krb5_context context, krb5_pac *pac);

/** Parse the supplied data into the newly allocated PAC.
 *
 * @param [in]  context         Context structure
 * @param [in]  ptr             PAC buffer
 * @param [in]  len             Size 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         Context structure
 * @param [in] pac             PAC handle
 * @param [in] authtime        Timestamp to be compared with one in @a pac
 * @param [in] principal       If non-null, use it to validate PAC's client name
 *                             and ticket information.
 * @param [in] server          Compare it with PAC'c server checksum.
 *                             Must not be NULL.
 * @param [in] privsvr         If non-null, compare it with PAC'c KDC checksum
 *
 * This function validates @a pac against the supplied @a server, @a privsvr,
 * @a principal and @a authtime and then, if successful, sets @a pac->verified
 * to TRUE.
 *
 * @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, marking PAC
 * as not verified.
 *
 * @retval 0 Success; Otherwise - Kerberos error codes
 */
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);

/** Allow the appplication to override the profile's allow_weak_crypto setting.
 *
 * @param [in,out] context      Context structure
 * @param [in]     enable       Boolean flag
 *
 * This function sets @a allow_weak_crypto field in @a context to @a enable.
 * It is primarily for use by aklog.
 *
 * @retval 0  (always)
 */
krb5_error_code KRB5_CALLCONV
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,out] context      Context structure
 * @param [in]     fn           Callback function name
 * @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 to allow cleanup of @a cb_data.  Supply a NULL value for @a
 * fn to disable trace callbacks within @a context.
 *
 * @return Returns KRB5_TRACE_NOSUPP if tracing is not supported in the library
 * (unless @a fn is NULL).
 */
krb5_error_code KRB5_CALLCONV
krb5_set_trace_callback(krb5_context context, krb5_trace_callback fn,
                        void *cb_data);

/** Specify a file name for directing trace events.
 *
 * @param [in,out] context      Context structure
 * @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.
 *
 * @return  KRB5_TRACE_NOSUPP if tracing is not supported in the library.
 */
krb5_error_code KRB5_CALLCONV
krb5_set_trace_filename(krb5_context context, const char *filename);

#if TARGET_OS_MAC
#    pragma pack(pop)
#endif

KRB5INT_END_DECLS

/* Don't use this!  We're going to phase it out.  It's just here to keep
   applications from breaking right away.  */
#define krb5_const const

#undef KRB5_ATTR_DEPRECATED

#endif /* KRB5_GENERAL__ */