K5Wiki - User contributions [en]

Kerberos for Windows Release Engineering

2015-06-25T22:04:56Z

BenKaduk: List the steps involved in building the official release binaries

Release Engineering notes for the Kerberos for Windows 4.0.0 release

Software to test against new builds:
* SapGUI
* OpenAFS
* SecureCRT (and SecureFX?)
* SPNEGO (in multiple browsers?)
* Adobe Keyserver a.k.a the Sassafras key client
* SMTP/IMAP via Thunderbird (must disable SSPI though?)
* LDAP in some form?
* XMPP via, e.g., Pidgin

Upgrades scenarios to test:
* 32-bit to 32-bit, from 3.2
* 64-bit to 64-bit, from 3.2
* 32-bit to 64-bit, from 3.2
* 32-bit and 64-bit to 64-bit, from 3.2
* 32-bit to 64-bit, from 4.0
* 64-bit to 32-bit, from 4.0
When starting from 3.2, it probably suffices to test the Secure Endpoints versions once only, and assume that there will not be future changes to 4.0 which cause the upgrade process to fail for the SE version but not the MIT-distributed version.
The NSIS upgrade path is a separate codepath and should be tested separately.

Current known issues:
* The version number implanted in various dlls no longer reflects the underlying krb5 version (instead using the KfW version); this may not actually be a bug.
* windows/README is outdated
* (Version) upgrades that go from 64-bit to 32-bit leave 64-bit binaries around but otherwise succeed.

Issues that we believe to be resolved:
* The uninstaller prompts to kill running processes but does not do succeed in doing so. There may be cases in which it just kills processes without prompting, which may still be a bug.
* The upgrade procedure attempts to kill running processes but does not succeed in doing so (these two may be sharing most of the code). The wix-users archives suggest that Util:CloseApplication may be useful to do this in pure WiX instead of a custom element
* There is a report of crashes on a multiprocessor machine unless CPU-pinning is used
* Uninitialized (NULL) TLS pointers that were most prominent on multi-processor machines, causing internal ccache errors that were reported as "unknown error" due to another minor bug.
* Thunderbird cannot do GSSAPI auth unless you disable SSPI
* Our DllMain attach/detach handler spews to the terminal when running command-line utilities. Possibly other debug print statements, too.

Procedure for building release binaries (MIT and non-MIT, i386 and amd64):

On the VM host:

rm -rf /path/to/share/kfw-4.1-beta2 && git archive --prefix=kfw-4.1-beta2/ [committish] | (cd /path/to/share/; tar x)
rm -rf /path/to/share/kfw-4.1-beta2-mit && git archive --prefix=kfw-4.1-beta2-mit/ [committish] | (cd /path/to/share/; tar x)
git archive --prefix=kfw-4.1-beta2/ --format=zip -o ../kfw-4.1-beta2-src.zip refs/tags/kfw-4.1-beta2

mkdir C:\destdir
mkdir C:\debug-symbols
mkdir C:\debug-symbols\kfw-NNN-i386-mit
mkdir C:\debug-symbols\kfw-NNN-amd64-mit
mkdir C:\debug-symbols\kfw-NNN-i386
mkdir C:\debug-symbols\kfw-NNN-amd64
setenv /x86 /release
set CPU=i386
set KRB_INSTALL_DIR=C:\destdir
set NODEBUG=1
set DEBUG_SYMBOL=1
set MIT_INTERNAL=1
# do the MIT i386 build
cd C:\kfw-NNN-mit\src
nmake -f Makefile.in prep-windows
nmake
nmake install
set DEBUG_SYMBOL= # unset it
mv C:\destdir\bin\*.pdb C:\debug-symbols\kfw-NNN-i386-mit
cd windows\installer\wix
nmake
rename kfw.msi kfw-NNN-i386-mit.msi
# time for the MIT amd64 build
cd ..\..\..
setenv /x64 /release
set CPU=AMD64
set DEBUG_SYMBOL=1
nmake clean
nmake
nmake install
set DEBUG_SYMBOL= # unset it
mv C:\destdir\bin\*.pdb C:\debug-symbols\kfw-NNN-amd64-mit
cd windows\installer\wix
nmake clean
nmake
rename kfw.msi kfw-NNN-amd64-mit.msi
rm -r C:\destdir\bin
rm -r C:\destdir\lib
rm -r C:\destdir\include
# fresh env for the non-MIT i386 build
setenv /x86 /release
set CPU=i386
set DEBUG_SYMBOL=1
set MIT_INTERNAL= # unset it
cd C:\kfw-NNN\src
nmake -f Makefile.in prep-windows
nmake
nmake install
set DEBUG_SYMBOL= # unset it
mv C:\destdir\bin\*.pdb C:\debug-symbols\kfw-NNN-i386
cd windows\installer\wix
nmake
rename kfw.msi kfw-NNN-i386.msi
cd ..\..\..
# the non-MIT amd64 build
setenv /x64 /release
set CPU=AMD64
set DEBUG_SYMBOL=1
nmake clean
nmake
nmake install
set DEBUG_SYMBOL= # unset it
mv C:\destdir\bin\*.pdb C:\debug-symbols\kfw-NNN-amd64
cd windows\installer\wix
nmake clean
nmake
rename kfw.msi kfw-NNN-amd64.msi
[copy C:\kfw-NNN{,-mit}\src\windows\installer\wix\*.msi to the shared drive]
[recursively copy C:\debug-symbols\kfw-NNN* to the shared drive]

On the VM host, extract the build output for signing.

Projects/White Papers

2013-12-12T17:25:53Z

BenKaduk: /* Summary of topics */

{{project-early}}

== Purpose ==

To codify in a single place assembled knowledge about the architecture of Kerberos, design considerations/assumptions and how these are present/different in real-world-environments, best practice for operational issues regarding Kerberos, and more.

== Summary of topics ==

List here topics or potential topics for white papers. Individual papers may have an outline fleshed out as a separate section.

* Revisiting the design assumptions that went into Kerberos' creation and analyzing their current validity
* Revisiting the Kerberos threat model (from Kerberos' creation) and analyzing present-day weaknesses, possibly with emphasis on preauthentication schemes
* Operational issues of relevance to running a KDC on the open internet
* (category, not necessarily a single paper) Discussion of particular enctype(s), known attacks on their ciphers/hashes, and their relevance to Kerberos
* What could "kerberos in the cloud" mean? Is there such a concept which is useful?
* Use cases for PKINIT
* Use cases for anonymous PKINIT
* Use cases for anonymous tickets (both realm-anonymous and fully-anonymous)
* Security benefits of the https proxy, and how it compares to FAST with anonmyous PKINIT

Projects/Improve GSSAPI mechanism configuration

2013-10-18T19:44:30Z

BenKaduk: spell 'each' correctly

{{project-early}}
{{project-target|1.13}}

==Requirements and scope==

The GSSAPI mechglue allows the installation of additional mechanisms, these mechanisms are currently sourced from the file /etc/gss/mech at library load time.

In order to improve management of additional mechanism as separate packages for distributions it would be easier if each package could drop a configuration fragment in a separate file to activate a new installed plugin instead of changing a signle configuration file.

==Design==

A new directory owned by the GSSAPI library is created in /etc/gss/mech.d
In this directory packages can drop configuration fragments that use the exact same configuration format of the current /etc/gss/mech file.

After the main /etc/gss/mech file has been parsed, any file in this directory is opened and parsed to find additional mechanisms to load.

Projects/Audit

2013-10-11T21:20:54Z

BenKaduk: Make the list of information available to plugin authors match reality

{{project-rel|1.12}}

== Description ==

This project creates a pluggable audit interface to allow the monitoring of security-related events on the KDC.

The interface is considered "experimental", in that API stability is not guaranteed to future major releases.

== Requirements ==

The new audit system should be:

* build-time enabled;
* run-time pluggable;
* simple and flexible, so it could be easily replaced with the OS specific and third-parties implementations;

== Events ==

We consider events under the categorization of the Common Criteria Class FIA.

This section details the categories of the auditable events and the associated data.

1. Startup and shutdown of the KDC must be recorded by audit system;

2. The bulk of the audit information will be produced while processing AS and TGS requests. Though KDC request processing can be grouped into several logical phases, we generate (usually) only two events, one at the initial receipt of a request, and a second, final, one before sending a reply. All events relating to the same request can be linked together in the audit log by a 32-character alphanumeric string (about 190 bits of uniqueness) which is randomly generated at the start of processing. If the request is a S4U2Self or S4U2Proxy request, an additional audit event will be generated with information particular to the S4U request. The following table lists the logical stages of KDC processing, and which components are logged in the AS and TGS cases:

{| class="wikitable" style="border: 3px solid #59121e"
|+
|-
! Phase
! style="padding-left: 2em; padding-right: 2em;" | Data to be logged
! AS_REQ
! TGS_REQ
|-
|rowspan=3|Authenticate request content and client
| client’s address and port || ✔ || ✔
|-
| original KDC request and [[#Request ID| request ID ]] || ✔ || ✔
|-
| primary [[#Ticket ID|ticket ID]] || ✗ ||(S4U:front-end server's) TGT
|-
|rowspan=3|Determine service principal
| modified KDC request and [[#Request ID|request ID]] ||✔ || ✔
|-
| cross-realm referral || ✗ || service principal, TGS
|-
| user-to-user: client in the 2nd ticket || ✗ ||✔
|-
|rowspan=2|Validate policies
| local policy violation ||✔ || ✔
|-
| protocol constraints ||✗ || S4U2Proxy, S4U2Self
|-
|rowspan=5|Issue ticket
| ticket renewed ||✗ || ✔
|-
| ticket validated ||✗ || ✔
|-
| session key enctype (short-term) ||✔ || ✔
|-
| enctype of the service's long-term key||✗ || ✔
|-
| derived [[#Ticket ID|ticket ID]]|| TGT || service or referral TGT
|-
|rowspan=2|Encrypt reply
| KDC reply ||✔ || ✔
|-
| Reply-encrypting key enctype (long-term) ||✔ || ✔
|-
|rowspan=1|All phases
| Additional info(KDC status,policy details,etc)|| ✔ ||✔
|-
|}

The following information will be made available to audit plugins:

: a unique request ID
: the complete KDC request structure
: the KDC reply structure (possibly only partially populated)
: the client's IP address and port number
: the stage of KDC processing at which the audit event was triggered
: the KDC status string (as appears in kdc.log)
: ticket IDs (checksums) for any supplied tickets or ticket to be returned
: the remote client's realm (for referrals)
: the impersonated user for an S4U2Self request
: the "type of violation" which caused the request to fail, if applicable

Other events to consider for the future development:

3. Further details about policy viloations
:Event description, reason and how to fix it;
4. Secrets (Common Criteria FCS_CKM.1, FCS_CKM.4);
:long- and short-term key creation, manipulation, cleaning.

== Design details ==

====Ticket ID====
Ticket ID is recorded as part of audit messages. This allows to link tickets to their initial TGT at any stage of the Kerberos exchange.

For the purpose of this project we will create a private to KDC ticket ID: each successfully created ticket will be hashed and recorded into audit log. The administrators will correlate the primary and derived ticket IDs after the fact.

For the future, however, we need a more complex system that would allow to tie the tickets from a successful AS_REQ all the way to the application server. It is marked as an action item in [[#Future work|this]] section.

====Request ID====
Request ID is a randomly generated alpha-numeric string. Using this ID an administrator can easily correlate multiple audit events related to a single request. It should be informative both in cases when the request is sent to multiple KDCs, or to the same KDC multiple times.

=== KDC facing API ===

/* Audit plugin loaded/unloaded */
krb5_error_code
load_audit_plugin(krb5_context context);
krb5_error_code
unload_audit_plugin(krb5_context context);
krb5_boolean
kau_isloaded(krb5_context context);
/* event specific functions */
krb5_error_code
kau_kdc_start(krb5_context context, const int event_id, const int status);
krb5_error_code
kau_kdc_stop(krb5_context context, const int event_id, const int status);
krb5_error_code
kau_asreq(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_tgsreq(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_s4u2self(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_s4u2proxy(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_u2u(krb5_context context, const int event_id, const int status, audit_state *state);
/* utilities */
krb5_error_code
kau_init_kdc_req(krb5_context context, krb5_kdc_req *request, const krb5_fulladdr *from, audit_state **au_state);
krb5_error_code
kau_make_tkt_id(krb5_context context, const krb5_ticket *ticket, char **out);
krb5_error_code
kau_make_req_id(krb5_context context, const krb5_kdc_req *request, char **out);

where ''event_id'' references to the ''Phase'' (left column of [[#Events| events]] table), and ''audit_state'' structure holds the following information:

typedef struct _audit_state {
krb5_kdc_req *req_in; /* request in the original form */
krb5_kdc_req *req_mod; /* modified (per protocol) request */
krb5_kdc_rep *reply;
const krb5_fulladdr *from;
const char *status; /* additional information string */
char *tkt_in_id; /* primary (TGT) ticket ID */
char *tkt_out_id; /* derived (service or referral TGT) ticket ID */
char *evid_tkt_id; /* for s4u2proxy - user's evidence ticket ID, for u2u - TGT ticket ID */
char *req_in_id; /* original-request ID */
char *req_mod_id; /* modified-request ID */
krb5_int32 sess_etype; /* session key enctype */
krb5_int32 srv_etype; /* enctype of the long-term key of service */
krb5_int32 rep_etype; /* reply-encrypting key enctype */
krb5_boolean tkt_renewed;
krb5_boolean tkt_validated;
/* referrals */
krb5_data *cl_realm; /* remote client's realm */
/* s4u and u2u */
krb5_principal s4u2self_user; /* impersonated user */
krb5_principal s4u2proxy_user; /* delegated user */
krb5_principal u2u_user; /* client for the second ticket */
char *violation; /* local or protocol policy problem */
} audit_state;

=== Pluggable interface ===

/* Audit plugin vtable */
typedef struct krb5_audit_vtable_st {
/* Mandatory: name of module. */
char *name;
int conf_options;
kau_open_fn open;
kau_close_fn close;
kau_kdc_start_fn kdc_start;
kau_kdc_stop_fn kdc_stop;
kau_as_req_fn as_req;
kau_tgs_req_fn tgs_req;
kau_s4u2self_fn tgs_s4u2self;
kau_s4u2proxy_fn tgs_s4u2proxy;
kau_u2u_fn tgs_u2u;;
} *krb5_audit_vtable;

typedef krb5_error_code
(*kau_open_fn)(kau_ctx *au_ctx);
typedef krb5_error_code
(*kau_close_fn)(kau_ctx au_ctx);
typedef krb5_error_code
(*kau_kdc_start_fn)(kau_ctx au_ctx, const int event_id, int status);
typedef krb5_error_code
(*kau_kdc_stop_fn)(kau_ctx au_ctx, const int event_id, int status);
typedef krb5_error_code
(*kau_as_req_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_tgs_req_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_s4u2self_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_s4u2proxy_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_u2u_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);

== JSON based audit module ==

We will use libaudit module available on Fedora, Debian, SuSe for the first round. The new JSON utility library will be built to parse Kerberos specific structures. The "simple" audit module will be statically linked to this library.

The following is a proposed ''Dictionary '' - the basic field names for JSON parsing:

{| class="wikitable" style="border: 3px solid #59121e"
|+
|-
! Key
! style="padding-left: 2em; padding-right: 2em;" | Type
! Comments
|-
| event_success || style="padding-left: 2em "| INT || event was success or failure
|-
| event_name || style="padding-left: 2em "| STR || name of the event (KDC_START, AS_REQ etc)
|-
| stage || style="padding-left: 2em "| INT || stage in the KDC exchange processing
|-
| tkt_id_in || style="padding-left: 2em "| STR || primary (TGT) ticket ID
|-
| tkt_id_out || style="padding-left: 2em "| STR || derived (service or referral TGT) ticket ID
|-
| req_id || style="padding-left: 2em "| STR || request ID
|-
| kdc_status || style="padding-left: 2em "| STR|| Additional information string
|-
| fromaddr || style="padding-left: 2em "| STR || client's address
|-
| fromport || style="padding-left: 2em "| NUM || client's port
|-
|sess_etype || style="padding-left: 2em "| NUM || enctype of session key
|-
|rep_etype || style="padding-left: 2em "| NUM || enctype of reply-encrypting key
|-
|srv_etype || style="padding-left: 2em "| NUM || enctype of long-term key of the service key
|-
|tkt_renewed|| style="padding-left: 2em "| BOOL || was ticket renewed
|-
|tkt_validated|| style="padding-left: 2em "| BOOL || was ticket validated
|-
|req.addresses || style="padding-left: 2em "| STR || requested addresses
|-
|req.avail_etypes || style="padding-left: 2em "| STR || requested/available enc types
|-
|req.kdc_options || style="padding-left: 2em "| NUM || KDC options (forwardable, allow_postdate etc)
|-
|req.tkt_start || style="padding-left: 2em "| NUM || requested ticket start time
|-
|req.tkt_end || style="padding-left: 2em "| NUM || requested ticket end time
|-
|req.tkt_renew_till || style="padding-left: 2em "| NUM || requested ticket renew-till time
|-
|req.tkt_authtime || style="padding-left: 2em "| NUM || requested ticket authtime
|-
| req.sectkt_cname|| style="padding-left: 2em "| STR || client principal in the second ticket (U2U etc)
|-
| req.sectkt_sname|| style="padding-left: 2em "| STR || service principal in the second ticket
|-
| req.sectkt_flags|| style="padding-left: 2em "| NUM || second ticket flags
|-
| req.sectkt_start|| style="padding-left: 2em "| NUM || second ticket start time
|-
| req.sectkt_end|| style="padding-left: 2em "| NUM || second ticket end time
|-
| req.sectkt_authtime|| style="padding-left: 2em "| NUM || second ticket authtime
|-
| req.sectkt_etype|| style="padding-left: 2em "| NUM || second ticket key type
|-
|req.sname || style="padding-left: 2em "| STR || requested service principal
|-
| req.cname || style="padding-left: 2em "| STR || client's principal
|-
|rep.sname || style="padding-left: 2em "| STR || service principal in ticket
|-
| rep.cname || style="padding-left: 2em "| STR || client principal in ticket
|-
| rep.pa_type || style="padding-left: 2em "| STR || reply preauth types
|-
| rep.rep_authtime || style="padding-left: 2em "| NUM || ticket authtime
|-
| rep.tkt_start || style="padding-left: 2em "| NUM || ticket start time
|-
| rep.tkt_end || style="padding-left: 2em "| NUM || ticket end time
|-
| rep.tkt_renew_till|| style="padding-left: 2em "| NUM || ticket renewed-till time
|-
|rep.tr_contents|| style="padding-left: 2em "| STR|| ticket transited-realms list
|-
|}

== Configuration ==

The following ./configure option to be added:

--with-audit-plugin

For example,'' --with-audit-plugin=simple'', where ''simple'' is the name of the audit plugin module

== Test ==

A testable audit module, k5audit_test, will be built, and enabled for a python test program which is added. This test module uses the internal libauditjenc library to generate a JSON encoding of the audit event, and writes that encoded string to a flat file, which is parsed by the python test program.

== Commits ==

1003f0173f266a6428ccf2c89976f0029d3ee831 KDC Audit infrastructure and plugin implementation
5036f91e7b61a73a1ec2d39ce1cc6bbf60dd82ab Fix audit test module initialization

Completed in {{bug|7712}} and {{bug|7713}}

== Release Notes ==

Administrator experience:

* Add an experimental pluggable interface for auditing KDC processing. This interface may change in a backwards-incompatible way in a future release.

==Future work==

# Standardize a ''Ticket ID'';
# Make reporting auditable events configurable. For example, one can choose to report TGS_REQ, but not AS_REQ;
# Sanitize ''KDC request'' and ''KDC reply'' before passing them to the concrete audit implementation: security sensitive information should not leave KDC boundaries;
# Develop audit system for Preauth and Authdata mechanisms.

== References ==

# Common Criteria for Information Technology Security Evaluation http://www.commoncriteriaportal.org/files/ccfiles/CCPART2V3.1R4.pdf
# Oracle Solaris Auditing http://docs.oracle.com/cd/E19963-01/html/821-1456/auditov-1.html
# Understanding Linux Audit http://doc.opensuse.org/products/draft/SLES/SLES-security_sd_draft/cha.audit.comp.html
# Advanced Security Audit Policy Settings http://technet.microsoft.com/en-us/library/dd772712(v=ws.10).aspx
# Events Classification in Log Audit http://airccse.org/journal/nsa/0410ijnsa5.pdf
# CEE Log Syntax (CLS) Encoding http://cee.mitre.org/language/1.0-beta1/cls.html

Projects/Audit

2013-10-11T21:13:35Z

BenKaduk: update the intro for the events section, listing contents to be updated in a later change

{{project-rel|1.12}}

== Description ==

This project creates a pluggable audit interface to allow the monitoring of security-related events on the KDC.

The interface is considered "experimental", in that API stability is not guaranteed to future major releases.

== Requirements ==

The new audit system should be:

* build-time enabled;
* run-time pluggable;
* simple and flexible, so it could be easily replaced with the OS specific and third-parties implementations;

== Events ==

We consider events under the categorization of the Common Criteria Class FIA.

This section details the categories of the auditable events and the associated data.

1. Startup and shutdown of the KDC must be recorded by audit system;

2. The bulk of the audit information will be produced while processing AS and TGS requests. Though KDC request processing can be grouped into several logical phases, we generate (usually) only two events, one at the initial receipt of a request, and a second, final, one before sending a reply. All events relating to the same request can be linked together in the audit log by a 32-character alphanumeric string (about 190 bits of uniqueness) which is randomly generated at the start of processing. If the request is a S4U2Self or S4U2Proxy request, an additional audit event will be generated with information particular to the S4U request. The following table lists the logical stages of KDC processing, and which components are logged in the AS and TGS cases:

{| class="wikitable" style="border: 3px solid #59121e"
|+
|-
! Phase
! style="padding-left: 2em; padding-right: 2em;" | Data to be logged
! AS_REQ
! TGS_REQ
|-
|rowspan=3|Authenticate request content and client
| client’s address and port || ✔ || ✔
|-
| original KDC request and [[#Request ID| request ID ]] || ✔ || ✔
|-
| primary [[#Ticket ID|ticket ID]] || ✗ ||(S4U:front-end server's) TGT
|-
|rowspan=3|Determine service principal
| modified KDC request and [[#Request ID|request ID]] ||✔ || ✔
|-
| cross-realm referral || ✗ || service principal, TGS
|-
| user-to-user: client in the 2nd ticket || ✗ ||✔
|-
|rowspan=2|Validate policies
| local policy violation ||✔ || ✔
|-
| protocol constraints ||✗ || S4U2Proxy, S4U2Self
|-
|rowspan=5|Issue ticket
| ticket renewed ||✗ || ✔
|-
| ticket validated ||✗ || ✔
|-
| session key enctype (short-term) ||✔ || ✔
|-
| enctype of the service's long-term key||✗ || ✔
|-
| derived [[#Ticket ID|ticket ID]]|| TGT || service or referral TGT
|-
|rowspan=2|Encrypt reply
| KDC reply ||✔ || ✔
|-
| Reply-encrypting key enctype (long-term) ||✔ || ✔
|-
|rowspan=1|All phases
| Additional info(KDC status,policy details,etc)|| ✔ ||✔
|-
|}

The following information will be made available to audit plugins:

KDC request:
: requested service principal;
: client’s principal;
: KDC options;
: requested ticket start, end and renew_till times;
: list of requested addresses;
: requested enctypes;
: preauth types

KDC reply:
: preauth types;
: TGT, referral TGT or service ticket with the following level of details:
::client and server principals;
::flags;
::start, end and renew_till times;
::authtime;
::authentication path - encoded list of transited realms for service ticket or referral TGT (for TGS only);

Other events to consider for the future development:

3. Policy
:Policies violation - event description, reason and how to fix it;
4. Secrets (Common Criteria FCS_CKM.1, FCS_CKM.4);
:long- and short-term keys creation, manipulation, cleaning.

== Design details ==

====Ticket ID====
Ticket ID is recorded as part of audit messages. This allows to link tickets to their initial TGT at any stage of the Kerberos exchange.

For the purpose of this project we will create a private to KDC ticket ID: each successfully created ticket will be hashed and recorded into audit log. The administrators will correlate the primary and derived ticket IDs after the fact.

For the future, however, we need a more complex system that would allow to tie the tickets from a successful AS_REQ all the way to the application server. It is marked as an action item in [[#Future work|this]] section.

====Request ID====
Request ID is a randomly generated alpha-numeric string. Using this ID an administrator can easily correlate multiple audit events related to a single request. It should be informative both in cases when the request is sent to multiple KDCs, or to the same KDC multiple times.

=== KDC facing API ===

/* Audit plugin loaded/unloaded */
krb5_error_code
load_audit_plugin(krb5_context context);
krb5_error_code
unload_audit_plugin(krb5_context context);
krb5_boolean
kau_isloaded(krb5_context context);
/* event specific functions */
krb5_error_code
kau_kdc_start(krb5_context context, const int event_id, const int status);
krb5_error_code
kau_kdc_stop(krb5_context context, const int event_id, const int status);
krb5_error_code
kau_asreq(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_tgsreq(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_s4u2self(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_s4u2proxy(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_u2u(krb5_context context, const int event_id, const int status, audit_state *state);
/* utilities */
krb5_error_code
kau_init_kdc_req(krb5_context context, krb5_kdc_req *request, const krb5_fulladdr *from, audit_state **au_state);
krb5_error_code
kau_make_tkt_id(krb5_context context, const krb5_ticket *ticket, char **out);
krb5_error_code
kau_make_req_id(krb5_context context, const krb5_kdc_req *request, char **out);

where ''event_id'' references to the ''Phase'' (left column of [[#Events| events]] table), and ''audit_state'' structure holds the following information:

typedef struct _audit_state {
krb5_kdc_req *req_in; /* request in the original form */
krb5_kdc_req *req_mod; /* modified (per protocol) request */
krb5_kdc_rep *reply;
const krb5_fulladdr *from;
const char *status; /* additional information string */
char *tkt_in_id; /* primary (TGT) ticket ID */
char *tkt_out_id; /* derived (service or referral TGT) ticket ID */
char *evid_tkt_id; /* for s4u2proxy - user's evidence ticket ID, for u2u - TGT ticket ID */
char *req_in_id; /* original-request ID */
char *req_mod_id; /* modified-request ID */
krb5_int32 sess_etype; /* session key enctype */
krb5_int32 srv_etype; /* enctype of the long-term key of service */
krb5_int32 rep_etype; /* reply-encrypting key enctype */
krb5_boolean tkt_renewed;
krb5_boolean tkt_validated;
/* referrals */
krb5_data *cl_realm; /* remote client's realm */
/* s4u and u2u */
krb5_principal s4u2self_user; /* impersonated user */
krb5_principal s4u2proxy_user; /* delegated user */
krb5_principal u2u_user; /* client for the second ticket */
char *violation; /* local or protocol policy problem */
} audit_state;

=== Pluggable interface ===

/* Audit plugin vtable */
typedef struct krb5_audit_vtable_st {
/* Mandatory: name of module. */
char *name;
int conf_options;
kau_open_fn open;
kau_close_fn close;
kau_kdc_start_fn kdc_start;
kau_kdc_stop_fn kdc_stop;
kau_as_req_fn as_req;
kau_tgs_req_fn tgs_req;
kau_s4u2self_fn tgs_s4u2self;
kau_s4u2proxy_fn tgs_s4u2proxy;
kau_u2u_fn tgs_u2u;;
} *krb5_audit_vtable;

typedef krb5_error_code
(*kau_open_fn)(kau_ctx *au_ctx);
typedef krb5_error_code
(*kau_close_fn)(kau_ctx au_ctx);
typedef krb5_error_code
(*kau_kdc_start_fn)(kau_ctx au_ctx, const int event_id, int status);
typedef krb5_error_code
(*kau_kdc_stop_fn)(kau_ctx au_ctx, const int event_id, int status);
typedef krb5_error_code
(*kau_as_req_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_tgs_req_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_s4u2self_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_s4u2proxy_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_u2u_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);

== JSON based audit module ==

We will use libaudit module available on Fedora, Debian, SuSe for the first round. The new JSON utility library will be built to parse Kerberos specific structures. The "simple" audit module will be statically linked to this library.

The following is a proposed ''Dictionary '' - the basic field names for JSON parsing:

{| class="wikitable" style="border: 3px solid #59121e"
|+
|-
! Key
! style="padding-left: 2em; padding-right: 2em;" | Type
! Comments
|-
| event_success || style="padding-left: 2em "| INT || event was success or failure
|-
| event_name || style="padding-left: 2em "| STR || name of the event (KDC_START, AS_REQ etc)
|-
| stage || style="padding-left: 2em "| INT || stage in the KDC exchange processing
|-
| tkt_id_in || style="padding-left: 2em "| STR || primary (TGT) ticket ID
|-
| tkt_id_out || style="padding-left: 2em "| STR || derived (service or referral TGT) ticket ID
|-
| req_id || style="padding-left: 2em "| STR || request ID
|-
| kdc_status || style="padding-left: 2em "| STR|| Additional information string
|-
| fromaddr || style="padding-left: 2em "| STR || client's address
|-
| fromport || style="padding-left: 2em "| NUM || client's port
|-
|sess_etype || style="padding-left: 2em "| NUM || enctype of session key
|-
|rep_etype || style="padding-left: 2em "| NUM || enctype of reply-encrypting key
|-
|srv_etype || style="padding-left: 2em "| NUM || enctype of long-term key of the service key
|-
|tkt_renewed|| style="padding-left: 2em "| BOOL || was ticket renewed
|-
|tkt_validated|| style="padding-left: 2em "| BOOL || was ticket validated
|-
|req.addresses || style="padding-left: 2em "| STR || requested addresses
|-
|req.avail_etypes || style="padding-left: 2em "| STR || requested/available enc types
|-
|req.kdc_options || style="padding-left: 2em "| NUM || KDC options (forwardable, allow_postdate etc)
|-
|req.tkt_start || style="padding-left: 2em "| NUM || requested ticket start time
|-
|req.tkt_end || style="padding-left: 2em "| NUM || requested ticket end time
|-
|req.tkt_renew_till || style="padding-left: 2em "| NUM || requested ticket renew-till time
|-
|req.tkt_authtime || style="padding-left: 2em "| NUM || requested ticket authtime
|-
| req.sectkt_cname|| style="padding-left: 2em "| STR || client principal in the second ticket (U2U etc)
|-
| req.sectkt_sname|| style="padding-left: 2em "| STR || service principal in the second ticket
|-
| req.sectkt_flags|| style="padding-left: 2em "| NUM || second ticket flags
|-
| req.sectkt_start|| style="padding-left: 2em "| NUM || second ticket start time
|-
| req.sectkt_end|| style="padding-left: 2em "| NUM || second ticket end time
|-
| req.sectkt_authtime|| style="padding-left: 2em "| NUM || second ticket authtime
|-
| req.sectkt_etype|| style="padding-left: 2em "| NUM || second ticket key type
|-
|req.sname || style="padding-left: 2em "| STR || requested service principal
|-
| req.cname || style="padding-left: 2em "| STR || client's principal
|-
|rep.sname || style="padding-left: 2em "| STR || service principal in ticket
|-
| rep.cname || style="padding-left: 2em "| STR || client principal in ticket
|-
| rep.pa_type || style="padding-left: 2em "| STR || reply preauth types
|-
| rep.rep_authtime || style="padding-left: 2em "| NUM || ticket authtime
|-
| rep.tkt_start || style="padding-left: 2em "| NUM || ticket start time
|-
| rep.tkt_end || style="padding-left: 2em "| NUM || ticket end time
|-
| rep.tkt_renew_till|| style="padding-left: 2em "| NUM || ticket renewed-till time
|-
|rep.tr_contents|| style="padding-left: 2em "| STR|| ticket transited-realms list
|-
|}

== Configuration ==

The following ./configure option to be added:

--with-audit-plugin

For example,'' --with-audit-plugin=simple'', where ''simple'' is the name of the audit plugin module

== Test ==

A testable audit module, k5audit_test, will be built, and enabled for a python test program which is added. This test module uses the internal libauditjenc library to generate a JSON encoding of the audit event, and writes that encoded string to a flat file, which is parsed by the python test program.

== Commits ==

1003f0173f266a6428ccf2c89976f0029d3ee831 KDC Audit infrastructure and plugin implementation
5036f91e7b61a73a1ec2d39ce1cc6bbf60dd82ab Fix audit test module initialization

Completed in {{bug|7712}} and {{bug|7713}}

== Release Notes ==

Administrator experience:

* Add an experimental pluggable interface for auditing KDC processing. This interface may change in a backwards-incompatible way in a future release.

==Future work==

# Standardize a ''Ticket ID'';
# Make reporting auditable events configurable. For example, one can choose to report TGS_REQ, but not AS_REQ;
# Sanitize ''KDC request'' and ''KDC reply'' before passing them to the concrete audit implementation: security sensitive information should not leave KDC boundaries;
# Develop audit system for Preauth and Authdata mechanisms.

== References ==

# Common Criteria for Information Technology Security Evaluation http://www.commoncriteriaportal.org/files/ccfiles/CCPART2V3.1R4.pdf
# Oracle Solaris Auditing http://docs.oracle.com/cd/E19963-01/html/821-1456/auditov-1.html
# Understanding Linux Audit http://doc.opensuse.org/products/draft/SLES/SLES-security_sd_draft/cha.audit.comp.html
# Advanced Security Audit Policy Settings http://technet.microsoft.com/en-us/library/dd772712(v=ws.10).aspx
# Events Classification in Log Audit http://airccse.org/journal/nsa/0410ijnsa5.pdf
# CEE Log Syntax (CLS) Encoding http://cee.mitre.org/language/1.0-beta1/cls.html

Projects/Audit

2013-10-11T21:00:46Z

BenKaduk: this time, for sure

{{project-rel|1.12}}

== Description ==

This project creates a pluggable audit interface to allow the monitoring of security-related events on the KDC.

The interface is considered "experimental", in that API stability is not guaranteed to future major releases.

== Requirements ==

The new audit system should be:

* build-time enabled;
* run-time pluggable;
* simple and flexible, so it could be easily replaced with the OS specific and third-parties implementations;

== Events ==

(Common Criteria Class FIA)

This section details the categories of the auditable events and the associated data.

1. Startup and shutdown of the KDC must be recorded by audit system;

2. AS_REQ and TGS_REQ:

{| class="wikitable" style="border: 3px solid #59121e"
|+
|-
! Phase
! style="padding-left: 2em; padding-right: 2em;" | Data to be logged
! AS_REQ
! TGS_REQ
|-
|rowspan=3|Authenticate request content and client
| client’s address and port || ✔ || ✔
|-
| original KDC request and [[#Request ID| request ID ]] || ✔ || ✔
|-
| primary [[#Ticket ID|ticket ID]] || ✗ ||(S4U:front-end server's) TGT
|-
|rowspan=3|Determine service principal
| modified KDC request and [[#Request ID|request ID]] ||✔ || ✔
|-
| cross-realm referral || ✗ || service principal, TGS
|-
| user-to-user: client in the 2nd ticket || ✗ ||✔
|-
|rowspan=2|Validate policies
| local policy violation ||✔ || ✔
|-
| protocol constraints ||✗ || S4U2Proxy, S4U2Self
|-
|rowspan=5|Issue ticket
| ticket renewed ||✗ || ✔
|-
| ticket validated ||✗ || ✔
|-
| session key enctype (short-term) ||✔ || ✔
|-
| enctype of the service's long-term key||✗ || ✔
|-
| derived [[#Ticket ID|ticket ID]]|| TGT || service or referral TGT
|-
|rowspan=2|Encrypt reply
| KDC reply ||✔ || ✔
|-
| Reply-encrypting key enctype (long-term) ||✔ || ✔
|-
|rowspan=1|All phases
| Additional info(KDC status,policy details,etc)|| ✔ ||✔
|-
|}

The implementors of audit plugin will be able to extract the following auditable information:

KDC request:
: requested service principal;
: client’s principal;
: KDC options;
: requested ticket start, end and renew_till times;
: list of requested addresses;
: requested enctypes;
: preauth types

KDC reply:
: preauth types;
: TGT, referral TGT or service ticket with the following level of details:
::client and server principals;
::flags;
::start, end and renew_till times;
::authtime;
::authentication path - encoded list of transited realms for service ticket or referral TGT (for TGS only);

Other events to consider for the future development:

3. Policy
:Policies violation - event description, reason and how to fix it;
4. Secrets (Common Criteria FCS_CKM.1, FCS_CKM.4);
:long- and short-term keys creation, manipulation, cleaning.

== Design details ==

====Ticket ID====
Ticket ID is recorded as part of audit messages. This allows to link tickets to their initial TGT at any stage of the Kerberos exchange.

For the purpose of this project we will create a private to KDC ticket ID: each successfully created ticket will be hashed and recorded into audit log. The administrators will correlate the primary and derived ticket IDs after the fact.

For the future, however, we need a more complex system that would allow to tie the tickets from a successful AS_REQ all the way to the application server. It is marked as an action item in [[#Future work|this]] section.

====Request ID====
Request ID is a randomly generated alpha-numeric string. Using this ID an administrator can easily correlate multiple audit events related to a single request. It should be informative both in cases when the request is sent to multiple KDCs, or to the same KDC multiple times.

=== KDC facing API ===

/* Audit plugin loaded/unloaded */
krb5_error_code
load_audit_plugin(krb5_context context);
krb5_error_code
unload_audit_plugin(krb5_context context);
krb5_boolean
kau_isloaded(krb5_context context);
/* event specific functions */
krb5_error_code
kau_kdc_start(krb5_context context, const int event_id, const int status);
krb5_error_code
kau_kdc_stop(krb5_context context, const int event_id, const int status);
krb5_error_code
kau_asreq(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_tgsreq(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_s4u2self(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_s4u2proxy(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_u2u(krb5_context context, const int event_id, const int status, audit_state *state);
/* utilities */
krb5_error_code
kau_init_kdc_req(krb5_context context, krb5_kdc_req *request, const krb5_fulladdr *from, audit_state **au_state);
krb5_error_code
kau_make_tkt_id(krb5_context context, const krb5_ticket *ticket, char **out);
krb5_error_code
kau_make_req_id(krb5_context context, const krb5_kdc_req *request, char **out);

where ''event_id'' references to the ''Phase'' (left column of [[#Events| events]] table), and ''audit_state'' structure holds the following information:

typedef struct _audit_state {
krb5_kdc_req *req_in; /* request in the original form */
krb5_kdc_req *req_mod; /* modified (per protocol) request */
krb5_kdc_rep *reply;
const krb5_fulladdr *from;
const char *status; /* additional information string */
char *tkt_in_id; /* primary (TGT) ticket ID */
char *tkt_out_id; /* derived (service or referral TGT) ticket ID */
char *evid_tkt_id; /* for s4u2proxy - user's evidence ticket ID, for u2u - TGT ticket ID */
char *req_in_id; /* original-request ID */
char *req_mod_id; /* modified-request ID */
krb5_int32 sess_etype; /* session key enctype */
krb5_int32 srv_etype; /* enctype of the long-term key of service */
krb5_int32 rep_etype; /* reply-encrypting key enctype */
krb5_boolean tkt_renewed;
krb5_boolean tkt_validated;
/* referrals */
krb5_data *cl_realm; /* remote client's realm */
/* s4u and u2u */
krb5_principal s4u2self_user; /* impersonated user */
krb5_principal s4u2proxy_user; /* delegated user */
krb5_principal u2u_user; /* client for the second ticket */
char *violation; /* local or protocol policy problem */
} audit_state;

=== Pluggable interface ===

/* Audit plugin vtable */
typedef struct krb5_audit_vtable_st {
/* Mandatory: name of module. */
char *name;
int conf_options;
kau_open_fn open;
kau_close_fn close;
kau_kdc_start_fn kdc_start;
kau_kdc_stop_fn kdc_stop;
kau_as_req_fn as_req;
kau_tgs_req_fn tgs_req;
kau_s4u2self_fn tgs_s4u2self;
kau_s4u2proxy_fn tgs_s4u2proxy;
kau_u2u_fn tgs_u2u;;
} *krb5_audit_vtable;

typedef krb5_error_code
(*kau_open_fn)(kau_ctx *au_ctx);
typedef krb5_error_code
(*kau_close_fn)(kau_ctx au_ctx);
typedef krb5_error_code
(*kau_kdc_start_fn)(kau_ctx au_ctx, const int event_id, int status);
typedef krb5_error_code
(*kau_kdc_stop_fn)(kau_ctx au_ctx, const int event_id, int status);
typedef krb5_error_code
(*kau_as_req_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_tgs_req_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_s4u2self_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_s4u2proxy_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_u2u_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);

== JSON based audit module ==

We will use libaudit module available on Fedora, Debian, SuSe for the first round. The new JSON utility library will be built to parse Kerberos specific structures. The "simple" audit module will be statically linked to this library.

The following is a proposed ''Dictionary '' - the basic field names for JSON parsing:

{| class="wikitable" style="border: 3px solid #59121e"
|+
|-
! Key
! style="padding-left: 2em; padding-right: 2em;" | Type
! Comments
|-
| event_success || style="padding-left: 2em "| INT || event was success or failure
|-
| event_name || style="padding-left: 2em "| STR || name of the event (KDC_START, AS_REQ etc)
|-
| stage || style="padding-left: 2em "| INT || stage in the KDC exchange processing
|-
| tkt_id_in || style="padding-left: 2em "| STR || primary (TGT) ticket ID
|-
| tkt_id_out || style="padding-left: 2em "| STR || derived (service or referral TGT) ticket ID
|-
| req_id || style="padding-left: 2em "| STR || request ID
|-
| kdc_status || style="padding-left: 2em "| STR|| Additional information string
|-
| fromaddr || style="padding-left: 2em "| STR || client's address
|-
| fromport || style="padding-left: 2em "| NUM || client's port
|-
|sess_etype || style="padding-left: 2em "| NUM || enctype of session key
|-
|rep_etype || style="padding-left: 2em "| NUM || enctype of reply-encrypting key
|-
|srv_etype || style="padding-left: 2em "| NUM || enctype of long-term key of the service key
|-
|tkt_renewed|| style="padding-left: 2em "| BOOL || was ticket renewed
|-
|tkt_validated|| style="padding-left: 2em "| BOOL || was ticket validated
|-
|req.addresses || style="padding-left: 2em "| STR || requested addresses
|-
|req.avail_etypes || style="padding-left: 2em "| STR || requested/available enc types
|-
|req.kdc_options || style="padding-left: 2em "| NUM || KDC options (forwardable, allow_postdate etc)
|-
|req.tkt_start || style="padding-left: 2em "| NUM || requested ticket start time
|-
|req.tkt_end || style="padding-left: 2em "| NUM || requested ticket end time
|-
|req.tkt_renew_till || style="padding-left: 2em "| NUM || requested ticket renew-till time
|-
|req.tkt_authtime || style="padding-left: 2em "| NUM || requested ticket authtime
|-
| req.sectkt_cname|| style="padding-left: 2em "| STR || client principal in the second ticket (U2U etc)
|-
| req.sectkt_sname|| style="padding-left: 2em "| STR || service principal in the second ticket
|-
| req.sectkt_flags|| style="padding-left: 2em "| NUM || second ticket flags
|-
| req.sectkt_start|| style="padding-left: 2em "| NUM || second ticket start time
|-
| req.sectkt_end|| style="padding-left: 2em "| NUM || second ticket end time
|-
| req.sectkt_authtime|| style="padding-left: 2em "| NUM || second ticket authtime
|-
| req.sectkt_etype|| style="padding-left: 2em "| NUM || second ticket key type
|-
|req.sname || style="padding-left: 2em "| STR || requested service principal
|-
| req.cname || style="padding-left: 2em "| STR || client's principal
|-
|rep.sname || style="padding-left: 2em "| STR || service principal in ticket
|-
| rep.cname || style="padding-left: 2em "| STR || client principal in ticket
|-
| rep.pa_type || style="padding-left: 2em "| STR || reply preauth types
|-
| rep.rep_authtime || style="padding-left: 2em "| NUM || ticket authtime
|-
| rep.tkt_start || style="padding-left: 2em "| NUM || ticket start time
|-
| rep.tkt_end || style="padding-left: 2em "| NUM || ticket end time
|-
| rep.tkt_renew_till|| style="padding-left: 2em "| NUM || ticket renewed-till time
|-
|rep.tr_contents|| style="padding-left: 2em "| STR|| ticket transited-realms list
|-
|}

== Configuration ==

The following ./configure option to be added:

--with-audit-plugin

For example,'' --with-audit-plugin=simple'', where ''simple'' is the name of the audit plugin module

== Test ==

A testable audit module, k5audit_test, will be built, and enabled for a python test program which is added. This test module uses the internal libauditjenc library to generate a JSON encoding of the audit event, and writes that encoded string to a flat file, which is parsed by the python test program.

== Commits ==

1003f0173f266a6428ccf2c89976f0029d3ee831 KDC Audit infrastructure and plugin implementation
5036f91e7b61a73a1ec2d39ce1cc6bbf60dd82ab Fix audit test module initialization

Completed in {{bug|7712}} and {{bug|7713}}

== Release Notes ==

Administrator experience:

* Add an experimental pluggable interface for auditing KDC processing. This interface may change in a backwards-incompatible way in a future release.

==Future work==

# Standardize a ''Ticket ID'';
# Make reporting auditable events configurable. For example, one can choose to report TGS_REQ, but not AS_REQ;
# Sanitize ''KDC request'' and ''KDC reply'' before passing them to the concrete audit implementation: security sensitive information should not leave KDC boundaries;
# Develop audit system for Preauth and Authdata mechanisms.

== References ==

# Common Criteria for Information Technology Security Evaluation http://www.commoncriteriaportal.org/files/ccfiles/CCPART2V3.1R4.pdf
# Oracle Solaris Auditing http://docs.oracle.com/cd/E19963-01/html/821-1456/auditov-1.html
# Understanding Linux Audit http://doc.opensuse.org/products/draft/SLES/SLES-security_sd_draft/cha.audit.comp.html
# Advanced Security Audit Policy Settings http://technet.microsoft.com/en-us/library/dd772712(v=ws.10).aspx
# Events Classification in Log Audit http://airccse.org/journal/nsa/0410ijnsa5.pdf
# CEE Log Syntax (CLS) Encoding http://cee.mitre.org/language/1.0-beta1/cls.html

Projects/Audit

2013-10-11T20:59:06Z

BenKaduk: make the 'test' section reflect reality

{{project-rel|1.12}}

== Description ==

This project creates a pluggable audit interface to allow the monitoring of security-related events on the KDC.

The interface is considered "experimental", in that API stability is not guaranteed to future major releases.

== Requirements ==

The new audit system should be:

* build-time enabled;
* run-time pluggable;
* simple and flexible, so it could be easily replaced with the OS specific and third-parties implementations;

== Events ==

(Common Criteria Class FIA)

This section details the categories of the auditable events and the associated data.

1. Startup and shutdown of the KDC must be recorded by audit system;

2. AS_REQ and TGS_REQ:

{| class="wikitable" style="border: 3px solid #59121e"
|+
|-
! Phase
! style="padding-left: 2em; padding-right: 2em;" | Data to be logged
! AS_REQ
! TGS_REQ
|-
|rowspan=3|Authenticate request content and client
| client’s address and port || ✔ || ✔
|-
| original KDC request and [[#Request ID| request ID ]] || ✔ || ✔
|-
| primary [[#Ticket ID|ticket ID]] || ✗ ||(S4U:front-end server's) TGT
|-
|rowspan=3|Determine service principal
| modified KDC request and [[#Request ID|request ID]] ||✔ || ✔
|-
| cross-realm referral || ✗ || service principal, TGS
|-
| user-to-user: client in the 2nd ticket || ✗ ||✔
|-
|rowspan=2|Validate policies
| local policy violation ||✔ || ✔
|-
| protocol constraints ||✗ || S4U2Proxy, S4U2Self
|-
|rowspan=5|Issue ticket
| ticket renewed ||✗ || ✔
|-
| ticket validated ||✗ || ✔
|-
| session key enctype (short-term) ||✔ || ✔
|-
| enctype of the service's long-term key||✗ || ✔
|-
| derived [[#Ticket ID|ticket ID]]|| TGT || service or referral TGT
|-
|rowspan=2|Encrypt reply
| KDC reply ||✔ || ✔
|-
| Reply-encrypting key enctype (long-term) ||✔ || ✔
|-
|rowspan=1|All phases
| Additional info(KDC status,policy details,etc)|| ✔ ||✔
|-
|}

The implementors of audit plugin will be able to extract the following auditable information:

KDC request:
: requested service principal;
: client’s principal;
: KDC options;
: requested ticket start, end and renew_till times;
: list of requested addresses;
: requested enctypes;
: preauth types

KDC reply:
: preauth types;
: TGT, referral TGT or service ticket with the following level of details:
::client and server principals;
::flags;
::start, end and renew_till times;
::authtime;
::authentication path - encoded list of transited realms for service ticket or referral TGT (for TGS only);

Other events to consider for the future development:

3. Policy
:Policies violation - event description, reason and how to fix it;
4. Secrets (Common Criteria FCS_CKM.1, FCS_CKM.4);
:long- and short-term keys creation, manipulation, cleaning.

== Design details ==

====Ticket ID====
Ticket ID is recorded as part of audit messages. This allows to link tickets to their initial TGT at any stage of the Kerberos exchange.

For the purpose of this project we will create a private to KDC ticket ID: each successfully created ticket will be hashed and recorded into audit log. The administrators will correlate the primary and derived ticket IDs after the fact.

For the future, however, we need a more complex system that would allow to tie the tickets from a successful AS_REQ all the way to the application server. It is marked as an action item in [[#Future work|this]] section.

====Request ID====
Request ID is a randomly generated alpha-numeric string. Using this ID an administrator can easily correlate multiple audit events related to a single request. It should be informative both in cases when the request is sent to multiple KDCs, or to the same KDC multiple times.

=== KDC facing API ===

/* Audit plugin loaded/unloaded */
krb5_error_code
load_audit_plugin(krb5_context context);
krb5_error_code
unload_audit_plugin(krb5_context context);
krb5_boolean
kau_isloaded(krb5_context context);
/* event specific functions */
krb5_error_code
kau_kdc_start(krb5_context context, const int event_id, const int status);
krb5_error_code
kau_kdc_stop(krb5_context context, const int event_id, const int status);
krb5_error_code
kau_asreq(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_tgsreq(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_s4u2self(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_s4u2proxy(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_u2u(krb5_context context, const int event_id, const int status, audit_state *state);
/* utilities */
krb5_error_code
kau_init_kdc_req(krb5_context context, krb5_kdc_req *request, const krb5_fulladdr *from, audit_state **au_state);
krb5_error_code
kau_make_tkt_id(krb5_context context, const krb5_ticket *ticket, char **out);
krb5_error_code
kau_make_req_id(krb5_context context, const krb5_kdc_req *request, char **out);

where ''event_id'' references to the ''Phase'' (left column of [[#Events| events]] table), and ''audit_state'' structure holds the following information:

typedef struct _audit_state {
krb5_kdc_req *req_in; /* request in the original form */
krb5_kdc_req *req_mod; /* modified (per protocol) request */
krb5_kdc_rep *reply;
const krb5_fulladdr *from;
const char *status; /* additional information string */
char *tkt_in_id; /* primary (TGT) ticket ID */
char *tkt_out_id; /* derived (service or referral TGT) ticket ID */
char *evid_tkt_id; /* for s4u2proxy - user's evidence ticket ID, for u2u - TGT ticket ID */
char *req_in_id; /* original-request ID */
char *req_mod_id; /* modified-request ID */
krb5_int32 sess_etype; /* session key enctype */
krb5_int32 srv_etype; /* enctype of the long-term key of service */
krb5_int32 rep_etype; /* reply-encrypting key enctype */
krb5_boolean tkt_renewed;
krb5_boolean tkt_validated;
/* referrals */
krb5_data *cl_realm; /* remote client's realm */
/* s4u and u2u */
krb5_principal s4u2self_user; /* impersonated user */
krb5_principal s4u2proxy_user; /* delegated user */
krb5_principal u2u_user; /* client for the second ticket */
char *violation; /* local or protocol policy problem */
} audit_state;

=== Pluggable interface ===

/* Audit plugin vtable */
typedef struct krb5_audit_vtable_st {
/* Mandatory: name of module. */
char *name;
int conf_options;
kau_open_fn open;
kau_close_fn close;
kau_kdc_start_fn kdc_start;
kau_kdc_stop_fn kdc_stop;
kau_as_req_fn as_req;
kau_tgs_req_fn tgs_req;
kau_s4u2self_fn tgs_s4u2self;
kau_s4u2proxy_fn tgs_s4u2proxy;
kau_u2u_fn tgs_u2u;;
} *krb5_audit_vtable;

typedef krb5_error_code
(*kau_open_fn)(kau_ctx *au_ctx);
typedef krb5_error_code
(*kau_close_fn)(kau_ctx au_ctx);
typedef krb5_error_code
(*kau_kdc_start_fn)(kau_ctx au_ctx, const int event_id, int status);
typedef krb5_error_code
(*kau_kdc_stop_fn)(kau_ctx au_ctx, const int event_id, int status);
typedef krb5_error_code
(*kau_as_req_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_tgs_req_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_s4u2self_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_s4u2proxy_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_u2u_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);

== JSON based audit module ==

We will use libaudit module available on Fedora, Debian, SuSe for the first round. The new JSON utility library will be built to parse Kerberos specific structures. The "simple" audit module will be statically linked to this library.

The following is a proposed ''Dictionary '' - the basic field names for JSON parsing:

{| class="wikitable" style="border: 3px solid #59121e"
|+
|-
! Key
! style="padding-left: 2em; padding-right: 2em;" | Type
! Comments
|-
| event_success || style="padding-left: 2em "| INT || event was success or failure
|-
| event_name || style="padding-left: 2em "| STR || name of the event (KDC_START, AS_REQ etc)
|-
| stage || style="padding-left: 2em "| INT || stage in the KDC exchange processing
|-
| tkt_id_in || style="padding-left: 2em "| STR || primary (TGT) ticket ID
|-
| tkt_id_out || style="padding-left: 2em "| STR || derived (service or referral TGT) ticket ID
|-
| req_id || style="padding-left: 2em "| STR || request ID
|-
| kdc_status || style="padding-left: 2em "| STR|| Additional information string
|-
| fromaddr || style="padding-left: 2em "| STR || client's address
|-
| fromport || style="padding-left: 2em "| NUM || client's port
|-
|sess_etype || style="padding-left: 2em "| NUM || enctype of session key
|-
|rep_etype || style="padding-left: 2em "| NUM || enctype of reply-encrypting key
|-
|srv_etype || style="padding-left: 2em "| NUM || enctype of long-term key of the service key
|-
|tkt_renewed|| style="padding-left: 2em "| BOOL || was ticket renewed
|-
|tkt_validated|| style="padding-left: 2em "| BOOL || was ticket validated
|-
|req.addresses || style="padding-left: 2em "| STR || requested addresses
|-
|req.avail_etypes || style="padding-left: 2em "| STR || requested/available enc types
|-
|req.kdc_options || style="padding-left: 2em "| NUM || KDC options (forwardable, allow_postdate etc)
|-
|req.tkt_start || style="padding-left: 2em "| NUM || requested ticket start time
|-
|req.tkt_end || style="padding-left: 2em "| NUM || requested ticket end time
|-
|req.tkt_renew_till || style="padding-left: 2em "| NUM || requested ticket renew-till time
|-
|req.tkt_authtime || style="padding-left: 2em "| NUM || requested ticket authtime
|-
| req.sectkt_cname|| style="padding-left: 2em "| STR || client principal in the second ticket (U2U etc)
|-
| req.sectkt_sname|| style="padding-left: 2em "| STR || service principal in the second ticket
|-
| req.sectkt_flags|| style="padding-left: 2em "| NUM || second ticket flags
|-
| req.sectkt_start|| style="padding-left: 2em "| NUM || second ticket start time
|-
| req.sectkt_end|| style="padding-left: 2em "| NUM || second ticket end time
|-
| req.sectkt_authtime|| style="padding-left: 2em "| NUM || second ticket authtime
|-
| req.sectkt_etype|| style="padding-left: 2em "| NUM || second ticket key type
|-
|req.sname || style="padding-left: 2em "| STR || requested service principal
|-
| req.cname || style="padding-left: 2em "| STR || client's principal
|-
|rep.sname || style="padding-left: 2em "| STR || service principal in ticket
|-
| rep.cname || style="padding-left: 2em "| STR || client principal in ticket
|-
| rep.pa_type || style="padding-left: 2em "| STR || reply preauth types
|-
| rep.rep_authtime || style="padding-left: 2em "| NUM || ticket authtime
|-
| rep.tkt_start || style="padding-left: 2em "| NUM || ticket start time
|-
| rep.tkt_end || style="padding-left: 2em "| NUM || ticket end time
|-
| rep.tkt_renew_till|| style="padding-left: 2em "| NUM || ticket renewed-till time
|-
|rep.tr_contents|| style="padding-left: 2em "| STR|| ticket transited-realms list
|-
|}

== Configuration ==

The following ./configure option to be added:

--with-audit-plugin

For example,'' --with-audit-plugin=simple'', where ''simple'' is the name of the audit plugin module

== Test ==

A testable audit module, au_test, will be built, and enabled for a python test program which is added. This test module uses the internal libauditjenc library to generate a JSON encoding of the audit event, and writes that encoded string to a flat file, which is parsed by the python test program.

== Commits ==

1003f0173f266a6428ccf2c89976f0029d3ee831 KDC Audit infrastructure and plugin implementation
5036f91e7b61a73a1ec2d39ce1cc6bbf60dd82ab Fix audit test module initialization

Completed in {{bug|7712}} and {{bug|7713}}

== Release Notes ==

Administrator experience:

* Add an experimental pluggable interface for auditing KDC processing. This interface may change in a backwards-incompatible way in a future release.

==Future work==

# Standardize a ''Ticket ID'';
# Make reporting auditable events configurable. For example, one can choose to report TGS_REQ, but not AS_REQ;
# Sanitize ''KDC request'' and ''KDC reply'' before passing them to the concrete audit implementation: security sensitive information should not leave KDC boundaries;
# Develop audit system for Preauth and Authdata mechanisms.

== References ==

# Common Criteria for Information Technology Security Evaluation http://www.commoncriteriaportal.org/files/ccfiles/CCPART2V3.1R4.pdf
# Oracle Solaris Auditing http://docs.oracle.com/cd/E19963-01/html/821-1456/auditov-1.html
# Understanding Linux Audit http://doc.opensuse.org/products/draft/SLES/SLES-security_sd_draft/cha.audit.comp.html
# Advanced Security Audit Policy Settings http://technet.microsoft.com/en-us/library/dd772712(v=ws.10).aspx
# Events Classification in Log Audit http://airccse.org/journal/nsa/0410ijnsa5.pdf
# CEE Log Syntax (CLS) Encoding http://cee.mitre.org/language/1.0-beta1/cls.html

Projects/Audit

2013-10-11T20:10:58Z

BenKaduk: Add commits and relnotes entries, move to projects/1.12, note experimental nature

{{project-rel|1.12}}

== Description ==

This project creates a pluggable audit interface to allow the monitoring of security-related events on the KDC.

The interface is considered "experimental", in that API stability is not guaranteed to future major releases.

== Requirements ==

The new audit system should be:

* build-time enabled;
* run-time pluggable;
* simple and flexible, so it could be easily replaced with the OS specific and third-parties implementations;

== Events ==

(Common Criteria Class FIA)

This section details the categories of the auditable events and the associated data.

1. Startup and shutdown of the KDC must be recorded by audit system;

2. AS_REQ and TGS_REQ:

{| class="wikitable" style="border: 3px solid #59121e"
|+
|-
! Phase
! style="padding-left: 2em; padding-right: 2em;" | Data to be logged
! AS_REQ
! TGS_REQ
|-
|rowspan=3|Authenticate request content and client
| client’s address and port || ✔ || ✔
|-
| original KDC request and [[#Request ID| request ID ]] || ✔ || ✔
|-
| primary [[#Ticket ID|ticket ID]] || ✗ ||(S4U:front-end server's) TGT
|-
|rowspan=3|Determine service principal
| modified KDC request and [[#Request ID|request ID]] ||✔ || ✔
|-
| cross-realm referral || ✗ || service principal, TGS
|-
| user-to-user: client in the 2nd ticket || ✗ ||✔
|-
|rowspan=2|Validate policies
| local policy violation ||✔ || ✔
|-
| protocol constraints ||✗ || S4U2Proxy, S4U2Self
|-
|rowspan=5|Issue ticket
| ticket renewed ||✗ || ✔
|-
| ticket validated ||✗ || ✔
|-
| session key enctype (short-term) ||✔ || ✔
|-
| enctype of the service's long-term key||✗ || ✔
|-
| derived [[#Ticket ID|ticket ID]]|| TGT || service or referral TGT
|-
|rowspan=2|Encrypt reply
| KDC reply ||✔ || ✔
|-
| Reply-encrypting key enctype (long-term) ||✔ || ✔
|-
|rowspan=1|All phases
| Additional info(KDC status,policy details,etc)|| ✔ ||✔
|-
|}

The implementors of audit plugin will be able to extract the following auditable information:

KDC request:
: requested service principal;
: client’s principal;
: KDC options;
: requested ticket start, end and renew_till times;
: list of requested addresses;
: requested enctypes;
: preauth types

KDC reply:
: preauth types;
: TGT, referral TGT or service ticket with the following level of details:
::client and server principals;
::flags;
::start, end and renew_till times;
::authtime;
::authentication path - encoded list of transited realms for service ticket or referral TGT (for TGS only);

Other events to consider for the future development:

3. Policy
:Policies violation - event description, reason and how to fix it;
4. Secrets (Common Criteria FCS_CKM.1, FCS_CKM.4);
:long- and short-term keys creation, manipulation, cleaning.

== Design details ==

====Ticket ID====
Ticket ID is recorded as part of audit messages. This allows to link tickets to their initial TGT at any stage of the Kerberos exchange.

For the purpose of this project we will create a private to KDC ticket ID: each successfully created ticket will be hashed and recorded into audit log. The administrators will correlate the primary and derived ticket IDs after the fact.

For the future, however, we need a more complex system that would allow to tie the tickets from a successful AS_REQ all the way to the application server. It is marked as an action item in [[#Future work|this]] section.

====Request ID====
Request ID is a randomly generated alpha-numeric string. Using this ID an administrator can easily correlate multiple audit events related to a single request. It should be informative both in cases when the request is sent to multiple KDCs, or to the same KDC multiple times.

=== KDC facing API ===

/* Audit plugin loaded/unloaded */
krb5_error_code
load_audit_plugin(krb5_context context);
krb5_error_code
unload_audit_plugin(krb5_context context);
krb5_boolean
kau_isloaded(krb5_context context);
/* event specific functions */
krb5_error_code
kau_kdc_start(krb5_context context, const int event_id, const int status);
krb5_error_code
kau_kdc_stop(krb5_context context, const int event_id, const int status);
krb5_error_code
kau_asreq(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_tgsreq(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_s4u2self(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_s4u2proxy(krb5_context context, const int event_id, const int status, audit_state *state);
krb5_error_code
kau_u2u(krb5_context context, const int event_id, const int status, audit_state *state);
/* utilities */
krb5_error_code
kau_init_kdc_req(krb5_context context, krb5_kdc_req *request, const krb5_fulladdr *from, audit_state **au_state);
krb5_error_code
kau_make_tkt_id(krb5_context context, const krb5_ticket *ticket, char **out);
krb5_error_code
kau_make_req_id(krb5_context context, const krb5_kdc_req *request, char **out);

where ''event_id'' references to the ''Phase'' (left column of [[#Events| events]] table), and ''audit_state'' structure holds the following information:

typedef struct _audit_state {
krb5_kdc_req *req_in; /* request in the original form */
krb5_kdc_req *req_mod; /* modified (per protocol) request */
krb5_kdc_rep *reply;
const krb5_fulladdr *from;
const char *status; /* additional information string */
char *tkt_in_id; /* primary (TGT) ticket ID */
char *tkt_out_id; /* derived (service or referral TGT) ticket ID */
char *evid_tkt_id; /* for s4u2proxy - user's evidence ticket ID, for u2u - TGT ticket ID */
char *req_in_id; /* original-request ID */
char *req_mod_id; /* modified-request ID */
krb5_int32 sess_etype; /* session key enctype */
krb5_int32 srv_etype; /* enctype of the long-term key of service */
krb5_int32 rep_etype; /* reply-encrypting key enctype */
krb5_boolean tkt_renewed;
krb5_boolean tkt_validated;
/* referrals */
krb5_data *cl_realm; /* remote client's realm */
/* s4u and u2u */
krb5_principal s4u2self_user; /* impersonated user */
krb5_principal s4u2proxy_user; /* delegated user */
krb5_principal u2u_user; /* client for the second ticket */
char *violation; /* local or protocol policy problem */
} audit_state;

=== Pluggable interface ===

/* Audit plugin vtable */
typedef struct krb5_audit_vtable_st {
/* Mandatory: name of module. */
char *name;
int conf_options;
kau_open_fn open;
kau_close_fn close;
kau_kdc_start_fn kdc_start;
kau_kdc_stop_fn kdc_stop;
kau_as_req_fn as_req;
kau_tgs_req_fn tgs_req;
kau_s4u2self_fn tgs_s4u2self;
kau_s4u2proxy_fn tgs_s4u2proxy;
kau_u2u_fn tgs_u2u;;
} *krb5_audit_vtable;

typedef krb5_error_code
(*kau_open_fn)(kau_ctx *au_ctx);
typedef krb5_error_code
(*kau_close_fn)(kau_ctx au_ctx);
typedef krb5_error_code
(*kau_kdc_start_fn)(kau_ctx au_ctx, const int event_id, int status);
typedef krb5_error_code
(*kau_kdc_stop_fn)(kau_ctx au_ctx, const int event_id, int status);
typedef krb5_error_code
(*kau_as_req_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_tgs_req_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_s4u2self_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_s4u2proxy_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);
typedef krb5_error_code
(*kau_u2u_fn)(kau_ctx au_ctx, const int event_id, int status, audit_state *state);

== JSON based audit module ==

We will use libaudit module available on Fedora, Debian, SuSe for the first round. The new JSON utility library will be built to parse Kerberos specific structures. The "simple" audit module will be statically linked to this library.

The following is a proposed ''Dictionary '' - the basic field names for JSON parsing:

{| class="wikitable" style="border: 3px solid #59121e"
|+
|-
! Key
! style="padding-left: 2em; padding-right: 2em;" | Type
! Comments
|-
| event_success || style="padding-left: 2em "| INT || event was success or failure
|-
| event_name || style="padding-left: 2em "| STR || name of the event (KDC_START, AS_REQ etc)
|-
| stage || style="padding-left: 2em "| INT || stage in the KDC exchange processing
|-
| tkt_id_in || style="padding-left: 2em "| STR || primary (TGT) ticket ID
|-
| tkt_id_out || style="padding-left: 2em "| STR || derived (service or referral TGT) ticket ID
|-
| req_id || style="padding-left: 2em "| STR || request ID
|-
| kdc_status || style="padding-left: 2em "| STR|| Additional information string
|-
| fromaddr || style="padding-left: 2em "| STR || client's address
|-
| fromport || style="padding-left: 2em "| NUM || client's port
|-
|sess_etype || style="padding-left: 2em "| NUM || enctype of session key
|-
|rep_etype || style="padding-left: 2em "| NUM || enctype of reply-encrypting key
|-
|srv_etype || style="padding-left: 2em "| NUM || enctype of long-term key of the service key
|-
|tkt_renewed|| style="padding-left: 2em "| BOOL || was ticket renewed
|-
|tkt_validated|| style="padding-left: 2em "| BOOL || was ticket validated
|-
|req.addresses || style="padding-left: 2em "| STR || requested addresses
|-
|req.avail_etypes || style="padding-left: 2em "| STR || requested/available enc types
|-
|req.kdc_options || style="padding-left: 2em "| NUM || KDC options (forwardable, allow_postdate etc)
|-
|req.tkt_start || style="padding-left: 2em "| NUM || requested ticket start time
|-
|req.tkt_end || style="padding-left: 2em "| NUM || requested ticket end time
|-
|req.tkt_renew_till || style="padding-left: 2em "| NUM || requested ticket renew-till time
|-
|req.tkt_authtime || style="padding-left: 2em "| NUM || requested ticket authtime
|-
| req.sectkt_cname|| style="padding-left: 2em "| STR || client principal in the second ticket (U2U etc)
|-
| req.sectkt_sname|| style="padding-left: 2em "| STR || service principal in the second ticket
|-
| req.sectkt_flags|| style="padding-left: 2em "| NUM || second ticket flags
|-
| req.sectkt_start|| style="padding-left: 2em "| NUM || second ticket start time
|-
| req.sectkt_end|| style="padding-left: 2em "| NUM || second ticket end time
|-
| req.sectkt_authtime|| style="padding-left: 2em "| NUM || second ticket authtime
|-
| req.sectkt_etype|| style="padding-left: 2em "| NUM || second ticket key type
|-
|req.sname || style="padding-left: 2em "| STR || requested service principal
|-
| req.cname || style="padding-left: 2em "| STR || client's principal
|-
|rep.sname || style="padding-left: 2em "| STR || service principal in ticket
|-
| rep.cname || style="padding-left: 2em "| STR || client principal in ticket
|-
| rep.pa_type || style="padding-left: 2em "| STR || reply preauth types
|-
| rep.rep_authtime || style="padding-left: 2em "| NUM || ticket authtime
|-
| rep.tkt_start || style="padding-left: 2em "| NUM || ticket start time
|-
| rep.tkt_end || style="padding-left: 2em "| NUM || ticket end time
|-
| rep.tkt_renew_till|| style="padding-left: 2em "| NUM || ticket renewed-till time
|-
|rep.tr_contents|| style="padding-left: 2em "| STR|| ticket transited-realms list
|-
|}

== Configuration ==

The following ./configure option to be added:

--with-audit-plugin

For example,'' --with-audit-plugin=simple'', where ''simple'' is the name of the audit plugin module

== Test ==

Python test system will become aware of the existence of "simple" json-based audit plugin module. Running "make check" will result in storing audit messages into audit log file.

== Commits ==

1003f0173f266a6428ccf2c89976f0029d3ee831 KDC Audit infrastructure and plugin implementation
5036f91e7b61a73a1ec2d39ce1cc6bbf60dd82ab Fix audit test module initialization

Completed in {{bug|7712}} and {{bug|7713}}

== Release Notes ==

Administrator experience:

* Add an experimental pluggable interface for auditing KDC processing. This interface may change in a backwards-incompatible way in a future release.

==Future work==

# Standardize a ''Ticket ID'';
# Make reporting auditable events configurable. For example, one can choose to report TGS_REQ, but not AS_REQ;
# Sanitize ''KDC request'' and ''KDC reply'' before passing them to the concrete audit implementation: security sensitive information should not leave KDC boundaries;
# Develop audit system for Preauth and Authdata mechanisms.

== References ==

# Common Criteria for Information Technology Security Evaluation http://www.commoncriteriaportal.org/files/ccfiles/CCPART2V3.1R4.pdf
# Oracle Solaris Auditing http://docs.oracle.com/cd/E19963-01/html/821-1456/auditov-1.html
# Understanding Linux Audit http://doc.opensuse.org/products/draft/SLES/SLES-security_sd_draft/cha.audit.comp.html
# Advanced Security Audit Policy Settings http://technet.microsoft.com/en-us/library/dd772712(v=ws.10).aspx
# Events Classification in Log Audit http://airccse.org/journal/nsa/0410ijnsa5.pdf
# CEE Log Syntax (CLS) Encoding http://cee.mitre.org/language/1.0-beta1/cls.html

Projects/White Papers

2013-10-09T17:18:45Z

BenKaduk: /* Summary of topics */

Projects/White Papers

2013-05-30T17:39:50Z

BenKaduk: /* Summary of topics */

Projects/White Papers

2013-05-30T14:58:04Z

BenKaduk: Project page for tracking white paper ideas

Manual Testing

2012-11-21T23:47:37Z

BenKaduk: /* Valgrind */

This page describes manual testing procedures. There are two reasons these exist:

# Manual testing is sometimes simpler than running an automated test and instrumenting it.
# In some cases we have a manual testing procedure for part of the code, but not an automated test.

We do have an automated [[Test suite]].

==Basic Test KDC Setup==

Test KDCs are a crucial building block of testing. You can set one up easily by running "make testrealm" in the top level of a build tree, or you can follow these steps to set one up by hand:

1. Pick a name for your test KDC; this example will assume EXAMPLE.COM.

2. Do a build and install of the krb5 sources into some prefix; this example will assume /usr/local, but anywhere is fine. Put the prefix's bin and sbin directories in your path, or use full pathnames for the commands below.

3. Pick two port numbers, for the KDC and admin server. This example will assume 50000 and 50001.

4. Set up a krb5.conf file somewhere; this example will assume /usr/local/etc/krb5.conf. Make it look something like:
[libdefaults]
default_realm = EXAMPLE.COM
# Depending on what you are testing, you may want something like:
# default_keytab_name = FILE:/usr/local/var/keytab
[realms]
EXAMPLE.COM = {
admin_server = 127.0.0.1:50001
kdc = 127.0.0.1:50000
database_module = DB2
kdc_ports = 50000
kadmind_port = 50001
}
[dbmodules]
DB2 = {
db_library = db2
}
[logging]
# Use any pathnames you want here.
kdc = FILE:/usr/local/var/krb5kdc/kdc.log
admin_server = FILE:/usr/local/var/krb5kdc/kadmin.log
# Depending on what you are testing, you may want:
# [domain_realm]
# .your.domain = EXAMPLE.COM
Set the environment variable KRB5_CONFIG to the pathname of this krb5.conf file. Set the environment variable KRB5_KDC_PROFILE to /dev/null.

5. Run:
kdb5_util create -s
Enter a master password; it can be something insecure like "master". The DB will be created in /usr/local/var/krb5kdc/principal and a few other similarly-named files. The master key stash will be created in /usr/local/var/krb5kdc/.k5.EXAMPLE.COM.

6. Run:
kadmin.local
addprinc user
quit
Enter a user password; it can be something insecure like "user".

7. Start the KDC by running:
krb5kdc
Check the log file specified in krb5.conf if the KDC has any trouble starting. You should be able to "kinit user" at this point.

8. If you need kadmind, add another principle user/admin (using kadmin.local as described above), and create the file /usr/local/var/krb5kdc/kadm5.acl containing:
user/admin *
Then start the kadmind server with:
kadmind
If it has trouble starting, check the log file specified in krb5.conf.

==Services4User testing==

A test for Services4User can be found in tests/gssapi/t_s4u.c. You will need a W2K3 or higher AD domain to test this. Notes follow:

* Create a computer account FOO$ using Active Directory Users & Computers (ADUC)
* Set the UPN to host/foo.domain (no suffix); this is necessary to be able to send an AS-REQ as this principal, otherwise you would need to use the canonical name (FOO$), which will cause principal comparison errors in gss_accept_sec_context() (note: apparently only W2K8 supports suffix-less UPNs; you should use the domain as a suffix for earlier versions). There is an attribute editor in the W2K8 ADUC that lets you do this, otherwise you will need to use LDP.exe or a generic LDAP client.
* Add a SPN of host/foo.domain. (Again, you can use ADUC in W2K8, or LDP.exe/generic client.)
* Configure the computer account to support constrained delegation with protocol transition (Trust this computer for delegation to specified services only / Use any authentication protocol)
* Add host/foo.domain to the keytab (possibly easiest to do this manually with ktadd)

For S4U2Proxy to work the TGT must be forwardable too.

<pre>
kinit -k -t test.keytab -f 'host/test.win.mit.edu@WIN.MIT.EDU'
./t_s4u delegtest@WIN.MIT.EDU HOST/winhost.win.mit.edu@WIN.MIT.EDU test.keytab
</pre>

In the above example delegtest@WIN.MIT.EDU is the principal on whose behalf credentials are acquired using S4U2Self; HOST/winhost.win.mit.edu is the host to which we wish to delegate using S4U2Proxy; and test.keytab contains the long term key for test.win.mit.edu.

To test S4U2Self with the MIT KDC, set the ok_to_auth_as_delegate attribute on the service principal using kadmin.

==GSS-API Naming Extensions testing==

Note: the S4U test also tests the GSS-API naming extensions, but there also is a specific test in tests/gssapi/t_namingexts.c. This tests the following APIs:

* gss_import_name() with composite names
* gss_inquire_name()
* gss_get_name_attribute()
* gss_set_name_attribute()
* gss_delete_name_attribute()
* gss_export_name_composite()
* gss_map_name_to_any
* gss_release_any_name_mapping

Note: gss_display_name_ext() is not tested because we don't yet have a concrete implementation of it.

The usage of this test is:

<pre>
t_namingexts [--spnego] [principal] [keytab]
</pre>

where the optional --spnego argument uses the SPNEGO (as opposed to the krb5) mechanism; principal is the service principal to test with, and keytab is a path to the keytab containing the key for the service principal. (The client and service principal are identical in the test. To test with another client principal, use the S4U test.)

You likely want to test this against a Windows KDC, in order to validate PAC introspection; however, you can also test with the greet_client (and greet_server) plugins that are included in plugins/authdata/greet_{client,server}.

==Principal lockout testing==

There are now some automated lockout tests, but these procedures are still helpful for examining some edge cases.

Testing for lockout is identical for the LDAP and DB2 backends, although if you wish to test the replication functionality, you'll need to use a DB2 backend. No changes are required for configuring kprop/iprop; it's business as usual (the only difference being that lockout-related attributes will not be replicated, so as part of testing you should verify on each KDC that this is the case).

First, you need to create a password policy that specifies a lockout policy. Do this with kadmin. Here we create a policy where a maximum failure count of 3, a failure count reset interval of 180 seconds, and a lockout duration of 60 seconds.

<pre>
kadmin: addpol -maxfailure 3 -failurecountinterval 180 -lockoutduration 60 lockout_test
</pre>

Then, you need to associate a principal with the lockout policy. Note also that the pre-authentication required attribute must be set on the principal; principals without this attribute set are not subject to the lockout policy (as they are not required to prove knowledge of their long-term key to the KDC).

<pre>
kadmin: modprinc -policy lockout_test +requires_preauth lukeh
Principal "lukeh@MIT.DE.PADL.COM" modified.
</pre>

Now, perform a successful authentication with kinit. You should see the last successful authentication timestamp updated in the information returned by kadmin:

<pre>
kadmin: getprinc lukeh
...
Last successful authentication: Wed Oct 07 14:07:08 CEST 2009
</pre>

Perform an unsuccessful authentication (ie. kinit with an incorrect password) and you should see the failed authentication timestamp and count updated:

<pre>
kadmin: getprinc lukeh
...
Last failed authentication: Wed Oct 07 14:07:58 CEST 2009
Failed password attempts: 1
Account locked time: [never]
</pre>

Another two authentication failures (recall, the maximum failure count above is 3) and you should see that the principal is locked out:

<pre>
kadmin: getprinc lukeh
...
Last failed authentication: Wed Oct 07 14:08:37 CEST 2009
Failed password attempts: 3
Account locked time: Wed Oct 07 14:08:37 CEST 2009
</pre>

You can try to unlock the account explicitly with <i>modprinc -unlock</i>, or you can wait the lockout duration (here, 60 seconds) and you should be able to authenticate again.

==KDC worker processes==

There is a very basic automated test of parallel KDC worker processes, but it doesn't ensure that all worker processes can receive packets. To test that, make the following temporary code modifications:

* In plugins/kdb/db2/kdb_db2.c:krb5_db2_get_principal(), add this code near the beginning:

if (searchfor->length >= 1 &&
data_eq_string(searchfor->data[0], "slowuser"))
sleep(60);

* In lib/krb5/os/sendto_kdc.c, change MAX_PASS from 3 to 1, and in krb5_sendto_kdc() change all assignments of socktype2 to 0. This ensures that kinit will only send one request.

* In util/k5test.py, change the default arguments for the start_kdc() realm method like so:

def start_kdc(self, args=['-w', '3']):

Build the sources and run "make testrealm". You should be able to run "kinit slowuser" three times before the KDC becomes unresponsive to "kinit user".

==SAM-2 preauth client code==

The securid_sam2 preauth module isn't built by default and ordinarily only compiles successfully in the presence of the RSA ACE library. But it can be built with alternate flags to use a test method which can help exercise the client SAM-2 preauth code in send-encrypted-sad mode.

* First, build the securid_sam2 module with the test method instead of the securid method:

cd plugins/preauth/securid_sam2
make DEFINES='-DGRAIL_PREAUTH' ACELIB=
cd ../../..

* Start with a basic test realm:

make testrealm

* Edit testdir/krb5.master.conf and add the following to register the module. Make sure to specify the correct absolute path to the module shared object, which will depend on where your build directory is located.

[plugins]
kdcpreauth = {
module = securid_sam2:/path/to/plugins/preauth/securid_sam2/securid_sam2.so
}

* Do the following in kadmin.local:

addprinc -randkey user/GRAIL
modprinc +requires_hwauth user

* Restart the KDC (find the pid of the running krb5kdc process, kill it, and then run "krb5kdc").

* Run "kinit user". If you enter the correct password for user and correctly echo the challenge, you should get tickets. If you enter either one wrong, you should get an error.

* Remember to kill your krb5kdc process after exiting the test realm; the test realm code won't clean up the one you started by hand.

==Valgrind==

Many of the automated tests are configured to optionally be run under valgrind, a memory checking tool. However, some tests will fail if there is extra output on stdout or stderr, such as that written by valgrind's summary report. Manually running the test suite under valgrind can be done with

make VALGRIND='${VALGRIND1}' check

The VALGRIND1 variable is set automatically by the build system to run with the memory checker, a log file at BUILDTOP/vg.[pid] and a list of known warnings to suppress. It is a make variable, not a shell/environment variable, so it must be quoted on the command line.

In order to get more useful stack traces from valgrind, it may be useful to add RTLD_NODELETE to the flags passed to dlopen() in src/util/support/plugins.c (if your platform supports that flag). Compiling with debugging symbols is also useful.

Manual Testing

2012-11-21T21:35:40Z

BenKaduk: recommended way to run tests with valgrind

Projects/Documentation Tasks

2012-11-13T19:54:19Z

BenKaduk: spelling

{{project-early}}

== Purpose ==

To keep track of the various tasks that need to be documented such as function documentation, administration, troubleshooting etc.

{| class="wikitable"
|+ Matrix of Document-Type VS Intended Readership
|-
! Doc-type/Reader
! Architectural Guide
! Setup & Config of Kerberos
! Admin & Operations of Kerberos
! Custom Build
! API Description
! API Details
|-
|-
| End-users || || || || || ||
|-
| Architects || || || || || ||
|-
|System Admins || || || || || ||
|-
|Application Developers || || || || || ||
|-
|GSSAPI Developers || || || || || ||
|-
|Kerberos Developers || || || || || ||
|}

== Application development ==

{| class="wikitable"
|+
|-
! task
! Proposed Author
! Target Date
! Reviewer
! Reviewer Comments
|-
|-
| Designing a new protocol, or extending existing one, to use GSS-API || NW || || ||
|-
| Choosing security API|| || || ||
|-
| <ul><li> GSS-API vs SASL vs KRB5 </ul>|| NW || || ||
|-
| <ul><li> A guide to the similarities and differences between Heimdal and MIT Kerberos API </ul>|| NW || || ||
|-
| GSS-API || || || ||
|-
| <ul><li> A basic introduction to GSS-API, making use of the sample client and server, with special attention paid to Kerberos-related GSS-API issues</ul>|| NW || || ||
|-
| <ul><li> How to tell the GSS-API library on the client side where the existing Kerberos ticket cache is </ul>|| NW || || ||
|-
| <ul><li> How to write mechanism-independent GSS-API code</ul>|| NW || || ||
|-
| <ul><li> Acceptor naming - How to get servers to use any key in a keytab</ul>|| GH||2012-03-01|| || DONE
|-
| <ul><li> A guide to GSS-API naming as compared to Kerberos principal naming</ul>|| NW || || ||
|-
| <ul><li> Using IAKERB</ul>|| || || ||
|-
| <ul><li> Anonymous credentials</ul>|| GH ||2012-10-01 || ||
|-
| <ul><li> Delegating credentials</ul>|| GH ||2012-10-01 || ||
|-
| <ul><li> Available extensions</ul>|| NW || || ||
|-
| <ul><li> Thread safety</ul>|| KR || || ||
|-
| <ul><li> Validating the flags set on the connection to ensure things like mutual authentication, confidentiality, integrity, replay protection, and sequence protection</ul>|| || || ||
|-
| Developing plugins|| GH ||2012-03-08|| || ready for review
|-
| <ul><li> A guide to developing plugins </ul>|| || || || DONE
|-
| <ul><li>Overview of existing pluggable interfaces </ul>|| || ||ZT reviewed profile plugin || DONE
|-
| Krb5 library guide|| || || ||
|-
| <ul><li> A more advanced introduction to using the Kerberos libraries for initial authentication, focusing on the authentication steps, validating initial credential</ul>|| TY || 2012-04-27 ||need examples ||
|-
| <ul><li> Kerberos prompter behavior</ul>|| NW || || ||
|-
| <ul><li> An introduction to ticket caches and keytabs and their corresponding APIs </ul>|| KR || || || under review
|-
| <ul><li> An advanced guide to the pre-auth mechanisms, FAST</ul>|| || || ||
|-
| <ul><li> An advanced guide to the principal manipulation and parsing</ul>|| TY || TBD || ||
|-
| <ul><li> Thread safety</ul>|| KR || || ||
|-
| <ul><li> Password change including the automatic internal support for password change on expired passwords if a prompter is provided</ul>|| || || ||
|-
| <ul><li> krb5_appdefault_* functions and their alternatives </ul>|| || || ||
|-
| MIT Kerberos features : quick facts || ZT || ongoing || || DONE
|-
| How to build Kerberos from source || ZT || || || DONE
|-
|}

== Administration ==

{| class="wikitable"
|+
|-
! task
! Proposed Author
! Target Date
! Reviewer
! Reviewer Comments
|-
| Introduction to Kerberos system || || || ||
|-
|<ul><li>Man page </ul>|| TH || 2012-08-15|| ||
|-
|<ul><li>General overview</ul>|| TH ||2012-08-15 || ||
|-
|<ul><li>Intro for admins</ul>|| TH ||2012-08-15 || ||
|-
|<ul><li>Technical overview</ul>|| TH ||2012-07-15 || ||under review
|-
|Setting a new realm|| || || ||
|-
|<ul><li>Choosing backend: LDAP vs DB2</ul>|| || || ||
|-
|<ul><li>Replication</ul>|| ZT|| || || DONE
|-
|<ul><li> DNS configuration and SRV records - how they are used, in what order</ul>|| KR || || ||
|-
| Reverse DNS|| TY|| 2012-10-01|| ||
|-
| Choosing encryption types for principals|| TY|| 2012-10-01|| ||
|-
| Integration Kerberos with Login System|| || || ||
|-
| <ul><li> Difference between real Kerberos authentication, Kerberos password verification on the server side, and "LDAP authentication" in a Kerberos environment</ul>|| || || ||
|-
| <ul><li> Validating Kerberos tickets</ul>|| || || ||
|-
| <ul><li> Clear text password over HTTPS </ul>|| NW || || ||
|-
| <ul><li> Configuring with pam_krb5 module</ul>|| NW || || ||
|-
| <ul><li> Storing/locating keytab</ul>|| || || ||
|-
| Cross-realm|| || || ||
|-
| <ul><li>cross-realm interaction with AD </ul>|| || || ||
|-
| <ul><li> Transitive trust</ul>|| || || ||
|-
| <ul><li> Referrals</ul>|| || || ||
|-
| Performance|| || || ||
|-
| <ul><li> Performance tuning tips</ul>|| || || ||
|-
| <ul><li> Performance tradeoffs</ul>|| || || ||
|-
| kadmin interface|| || || ||
|-
| <ul><li> Keying workstation/ host key setting</ul>|| || || ||
|-
| Using Smartcard with PKINIT|| || || ||
|-
| Kerberized ssh|| NW || || ||
|-
| <ul><li> Configuration</ul>|| || || ||
|-
| <ul><li>Cross-realm and ssh</ul>|| || || ||
|-
| Selecting and configuring plugins|| GH ||2012-03-15|| || DONE
|-
| Anonymity support|| GH ||2012-10-01 || ||
|-
| A guide to principal naming basics and structure|| || || ||
|-
| Troubleshooting|| || || ||
|-
| <ul><li>Troubleshooting errors</ul> || ZT || ongoing|| ||
|-
| <ul><li>Trace logging</ul>||GH ||2012-03-22|| ||DONE
|-
| <ul><li>Realm renaming </ul>|| || || ||
|-
| Using LDAP server for Kerberos backend|| ZT || || || Ubuntu 10.4 (lucid) DONE
|-
| Basic concepts (passwd policy, ticket ) || || || ||
|-
| Approaches to authorization -- centralized vs distributed, etc. || || || ||
|-
| Acceptable date and time formats || ZT || 2012-07-15 || ||DONE
|-
| kadm5.acl man page || ZT || 2012-08-15 || || DONE
|-
|}

== API documentation ==

===Most commonly used API functions (in alphabetical order)===

{| class="wikitable"
|+ Tier 1 - Highest priority
|-
! API
! Proposed Author
! Reviewer
! Target Date
! Reviewer Comments
|-
|-
| krb5_build_principal [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_build_principal.html]|| ZT || GH|| ||
|-
|krb5_build_principal_alloc_va [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_build_principal_alloc_va.html] || ZT || GH|| ||
|-
| krb5_build_principal_ext [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_build_principal_ext.html]|| ZT ||GH || ||
|-
| krb5_cc_close [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_close.html] ||ZT ||GH || ||
|-
| krb5_cc_default [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_default.html]|| ZT|| GH|| ||
|-
| krb5_cc_default_name [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_default_name.html]|| ZT|| GH|| ||
|-
| krb5_cc_destroy [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_destroy.html]|| ZT|| GH|| ||
|-
| krb5_cc_dup [http://web.mit.edu/kerberos/krb5-current/dockrb_appldev/refs/api/krb5_cc_dup.html]|| ZT|| GH|| ||
|-
| krb5_cc_get_name [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_get_name.html]|| ZT || GH|| ||
|-
| krb5_cc_get_principal [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_get_principal.html]|| ZT ||GH || ||
|-
| krb5_cc_get_type [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_get_type.html]|| ZT ||GH || ||
|-
| krb5_cc_initialize [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_initialize.html]|| ZT||GH || ||
|-
| krb5_cc_new_unique [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_new_unique.html]|| ZT|| GH|| ||
|-
| krb5_cc_resolve [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_resolve.html]|| ZT|| GH|| ||
|-
| krb5_change_password [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_change_password.html]|| ZT||GH || ||
|-
| krb5_free_context [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_free_context.html]|| ZT|| GH|| ||
|-
| krb5_free_error_message [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_free_error_message.html]|| ZT ||GH || ||
|-
| krb5_free_principal [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_free_principal.html]|| ZT ||GH || ||
|-
| krb5_fwd_tgt_cred [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_fwd_tgt_cred.html]|| ZT || GH|| || Needs example
|-
| krb5_get_default_realm [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_default_realm.html]|| ZT || GH|| ||
|-
| krb5_get_error_message [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_error_message.html]|| ZT || GH|| ||
|-
| krb5_get_host_realm [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_host_realm.html]|| ZT ||GH || ||
|-
| krb5_get_credentials [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_credentials.html]|| ZT ||GH || ||
|-
| krb5_get_fallback_host_realm [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_fallback_host_realm.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_keytab [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_keytab.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_alloc [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_alloc.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_free [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_free.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_get_fast_flags [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_get_fast_flags.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_init [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_init.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_address_list [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_address_list.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_set_anonymous [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_anonymous.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_canonicalize [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_canonicalize.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_set_change_password_prompt [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_change_password_prompt.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_set_etype_list [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_etype_list.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_expire_callback [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_expire_callback.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_fast_ccache [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_fast_ccache.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_fast_ccache_name [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_fast_ccache_name.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_fast_flags [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_fast_flags.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_set_forwardable [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_forwardable.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_set_out_ccache [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_out_ccache.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_pa [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_pa.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_preauth_list [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_preauth_list.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_set_proxiable [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_proxiable.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_set_renew_life [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_renew_life.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_salt [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_salt.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_set_tkt_life [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_tkt_life.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_password [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_password.html]|| ZT || GH|| ||
|-
| krb5_get_profile [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_profile.html]|| ZT || GH|| ||
|-
| krb5_get_prompt_types [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_prompt_types.html]|| ZT ||GH || ||
|-
| krb5_get_renewed_creds [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_renewed_creds.html]|| ZT || GH|| ||
|-
| krb5_get_validated_creds [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_validated_creds.html]|| ZT || GH|| ||
|-
| krb5_init_context [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_init_context.html]|| ZT ||GH || ||
|-
| krb5_init_secure_context [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_init_secure_context.html]|| ZT || GH|| ||
|-
| krb5_is_config_principal [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_is_config_principal.html]|| ZT ||GH || ||
|-
| krb5_is_thread_safe [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_is_thread_safe.html]|| ZT ||GH || ||
|-
| krb5_kt_close [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_kt_close.html]|| ZT || GH|| ||
|-
| krb5_kt_default [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_kt_default.html]|| ZT ||GH || ||
|-
| krb5_kt_default_name [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_kt_default_name.html]|| ZT ||GH || ||
|-
| krb5_kt_get_name [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_kt_get_name.html]|| ZT ||GH || ||
|-
| krb5_kt_get_type [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_kt_get_type.html] || ZT ||GH || ||
|-
| krb5_kt_resolve [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_kt_resolve.html]|| ZT || GH|| ||
|-
| krb5_kuserok [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_kuserok.html] || ZT ||GH || ||
|-
| krb5_parse_name [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_parse_name.html]|| ZT ||GH || ||
|-
| krb5_parse_name_flags [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_parse_name_flags.html]|| ZT || GH|| ||
|-
| krb5_principal_compare [http://web.mit.edu/kerberos/krb5-current/dockrb_appldev/refs/api/krb5_principal_compare.html]|| ZT ||GH || ||
|-
| krb5_principal_compare_any_realm [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_principal_compare_any_realm.html]|| ZT || GH|| ||
|-
| krb5_principal_compare_flags [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_principal_compare_flags.html]|| ZT ||GH || ||
|-
| krb5_prompter_posix [http://web.mit.edu/kerberos/krb5-current/dockrb_appldev/refs/api/krb5_prompter_posix.html]|| ZT||GH || ||
|-
| krb5_realm_compare [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_realm_compare.html]|| ZT ||GH || ||
|-
| krb5_recvauth [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_recvauth.html]||ZT ||GH || ||
|-
| krb5_recvauth_version [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_recvauth_version.html] ||ZT ||GH || ||
|-
| krb5_set_default_realm [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_set_default_realm.html]|| ZT ||GH || ||
|-
| krb5_set_password [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_set_password.html]|| ZT || GH|| ||
|-
| krb5_set_password_using_ccache [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_set_password_using_ccache.html] || ZT ||GH || ||
|-
| krb5_set_principal_realm [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_set_principal_realm.html] || ZT || GH|| ||
|-
| krb5_set_trace_callback [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_set_trace_callback.html]|| ZT ||GH || ||
|-
| krb5_set_trace_filename [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_set_trace_filename.html]|| ZT ||GH || ||
|-
| krb5_sname_to_principal [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_sname_to_principal.html]|| ZT ||GH || ||
|-
| krb5_unparse_name [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_unparse_name.html]|| ZT || GH|| ||
|-
| krb5_unparse_name_ext [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_unparse_name_ext.html]|| ZT ||GH || ||
|-
| krb5_unparse_name_flags [http://web.mit.edu/kerberos/krb5-current/dockrb_appldev/refs/api/krb5_unparse_name_flags.html] || ZT || GH|| ||
|-
| krb5_unparse_name_flags_ext [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_unparse_name_flags_ext.html] || ZT ||GH || ||
|-
| krb5_us_timeofday [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_us_timeofday.html]|| ZT || GH|| ||
|-
| krb5_verify_authdata_kdc_issued [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_verify_authdata_kdc_issued.html]|| ZT || GH|| ||
|-
|}
We may want to have more examples for some of the common API functions.

== Manpage proofreading ==
{| class="wikitable"
|+
|-
! manpage
! original
! reviewer
! comments
|-
| k5identity.5 || src/gen-manpages/k5identity.M || GH ||
|-
| k5login.5 || src/gen-manpages/k5login.M || GH ||
|-
| k5srvutil.1 || src/kadmin/cli/k5srvutil.M || GH ||
|-
| kadmin.1 || src/kadmin/cli/kadmin.M || GH ||
|-
| kadmind.8 || src/kadmin/server/kadmind.M || GH ||
|-
| kdb5_ldap_util.8 || src/plugins/kdb/ldap/ldap_util/kdb5_ldap_util.M || GH ||
|-
| kdb5_util.8 || src/kadmin/dbutil/kdb5_util.M || GH ||
|-
| kdc.conf.5 || src/config-files/kdc.conf.M || GH ||
|-
| kdestroy.1 || src/clients/kdestroy/kdestroy.M || GH ||
|-
| kinit.1 || src/clients/kinit/kinit.M || GH ||
|-
| kpasswd.1 || src/clients/kpasswd/kpasswd.M || GH ||
|-
| kprop.8 || src/slave/kprop.M || GH ||
|-
| kpropd.8 || src/slave/kpropd.M || GH ||
|-
| kproplog.8 || src/slave/kproplog.M || GH ||
|-
| krb5-send-pr.1 || src/util/send-pr/send-pr.1 || || copyright issues. Removed from the documentation
|-
| krb5.conf.5 || src/config-files/krb5.conf.M || GH ||
|-
| krb5kdc.8 || src/kdc/krb5kdc.M || GH ||
|-
| ksu.1 || src/clients/ksu/ksu.M || GH || needs rewrite
|-
| kswitch.1 || src/clients/kswitch/kswitch.M || GH ||
|-
| kvno.1 || src/clients/kvno/kvno.M || GH ||
|-
| sclient.1 || src/appl/sample/sclient/sclient.M || GH ||
|-
| sserver.8 || src/appl/sample/sserver/sserver.M || GH ||
|}

== Abbreviations ==

{| class="wikitable"
|+
|-
! abbreviation
! full names?
|-
|-
| GH || Greg Hudson
|-
| KR || Ken Raeburn
|-
| MIT || MITKC group
|-
| NW || Nico Williams
|-
| TH || Thomas Hardjono
|-
| TY || Tom Yu
|-
| ZT || Zhanna Tsitkov
|-
|}

Projects/Kerberos Documentation

2012-11-02T16:36:54Z

BenKaduk: import content from philsophy.rst in the doc tree

{{project-early}}

== Purpose ==

The goal of the project is to create an infrastructure and process for the future development of the extensive Kerberos documentation.
The documentation should be useful and correct; it must be detailed, but optimized -- do not be too verbose.

'''The documentation will be built incrementally. We will analyze what works and what doesn't and correct the course of action as needed.'''
Part of the criteria for "what works" is that the documentation should be easy to maintain.

The actualized documentation will be useful for developers and administrators, both for experienced ones and newcomers. It will address the following topics:

* Complete reference - API, internal functions, data types, macros
* Tutorial for application developers - description on various tasks such as working with credentials, topics on how to write plugins, etc
* Cookbook for administrators - Installation, configuration, troubleshooting.

== Example ==

Please, follow this link for Kerberos documentation general example [http://web.mit.edu/tsitkova/www/build/index.html];
advanced admin topic example: [http://web.mit.edu/tsitkova/www/build/cookbook/advanced/ldapbackend.html]
MIT Kerberos features: [http://web.mit.edu/tsitkova/www/build/mitK5features.html]

== Documentation for application developers ==

TODO

Generally any topic in the Kerberos documentation can cross-reference with function documentation and each other. See [http://web.mit.edu/tsitkova/www/build/tutorial/h5l_mit_apidiff.html]

== Details of source documentation ==

==== Documenting functions ====

=====Part_1=====

The following fields ''must'' be included in the function documentation and should reside in the source code :

# Function signature
# Brief function description
# Arguments - [in/out] with description
# Return value description
# Detailed description (optional)

One can see that Part_1 contains the information that is the most useful for those who update the code and fix the bugs. To avoid the code overcrowding and make any additions to the function documentation as simple as possible, we suggest to save additional documentation ( see below Part_2) in the separate location - one file per function..

Effectively this means that we expect the Doxygen style comments in the headers in the following format:

<pre>
/**
* @brief Some brief description
*
* Optional detailed description
*
* @param[in] arg1 Description of arg1
*
* @return Something useful
*/
char * KRB5_CALLCONV
krb5_X(type arg1)
</pre>

Note, that ''@brief'' notation may be omitted if JAVADOC_AUTOBRIEF is set to YES in the Doxygen configuration file. In this case the very first line of the comments will be interpreted as the brief description:

<pre>
/** Some brief description
*
* Optional detailed description
*
* @param[in] arg1 Description of arg1
*
* @return Something useful
*/
char * KRB5_CALLCONV
krb5_X(type arg1)
</pre>

=====Part_2=====

The ''optional'' fields may include:

# ''See also'' section to refer to the related functions,
# ''Note'' section to highlight the specifics of the behaivor
# Examples of the usage
# Snap-shot of the real code involving this function
# Links to KRB5 Wiki Project page, krbdev discussion, RFC document or its section etc
# Version of Kerberos when fuction was introduced or became obsolete

''' Part_2 in ReST format '''

When available, we suggest to have Part_2 information associated with the particular function in ReST format. For example:

* Warnings and suggestions
Warn about any potential mistakes and misuse.
Point to other useful routines.

* Links to RFC, wiki Projects, krbdev discussions
:rfc:4120
Or if you want to reffer to the specific section of the RFC use the following notation: :rfc:4120#section-5.2
Or link to Kerberos Project page, for example, Disable_DES project <http://k5wiki.kerberos.org/wiki/Projects/Disable_DES>

* Example
The place for the function usage examples

''' Part_2 in Doxygen format '''

Alternatively, when desired, Part_2 may be documented in Doxygen format by adding ''@include'' directive to the comment, for example, to reference to example code fragments

<pre>
/** Some brief description
*
* Optional detailed description
*
* @param[in] arg1 Description of arg1
*
* @return Something useful
*
* @include example_krb5_X.c
*/
char * KRB5_CALLCONV
krb5_X(type arg1)
</pre>

Note: The path to the example file (here example_krb5_X.c) must be set in the EXAMPLE_PATH tag in the Doxygen configuration file

=====Workflow: Putting Part_1 and Part_2 together=====

# Configure Doxygen to generate output both in xml and html formats. Run Doxygen.
# For each function and data type generate document in ReST format. It is expected that it contains information from Part_1. For the function ''krb5_X()'' lets call it ''krb5_X_p1''.
# (For ReST format only) If the Part_2 documentation for ''krb5_X()'' has been already written, there is a file called ''krb5_X_p2.rst'' in the designated directory. If not - nothing happens.
# (For ReST format only) Concatenate ''krb5_X_p1'' and ''krb5_X_p2.rst'' (if it exists), add the link to Doxygen generated documentation for this function in html format (generated automatically) and save as a file ''krb5_X.rst''.
# File ''krb5_X.rst'' can be used as input for Sphinx

NOTE: Initially we provide Python script to automate steps 2-4. The whole process will be automated later.

==== Documenting data types ====

TODO

== How to contribute ==

# The core team - the administrator - posts the initial list of the tasks (such as API, admin tasks, "How to"-s etc) and further supports it. See [[Projects/Documentation Tasks]] for more detailed information.
# Community can suggest new tasks
# The core team provides templates that, if helpful, may be used by the documentation writers. The most desirable format for the contributed documents is ReST as the easiest to integrate with the mainstream documentation.
# Community can provide the feedback on the documented tasks.

== Tools ==

* Doxygen 1.7.2 <http://www.stack.nl/~dimitri/doxygen/index.html>
* Sphinx 1.0.4 <http://sphinx.pocoo.org>
* Python 2.5+ (with lxml extension)
* Cheetah 2.4.4 <http://www.cheetahtemplate.org>
* Restructured Text markup <http://docutils.sourceforge.net/docs/user/rst/quickstart.html>

Solaris and pkgsrc

2012-10-02T20:45:16Z

BenKaduk:

Bootstrapping krbdev-sparc-build.mit.edu as a build slave with solaris 10:

Get the pkgsrc repo locally and copy it over:

env CVS_RSH=ssh cvs -d anoncvs@anoncvs.NetBSD.org:/cvsroot checkout pkgsrc

I see the key fingerprint of anoncvs as:

1024 a0:b1:35:d7:56:be:2c:30:78:b0:21:df:43:d9:64:5c anoncvs.netbsd.org,149.20.53.68 (RSA)

I can't find a cvs binary from Oracle TechNet, hence the copying.

On the server, drop it in /opt/pkgsrc
The next step, per http://www.netbsd.org/docs/pkgsrc/platforms.html is to run the bootstrap script.

This requires several components from Oracle, and some things which are not in the default path of /usr/sbin:/usr/bin

I am making an /opt/pkgsrc/buildenv.sh to run that will set up PATH and other environment variables to make an appropriate build environment. (This is done so as to not disrupt root's default PATH and clutter it with a bunch of stuff.)

Per http://wiki.netbsd.org/pkgsrc/how_to_use_pkgsrc_on_solaris/ , perhaps the only thing we do not have but need is SUNWsprot.

Mounting iso images in solaris: https://blogs.oracle.com/gerhardhofweber/entry/mounting_iso_images_in_solaris
Uses lofiadm to make a mountable device for 'mount -F hsfs'

# mkdir -p /iso/sol-10-u10-ga2-sparc
# lofiadm -a /var/tmp/sol-10-u10-ga2-sparc-dvd.iso
/dev/lofi/1
# mount -F hsfs -o ro /dev/lofi/1 /iso/sol-10-u10-ga2-sparc

Attempting
pkgadd -d /iso/sol-10-u10-ga2-sparc/Solaris_10/Product/ SUNWsprot
claims it is already installed, though. pkginfo confirms; I must have missed it the first time around.

Solaris and pkgsrc

2012-10-02T20:39:32Z

BenKaduk:

Solaris and pkgsrc

2012-10-02T20:38:12Z

BenKaduk:

Bootstrapping krbdev-sparc-build.mit.edu as a build slave with solaris 10:

Get the pkgsrc repo locally and copy it over:

env CVS_RSH=ssh cvs -d anoncvs@anoncvs.NetBSD.org:/cvsroot checkout pkgsrc

I see the key fingerprint of anoncvs as:

1024 a0:b1:35:d7:56:be:2c:30:78:b0:21:df:43:d9:64:5c anoncvs.netbsd.org,149.20.53.68 (RSA)

I can't find a cvs binary from Oracle TechNet, hence the copying.

On the server, drop it in /opt/pkgsrc
The next step, per http://www.netbsd.org/docs/pkgsrc/platforms.html is to run the bootstrap script.

This requires several components from Oracle, and some things which are not in the default path of /usr/sbin:/usr/bin

I am making an /opt/pkgsrc/buildenv.sh to run that will set up PATH and other environment variables to make an appropriate build environment. (This is done so as to not disrupt root's default PATH and clutter it with a bunch of stuff.)

Per http://wiki.netbsd.org/pkgsrc/how_to_use_pkgsrc_on_solaris/ , perhaps the only thing we do not have but need is SUNWsprot.

Mounting iso images in solaris: https://blogs.oracle.com/gerhardhofweber/entry/mounting_iso_images_in_solaris
Uses lofiadm to make a mountable device for 'mount -F hsfs'

{{{
# mkdir -p /iso/sol-10-u10-ga2-sparc
# lofiadm -a /var/tmp/sol-10-u10-ga2-sparc-dvd.iso
/dev/lofi/1
# mount -F hsfs -o ro /dev/lofi/1 /iso/sol-10-u10-ga2-sparc
}}}

Solaris and pkgsrc

2012-10-02T20:32:54Z

BenKaduk:

Solaris and pkgsrc

2012-10-02T15:16:30Z

BenKaduk:

Solaris and pkgsrc

2012-10-01T22:45:58Z

BenKaduk:

Solaris and pkgsrc

2012-10-01T21:25:46Z

BenKaduk: New page: Bootstrapping krbdev-sparc-build.mit.edu as a build slave with solaris 10: Get the pkgsrc repo locally and copy it over: env CVS_RSH=ssh cvs -d anoncvs@anoncvs.NetBSD.org:/cvsroot checko...

Kerberos for Windows (KfW) Build Environment

2012-09-19T21:20:16Z

BenKaduk: more formatting tweaks to avoid splitting sentences. More work still needed

Directions for producing an environment in which to build
Kerberos for Windows version 4

Start with a clean Windows 7 installation (64-bit necessary?)

(0) get a browser that you like/trust to validate SSL certs/etc.

(1) Install MS Visual Studio 2010 Professional
grab the Visual C++ 10.0 runtime for x86 and x64
also the 64-bit prerequisites
Documentation files not necessary
Choose 'Visual C++ Development Settings' (probably doesn't matter)
You should now have an 'HTML Help Workshop' entry within
Program Files (x86). This will get added to the path, later.
(2) Install the Windows SDK version 7.1
http://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=8279
The download is over a non-https url by default, though the installer
is signed by a Microsoft certificate.
[Select all components (add application verifier, debugging tools,
windows performance toolkit)]
Finishing the installation brings up the Help Library Manager (installer?)
but nothing should be necessary from that utility.
(3) Install the Utilities and SDK for UNIX-based Applications (amd64 if on a 64-bit system)
First, enable the Windows feature "Subsystem for UNIX-based Applications"
from the Control Panel. (Programs [and Features] menu, "Turn on or off
Windows features", or similar.)
Then visit (also available from the All Programs menu)
http://www.microsoft.com/en-us/download/details.aspx?id=23754
Again, this is a http-default page, and attempting to use SSL causes
an error due to Akamai configuration.
I have Version 10.0.6030.0 of the SUA, which claims to be for
Windows Vista RTM/Windows Vista SP1/Windows Server 2008 RTM
but appears to work fine on Windows 7.
[The standard installation gives us awk, which may be all we need?]
(4) Install the Windows Installer XML Toolkit
Tested with version 3.5; there is a 3.6 beta available as well.
wix.sourceforge.net --> wix.codeplex.com/releases/view/60102
These default to non-SSL urls; try to get
https://download-codeplex.sec.s-msft.com/Download/Release?ProjectName=wix&DownloadId=204417&FileTime=129409234222130000&Build=19194
Install all components (the default setting).
(5) Update the system path to include some necessary utilities.
This is something like
Control Panel->System->Advanced System Settings->Environment
awk is in C:\Windows\SUA\bin
But, you will need to make a *copy* (not link) of it named awk.exe in
order for things to work properly. Check the permissions so that everyone
can read and execute it.
Add the directory containing hhc.exe to the path:
C:\Program Files (x86)\HTML Help Workshop
Add C:\Program Files (x86)\Windows Installer XML v3.5\bin to the path
to get candle.exe.
(6) Install a real Perl that can handle both forward-slash and backward-slash as path separators, e.g., ActivePerl or Strawberry Perl.
I used Strawberry Perl, since its installer was downloadable over SSL and
was digitally signed.
I have strawberry_perl-5.14.2.1-64bit.msi
Note that you may not have spaces in the path to the installation, so
it installs to c:\strawberry by default.

That should be enough for the build environment.

To actually build an installer, fire up the Windows SDK 7.1 command prompt.

(0) cmd /v to get delayed expansion of variables

(1) Environment set-up
set KRB_INSTALL_DIR=/path/to/an/obj/dir
[set MIT_INTERNAL=1]
[set NODEBUG=1]
\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.cmd /x86 [/release]
set CPU=i386
(2) Build the 32-bit binaries
cd /path/to/krb5-tree/src
[nmake clean]
nmake -f Makefile.in prep-windows
nmake
nmake install
(3) Build 32-bit installer
cd windows/installer/wix
[nmake clean]
nmake
rename kfw.msi kfw32.msi
(4) 64-bit build
\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.cmd /x64 [/release]
set CPU=AMD64
cd /path/to/krb5-tree/src
nmake clean
nmake -f Makefile.in prep-windows [?]
nmake
nmake install
(5) Build 64-bit installer
cd windows/installer/wix
nmake clean
nmake
rename kfw.msi kfw64.msi

Kerberos for Windows (KfW) Build Environment

2012-09-19T20:10:20Z

BenKaduk: tweak formatting

Directions for producing an environment in which to build
Kerberos for Windows version 4

Start with a clean Windows 7 installation (64-bit necessary?)

(0) get a browser that you like/trust to validate SSL certs/etc.

(1) Install MS Visual Studio 2010 Professional
grab the Visual C++ 10.0 runtime for x86 and x64
also the 64-bit prerequisites
Documentation files not necessary
Choose 'Visual C++ Development Settings' (probably doesn't matter)
You should now have an 'HTML Help Workshop' entry within
Program Files (x86). This will get added to the path, later.
(2) Install the Windows SDK version 7.1
http://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=8279
The download is over a non-https url by default, though the installer
is signed by a Microsoft certificate.
[Select all components (add application verifier, debugging tools,
windows performance toolkit)]
Finishing the installation brings up the Help Library Manager (installer?)
but nothing should be necessary from that utility.
(3) Install the Utilities and SDK for UNIX-based Applications (amd64 if
on a 64-bit system)
First, enable the Windows feature "Subsystem for UNIX-based Applications"
from the Control Panel. (Programs [and Features] menu, "Turn on or off
Windows features", or similar.)
Then visit (also available from the All Programs menu)
http://www.microsoft.com/en-us/download/details.aspx?id=23754
Again, this is a http-default page, and attempting to use SSL causes
an error due to Akamai configuration.
I have Version 10.0.6030.0 of the SUA, which claims to be for
Windows Vista RTM/Windows Vista SP1/Windows Server 2008 RTM
but appears to work fine on Windows 7.
[The standard installation gives us awk, which may be all we need?]
(4) Install the Windows Installer XML Toolkit
Tested with version 3.5; there is a 3.6 beta available as well.
wix.sourceforge.net --> wix.codeplex.com/releases/view/60102
These default to non-SSL urls; try to get
https://download-codeplex.sec.s-msft.com/Download/Release?ProjectName=wix&DownloadId=204417&FileTime=129409234222130000&Build=19194
Install all components (the default setting).
(5) Update the system path to include some necessary utilities.
This is something like
Control Panel->System->Advanced System Settings->Environment
awk is in C:\Windows\SUA\bin
But, you will need to make a *copy* (not link) of it named awk.exe in
order for things to work properly. Check the permissions so that everyone
can read and execute it.
Add the directory containing hhc.exe to the path:
C:\Program Files (x86)\HTML Help Workshop
Add C:\Program Files (x86)\Windows Installer XML v3.5\bin to the path
to get candle.exe.
(6) Install a real Perl that can handle both forward-slash and backward-slash
as path separators, e.g., ActivePerl or Strawberry Perl.
I used Strawberry Perl, since its installer was downloadable over SSL and
was digitally signed.
I have strawberry_perl-5.14.2.1-64bit.msi
Note that you may not have spaces in the path to the installation, so
it installs to c:\strawberry by default.

That should be enough for the build environment.

To actually build an installer, fire up the Windows SDK 7.1 command prompt.

(0) cmd /v to get delayed expansion of variables

(1) Environment set-up
set KRB_INSTALL_DIR=/path/to/an/obj/dir
[set MIT_INTERNAL=1]
[set NODEBUG=1]
\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.cmd /x86 [/release]
set CPU=i386
(2) Build the 32-bit binaries
cd /path/to/krb5-tree/src
[nmake clean]
nmake -f Makefile.in prep-windows
nmake
nmake install
(3) Build 32-bit installer
cd windows/installer/wix
[nmake clean]
nmake
rename kfw.msi kfw32.msi
(4) 64-bit build
\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.cmd /x64 [/release]
set CPU=AMD64
cd /path/to/krb5-tree/src
nmake clean
nmake -f Makefile.in prep-windows [?]
nmake
nmake install
(5) Build 64-bit installer
cd windows/installer/wix
nmake clean
nmake
rename kfw.msi kfw64.msi

Kerberos for Windows (KfW) Build Environment

2012-09-19T20:08:24Z

BenKaduk: Import my notes onto the wiki

Directions for producing an environment in which to build
Kerberos for Windows version 4

Start with a clean Windows 7 installation (64-bit necessary?)

(0) get a browser that you like/trust to validate SSL certs/etc.
(1) Install MS Visual Studio 2010 Professional
grab the Visual C++ 10.0 runtime for x86 and x64
also the 64-bit prerequisites
Documentation files not necessary
Choose 'Visual C++ Development Settings' (probably doesn't matter)
You should now have an 'HTML Help Workshop' entry within
Program Files (x86). This will get added to the path, later.
(2) Install the Windows SDK version 7.1
http://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=8279
The download is over a non-https url by default, though the installer
is signed by a Microsoft certificate.
[Select all components (add application verifier, debugging tools,
windows performance toolkit)]
Finishing the installation brings up the Help Library Manager (installer?)
but nothing should be necessary from that utility.
(3) Install the Utilities and SDK for UNIX-based Applications (amd64 if
on a 64-bit system)
First, enable the Windows feature "Subsystem for UNIX-based Applications"
from the Control Panel. (Programs [and Features] menu, "Turn on or off
Windows features", or similar.)
Then visit (also available from the All Programs menu)
http://www.microsoft.com/en-us/download/details.aspx?id=23754
Again, this is a http-default page, and attempting to use SSL causes
an error due to Akamai configuration.
I have Version 10.0.6030.0 of the SUA, which claims to be for
Windows Vista RTM/Windows Vista SP1/Windows Server 2008 RTM
but appears to work fine on Windows 7.
[The standard installation gives us awk, which may be all we need?]
(4) Install the Windows Installer XML Toolkit
Tested with version 3.5; there is a 3.6 beta available as well.
wix.sourceforge.net --> wix.codeplex.com/releases/view/60102
These default to non-SSL urls; try to get
https://download-codeplex.sec.s-msft.com/Download/Release?ProjectName=wix&DownloadId=204417&FileTime=129409234222130000&Build=19194
Install all components (the default setting).
(5) Update the system path to include some necessary utilities.
This is something like
Control Panel->System->Advanced System Settings->Environment
awk is in C:\Windows\SUA\bin
But, you will need to make a *copy* (not link) of it named awk.exe in
order for things to work properly. Check the permissions so that everyone
can read and execute it.
Add the directory containing hhc.exe to the path:
C:\Program Files (x86)\HTML Help Workshop
Add C:\Program Files (x86)\Windows Installer XML v3.5\bin to the path
to get candle.exe.
(6) Install a real Perl that can handle both forward-slash and backward-slash
as path separators, e.g., ActivePerl or Strawberry Perl.
I used Strawberry Perl, since its installer was downloadable over SSL and
was digitally signed.
I have strawberry_perl-5.14.2.1-64bit.msi
Note that you may not have spaces in the path to the installation, so
it installs to c:\strawberry by default.

That should be enough for the build environment.

To actually build an installer, fire up the Windows SDK 7.1 command prompt.

(0) cmd /v to get delayed expansion of variables

(1) Environment set-up
set KRB_INSTALL_DIR=/path/to/an/obj/dir
[set MIT_INTERNAL=1]
[set NODEBUG=1]
\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.cmd /x86 [/release]
set CPU=i386
(2) Build the 32-bit binaries
cd /path/to/krb5-tree/src
[nmake clean]
nmake -f Makefile.in prep-windows
nmake
nmake install
(3) Build 32-bit installer
cd windows/installer/wix
[nmake clean]
nmake
rename kfw.msi kfw32.msi
(4) 64-bit build
\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.cmd /x64 [/release]
set CPU=AMD64
cd /path/to/krb5-tree/src
nmake clean
nmake -f Makefile.in prep-windows [?]
nmake
nmake install
(5) Build 64-bit installer
cd windows/installer/wix
nmake clean
nmake
rename kfw.msi kfw64.msi

Kerberos for Windows (KfW) Build Environment

2012-09-19T20:03:34Z

BenKaduk: New page for KfW 4.x build environment

Kerberos for Windows (KfW) 3.2.x Build Environment

2012-09-19T20:02:26Z

BenKaduk:

Note: this article is archival content, and is believed to describe the procedure needed to generate a build environment for Kerberos for Windows 3.2.x, which is no longer the current version. The build environment for Kerberos for Windows 4.x is different and is described elsewhere.

Kerberos for Windows (KfW) is a specialized distribution of MIT Kerberos targeting the Windows platform. This document describes how to setup your development environment to build KfW.

==Overview==
The KfW build is automated by a set of Perl scripts and uses a combination of GNU and Microsoft tools to assemble the final build. In the following sections, we’ll outline the required components to run the build system.

===Source Control Access===
The Kerberos source tree is currently split over two source control systems. Current source is managed using Subversion (SVN), while legacy code is managed using the Concurrent Versioning System (CVS). The [http://www.cygwin.com/ Cygwin] distribution provides an SVN client that can be used with our Kerberized SVN repository.

====Kerberized Access====
Both source control systems support Kerberos authentication. In order to execute the KfW build script, you must use the Kerberos authentication mechanism as the script is not designed to prompt for passwords. Unfortunately, neither the CVS nor SVN client natively supports Kerberos authentication.

In order to provide Kerberized access for SVN, you must use a Kerberized SSH client in conjunction with the standard SVN client included with Cygwin. (In this guide, we will use a special build of '''PuTTY''' to accomplish this.)

In order to provide Kerberized access for CVS, we will use a custom build of the CVS client that supports Kerberos authentication.

===Required Tools===
====Source Control====
* CVS with Kerberos Support
* SVN
* PuTTY

====Scripting Support====
* Cygwin (v1.5 or later)
** Provides the sed, awk, cat, rm, and find utilities.
* ActiveState Perl (v5.10.0.1005 or later)

====Compilers and Libraries====
* Microsoft Visual Studio (v2005 SP1 or later)
* Microsoft Windows SDK (v6.1 or later)

====Documentation Generation====
* Doxygen
* Microsoft HTML Help Workshop
* Microsoft Windows Help Authoring Kit

====Installation Packagers====
* Windows Installer XML (WiX) toolset
* Nullsoft Scriptable Install System (NSIS)

==Setting up Source Control Access==
In order to access the SVN repository, we will need to install and configure Cygwin, the KFW binaries (for Kerberized source control access), PuTTY, and a custom build of the CVS client.

Please note: Prior to testing any of the configurations described below, please be sure that you have been granted permissions to access the SVN and CVS repositories. PuTTY will throw unintelligible errors if permissions have not been set properly.

===Installing and Cygwin and SVN===
# Download a copy of the Cygwin installer [http://www.cygwin.com/ here]. Save it too your local machine (note the location, as this executable is required to make any modifications to you Cygwin distribution).
# Run '''setup.exe'''
# Click '''Next''' through the introduction and download screens, accepting the default values.
# When prompted, change the root directory of the Cygwin installation to '''C:\tools\cygwin''', and click '''Next'''.
# When choosing a directory to store the installation packages, you may accept the default, though this might place the files in temporary internet files directory. If you want these packages to be available for reinstallation at a later time, choose a more suitable directory (i.e. '''C:\cyginstall'''). Click '''Next'''.
# Leave the default connection settings, and click '''Next'''
# Choose a download site from the list, and click '''Next'''
# In the ''Choose Packages'' screen, mark the Devel/Subversion package for installation, and click '''Next'''. The installer will proceed to download and install the selected packages.
# Click '''Finish'''. The installer will close.
# Open the '''Control Panel -> System''' applet. Click the '''Advanced''' tab and click '''Environment Variables'''.
# Under the '''System Variables''' list, double-click '''Path''' (possibly listed as '''PATH'''), add a semicolon after the last entry and add '''C:\tools\cygwin\bin''' to the variable. Click '''OK''' on each window to close it, accepting changes.
# Open Windows Explorer and navigate to the Cygwin bin directory ('''C:\tools\cygwin\bin''').
# Delete '''awk.exe''' (this is a symbolic link that the Windows shell doesn't handle properly).
# Copy '''gawk.exe''' and rename it to '''awk.exe'''.

===Installing the KfW Binaries===
If you are not currently using a pre-built version of KfW, you'll need to install one now in order to use Kerberized source control access.

# Download a copy of the '''MIT Kerberos for Windows''' MSI installer [http://web.mit.edu/kerberos/dist/ here]. Run the MSI.
# Accept the default install options.
# Once setup completes, launch the '''Network Identity Manager (NIM)''' from the '''Kerberos for Windows''' folder in the '''Start Menu'''. By default, it should be configured for the ATHENA.MIT.EDU realm.
# Create new credentials using you Athena username and password, and minimize NIM (this should hide it in the taskbar).

===Installing PuTTY===
PuTTY will provide the Kerberized SSH connection to our SVN repository.
# Download a copy of the '''PuTTY with GSSAPI Extensions''' archive [http://www.sweb.cz/v_t_m/putty/PuTTY-0.58-GSSAPI-2005-07-24.zip here]. Note, there are several distributions of PuTTY that support Kerberos. You may choose the one that works best for you.
# Unzip the archive to '''C:\tools\putty'''.
# Launch '''C:\tools\putty\putty.exe'''.
# Using the tree on the left, navigate to the '''Connection -> Data''' screen and enter your Athena username as the '''Auto-login username'''.
# Open the '''Connection --> SSH --> Auth screen'''. In Authentication Methods, select '''Attempt "keyboard-interactive" auth (SSH-2)''' and '''Attempt Kerberos 5 GSSAPI/SSPI auth (SSH-2)'''. In Authentication parameters, select '''Allow Kerberos 5 ticket forwarding in GSSAPI/SSF''' and enter '''ATHENA.MIT.EDU''' as the '''Server realm'''.
# Open the '''Session''' screen. Select (highlight) '''Default Settings''' from the list and click '''Save'''.
# Close the PuTTY configuration windows.

===Configuring SVN & PuTTY===
# Open the '''Control Panel -> System''' applet. Click the '''Advanced''' tab and click '''Environment Variables'''.
# Under the '''System Variables''' list, double-click '''Path''' (possibly listed as '''PATH'''), add a semicolon after the last entry and add '''C:\tools\putty''' to the variable. Click '''OK''' on each window to close it, accepting changes.
# Under the '''System Variables''' list, add a '''SVN_SSH''' variable and give it the value '''plink.exe'''.
# Create a directory to house a temporary SVN snapshot (i.e. '''C:\kfw\svn''').
# Open the Command Prompt ('''Start -> Run -> cmd''') and type:
#:<code>plink svn.mit.edu</code>
#:Please note, it's important to run plink once before attempting to use it with SVN, because when connecting to the server for the first time there will be interactive prompts that SVN does not support.
# You may be prompted to add the server to your trusted list. If so, type '''y''' and hit '''Enter'''. Once the connection completes, hit '''Ctrl+C''' to end plink. It should ''not'' prompt you for a password at any time. If so, your Kerberos credentials have not been configured correctly or have expired.
# Now that we've confirmed plink is working with a Kerberized connection, we need to checkout a snapshot of the SVN repository. In the Command Prompt type:
#:<code>svn co svn+ssh://svn.mit.edu/krb5/trunk C:\kfw\svn</code>
If your SVN client is properly configured, you should get a complete snapshot of the Krb5 trunk from the SVN repository, now located in C:\kfw\svn (or another directory of your choosing).

===Installing CVS===
# Download a copy of CVS that supports Kerberos authentication. While there doesn't appear to be a readily accessible CVS client distribution that supports Kerberos, you can use the cvs client found [http://web.mit.edu/rsilk/Public/Kerberos/Utils/cvs.exe here].
# '''Move''' the file to your Cygwin binary directory (i.e.''' C:\tools\cygwin\bin''').

==Configuring the Build Tools==
Now that we have access to the repositories and have a snapshot of the SVN trunk, we need to install the required Microsoft libraries. We also need to install ActiveState Perl in order to run the build script. Finally, we need to install the remaining build tools required for documentation generation and packaging.

===Configuring Microsoft Visual Studio===
This guide assumes you have a working version of Microsoft Visual Studio 2005 Standard or later. Be sure to install the 64 bit libraries in addition to the standard 23 bit libraries if you intend to build for both architectures.

===Installing the Microsoft Windows SDK===
# Download a copy of the '''Microsoft Windows SDK''' (version 6.1 or later) [http://www.microsoft.com/downloads/details.aspx?FamilyId=E6E1C3DF-A74F-4207-8586-711EBE331CDC&displaylang=en here].
# Run the installer, accepting all default options (though you may need to select the 64 bit libraries if desired).

===Installing ActiveState Perl===
# Download a copy of '''ActiveState Perl''' (currently version 5.10.0.1005) [http://www.activestate.com/activeperl/downloads/ here].
# Run the installer, accepting all default options. This should automatically add the Perl directory to your system path.

===Installing Microsoft HTML Help Workshop===
# Download a copy of '''Microsoft HTML Help Workshop''' (currently version 1.3) [http://go.microsoft.com/fwlink/?linkid=14188 here].
# Run the installer, accepting all default options. Please note, the installer may complain that you already have a newer version of Help Workshop installed. Ignore this error; the installer will complete successfully..
# Open the '''Control Panel -> System''' applet. Click the '''Advanced''' tab and click '''Environment Variables'''.
# Under the '''System Variables''' list, double-click '''Path''' (possibly listed as '''PATH'''), add a semicolon after the last entry and add '''C:\Program Fles\HTML Help Workshop''' to the variable. Click '''OK''' on each window to close it, accepting changes.

===Installing the Windows Help Authoring Kit===
Depending on your build configuration, you may also need the '''Windows Help Authoring Kit'''.
# Download a copy of the '''Windows Help Authoring Kit''' [http://www.microsoft.com/downloads/details.aspx?FamilyID=34D35502-4DE9-4676-952C-34CC7F64F098&displaylang=en here].
# Run the installer, accepting all default options.
# Open the '''Control Panel -> System''' applet. Click the '''Advanced''' tab and click '''Environment Variables'''.
# Under the '''System Variables''' list, double-click '''Path''' (possibly listed as '''PATH'''), add a semicolon after the last entry and add '''C:\Program Fles\Help Workshop''' to the variable. Click '''OK''' on each window to close it, accepting changes.

===Installing Doxygen===
# Download a copy of the '''Doxygen distribution for Windows''' (currently version 1.5.9) [http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc here].
# Run the installer, accepting all default options. This should automatically add the Doxygen directory to your system path.

===Installing WiX===
# Download a copy of the Windows Install XML ('''WiX''') core toolset (currently version 2.0) [http://wix.sourceforge.net/downloadv2.html here].
# Unzip the archive to '''C:\tools\wix'''.
# Open the '''Control Panel -> System''' applet. Click the '''Advanced''' tab and click '''Environment Variables'''.
# Under the '''System Variables''' list, double-click '''Path''' (possibly listed as '''PATH'''), add a semicolon after the last entry and add '''C:\tools\wix''' to the variable. Click '''OK''' on each window to close it, accepting changes.

===Installing NSIS===
# Download a copy of the Nullsoft Scriptable Install System (NSIS - currently version 2.45) [http://nsis.sourceforge.net/Download here].
# Run installer, accepting all default options.
# Open the '''Control Panel -> System''' applet. Click the '''Advanced''' tab and click '''Environment Variables'''.
# Under the '''System Variables''' list, double-click '''Path''' (possibly listed as '''PATH'''), add a semicolon after the last entry and add '''C:\Program Files\NSIS''' to the variable. Click '''OK''' on each window to close it, accepting changes.

===Installing Windows Support Tools===
On some machines you may need to install the '''Windows XP SP2 Support Tools''' package to get the '''filever.exe''' utility (which is currently required by the build script).
# Download a copy of the '''Windows XP SP2 Support Tools''' package [http://www.microsoft.com/downloads/details.aspx?FamilyID=49ae8576-9bb9-4126-9761-ba8011fabf38&displaylang=en here].
# Run the installer, accepting all default options.

Kerberos for Windows (KfW) 3.2.x Build Environment

2012-09-19T19:58:10Z

BenKaduk: Kerberos for Windows (KfW) Build Environment moved to Kerberos for Windows (KfW) 3.2.x Build Environment: The build environment requirements will change for KfW 4.0

Kerberos for Windows (KfW) is a specialized distribution of MIT Kerberos targeting the Windows platform. This document describes how to setup your development environment to build KfW.

==Overview==
The KfW build is automated by a set of Perl scripts and uses a combination of GNU and Microsoft tools to assemble the final build. In the following sections, we’ll outline the required components to run the build system.

===Source Control Access===
The Kerberos source tree is currently split over two source control systems. Current source is managed using Subversion (SVN), while legacy code is managed using the Concurrent Versioning System (CVS). The [http://www.cygwin.com/ Cygwin] distribution provides an SVN client that can be used with our Kerberized SVN repository.

====Kerberized Access====
Both source control systems support Kerberos authentication. In order to execute the KfW build script, you must use the Kerberos authentication mechanism as the script is not designed to prompt for passwords. Unfortunately, neither the CVS nor SVN client natively supports Kerberos authentication.

In order to provide Kerberized access for SVN, you must use a Kerberized SSH client in conjunction with the standard SVN client included with Cygwin. (In this guide, we will use a special build of '''PuTTY''' to accomplish this.)

In order to provide Kerberized access for CVS, we will use a custom build of the CVS client that supports Kerberos authentication.

===Required Tools===
====Source Control====
* CVS with Kerberos Support
* SVN
* PuTTY

====Scripting Support====
* Cygwin (v1.5 or later)
** Provides the sed, awk, cat, rm, and find utilities.
* ActiveState Perl (v5.10.0.1005 or later)

====Compilers and Libraries====
* Microsoft Visual Studio (v2005 SP1 or later)
* Microsoft Windows SDK (v6.1 or later)

====Documentation Generation====
* Doxygen
* Microsoft HTML Help Workshop
* Microsoft Windows Help Authoring Kit

====Installation Packagers====
* Windows Installer XML (WiX) toolset
* Nullsoft Scriptable Install System (NSIS)

==Setting up Source Control Access==
In order to access the SVN repository, we will need to install and configure Cygwin, the KFW binaries (for Kerberized source control access), PuTTY, and a custom build of the CVS client.

Please note: Prior to testing any of the configurations described below, please be sure that you have been granted permissions to access the SVN and CVS repositories. PuTTY will throw unintelligible errors if permissions have not been set properly.

===Installing and Cygwin and SVN===
# Download a copy of the Cygwin installer [http://www.cygwin.com/ here]. Save it too your local machine (note the location, as this executable is required to make any modifications to you Cygwin distribution).
# Run '''setup.exe'''
# Click '''Next''' through the introduction and download screens, accepting the default values.
# When prompted, change the root directory of the Cygwin installation to '''C:\tools\cygwin''', and click '''Next'''.
# When choosing a directory to store the installation packages, you may accept the default, though this might place the files in temporary internet files directory. If you want these packages to be available for reinstallation at a later time, choose a more suitable directory (i.e. '''C:\cyginstall'''). Click '''Next'''.
# Leave the default connection settings, and click '''Next'''
# Choose a download site from the list, and click '''Next'''
# In the ''Choose Packages'' screen, mark the Devel/Subversion package for installation, and click '''Next'''. The installer will proceed to download and install the selected packages.
# Click '''Finish'''. The installer will close.
# Open the '''Control Panel -> System''' applet. Click the '''Advanced''' tab and click '''Environment Variables'''.
# Under the '''System Variables''' list, double-click '''Path''' (possibly listed as '''PATH'''), add a semicolon after the last entry and add '''C:\tools\cygwin\bin''' to the variable. Click '''OK''' on each window to close it, accepting changes.
# Open Windows Explorer and navigate to the Cygwin bin directory ('''C:\tools\cygwin\bin''').
# Delete '''awk.exe''' (this is a symbolic link that the Windows shell doesn't handle properly).
# Copy '''gawk.exe''' and rename it to '''awk.exe'''.

===Installing the KfW Binaries===
If you are not currently using a pre-built version of KfW, you'll need to install one now in order to use Kerberized source control access.

# Download a copy of the '''MIT Kerberos for Windows''' MSI installer [http://web.mit.edu/kerberos/dist/ here]. Run the MSI.
# Accept the default install options.
# Once setup completes, launch the '''Network Identity Manager (NIM)''' from the '''Kerberos for Windows''' folder in the '''Start Menu'''. By default, it should be configured for the ATHENA.MIT.EDU realm.
# Create new credentials using you Athena username and password, and minimize NIM (this should hide it in the taskbar).

===Installing PuTTY===
PuTTY will provide the Kerberized SSH connection to our SVN repository.
# Download a copy of the '''PuTTY with GSSAPI Extensions''' archive [http://www.sweb.cz/v_t_m/putty/PuTTY-0.58-GSSAPI-2005-07-24.zip here]. Note, there are several distributions of PuTTY that support Kerberos. You may choose the one that works best for you.
# Unzip the archive to '''C:\tools\putty'''.
# Launch '''C:\tools\putty\putty.exe'''.
# Using the tree on the left, navigate to the '''Connection -> Data''' screen and enter your Athena username as the '''Auto-login username'''.
# Open the '''Connection --> SSH --> Auth screen'''. In Authentication Methods, select '''Attempt "keyboard-interactive" auth (SSH-2)''' and '''Attempt Kerberos 5 GSSAPI/SSPI auth (SSH-2)'''. In Authentication parameters, select '''Allow Kerberos 5 ticket forwarding in GSSAPI/SSF''' and enter '''ATHENA.MIT.EDU''' as the '''Server realm'''.
# Open the '''Session''' screen. Select (highlight) '''Default Settings''' from the list and click '''Save'''.
# Close the PuTTY configuration windows.

===Configuring SVN & PuTTY===
# Open the '''Control Panel -> System''' applet. Click the '''Advanced''' tab and click '''Environment Variables'''.
# Under the '''System Variables''' list, double-click '''Path''' (possibly listed as '''PATH'''), add a semicolon after the last entry and add '''C:\tools\putty''' to the variable. Click '''OK''' on each window to close it, accepting changes.
# Under the '''System Variables''' list, add a '''SVN_SSH''' variable and give it the value '''plink.exe'''.
# Create a directory to house a temporary SVN snapshot (i.e. '''C:\kfw\svn''').
# Open the Command Prompt ('''Start -> Run -> cmd''') and type:
#:<code>plink svn.mit.edu</code>
#:Please note, it's important to run plink once before attempting to use it with SVN, because when connecting to the server for the first time there will be interactive prompts that SVN does not support.
# You may be prompted to add the server to your trusted list. If so, type '''y''' and hit '''Enter'''. Once the connection completes, hit '''Ctrl+C''' to end plink. It should ''not'' prompt you for a password at any time. If so, your Kerberos credentials have not been configured correctly or have expired.
# Now that we've confirmed plink is working with a Kerberized connection, we need to checkout a snapshot of the SVN repository. In the Command Prompt type:
#:<code>svn co svn+ssh://svn.mit.edu/krb5/trunk C:\kfw\svn</code>
If your SVN client is properly configured, you should get a complete snapshot of the Krb5 trunk from the SVN repository, now located in C:\kfw\svn (or another directory of your choosing).

===Installing CVS===
# Download a copy of CVS that supports Kerberos authentication. While there doesn't appear to be a readily accessible CVS client distribution that supports Kerberos, you can use the cvs client found [http://web.mit.edu/rsilk/Public/Kerberos/Utils/cvs.exe here].
# '''Move''' the file to your Cygwin binary directory (i.e.''' C:\tools\cygwin\bin''').

==Configuring the Build Tools==
Now that we have access to the repositories and have a snapshot of the SVN trunk, we need to install the required Microsoft libraries. We also need to install ActiveState Perl in order to run the build script. Finally, we need to install the remaining build tools required for documentation generation and packaging.

===Configuring Microsoft Visual Studio===
This guide assumes you have a working version of Microsoft Visual Studio 2005 Standard or later. Be sure to install the 64 bit libraries in addition to the standard 23 bit libraries if you intend to build for both architectures.

===Installing the Microsoft Windows SDK===
# Download a copy of the '''Microsoft Windows SDK''' (version 6.1 or later) [http://www.microsoft.com/downloads/details.aspx?FamilyId=E6E1C3DF-A74F-4207-8586-711EBE331CDC&displaylang=en here].
# Run the installer, accepting all default options (though you may need to select the 64 bit libraries if desired).

===Installing ActiveState Perl===
# Download a copy of '''ActiveState Perl''' (currently version 5.10.0.1005) [http://www.activestate.com/activeperl/downloads/ here].
# Run the installer, accepting all default options. This should automatically add the Perl directory to your system path.

===Installing Microsoft HTML Help Workshop===
# Download a copy of '''Microsoft HTML Help Workshop''' (currently version 1.3) [http://go.microsoft.com/fwlink/?linkid=14188 here].
# Run the installer, accepting all default options. Please note, the installer may complain that you already have a newer version of Help Workshop installed. Ignore this error; the installer will complete successfully..
# Open the '''Control Panel -> System''' applet. Click the '''Advanced''' tab and click '''Environment Variables'''.
# Under the '''System Variables''' list, double-click '''Path''' (possibly listed as '''PATH'''), add a semicolon after the last entry and add '''C:\Program Fles\HTML Help Workshop''' to the variable. Click '''OK''' on each window to close it, accepting changes.

===Installing the Windows Help Authoring Kit===
Depending on your build configuration, you may also need the '''Windows Help Authoring Kit'''.
# Download a copy of the '''Windows Help Authoring Kit''' [http://www.microsoft.com/downloads/details.aspx?FamilyID=34D35502-4DE9-4676-952C-34CC7F64F098&displaylang=en here].
# Run the installer, accepting all default options.
# Open the '''Control Panel -> System''' applet. Click the '''Advanced''' tab and click '''Environment Variables'''.
# Under the '''System Variables''' list, double-click '''Path''' (possibly listed as '''PATH'''), add a semicolon after the last entry and add '''C:\Program Fles\Help Workshop''' to the variable. Click '''OK''' on each window to close it, accepting changes.

===Installing Doxygen===
# Download a copy of the '''Doxygen distribution for Windows''' (currently version 1.5.9) [http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc here].
# Run the installer, accepting all default options. This should automatically add the Doxygen directory to your system path.

===Installing WiX===
# Download a copy of the Windows Install XML ('''WiX''') core toolset (currently version 2.0) [http://wix.sourceforge.net/downloadv2.html here].
# Unzip the archive to '''C:\tools\wix'''.
# Open the '''Control Panel -> System''' applet. Click the '''Advanced''' tab and click '''Environment Variables'''.
# Under the '''System Variables''' list, double-click '''Path''' (possibly listed as '''PATH'''), add a semicolon after the last entry and add '''C:\tools\wix''' to the variable. Click '''OK''' on each window to close it, accepting changes.

===Installing NSIS===
# Download a copy of the Nullsoft Scriptable Install System (NSIS - currently version 2.45) [http://nsis.sourceforge.net/Download here].
# Run installer, accepting all default options.
# Open the '''Control Panel -> System''' applet. Click the '''Advanced''' tab and click '''Environment Variables'''.
# Under the '''System Variables''' list, double-click '''Path''' (possibly listed as '''PATH'''), add a semicolon after the last entry and add '''C:\Program Files\NSIS''' to the variable. Click '''OK''' on each window to close it, accepting changes.

===Installing Windows Support Tools===
On some machines you may need to install the '''Windows XP SP2 Support Tools''' package to get the '''filever.exe''' utility (which is currently required by the build script).
# Download a copy of the '''Windows XP SP2 Support Tools''' package [http://www.microsoft.com/downloads/details.aspx?FamilyID=49ae8576-9bb9-4126-9761-ba8011fabf38&displaylang=en here].
# Run the installer, accepting all default options.

Kerberos for Windows (KfW) Build Environment

2012-09-19T19:58:10Z

BenKaduk: Kerberos for Windows (KfW) Build Environment moved to Kerberos for Windows (KfW) 3.2.x Build Environment: The build environment requirements will change for KfW 4.0

#REDIRECT [[Kerberos for Windows (KfW) 3.2.x Build Environment]]

Kerberos for Windows Release Engineering

2012-09-19T19:40:48Z

BenKaduk:

Kerberos for Windows Release Engineering

2012-09-17T19:21:03Z

BenKaduk: we resolved some issues

Kerberos for Windows Release Engineering

2012-09-17T19:19:49Z

BenKaduk:

Kerberos for Windows Release Engineering

2012-08-22T17:04:43Z

BenKaduk:

Release Engineering notes for the Kerberos for Windows 4.0.0 release

Software to test against new builds:
* SapGUI
* OpenAFS
* SecureCRT (and SecureFX?)
* SPNEGO (in multiple browsers?)
* Adobe Keyserver a.k.a the Sassafras key client
* SMTP in some form?
* LDAP in some form?
* XMPP in some form (pidgin?)?

Upgrades scenarios to test:
* 32-bit to 32-bit, from 3.2
* 64-bit to 64-bit, from 3.2
* 32-bit to 64-bit, from 3.2
* 32-bit and 64-bit to 64-bit, from 3.2
* 32-bit to 64-bit, from 4.0
* 64-bit to 32-bit, from 4.0
When starting from 3.2, it probably suffices to test the Secure Endpoints versions once only, and assume that there will not be future changes to 4.0 which cause the upgrade process to fail for the SE version but not the MIT-distributed version.
The NSIS upgrade path is a separate codepath and should be tested separately.

Current known issues:
* The version number implanted in various dlls may no longer reflect the underlying krb5 version (instead using the KfW version)
* windows/README is outdated
* Thunderbird cannot do GSSAPI auth
* Our DllMain attach/detach handler spews to the terminal when running command-line utilities. Possibly other debug print statements, too.

Issues that we believe to be resolved:
* The uninstaller prompts to kill running processes but does not do succeed in doing so. There may be cases in which it just kills processes without prompting, which may still be a bug.
* The upgrade procedure attempts to kill running processes but does not succeed in doing so (these two may be sharing most of the code). The wix-users archives suggest that Util:CloseApplication may be useful to do this in pure WiX instead of a custom element
* There is a report of crashes on a multiprocessor machine unless CPU-pinning is used
* Uninitialized (NULL) TLS pointers that were most prominent on multi-processor machines, causing internal ccache errors that were reported as "unknown error" due to another minor bug.

Kerberos for Windows Release Engineering

2012-08-22T16:12:29Z

BenKaduk:

Release Engineering notes for the Kerberos for Windows 4.0.0 release

Software to test against new builds:
* SapGUI
* OpenAFS
* SecureCRT (and SecureFX?)
* SPNEGO (in multiple browsers?)
* Adobe Keyserver a.k.a the Sassafras key client
* SMTP in some form?
* LDAP in some form?
* XMPP in some form (pidgin?)?

Upgrades scenarios to test:
* 32-bit to 32-bit, from 3.2
* 64-bit to 64-bit, from 3.2
* 32-bit to 64-bit, from 3.2
* 32-bit and 64-bit to 64-bit, from 3.2
* 32-bit to 64-bit, from 4.0
* 64-bit to 32-bit, from 4.0
When starting from 3.2, it probably suffices to test the Secure Endpoints versions once only, and assume that there will not be future changes to 4.0 which cause the upgrade process to fail for the SE version but not the MIT-distributed version.

Current known issues:
* The version number implanted in various dlls may no longer reflect the underlying krb5 version (instead using the KfW version)
* windows/README is outdated
* Thunderbird cannot do GSSAPI auth
* Our DllMain attach/detach handler spews to the terminal when running command-line utilities. Possibly other debug print statements, too.

Issues that we believe to be resolved:
* The uninstaller prompts to kill running processes but does not do succeed in doing so. There may be cases in which it just kills processes without prompting, which may still be a bug.
* The upgrade procedure attempts to kill running processes but does not succeed in doing so (these two may be sharing most of the code). The wix-users archives suggest that Util:CloseApplication may be useful to do this in pure WiX instead of a custom element
* There is a report of crashes on a multiprocessor machine unless CPU-pinning is used
* Uninitialized (NULL) TLS pointers that were most prominent on multi-processor machines, causing internal ccache errors that were reported as "unknown error" due to another minor bug.

Kerberos for Windows Release Engineering

2012-08-20T23:13:17Z

BenKaduk: Move some issues into the (new) "we think they're fixed" category

Release Engineering notes for the Kerberos for Windows 4.0.0 release

Software to test against new builds:
* SapGUI
* OpenAFS
* SecureCRT (and SecureFX?)
* SPNEGO (in multiple browsers?)
* Adobe Keyserver a.k.a the Sassafras key client
* SMTP in some form?
* LDAP in some form?
* XMPP in some form (pidgin?)?

Upgrades scenarios to test:
* 32-bit to 32-bit, from 3.2
* 64-bit to 64-bit, from 3.2
* 32-bit to 64-bit, from 3.2
* 32-bit and 64-bit to 64-bit, from 3.2
* 32-bit to 64-bit, from 4.0
* 64-bit to 32-bit, from 4.0
When starting from 3.2, it probably suffices to test the Secure Endpoints versions once only, and assume that there will not be future changes to 4.0 which cause the upgrade process to fail for the SE version but not the MIT-distributed version.

Current known issues:
* The version number implanted in various dlls may no longer reflect the underlying krb5 version (instead using the KfW version)
* windows/README is outdated
* Thunderbird cannot do GSSAPI auth

Issues that we believe to be resolved:
* The uninstaller prompts to kill running processes but does not do succeed in doing so. There may be cases in which it just kills processes without prompting, which may still be a bug.
* The upgrade procedure attempts to kill running processes but does not succeed in doing so (these two may be sharing most of the code). The wix-users archives suggest that Util:CloseApplication may be useful to do this in pure WiX instead of a custom element
* There is a report of crashes on a multiprocessor machine unless CPU-pinning is used
* Uninitialized (NULL) TLS pointers that were most prominent on multi-processor machines, causing internal ccache errors that were reported as "unknown error" due to another minor bug.

Kerberos for Windows Release Engineering

2012-08-16T21:42:05Z

BenKaduk:

Release Engineering notes for the Kerberos for Windows 4.0.0 release

Software to test against new builds:
* SapGUI
* OpenAFS
* SecureCRT (and SecureFX?)
* SPNEGO (in multiple browsers?)
* Adobe Keyserver a.k.a the Sassafras key client
* SMTP in some form?
* LDAP in some form?
* XMPP in some form (pidgin?)?

Upgrades scenarios to test:
* 32-bit to 32-bit, from 3.2
* 64-bit to 64-bit, from 3.2
* 32-bit to 64-bit, from 3.2
* 32-bit and 64-bit to 64-bit, from 3.2
* 32-bit to 64-bit, from 4.0
* 64-bit to 32-bit, from 4.0
When starting from 3.2, it probably suffices to test the Secure Endpoints versions once only, and assume that there will not be future changes to 4.0 which cause the upgrade process to fail for the SE version but not the MIT-distributed version.

Current known issues:
* The uninstaller prompts to kill running processes but does not do succeed in doing so
* The upgrade procedure attempts to kill running processes but does not succeed in doing so (these two may be sharing most of the code). The wix-users archives suggest that Util:CloseApplication may be useful to do this in pure WiX instead of a custom element
* The version number implanted in various dlls may no longer reflect the underlying krb5 version (instead using the KfW version)
* windows/README is outdated
* Thunderbird cannot do GSSAPI auth
* There is a report of crashes on a multiprocessor machine unless CPU-pinning is used

Kerberos for Windows Release Engineering

2012-08-15T00:30:38Z

BenKaduk:

Release Engineering notes for the Kerberos for Windows 4.0.0 release

Software to test against new builds:
* SapGUI
* OpenAFS
* SecureCRT (and SecureFX?)
* SPNEGO (in multiple browsers?)
* Adobe Keyserver a.k.a the Sassafras key client
* SMTP in some form?
* LDAP in some form?
* XMPP in some form (pidgin?)?

Upgrades scenarios to test:
* 32-bit to 32-bit, from 3.2
* 64-bit to 64-bit, from 3.2
* 32-bit to 64-bit, from 3.2
* 32-bit and 64-bit to 64-bit, from 3.2
* 32-bit to 64-bit, from 4.0
* 64-bit to 32-bit, from 4.0
When starting from 3.2, it probably suffices to test the Secure Endpoints versions once only, and assume that there will not be future changes to 4.0 which cause the upgrade process to fail for the SE version but not the MIT-distributed version.

Current known issues:
* The uninstaller prompts to kill running processes but does not do succeed in doing so
* The upgrade procedure attempts to kill running processes but does not succeed in doing so (these two may be sharing most of the code). The wix-users archives suggest that Util:CloseApplication may be useful to do this in pure WiX instead of a custom element
* The version number implanted in various dlls may no longer reflect the underlying krb5 version (instead using the KfW version)
* windows/README is outdated

Kerberos for Windows Release Engineering

2012-08-14T22:06:26Z

BenKaduk:

Release Engineering notes for the Kerberos for Windows 4.0.0 release

Software to test against new builds:
* SapGUI
* OpenAFS
* SecureCRT (and SecureFX?)
* SPNEGO (in multiple browsers?)
* Adobe Keyserver a.k.a the Sassafras key client
* SMTP in some form?
* LDAP in some form?
* XMPP in some form (pidgin?)?

Upgrades scenarios to test:
* 32-bit to 32-bit, from 3.2
* 64-bit to 64-bit, from 3.2
* 32-bit to 64-bit, from 3.2
* 32-bit and 64-bit to 64-bit, from 3.2
* 32-bit to 64-bit, from 4.0
* 64-bit to 32-bit, from 4.0

Current known issues:
* The uninstaller prompts to kill running processes but does not do succeed in doing so
* The upgrade procedure attempts to kill running processes but does not succeed in doing so (these two may be sharing most of the code). The wix-users archives suggest that Util:CloseApplication may be useful to do this in pure WiX instead of a custom element
* The version number implanted in various dlls may no longer reflect the underlying krb5 version (instead using the KfW version)
* windows/README is outdated

Kerberos for Windows Release Engineering

2012-08-14T21:54:17Z

BenKaduk: New page: Release Engineering notes for the Kerberos for Windows 4.0.0 release Software to test against new builds: * SapGUI * OpenAFS * SecureCRT (and SecureFX?) * SPNEGO (in multiple browsers?) *...

Release Engineering notes for the Kerberos for Windows 4.0.0 release

Software to test against new builds:
* SapGUI
* OpenAFS
* SecureCRT (and SecureFX?)
* SPNEGO (in multiple browsers?)
* Adobe Keyserver a.k.a the Sassafras key client
* SMTP in some form?
* LDAP in some form?
* XMPP in some form (pidgin?)?

Upgrades scenarios to test:
* 32-bit to 32-bit, from 3.2
* 64-bit to 64-bit, from 3.2
* 32-bit to 64-bit, from 3.2
* 32-bit and 64-bit to 64-bit, from 3.2
* 32-bit to 64-bit, from 4.0
* 64-bit to 32-bit, from 4.0

Current known issues:
* The uninstaller prompts to kill running processes but does not do succeed in doing so
* The upgrade procedure attempts to kill running processes but does not succeed in doing so (these two may be sharing most of the code)
* The version number implanted in various dlls may no longer reflect the underlying krb5 version (instead using the KfW version)
* windows/README is outdated

Projects/Documentation Tasks

2012-07-17T19:03:12Z

BenKaduk: Mention desire for examples of API usage

{{project-early}}

== Purpose ==

To keep track of the various tasks that need to be documented such as function documentation, administration, troubleshooting etc.

{| class="wikitable"
|+ Matrix of Document-Type VS Intended Readership
|-
! Doc-type/Reader
! Architectural Guide
! Setup & Config of Kerberos
! Admin & Operations of Kerberos
! Custom Build
! API Description
! API Details
|-
|-
| End-users || || || || || ||
|-
| Architects || || || || || ||
|-
|System Admins || || || || || ||
|-
|Application Developers || || || || || ||
|-
|GSSAPI Developers || || || || || ||
|-
|Kerberos Developers || || || || || ||
|}

== Application development ==

{| class="wikitable"
|+
|-
! task
! Proposed Author
! Target Date
! Reviewer
! Reviewer Comments
|-
|-
| Designing a new protocol, or extending existing one, to use GSS-API || NW || || ||
|-
| Choosing security API|| || || ||
|-
| <ul><li> GSS-API vs SASL vs KRB5 </ul>|| NW || || ||
|-
| <ul><li> A guide to the similarities and differences between Heimdal and MIT Kerberos API </ul>|| NW || || ||
|-
| GSS-API || || || ||
|-
| <ul><li> A basic introduction to GSS-API, making use of the sample client and server, with special attention paid to Kerberos-related GSS-API issues</ul>|| NW || || ||
|-
| <ul><li> How to tell the GSS-API library on the client side where the existing Kerberos ticket cache is </ul>|| NW || || ||
|-
| <ul><li> How to write mechanism-independent GSS-API code</ul>|| NW || || ||
|-
| <ul><li> Acceptor naming - How to get servers to use any key in a keytab</ul>|| GH||2012-03-01|| || ready for review
|-
| <ul><li> A guide to GSS-API naming as compared to Kerberos principal naming</ul>|| NW || || ||
|-
| <ul><li> Using IAKERB</ul>|| || || ||
|-
| <ul><li> Anonymous credentials</ul>|| GH ||2012-10-01 || ||
|-
| <ul><li> Delegating credentials</ul>|| GH ||2012-10-01 || ||
|-
| <ul><li> Available extensions</ul>|| NW || || ||
|-
| <ul><li> Thread safety</ul>|| KR || || ||
|-
| <ul><li> Validating the flags set on the connection to ensure things like mutual authentication, confidentiality, integrity, replay protection, and sequence protection</ul>|| || || ||
|-
| Developing plugins|| GH ||2012-03-08|| || ready for review
|-
| <ul><li> A guide to developing plugins </ul>|| || || ||
|-
| <ul><li>Overview of existing pluggable interfaces </ul>|| || ||ZT reviewed profile plugin ||
|-
| Krb5 library guide|| || || ||
|-
| <ul><li> A more advanced introduction to using the Kerberos libraries for initial authentication, focusing on the authentication steps, validating initial credential</ul>|| TY || 2012-04-27 ||need examples ||
|-
| <ul><li> Kerberos prompter behavior</ul>|| NW || || ||
|-
| <ul><li> An introduction to ticket caches and keytabs and their corresponding APIs </ul>|| KR || || || under review
|-
| <ul><li> An advanced guide to the pre-auth mechanisms, FAST</ul>|| || || ||
|-
| <ul><li> An advanced guide to the principal manipulation and parsing</ul>|| TY || TBD || ||
|-
| <ul><li> Thread safety</ul>|| KR || || ||
|-
| <ul><li> Password change including the automatic internal support for password change on expired passwords if a prompter is provided</ul>|| || || ||
|-
| <ul><li> krb5_appdefault_* functions and their alternatives </ul>|| || || ||
|-
| MIT Kerberos features : quick facts || ZT || ongoing || ||
|-
| How to build Kerberos from source || ZT || || || ready for review
|-
|}

== Administration ==

{| class="wikitable"
|+
|-
! task
! Proposed Author
! Target Date
! Reviewer
! Reviewer Comments
|-
| Introduction to Kerberos system || || || ||
|-
|<ul><li>Man page </ul>|| TH || 2012-07-15|| ||
|-
|<ul><li>General overview</ul>|| TH ||2012-07-15 || ||
|-
|Setting a new realm|| || || ||
|-
|<ul><li>Choosing backend: LDAP vs DB2</ul>|| || || ||
|-
|<ul><li>Replication</ul>|| ZT|| || ||ready for review
|-
|<ul><li> DNS configuration and SRV records - how they are used, in what order</ul>|| KR || || ||
|-
| Reverse DNS|| TY|| 2012-10-01|| ||
|-
| Choosing encryption types for principals|| TY|| 2012-10-01|| ||
|-
| Integration Kerberos with Login System|| || || ||
|-
| <ul><li> Difference between real Kerberos authentication, Kerberos password verification on the server side, and "LDAP authentication" in a Kerberos environment</ul>|| || || ||
|-
| <ul><li> Validating Kerberos tickets</ul>|| || || ||
|-
| <ul><li> Clear text password over HTTPS </ul>|| NW || || ||
|-
| <ul><li> Configuring with pam_krb5 module</ul>|| NW || || ||
|-
| <ul><li> Storing/locating keytab</ul>|| || || ||
|-
| Cross-realm|| || || ||
|-
| <ul><li>cross-realm interaction with AD </ul>|| || || ||
|-
| <ul><li> Transitive trust</ul>|| || || ||
|-
| <ul><li> Referrals</ul>|| || || ||
|-
| Performance|| || || ||
|-
| <ul><li> Performance tuning tips</ul>|| || || ||
|-
| <ul><li> Performance tradeoffs</ul>|| || || ||
|-
| kadmin interface|| || || ||
|-
| <ul><li> Keying workstation/ host key setting</ul>|| || || ||
|-
| Using Smartcard with PKINIT|| || || ||
|-
| Kerberized ssh|| NW || || ||
|-
| <ul><li> Configuration</ul>|| || || ||
|-
| <ul><li>Cross-realm and ssh</ul>|| || || ||
|-
| Selecting and configuring plugins|| GH ||2012-03-15|| || ready for review
|-
| Anonymity support|| GH ||2012-10-01 || ||
|-
| A guide to principal naming basics and structure|| || || ||
|-
| Troubleshooting|| || || ||
|-
| <ul><li>Troubleshooting errors</ul> || ZT || ongoing|| ||
|-
| <ul><li>Trace logging</ul>||GH ||2012-03-22|| || ready for review
|-
| <ul><li>Realm renaming </ul>|| || || ||
|-
| Using LDAP server for Kerberos backend|| ZT || || || Ubuntu 10.4 (lucid)
|-
| Basic concepts (passwd policy, ticket ) || || || ||
|-
| Approaches to authorization -- centralized vs distributed, etc. || || || ||
|-
| Acceptable date and time formats || ZT || 2012-07-15 || ||ready for review
|-
| kadm5.acl man page || ZT || 2012-08-15 || ||
|-
|}

== API documentation ==

===Most commonly used API functions (in alphabetical order)===

{| class="wikitable"
|+ Tier 1 - Highest priority
|-
! API
! Proposed Author
! Reviewer
! Target Date
! Reviewer Comments
|-
|-
| krb5_build_principal [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_build_principal.html]|| ZT || GH|| ||
|-
|krb5_build_principal_alloc_va [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_build_principal_alloc_va.html] || ZT || GH|| ||
|-
| krb5_build_principal_ext [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_build_principal_ext.html]|| ZT ||GH || ||
|-
| krb5_cc_close [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_close.html] ||ZT ||GH || ||
|-
| krb5_cc_default [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_default.html]|| ZT|| GH|| ||
|-
| krb5_cc_default_name [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_default_name.html]|| ZT|| GH|| ||
|-
| krb5_cc_destroy [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_destroy.html]|| ZT|| GH|| ||
|-
| krb5_cc_dup [http://web.mit.edu/kerberos/krb5-current/dockrb_appldev/refs/api/krb5_cc_dup.html]|| ZT|| GH|| ||
|-
| krb5_cc_get_name [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_get_name.html]|| ZT || GH|| ||
|-
| krb5_cc_get_principal [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_get_principal.html]|| ZT ||GH || ||
|-
| krb5_cc_get_type [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_get_type.html]|| ZT ||GH || ||
|-
| krb5_cc_initialize [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_initialize.html]|| ZT||GH || ||
|-
| krb5_cc_new_unique [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_new_unique.html]|| ZT|| GH|| ||
|-
| krb5_cc_resolve [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_cc_resolve.html]|| ZT|| GH|| ||
|-
| krb5_change_password [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_change_password.html]|| ZT||GH || ||
|-
| krb5_free_context [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_free_context.html]|| ZT|| GH|| ||
|-
| krb5_free_error_message [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_free_error_message.html]|| ZT ||GH || ||
|-
| krb5_free_principal [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_free_principal.html]|| ZT ||GH || ||
|-
| krb5_fwd_tgt_cred [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_fwd_tgt_cred.html]|| ZT || GH|| || Needs example
|-
| krb5_get_default_realm [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_default_realm.html]|| ZT || GH|| ||
|-
| krb5_get_error_message [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_error_message.html]|| ZT || GH|| ||
|-
| krb5_get_host_realm [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_host_realm.html]|| ZT ||GH || ||
|-
| krb5_get_credentials [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_credentials.html]|| ZT ||GH || ||
|-
| krb5_get_fallback_host_realm [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_fallback_host_realm.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_keytab [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_keytab.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_alloc [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_alloc.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_free [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_free.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_get_fast_flags [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_get_fast_flags.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_init [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_init.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_address_list [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_address_list.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_set_anonymous [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_anonymous.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_canonicalize [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_canonicalize.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_set_change_password_prompt [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_change_password_prompt.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_set_etype_list [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_etype_list.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_expire_callback [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_expire_callback.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_fast_ccache [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_fast_ccache.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_fast_ccache_name [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_fast_ccache_name.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_fast_flags [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_fast_flags.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_set_forwardable [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_forwardable.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_set_out_ccache [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_out_ccache.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_pa [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_pa.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_preauth_list [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_preauth_list.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_set_proxiable [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_proxiable.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_set_renew_life [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_renew_life.html]|| ZT || GH|| ||
|-
| krb5_get_init_creds_opt_set_salt [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_salt.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_opt_set_tkt_life [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_opt_set_tkt_life.html]|| ZT ||GH || ||
|-
| krb5_get_init_creds_password [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_init_creds_password.html]|| ZT || GH|| ||
|-
| krb5_get_profile [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_profile.html]|| ZT || GH|| ||
|-
| krb5_get_prompt_types [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_prompt_types.html]|| ZT ||GH || ||
|-
| krb5_get_renewed_creds [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_renewed_creds.html]|| ZT || GH|| ||
|-
| krb5_get_validated_creds [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_get_validated_creds.html]|| ZT || GH|| ||
|-
| krb5_init_context [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_init_context.html]|| ZT ||GH || ||
|-
| krb5_init_secure_context [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_init_secure_context.html]|| ZT || GH|| ||
|-
| krb5_is_config_principal [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_is_config_principal.html]|| ZT ||GH || ||
|-
| krb5_is_thread_safe [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_is_thread_safe.html]|| ZT ||GH || ||
|-
| krb5_kt_close [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_kt_close.html]|| ZT || GH|| ||
|-
| krb5_kt_default [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_kt_default.html]|| ZT ||GH || ||
|-
| krb5_kt_default_name [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_kt_default_name.html]|| ZT ||GH || ||
|-
| krb5_kt_get_name [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_kt_get_name.html]|| ZT ||GH || ||
|-
| krb5_kt_get_type [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_kt_get_type.html] || ZT ||GH || ||
|-
| krb5_kt_resolve [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_kt_resolve.html]|| ZT || GH|| ||
|-
| krb5_kuserok [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_kuserok.html] || ZT ||GH || ||
|-
| krb5_parse_name [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_parse_name.html]|| ZT ||GH || ||
|-
| krb5_parse_name_flags [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_parse_name_flags.html]|| ZT || GH|| ||
|-
| krb5_principal_compare [http://web.mit.edu/kerberos/krb5-current/dockrb_appldev/refs/api/krb5_principal_compare.html]|| ZT ||GH || ||
|-
| krb5_principal_compare_any_realm [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_principal_compare_any_realm.html]|| ZT || GH|| ||
|-
| krb5_principal_compare_flags [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_principal_compare_flags.html]|| ZT ||GH || ||
|-
| krb5_prompter_posix [http://web.mit.edu/kerberos/krb5-current/dockrb_appldev/refs/api/krb5_prompter_posix.html]|| ZT||GH || ||
|-
| krb5_realm_compare [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_realm_compare.html]|| ZT ||GH || ||
|-
| krb5_recvauth [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_recvauth.html]||ZT ||GH || ||
|-
| krb5_recvauth_version [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_recvauth_version.html] ||ZT ||GH || ||
|-
| krb5_set_default_realm [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_set_default_realm.html]|| ZT ||GH || ||
|-
| krb5_set_password [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_set_password.html]|| ZT || GH|| ||
|-
| krb5_set_password_using_ccache [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_set_password_using_ccache.html] || ZT ||GH || ||
|-
| krb5_set_principal_realm [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_set_principal_realm.html] || ZT || GH|| ||
|-
| krb5_set_trace_callback [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_set_trace_callback.html]|| ZT ||GH || ||
|-
| krb5_set_trace_filename [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_set_trace_filename.html]|| ZT ||GH || ||
|-
| krb5_sname_to_principal [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_sname_to_principal.html]|| ZT ||GH || ||
|-
| krb5_unparse_name [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_unparse_name.html]|| ZT || GH|| ||
|-
| krb5_unparse_name_ext [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_unparse_name_ext.html]|| ZT ||GH || ||
|-
| krb5_unparse_name_flags [http://web.mit.edu/kerberos/krb5-current/dockrb_appldev/refs/api/krb5_unparse_name_flags.html] || ZT || GH|| ||
|-
| krb5_unparse_name_flags_ext [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_unparse_name_flags_ext.html] || ZT ||GH || ||
|-
| krb5_us_timeofday [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_us_timeofday.html]|| ZT || GH|| ||
|-
| krb5_verify_authdata_kdc_issued [http://web.mit.edu/kerberos/krb5-current/doc/krb_appldev/refs/api/krb5_verify_authdata_kdc_issued.html]|| ZT || GH|| ||
|-
|}
We may want to have more examples for some of the common API funcitons.

== Manpage proofreading ==
{| class="wikitable"
|+
|-
! manpage
! original
! reviewer
! comments
|-
| k5identity.5 || src/gen-manpages/k5identity.M || GH ||
|-
| k5login.5 || src/gen-manpages/k5login.M || GH ||
|-
| k5srvutil.1 || src/kadmin/cli/k5srvutil.M || GH ||
|-
| kadmin.1 || src/kadmin/cli/kadmin.M || GH ||
|-
| kadmind.8 || src/kadmin/server/kadmind.M || GH ||
|-
| kdb5_ldap_util.8 || src/plugins/kdb/ldap/ldap_util/kdb5_ldap_util.M || GH ||
|-
| kdb5_util.8 || src/kadmin/dbutil/kdb5_util.M || GH ||
|-
| kdc.conf.5 || src/config-files/kdc.conf.M || GH ||
|-
| kdestroy.1 || src/clients/kdestroy/kdestroy.M || GH ||
|-
| kinit.1 || src/clients/kinit/kinit.M || GH ||
|-
| kpasswd.1 || src/clients/kpasswd/kpasswd.M || GH ||
|-
| kprop.8 || src/slave/kprop.M || GH ||
|-
| kpropd.8 || src/slave/kpropd.M || GH ||
|-
| kproplog.8 || src/slave/kproplog.M || GH ||
|-
| krb5-send-pr.1 || src/util/send-pr/send-pr.1 || || copyright issues. Removed from the documentation
|-
| krb5.conf.5 || src/config-files/krb5.conf.M || GH ||
|-
| krb5kdc.8 || src/kdc/krb5kdc.M || GH ||
|-
| ksu.1 || src/clients/ksu/ksu.M || GH || needs rewrite
|-
| kswitch.1 || src/clients/kswitch/kswitch.M || GH ||
|-
| kvno.1 || src/clients/kvno/kvno.M || GH ||
|-
| sclient.1 || src/appl/sample/sclient/sclient.M || GH ||
|-
| sserver.8 || src/appl/sample/sserver/sserver.M || GH ||
|}

== Abbreviations ==

{| class="wikitable"
|+
|-
! abbreviation
! full names?
|-
|-
| GH || Greg Hudson
|-
| KR || Ken Raeburn
|-
| MIT || MITKC group
|-
| NW || Nico Williams
|-
| TH || Thomas Hardjono
|-
| TY || Tom Yu
|-
| ZT || Zhanna Tsitkov
|-
|}

Test suite

2012-07-03T19:59:49Z

BenKaduk: reverse-resolution test suite issues

[[Category:Lore]]
== Additional build requirements for running "make check" ==

The following additional software (in addition to the requirements at [[Building]]) is needed to run "make check". As for the packages listed at [[Building]], the software packages are identified by their Debian / Ubuntu package names.

* csh (for some of the Berkeley DB tests)
* dejagnu (for many dejagnu-based tests)
* expect (needed by dejagnu)
* g++ (for some API sanity checks)
* portmap (for lib/rpc/unit-test)
* tcl (needed by expect)
* tcl-dev (to build some kadm5 test programs)

== Known test suite issues ==

On Linux systems, sometimes the <code>--disable-rpath</code> option to <code>configure</code> is required in order to avoid problems with previously-installed versions of MIT krb5. Alternatively, you can run "make install" before "make check".

Prior to krb5-1.9, calls to krb5_c_random_os_entropy that pass the value 1 in the <code>strong</code> argument (which causes the library to read from the strong OS random number source) can cause stalls and timeouts in the test suite. Changing those calls to pass 0 instead will reduce the stalls. Starting in krb5-1.9, we disable the reading of strong random numbers during tests. This is primarily a problem on Linux systems.

Prior to krb5-1.9, the test suite tripped a bug where Dejagnu breaks the autoloading required by modern versions of Tcl. This manifests as errors such as:

<pre>
ERROR: (DejaGnu) proc "::tcl::tm::UnknownHandler ::tclPkgUnknown msgcat 1.4" does not exist.
</pre>

The Dejagnu maintainers are aware of this problem (http://lists.gnu.org/archive/html/dejagnu/2011-03/msg00002.html), but as of June 2011 there doesn't seem to be a release containing the fix. Since krb5-1.9, the offending piece of Tcl code (<code>clock format [clock seconds]</code>) is no longer used. A fix has been applied to the krb5-1.8 branch as well. ({{bug|6926}})

If an existing kdc.conf exists in the "installed" location, it can disrupt the automated tests, especially if it contains syntax errors.

On older Debian or Ubuntu systems, a bug in <code>expect</code> could cause stalls in the dejagnu parts of the test suite. It is documented at http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=421187. Current stable releases of Debian and Ubuntu no longer have an affected version of the <code>expect</code> package.

As of July 2012, portions of the test suite will fail if the current hostname does not properly resolve (e.g., if a hostname is set, but the IP address assigned via DHCP corresponds to a different name); setting explicit entries in <code>/etc/hosts</code> should be an effective workaround (an IPv6 entry may be needed in addition to an IPv4 entry).

Manual Testing

2012-07-03T19:30:40Z

BenKaduk:

This page describes manual testing procedures. There are two reasons these exist:

# Manual testing is sometimes simpler than running an automated test and instrumenting it.
# In some cases we have a manual testing procedure for part of the code, but not an automated test.

We do have an automated [[Test suite]].

==Basic Test KDC Setup==

Test KDCs are a crucial building block of testing. You can set one up easily by running "make testrealm" in the top level of a build tree, or you can follow these steps to set one up by hand:

1. Pick a name for your test KDC; this example will assume EXAMPLE.COM.

2. Do a build and install of the krb5 sources into some prefix; this example will assume /usr/local, but anywhere is fine. Put the prefix's bin and sbin directories in your path, or use full pathnames for the commands below.

3. Pick two port numbers, for the KDC and admin server. This example will assume 50000 and 50001.

4. Set up a krb5.conf file somewhere; this example will assume /usr/local/etc/krb5.conf. Make it look something like:
[libdefaults]
default_realm = EXAMPLE.COM
# Depending on what you are testing, you may want something like:
# default_keytab_name = FILE:/usr/local/var/keytab
[realms]
EXAMPLE.COM = {
admin_server = 127.0.0.1:50001
kdc = 127.0.0.1:50000
database_module = DB2
kdc_ports = 50000
kadmind_port = 50001
}
[dbmodules]
DB2 = {
db_library = db2
}
[logging]
# Use any pathnames you want here.
kdc = FILE:/usr/local/var/krb5kdc/kdc.log
admin_server = FILE:/usr/local/var/krb5kdc/kadmin.log
# Depending on what you are testing, you may want:
# [domain_realm]
# .your.domain = EXAMPLE.COM
Set the environment variable KRB5_CONFIG to the pathname of this krb5.conf file. Set the environment variable KRB5_KDC_PROFILE to /dev/null.

5. Run:
kdb5_util create -s
Enter a master password; it can be something insecure like "master". The DB will be created in /usr/local/var/krb5kdc/principal and a few other similarly-named files. The master key stash will be created in /usr/local/var/krb5kdc/.k5.EXAMPLE.COM.

6. Run:
kadmin.local
addprinc user
quit
Enter a user password; it can be something insecure like "user".

7. Start the KDC by running:
krb5kdc
Check the log file specified in krb5.conf if the KDC has any trouble starting. You should be able to "kinit user" at this point.

8. If you need kadmind, add another principle user/admin (using kadmin.local as described above), and create the file /usr/local/var/krb5kdc/kadm5.acl containing:
user/admin *
Then start the kadmind server with:
kadmind
If it has trouble starting, check the log file specified in krb5.conf.

==Services4User testing==

A test for Services4User can be found in tests/gssapi/t_s4u.c. You will need a W2K3 or higher AD domain to test this. Notes follow:

* Create a computer account FOO$ using Active Directory Users & Computers (ADUC)
* Set the UPN to host/foo.domain (no suffix); this is necessary to be able to send an AS-REQ as this principal, otherwise you would need to use the canonical name (FOO$), which will cause principal comparison errors in gss_accept_sec_context() (note: apparently only W2K8 supports suffix-less UPNs; you should use the domain as a suffix for earlier versions). There is an attribute editor in the W2K8 ADUC that lets you do this, otherwise you will need to use LDP.exe or a generic LDAP client.
* Add a SPN of host/foo.domain. (Again, you can use ADUC in W2K8, or LDP.exe/generic client.)
* Configure the computer account to support constrained delegation with protocol transition (Trust this computer for delegation to specified services only / Use any authentication protocol)
* Add host/foo.domain to the keytab (possibly easiest to do this manually with ktadd)

For S4U2Proxy to work the TGT must be forwardable too.

<pre>
kinit -k -t test.keytab -f 'host/test.win.mit.edu@WIN.MIT.EDU'
./t_s4u delegtest@WIN.MIT.EDU HOST/winhost.win.mit.edu@WIN.MIT.EDU test.keytab
</pre>

In the above example delegtest@WIN.MIT.EDU is the principal on whose behalf credentials are acquired using S4U2Self; HOST/winhost.win.mit.edu is the host to which we wish to delegate using S4U2Proxy; and test.keytab contains the long term key for test.win.mit.edu.

To test S4U2Self with the MIT KDC, set the ok_to_auth_as_delegate attribute on the service principal using kadmin.

==GSS-API Naming Extensions testing==

Note: the S4U test also tests the GSS-API naming extensions, but there also is a specific test in tests/gssapi/t_namingexts.c. This tests the following APIs:

* gss_import_name() with composite names
* gss_inquire_name()
* gss_get_name_attribute()
* gss_set_name_attribute()
* gss_delete_name_attribute()
* gss_export_name_composite()
* gss_map_name_to_any
* gss_release_any_name_mapping

Note: gss_display_name_ext() is not tested because we don't yet have a concrete implementation of it.

The usage of this test is:

<pre>
t_namingexts [--spnego] [principal] [keytab]
</pre>

where the optional --spnego argument uses the SPNEGO (as opposed to the krb5) mechanism; principal is the service principal to test with, and keytab is a path to the keytab containing the key for the service principal. (The client and service principal are identical in the test. To test with another client principal, use the S4U test.)

You likely want to test this against a Windows KDC, in order to validate PAC introspection; however, you can also test with the greet_client (and greet_server) plugins that are included in plugins/authdata/greet_{client,server}.

==Principal lockout testing==

There are now some automated lockout tests, but these procedures are still helpful for examining some edge cases.

Testing for lockout is identical for the LDAP and DB2 backends, although if you wish to test the replication functionality, you'll need to use a DB2 backend. No changes are required for configuring kprop/iprop; it's business as usual (the only difference being that lockout-related attributes will not be replicated, so as part of testing you should verify on each KDC that this is the case).

First, you need to create a password policy that specifies a lockout policy. Do this with kadmin. Here we create a policy where a maximum failure count of 3, a failure count reset interval of 180 seconds, and a lockout duration of 60 seconds.

<pre>
kadmin: addpol -maxfailure 3 -failurecountinterval 180 -lockoutduration 60 lockout_test
</pre>

Then, you need to associate a principal with the lockout policy. Note also that the pre-authentication required attribute must be set on the principal; principals without this attribute set are not subject to the lockout policy (as they are not required to prove knowledge of their long-term key to the KDC).

<pre>
kadmin: modprinc -policy lockout_test +requires_preauth lukeh
Principal "lukeh@MIT.DE.PADL.COM" modified.
</pre>

Now, perform a successful authentication with kinit. You should see the last successful authentication timestamp updated in the information returned by kadmin:

<pre>
kadmin: getprinc lukeh
...
Last successful authentication: Wed Oct 07 14:07:08 CEST 2009
</pre>

Perform an unsuccessful authentication (ie. kinit with an incorrect password) and you should see the failed authentication timestamp and count updated:

<pre>
kadmin: getprinc lukeh
...
Last failed authentication: Wed Oct 07 14:07:58 CEST 2009
Failed password attempts: 1
Account locked time: [never]
</pre>

Another two authentication failures (recall, the maximum failure count above is 3) and you should see that the principal is locked out:

<pre>
kadmin: getprinc lukeh
...
Last failed authentication: Wed Oct 07 14:08:37 CEST 2009
Failed password attempts: 3
Account locked time: Wed Oct 07 14:08:37 CEST 2009
</pre>

You can try to unlock the account explicitly with <i>modprinc -unlock</i>, or you can wait the lockout duration (here, 60 seconds) and you should be able to authenticate again.

==KDC worker processes==

There is a very basic automated test of parallel KDC worker processes, but it doesn't ensure that all worker processes can receive packets. To test that, make the following temporary code modifications:

* In plugins/kdb/db2/kdb_db2.c:krb5_db2_get_principal(), add this code near the beginning:

if (searchfor->length >= 1 &&
data_eq_string(searchfor->data[0], "slowuser"))
sleep(60);

* In lib/krb5/os/sendto_kdc.c, change MAX_PASS from 3 to 1, and in krb5_sendto_kdc() change all assignments of socktype2 to 0. This ensures that kinit will only send one request.

* In util/k5test.py, change the default arguments for the start_kdc() realm method like so:

def start_kdc(self, args=['-w', '3']):

Build the sources and run "make testrealm". You should be able to run "kinit slowuser" three times before the KDC becomes unresponsive to "kinit user".

==SAM-2 preauth client code==

The securid_sam2 preauth module isn't built by default and ordinarily only compiles successfully in the presence of the RSA ACE library. But it can be built with alternate flags to use a test method which can help exercise the client SAM-2 preauth code in send-encrypted-sad mode.

* First, build the securid_sam2 module with the test method instead of the securid method:

cd plugins/preauth/securid_sam2
make DEFINES='-DGRAIL_PREAUTH' ACELIB=
cd ../../..

* Start with a basic test realm:

make testrealm

* Edit datadir/krb5.master.conf and add the following to register the module. Make sure to specify the correct absolute path to the module shared object, which will depend on where your build directory is located.

[plugins]
kdcpreauth = {
module = securid_sam2:/path/to/plugins/preauth/securid_sam2/securid_sam2.so
}

* Do the following in kadmin.local:

addprinc -randkey user/GRAIL
modprinc +requires_hwauth user

* Restart the KDC (find the pid of the running krb5kdc process, kill it, and then run "krb5kdc").

* Run "kinit user". If you enter the correct password for user and correctly echo the challenge, you should get tickets. If you enter either one wrong, you should get an error.

* Remember to kill your krb5kdc process after exiting the test realm; the test realm code won't clean up the one you started by hand.

Developer resources

2012-06-27T15:52:07Z

BenKaduk: Don't link to the old texinfo documentation

This page lists resources that [[developers]] use on a regular basis. One goal of the page is to help those beginning to track the project know what they may be interested in looking at.
==Documentation==

* [http://web.mit.edu/kerberos/krb5-current/doc/krb_build/index.html Building Kerberos V5] describes how to build and install MIT Kerberos.
* The [http://web.mit.edu/kerberos/krb5-current/doc/ documentation site] contains administrator and user documentation, and some information for developers; this documentation can help in understanding the product.
* The [[Glossary]] is a quick index of acronyms and terms related to Kerberos, which you may come across while reading the code.
* [[Plugin development]] notes, pointers, tips, etc (needed!)

==Mailing lists==

Much of the discussion of new proposals, discussion of what direction to take the product and answering of questions takes place on mailing lists.

* [http://mailman.mit.edu/mailman/listinfo/krbdev krbdev@mit.edu] is the primary list for developers of [[MIT Kerberos]].
* [http://mailman.mit.edu/mailman/listinfo/kfwdev kfwdev@mit.edu] serves a similar purpose for [[Kerberos for Windows]].
* [http://mailman.mit.edu/mailman/listinfo/cvs-krb5 cvs-krb5@mit.edu] receives all krb5 commit messages and allows developers to track all changes made to MIT Kerberos.
* [http://mailman.mit.edu/mailman/listinfo/krb5-appl-commits krb5-appl-commits@mit.edu] receives all krb5-appl commit messages and allows developers to track all changes made to the MIT Kerberos applications.
* [http://mailman.mit.edu/mailman/listinfo/krb5-bugs krb5-bugs@mit.edu] is notified when a [[ticket]] is created or updated. This list helps track bugs and feature requests.
* krbcore@mit.edu is a private list for [[Krbcore]]; send mail to this list if you need to contact the core team.
* krbcore-security@mit.edu is the point of contact for security problems with MIT Kerberos.

==Source code==

* [[Getting source code]]

==Bug tracking==

* http://krbdev.mit.edu/rt/ is the interface to the bug tracking server.
* Log in with user name guest and password guest. (or use the guest login button)
* See {{trunkref|doc/procedures.txt}} for some information on bug states.

== Instant messaging ==

[[Developer chat]]

== Lore ==

You may find relevant accumulated lore in [[:Category:Lore]].

Getting source code

2012-06-27T14:44:40Z

BenKaduk: link to building and test suite where we talk about the git repo

The MIT Kerberos source code is in a Git repository.

== Official releases ==

Typically, end users and system administrators who want the latest stable MIT krb5 software should use the official releases:

* [http://web.mit.edu/kerberos/dist/ MIT Keberos download page]

== Git repository access ==

The current development source code is now in a Git repository. The latest development code is on the "master" branch, as is usual for Git. (It used to be "trunk" when the main repository was in Subversion.) Developers wishing to contribute changes to the krb5 software should track this repository. Advanced end users and system administrators may also wish to obtain the latest development sources from this repository.

The krb5 repository migrated to Git during the weekend of 2012-05-11. Use the following URLs for read-only access.

* git://github.com/krb5/krb5.git for the public read-only Git access
* https://github.com/krb5/krb5 for browsing

If you are interested in contributing changes to our repository, please consult our [[Coding style/Version control practices | version control practices]] page. You should of course test changes before submitting them for inclusion; see [[Building]] for the additional steps needed to build from a git checkout and [[Test suite]] for more information about the regression tests. Additional information about the [[Git migration]] is available, including help for situations where you have an existing GitHub fork of the krb5-anonsvn Git repository.

There is a wiki page with details about the [[Git conversion]] process available for people who are interested in the technical details.

== Repository browsing ==

* https://github.com/krb5/krb5 for browsing on GitHub

The following browsing options currently point to a frozen Subversion snapshot, but may convert to tracking the Git repository in the future.

* [http://src.mit.edu/fisheye/browse/krb5 FishEye] provides a feature-rich view of the repository
* [http://src.mit.edu/opengrok/ OpenGrok] provides an interface that allows you to search for the definition or usage of a specific function; it is somewhat better for cross references than FishEye.

== Subversion repository (historical) ==

The Subversion repository is now frozen, and remains accessible for specialized reference purposes (e.g., inspecting history that the Git conversion intentionally omitted).

=== Subversion repository access ===

* svn://anonsvn.mit.edu/krb5 provides read-only Subversion access to the repository.
* http://anonsvn.mit.edu/viewvc/krb5 provides a basic form of web access to the entire repository.


=== Git-svn mirror ===

The Git-svn mirror described below is a static snapshot, since the main repository has migrated to Git.

Additional information is available about [[using git-svn (historical)]].
* git://krbdev.mit.edu/git/krb5-anonsvn.git is a git-svn mirror of the anonsvn repository.
* https://github.com/krb5/krb5-anonsvn is a Github repository that mirrors the krb5-anonsvn repository. The web interface allows for repository browsing, and also displays URLs for git access using both native git protocol and HTTPS (for firewall traversal, etc.).

Committer resources

2012-06-26T20:59:49Z

BenKaduk: Undo revision 4702 by BenKaduk (Talk)

This is information for developers who are newly receiving commit access.

== Enrollment ==

* Athena account: MITKC staff will sponsor as appropriate. See http://web.mit.edu/accounts/www/getaccount.html for some overview information about Athena accounts.
* X.509 client certificate: Needed for RT access, among others. Information on how to obtain one is at http://web.mit.edu/ist/topics/certificates/index.html
* RT account
* Git access
* Daptiv access (for some contributors working on time-sensitive projects)
* Posting authorization to cvs-krb5 if you are going to commit stuff.

== Where stuff is at ==

* Git URL git.mit.edu:/git/krb5.git -- you may need to put "username@" in front of the hostname if your local username is not the same as your Athena account name. Kerberos-authenticated SSH is best, if you can get it to work.
* SSH to athena.dialup.mit.edu if you want easy access to AFS, a UNIX shell, etc.
* RT https://krbdev.mit.edu/rt/ (or https://krbdev.mit.edu:444/rt/ if your browser doesn't deal with "optional" SSL client certificate verification)

[[Category:Lore]]

Committer resources

2012-06-26T15:36:28Z

BenKaduk: Make the git repo URL one that actually works

This is information for developers who are newly receiving commit access.

== Enrollment ==

* Athena account: MITKC staff will sponsor as appropriate. See http://web.mit.edu/accounts/www/getaccount.html for some overview information about Athena accounts.
* X.509 client certificate: Needed for RT access, among others. Information on how to obtain one is at http://web.mit.edu/ist/topics/certificates/index.html
* RT account
* Git access
* Daptiv access (for some contributors working on time-sensitive projects)
* Posting authorization to cvs-krb5 if you are going to commit stuff.

== Where stuff is at ==

* Git URL git+ssh://git.mit.edu/git/krb5.git -- you may need to create a ssh configuration entry (~/.ssh/config) for Host git.mit.edu with a User directive if your local username is not the same as your Athena account name. Kerberos-authenticated SSH is best, if you can get it to work.
* SSH to athena.dialup.mit.edu if you want easy access to AFS, a UNIX shell, etc.
* RT https://krbdev.mit.edu/rt/ (or https://krbdev.mit.edu:444/rt/ if your browser doesn't deal with "optional" SSL client certificate verification)

[[Category:Lore]]