K5Wiki - User contributions [en]

Coding style

2009-09-22T22:51:08Z

Wfiveash: /* General information */

__NOTOC__
The C language '''Coding style''' described here is based on the BSD coding style (Kernel Normal Form - KNF), with some additional elements from the GNU coding standards and the SunOS coding standards.

* [[Coding style/Formatting|Formatting]]
* [[Coding style/Practices|Practices]]
* [[Coding style/Transition_strategies|Transition strategies]]

== External links ==

* [http://cvsweb.netbsd.org/bsdweb.cgi/~checkout~/src/share/misc/style?rev=HEAD NetBSD <code>/usr/share/misc/style</code>] [http://cvsweb.netbsd.org/bsdweb.cgi/src/share/misc/style (log)]
* [http://www.gnu.org/prep/standards/ GNU coding standards]
* [http://opensolaris.org/os/community/on/cstyle.ms.pdf C Style and Coding Standards for SunOS]

== General information ==

=== Aspects of C style in GNU coding std but not here ===

* redundant parens to force extra indent of operators of different precedences

* redundant parens to force general extra indent of expressions that are broken between lines

* use of ^L characters to break up source files into pages

* nitpicking about capitalization in comments of variable names when their values are meant

* commenting usages of static variables

* casts to void

* separation of word in names with underscores vs case change

* enum vs #define'd integer constants

* 14 char filename limits, MS-DOS filename limits

* portability

* system library function quirks

* internationalization

* mmap()

=== Aspects of C style in BSD KNF but not here ===

* sorting of header files

* sorting of struct members

* separating struct tag decl and struct typedef

* sorting of var decl

* lining up var names in decls

* newline after decls

* usage of __P

* usage of getopt

* not initializing vars in decls

* stdarg/varargs handling

=== Emacs cc-mode style ===

Putting the following code in your .emacs file will result in mostly
the right thing happening with respect to formatting style. Note that
you may want to turn on auto-newline feature of cc-mode, though that
seems to have some bugs with brace-elseif-brace handling at least in
the version of cc-mode that comes with emacs 20.3.

(defconst krb5-c-style
'("bsd"
(c-cleanup-list
brace-elseif-brace brace-else-brace defun-close-semi)
(c-comment-continuation-stars . "* ")
(c-electric-pound-behavior alignleft)
(c-hanging-braces-alist
(brace-list-open)
(class-open after)
(substatement-open after)
(block-close . c-snug-do-while)
(extern-lang-open after))
(c-hanging-colons-alist
(case-label after)
(label after))
(c-hanging-comment-starter-p)
(c-hanging-comment-ender-p)
(c-indent-comments-syntactically-p . t)
(c-label-minimum-indentation . 0)
(c-special-indent-hook)))
(defun krb5-c-hook ()
(c-add-style "krb5" krb5-c-style t))
(add-hook 'c-mode-common-hook 'krb5-c-hook)

You might also want to try (for Emacs 22 and later):

(add-hook 'before-save-hook 'copyright-update)

which will offer to update the year in the top-most copyright notice in a file when you save it, if it's not already current.

=== indent.pro settings ===

The following settings for the indent program should produce a
reasonable approximation to the C coding style described here, though
some manual cleanup may be necessary. Note that the gindent installed
in the gnu locker does not currently handle -nut or -psl correctly though.

<pre>
-bap
-br
-ce
-ci4
-cli0
-d0
-di8
-i4
-ip4
-l79
-nbc
-ncdb
-ndj
-nfc1
-lp
-npcs
-nut
-psl
-sc
-sob
</pre>
=== vim/gvim editor settings ===
These settings allow the vim/gvim editor to conform to the MITKC code style:

<pre>
set shiftwidth=4
set tabstop=8
set softtabstop=4
set expandtab
set nosmartindent
set cindent
set cinoptions=p0,t0,+4,(0,u4,U1,:0
set formatoptions=croq
set comments=sr:/*,mb:*,ex:*/,://
set textwidth=79
</pre>

Projects/Master Key Migration

2009-06-29T22:11:06Z

Wfiveash:

{{project-completed}}

==Desired changes==

This project will provide the ability to add a new master key (with an
enctype differing from the current master key) to the master key
principal and stash file and then migrate the encryption of existing
principals long term keys to use the new master key. In addition
deletion of master keys will be provided.

==Functional Requirements==

The KDC must be able to deal with multiple master keys and determine
which key to use when decrypting a principal's long term secret key.
The KDC must be able to access any of the master key (K/M) principal's
keys as long as it has access to a master key that is in use.

The administrator must be able re-encrypt principal keys using a
specified mkey and be able to specifying the set of principals is to be
re-encrypted. The command doing this must be able to determine if a
principal's keys are protected by the current master key or not. This
implies that some set of principals may be protected with a non-current
master key.

Slave KDC's must be able to access all master keys currently protecting
principal entries and therefore have access to the principal's secret
keys regardless of which master key is used to encrypt the key.

The administrator will be able to:

* Add a new master key to master key principal and optionally to the masterkey keytab stash.

* Enable a new master key (make it the current master key used to protect newly created principals or principal rekeys).

* List all master keys associated with the master key principal.

* Delete a particular master key from the master key principal and optionally from the masterkey keytab stash.

* Purge unused master keys (keys not used to protect any principal).

==Design of implementation==

Fundamentally the current implementation must be changed to support
multiple master keys. And possession of any master key stored with the
K/M principal allows access to all master keys. In addition, a
principal's secret key may be encrypted by any of the master keys in use
and the KDC must be able to decrypt that principal's key.

In order to accommodate this, these changes will be made:

* A new TL-data type, KRB5_TL_MKVNO, would apply to all principals except the K/M and would store the version number of the master key used to encrypt the keys of that principal. The db2 back end would store it as opaque TL-data, the LDAP back end has a slot for it.
* A new TL-data type, KRB5_TL_ACTKVNO, would apply to all principals and will be a set of {actkvno, start_time} tuples where actkvno is the "active" KVNO and start_time indicates when actkvno is valid for use.
** When set for the K/M principal this indicates the master key to be used when encrypting principal's long term keys. If this TL-data type is not found in the K/M record then the default value for this will be 1 which is the default MKVNO.
** When set for service principals this indicates the key to be used when the KDC issues service tickets.
** Trailing stuff is ignored for now, making the structure extensible.
* The krb5_key_data array in the krb5_db_entry for the K/M principal will hold all master keys in use. All the keys in this array will be encrypted using the most recently created master key.
* A new TL-data type, KRB5_TL_MKEY_AUX, would apply only to the K/M principal. This new TL data would contain:
** A set of copies of the latest master key, each encrypted by one of the other supported mkeys, in {old-mkvno, keydata} tuples. Thus the "master key" used in DAL (DB abstraction layer) need only be any one of these keys.
** Trailing stuff is ignored for now, making the structure extensible.
* kdc_realm_t will be modified to hold all master keys (including KVNO and enctype) associated with a realm. It will also hold the current mkey KVNO that should be used when encrypting a principal's keys. To facilitate this, a new struct will be defined:

typedef struct _krb5_keylist_node {
krb5_keyblock *keyblock;
krb5_kvno kvno;
struct _krb5_keylist_node *next;
} krb5_keyblock_node;

This will be used to create a list of mkeys. kdc_realm_t will also have
a current_realm_mkey which will point to the krb5_keyblock_node that
contains the current mkey (used when encrypting a principal's keys, does
not apply the K/M mkeys).

The initialization of the list of mkeys will occur in init_realm().

Any code needing to decrypt principal keys will need to determine which
mkey to use. A function will be created to return the mkey to use for
decrypting a principal's keys given the principal's krb5_db_entry and
realm_mkeys list as input args. If the principals krb5_db_entry does
not contain KRB5_TL_MKVNO TL-data the function will default to choosing
the mkey with KVNO 1. If the princ krb5_db_entry does have
KRB5_TL_MKVNO data and no matching mkey is found the function will get
the K/M princ KDB entry, update the list of mkeys if new mkeys are found
and return a matching mkey if found. An error will be returned if a
matching mkey is not found.

This function would be called prior to calling
krb5_dbekd_decrypt_key_data() to determine which mkey to pass in.

Similarly, any code calling krb5_dbekd_encrypt_key_data() will be
modified to pass in the current_realm_mkey (mentioned above).

kdb5_util will be modified to support these new commands:

; add_mkey [-s] : Add a new master key to K/M. The optional -s will add the mkey to the stash file.

; use_mkey <KVNO> [startdate] : Set the current mkey KVNO. This controls which master key is used when encrypting principal keys. The kadmind and krb5kdc should be restarted after this command successfully completes.

; list_mkeys : Shows all master keys from most recent to earliest in K/M principal. The output will show the KVNO, enctype and salt for each mkey similar to kadmin getprinc output. A * following an mkey denotes the current mkey.

; purge_mkeys [-f] : Delete mkeys from K/M princ that are not used to protect any principals. With -f, does not prompt user. The prompt will be "Delete version 3 master key for the FOO.COM realm? [y/n] ".

; sync_stash [-f] : Sync up the set of keys in the keytab stash with those in the K/M princ entry in the KDB. Keys in keytab stash not found in K/M will be removed. With -f, does not prompt user. (NOTE: During implementation, this was changed to just use the preexisting "stash" command when a stash file is already present.)

; update_princ_encryption [-f] [expression] : Use current mkey to encrypt principals (other than K/M) secret keys if not already encrypted by that mkey. Should support either doing all princs if no argument given or a subset specified by expression (supports shell-style globbing, similar to kadmin). Both the principal's secret keys and key history will first be decrypted with the original encrypting mkey then encrypted with the current mkey. If the current mkey kvno is that of the mkey that originally encrypted the principal's keys the code will stop processing that principal and go on to the next. With -f, does not prompt user.

The kdb5_util dump -mkey_convert will be modified to update the
KRB5_TL_MKVNO of all principals except the K/M principal with the KVNO
of the mkey used for the conversion. The K/M KRB5_TL_MKEY_AUX TL data
will be updated to include the new mkey used for the conversion.

==Tasks/milestones==

* project start. Aug 29, 2008
* project review. ~2 week
* Implementation. ~6 weeks
* test. ~4 week
* code review. ~2 week
* documentation. ~3 day

==Desired integration and release goals==

==Testing plan==

Unit testing of all new and modified commands will be done to verify
they work as specified. This will be done for both the db2 and LDAP KDB
plugins. Unit tests will include testing that the various of setting a
new key (kpasswd, kadmin commands like cpw or ktadd, as well as the
new/modified commands) when applied to the master key principal will
either be rejected without changing the database or retain all the old
keys, even if that list is larger than the normal key history size in
order to make sure the normal key history mechanisms won't accidentally
throw away any still-used master keys.

The kadmind and krb5kdc daemons will be tested to verify they work
properly when accessing a KDB some set of principals is protected by one
mkey and the other set is protected by another set. Slave KDCs will
also be tested after the KDB is propagated both with kprop and kiprop.

Bounds testing will verify the krb utils and daemons work properly when
the MKVNO wraps back to 1 (0 is not a valid value).

The existing MIT Kerberos test suites will be run to make sure there are
no regressions introduced by this project.

==Review==

This section documents the review of the project according to [[Project policy]].
It is divided into multiple sections. First, approvals should be listed. To list an approval type
:<nowiki>#~~~~</nowiki>
on its own line.
The next section is for discussion. Use standard [http://en.wikipedia.org/wiki/Wikipedia:Tutorial_%28Talk_pages%29 talk page conventions]. In particular, sign comments with
:<nowiki>--~~~~</nowiki>
and indent replies.

Members of Krbcore raising Blocking objections should preface their comment with <nowiki>{{project-block}}</nowiki>. The member who raised the objection should remove this markup when their objection is handled.

===Approvals===

#[[User:TomYu|TomYu]]

===Discussion===

== Current status ==

Talk:Reporting bugs

2009-04-23T19:14:31Z

Wfiveash: New page: Are security vulnerability bug also supposed to be reported this way? If not, this page should explain how to report those sorts of bugs.

Are security vulnerability bug also supposed to be reported this way? If not, this page should explain how to report those sorts of bugs.

Projects/Master Key Migration

2008-10-21T18:50:32Z

Wfiveash: /* Testing plan */

{{project-approved}}

==Desired changes==

This project will provide the ability to add a new master key (with an
enctype differing from the current master key) to the master key
principal and stash file and then migrate the encryption of existing
principals long term keys to use the new master key. In addition
deletion of master keys will be provided.

==Functional Requirements==

The KDC must be able to deal with multiple master keys and determine
which key to use when decrypting a principal's long term secret key.
The KDC must be able to access any of the master key (K/M) principal's
keys as long as it has access to a master key that is in use.

The administrator must be able re-encrypt principal keys using a
specified mkey and be able to specifying the set of principals is to be
re-encrypted. The command doing this must be able to determine if a
principal's keys are protected by the current master key or not. This
implies that some set of principals may be protected with a non-current
master key.

Slave KDC's must be able to access all master keys currently protecting
principal entries and therefore have access to the principal's secret
keys regardless of which master key is used to encrypt the key.

The administrator will be able to:

* Add a new master key to master key principal and optionally to the masterkey keytab stash.

* Enable a new master key (make it the current master key used to protect newly created principals or principal rekeys).

* List all master keys associated with the master key principal.

* Delete a particular master key from the master key principal and optionally from the masterkey keytab stash.

* Purge unused master keys (keys not used to protect any principal).

==Design of implementation==

Fundamentally the current implementation must be changed to support
multiple master keys. And possession of any master key stored with the
K/M principal allows access to all master keys. In addition, a
principal's secret key may be encrypted by any of the master keys in use
and the KDC must be able to decrypt that principal's key.

In order to accommodate this, these changes will be made:

* A new TL-data type, KRB5_TL_MKVNO, would apply to all principals except the K/M and would store the version number of the master key used to encrypt the keys of that principal. The db2 back end would store it as opaque TL-data, the LDAP back end has a slot for it.
* A new TL-data type, KRB5_TL_ACTKVNO, would apply to all principals and will be a set of {actkvno, start_time} tuples where actkvno is the "active" KVNO and start_time indicates when actkvno is valid for use.
** When set for the K/M principal this indicates the master key to be used when encrypting principal's long term keys. If this TL-data type is not found in the K/M record then the default value for this will be 1 which is the default MKVNO.
** When set for service principals this indicates the key to be used when the KDC issues service tickets.
** Trailing stuff is ignored for now, making the structure extensible.
* The krb5_key_data array in the krb5_db_entry for the K/M principal will hold all master keys in use. All the keys in this array will be encrypted using the most recently created master key.
* A new TL-data type, KRB5_TL_MKEY_AUX, would apply only to the K/M principal. This new TL data would contain:
** A set of copies of the latest master key, each encrypted by one of the other supported mkeys, in {old-mkvno, keydata} tuples. Thus the "master key" used in DAL (DB abstraction layer) need only be any one of these keys.
** Trailing stuff is ignored for now, making the structure extensible.
* kdc_realm_t will be modified to hold all master keys (including KVNO and enctype) associated with a realm. It will also hold the current mkey KVNO that should be used when encrypting a principal's keys. To facilitate this, a new struct will be defined:

typedef struct _krb5_keylist_node {
krb5_keyblock *keyblock;
krb5_kvno kvno;
struct _krb5_keylist_node *next;
} krb5_keyblock_node;

This will be used to create a list of mkeys. kdc_realm_t will also have
a current_realm_mkey which will point to the krb5_keyblock_node that
contains the current mkey (used when encrypting a principal's keys, does
not apply the K/M mkeys).

The initialization of the list of mkeys will occur in init_realm().

Any code needing to decrypt principal keys will need to determine which
mkey to use. A function will be created to return the mkey to use for
decrypting a principal's keys given the principal's krb5_db_entry and
realm_mkeys list as input args. If the principals krb5_db_entry does
not contain KRB5_TL_MKVNO TL-data the function will default to choosing
the mkey with KVNO 1. If the princ krb5_db_entry does have
KRB5_TL_MKVNO data and no matching mkey is found the function will get
the K/M princ KDB entry, update the list of mkeys if new mkeys are found
and return a matching mkey if found. An error will be returned if a
matching mkey is not found.

This function would be called prior to calling
krb5_dbekd_decrypt_key_data() to determine which mkey to pass in.

Similarly, any code calling krb5_dbekd_encrypt_key_data() will be
modified to pass in the current_realm_mkey (mentioned above).

kdb5_util will be modified to support these new commands:

; add_mkey [-s] : Add a new master key to K/M. The optional -s will add the mkey to the stash file.

; use_mkey <KVNO> [startdate] : Set the current mkey KVNO. This controls which master key is used when encrypting principal keys. The kadmind and krb5kdc should be restarted after this command successfully completes.

; list_mkeys : Shows all masterkeys from most recent to earliest in K/M principal. The output will show the KVNO, enctype and salt for each mkey similar to kadmin getprinc output. A * following an mkey denotes the current mkey.

; purge_mkeys [-f] : Delete mkeys from K/M princ that are not used to protect any principals. With -f, does not prompt user. The prompt will be "Delete version 3 master key for the FOO.COM realm? [y/n] ".

; sync_stash [-f] : Sync up the set of keys in the keytab stash with those in the K/M princ entry in the KDB. Keys in keytab stash not found in K/M will be removed. With -f, does not prompt user.

; update_princ_encryption [-f] [expression] : Use current mkey to encrypt principals (other than K/M) secret keys if not already encrypted by that mkey. Should support either doing all princs if no argument given or a subset specified by expression (supports shell-style globbing, similar to kadmin). Both the principal's secret keys and key history will first be decrypted with the original encrypting mkey then encrypted with the current mkey. If the current mkey kvno is that of the mkey that originaly encrypted the principal's keys the code will stop processing that principal and go on to the next. With -f, does not prompt user.

The kdb5_util dump -mkey_convert will be modified to update the
KRB5_TL_MKVNO of all principals except the K/M principal with the KVNO
of the mkey used for the conversion. The K/M KRB5_TL_MKEY_AUX TL data
will be updated to include the new mkey used for the conversion.

==Tasks/milestones==

* project start. Aug 29, 2008
* project review. ~2 week
* Implementation. ~6 weeks
* test. ~4 week
* code review. ~2 week
* documentation. ~3 day

==Desired integration and release goals==

==Testing plan==

Unit testing of all new and modified commands will be done to verify
they work as specified. This will be done for both the db2 and LDAP KDB
plugins. Unit tests will include testing that the various of setting a
new key (kpasswd, kadmin commands like cpw or ktadd, as well as the
new/modified commands) when applied to the master key principal will
either be rejected without changing the database or retain all the old
keys, even if that list is larger than the normal key history size in
order to make sure the normal key history mechanisms won't accidentally
throw away any still-used master keys.

The kadmind and krb5kdc daemons will be tested to verify they work
properly when accessing a KDB some set of principals is protected by one
mkey and the other set is protected by another set. Slave KDCs will
also be tested after the KDB is propagated both with kprop and kiprop.

Bounds testing will verify the krb utils and daemons work properly when
the MKVNO wraps back to 1 (0 is not a valid value).

The existing MIT Kerberos test suites will be run to make sure there are
no regressions introduced by this project.

==Review==

This section documents the review of the project according to [[Project policy]].
It is divided into multiple sections. First, approvals should be listed. To list an approval type
:<nowiki>#~~~~</nowiki>
on its own line.
The next section is for discussion. Use standard [http://en.wikipedia.org/wiki/Wikipedia:Tutorial_%28Talk_pages%29 talk page conventions]. In particular, sign comments with
:<nowiki>--~~~~</nowiki>
and indent replies.

Members of Krbcore raising Blocking objections should preface their comment with <nowiki>{{project-block}}</nowiki>. The member who raised the objection should remove this markup when their objection is handled.

===Approvals===

#[[User:TomYu|TomYu]]

===Discussion===

== Current status ==

Projects/Master Key Migration

2008-10-01T20:32:59Z

Wfiveash: /* Tasks/milestones */

{{project-review|2008-09-16}}

=Desired changes=

This project will provide the ability to add a new master key (with an
enctype differing from the current master key) to the master key
principal and stash file and then migrate the encryption of existing
principals long term keys to use the new master key. In addition
deletion of master keys will be provided.

=Functional Requirements=

The KDC must be able to deal with multiple master keys and determine
which key to use when decrypting a principal's long term secret key.
The KDC must be able to access any of the master key (K/M) principal's
keys as long as it has access to a master key that is in use.

The administrator must be able re-encrypt principal keys using a
specified mkey and be able to specifying the set of principals is to be
re-encrypted. The command doing this must be able to determine if a
principal's keys are protected by the current master key or not. This
implies that some set of principals may be protected with a non-current
master key.

Slave KDC's must be able to access all master keys currently protecting
principal entries and therefore have access to the principal's secret
keys regardless of which master key is used to encrypt the key.

The administrator will be able to:

* Add a new master key to master key principal and optionally to the masterkey keytab stash.

* Enable a new master key (make it the current master key used to protect newly created principals or principal rekeys).

* List all master keys associated with the master key principal.

* Delete a particular master key from the master key principal and optionally from the masterkey keytab stash.

* Purge unused master keys (keys not used to protect any principal).

=Design of implementation=

Fundamentally the current implementation must be changed to support
multiple master keys. And possession of any master key stored with the
K/M principal allows access to all master keys. In addition, a
principal's secret key may be encrypted by any of the master keys in use
and the KDC must be able to decrypt that principal's key.

In order to accommodate this, these changes will be made:

* A new TL-data type, KRB5_TL_MKVNO, would apply to all principals except the K/M and would store the version number of the master key used to encrypt the keys of that principal. The db2 back end would store it as opaque TL-data, the LDAP back end has a slot for it.
* A new TL-data type, KRB5_TL_ACTKVNO, would apply to all principals and will be a set of {actkvno, start_time} tuples where actkvno is the "active" KVNO and start_time indicates when actkvno is valid for use.
** When set for the K/M principal this indicates the master key to be used when encrypting principal's long term keys. If this TL-data type is not found in the K/M record then the default value for this will be 1 which is the default MKVNO.
** When set for service principals this indicates the key to be used when the KDC issues service tickets.
** Trailing stuff is ignored for now, making the structure extensible.
* The krb5_key_data array in the krb5_db_entry for the K/M principal will hold all master keys in use. All the keys in this array will be encrypted using the most recently created master key.
* A new TL-data type, KRB5_TL_MKEY_AUX, would apply only to the K/M principal. This new TL data would contain:
** A set of copies of the latest master key, each encrypted by one of the other supported mkeys, in {old-mkvno, keydata} tuples. Thus the "master key" used in DAL (DB abstraction layer) need only be any one of these keys.
** Trailing stuff is ignored for now, making the structure extensible.
* kdc_realm_t will be modified to hold all master keys (including KVNO and enctype) associated with a realm. It will also hold the current mkey KVNO that should be used when encrypting a principal's keys. To facilitate this, a new struct will be defined:

typedef struct _krb5_keylist_node {
krb5_keyblock *keyblock;
krb5_kvno kvno;
struct _krb5_keylist_node *next;
} krb5_keyblock_node;

This will be used to create a list of mkeys. kdc_realm_t will also have
a current_realm_mkey which will point to the krb5_keyblock_node that
contains the current mkey (used when encrypting a principal's keys, does
not apply the K/M mkeys).

The initialization of the list of mkeys will occur in init_realm().

Any code needing to decrypt principal keys will need to determine which
mkey to use. A function will be created to return the mkey to use for
decrypting a principal's keys given the principal's krb5_db_entry and
realm_mkeys list as input args. If the principals krb5_db_entry does
not contain KRB5_TL_MKVNO TL-data the function will default to choosing
the mkey with KVNO 1. If the princ krb5_db_entry does have
KRB5_TL_MKVNO data and no matching mkey is found the function will get
the K/M princ KDB entry, update the list of mkeys if new mkeys are found
and return a matching mkey if found. An error will be returned if a
matching mkey is not found.

This function would be called prior to calling
krb5_dbekd_decrypt_key_data() to determine which mkey to pass in.

Similarly, any code calling krb5_dbekd_encrypt_key_data() will be
modified to pass in the current_realm_mkey (mentioned above).

kdb5_util will be modified to support these new commands:

; add_mkey [-s] : Add a new master key to K/M. The optional -s will add the mkey to the stash file.

; use_mkey <KVNO> [startdate] : Set the current mkey KVNO. This controls which master key is used when encrypting principal keys. The kadmind and krb5kdc should be restarted after this command successfully completes.

; list_mkeys : Shows all masterkeys from most recent to earliest in K/M principal. The output will show the KVNO, enctype and salt for each mkey similar to kadmin getprinc output. A * following an mkey denotes the current mkey.

; purge_mkeys [-f] : Delete mkeys from K/M princ that are not used to protect any principals. With -f, does not prompt user. The prompt will be "Delete version 3 master key for the FOO.COM realm? [y/n] ".

; sync_stash [-f] : Sync up the set of keys in the keytab stash with those in the K/M princ entry in the KDB. Keys in keytab stash not found in K/M will be removed. With -f, does not prompt user.

; update_princ_encryption [-f] [expression] : Use current mkey to encrypt principals (other than K/M) secret keys if not already encrypted by that mkey. Should support either doing all princs if no argument given or a subset specified by expression (supports shell-style globbing, similar to kadmin). Both the principal's secret keys and key history will first be decrypted with the original encrypting mkey then encrypted with the current mkey. If the current mkey kvno is that of the mkey that originaly encrypted the principal's keys the code will stop processing that principal and go on to the next. With -f, does not prompt user.

The kdb5_util dump -mkey_convert will be modified to update the
KRB5_TL_MKVNO of all principals except the K/M principal with the KVNO
of the mkey used for the conversion. The K/M KRB5_TL_MKEY_AUX TL data
will be updated to include the new mkey used for the conversion.

=Tasks/milestones=

* project start. Aug 29, 2008
* project review. ~2 week
* Implementation. ~6 weeks
* test. ~4 week
* code review. ~2 week
* documentation. ~3 day

=Desired integration and release goals=

=Testing plan=

Unit testing of all new and modified commands will be done to verify
they work as specified. This will be done for both the db2 and LDAP KDB
plugins.

The kadmind and krb5kdc daemons will be tested to verify they work
properly when accessing a KDB some set of principals is protected by one
mkey and the other set is protected by another set. Slave KDCs will
also be tested after the KDB is propagated both with kprop and kiprop.

Bounds testing will verify the krb utils and daemons work properly when
the MKVNO wraps back to 0.

The existing MIT Kerberos test suites will be run to make sure there are
no regressions introduced by this project.

==Review==

This section documents the review of the project according to [[Project policy]].
It is divided into multiple sections. First, approvals should be listed. To list an approval type
:<nowiki>#~~~~</nowiki>
on its own line.
The next section is for discussion. Use standard [http://en.wikipedia.org/wiki/Wikipedia:Tutorial_%28Talk_pages%29 talk page conventions]. In particular, sign comments with
:<nowiki>--~~~~</nowiki>
and indent replies.

Members of Krbcore raising Blocking objections should preface their comment with <nowiki>{{project-block}}</nowiki>. The member who raised the objection should remove this markup when their objection is handled.

===Approvals===

===Discussion===

Projects/Master Key Migration

2008-09-30T23:29:59Z

Wfiveash: /* Design of implementation */

{{project-review|2008-09-16}}

=Desired changes=

This project will provide the ability to add a new master key (with an
enctype differing from the current master key) to the master key
principal and stash file and then migrate the encryption of existing
principals long term keys to use the new master key. In addition
deletion of master keys will be provided.

=Functional Requirements=

The KDC must be able to deal with multiple master keys and determine
which key to use when decrypting a principal's long term secret key.
The KDC must be able to access any of the master key (K/M) principal's
keys as long as it has access to a master key that is in use.

The administrator must be able re-encrypt principal keys using a
specified mkey and be able to specifying the set of principals is to be
re-encrypted. The command doing this must be able to determine if a
principal's keys are protected by the current master key or not. This
implies that some set of principals may be protected with a non-current
master key.

Slave KDC's must be able to access all master keys currently protecting
principal entries and therefore have access to the principal's secret
keys regardless of which master key is used to encrypt the key.

The administrator will be able to:

* Add a new master key to master key principal and optionally to the masterkey keytab stash.

* Enable a new master key (make it the current master key used to protect newly created principals or principal rekeys).

* List all master keys associated with the master key principal.

* Delete a particular master key from the master key principal and optionally from the masterkey keytab stash.

* Purge unused master keys (keys not used to protect any principal).

=Design of implementation=

Fundamentally the current implementation must be changed to support
multiple master keys. And possession of any master key stored with the
K/M principal allows access to all master keys. In addition, a
principal's secret key may be encrypted by any of the master keys in use
and the KDC must be able to decrypt that principal's key.

In order to accommodate this, these changes will be made:

* A new TL-data type, KRB5_TL_MKVNO, would apply to all principals except the K/M and would store the version number of the master key used to encrypt the keys of that principal. The db2 back end would store it as opaque TL-data, the LDAP back end has a slot for it.
* A new TL-data type, KRB5_TL_ACTKVNO, would apply to all principals and will be a set of {actkvno, start_time} tuples where actkvno is the "active" KVNO and start_time indicates when actkvno is valid for use.
** When set for the K/M principal this indicates the master key to be used when encrypting principal's long term keys. If this TL-data type is not found in the K/M record then the default value for this will be 1 which is the default MKVNO.
** When set for service principals this indicates the key to be used when the KDC issues service tickets.
** Trailing stuff is ignored for now, making the structure extensible.
* The krb5_key_data array in the krb5_db_entry for the K/M principal will hold all master keys in use. All the keys in this array will be encrypted using the most recently created master key.
* A new TL-data type, KRB5_TL_MKEY_AUX, would apply only to the K/M principal. This new TL data would contain:
** A set of copies of the latest master key, each encrypted by one of the other supported mkeys, in {old-mkvno, keydata} tuples. Thus the "master key" used in DAL (DB abstraction layer) need only be any one of these keys.
** Trailing stuff is ignored for now, making the structure extensible.
* kdc_realm_t will be modified to hold all master keys (including KVNO and enctype) associated with a realm. It will also hold the current mkey KVNO that should be used when encrypting a principal's keys. To facilitate this, a new struct will be defined:

typedef struct _krb5_keylist_node {
krb5_keyblock *keyblock;
krb5_kvno kvno;
struct _krb5_keylist_node *next;
} krb5_keyblock_node;

This will be used to create a list of mkeys. kdc_realm_t will also have
a current_realm_mkey which will point to the krb5_keyblock_node that
contains the current mkey (used when encrypting a principal's keys, does
not apply the K/M mkeys).

The initialization of the list of mkeys will occur in init_realm().

Any code needing to decrypt principal keys will need to determine which
mkey to use. A function will be created to return the mkey to use for
decrypting a principal's keys given the principal's krb5_db_entry and
realm_mkeys list as input args. If the principals krb5_db_entry does
not contain KRB5_TL_MKVNO TL-data the function will default to choosing
the mkey with KVNO 1. If the princ krb5_db_entry does have
KRB5_TL_MKVNO data and no matching mkey is found the function will get
the K/M princ KDB entry, update the list of mkeys if new mkeys are found
and return a matching mkey if found. An error will be returned if a
matching mkey is not found.

This function would be called prior to calling
krb5_dbekd_decrypt_key_data() to determine which mkey to pass in.

Similarly, any code calling krb5_dbekd_encrypt_key_data() will be
modified to pass in the current_realm_mkey (mentioned above).

kdb5_util will be modified to support these new commands:

; add_mkey [-s] : Add a new master key to K/M. The optional -s will add the mkey to the stash file.

; use_mkey <KVNO> [startdate] : Set the current mkey KVNO. This controls which master key is used when encrypting principal keys. The kadmind and krb5kdc should be restarted after this command successfully completes.

; list_mkeys : Shows all masterkeys from most recent to earliest in K/M principal. The output will show the KVNO, enctype and salt for each mkey similar to kadmin getprinc output. A * following an mkey denotes the current mkey.

; purge_mkeys [-f] : Delete mkeys from K/M princ that are not used to protect any principals. With -f, does not prompt user. The prompt will be "Delete version 3 master key for the FOO.COM realm? [y/n] ".

; sync_stash [-f] : Sync up the set of keys in the keytab stash with those in the K/M princ entry in the KDB. Keys in keytab stash not found in K/M will be removed. With -f, does not prompt user.

; update_princ_encryption [-f] [expression] : Use current mkey to encrypt principals (other than K/M) secret keys if not already encrypted by that mkey. Should support either doing all princs if no argument given or a subset specified by expression (supports shell-style globbing, similar to kadmin). Both the principal's secret keys and key history will first be decrypted with the original encrypting mkey then encrypted with the current mkey. If the current mkey kvno is that of the mkey that originaly encrypted the principal's keys the code will stop processing that principal and go on to the next. With -f, does not prompt user.

The kdb5_util dump -mkey_convert will be modified to update the
KRB5_TL_MKVNO of all principals except the K/M principal with the KVNO
of the mkey used for the conversion. The K/M KRB5_TL_MKEY_AUX TL data
will be updated to include the new mkey used for the conversion.

=Tasks/milestones=

* project start. Aug 29, 2008
* project review. ~2 week
* Implementation. ~8 week
* test. ~4 week
* code review. ~2 week
* documentation. ~3 day

=Desired integration and release goals=

=Testing plan=

Unit testing of all new and modified commands will be done to verify
they work as specified. This will be done for both the db2 and LDAP KDB
plugins.

The kadmind and krb5kdc daemons will be tested to verify they work
properly when accessing a KDB some set of principals is protected by one
mkey and the other set is protected by another set. Slave KDCs will
also be tested after the KDB is propagated both with kprop and kiprop.

Bounds testing will verify the krb utils and daemons work properly when
the MKVNO wraps back to 0.

The existing MIT Kerberos test suites will be run to make sure there are
no regressions introduced by this project.

==Review==

This section documents the review of the project according to [[Project policy]].
It is divided into multiple sections. First, approvals should be listed. To list an approval type
:<nowiki>#~~~~</nowiki>
on its own line.
The next section is for discussion. Use standard [http://en.wikipedia.org/wiki/Wikipedia:Tutorial_%28Talk_pages%29 talk page conventions]. In particular, sign comments with
:<nowiki>--~~~~</nowiki>
and indent replies.

Members of Krbcore raising Blocking objections should preface their comment with <nowiki>{{project-block}}</nowiki>. The member who raised the objection should remove this markup when their objection is handled.

===Approvals===

===Discussion===

Projects/Master Key Migration

2008-09-12T00:21:16Z

Wfiveash: /* Design of implementation */

{{project-review|2008-09-16}}

=Desired changes=

This project will provide the ability to add a new master key (with an
enctype differing from the current master key) to the master key
principal and stash file and then migrate the encryption of existing
principals long term keys to use the new master key. In addition
deletion of master keys will be provided.

=Functional Requirements=

The KDC must be able to deal with multiple master keys and determine
which key to use when decrypting a principal's long term secret key.
The KDC must be able to access any of the master key (K/M) principal's
keys as long as it has access to a master key that is in use.

The administrator must be able re-encrypt principal keys using a
specified mkey and be able to specifying the set of principals is to be
re-encrypted. The command doing this must be able to determine if a
principal's keys are protected by the current master key or not. This
implies that some set of principals may be protected with a non-current
master key.

Slave KDC's must be able to access all master keys currently protecting
principal entries and therefore have access to the principal's secret
keys regardless of which master key is used to encrypt the key.

The administrator will be able to:

* Add a new master key to master key principal and optionally to the masterkey keytab stash.

* Enable a new master key (make it the current master key used to protect newly created principals or principal rekeys).

* List all master keys associated with the master key principal.

* Delete a particular master key from the master key principal and optionally from the masterkey keytab stash.

* Purge unused master keys (keys not used to protect any principal).

=Design of implementation=

Fundamentally the current implementation must be changed to support
multiple master keys. And possession of any master key stored with the
K/M principal allows access to all master keys. In addition, a
principal's secret key may be encrypted by any of the master keys in use
and the KDC must be able to decrypt that principal's key.

In order to accommodate this, these changes will be made:

* A new TL-data type, KRB5_TL_MKVNO, would apply to all principals except the K/M, and would store the version number of the master key used to encrypt the keys of that principal. The db2 back end would store it as opaque TL-data, the LDAP back end has a slot for it.
* The krb5_key_data array in the krb5_db_entry for the K/M principal will hold all master keys in use. All the keys in this array will be encrypted using the most recently created master key.
* A new TL-data type, KRB5_TL_MKEY_AUX, would apply only to the K/M principal. This new TL data would contain:
** The current master key version number that should be used when changing database entries. This may not be the latest key and is set by the administrator. If this TL-data type is not found in the K/M record then the default value for this will be 1 which is the default MKVNO.
** A set of copies of the latest master key, each encrypted by one of the other supported mkeys, in {old-mkvno, keydata} tuples. Thus the "master key" used in DAL (DB abstraction layer) need only be any one of these keys.
** Trailing stuff is ignored for now, making the structure extensible.
* kdc_realm_t will be modified to hold all master keys (including KVNO and enctype) associated with a realm. It will also hold the current mkey KVNO that should be used when encrypting a principal's keys. To facilitate this, a new struct will be defined:

typedef struct _krb5_keylist_node {
krb5_keyblock *keyblock;
krb5_kvno kvno;
struct _krb5_keylist_node *next;
} krb5_keyblock_node;

This will be used to create a list of mkeys. kdc_realm_t will also have
a current_realm_mkey which will point to the krb5_keyblock_node that
contains the current mkey (used when encrypting a principal's keys, does
not apply the K/M mkeys).

The initialization of the list of mkeys will occur in init_realm().

Any code needing to decrypt principal keys will need to determine which
mkey to use. A function will be created to return the mkey to use for
decrypting a principal's keys given the principal's krb5_db_entry and
realm_mkeys list as input args. If the principals krb5_db_entry does
not contain KRB5_TL_MKVNO TL-data the function will default to choosing
the mkey with KVNO 1. If the princ krb5_db_entry does have
KRB5_TL_MKVNO data and no matching mkey is found the function will get
the K/M princ KDB entry, update the list of mkeys if new mkeys are found
and return a matching mkey if found. An error will be returned if a
matching mkey is not found.

This function would be called prior to calling
krb5_dbekd_decrypt_key_data() to determine which mkey to pass in.

Similarly, any code calling krb5_dbekd_encrypt_key_data() will be
modified to pass in the current_realm_mkey (mentioned above).

kdb5_util will be modified to support these new commands:

; add_mkey [-s] : Add a new mkey to K/M. The optional -s will add the mkey to the stash file.

; use_mkey <KVNO> : Set the current mkey KVNO. This controls which mkey is used when encrypting principal keys. The kadmind and krb5kdc should be restarted after this command successfully completes.

; list_mkeys : Shows all masterkeys from most recent to earliest in K/M principal. The output will show the KVNO, enctype and salt for each mkey similar to kadmin getprinc output. A * following an mkey denotes the current mkey.

; purge_mkeys [-f] : Delete mkeys from K/M princ that are not used to protect any principals. With -f, does not prompt user. The prompt will be "Delete version 3 master key for the FOO.COM realm? [y/n] ".

; sync_stash [-f] : Sync up the set of keys in the keytab stash with those in the K/M princ entry in the KDB. Keys in keytab stash not found in K/M will be removed. With -f, does not prompt user.

; update_princ_encryption [-f] [expression] : Use current mkey to encrypt principals (other than K/M) secret keys if not already encrypted by that mkey. Should support either doing all princs if no argument given or a subset specified by expression (supports shell-style globbing, similar to kadmin). Both the principal's secret keys and key history will first be decrypted with the original encrypting mkey then encrypted with the current mkey. If the current mkey kvno is that of the mkey that originaly encrypted the principal's keys the code will stop processing that principal and go on to the next. With -f, does not prompt user.

The kdb5_util dump -mkey_convert will be modified to update the
KRB5_TL_MKVNO of all principals except the K/M principal with the KVNO
of the mkey used for the conversion. The K/M KRB5_TL_MKEY_AUX TL data
will be updated to include the new mkey used for the conversion.

=Tasks/milestones=

* project start. Aug 29, 2008
* project review. ~2 week
* Implementation. ~8 week
* test. ~4 week
* code review. ~2 week
* documentation. ~3 day

=Desired integration and release goals=

=Testing plan=

Unit testing of all new and modified commands will be done to verify
they work as specified. This will be done for both the db2 and LDAP KDB
plugins.

The kadmind and krb5kdc daemons will be tested to verify they work
properly when accessing a KDB some set of principals is protected by one
mkey and the other set is protected by another set. Slave KDCs will
also be tested after the KDB is propagated both with kprop and kiprop.

Bounds testing will verify the krb utils and daemons work properly when
the MKVNO wraps back to 0.

The existing MIT Kerberos test suites will be run to make sure there are
no regressions introduced by this project.

==Review==

This section documents the review of the project according to [[Project policy]].
It is divided into multiple sections. First, approvals should be listed. To list an approval type
:<nowiki>#~~~~</nowiki>
on its own line.
The next section is for discussion. Use standard [http://en.wikipedia.org/wiki/Wikipedia:Tutorial_%28Talk_pages%29 talk page conventions]. In particular, sign comments with
:<nowiki>--~~~~</nowiki>
and indent replies.

Members of Krbcore raising Blocking objections should preface their comment with <nowiki>{{project-block}}</nowiki>. The member who raised the objection should remove this markup when their objection is handled.

===Approvals===

===Discussion===

Projects/Master Key Migration

2008-09-03T00:16:50Z

Wfiveash:

{{project-review|2008-09-16}}

=Desired changes=

This project will provide the ability to add a new master key (with an
enctype differing from the current master key) to the master key
principal and stash file and then migrate the encryption of existing
principals long term keys to use the new master key. In addition
deletion of master keys will be provided.

=Functional Requirements=

The KDC must be able to deal with multiple master keys and determine
which key to use when decrypting a principal's long term secret key.
The KDC must be able to access any of the master key (K/M) principal's
keys as long as it has access to a master key that is in use.

The administrator must be able re-encrypt principal keys using a
specified mkey and be able to specifying the set of principals is to be
re-encrypted. The command doing this must be able to determine if a
principal's keys are protected by the current master key or not. This
implies that some set of principals may be protected with a non-current
master key.

Slave KDC's must be able to access all master keys currently protecting
principal entries and therefore have access to the principal's secret
keys regardless of which master key is used to encrypt the key.

The administrator will be able to:

* Add a new master key to master key principal and optionally to the masterkey keytab stash.

* Enable a new master key (make it the current master key used to protect newly created principals or principal rekeys).

* List all master keys associated with the master key principal.

* Delete a particular master key from the master key principal and optionally from the masterkey keytab stash.

* Purge unused master keys (keys not used to protect any principal).

=Design of implementation=

Fundamentally the current implementation must be changed to support
multiple master keys. And possession of any master key stored with the
K/M principal allows access to all master keys. In addition, a
principal's secret key may be encrypted by any of the master keys in use
and the KDC must be able to decrypt that principal's key.

In order to accommodate this, these changes will be made:

* A new TL-data type, KRB5_TL_MKVNO, would apply to all principals except the K/M, and would store the version number of the master key used to encrypt the keys of that principal. The db2 back end would store it as opaque TL-data, the LDAP back end has a slot for it.
* The krb5_key_data array in the krb5_db_entry for the K/M principal will hold all master keys in use. All the keys in this array will be encrypted using the most recently created master key.
* A new TL-data type, KRB5_TL_MKEY_AUX, would apply only to the K/M principal. This new TL data would contain:
** The current master key version number that should be used when changing database entries. This may not be the latest key and is set by the administrator. If this TL-data type is not found in the K/M record then the default value for this will be 1 which is the default MKVNO.
** A set of copies of the latest master key, each encrypted by one of the other supported mkeys, in {old-mkvno, keydata} tuples. Thus the "master key" used in DAL (DB abstraction layer) need only be any one of these keys.
** Trailing stuff is ignored for now, making the structure extensible.
* kdc_realm_t will be modified to hold all master keys (including KVNO and enctype) associated with a realm. It will also hold the current mkey KVNO that should be used when encrypting a principal's keys. To facilitate this, a new struct will be defined:

typedef struct _krb5_keylist_node {
krb5_keyblock *keyblock;
krb5_kvno kvno;
struct _krb5_keylist_node *next;
} krb5_keyblock_node;

This will be used to create a list of mkeys. kdc_realm_t will also have
a current_realm_mkey which will point to the krb5_keyblock_node that
contains the current mkey (used when encrypting a principal's keys, does
not apply the K/M mkeys).

The initialization of the list of mkeys will occur in init_realm().

Any code needing to decrypt principal keys will need to determine which
mkey to use. A function will be created to return the mkey to use for
decrypting a principal's keys given the principal's krb5_db_entry and
realm_mkeys list as input args. If the principals krb5_db_entry does
not contain KRB5_TL_MKVNO TL-data the function will default to choosing
the mkey with KVNO 1. If the princ krb5_db_entry does have
KRB5_TL_MKVNO data and no matching mkey is found the function will get
the K/M princ KDB entry, update the list of mkeys if new mkeys are found
and return a matching mkey if found. An error will be returned if a
matching mkey is not found.

This function would be called prior to calling
krb5_dbekd_decrypt_key_data() to determine which mkey to pass in.

Similarly, any code calling krb5_dbekd_encrypt_key_data() will be
modified to pass in the current_realm_mkey (mentioned above).

kdb5_util will be modified to support these new commands:

; add_mkey [-s] : Add a new mkey to K/M. The optional -s will add the mkey to the stash file.

; use_mkey <KVNO> : Set the current mkey KVNO. This controls which mkey is used when encrypting principal keys. The kadmind should be stopped/disabled prior to running this command and enabled after successful completion.

; list_mkeys : Shows all masterkeys from most recent to earliest in K/M principal. The output will show the KVNO, enctype and salt for each mkey similar to kadmin getprinc output. A * following an mkey denotes the current mkey.

; purge_mkeys [-f] : Delete mkeys from K/M princ that are not used to protect any principals. With -f, does not prompt user.

; sync_stash [-f] : Sync up the set of keys in the keytab stash with those in the K/M princ entry in the KDB. Keys in keytab stash not found in K/M will be removed. With -f, does not prompt user.

; update_princ_encryption [-f] [expression] : Use current mkey to encrypt principals (other than K/M) secret keys if not already encrypted by that mkey. Should support either doing all princs if no argument given or a subset specified by expression (supports shell-style globbing, similar to kadmin). Both the principal's secret keys and key history will first be decrypted with the original encrypting mkey then encrypted with the current mkey. If the current mkey kvno is that of the mkey that originaly encrypted the principal's keys the code will stop processing that principal and go on to the next. With -f, does not prompt user.

The kdb5_util dump -mkey_convert will be modified to update the
KRB5_TL_MKVNO of all principals except the K/M principal with the KVNO
of the mkey used for the conversion. The K/M KRB5_TL_MKEY_AUX TL data
will be updated to include the new mkey used for the conversion.

=Tasks/milestones=

* project start. Aug 29, 2008
* project review. ~2 week
* Implementation. ~8 week
* test. ~4 week
* code review. ~2 week
* documentation. ~3 day

=Desired integration and release goals=

=Testing plan=

Unit testing of all new and modified commands will be done to verify
they work as specified. This will be done for both the db2 and LDAP KDB
plugins.

The kadmind and krb5kdc daemons will be tested to verify they work
properly when accessing a KDB some set of principals is protected by one
mkey and the other set is protected by another set. Slave KDCs will
also be tested after the KDB is propagated both with kprop and kiprop.

Bounds testing will verify the krb utils and daemons work properly when
the MKVNO wraps back to 0.

The existing MIT Kerberos test suites will be run to make sure there are
no regressions introduced by this project.

==Review==

This section documents the review of the project according to [[Project policy]].
It is divided into multiple sections. First, approvals should be listed. To list an approval type
:<nowiki>#~~~~</nowiki>
on its own line.
The next section is for discussion. Use standard [http://en.wikipedia.org/wiki/Wikipedia:Tutorial_%28Talk_pages%29 talk page conventions]. In particular, sign comments with
:<nowiki>--~~~~</nowiki>
and indent replies.

Members of Krbcore raising Blocking objections should preface their comment with <nowiki>{{project-block}}</nowiki>. The member who raised the objection should remove this markup when their objection is handled.

===Approvals===

===Discussion===

Projects/Master Key Migration

2008-09-03T00:10:54Z

Wfiveash: New page: {{project-early}} =Desired changes= This project will provide the ability to add a new master key (with an enctype differing from the current master key) to the master key principal and ...

{{project-early}}

=Desired changes=

This project will provide the ability to add a new master key (with an
enctype differing from the current master key) to the master key
principal and stash file and then migrate the encryption of existing
principals long term keys to use the new master key. In addition
deletion of master keys will be provided.

=Functional Requirements=

The KDC must be able to deal with multiple master keys and determine
which key to use when decrypting a principal's long term secret key.
The KDC must be able to access any of the master key (K/M) principal's
keys as long as it has access to a master key that is in use.

The administrator must be able re-encrypt principal keys using a
specified mkey and be able to specifying the set of principals is to be
re-encrypted. The command doing this must be able to determine if a
principal's keys are protected by the current master key or not. This
implies that some set of principals may be protected with a non-current
master key.

Slave KDC's must be able to access all master keys currently protecting
principal entries and therefore have access to the principal's secret
keys regardless of which master key is used to encrypt the key.

The administrator will be able to:

* Add a new master key to master key principal and optionally to the masterkey keytab stash.

* Enable a new master key (make it the current master key used to protect newly created principals or principal rekeys).

* List all master keys associated with the master key principal.

* Delete a particular master key from the master key principal and optionally from the masterkey keytab stash.

* Purge unused master keys (keys not used to protect any principal).

=Design of implementation=

Fundamentally the current implementation must be changed to support
multiple master keys. And possession of any master key stored with the
K/M principal allows access to all master keys. In addition, a
principal's secret key may be encrypted by any of the master keys in use
and the KDC must be able to decrypt that principal's key.

In order to accommodate this, these changes will be made:

* A new TL-data type, KRB5_TL_MKVNO, would apply to all principals except the K/M, and would store the version number of the master key used to encrypt the keys of that principal. The db2 back end would store it as opaque TL-data, the LDAP back end has a slot for it.
* The krb5_key_data array in the krb5_db_entry for the K/M principal will hold all master keys in use. All the keys in this array will be encrypted using the most recently created master key.
* A new TL-data type, KRB5_TL_MKEY_AUX, would apply only to the K/M principal. This new TL data would contain:
** The current master key version number that should be used when changing database entries. This may not be the latest key and is set by the administrator. If this TL-data type is not found in the K/M record then the default value for this will be 1 which is the default MKVNO.
** A set of copies of the latest master key, each encrypted by one of the other supported mkeys, in {old-mkvno, keydata} tuples. Thus the "master key" used in DAL (DB abstraction layer) need only be any one of these keys.
** Trailing stuff is ignored for now, making the structure extensible.
* kdc_realm_t will be modified to hold all master keys (including KVNO and enctype) associated with a realm. It will also hold the current mkey KVNO that should be used when encrypting a principal's keys. To facilitate this, a new struct will be defined:

typedef struct _krb5_keylist_node {
krb5_keyblock *keyblock;
krb5_kvno kvno;
struct _krb5_keylist_node *next;
} krb5_keyblock_node;

This will be used to create a list of mkeys. kdc_realm_t will also have
a current_realm_mkey which will point to the krb5_keyblock_node that
contains the current mkey (used when encrypting a principal's keys, does
not apply the K/M mkeys).

The initialization of the list of mkeys will occur in init_realm().

Any code needing to decrypt principal keys will need to determine which
mkey to use. A function will be created to return the mkey to use for
decrypting a principal's keys given the principal's krb5_db_entry and
realm_mkeys list as input args. If the principals krb5_db_entry does
not contain KRB5_TL_MKVNO TL-data the function will default to choosing
the mkey with KVNO 1. If the princ krb5_db_entry does have
KRB5_TL_MKVNO data and no matching mkey is found the function will get
the K/M princ KDB entry, update the list of mkeys if new mkeys are found
and return a matching mkey if found. An error will be returned if a
matching mkey is not found.

This function would be called prior to calling
krb5_dbekd_decrypt_key_data() to determine which mkey to pass in.

Similarly, any code calling krb5_dbekd_encrypt_key_data() will be
modified to pass in the current_realm_mkey (mentioned above).

kdb5_util will be modified to support these new commands:

; add_mkey [-s] : Add a new mkey to K/M. The optional -s will add the mkey to the stash file.

; use_mkey <KVNO> : Set the current mkey KVNO. This controls which mkey is used when encrypting principal keys. The kadmind should be stopped/disabled prior to running this command and enabled after successful completion.

; list_mkeys : Shows all masterkeys from most recent to earliest in K/M principal. The output will show the KVNO, enctype and salt for each mkey similar to kadmin getprinc output. A * following an mkey denotes the current mkey.

; purge_mkeys [-f] : Delete mkeys from K/M princ that are not used to protect any principals. With -f, does not prompt user.

; sync_stash [-f] : Sync up the set of keys in the keytab stash with those in the K/M princ entry in the KDB. Keys in keytab stash not found in K/M will be removed. With -f, does not prompt user.

; update_princ_encryption [-f] [expression] : Use current mkey to encrypt principals (other than K/M) secret keys if not already encrypted by that mkey. Should support either doing all princs if no argument given or a subset specified by expression (supports shell-style globbing, similar to kadmin). Both the principal's secret keys and key history will first be decrypted with the original encrypting mkey then encrypted with the current mkey. If the current mkey kvno is that of the mkey that originaly encrypted the principal's keys the code will stop processing that principal and go on to the next. With -f, does not prompt user.

The kdb5_util dump -mkey_convert will be modified to update the
KRB5_TL_MKVNO of all principals except the K/M principal with the KVNO
of the mkey used for the conversion. The K/M KRB5_TL_MKEY_AUX TL data
will be updated to include the new mkey used for the conversion.

=Tasks/milestones=

* project start. Aug 29, 2008
* project review. ~2 week
* Implementation. ~8 week
* test. ~4 week
* code review. ~2 week
* documentation. ~3 day

=Desired integration and release goals=

=Testing plan=

Unit testing of all new and modified commands will be done to verify
they work as specified. This will be done for both the db2 and LDAP KDB
plugins.

The kadmind and krb5kdc daemons will be tested to verify they work
properly when accessing a KDB some set of principals is protected by one
mkey and the other set is protected by another set. Slave KDCs will
also be tested after the KDB is propagated both with kprop and kiprop.

Bounds testing will verify the krb utils and daemons work properly when
the MKVNO wraps back to 0.

The existing MIT Kerberos test suites will be run to make sure there are
no regressions introduced by this project.

Projects/Masterkey Keytab Stash

2008-05-08T21:56:04Z

Wfiveash:

{{project-approved|2008-04-18}}

=Desired changes=

The point of this small project is to change the format of the master
key stash file to that of a keytab type file. This will allow the
master key's KVNO to be stored along with its enctype and key data which
in turn will enable an efficient implementation of master key updating.

=Functional Requirements=

The KDC must be able to access the most recent master key in the
masterkey keytab and also retrieve a master key
based on a given KVNO and or enctype. If the
masterkey is stored in the old stash file format then the KDC will be
backwards compatible and still be able to access the masterkey.

The utilities (kdb5_util, kdb_ldap_util, ktutil) must be able to read
and write to a masterkey keytab. These utilities will also be able to read and old format stash file.
They will not be able to write an old format stash file.

=Design of implementation=

The krb5_def_store_mkey() and krb5_db_def_fetch_mkey() functions would
be modified to use the keytab functions found in libkrb5.

The krb5_db_def_fetch_mkey() function would first try to read the master
key stash as a keytab file using krb5_kt_get_entry() and if that fails
it would fall back to using the current stash code to treat the stash
file as an old format stash file. Note that this function already has a
kvno arg that can be used for input and output. Also note that
krb5_db_def_fetch_mkey() will be passing the K/M@<realm> master key
principal as an arg to krb5_kt_get_entry() which will return an error if
there are no entries for that principal in the keytab.

The krb5_def_store_mkey() interface would be modified to write a keytab
and to accept an optional KVNO argument. It would need to deal with
existing old stash format files so the code would test to see if the
stash file existed and was non-0 size and if so, would first try reading
it as a keytab. If the stash file is determined to be a keytab by a
successful call to krb5_kt_get_entry() and the principal name is
verified to be correct then krb5_kt_add_entry() would be called to add
the new masterkey to the stash file.

If krb5_kt_get_entry() returned an error then the stash file would be
truncated to 0 bytes and then krb5_kt_add_entry() would be called to add
the masterkey entry. If the stash file did not exist or was 0 bytes in
size then krb5_kt_add_entry() would be called directly. The reason for
detecting and an existing old format stash file is to allow
krb5_def_store_mkey() the ability to store > 1 masterkey. Since
krb5_kt_add_entry() always appends to a keytab care must be taken to
ensure the existing stash file is a keytab and not the old format stash.

Callers of krb5_def_store_mkey() would need to be modified to deal with
the new KVNO argument. If a user specified KVNO was passed in and a key
with that KVNO existed in the keytab, an error would be returned
otherwise a new key with that KVNO would be added to the keytab. If a
KVNO was not specified, the current behavior whose KVNO would either be
0 if no keys exist in the keytab or would be one greater than the
largest KVNO found in the keytab.

The kdb5_util interface would be modified to allow the user to specify
the KVNO. The code will return an error if kdb5_util attemps to add a
key with a user specified KVNO to the masterkey keytab and a key with
that same KVNO already exists in the keytab. At that point the user
would either to use ktutil at that point to remove the existing key,
specify a different KVNO, or just remove the keytab file and rerun the
kdb5_util command.

Note the default file name convention currently used for stash files
will be used for masterkey keytab files. One implication of this is
that once an admin overwrites an existing old format stash file with the
new keytab format there is no going back to the old format as kdb5_util
will not support creation of the old format.

=Tasks/milestones=

* project start. Apr 3, 2008
* project review. ~2 week
* Implementation. ~2 week
* test. ~1 week
* code review. ~1 week
* documentation. ~1 day

=Desired integration and release goals=

Integrate and test before 1.7 release.

=Testing plan=

Unit testing of stash file related functions will be performed to make
sure the krb5kdc, kadmind, kadmin, kadmin.local, kdb5_util, and ktutil
are able to access and administer the masterkey keytab file. Tests will
be done for these scenarios:

* An old format stash file exists. The krb5kdc and kadmind should be
able to read the masterkey. The kdb5_util stash and create commands
should be able to overwrite the stash file.

* No stash exists. kdb5_util should be able to create a masterkey
keytab stash.

* The daemons that require masterkey access will be tested to validate
the ability to read the masterkey in a keytab.

Regression testing will be running the tests in the MIT source tree that
test the function of the krb5kdc, kadmind, kadmin, kadmin.local,
kdb5_util, and ktutil.

An old copy of a binary stash file will be checked in to the source
tree to aid in regression testing.

==Review==

This section documents the review of the project according to [[Project policy]].
It is divided into multiple sections. First, approvals should be listed. To list an approval type
:<nowiki>#~~~~</nowiki>
on its own line.
The next section is for discussion. Use standard ''talk page''conventions. In particular, sign comments with
:<nowiki>--~~~~</nowiki>
and indent replies.

Members of Krbcore raising Blocking objections should preface their comment with <nowiki>{{project-block}}</nowiki>. The member who raised the objection should remove this markup when their objection is handled.

===Approvals===
:[[User:SamHartman|SamHartman]] 12:20, 4 April 2008 (EDT)
===Discussion===

I've noted approval but I'd like to ask you to consider a couple of issues:
* It would be good if an old format stash file was checked into the source tree and the regression tests run with make check confirm we can read that stash file.
* Please clearly document what happens when kt_get_entry doesn't find the right principal but does parse the file as a keytab?
:--[[User:SamHartman|SamHartman]] 12:20, 4 April 2008 (EDT)

Projects/Masterkey Keytab Stash

2008-05-07T23:35:48Z

Wfiveash: /* Design of implementation */

{{project-review|2008-04-18}}

=Desired changes=

The point of this small project is to change the format of the master
key stash file to that of a keytab type file. This will allow the
master key's KVNO to be stored along with its enctype and key data which
in turn will enable an efficient implementation of master key updating.

=Functional Requirements=

The KDC must be able to access the most recent master key in the
masterkey keytab and also retrieve a master key
based on a given KVNO and or enctype. If the
masterkey is stored in the old stash file format then the KDC will be
backwards compatible and still be able to access the masterkey.

The utilities (kdb5_util, kdb_ldap_util, ktutil) must be able to read
and write to a masterkey keytab. These utilities will also be able to read and old format stash file.
They will not be able to write an old format stash file.

=Design of implementation=

The krb5_def_store_mkey() and krb5_db_def_fetch_mkey() functions would
be modified to use the keytab functions found in libkrb5.

The krb5_db_def_fetch_mkey() function would first try to read the master
key stash as a keytab file using krb5_kt_get_entry() and if that fails
it would fall back to using the current stash code to treat the stash
file as an old format stash file. Note that this function already has a
kvno arg that can be used for input and output. Also note that
krb5_db_def_fetch_mkey() will be passing the K/M@<realm> master key
principal as an arg to krb5_kt_get_entry() which will return an error if
there are no entries for that principal in the keytab.

The krb5_def_store_mkey() interface would be modified to write a keytab
and to accept an optional KVNO argument. It would need to deal with
existing old stash format files so the code would test to see if the
stash file existed and was non-0 size and if so, would first try reading
it as a keytab. If the stash file is determined to be a keytab by a
successful call to krb5_kt_get_entry() and the principal name is
verified to be correct then krb5_kt_add_entry() would be called to add
the new masterkey to the stash file.

If krb5_kt_get_entry() returned an error then the stash file would be
truncated to 0 bytes and then krb5_kt_add_entry() would be called to add
the masterkey entry. If the stash file did not exist or was 0 bytes in
size then krb5_kt_add_entry() would be called directly. The reason for
detecting and an existing old format stash file is to allow
krb5_def_store_mkey() the ability to store > 1 masterkey. Since
krb5_kt_add_entry() always appends to a keytab care must be taken to
ensure the existing stash file is a keytab and not the old format stash.

Callers of krb5_def_store_mkey() would need to be modified to deal with
the new KVNO argument. If a user specified KVNO was passed in and a key
with that KVNO existed in the keytab, an error would be returned
otherwise a new key with that KVNO would be added to the keytab. If a
KVNO was not specified, the current behavior whose KVNO would either be
0 if no keys exist in the keytab or would be one greater than the
largest KVNO found in the keytab.

The kdb5_util interface would be modified to allow the user to specify
the KVNO. The code will return an error if kdb5_util attemps to add a
key with a user specified KVNO to the masterkey keytab and a key with
that same KVNO already exists in the keytab. At that point the user
would either to use ktutil at that point to remove the existing key,
specify a different KVNO, or just remove the keytab file and rerun the
kdb5_util command.

Note the default file name convention currently used for stash files
will be used for masterkey keytab files. One implication of this is
that once an admin overwrites an existing old format stash file with the
new keytab format there is no going back to the old format as kdb5_util
will not support creation of the old format.

=Tasks/milestones=

* project start. Apr 3, 2008
* project review. ~2 week
* Implementation. ~2 week
* test. ~1 week
* code review. ~1 week
* documentation. ~1 day

=Desired integration and release goals=

Integrate and test before 1.7 release.

=Testing plan=

Unit testing of stash file related functions will be performed to make
sure the krb5kdc, kadmind, kadmin, kadmin.local, kdb5_util, and ktutil
are able to access and administer the masterkey keytab file. Tests will
be done for these scenarios:

* An old format stash file exists. The krb5kdc and kadmind should be
able to read the masterkey. The kdb5_util stash and create commands
should be able to overwrite the stash file.

* No stash exists. kdb5_util should be able to create a masterkey
keytab stash.

* The daemons that require masterkey access will be tested to validate
the ability to read the masterkey in a keytab.

Regression testing will be running the tests in the MIT source tree that
test the function of the krb5kdc, kadmind, kadmin, kadmin.local,
kdb5_util, and ktutil.

An old copy of a binary stash file will be checked in to the source
tree to aid in regression testing.

==Review==

This section documents the review of the project according to [[Project policy]].
It is divided into multiple sections. First, approvals should be listed. To list an approval type
:<nowiki>#~~~~</nowiki>
on its own line.
The next section is for discussion. Use standard ''talk page''conventions. In particular, sign comments with
:<nowiki>--~~~~</nowiki>
and indent replies.

Members of Krbcore raising Blocking objections should preface their comment with <nowiki>{{project-block}}</nowiki>. The member who raised the objection should remove this markup when their objection is handled.

===Approvals===
:[[User:SamHartman|SamHartman]] 12:20, 4 April 2008 (EDT)
===Discussion===

I've noted approval but I'd like to ask you to consider a couple of issues:
* It would be good if an old format stash file was checked into the source tree and the regression tests run with make check confirm we can read that stash file.
* Please clearly document what happens when kt_get_entry doesn't find the right principal but does parse the file as a keytab?
:--[[User:SamHartman|SamHartman]] 12:20, 4 April 2008 (EDT)

Projects/Masterkey Keytab Stash

2008-05-07T22:31:17Z

Wfiveash: /* Testing plan */

{{project-review|2008-04-18}}

=Desired changes=

The point of this small project is to change the format of the master
key stash file to that of a keytab type file. This will allow the
master key's KVNO to be stored along with its enctype and key data which
in turn will enable an efficient implementation of master key updating.

=Functional Requirements=

The KDC must be able to access the most recent master key in the
masterkey keytab and also retrieve a master key
based on a given KVNO and or enctype. If the
masterkey is stored in the old stash file format then the KDC will be
backwards compatible and still be able to access the masterkey.

The utilities (kdb5_util, kdb_ldap_util, ktutil) must be able to read
and write to a masterkey keytab. These utilities will also be able to read and old format stash file.
They will not be able to write an old format stash file.

=Design of implementation=

The krb5_def_store_mkey() and krb5_db_def_fetch_mkey() functions would
be modified to use the keytab functions found in libkrb5.

The krb5_db_def_fetch_mkey() function would first try to read the master
key stash as a keytab file using krb5_kt_get_entry() and if that fails
it would fall back to using the current stash code to treat the stash
file as an old format stash file. Note that this function already has a
kvno arg that can be used for input and output.

The krb5_def_store_mkey() interface would be modified to write a keytab
and to accept an optional KVNO argument. It would need to deal with
existing old stash format files so the code would test to see if the
stash file existed and was non-0 size and if so, would first try reading
it as a keytab. If the stash file is determined to be a keytab by a
successful call to krb5_kt_get_entry() and the principal name is
verified to be correct then krb5_kt_add_entry() would be called to add
the new masterkey to the stash file.

If krb5_kt_get_entry() returned an error then the stash file would be
truncated to 0 bytes and then krb5_kt_add_entry() would be called to add
the masterkey entry. If the stash file did not exist or was 0 bytes in
size then krb5_kt_add_entry() would be called directly. The reason for
detecting and an existing old format stash file is to allow
krb5_def_store_mkey() the ability to store > 1 masterkey. Since
krb5_kt_add_entry() always appends to a keytab care must be taken to
ensure the existing stash file is a keytab and not the old format stash.

Callers of krb5_def_store_mkey() would need to be modified to deal with
the new KVNO argument. If a user specified KVNO was passed in and a key
with that KVNO existed in the keytab, an error would be returned
otherwise a new key with that KVNO would be added to the keytab. If a
KVNO was not specified, the current behavior whose KVNO would either be
0 if no keys exist in the keytab or would be one greater than the
largest KVNO found in the keytab.

The kdb5_util interface would be modified to allow the user to specify
the KVNO. The code will return an error if kdb5_util attemps to add a
key with a user specified KVNO to the masterkey keytab and a key with
that same KVNO already exists in the keytab. At that point the user
would either to use ktutil at that point to remove the existing key,
specify a different KVNO, or just remove the keytab file and rerun the
kdb5_util command.

Note the default file name convention currently used for stash files
will be used for masterkey keytab files. One implication of this is
that once an admin overwrites an existing old format stash file with the
new keytab format there is no going back to the old format as kdb5_util
will not support creation of the old format.

=Tasks/milestones=

* project start. Apr 3, 2008
* project review. ~2 week
* Implementation. ~2 week
* test. ~1 week
* code review. ~1 week
* documentation. ~1 day

=Desired integration and release goals=

Integrate and test before 1.7 release.

=Testing plan=

Unit testing of stash file related functions will be performed to make
sure the krb5kdc, kadmind, kadmin, kadmin.local, kdb5_util, and ktutil
are able to access and administer the masterkey keytab file. Tests will
be done for these scenarios:

* An old format stash file exists. The krb5kdc and kadmind should be
able to read the masterkey. The kdb5_util stash and create commands
should be able to overwrite the stash file.

* No stash exists. kdb5_util should be able to create a masterkey
keytab stash.

* The daemons that require masterkey access will be tested to validate
the ability to read the masterkey in a keytab.

Regression testing will be running the tests in the MIT source tree that
test the function of the krb5kdc, kadmind, kadmin, kadmin.local,
kdb5_util, and ktutil.

An old copy of a binary stash file will be checked in to the source
tree to aid in regression testing.

==Review==

This section documents the review of the project according to [[Project policy]].
It is divided into multiple sections. First, approvals should be listed. To list an approval type
:<nowiki>#~~~~</nowiki>
on its own line.
The next section is for discussion. Use standard ''talk page''conventions. In particular, sign comments with
:<nowiki>--~~~~</nowiki>
and indent replies.

Members of Krbcore raising Blocking objections should preface their comment with <nowiki>{{project-block}}</nowiki>. The member who raised the objection should remove this markup when their objection is handled.

===Approvals===
:[[User:SamHartman|SamHartman]] 12:20, 4 April 2008 (EDT)
===Discussion===

I've noted approval but I'd like to ask you to consider a couple of issues:
* It would be good if an old format stash file was checked into the source tree and the regression tests run with make check confirm we can read that stash file.
* Please clearly document what happens when kt_get_entry doesn't find the right principal but does parse the file as a keytab?
:--[[User:SamHartman|SamHartman]] 12:20, 4 April 2008 (EDT)

Projects/Masterkey Keytab Stash

2008-04-18T16:58:58Z

Wfiveash: /* Functional Requirements */

{{project-review|2008-04-18}}

=Desired changes=

The point of this small project is to change the format of the master
key stash file to that of a keytab type file. This will allow the
master key's KVNO to be stored along with its enctype and key data which
in turn will enable an efficient implementation of master key updating.

=Functional Requirements=

The KDC must be able to access the most recent master key in the
masterkey keytab and also retrieve a master key
based on a given KVNO and or enctype. If the
masterkey is stored in the old stash file format then the KDC will be
backwards compatible and still be able to access the masterkey.

The utilities (kdb5_util, kdb_ldap_util, ktutil) must be able to read
and write to a masterkey keytab. These utilities will also be able to read and old format stash file.
They will not be able to write an old format stash file.

=Design of implementation=

The krb5_def_store_mkey() and krb5_db_def_fetch_mkey() functions would
be modified to use the keytab functions found in libkrb5.

The krb5_db_def_fetch_mkey() function would first try to read the master
key stash as a keytab file using krb5_kt_get_entry() and if that fails
it would fall back to using the current stash code to treat the stash
file as an old format stash file. Note that this function already has a
kvno arg that can be used for input and output.

The krb5_def_store_mkey() interface would be modified to write a keytab
and to accept an optional KVNO argument. It would need to deal with
existing old stash format files so the code would test to see if the
stash file existed and was non-0 size and if so, would first try reading
it as a keytab. If the stash file is determined to be a keytab by a
successful call to krb5_kt_get_entry() and the principal name is
verified to be correct then krb5_kt_add_entry() would be called to add
the new masterkey to the stash file.

If krb5_kt_get_entry() returned an error then the stash file would be
truncated to 0 bytes and then krb5_kt_add_entry() would be called to add
the masterkey entry. If the stash file did not exist or was 0 bytes in
size then krb5_kt_add_entry() would be called directly. The reason for
detecting and an existing old format stash file is to allow
krb5_def_store_mkey() the ability to store > 1 masterkey. Since
krb5_kt_add_entry() always appends to a keytab care must be taken to
ensure the existing stash file is a keytab and not the old format stash.

Callers of krb5_def_store_mkey() would need to be modified to deal with
the new KVNO argument. If a user specified KVNO was passed in and a key
with that KVNO existed in the keytab, an error would be returned
otherwise a new key with that KVNO would be added to the keytab. If a
KVNO was not specified, the current behavior whose KVNO would either be
0 if no keys exist in the keytab or would be one greater than the
largest KVNO found in the keytab.

The kdb5_util interface would be modified to allow the user to specify
the KVNO. The code will return an error if kdb5_util attemps to add a
key with a user specified KVNO to the masterkey keytab and a key with
that same KVNO already exists in the keytab. At that point the user
would either to use ktutil at that point to remove the existing key,
specify a different KVNO, or just remove the keytab file and rerun the
kdb5_util command.

Note the default file name convention currently used for stash files
will be used for masterkey keytab files. One implication of this is
that once an admin overwrites an existing old format stash file with the
new keytab format there is no going back to the old format as kdb5_util
will not support creation of the old format.

=Tasks/milestones=

* project start. Apr 3, 2008
* project review. ~2 week
* Implementation. ~2 week
* test. ~1 week
* code review. ~1 week
* documentation. ~1 day

=Desired integration and release goals=

Integrate and test before 1.7 release.

=Testing plan=

Unit testing of stash file related functions will be performed to make
sure the krb5kdc, kadmind, kadmin, kadmin.local, kdb5_util, and ktutil
are able to access and administer the masterkey keytab file. Tests will
be done for these scenarios:

* An old format stash file exists. The krb5kdc and kadmind should be
able to read the masterkey. The kdb5_util stash and create commands
should be able to overwrite the stash file.

* No stash exists. kdb5_util should be able to create a masterkey
keytab stash.

* The daemons that require masterkey access will be tested to validate
the ability to read the masterkey in a keytab.

Regression testing will be running the tests in the MIT source tree that
test the function of the krb5kdc, kadmind, kadmin, kadmin.local,
kdb5_util, and ktutil.

==Review==

This section documents the review of the project according to [[Project policy]].
It is divided into multiple sections. First, approvals should be listed. To list an approval type
:<nowiki>#~~~~</nowiki>
on its own line.
The next section is for discussion. Use standard ''talk page''conventions. In particular, sign comments with
:<nowiki>--~~~~</nowiki>
and indent replies.

Members of Krbcore raising Blocking objections should preface their comment with <nowiki>{{project-block}}</nowiki>. The member who raised the objection should remove this markup when their objection is handled.

===Approvals===
:[[User:SamHartman|SamHartman]] 12:20, 4 April 2008 (EDT)
===Discussion===

I've noted approval but I'd like to ask you to consider a couple of issues:
* It would be good if an old format stash file was checked into the source tree and the regression tests run with make check confirm we can read that stash file.
* Please clearly document what happens when kt_get_entry doesn't find the right principal but does parse the file as a keytab?
:--[[User:SamHartman|SamHartman]] 12:20, 4 April 2008 (EDT)

Talk:Project policy

2008-04-10T21:23:04Z

Wfiveash: /* Proposing a project Issue */

I don't see a link from the project policy on the k5wiki to code change/integration policy. So I do not know if a code review is necessary and what sort of testing is expected.
: There is not a formalized code review policy. Certainly requesting specific code review as part of the community review of a project would be fine. --[[User:SamHartman|SamHartman]] 12:08, 4 April 2008 (EDT)

== Submitting a project for review needs work ==

The "Submitting a project for review" section indicates the submitter
should:
<pre>
To start the review period :

1. Replace {{project-early}} with {{project-review|end_of_review_date}}
2. Add {{subst:project-vote}} at the bottom of the project page.
3. Send mail to krbdev@mit.edu including:
</pre>

But after saving the project page after following steps 1 & 2, this text
appears on the project page:

An announcement has been sent to krbdev@mit.edu starting a review of
this project. That review will conclude on 2008-04-18.

This is confusing as it sounds like step 3 was done automatically by the
wiki. If the wiki is sending out notification automatically (and I
think it should) then step 3 should be removed.

:The Wiki cannot send out mail. The procedure is correct, but the text on the project page assumes that you actually follow the directions and send the mail. --[[User:SamHartman|SamHartman]] 12:08, 4 April 2008 (EDT)

::I think the wording of the project-review template needs to be changed to avoid the ambiguity. Something like:

The project owner should have sent an announcement to krbdev@mit.edu starting a review of
this project. That review will conclude on 2008-04-18.
:: --[[User:Wfiveash|Will Fiveash]] 12:42, 4 April 2008 (CDT)
:::I think updating the policy to make it clear that you need to send the mail but that the page will say that mail is sent would be good. I think that updating the template will be more confusing than desirable. I'll also update the template docs. --[[User:SamHartman|SamHartman]] 13:51, 4 April 2008 (EDT)

== let no one else's work evade your eyes... ==

This is mostly about meta-issues, like how to find project policies for other opensource projects (with links to same) than it is about the content of the policies themselves(''project'' as in ''opensource entity'', like MySQL, not as in a development project for said entity. This is what you get when you hire a tech writer.)

How we make this information available implies how easy it is to contribute to an existing project vs. how easy it is to propose a project (and affect the general road map). Some opensource projects hide this information from the general public, restricting it to members.

Come to that, I don't see any obvious information about how to become a "member" on our wiki-- i.e.,set up an account with wiki-editing privileges for the Kerberos wiki. I think all you get is an error message that you have to log in to edit a page (is it the same for talk?). There's nothing at all on the [http://web.mit.edu/kerberos/ public web site] about membership/contribution, nor is there any mention or link to the public wiki. Do we want to control access to information about this level of development? I think this is inherently part of the policy -- who can even find this information? (I think this topic should be considered w/r/t the new website design.)

----

'''Eclipse''' presents this information on the [http://www.eclipse.org/projects/dev_process/development_process.php Development Process] page. It's pretty structured -- do we want to be this formal? Requests and complaints about policy are entered into the bug log. There's also a link to the version-in-progress, and a link to the diffs between it and the current version.

''The Wiki cannot send out mail. The procedure is correct, but the text on the project page assumes that you actually follow the directions and send the mail. --SamHartman 12:08, 4 April 2008 (EDT)

'''LaTex''' gets around this by offering mailing lists to which anyone can subscribe on their [http://www.latex-project.org/code.html Development Code] page. I know we have links to our various mailing lists on the [http://web.mit.edu/kerberos/ public web site] but nothing explicit about a mechanism for using a list to send mail for this purpose Maybe it should be part of the policy page in the wiki? Is that an appropriate use for a mailing list? I hesitate to recommend a separate mailing list for such things (we already have so many!).

BTW, LaTex names their website [http://www.latex-project.org LaTex Project], which implies that it's not so much a product as an ongoing development process. What we call things affects others' perceptions.

'''MySQL''' has a very slick site with a tab for [http://dev.mysql.com Developer Zone]. FWIW, I don't like the site itself because it looks too corporate, not like a friendly opensource home page. I didn't delve into it, but it looks like their policy requires potential developers to pass a certification test. They also have a very nice [http://forums.mysql.com forum page].

There's also [http://opensourcehowto.org OpenSource HowTo], but it's intended for novices. BTW, I searched on "kerberos" and it only appeared buried in articles about other opensource programs.

Obviously, I could cite examples forever -- so I'll stop now.

--[[User:Estone|Estone]] 14:12, 10 April 2008 (EDT)

:[[Developers]] makes it fairly clear that anyone can contribute. The login page has a link for creating an account. I think it fairly likely that anyone who will successfully manage to contribute to the project will be able to figure that out. I think this wiki is intended to be fairly public. I'm reasonably sure this discussion belongs somewhere else--perhaps [[K5wiki:Positioning the wiki]] or some such. --[[User:SamHartman|SamHartman]] 17:04, 10 April 2008 (EDT)

== Proposing a project Issue ==

In the Proposing a project section there is this list of elements a
project proposal should have:

* A description of the desired change in functionality
* Any functional requirements that must be met for the project to be successful
* A design for how the desired functionality will be implemented
* A breakdown of tasks or milestones to judge progress of the project
* Screenshots or other proposed user interface descriptions
* Documentation and sample code for any APIs that are proposed
* Dependencies on other projects
* Information on desired integration and release goals
* Testing plan

My issue with the above is that having to include a design,
documentation and test plan in the initial project proposal is too
burdensome. I think the initial proposal must include:

* A description of the desired change in functionality
* Any functional requirements that must be met for the project to be successful
* A breakdown of tasks or milestones to judge progress of the project
* Screenshots or other proposed user interface descriptions
* Dependencies on other projects
* Information on desired integration and release goals

and the following would be optional in the initial proposal but would
have to be submitted for further review if the initial proposal was
accepted:

* A design for how the desired functionality will be implemented
* Documentation and sample code for any APIs that are proposed
* Testing plan

So the idea would be that someone could submit a light weight project
proposal and if that is approved they would follow up with more detail
which would then be reviewed.

--[[User:Wfiveash|Will Fiveash]] 14:35, 10 April 2008 (CDT)

:I think it is fine for people to include less than is required for approval in a project proposal. However without a design I don't think the project should be approved; I think a "sounds like a good start; finish this off" response is fine. I think we may be agreening with each other. The question may be what changes do we need to make to the policy to make this more clear. --[[User:SamHartman|SamHartman]] 17:00, 10 April 2008 (EDT)

::I think we agree. However the wording of this section needs work. It's not clear to me from the doc what the point of the early stage is. If this is for the initial discussion of whether a project has a chance of approval then this should be fleshed out more.

::The wording of the project proposal section should make it clear as what sections are absolutely needed for the early stage and what sections are optional at the early stage.

::--[[User:Wfiveash|Will Fiveash]] 16:19, 10 April 2008 (CDT)

Talk:Project policy

2008-04-10T21:20:17Z

Wfiveash: /* Proposing a project Issue */

I don't see a link from the project policy on the k5wiki to code change/integration policy. So I do not know if a code review is necessary and what sort of testing is expected.
: There is not a formalized code review policy. Certainly requesting specific code review as part of the community review of a project would be fine. --[[User:SamHartman|SamHartman]] 12:08, 4 April 2008 (EDT)

== Submitting a project for review needs work ==

The "Submitting a project for review" section indicates the submitter
should:
<pre>
To start the review period :

1. Replace {{project-early}} with {{project-review|end_of_review_date}}
2. Add {{subst:project-vote}} at the bottom of the project page.
3. Send mail to krbdev@mit.edu including:
</pre>

But after saving the project page after following steps 1 & 2, this text
appears on the project page:

An announcement has been sent to krbdev@mit.edu starting a review of
this project. That review will conclude on 2008-04-18.

This is confusing as it sounds like step 3 was done automatically by the
wiki. If the wiki is sending out notification automatically (and I
think it should) then step 3 should be removed.

:The Wiki cannot send out mail. The procedure is correct, but the text on the project page assumes that you actually follow the directions and send the mail. --[[User:SamHartman|SamHartman]] 12:08, 4 April 2008 (EDT)

::I think the wording of the project-review template needs to be changed to avoid the ambiguity. Something like:

The project owner should have sent an announcement to krbdev@mit.edu starting a review of
this project. That review will conclude on 2008-04-18.
:: --[[User:Wfiveash|Will Fiveash]] 12:42, 4 April 2008 (CDT)
:::I think updating the policy to make it clear that you need to send the mail but that the page will say that mail is sent would be good. I think that updating the template will be more confusing than desirable. I'll also update the template docs. --[[User:SamHartman|SamHartman]] 13:51, 4 April 2008 (EDT)

== let no one else's work evade your eyes... ==

This is mostly about meta-issues, like how to find project policies for other opensource projects (with links to same) than it is about the content of the policies themselves(''project'' as in ''opensource entity'', like MySQL, not as in a development project for said entity. This is what you get when you hire a tech writer.)

How we make this information available implies how easy it is to contribute to an existing project vs. how easy it is to propose a project (and affect the general road map). Some opensource projects hide this information from the general public, restricting it to members.

Come to that, I don't see any obvious information about how to become a "member" on our wiki-- i.e.,set up an account with wiki-editing privileges for the Kerberos wiki. I think all you get is an error message that you have to log in to edit a page (is it the same for talk?). There's nothing at all on the [http://web.mit.edu/kerberos/ public web site] about membership/contribution, nor is there any mention or link to the public wiki. Do we want to control access to information about this level of development? I think this is inherently part of the policy -- who can even find this information? (I think this topic should be considered w/r/t the new website design.)

----

'''Eclipse''' presents this information on the [http://www.eclipse.org/projects/dev_process/development_process.php Development Process] page. It's pretty structured -- do we want to be this formal? Requests and complaints about policy are entered into the bug log. There's also a link to the version-in-progress, and a link to the diffs between it and the current version.

''The Wiki cannot send out mail. The procedure is correct, but the text on the project page assumes that you actually follow the directions and send the mail. --SamHartman 12:08, 4 April 2008 (EDT)

'''LaTex''' gets around this by offering mailing lists to which anyone can subscribe on their [http://www.latex-project.org/code.html Development Code] page. I know we have links to our various mailing lists on the [http://web.mit.edu/kerberos/ public web site] but nothing explicit about a mechanism for using a list to send mail for this purpose Maybe it should be part of the policy page in the wiki? Is that an appropriate use for a mailing list? I hesitate to recommend a separate mailing list for such things (we already have so many!).

BTW, LaTex names their website [http://www.latex-project.org LaTex Project], which implies that it's not so much a product as an ongoing development process. What we call things affects others' perceptions.

'''MySQL''' has a very slick site with a tab for [http://dev.mysql.com Developer Zone]. FWIW, I don't like the site itself because it looks too corporate, not like a friendly opensource home page. I didn't delve into it, but it looks like their policy requires potential developers to pass a certification test. They also have a very nice [http://forums.mysql.com forum page].

There's also [http://opensourcehowto.org OpenSource HowTo], but it's intended for novices. BTW, I searched on "kerberos" and it only appeared buried in articles about other opensource programs.

Obviously, I could cite examples forever -- so I'll stop now.

--[[User:Estone|Estone]] 14:12, 10 April 2008 (EDT)

:[[Developers]] makes it fairly clear that anyone can contribute. The login page has a link for creating an account. I think it fairly likely that anyone who will successfully manage to contribute to the project will be able to figure that out. I think this wiki is intended to be fairly public. I'm reasonably sure this discussion belongs somewhere else--perhaps [[K5wiki:Positioning the wiki]] or some such. --[[User:SamHartman|SamHartman]] 17:04, 10 April 2008 (EDT)

== Proposing a project Issue ==

In the Proposing a project section there is this list of elements a
project proposal should have:

* A description of the desired change in functionality
* Any functional requirements that must be met for the project to be successful
* A design for how the desired functionality will be implemented
* A breakdown of tasks or milestones to judge progress of the project
* Screenshots or other proposed user interface descriptions
* Documentation and sample code for any APIs that are proposed
* Dependencies on other projects
* Information on desired integration and release goals
* Testing plan

My issue with the above is that having to include a design,
documentation and test plan in the initial project proposal is too
burdensome. I think the initial proposal must include:

* A description of the desired change in functionality
* Any functional requirements that must be met for the project to be successful
* A breakdown of tasks or milestones to judge progress of the project
* Screenshots or other proposed user interface descriptions
* Dependencies on other projects
* Information on desired integration and release goals

and the following would be optional in the initial proposal but would
have to be submitted for further review if the initial proposal was
accepted:

* A design for how the desired functionality will be implemented
* Documentation and sample code for any APIs that are proposed
* Testing plan

So the idea would be that someone could submit a light weight project
proposal and if that is approved they would follow up with more detail
which would then be reviewed.

--[[User:Wfiveash|Will Fiveash]] 14:35, 10 April 2008 (CDT)

:I think it is fine for people to include less than is required for approval in a project proposal. However without a design I don't think the project should be approved; I think a "sounds like a good start; finish this off" response is fine. I think we may be agreening with each other. The question may be what changes do we need to make to the policy to make this more clear. --[[User:SamHartman|SamHartman]] 17:00, 10 April 2008 (EDT)

I think we agree. However the wording of this section needs work.
It's not clear to me from the doc what the point of the early stage is.
If this is for the initial discussion of whether a project has a chance
of approval then this should be fleshed out more.

The wording of the project proposal section should make it clear as what
sections are absolutely needed for the early stage and what sections are
optional at the early stage.

--[[User:Wfiveash|Will Fiveash]] 16:19, 10 April 2008 (CDT)

Talk:Project policy

2008-04-10T19:38:40Z

Wfiveash: New section: Proposing a project Issue

I don't see a link from the project policy on the k5wiki to code change/integration policy. So I do not know if a code review is necessary and what sort of testing is expected.
: There is not a formalized code review policy. Certainly requesting specific code review as part of the community review of a project would be fine. --[[User:SamHartman|SamHartman]] 12:08, 4 April 2008 (EDT)

== Submitting a project for review needs work ==

The "Submitting a project for review" section indicates the submitter
should:
<pre>
To start the review period :

1. Replace {{project-early}} with {{project-review|end_of_review_date}}
2. Add {{subst:project-vote}} at the bottom of the project page.
3. Send mail to krbdev@mit.edu including:
</pre>

But after saving the project page after following steps 1 & 2, this text
appears on the project page:

An announcement has been sent to krbdev@mit.edu starting a review of
this project. That review will conclude on 2008-04-18.

This is confusing as it sounds like step 3 was done automatically by the
wiki. If the wiki is sending out notification automatically (and I
think it should) then step 3 should be removed.

:The Wiki cannot send out mail. The procedure is correct, but the text on the project page assumes that you actually follow the directions and send the mail. --[[User:SamHartman|SamHartman]] 12:08, 4 April 2008 (EDT)

::I think the wording of the project-review template needs to be changed to avoid the ambiguity. Something like:

The project owner should have sent an announcement to krbdev@mit.edu starting a review of
this project. That review will conclude on 2008-04-18.
:: --[[User:Wfiveash|Will Fiveash]] 12:42, 4 April 2008 (CDT)
:::I think updating the policy to make it clear that you need to send the mail but that the page will say that mail is sent would be good. I think that updating the template will be more confusing than desirable. I'll also update the template docs. --[[User:SamHartman|SamHartman]] 13:51, 4 April 2008 (EDT)

== let no one else's work evade your eyes... ==

This is mostly about meta-issues, like how to find project policies for other opensource projects (with links to same) than it is about the content of the policies themselves(''project'' as in ''opensource entity'', like MySQL, not as in a development project for said entity. This is what you get when you hire a tech writer.)

How we make this information available implies how easy it is to contribute to an existing project vs. how easy it is to propose a project (and affect the general road map). Some opensource projects hide this information from the general public, restricting it to members.

Come to that, I don't see any obvious information about how to become a "member" on our wiki-- i.e.,set up an account with wiki-editing privileges for the Kerberos wiki. I think all you get is an error message that you have to log in to edit a page (is it the same for talk?). There's nothing at all on the [http://web.mit.edu/kerberos/ public web site] about membership/contribution, nor is there any mention or link to the public wiki. Do we want to control access to information about this level of development? I think this is inherently part of the policy -- who can even find this information? (I think this topic should be considered w/r/t the new website design.)

----

'''Eclipse''' presents this information on the [http://www.eclipse.org/projects/dev_process/development_process.php Development Process] page. It's pretty structured -- do we want to be this formal? Requests and complaints about policy are entered into the bug log. There's also a link to the version-in-progress, and a link to the diffs between it and the current version.

''The Wiki cannot send out mail. The procedure is correct, but the text on the project page assumes that you actually follow the directions and send the mail. --SamHartman 12:08, 4 April 2008 (EDT)

'''LaTex''' gets around this by offering mailing lists to which anyone can subscribe on their [http://www.latex-project.org/code.html Development Code] page. I know we have links to our various mailing lists on the [http://web.mit.edu/kerberos/ public web site] but nothing explicit about a mechanism for using a list to send mail for this purpose Maybe it should be part of the policy page in the wiki? Is that an appropriate use for a mailing list? I hesitate to recommend a separate mailing list for such things (we already have so many!).

BTW, LaTex names their website [http://www.latex-project.org LaTex Project], which implies that it's not so much a product as an ongoing development process. What we call things affects others' perceptions.

'''MySQL''' has a very slick site with a tab for [http://dev.mysql.com Developer Zone]. FWIW, I don't like the site itself because it looks too corporate, not like a friendly opensource home page. I didn't delve into it, but it looks like their policy requires potential developers to pass a certification test. They also have a very nice [http://forums.mysql.com forum page].

There's also [http://opensourcehowto.org OpenSource HowTo], but it's intended for novices. BTW, I searched on "kerberos" and it only appeared buried in articles about other opensource programs.

Obviously, I could cite examples forever -- so I'll stop now.

--[[User:Estone|Estone]] 14:12, 10 April 2008 (EDT)

== Proposing a project Issue ==

In the Proposing a project section there is this list of elements a
project proposal should have:

* A description of the desired change in functionality
* Any functional requirements that must be met for the project to be successful
* A design for how the desired functionality will be implemented
* A breakdown of tasks or milestones to judge progress of the project
* Screenshots or other proposed user interface descriptions
* Documentation and sample code for any APIs that are proposed
* Dependencies on other projects
* Information on desired integration and release goals
* Testing plan

My issue with the above is that having to include a design,
documentation and test plan in the initial project proposal is too
burdensome. I think the initial proposal must include:

* A description of the desired change in functionality
* Any functional requirements that must be met for the project to be successful
* A breakdown of tasks or milestones to judge progress of the project
* Screenshots or other proposed user interface descriptions
* Dependencies on other projects
* Information on desired integration and release goals

and the following would be optional in the initial proposal but would
have to be submitted for further review if the initial proposal was
accepted:

* A design for how the desired functionality will be implemented
* Documentation and sample code for any APIs that are proposed
* Testing plan

So the idea would be that someone could submit a light weight project
proposal and if that is approved they would follow up with more detail
which would then be reviewed.

--[[User:Wfiveash|Will Fiveash]] 14:35, 10 April 2008 (CDT)

Talk:Project policy

2008-04-04T17:43:43Z

Wfiveash:

Project policy

2008-04-04T17:15:37Z

Wfiveash:

{{policy}}

The '''Project Policy''' describes how members of the community propose to make changes in MIT Kerberos. A project is a proposal to add new functionality or to change existing functionality in MIT Kerberos. Projects are reviewed by the community before the required changes can be integrated into MIT Kerberos. This review provides the community an opportunity to suggest improvements to the project and to confirm that the community believes that implementing the project would be a good idea.

==When are projects needed?==

Small changes and relatively simple bug fixes do not require a project. The project process is designed to provide sufficient community review. If a change is simple enough and uncontroversial enough then the change can be made without going through this process. If members of the development community,especially members of [[Krbcore]], wish to review the change then it should go through a project process. If a change is committed outside of a project and objections are raised, then any member of Krbcore may revert the change until a project is approved.

The following always require the project process to be invoked:
# Introduction of any public [[API]]s
# Changes in an API or the [[ABI]]. Such changes are rarely approved
# Significant user interface changes such as the introduction of a new dialogue .
# Introduction of configuration file variables or documented registry keys

==Proposing a project==

To propose a project, create a new page under [[Projects]]. For example a project to create a new administration protocol might be called "Projects/new administration protocol".
At the beginning of that page include the following:
<blockquote>
<nowiki>{{project-early}}
</nowiki></blockquote>
This will include the [[Template:project-early|early project template]] which indicates that the project is being fleshed out by its supporters and is not yet under consideration for approval. Note, to create a page enter the page name ("Projects/new administration protocol" for example) in the wiki search box on left and click on the Go button.

The project proposal page should include the following elements:
* A description of the desired change in functionality
* Any functional requirements that must be met for the project to be successful
* A design for how the desired functionality will be implemented
* A breakdown of tasks or milestones to judge progress of the project
* Screenshots or other proposed user interface descriptions
* Documentation and sample code for any APIs that are proposed
* Dependencies on other projects
* Information on desired integration and release goals
* Testing plan

===User Interface===

It is expected that screenshots describing any proposed user interface will be included in any project that describes new interfaces. Discussion of customer study groups that have evaluated the new interface or other information to validate the interface will help support the project.

===Documenting proposed APIs===
See [[Documenting APIs]] for current recommendations on how to document APIs that are introduced in a project. Typically, the community will expect sample code to be included describing the use of APIs that are introduced.

==Which release does a project go in==

Unless a project mentions it is targeting a specific release, then the project will be included in the next release [[Release branches|branched]] off the [[trunk]] after the project is checked in.

Typically the goals of a given release are set during a release planning process at the beginning of that release process. It is unusual to include additional projects in a release after the planning has concluded. A project may propose that it be included in a specific release after the goals for that release have been set, although absent a very convincing justification this is likely to result in blocking objections.

If a project is a goal for a given release, it will typically need to include milestones to judge its progress against the rest of the release. If the project is being managed by the consortium staff, then the consortium project tracking process will be used. For projects not being done by consortium staff, it is typical to establish coordination point milestones. See [[Meeting release goals]] for information on how these milestones are used once projects are approved.

==Submitting a project for review==

Except in cases where prompt action is required, projects require a two week review cycle. Projects require at least one yes vote from a member of Krbcore who has not been a primary proponent of the project to be approved and no blocking objections. Proponents of the project should work with members of the community to address suggestions that are raised even if these suggestions are not blocking objections. If discussion of significant issues is ongoing when the review period extends then approval should be delayed until the discussion concludes.

To start the review period :
# Replace <nowiki>{{project-early}} with {{project-review|end_of_review_date}}</nowiki>
# Add <nowiki>{{subst:project-vote}}</nowiki> at the bottom of the project page.
# Send mail to krbdev@mit.edu including:
##The URI to the project page
##The end of the review period
##Cut and paste the description of the project from the project page into the review.

==That's a good start==

Often the result of a review will be that what is written so far is good enough that the community wants to explore the project, but checkpoints or '''review gates''' are required. Examples of such gates include things like requesting review of design of a particular part of the system, requesting review of APIs that are designed in the future, or interactions with some part of the system. Particularly when some of the recommended information is not included in the original project proposal, a review gate may be requested. When the information to be reviewed is available, another project review should be conducted. There are no specific details on how to document this review other than that the <nowiki>{{project-review}}</nowiki> template should be used so that the project is categorized as under review.

== Project life cycle changes==

===Approving a project===

If the project review concludes successfully then:
# Replace <nowiki>{{project-review}} with {{project-approved}}</nowiki>.
#Add a ''Current status'' section at the bottom of the project page to track updates
# Send mail to krbdev@mit.edu noting that the project is approved.
# If the project is targeted for a specific release add <nowiki>{{project-target|release_name}}</nowiki> below the project-approved target.

===Marking a project as completed===

Replace <nowiki>{{project-approved}}</nowiki> with <nowiki>{{project-completed}}</nowiki>. If the release including the project has shipped, replace <nowiki>{{project-target}} with {{project-release|release_name}}</nowiki>

===Updating the scope or design of the project===

Any significant updates to the project design or scope should be sent to krbdev@mit.edu. Comments should be addressed; if blocking objections are raised then they must be addressed.

Talk:Project policy

2008-04-04T00:29:48Z

Wfiveash: New section: Submitting a project for review needs work

I don't see a link from the project policy on the k5wiki to code change/integration policy. So I do not know if a code review is necessary and what sort of testing is expected.

== Submitting a project for review needs work ==

The "Submitting a project for review" section indicates the submitter
should:
<pre>
To start the review period :

1. Replace {{project-early}} with {{project-review|end_of_review_date}}
2. Add {{subst:project-vote}} at the bottom of the project page.
3. Send mail to krbdev@mit.edu including:
</pre>

But after saving the project page after following steps 1 & 2, this text
appears on the project page:

An announcement has been sent to krbdev@mit.edu starting a review of
this project. That review will conclude on 2008-04-18.

This is confusing as it sounds like step 3 was done automatically by the
wiki. If the wiki is sending out notification automatically (and I
think it should) then step 3 should be removed.

Projects/Masterkey Keytab Stash

2008-04-03T23:56:48Z

Wfiveash:

{{project-review|2008-04-18}}

=Desired changes=

The point of this small project is to change the format of the master
key stash file to that of a keytab type file. This will allow the
master key's KVNO to be stored along with its enctype and key data which
in turn will enable an efficient implementation of master key updating.

=Functional Requirements=

The KDC must be able to access the most recent master key in the
masterkey keytab given a principal name and also retrieve a master key
based on a given principal name and a KVNO and or enctype. If the
masterkey is stored in the old stash file format then the KDC will be
backwards compatible and still be able to access the masterkey.

The utilities (kdb5_util, kdb_ldap_util, ktutil) must be able to read
and write to a masterkey keytab.

=Design of implementation=

The krb5_def_store_mkey() and krb5_db_def_fetch_mkey() functions would
be modified to use the keytab functions found in libkrb5.

The krb5_db_def_fetch_mkey() function would first try to read the master
key stash as a keytab file using krb5_kt_get_entry() and if that fails
it would fall back to using the current stash code to treat the stash
file as an old format stash file. Note that this function already has a
kvno arg that can be used for input and output.

The krb5_def_store_mkey() interface would be modified to write a keytab
and to accept an optional KVNO argument. It would need to deal with
existing old stash format files so the code would test to see if the
stash file existed and was non-0 size and if so, would first try reading
it as a keytab. If the stash file is determined to be a keytab by a
successful call to krb5_kt_get_entry() and the principal name is
verified to be correct then krb5_kt_add_entry() would be called to add
the new masterkey to the stash file.

If krb5_kt_get_entry() returned an error then the stash file would be
truncated to 0 bytes and then krb5_kt_add_entry() would be called to add
the masterkey entry. If the stash file did not exist or was 0 bytes in
size then krb5_kt_add_entry() would be called directly. The reason for
detecting and an existing old format stash file is to allow
krb5_def_store_mkey() the ability to store > 1 masterkey. Since
krb5_kt_add_entry() always appends to a keytab care must be taken to
ensure the existing stash file is a keytab and not the old format stash.

Callers of krb5_def_store_mkey() would need to be modified to deal with
the new KVNO argument. If a user specified KVNO was passed in and a key
with that KVNO existed in the keytab, an error would be returned
otherwise a new key with that KVNO would be added to the keytab. If a
KVNO was not specified, the current behavior whose KVNO would either be
0 if no keys exist in the keytab or would be one greater than the
largest KVNO found in the keytab.

The kdb5_util interface would be modified to allow the user to specify
the KVNO. The code will return an error if kdb5_util attemps to add a
key with a user specified KVNO to the masterkey keytab and a key with
that same KVNO already exists in the keytab. At that point the user
would either to use ktutil at that point to remove the existing key,
specify a different KVNO, or just remove the keytab file and rerun the
kdb5_util command.

Note the default file name convention currently used for stash files
will be used for masterkey keytab files. One implication of this is
that once an admin overwrites an existing old format stash file with the
new keytab format there is no going back to the old format as kdb5_util
will not support creation of the old format.

=Tasks/milestones=

* project start. Apr 3, 2008
* project review. ~2 week
* Implementation. ~2 week
* test. ~1 week
* code review. ~1 week
* documentation. ~1 day

=Desired integration and release goals=

Integrate and test before 1.7 release.

=Testing plan=

Unit testing of stash file related functions will be performed to make
sure the krb5kdc, kadmind, kadmin, kadmin.local, kdb5_util, and ktutil
are able to access and administer the masterkey keytab file. Tests will
be done for these scenarios:

* An old format stash file exists. The krb5kdc and kadmind should be
able to read the masterkey. The kdb5_util stash and create commands
should be able to overwrite the stash file.

* No stash exists. kdb5_util should be able to create a masterkey
keytab stash.

* The daemons that require masterkey access will be tested to validate
the ability to read the masterkey in a keytab.

Regression testing will be running the tests in the MIT source tree that
test the function of the krb5kdc, kadmind, kadmin, kadmin.local,
kdb5_util, and ktutil.

==Review==

This section documents the review of the project according to [[Project policy]].
It is divided into multiple sections. First, approvals should be listed. To list an approval type
:<nowiki>#~~~~</nowiki>
on its own line.
The next section is for discussion. Use standard ''talk page''conventions. In particular, sign comments with
:<nowiki>--~~~~</nowiki>
and indent replies.

Members of Krbcore raising Blocking objections should preface their comment with <nowiki>{{project-block}}</nowiki>. The member who raised the objection should remove this markup when their objection is handled.

===Approvals===

===Discussion===

Project policy

2008-04-03T23:44:04Z

Wfiveash:

{{policy}}

The '''Project Policy''' describes how members of the community propose to make changes in MIT Kerberos. A project is a proposal to add new functionality or to change existing functionality in MIT Kerberos. Projects are reviewed by the community before the required changes can be integrated into MIT Kerberos. This review provides the community an opportunity to suggest improvements to the project and to confirm that the community believes that implementing the project would be a good idea.

==When are projects needed?==

Small changes and relatively simple bug fixes do not require a project. The project process is designed to provide sufficient community review. If a change is simple enough and uncontroversial enough then the change can be made without going through this process. If members of the development community,especially members of [[Krbcore]], wish to review the change then it should go through a project process. If a change is committed outside of a project and objections are raised, then any member of Krbcore may revert the change until a project is approved.

The following always require the project process to be invoked:
# Introduction of any public [[API]]s
# Changes in an API or the [[ABI]]. Such changes are rarely approved
# Significant user interface changes such as the introduction of a new dialogue .
# Introduction of configuration file variables or documented registry keys

==Proposing a project==

To propose a project, create a new page under [[Projects]]. For example a project to create a new administration protocol might be called "Projects/new administration protocol".
At the beginning of that page include the following:
<blockquote>
<nowiki>{{project-early}}
</nowiki></blockquote>
This will include the [[Template:project-early|early project template]] which indicates that the project is being fleshed out by its supporters and is not yet under consideration for approval. Note, to create a page enter the page name ("Projects/new administration protocol" for example) in the wikik search box on left and click on the Go button.

The project proposal page should include the following elements:
* A description of the desired change in functionality
* Any functional requirements that must be met for the project to be successful
* A design for how the desired functionality will be implemented
* A breakdown of tasks or milestones to judge progress of the project
* Screenshots or other proposed user interface descriptions
* Documentation and sample code for any APIs that are proposed
* Dependencies on other projects
* Information on desired integration and release goals
* Testing plan

===User Interface===

It is expected that screenshots describing any proposed user interface will be included in any project that describes new interfaces. Discussion of customer study groups that have evaluated the new interface or other information to validate the interface will help support the project.

===Documenting proposed APIs===
See [[Documenting APIs]] for current recommendations on how to document APIs that are introduced in a project. Typically, the community will expect sample code to be included describing the use of APIs that are introduced.

==Which release does a project go in==

Unless a project mentions it is targeting a specific release, then the project will be included in the next release [[Release branches|branched]] off the [[trunk]] after the project is checked in.

Typically the goals of a given release are set during a release planning process at the beginning of that release process. It is unusual to include additional projects in a release after the planning has concluded. A project may propose that it be included in a specific release after the goals for that release have been set, although absent a very convincing justification this is likely to result in blocking objections.

If a project is a goal for a given release, it will typically need to include milestones to judge its progress against the rest of the release. If the project is being managed by the consortium staff, then the consortium project tracking process will be used. For projects not being done by consortium staff, it is typical to establish coordination point milestones. See [[Meeting release goals]] for information on how these milestones are used once projects are approved.

==Submitting a project for review==

Except in cases where prompt action is required, projects require a two week review cycle. Projects require at least one yes vote from a member of Krbcore who has not been a primary proponent of the project to be approved and no blocking objections. Proponents of the project should work with members of the community to address suggestions that are raised even if these suggestions are not blocking objections. If discussion of significant issues is ongoing when the review period extends then approval should be delayed until the discussion concludes.

To start the review period :
# Replace <nowiki>{{project-early}} with {{project-review|end_of_review_date}}</nowiki>
# Add <nowiki>{{subst:project-vote}}</nowiki> at the bottom of the project page.
# Send mail to krbdev@mit.edu including:
##The URI to the project page
##The end of the review period
##Cut and paste the description of the project from the project page into the review.

==That's a good start==

Often the result of a review will be that what is written so far is good enough that the community wants to explore the project, but checkpoints or '''review gates''' are required. Examples of such gates include things like requesting review of design of a particular part of the system, requesting review of APIs that are designed in the future, or interactions with some part of the system. Particularly when some of the recommended information is not included in the original project proposal, a review gate may be requested. When the information to be reviewed is available, another project review should be conducted. There are no specific details on how to document this review other than that the <nowiki>{{project-review}}</nowiki> template should be used so that the project is categorized as under review.

== Project life cycle changes==

===Approving a project===

If the project review concludes successfully then:
# Replace <nowiki>{{project-review}} with {{project-approved}}</nowiki>.
#Add a ''Current status'' section at the bottom of the project page to track updates
# Send mail to krbdev@mit.edu noting that the project is approved.
# If the project is targeted for a specific release add <nowiki>{{project-target|release_name}}</nowiki> below the project-approved target.

===Marking a project as completed===

Replace <nowiki>{{project-approved}}</nowiki> with <nowiki>{{project-completed}}</nowiki>. If the release including the project has shipped, replace <nowiki>{{project-target}} with {{project-release|release_name}}</nowiki>

===Updating the scope or design of the project===

Any significant updates to the project design or scope should be sent to krbdev@mit.edu. Comments should be addressed; if blocking objections are raised then they must be addressed.

Projects/Masterkey Keytab Stash

2008-04-03T23:43:27Z

Wfiveash: New page: {{project-early}} =Desired changes= The point of this small project is to change the format of the master key stash file to that of a keytab type file. This will allow the master key's ...

{{project-early}}

=Desired changes=

The point of this small project is to change the format of the master
key stash file to that of a keytab type file. This will allow the
master key's KVNO to be stored along with its enctype and key data which
in turn will enable an efficient implementation of master key updating.

=Functional Requirements=

The KDC must be able to access the most recent master key in the
masterkey keytab given a principal name and also retrieve a master key
based on a given principal name and a KVNO and or enctype. If the
masterkey is stored in the old stash file format then the KDC will be
backwards compatible and still be able to access the masterkey.

The utilities (kdb5_util, kdb_ldap_util, ktutil) must be able to read
and write to a masterkey keytab.

=Design of implementation=

The krb5_def_store_mkey() and krb5_db_def_fetch_mkey() functions would
be modified to use the keytab functions found in libkrb5.

The krb5_db_def_fetch_mkey() function would first try to read the master
key stash as a keytab file using krb5_kt_get_entry() and if that fails
it would fall back to using the current stash code to treat the stash
file as an old format stash file. Note that this function already has a
kvno arg that can be used for input and output.

The krb5_def_store_mkey() interface would be modified to write a keytab
and to accept an optional KVNO argument. It would need to deal with
existing old stash format files so the code would test to see if the
stash file existed and was non-0 size and if so, would first try reading
it as a keytab. If the stash file is determined to be a keytab by a
successful call to krb5_kt_get_entry() and the principal name is
verified to be correct then krb5_kt_add_entry() would be called to add
the new masterkey to the stash file.

If krb5_kt_get_entry() returned an error then the stash file would be
truncated to 0 bytes and then krb5_kt_add_entry() would be called to add
the masterkey entry. If the stash file did not exist or was 0 bytes in
size then krb5_kt_add_entry() would be called directly. The reason for
detecting and an existing old format stash file is to allow
krb5_def_store_mkey() the ability to store > 1 masterkey. Since
krb5_kt_add_entry() always appends to a keytab care must be taken to
ensure the existing stash file is a keytab and not the old format stash.

Callers of krb5_def_store_mkey() would need to be modified to deal with
the new KVNO argument. If a user specified KVNO was passed in and a key
with that KVNO existed in the keytab, an error would be returned
otherwise a new key with that KVNO would be added to the keytab. If a
KVNO was not specified, the current behavior whose KVNO would either be
0 if no keys exist in the keytab or would be one greater than the
largest KVNO found in the keytab.

The kdb5_util interface would be modified to allow the user to specify
the KVNO. The code will return an error if kdb5_util attemps to add a
key with a user specified KVNO to the masterkey keytab and a key with
that same KVNO already exists in the keytab. At that point the user
would either to use ktutil at that point to remove the existing key,
specify a different KVNO, or just remove the keytab file and rerun the
kdb5_util command.

Note the default file name convention currently used for stash files
will be used for masterkey keytab files. One implication of this is
that once an admin overwrites an existing old format stash file with the
new keytab format there is no going back to the old format as kdb5_util
will not support creation of the old format.

=Tasks/milestones=

* project start. Apr 3, 2008
* project review. ~2 week
* Implementation. ~2 week
* test. ~1 week
* code review. ~1 week
* documentation. ~1 day

=Desired integration and release goals=

Integrate and test before 1.7 release.

=Testing plan=

Unit testing of stash file related functions will be performed to make
sure the krb5kdc, kadmind, kadmin, kadmin.local, kdb5_util, and ktutil
are able to access and administer the masterkey keytab file. Tests will
be done for these scenarios:

* An old format stash file exists. The krb5kdc and kadmind should be
able to read the masterkey. The kdb5_util stash and create commands
should be able to overwrite the stash file.

* No stash exists. kdb5_util should be able to create a masterkey
keytab stash.

* The daemons that require masterkey access will be tested to validate
the ability to read the masterkey in a keytab.

Regression testing will be running the tests in the MIT source tree that
test the function of the krb5kdc, kadmind, kadmin, kadmin.local,
kdb5_util, and ktutil.

Talk:Project policy

2008-03-31T19:34:07Z

Wfiveash: New page: I don't see a link from the project policy on the k5wiki to code change/integration policy. So I do not know if a code review is necessary and what sort of testing is expected.

I don't see a link from the project policy on the k5wiki to code change/integration policy. So I do not know if a code review is necessary and what sort of testing is expected.

Project policy

2008-03-31T19:33:29Z

Wfiveash:

{{policy}}

The '''Project Policy''' describes how members of the community propose to make changes in MIT Kerberos. A project is a proposal to add new functionality or to change existing functionality in MIT Kerberos. Projects are reviewed by the community before the required changes can be integrated into MIT Kerberos. This review provides the community an opportunity to suggest improvements to the project and to confirm that the community believes that implementing the project would be a good idea.

==When are projects needed?==

Small changes and relatively simple bug fixes do not require a project. The project process is designed to provide sufficient community review. If a change is simple enough and uncontroversial enough then the change can be made without going through this process. If members of the development community,especially members of [[Krbcore]], wish to review the change then it should go through a project process. If a change is committed outside of a project and objections are raised, then any member of Krbcore may revert the change until a project is approved.

The following always require the project process to be invoked:
# Introduction of any public [[API]]s
# Changes in an API or the [[ABI]]. Such changes are rarely approved
# Significant user interface changes such as the introduction of a new dialogue .
# Introduction of configuration file variables or documented registry keys

==Proposing a project==

To propose a project, create a new page under [[Projects]]. For example a project to create a new administration protocol might be called "Projects/new administration protocol".
At the beginning of that page include the following:
<blockquote>
<nowiki>{{project-early}}
</nowiki></blockquote>
This will include the [[Template:project-early|early project template]] which indicates that the project is being fleshed out by its supporters and is not yet under consideration for approval. Note, to create a page enter the page name ("Projects/new administration protocol" for example) in the wikik search box on left and click on the Search button.

The project proposal page should include the following elements:
* A description of the desired change in functionality
* Any functional requirements that must be met for the project to be successful
* A design for how the desired functionality will be implemented
* A breakdown of tasks or milestones to judge progress of the project
* Screenshots or other proposed user interface descriptions
* Documentation and sample code for any APIs that are proposed
* Dependencies on other projects
* Information on desired integration and release goals
* Testing plan

===User Interface===

It is expected that screenshots describing any proposed user interface will be included in any project that describes new interfaces. Discussion of customer study groups that have evaluated the new interface or other information to validate the interface will help support the project.

===Documenting proposed APIs===
See [[Documenting APIs]] for current recommendations on how to document APIs that are introduced in a project. Typically, the community will expect sample code to be included describing the use of APIs that are introduced.

==Which release does a project go in==

Unless a project mentions it is targeting a specific release, then the project will be included in the next release [[Release branches|branched]] off the [[trunk]] after the project is checked in.

Typically the goals of a given release are set during a release planning process at the beginning of that release process. It is unusual to include additional projects in a release after the planning has concluded. A project may propose that it be included in a specific release after the goals for that release have been set, although absent a very convincing justification this is likely to result in blocking objections.

If a project is a goal for a given release, it will typically need to include milestones to judge its progress against the rest of the release. If the project is being managed by the consortium staff, then the consortium project tracking process will be used. For projects not being done by consortium staff, it is typical to establish coordination point milestones. See [[Meeting release goals]] for information on how these milestones are used once projects are approved.

==Submitting a project for review==

Except in cases where prompt action is required, projects require a two week review cycle. Projects require at least one yes vote from a member of Krbcore who has not been a primary proponent of the project to be approved and no blocking objections. Proponents of the project should work with members of the community to address suggestions that are raised even if these suggestions are not blocking objections. If discussion of significant issues is ongoing when the review period extends then approval should be delayed until the discussion concludes.

To start the review period :
# Replace <nowiki>{{project-early}} with {{project-review|end_of_review_date}}</nowiki>
# Add <nowiki>{{subst:project-vote}}</nowiki> at the bottom of the project page.
# Send mail to krbdev@mit.edu including:
##The URI to the project page
##The end of the review period
##Cut and paste the description of the project from the project page into the review.

==That's a good start==

Often the result of a review will be that what is written so far is good enough that the community wants to explore the project, but checkpoints or '''review gates''' are required. Examples of such gates include things like requesting review of design of a particular part of the system, requesting review of APIs that are designed in the future, or interactions with some part of the system. Particularly when some of the recommended information is not included in the original project proposal, a review gate may be requested. When the information to be reviewed is available, another project review should be conducted. There are no specific details on how to document this review other than that the <nowiki>{{project-review}}</nowiki> template should be used so that the project is categorized as under review.

== Project life cycle changes==

===Approving a project===

If the project review concludes successfully then:
# Replace <nowiki>{{project-review}} with {{project-approved}}</nowiki>.
#Add a ''Current status'' section at the bottom of the project page to track updates
# Send mail to krbdev@mit.edu noting that the project is approved.
# If the project is targeted for a specific release add <nowiki>{{project-target|release_name}}</nowiki> below the project-approved target.

===Marking a project as completed===

Replace <nowiki>{{project-approved}}</nowiki> with <nowiki>{{project-completed}}</nowiki>. If the release including the project has shipped, replace <nowiki>{{project-target}} with {{project-release|release_name}}</nowiki>

===Updating the scope or design of the project===

Any significant updates to the project design or scope should be sent to krbdev@mit.edu. Comments should be addressed; if blocking objections are raised then they must be addressed.

Talk:Projects

2008-03-31T19:27:28Z

Wfiveash: New page: The Projects page should list the various consortium projects. The current list of Project policy and Category:Projects is a bit confusing and indirect.

The Projects page should list the various consortium projects. The current list of Project policy and Category:Projects is a bit confusing and indirect.