From e95f9f6875f4cbcae60fe96696eb83a6972bbf26 Mon Sep 17 00:00:00 2001 From: Ben Kaduk Date: Mon, 15 Oct 2012 14:39:15 -0400 Subject: Massive reST content rename All of rst_source/ is now just in doc/. The krb_ prefix is stripped from the document sub-directories. rst_tools are now just tools. The section headers of kadmind, krb5kdc, and sserver match as conflict markers. bigredbutton: whitespace ticket: 7409 --- doc/README | 69 ++ doc/_static/kerb.css | 150 +++ doc/_templates/layout.html | 86 ++ doc/admins/admin_commands/index.rst | 17 + doc/admins/admin_commands/k5srvutil.rst | 57 + doc/admins/admin_commands/kadmin_local.rst | 883 +++++++++++++++ doc/admins/admin_commands/kadmind.rst | 130 +++ doc/admins/admin_commands/kdb5_ldap_util.rst | 478 +++++++++ doc/admins/admin_commands/kdb5_util.rst | 355 +++++++ doc/admins/admin_commands/kprop.rst | 60 ++ doc/admins/admin_commands/kpropd.rst | 123 +++ doc/admins/admin_commands/kproplog.rst | 87 ++ doc/admins/admin_commands/krb5kdc.rst | 142 +++ doc/admins/admin_commands/ktutil.rst | 133 +++ doc/admins/admin_commands/sserver.rst | 121 +++ doc/admins/advanced/index.rst | 10 + doc/admins/advanced/ldapbackend.rst | 143 +++ doc/admins/advanced/retiring-des.rst | 129 +++ doc/admins/appl_servers.rst | 147 +++ doc/admins/backup_host.rst | 34 + doc/admins/conf_files/index.rst | 9 + doc/admins/conf_files/kadm5_acl.rst | 136 +++ doc/admins/conf_files/kdc_conf.rst | 711 +++++++++++++ doc/admins/conf_files/krb5_conf.rst | 1056 ++++++++++++++++++ doc/admins/conf_ldap.rst | 158 +++ doc/admins/database.rst | 785 ++++++++++++++ doc/admins/env_variables.rst | 45 + doc/admins/host_config.rst | 110 ++ doc/admins/index.rst | 24 + doc/admins/install.rst | 21 + doc/admins/install_appl_srv.rst | 83 ++ doc/admins/install_clients.rst | 57 + doc/admins/install_kdc.rst | 525 +++++++++ doc/admins/realm_config.rst | 217 ++++ doc/admins/troubleshoot.rst | 53 + doc/admins/various_envs.rst | 33 + doc/appldev/gssapi.rst | 220 ++++ doc/appldev/h5l_mit_apidiff.rst | 28 + doc/appldev/index.rst | 15 + doc/appldev/init_creds.rst | 59 + doc/appldev/princ_handle.rst | 79 ++ doc/appldev/refs/api/index.rst | 397 +++++++ doc/appldev/refs/index.rst | 10 + doc/appldev/refs/macros/index.rst | 355 +++++++ doc/appldev/refs/types/index.rst | 102 ++ doc/appldev/refs/types/krb5_int32.rst | 12 + doc/appldev/refs/types/krb5_ui_4.rst | 12 + doc/basic/date_format.rst | 138 +++ doc/basic/index.rst | 13 + doc/basic/keytab_def.rst | 61 ++ doc/basic/rcache_def.rst | 97 ++ doc/basic/stash_file_def.rst | 23 + doc/build/directory_org.rst | 76 ++ doc/build/doing_build.rst | 172 +++ doc/build/index.rst | 60 ++ doc/build/options2configure.rst | 408 +++++++ doc/build/osconf.rst | 26 + doc/build/test_cov.rst | 31 + doc/conf.py | 280 +++++ doc/index.rst | 22 + doc/mitK5defaults.rst | 76 ++ doc/mitK5features.rst | 140 +++ doc/mitK5license.rst | 6 + doc/notice.rst | 1124 ++++++++++++++++++++ doc/plugindev/ccselect.rst | 26 + doc/plugindev/clpreauth.rst | 53 + doc/plugindev/general.rst | 98 ++ doc/plugindev/index.rst | 32 + doc/plugindev/internal.rst | 32 + doc/plugindev/kadm5_hook.rst | 24 + doc/plugindev/kdcpreauth.rst | 61 ++ doc/plugindev/locate.rst | 32 + doc/plugindev/profile.rst | 92 ++ doc/plugindev/pwqual.rst | 23 + doc/relay/build_this.rst | 81 ++ doc/relay/index.rst | 9 + doc/relay/philosophy.rst | 28 + doc/resources.rst | 55 + doc/rst_source/README | 69 -- doc/rst_source/_static/kerb.css | 150 --- doc/rst_source/_templates/layout.html | 86 -- doc/rst_source/conf.py | 280 ----- doc/rst_source/index.rst | 22 - doc/rst_source/krb_admins/admin_commands/index.rst | 17 - .../krb_admins/admin_commands/k5srvutil.rst | 57 - .../krb_admins/admin_commands/kadmin_local.rst | 883 --------------- .../krb_admins/admin_commands/kadmind.rst | 130 --- .../krb_admins/admin_commands/kdb5_ldap_util.rst | 478 --------- .../krb_admins/admin_commands/kdb5_util.rst | 355 ------- doc/rst_source/krb_admins/admin_commands/kprop.rst | 60 -- .../krb_admins/admin_commands/kpropd.rst | 123 --- .../krb_admins/admin_commands/kproplog.rst | 87 -- .../krb_admins/admin_commands/krb5kdc.rst | 142 --- .../krb_admins/admin_commands/ktutil.rst | 133 --- .../krb_admins/admin_commands/sserver.rst | 121 --- doc/rst_source/krb_admins/advanced/index.rst | 10 - doc/rst_source/krb_admins/advanced/ldapbackend.rst | 143 --- .../krb_admins/advanced/retiring-des.rst | 129 --- doc/rst_source/krb_admins/appl_servers.rst | 147 --- doc/rst_source/krb_admins/backup_host.rst | 34 - doc/rst_source/krb_admins/conf_files/index.rst | 9 - doc/rst_source/krb_admins/conf_files/kadm5_acl.rst | 136 --- doc/rst_source/krb_admins/conf_files/kdc_conf.rst | 711 ------------- doc/rst_source/krb_admins/conf_files/krb5_conf.rst | 1056 ------------------ doc/rst_source/krb_admins/conf_ldap.rst | 158 --- doc/rst_source/krb_admins/database.rst | 785 -------------- doc/rst_source/krb_admins/env_variables.rst | 45 - doc/rst_source/krb_admins/host_config.rst | 110 -- doc/rst_source/krb_admins/index.rst | 24 - doc/rst_source/krb_admins/install.rst | 21 - doc/rst_source/krb_admins/install_appl_srv.rst | 83 -- doc/rst_source/krb_admins/install_clients.rst | 57 - doc/rst_source/krb_admins/install_kdc.rst | 525 --------- doc/rst_source/krb_admins/realm_config.rst | 217 ---- doc/rst_source/krb_admins/troubleshoot.rst | 53 - doc/rst_source/krb_admins/various_envs.rst | 33 - doc/rst_source/krb_appldev/gssapi.rst | 220 ---- doc/rst_source/krb_appldev/h5l_mit_apidiff.rst | 28 - doc/rst_source/krb_appldev/index.rst | 15 - doc/rst_source/krb_appldev/init_creds.rst | 59 - doc/rst_source/krb_appldev/princ_handle.rst | 79 -- doc/rst_source/krb_appldev/refs/api/index.rst | 397 ------- doc/rst_source/krb_appldev/refs/index.rst | 10 - doc/rst_source/krb_appldev/refs/macros/index.rst | 355 ------- doc/rst_source/krb_appldev/refs/types/index.rst | 102 -- .../krb_appldev/refs/types/krb5_int32.rst | 12 - .../krb_appldev/refs/types/krb5_ui_4.rst | 12 - doc/rst_source/krb_basic/date_format.rst | 138 --- doc/rst_source/krb_basic/index.rst | 13 - doc/rst_source/krb_basic/keytab_def.rst | 61 -- doc/rst_source/krb_basic/rcache_def.rst | 97 -- doc/rst_source/krb_basic/stash_file_def.rst | 23 - doc/rst_source/krb_build/directory_org.rst | 76 -- doc/rst_source/krb_build/doing_build.rst | 172 --- doc/rst_source/krb_build/index.rst | 60 -- doc/rst_source/krb_build/options2configure.rst | 408 ------- doc/rst_source/krb_build/osconf.rst | 26 - doc/rst_source/krb_build/test_cov.rst | 31 - doc/rst_source/krb_plugindev/ccselect.rst | 26 - doc/rst_source/krb_plugindev/clpreauth.rst | 53 - doc/rst_source/krb_plugindev/general.rst | 98 -- doc/rst_source/krb_plugindev/index.rst | 32 - doc/rst_source/krb_plugindev/internal.rst | 32 - doc/rst_source/krb_plugindev/kadm5_hook.rst | 24 - doc/rst_source/krb_plugindev/kdcpreauth.rst | 61 -- doc/rst_source/krb_plugindev/locate.rst | 32 - doc/rst_source/krb_plugindev/profile.rst | 92 -- doc/rst_source/krb_plugindev/pwqual.rst | 23 - doc/rst_source/krb_users/index.rst | 10 - doc/rst_source/krb_users/pwd_mgmt.rst | 106 -- doc/rst_source/krb_users/tkt_mgmt.rst | 312 ------ doc/rst_source/krb_users/user_commands/index.rst | 16 - .../krb_users/user_commands/kdestroy.rst | 77 -- doc/rst_source/krb_users/user_commands/kinit.rst | 211 ---- doc/rst_source/krb_users/user_commands/klist.rst | 135 --- doc/rst_source/krb_users/user_commands/kpasswd.rst | 39 - doc/rst_source/krb_users/user_commands/ksu.rst | 397 ------- doc/rst_source/krb_users/user_commands/kswitch.rst | 56 - doc/rst_source/krb_users/user_commands/kvno.rst | 86 -- doc/rst_source/krb_users/user_commands/sclient.rst | 24 - doc/rst_source/krb_users/user_config/index.rst | 12 - .../krb_users/user_config/k5identity.rst | 66 -- doc/rst_source/krb_users/user_config/k5login.rst | 53 - doc/rst_source/mitK5defaults.rst | 76 -- doc/rst_source/mitK5features.rst | 140 --- doc/rst_source/mitK5license.rst | 6 - doc/rst_source/notice.rst | 1124 -------------------- doc/rst_source/relay/build_this.rst | 81 -- doc/rst_source/relay/index.rst | 9 - doc/rst_source/relay/philosophy.rst | 28 - doc/rst_source/resources.rst | 55 - doc/rst_source/txt_conf.py | 88 -- doc/rst_tools/README | 65 -- doc/rst_tools/define_document.tmpl | 27 - doc/rst_tools/docmodel.py | 252 ----- doc/rst_tools/doxy.py | 64 -- doc/rst_tools/doxybuilder_funcs.py | 595 ----------- doc/rst_tools/doxybuilder_types.py | 370 ------- doc/rst_tools/func_document.tmpl | 99 -- doc/rst_tools/type_document.tmpl | 43 - doc/tools/README | 65 ++ doc/tools/define_document.tmpl | 27 + doc/tools/docmodel.py | 252 +++++ doc/tools/doxy.py | 64 ++ doc/tools/doxybuilder_funcs.py | 595 +++++++++++ doc/tools/doxybuilder_types.py | 370 +++++++ doc/tools/func_document.tmpl | 99 ++ doc/tools/type_document.tmpl | 43 + doc/txt_conf.py | 88 ++ doc/users/index.rst | 10 + doc/users/pwd_mgmt.rst | 106 ++ doc/users/tkt_mgmt.rst | 312 ++++++ doc/users/user_commands/index.rst | 16 + doc/users/user_commands/kdestroy.rst | 77 ++ doc/users/user_commands/kinit.rst | 211 ++++ doc/users/user_commands/klist.rst | 135 +++ doc/users/user_commands/kpasswd.rst | 39 + doc/users/user_commands/ksu.rst | 397 +++++++ doc/users/user_commands/kswitch.rst | 56 + doc/users/user_commands/kvno.rst | 86 ++ doc/users/user_commands/sclient.rst | 24 + doc/users/user_config/index.rst | 12 + doc/users/user_config/k5identity.rst | 66 ++ doc/users/user_config/k5login.rst | 53 + 204 files changed, 15268 insertions(+), 15268 deletions(-) create mode 100644 doc/README create mode 100644 doc/_static/kerb.css create mode 100644 doc/_templates/layout.html create mode 100644 doc/admins/admin_commands/index.rst create mode 100644 doc/admins/admin_commands/k5srvutil.rst create mode 100644 doc/admins/admin_commands/kadmin_local.rst create mode 100644 doc/admins/admin_commands/kadmind.rst create mode 100644 doc/admins/admin_commands/kdb5_ldap_util.rst create mode 100644 doc/admins/admin_commands/kdb5_util.rst create mode 100644 doc/admins/admin_commands/kprop.rst create mode 100644 doc/admins/admin_commands/kpropd.rst create mode 100644 doc/admins/admin_commands/kproplog.rst create mode 100644 doc/admins/admin_commands/krb5kdc.rst create mode 100644 doc/admins/admin_commands/ktutil.rst create mode 100644 doc/admins/admin_commands/sserver.rst create mode 100644 doc/admins/advanced/index.rst create mode 100644 doc/admins/advanced/ldapbackend.rst create mode 100644 doc/admins/advanced/retiring-des.rst create mode 100644 doc/admins/appl_servers.rst create mode 100644 doc/admins/backup_host.rst create mode 100644 doc/admins/conf_files/index.rst create mode 100644 doc/admins/conf_files/kadm5_acl.rst create mode 100644 doc/admins/conf_files/kdc_conf.rst create mode 100644 doc/admins/conf_files/krb5_conf.rst create mode 100644 doc/admins/conf_ldap.rst create mode 100644 doc/admins/database.rst create mode 100644 doc/admins/env_variables.rst create mode 100644 doc/admins/host_config.rst create mode 100644 doc/admins/index.rst create mode 100644 doc/admins/install.rst create mode 100644 doc/admins/install_appl_srv.rst create mode 100644 doc/admins/install_clients.rst create mode 100644 doc/admins/install_kdc.rst create mode 100644 doc/admins/realm_config.rst create mode 100644 doc/admins/troubleshoot.rst create mode 100644 doc/admins/various_envs.rst create mode 100644 doc/appldev/gssapi.rst create mode 100644 doc/appldev/h5l_mit_apidiff.rst create mode 100644 doc/appldev/index.rst create mode 100644 doc/appldev/init_creds.rst create mode 100644 doc/appldev/princ_handle.rst create mode 100644 doc/appldev/refs/api/index.rst create mode 100644 doc/appldev/refs/index.rst create mode 100644 doc/appldev/refs/macros/index.rst create mode 100644 doc/appldev/refs/types/index.rst create mode 100644 doc/appldev/refs/types/krb5_int32.rst create mode 100644 doc/appldev/refs/types/krb5_ui_4.rst create mode 100644 doc/basic/date_format.rst create mode 100644 doc/basic/index.rst create mode 100644 doc/basic/keytab_def.rst create mode 100644 doc/basic/rcache_def.rst create mode 100644 doc/basic/stash_file_def.rst create mode 100644 doc/build/directory_org.rst create mode 100644 doc/build/doing_build.rst create mode 100644 doc/build/index.rst create mode 100644 doc/build/options2configure.rst create mode 100644 doc/build/osconf.rst create mode 100644 doc/build/test_cov.rst create mode 100644 doc/conf.py create mode 100644 doc/index.rst create mode 100644 doc/mitK5defaults.rst create mode 100644 doc/mitK5features.rst create mode 100644 doc/mitK5license.rst create mode 100644 doc/notice.rst create mode 100644 doc/plugindev/ccselect.rst create mode 100644 doc/plugindev/clpreauth.rst create mode 100644 doc/plugindev/general.rst create mode 100644 doc/plugindev/index.rst create mode 100644 doc/plugindev/internal.rst create mode 100644 doc/plugindev/kadm5_hook.rst create mode 100644 doc/plugindev/kdcpreauth.rst create mode 100644 doc/plugindev/locate.rst create mode 100644 doc/plugindev/profile.rst create mode 100644 doc/plugindev/pwqual.rst create mode 100644 doc/relay/build_this.rst create mode 100644 doc/relay/index.rst create mode 100644 doc/relay/philosophy.rst create mode 100644 doc/resources.rst delete mode 100644 doc/rst_source/README delete mode 100644 doc/rst_source/_static/kerb.css delete mode 100644 doc/rst_source/_templates/layout.html delete mode 100644 doc/rst_source/conf.py delete mode 100644 doc/rst_source/index.rst delete mode 100644 doc/rst_source/krb_admins/admin_commands/index.rst delete mode 100644 doc/rst_source/krb_admins/admin_commands/k5srvutil.rst delete mode 100644 doc/rst_source/krb_admins/admin_commands/kadmin_local.rst delete mode 100644 doc/rst_source/krb_admins/admin_commands/kadmind.rst delete mode 100644 doc/rst_source/krb_admins/admin_commands/kdb5_ldap_util.rst delete mode 100644 doc/rst_source/krb_admins/admin_commands/kdb5_util.rst delete mode 100644 doc/rst_source/krb_admins/admin_commands/kprop.rst delete mode 100644 doc/rst_source/krb_admins/admin_commands/kpropd.rst delete mode 100644 doc/rst_source/krb_admins/admin_commands/kproplog.rst delete mode 100644 doc/rst_source/krb_admins/admin_commands/krb5kdc.rst delete mode 100644 doc/rst_source/krb_admins/admin_commands/ktutil.rst delete mode 100644 doc/rst_source/krb_admins/admin_commands/sserver.rst delete mode 100644 doc/rst_source/krb_admins/advanced/index.rst delete mode 100644 doc/rst_source/krb_admins/advanced/ldapbackend.rst delete mode 100644 doc/rst_source/krb_admins/advanced/retiring-des.rst delete mode 100644 doc/rst_source/krb_admins/appl_servers.rst delete mode 100644 doc/rst_source/krb_admins/backup_host.rst delete mode 100644 doc/rst_source/krb_admins/conf_files/index.rst delete mode 100644 doc/rst_source/krb_admins/conf_files/kadm5_acl.rst delete mode 100644 doc/rst_source/krb_admins/conf_files/kdc_conf.rst delete mode 100644 doc/rst_source/krb_admins/conf_files/krb5_conf.rst delete mode 100644 doc/rst_source/krb_admins/conf_ldap.rst delete mode 100644 doc/rst_source/krb_admins/database.rst delete mode 100644 doc/rst_source/krb_admins/env_variables.rst delete mode 100644 doc/rst_source/krb_admins/host_config.rst delete mode 100644 doc/rst_source/krb_admins/index.rst delete mode 100644 doc/rst_source/krb_admins/install.rst delete mode 100644 doc/rst_source/krb_admins/install_appl_srv.rst delete mode 100644 doc/rst_source/krb_admins/install_clients.rst delete mode 100644 doc/rst_source/krb_admins/install_kdc.rst delete mode 100644 doc/rst_source/krb_admins/realm_config.rst delete mode 100644 doc/rst_source/krb_admins/troubleshoot.rst delete mode 100644 doc/rst_source/krb_admins/various_envs.rst delete mode 100644 doc/rst_source/krb_appldev/gssapi.rst delete mode 100644 doc/rst_source/krb_appldev/h5l_mit_apidiff.rst delete mode 100644 doc/rst_source/krb_appldev/index.rst delete mode 100644 doc/rst_source/krb_appldev/init_creds.rst delete mode 100644 doc/rst_source/krb_appldev/princ_handle.rst delete mode 100644 doc/rst_source/krb_appldev/refs/api/index.rst delete mode 100644 doc/rst_source/krb_appldev/refs/index.rst delete mode 100644 doc/rst_source/krb_appldev/refs/macros/index.rst delete mode 100644 doc/rst_source/krb_appldev/refs/types/index.rst delete mode 100644 doc/rst_source/krb_appldev/refs/types/krb5_int32.rst delete mode 100644 doc/rst_source/krb_appldev/refs/types/krb5_ui_4.rst delete mode 100644 doc/rst_source/krb_basic/date_format.rst delete mode 100644 doc/rst_source/krb_basic/index.rst delete mode 100644 doc/rst_source/krb_basic/keytab_def.rst delete mode 100644 doc/rst_source/krb_basic/rcache_def.rst delete mode 100644 doc/rst_source/krb_basic/stash_file_def.rst delete mode 100644 doc/rst_source/krb_build/directory_org.rst delete mode 100644 doc/rst_source/krb_build/doing_build.rst delete mode 100644 doc/rst_source/krb_build/index.rst delete mode 100644 doc/rst_source/krb_build/options2configure.rst delete mode 100644 doc/rst_source/krb_build/osconf.rst delete mode 100644 doc/rst_source/krb_build/test_cov.rst delete mode 100644 doc/rst_source/krb_plugindev/ccselect.rst delete mode 100644 doc/rst_source/krb_plugindev/clpreauth.rst delete mode 100644 doc/rst_source/krb_plugindev/general.rst delete mode 100644 doc/rst_source/krb_plugindev/index.rst delete mode 100644 doc/rst_source/krb_plugindev/internal.rst delete mode 100644 doc/rst_source/krb_plugindev/kadm5_hook.rst delete mode 100644 doc/rst_source/krb_plugindev/kdcpreauth.rst delete mode 100644 doc/rst_source/krb_plugindev/locate.rst delete mode 100644 doc/rst_source/krb_plugindev/profile.rst delete mode 100644 doc/rst_source/krb_plugindev/pwqual.rst delete mode 100644 doc/rst_source/krb_users/index.rst delete mode 100644 doc/rst_source/krb_users/pwd_mgmt.rst delete mode 100644 doc/rst_source/krb_users/tkt_mgmt.rst delete mode 100644 doc/rst_source/krb_users/user_commands/index.rst delete mode 100644 doc/rst_source/krb_users/user_commands/kdestroy.rst delete mode 100644 doc/rst_source/krb_users/user_commands/kinit.rst delete mode 100644 doc/rst_source/krb_users/user_commands/klist.rst delete mode 100644 doc/rst_source/krb_users/user_commands/kpasswd.rst delete mode 100644 doc/rst_source/krb_users/user_commands/ksu.rst delete mode 100644 doc/rst_source/krb_users/user_commands/kswitch.rst delete mode 100644 doc/rst_source/krb_users/user_commands/kvno.rst delete mode 100644 doc/rst_source/krb_users/user_commands/sclient.rst delete mode 100644 doc/rst_source/krb_users/user_config/index.rst delete mode 100644 doc/rst_source/krb_users/user_config/k5identity.rst delete mode 100644 doc/rst_source/krb_users/user_config/k5login.rst delete mode 100644 doc/rst_source/mitK5defaults.rst delete mode 100644 doc/rst_source/mitK5features.rst delete mode 100644 doc/rst_source/mitK5license.rst delete mode 100644 doc/rst_source/notice.rst delete mode 100644 doc/rst_source/relay/build_this.rst delete mode 100644 doc/rst_source/relay/index.rst delete mode 100644 doc/rst_source/relay/philosophy.rst delete mode 100644 doc/rst_source/resources.rst delete mode 100644 doc/rst_source/txt_conf.py delete mode 100644 doc/rst_tools/README delete mode 100644 doc/rst_tools/define_document.tmpl delete mode 100644 doc/rst_tools/docmodel.py delete mode 100644 doc/rst_tools/doxy.py delete mode 100644 doc/rst_tools/doxybuilder_funcs.py delete mode 100644 doc/rst_tools/doxybuilder_types.py delete mode 100644 doc/rst_tools/func_document.tmpl delete mode 100644 doc/rst_tools/type_document.tmpl create mode 100644 doc/tools/README create mode 100644 doc/tools/define_document.tmpl create mode 100644 doc/tools/docmodel.py create mode 100644 doc/tools/doxy.py create mode 100644 doc/tools/doxybuilder_funcs.py create mode 100644 doc/tools/doxybuilder_types.py create mode 100644 doc/tools/func_document.tmpl create mode 100644 doc/tools/type_document.tmpl create mode 100644 doc/txt_conf.py create mode 100644 doc/users/index.rst create mode 100644 doc/users/pwd_mgmt.rst create mode 100644 doc/users/tkt_mgmt.rst create mode 100644 doc/users/user_commands/index.rst create mode 100644 doc/users/user_commands/kdestroy.rst create mode 100644 doc/users/user_commands/kinit.rst create mode 100644 doc/users/user_commands/klist.rst create mode 100644 doc/users/user_commands/kpasswd.rst create mode 100644 doc/users/user_commands/ksu.rst create mode 100644 doc/users/user_commands/kswitch.rst create mode 100644 doc/users/user_commands/kvno.rst create mode 100644 doc/users/user_commands/sclient.rst create mode 100644 doc/users/user_config/index.rst create mode 100644 doc/users/user_config/k5identity.rst create mode 100644 doc/users/user_config/k5login.rst diff --git a/doc/README b/doc/README new file mode 100644 index 000000000..8bb1c47cc --- /dev/null +++ b/doc/README @@ -0,0 +1,69 @@ +HTML +==== + +To build the documentation as HTML pages run: + +sphinx-build source_dir destination_dir + +where +source_dir is the source directory which includes configuration file conf.py and all source files; +destination_dir is the directory for the built documentation. + +Once completed, the newly generated HTML documentation can be viewed from the browser by pointing to destination_dir/index.html + + +MAN PAGES +========= + +Similarly, to build the documentation as man pages run: + +sphinx-build -b man source_dir destination_dir + +The list of manual pages to be built should be constructed under man_pages section on conf.py + + +CONVENTIONS +=========== + +We use the following conventions: + +* Use four-space indentation where indentation levels are arbitrary. + Do not use tabs anywhere. Avoid trailing whitespace at the end of + lines or files. + +* Fill lines to 70 columns (the emacs default) where lines can be + wrapped. + +* For section headers, use === underlines for page titles, --- for + sections, ~~~ for subsections, and ### for sub-subsections. Make + underlines exactly as long as titles. Do not include trailing + punctuation in section headers. Do not capitalize section headers + (except for the first word) except in source files intended to + generate man pages. + +* For bullet lists, use * for top-level bullets and - for sub-bullets. + Do not indent bullet or enumerated lists relative to the surrounding + text. + +* Use italics (*word*) for words representing variables or parameters. + Use boldface (**word**) for command options, subcommands of programs + like kadmin, and krb5.conf/kdc.conf parameter names. Use literal + text (``text``) for examples and multi-component pathnames. For + command names, single-component filenames, and krb5.conf/kdc.conf + section names, use references (like :ref:`kadmin(1)`) if introducing + them, or just use them unadorned otherwise. + +* In man pages for commands with subcommands, make a subsection for + each subcommand. Start the subcommand with an indented synopsis, + then follow with non-indented text describing the subcommand and its + options. See kadmin_local.rst for an example. + +* In man page synopses, put a newline in the RST source before each + option. Put all parts of the synopsis at the same indentation + level. Ideally we would want a hanging indent to the width of the + command or subcommand name, but RST doesn't support that. Use + boldface for literal text in the synopsis, italics for variable + text, and unadorned text for syntax symbols (such as square brackets + to indicate optional parameters). If immediately following one kind + of inline markup with another or putting inline markup next to + punctuation, you may need to use "\ " as a dummy separator. diff --git a/doc/_static/kerb.css b/doc/_static/kerb.css new file mode 100644 index 000000000..f28349662 --- /dev/null +++ b/doc/_static/kerb.css @@ -0,0 +1,150 @@ +/* + * kerb.css + * ~~~~~~~~~~~ + * + * Sphinx stylesheet -- modification to agogo theme. + * + */ +div.body { + padding-right: .5em; + text-align: left; + overflow-x: hidden; +} + +/* Page layout */ + +div.header, div.content, div.footer { + margin-left: auto; + margin-right: auto; +} + +div.header-wrapper { + background: white; + border-bottom: 3px solid #2e3436; + border-top: 13px solid #59121e; +} + +/* Header */ + +div.header { + padding-top: 10px; + padding-bottom: 10px; +} + +div.header h1 { + font-family: "Georgia", "Times New Roman", serif, black; + font-weight: normal; +} + +div.header div.right a { + color: #fcaf3e; + letter-spacing: .1em; + text-transform: lowercase; + float: right; +} + +/* Content */ + +div.document { + width: 80%; + float: left; + margin: 0; + background-color: white; + padding-top: 20px; + padding-bottom: 20px; +} + +div.document div.section h1 { + margin-bottom: 20px; + padding: 1px; + line-height: 130%; +} + +div.document div.section dl { + margin-top: 15px; + margin-bottom: 5px; + padding: 1px; + text-align: left; +} + +/* Sidebar */ + +div.sidebar { + float: right; + font-size: .9em; + width: 20%; + margin: 0; + padding: 0; + background-color: white; +} + +div.sidebar ul { + list-style-type: none; + margin-left: .5em; +} + +div.sidebar li.toctree-l1 a { + margin-left: .5em; +} + +div.sidebar li.toctree-l2 a { + margin-left: .5em; +} + +div.sidebar li.toctree-l3 a { + margin-left: .5em; +} + +div.sidebar li.toctree-l2.current a { + border-right: 2px solid #fcaf3e !important; +} + +div.sidebar li.toctree-l3.current a { + font-weight: bold; +} + +div.sidebar li.toctree-l4 a { + display: none; +} + +/* Other body styles */ + +dt:target, .highlighted { + background-color: #c1c1c1; +} + +/* Code displays */ + +pre { + overflow: auto; + overflow-y: hidden; +} + +td.linenos pre { + padding: 5px 0px; + border: 0; + background-color: transparent; + color: #aaa; +} + +/* ordered lists */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style-type: lower-roman; +} + +ol.upperroman { + list-style-type: upper-roman; +} diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html new file mode 100644 index 000000000..2cf03a18d --- /dev/null +++ b/doc/_templates/layout.html @@ -0,0 +1,86 @@ +{% extends "!layout.html" %} +{% set rellinks = [('search', 'Enter search criteria', 'C', 'Search')] + + rellinks + + [('index', 'Full Table of Contents', 'C', 'Contents')] %} +{% set css_files = css_files + ["_static/kerb.css"] %} + +{# Add a "feedback" button to the footer #} +{% macro feedback_rellinks() %} +
+
+
+ {%- for rellink in rellinks|reverse %} + {{ rellink[3] }} + {{ reldelim2 }} + {%- endfor %} + {%- block rootrellink %} + feedback + {%- endblock %} +
+
+
+{%- endmacro %} + +{% block footer %} {{ feedback_rellinks() }}{% endblock %} + +{% block header %} +
+
+ {% if logo %} + + {% endif %} + {% block headertitle %} +

{{ shorttitle|e }}

+ {% endblock %} +
+ {%- for rellink in rellinks|reverse %} + {{ rellink[3] }} + {{ reldelim2 }} + {%- endfor %} + feedback +
+

+
+{% endblock %} + +{%- block content %} +
+
+ {%- block sidebar2 %} {%- endblock %} + {%- block sidebar1 %} +
+

{{ _('On this page') }}

+ {{ toc }} +
+

{{ _('Table of contents') }}

+ {{ toctree(collapse=true, maxdepth=-1, titles_only=true) }} +
+

Full Table of Contents +

+

{{ _('Search') }}

+
+ + + + +
+
+ {%- endblock %} +
+ {%- block document %}{{ super() }}{%- endblock %} +
+
+
+
+{% endblock %} diff --git a/doc/admins/admin_commands/index.rst b/doc/admins/admin_commands/index.rst new file mode 100644 index 000000000..e8dc76524 --- /dev/null +++ b/doc/admins/admin_commands/index.rst @@ -0,0 +1,17 @@ +Administration programs +======================== + +.. toctree:: + :maxdepth: 1 + + kadmin_local.rst + kadmind.rst + kdb5_util.rst + kdb5_ldap_util.rst + krb5kdc.rst + kprop.rst + kpropd.rst + kproplog.rst + ktutil.rst + k5srvutil.rst + sserver.rst diff --git a/doc/admins/admin_commands/k5srvutil.rst b/doc/admins/admin_commands/k5srvutil.rst new file mode 100644 index 000000000..493c17653 --- /dev/null +++ b/doc/admins/admin_commands/k5srvutil.rst @@ -0,0 +1,57 @@ +.. _k5srvutil(1): + +k5srvutil +========= + +SYNOPSIS +-------- + +**k5srvutil** *operation* +[**-i**] +[**-f** *filename*] + +DESCRIPTION +----------- + +k5srvutil allows an administrator to list or change keys currently in +a keytab or to add new keys to the keytab. + +*operation* must be one of the following: + +**list** + Lists the keys in a keytab showing version number and principal + name. + +**change** + Uses the kadmin protocol to update the keys in the Kerberos + database to new randomly-generated keys, and updates the keys in + the keytab to match. If a key's version number doesn't match the + version number stored in the Kerberos server's database, then the + operation will fail. Old keys are retained in the keytab so that + existing tickets continue to work. If the **-i** flag is given, + k5srvutil will prompt for confirmation before changing each key. + If the **-k** option is given, the old and new keys will be + displayed. + +**delold** + Deletes keys that are not the most recent version from the keytab. + This operation should be used some time after a change operation + to remove old keys, after existing tickets issued for the service + have expired. If the **-i** flag is given, then k5srvutil will + prompt for confirmation for each principal. + +**delete** + Deletes particular keys in the keytab, interactively prompting for + each key. + +In all cases, the default keytab is used unless this is overridden by +the **-f** option. + +k5srvutil uses the :ref:`kadmin(1)` program to edit the keytab in +place. + + +SEE ALSO +-------- + +:ref:`kadmin(1)`, :ref:`ktutil(1)` diff --git a/doc/admins/admin_commands/kadmin_local.rst b/doc/admins/admin_commands/kadmin_local.rst new file mode 100644 index 000000000..396e25524 --- /dev/null +++ b/doc/admins/admin_commands/kadmin_local.rst @@ -0,0 +1,883 @@ +.. _kadmin(1): + +kadmin +====== + +SYNOPSIS +-------- + +.. _kadmin_synopsis: + +**kadmin** +[**-O**\|\ **-N**] +[**-r** *realm*] +[**-p** *principal*] +[**-q** *query*] +[[**-c** *cache_name*]\|[**-k** [**-t** *keytab*]]\|\ **-n**] +[**-w** *password*] +[**-s** *admin_server*\ [:*port*]] + +**kadmin.local** +[**-r** *realm*] +[**-p** *principal*] +[**-q** *query*] +[**-d** *dbname*] +[**-e** *enc*:*salt* ...] +[**-m**] +[**-x** *db_args*] + +.. _kadmin_synopsis_end: + + +DESCRIPTION +----------- + +kadmin and kadmin.local are command-line interfaces to the Kerberos V5 +administration system. They provide nearly identical functionalities; +the difference is that kadmin.local directly accesses the KDC +database, while kadmin performs operations using :ref:`kadmind(8)`. +Except as explicitly noted otherwise, this man page will use "kadmin" +to refer to both versions. kadmin provides for the maintenance of +Kerberos principals, password policies, and service key tables +(keytabs). + +The remote kadmin client uses Kerberos to authenticate to kadmind +using the service principal ``kadmin/ADMINHOST`` (where *ADMINHOST* is +the fully-qualified hostname of the admin server) or ``kadmin/admin``. +If the credentials cache contains a ticket for one of these +principals, and the **-c** credentials_cache option is specified, that +ticket is used to authenticate to kadmind. Otherwise, the **-p** and +**-k** options are used to specify the client Kerberos principal name +used to authenticate. Once kadmin has determined the principal name, +it requests a service ticket from the KDC, and uses that service +ticket to authenticate to kadmind. + +Since kadmin.local directly accesses the KDC database, it usually must +be run directly on the master KDC with sufficient permissions to read +the KDC database. If the KDC database uses the LDAP database module, +kadmin.local can be run on any host which can access the LDAP server. + + +OPTIONS +------- + +.. _kadmin_options: + +**-r** *realm* + Use *realm* as the default database realm. + +**-p** *principal* + Use *principal* to authenticate. Otherwise, kadmin will append + ``/admin`` to the primary principal name of the default ccache, + the value of the **USER** environment variable, or the username as + obtained with getpwuid, in order of preference. + +**-k** + Use a keytab to decrypt the KDC response instead of prompting for + a password. In this case, the default principal will be + ``host/hostname``. If there is no keytab specified with the + **-t** option, then the default keytab will be used. + +**-t** *keytab* + Use *keytab* to decrypt the KDC response. This can only be used + with the **-k** option. + +**-n** + Requests anonymous processing. Two types of anonymous principals + are supported. For fully anonymous Kerberos, configure PKINIT on + the KDC and configure **pkinit_anchors** in the client's + :ref:`krb5.conf(5)`. Then use the **-n** option with a principal + of the form ``@REALM`` (an empty principal name followed by the + at-sign and a realm name). If permitted by the KDC, an anonymous + ticket will be returned. A second form of anonymous tickets is + supported; these realm-exposed tickets hide the identity of the + client but not the client's realm. For this mode, use ``kinit + -n`` with a normal principal name. If supported by the KDC, the + principal (but not realm) will be replaced by the anonymous + principal. As of release 1.8, the MIT Kerberos KDC only supports + fully anonymous operation. + +**-c** *credentials_cache* + Use *credentials_cache* as the credentials cache. The + cache should contain a service ticket for the ``kadmin/ADMINHOST`` + (where *ADMINHOST* is the fully-qualified hostname of the admin + server) or ``kadmin/admin`` service; it can be acquired with the + :ref:`kinit(1)` program. If this option is not specified, kadmin + requests a new service ticket from the KDC, and stores it in its + own temporary ccache. + +**-w** *password* + Use *password* instead of prompting for one. Use this option with + care, as it may expose the password to other users on the system + via the process list. + +**-q** *query* + Perform the specified query and then exit. This can be useful for + writing scripts. + +**-d** *dbname* + Specifies the name of the KDC database. This option does not + apply to the LDAP database module. + +**-s** *admin_server*\ [:*port*] + Specifies the admin server which kadmin should contact. + +**-m** + If using kadmin.local, prompt for the database master password + instead of reading it from a stash file. + +**-e** "*enc*:*salt* ..." + Sets the list of encryption types and salt types to be used for + any new keys created. See :ref:`Encryption_and_salt_types` in + :ref:`kdc.conf(5)` for a list of possible values. + +**-O** + Force use of old AUTH_GSSAPI authentication flavor. + +**-N** + Prevent fallback to AUTH_GSSAPI authentication flavor. + +**-x** *db_args* + Specifies the database specific arguments. Options supported for + the LDAP database module are: + + **-x host=**\ *hostname* + Specifies the LDAP server to connect to by a LDAP URI. + + **-x binddn=**\ *bind_dn* + Specifies the DN of the object used by the administration + server to bind to the LDAP server. This object should have + the read and write privileges on the realm container, the + principal container, and the subtree that is referenced by the + realm. + + **-x bindpwd=**\ *bind_password* + Specifies the password for the above mentioned binddn. Using + this option may expose the password to other users on the + system via the process list; to avoid this, instead stash the + password using the **stashsrvpw** command of + :ref:`kdb5_ldap_util(8)`. + +.. _kadmin_options_end: + + +COMMANDS +-------- + +When using the remote client, available commands may be restricted +according to the privileges specified in the :ref:`kadm5.acl(5)` file +on the admin server. + +.. _add_principal: + +add_principal +~~~~~~~~~~~~~ + + **add_principal** [*options*] *newprinc* + +Creates the principal *newprinc*, prompting twice for a password. If +no password policy is specified with the **-policy** option, and the +policy named ``default`` is assigned to the principal if it exists. +However, creating a policy named ``default`` will not automatically +assign this policy to previously existing principals. This policy +assignment can be suppressed with the **-clearpolicy** option. + +This command requires the **add** privilege. + +Aliases: **addprinc**, **ank** + +Options: + +**-expire** *expdate* + (:ref:`getdate` string) The expiration date of the principal. + +**-pwexpire** *pwexpdate* + (:ref:`getdate` string) The password expiration date. + +**-maxlife** *maxlife* + (:ref:`getdate` string) The maximum ticket life for the principal. + +**-maxrenewlife** *maxrenewlife* + (:ref:`getdate` string) The maximum renewable life of tickets for + the principal. + +**-kvno** *kvno* + The initial key version number. + +**-policy** *policy* + The password policy used by this principal. If not specified, the + policy ``default`` is used if it exists (unless **-clearpolicy** + is specified). + +**-clearpolicy** + Prevents any policy from being assigned when **-policy** is not + specified. + +{-\|+}\ **allow_postdated** + **-allow_postdated** prohibits this principal from obtaining + postdated tickets. **+allow_postdated** clears this flag. + +{-\|+}\ **allow_forwardable** + **-allow_forwardable** prohibits this principal from obtaining + forwardable tickets. **+allow_forwardable** clears this flag. + +{-\|+}\ **allow_renewable** + **-allow_renewable** prohibits this principal from obtaining + renewable tickets. **+allow_renewable** clears this flag. + +{-\|+}\ **allow_proxiable** + **-allow_proxiable** prohibits this principal from obtaining + proxiable tickets. **+allow_proxiable** clears this flag. + +{-\|+}\ **allow_dup_skey** + **-allow_dup_skey** disables user-to-user authentication for this + principal by prohibiting this principal from obtaining a session + key for another user. **+allow_dup_skey** clears this flag. + +{-\|+}\ **requires_preauth** + **+requires_preauth** requires this principal to preauthenticate + before being allowed to kinit. **-requires_preauth** clears this + flag. + +{-\|+}\ **requires_hwauth** + **+requires_hwauth** requires this principal to preauthenticate + using a hardware device before being allowed to kinit. + **-requires_hwauth** clears this flag. + +{-\|+}\ **ok_as_delegate** + **+ok_as_delegate** sets the **okay as delegate** flag on tickets + issued with this principal as the service. Clients may use this + flag as a hint that credentials should be delegated when + authenticating to the service. **-ok_as_delegate** clears this + flag. + +{-\|+}\ **allow_svr** + **-allow_svr** prohibits the issuance of service tickets for this + principal. **+allow_svr** clears this flag. + +{-\|+}\ **allow_tgs_req** + **-allow_tgs_req** specifies that a Ticket-Granting Service (TGS) + request for a service ticket for this principal is not permitted. + **+allow_tgs_req** clears this flag. + +{-\|+}\ **allow_tix** + **-allow_tix** forbids the issuance of any tickets for this + principal. **+allow_tix** clears this flag. + +{-\|+}\ **needchange** + **+needchange** forces a password change on the next initial + authentication to this principal. **-needchange** clears this + flag. + +{-\|+}\ **password_changing_service** + **+password_changing_service** marks this principal as a password + change service principal. + +**-randkey** + Sets the key of the principal to a random value. + +**-pw** *password* + Sets the password of the principal to the specified string and + does not prompt for a password. Note: using this option in a + shell script may expose the password to other users on the system + via the process list. + +**-e** *enc*:*salt*,... + Uses the specified list of enctype-salttype pairs for setting the + key of the principal. + +**-x** *db_princ_args* + Indicates database-specific options. The options for the LDAP + database module are: + + **-x dn=**\ *dn* + Specifies the LDAP object that will contain the Kerberos + principal being created. + + **-x linkdn=**\ *dn* + Specifies the LDAP object to which the newly created Kerberos + principal object will point. + + **-x containerdn=**\ *container_dn* + Specifies the container object under which the Kerberos + principal is to be created. + + **-x tktpolicy=**\ *policy* + Associates a ticket policy to the Kerberos principal. + + .. note:: + - The **containerdn** and **linkdn** options cannot be + specified with the **dn** option. + - If the *dn* or *containerdn* options are not specified while + adding the principal, the principals are created under the + principal container configured in the realm or the realm + container. + - *dn* and *containerdn* should be within the subtrees or + principal container configured in the realm. + +Example: + + :: + + kadmin: addprinc jennifer + WARNING: no policy specified for "jennifer@ATHENA.MIT.EDU"; + defaulting to no policy. + Enter password for principal jennifer@ATHENA.MIT.EDU: + Re-enter password for principal jennifer@ATHENA.MIT.EDU: + Principal "jennifer@ATHENA.MIT.EDU" created. + kadmin: + +.. _add_principal_end: + +.. _modify_principal: + +modify_principal +~~~~~~~~~~~~~~~~ + + **modify_principal** [*options*] *principal* + +Modifies the specified principal, changing the fields as specified. +The options to **add_principal** also apply to this command, except +for the **-randkey**, **-pw**, and **-e** options. In addition, the +option **-clearpolicy** will clear the current policy of a principal. + +This command requires the *modify* privilege. + +Alias: **modprinc** + +Options (in addition to the **addprinc** options): + +**-unlock** + Unlocks a locked principal (one which has received too many failed + authentication attempts without enough time between them according + to its password policy) so that it can successfully authenticate. + +.. _modify_principal_end: + +.. _rename_principal: + +rename_principal +~~~~~~~~~~~~~~~~ + + **rename_principal** [**-force**] *old_principal* *new_principal* + +Renames the specified *old_principal* to *new_principal*. This +command prompts for confirmation, unless the **-force** option is +given. + +This command requires the **add** and **delete** privileges. + +Alias: **renprinc** + +.. _rename_principal_end: + +.. _delete_principal: + +delete_principal +~~~~~~~~~~~~~~~~ + + **delete_principal** [**-force**] *principal* + +Deletes the specified *principal* from the database. This command +prompts for deletion, unless the **-force** option is given. + +This command requires the **delete** privilege. + +Alias: **delprinc** + +.. _delete_principal_end: + +.. _change_password: + +change_password +~~~~~~~~~~~~~~~ + + **change_password** [*options*] *principal* + +Changes the password of *principal*. Prompts for a new password if +neither **-randkey** or **-pw** is specified. + +This command requires the **changepw** privilege, or that the +principal running the program is the same as the principal being +changed. + +Alias: **cpw** + +The following options are available: + +**-randkey** + Sets the key of the principal to a random value. + +**-pw** *password* + Set the password to the specified string. Using this option in a + script may expose the password to other users on the system via + the process list. + +**-e** *enc*:*salt*,... + Uses the specified list of enctype-salttype pairs for setting the + key of the principal. + +**-keepold** + Keeps the existing keys in the database. This flag is usually not + necessary except perhaps for ``krbtgt`` principals. + +Example: + + :: + + kadmin: cpw systest + Enter password for principal systest@BLEEP.COM: + Re-enter password for principal systest@BLEEP.COM: + Password for systest@BLEEP.COM changed. + kadmin: + +.. _change_password_end: + +.. _purgekeys: + +purgekeys +~~~~~~~~~ + + **purgekeys** [**-keepkvno** *oldest_kvno_to_keep*] *principal* + +Purges previously retained old keys (e.g., from **change_password +-keepold**) from *principal*. If **-keepkvno** is specified, then +only purges keys with kvnos lower than *oldest_kvno_to_keep*. + +This command requires the **modify** privilege. + +.. _purgekeys_end: + +.. _get_principal: + +get_principal +~~~~~~~~~~~~~ + + **get_principal** [**-terse**] *principal* + +Gets the attributes of principal. With the **-terse** option, outputs +fields as quoted tab-separated strings. + +This command requires the **inquire** privilege, or that the principal +running the the program to be the same as the one being listed. + +Alias: **getprinc** + +Examples: + + :: + + kadmin: getprinc tlyu/admin + Principal: tlyu/admin@BLEEP.COM + Expiration date: [never] + Last password change: Mon Aug 12 14:16:47 EDT 1996 + Password expiration date: [none] + Maximum ticket life: 0 days 10:00:00 + Maximum renewable life: 7 days 00:00:00 + Last modified: Mon Aug 12 14:16:47 EDT 1996 (bjaspan/admin@BLEEP.COM) + Last successful authentication: [never] + Last failed authentication: [never] + Failed password attempts: 0 + Number of keys: 2 + Key: vno 1, DES cbc mode with CRC-32, no salt + Key: vno 1, DES cbc mode with CRC-32, Version 4 + Attributes: + Policy: [none] + + kadmin: getprinc -terse systest + systest@BLEEP.COM 3 86400 604800 1 + 785926535 753241234 785900000 + tlyu/admin@BLEEP.COM 786100034 0 0 + kadmin: + +.. _get_principal_end: + +.. _list_principals: + +list_principals +~~~~~~~~~~~~~~~ + + **list_principals** [*expression*] + +Retrieves all or some principal names. *expression* is a shell-style +glob expression that can contain the wild-card characters ``?``, +``*``, and ``[]``. All principal names matching the expression are +printed. If no expression is provided, all principal names are +printed. If the expression does not contain an ``@`` character, an +``@`` character followed by the local realm is appended to the +expression. + +This command requires the **list** privilege. + +Alias: **listprincs**, **get_principals**, **get_princs** + +Example: + + :: + + kadmin: listprincs test* + test3@SECURE-TEST.OV.COM + test2@SECURE-TEST.OV.COM + test1@SECURE-TEST.OV.COM + testuser@SECURE-TEST.OV.COM + kadmin: + +.. _list_principals_end: + +.. _get_strings: + +get_strings +~~~~~~~~~~~ + + **get_strings** *principal* + +Displays string attributes on *principal*. + +This command requires the **inquire** privilege. + +Alias: **getstr** + +.. _get_strings_end: + +.. _set_string: + +set_string +~~~~~~~~~~ + + **set_string** *principal* *key* *value* + +Sets a string attribute on *principal*. String attributes are used to +supply per-principal configuration to the KDC and some KDC plugin +modules. The following string attributes are recognized by the KDC: + +**session_enctypes** + Specifies the encryption types supported for session keys when the + principal is authenticated to as a server. See + :ref:`Encryption_and_salt_types` in :ref:`kdc.conf(5)` for a list + of the accepted values. + +This command requires the **modify** privilege. + +Alias: **setstr** + +.. _set_string_end: + +.. _del_string: + +del_string +~~~~~~~~~~ + + **del_string** *principal* *key* + +Deletes a string attribute from *principal*. + +This command requires the **delete** privilege. + +Alias: **delstr** + +.. _del_string_end: + +.. _add_policy: + +add_policy +~~~~~~~~~~ + + **add_policy** [*options*] *policy* + +Adds a password policy named *policy* to the database. + +This command requires the **add** privilege. + +Alias: **addpol** + +The following options are available: + +**-maxlife** *time* + (:ref:`getdate` string) Sets the maximum lifetime of a password. + +**-minlife** *time* + (:ref:`getdate` string) Sets the minimum lifetime of a password. + +**-minlength** *length* + Sets the minimum length of a password. + +**-minclasses** *number* + Sets the minimum number of character classes required in a + password. The five character classes are lower case, upper case, + numbers, punctuation, and whitespace/unprintable characters. + +**-history** *number* + Sets the number of past keys kept for a principal. This option is + not supported with the LDAP KDC database module. + +**-maxfailure** *maxnumber* + Sets the maximum number of authentication failures before the + principal is locked. Authentication failures are only tracked for + principals which require preauthentication. + +**-failurecountinterval** *failuretime* + (:ref:`getdate` string) Sets the allowable time between + authentication failures. If an authentication failure happens + after *failuretime* has elapsed since the previous failure, + the number of authentication failures is reset to 1. + +**-lockoutduration** *lockouttime* + (:ref:`getdate` string) Sets the duration for which the principal + is locked from authenticating if too many authentication failures + occur without the specified failure count interval elapsing. + A duration of 0 means forever. + +**-allowedkeysalts** + Specifies the key/salt tuples supported for long-term keys when + setting or changing a principal's password/keys. See + :ref:`Encryption_and_salt_types` in :ref:`kdc.conf(5)` for a list + of the accepted values, but note that key/salt tuples must be + separated with commas (',') only. To clear the allowed key/salt + policy use a value of '-'. + +Example: + + :: + + kadmin: add_policy -maxlife "2 days" -minlength 5 guests + kadmin: + +.. _add_policy_end: + +.. _modify_policy: + +modify_policy +~~~~~~~~~~~~~ + + **modify_policy** [*options*] *policy* + +Modifies the password policy named *policy*. Options are as described +for **add_policy**. + +This command requires the **modify** privilege. + +Alias: **modpol** + +.. _modify_policy_end: + +.. _delete_policy: + +delete_policy +~~~~~~~~~~~~~ + + **delete_policy** [**-force**] *policy* + +Deletes the password policy named *policy*. Prompts for confirmation +before deletion. The command will fail if the policy is in use by any +principals. + +This command requires the **delete** privilege. + +Alias: **delpol** + +Example: + + :: + + kadmin: del_policy guests + Are you sure you want to delete the policy "guests"? + (yes/no): yes + kadmin: + +.. _delete_policy_end: + +.. _get_policy: + +get_policy +~~~~~~~~~~ + + **get_policy** [ **-terse** ] *policy* + +Displays the values of the password policy named *policy*. With the +**-terse** flag, outputs the fields as quoted strings separated by +tabs. + +This command requires the **inquire** privilege. + +Alias: getpol + +Examples: + + :: + + kadmin: get_policy admin + Policy: admin + Maximum password life: 180 days 00:00:00 + Minimum password life: 00:00:00 + Minimum password length: 6 + Minimum number of password character classes: 2 + Number of old keys kept: 5 + Reference count: 17 + + kadmin: get_policy -terse admin + admin 15552000 0 6 2 5 17 + kadmin: + +The "Reference count" is the number of principals using that policy. +With the LDAP KDC database module, the reference count field is not +meaningful. + +.. _get_policy_end: + +.. _list_policies: + +list_policies +~~~~~~~~~~~~~ + + **list_policies** [*expression*] + +Retrieves all or some policy names. *expression* is a shell-style +glob expression that can contain the wild-card characters ``?``, +``*``, and ``[]``. All policy names matching the expression are +printed. If no expression is provided, all existing policy names are +printed. + +This command requires the **list** privilege. + +Aliases: **listpols**, **get_policies**, **getpols**. + +Examples: + + :: + + kadmin: listpols + test-pol + dict-only + once-a-min + test-pol-nopw + + kadmin: listpols t* + test-pol + test-pol-nopw + kadmin: + +.. _list_policies_end: + +.. _ktadd: + +ktadd +~~~~~ + + | **ktadd** [options] *principal* + | **ktadd** [options] **-glob** *princ-exp* + +Adds a *principal*, or all principals matching *princ-exp*, to a +keytab file. Each principal's keys are randomized in the process. +The rules for *princ-exp* are described in the **list_principals** +command. + +This command requires the **inquire** and **changepw** privileges. +With the **-glob** form, it also requires the **list** privilege. + +The options are: + +**-k[eytab]** *keytab* + Use *keytab* as the keytab file. Otherwise, the default keytab is + used. + +**-e** *enc*:*salt*,... + Use the specified list of enctype-salttype pairs for setting the + new keys of the principal. + +**-q** + Display less verbose information. + +**-norandkey** + Do not randomize the keys. The keys and their version numbers stay + unchanged. This option is only available in kadmin.local, and + cannot be specified in combination with the **-e** option. + +An entry for each of the principal's unique encryption types is added, +ignoring multiple keys with the same encryption type but different +salt types. + +Example: + + :: + + kadmin: ktadd -k /tmp/foo-new-keytab host/foo.mit.edu + Entry for principal host/foo.mit.edu@ATHENA.MIT.EDU with kvno 3, + encryption type aes256-cts-hmac-sha1-96 added to keytab + FILE:/tmp/foo-new-keytab + kadmin: + +.. _ktadd_end: + +.. _ktremove: + +ktremove +~~~~~~~~ + + **ktremove** [options] *principal* [*kvno* | *all* | *old*] + +Removes entries for the specified *principal* from a keytab. Requires +no permissions, since this does not require database access. + +If the string "all" is specified, all entries for that principal are +removed; if the string "old" is specified, all entries for that +principal except those with the highest kvno are removed. Otherwise, +the value specified is parsed as an integer, and all entries whose +kvno match that integer are removed. + +The options are: + +**-k[eytab]** *keytab* + Use *keytab* as the keytab file. Otherwise, the default keytab is + used. + +**-q** + Display less verbose information. + +Example: + + :: + + kadmin: ktremove kadmin/admin all + Entry for principal kadmin/admin with kvno 3 removed from keytab + FILE:/etc/krb5.keytab + kadmin: + +.. _ktremove_end: + +lock +~~~~ + +Lock database exclusively. Use with extreme caution! This command +only works with the DB2 KDC database module. + +unlock +~~~~~~ + +Release the exclusive database lock. + +list_requests +~~~~~~~~~~~~~ + +Lists available for kadmin requests. + +Aliases: **lr**, **?** + +quit +~~~~ + +Exit program. If the database was locked, the lock is released. + +Aliases: **exit**, **q** + + +HISTORY +------- + +The kadmin program was originally written by Tom Yu at MIT, as an +interface to the OpenVision Kerberos administration program. + + +SEE ALSO +-------- + +:ref:`kpasswd(1)`, :ref:`kadmind(8)` diff --git a/doc/admins/admin_commands/kadmind.rst b/doc/admins/admin_commands/kadmind.rst new file mode 100644 index 000000000..10fc672cb --- /dev/null +++ b/doc/admins/admin_commands/kadmind.rst @@ -0,0 +1,130 @@ +.. _kadmind(8): + +kadmind +======= + +SYNOPSIS +-------- + +**kadmind** +[**-x** *db_args*] +[**-r** *realm*] +[**-m**] +[**-nofork**] +[**-port** *port-number*] +[**-P** *pid_file*] +[**-p** *kdb5_util_path*] +[**-K** *kprop_path*] +[**-F** *dump_file*] + +DESCRIPTION +----------- + +kadmind starts the Kerberos administration server. kadmind typically +runs on the master Kerberos server, which stores the KDC database. If +the KDC database uses the LDAP module, the administration server and +the KDC server need not run on the same machine. kadmind accepts +remote requests from programs such as :ref:`kadmin(1)` and +:ref:`kpasswd(1)` to administer the information in these database. + +kadmind requires a number of configuration files to be set up in order +for it to work: + +:ref:`kdc.conf(5)` + The KDC configuration file contains configuration information for + the KDC and admin servers. kadmind uses settings in this file to + locate the Kerberos database, and is also affected by the + **acl_file**, **dict_file**, **kadmind_port**, and iprop-related + settings. + +:ref:`kadm5.acl(5)` + kadmind's ACL (access control list) tells it which principals are + allowed to perform administration actions. The pathname to the + ACL file can be specified with the **acl_file** :ref:`kdc.conf(5)` + variable; by default, it is |kdcdir|\ ``/kadm5.acl``. + +After the server begins running, it puts itself in the background and +disassociates itself from its controlling terminal. + +kadmind can be configured for incremental database propagation. +Incremental propagation allows slave KDC servers to receive principal +and policy updates incrementally instead of receiving full dumps of +the database. This facility can be enabled in the :ref:`kdc.conf(5)` +file with the **iprop_enable** option. Incremental propagation +requires the principal ``kiprop/MASTER\@REALM`` (where MASTER is the +master KDC's canonical host name, and REALM the realm name) to be +registered in the database. + + +OPTIONS +------- + +**-r** *realm* + specifies the realm that kadmind will serve; if it is not + specified, the default realm of the host is used. + +**-m** + causes the master database password to be fetched from the + keyboard (before the server puts itself in the background, if not + invoked with the **-nofork** option) rather than from a file on + disk. + +**-nofork** + causes the server to remain in the foreground and remain + associated to the terminal. In normal operation, you should allow + the server to place itself in the background. + +**-port** *port-number* + specifies the port on which the administration server listens for + connections. The default port is determined by the + **kadmind_port** configuration variable in :ref:`kdc.conf(5)`. + +**-P** *pid_file* + specifies the file to which the PID of kadmind process should be + written after it starts up. This file can be used to identify + whether kadmind is still running and to allow init scripts to stop + the correct process. + +**-p** *kdb5_util_path* + specifies the path to the kdb5_util command to use when dumping the + KDB in response to full resync requests when iprop is enabled. + +**-K** *kprop_path* + specifies the path to the kprop command to use to send full dumps + to slaves in response to full resync requests. + +**-F** *dump_file* + specifies the file path to be used for dumping the KDB in response + to full resync requests when iprop is enabled. + +**-x** *db_args* + specifies database-specific arguments. + + Options supported for LDAP database are: + + **-x nconns=**\ *number_of_connections* + specifies the number of connections to be maintained per + LDAP server. + + **-x host=**\ *ldapuri* + specifies the LDAP server to connect to by URI. + + **-x binddn=**\ *binddn* + specifies the DN of the object used by the administration + server to bind to the LDAP server. This object should + have read and write privileges on the realm container, the + principal container, and the subtree that is referenced by + the realm. + + **-x bindpwd=**\ *bind_password* + specifies the password for the above mentioned binddn. + Using this option may expose the password to other users + on the system via the process list; to avoid this, instead + stash the password using the **stashsrvpw** command of + :ref:`kdb5_ldap_util(8)`. + +SEE ALSO +-------- + +:ref:`kpasswd(1)`, :ref:`kadmin(1)`, :ref:`kdb5_util(8)`, +:ref:`kdb5_ldap_util(8)`, :ref:`kadm5.acl(5)` diff --git a/doc/admins/admin_commands/kdb5_ldap_util.rst b/doc/admins/admin_commands/kdb5_ldap_util.rst new file mode 100644 index 000000000..e5c037db4 --- /dev/null +++ b/doc/admins/admin_commands/kdb5_ldap_util.rst @@ -0,0 +1,478 @@ +.. _kdb5_ldap_util(8): + +kdb5_ldap_util +=============== + +SYNOPSIS +-------- + +.. _kdb5_ldap_util_synopsis: + +**kdb5_ldap_util** +[**-D** *user_dn* [**-w** *passwd*]] +[**-H** *ldapuri*] +**command** +[*command_options*] + +.. _kdb5_ldap_util_synopsis_end: + + +DESCRIPTION +----------- + +kdb5_ldap_util allows an administrator to manage realms, Kerberos +services and ticket policies. + + +COMMAND-LINE OPTIONS +-------------------- + +.. _kdb5_ldap_util_options: + +**-D** *user_dn* + Specifies the Distinguished Name (DN) of the user who has + sufficient rights to perform the operation on the LDAP server. + +**-w** *passwd* + Specifies the password of *user_dn*. This option is not + recommended. + +**-H** *ldapuri* + Specifies the URI of the LDAP server. It is recommended to use + ``ldapi://`` or ``ldaps://`` to connect to the LDAP server. + +.. _kdb5_ldap_util_options_end: + + +COMMANDS +-------- + +create +~~~~~~ + +.. _kdb5_ldap_util_create: + + **create** + [**-subtrees** *subtree_dn_list*] + [**-sscope** *search_scope*] + [**-containerref** *container_reference_dn*] + [**-k** *mkeytype*] + [**-kv** *mkeyVNO*] + [**-m|-P** *password*\|\ **-sf** *stashfilename*] + [**-s**] + [**-r** *realm*] + [**-maxtktlife** *max_ticket_life*] + [**-maxrenewlife** *max_renewable_ticket_life*] + [*ticket_flags*] + +Creates realm in directory. Options: + +**-subtrees** *subtree_dn_list* + Specifies the list of subtrees containing the principals of a + realm. The list contains the DNs of the subtree objects separated + by colon (``:``). + +**-sscope** *search_scope* + Specifies the scope for searching the principals under the + subtree. The possible values are 1 or one (one level), 2 or sub + (subtrees). + +**-containerref** *container_reference_dn* + Specifies the DN of the container object in which the principals + of a realm will be created. If the container reference is not + configured for a realm, the principals will be created in the + realm container. + +**-k** *mkeytype* + Specifies the key type of the master key in the database. The + default is given by the **master_key_type** variable in + :ref:`kdc.conf(5)`. + +**-kv** *mkeyVNO* + Specifies the version number of the master key in the database; + the default is 1. Note that 0 is not allowed. + +**-m** + Specifies that the master database password should be read from + the TTY rather than fetched from a file on the disk. + +**-P** *password* + Specifies the master database password. This option is not + recommended. + +**-r** *realm* + Specifies the Kerberos realm of the database. + +**-sf** *stashfilename* + Specifies the stash file of the master database password. + +**-s** + Specifies that the stash file is to be created. + +**-maxtktlife** *max_ticket_life* + (:ref:`getdate` string) Specifies maximum ticket life for + principals in this realm. + +**-maxrenewlife** *max_renewable_ticket_life* + (:ref:`getdate` string) Specifies maximum renewable life of + tickets for principals in this realm. + +*ticket_flags* + Specifies global ticket flags for the realm. Allowable flags are + documented in the description of the **add_principal** command in + :ref:`kadmin(1)`. + +Example: + + :: + + kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu + create -subtrees o=org -sscope SUB -r ATHENA.MIT.EDU + Password for "cn=admin,o=org": + Initializing database for realm 'ATHENA.MIT.EDU' + You will be prompted for the database Master Password. + It is important that you NOT FORGET this password. + Enter KDC database master key: + Re-enter KDC database master key to verify: + +.. _kdb5_ldap_util_create_end: + +modify +~~~~~~ + +.. _kdb5_ldap_util_modify: + + **modify** + [**-subtrees** *subtree_dn_list*] + [**-sscope** *search_scope*] + [**-containerref** *container_reference_dn*] + [**-r** *realm*] + [**-maxtktlife** *max_ticket_life*] + [**-maxrenewlife** *max_renewable_ticket_life*] + [*ticket_flags*] + +Modifies the attributes of a realm. Options: + +**-subtrees** *subtree_dn_list* + Specifies the list of subtrees containing the principals of a + realm. The list contains the DNs of the subtree objects separated + by colon (``:``). This list replaces the existing list. + +**-sscope** *search_scope* + Specifies the scope for searching the principals under the + subtrees. The possible values are 1 or one (one level), 2 or sub + (subtrees). + +**-containerref** *container_reference_dn* Specifies the DN of the + container object in which the principals of a realm will be + created. + +**-r** *realm* + Specifies the Kerberos realm of the database. + +**-maxtktlife** *max_ticket_life* + (:ref:`getdate` string) Specifies maximum ticket life for + principals in this realm. + +**-maxrenewlife** *max_renewable_ticket_life* + (:ref:`getdate` string) Specifies maximum renewable life of + tickets for principals in this realm. + +*ticket_flags* + Specifies global ticket flags for the realm. Allowable flags are + documented in the description of the **add_principal** command in + :ref:`kadmin(1)`. + +Example: + + :: + + shell% kdb5_ldap_util -D cn=admin,o=org -H + ldaps://ldap-server1.mit.edu modify +requires_preauth -r + ATHENA.MIT.EDU + Password for "cn=admin,o=org": + shell% + +.. _kdb5_ldap_util_modify_end: + +view +~~~~ + +.. _kdb5_ldap_util_view: + + **view** [**-r** *realm*] + +Displays the attributes of a realm. Options: + +**-r** *realm* + Specifies the Kerberos realm of the database. + +Example: + + :: + + kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu + view -r ATHENA.MIT.EDU + Password for "cn=admin,o=org": + Realm Name: ATHENA.MIT.EDU + Subtree: ou=users,o=org + Subtree: ou=servers,o=org + SearchScope: ONE + Maximum ticket life: 0 days 01:00:00 + Maximum renewable life: 0 days 10:00:00 + Ticket flags: DISALLOW_FORWARDABLE REQUIRES_PWCHANGE + +.. _kdb5_ldap_util_view_end: + +destroy +~~~~~~~ + +.. _kdb5_ldap_util_destroy: + + **destroy** [**-f**] [**-r** *realm*] + +Destroys an existing realm. Options: + +**-f** + If specified, will not prompt the user for confirmation. + +**-r** *realm* + Specifies the Kerberos realm of the database. + +Example: + + :: + + shell% kdb5_ldap_util -D cn=admin,o=org -H + ldaps://ldap-server1.mit.edu destroy -r ATHENA.MIT.EDU + Password for "cn=admin,o=org": + Deleting KDC database of 'ATHENA.MIT.EDU', are you sure? + (type 'yes' to confirm)? yes + OK, deleting database of 'ATHENA.MIT.EDU'... + shell% + +.. _kdb5_ldap_util_destroy_end: + +list +~~~~ + +.. _kdb5_ldap_util_list: + + **list** + +Lists the name of realms. + +Example: + + :: + + shell% kdb5_ldap_util -D cn=admin,o=org -H + ldaps://ldap-server1.mit.edu list + Password for "cn=admin,o=org": + ATHENA.MIT.EDU + OPENLDAP.MIT.EDU + MEDIA-LAB.MIT.EDU + shell% + +.. _kdb5_ldap_util_list_end: + +stashsrvpw +~~~~~~~~~~ + +.. _kdb5_ldap_util_stashsrvpw: + + **stashsrvpw** + [**-f** *filename*] + *servicedn* + +Allows an administrator to store the password for service object in a +file so that KDC and Administration server can use it to authenticate +to the LDAP server. Options: + +**-f** *filename* + Specifies the complete path of the service password file. By + default, ``/usr/local/var/service_passwd`` is used. + +*servicedn* + Specifies Distinguished Name (DN) of the service object whose + password is to be stored in file. + +Example: + + :: + + kdb5_ldap_util stashsrvpw -f /home/andrew/conf_keyfile + cn=service-kdc,o=org + Password for "cn=service-kdc,o=org": + Re-enter password for "cn=service-kdc,o=org": + +.. _kdb5_ldap_util_stashsrvpw_end: + +create_policy +~~~~~~~~~~~~~ + +.. _kdb5_ldap_util_create_policy: + + **create_policy** + [**-r** *realm*] + [**-maxtktlife** *max_ticket_life*] + [**-maxrenewlife** *max_renewable_ticket_life*] + [*ticket_flags*] + *policy_name* + +Creates a ticket policy in the directory. Options: + +**-r** *realm* + Specifies the Kerberos realm of the database. + +**-maxtktlife** *max_ticket_life* + (:ref:`getdate` string) Specifies maximum ticket life for + principals. + +**-maxrenewlife** *max_renewable_ticket_life* + (:ref:`getdate` string) Specifies maximum renewable life of + tickets for principals. + +*ticket_flags* + Specifies the ticket flags. If this option is not specified, by + default, no restriction will be set by the policy. Allowable + flags are documented in the description of the **add_principal** + command in :ref:`kadmin(1)`. + +*policy_name* + Specifies the name of the ticket policy. + +Example: + + :: + + kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu + create_policy -r ATHENA.MIT.EDU -maxtktlife "1 day" + -maxrenewlife "1 week" -allow_postdated +needchange + -allow_forwardable tktpolicy + Password for "cn=admin,o=org": + +.. _kdb5_ldap_util_create_policy_end: + +modify_policy +~~~~~~~~~~~~~ + +.. _kdb5_ldap_util_modify_policy: + + **modify_policy** + [**-r** *realm*] + [**-maxtktlife** *max_ticket_life*] + [**-maxrenewlife** *max_renewable_ticket_life*] + [*ticket_flags*] + *policy_name* + +Modifies the attributes of a ticket policy. Options are same as for +**create_policy**. + +Example: + + :: + + kdb5_ldap_util -D cn=admin,o=org -H + ldaps://ldap-server1.mit.edu modify_policy -r ATHENA.MIT.EDU + -maxtktlife "60 minutes" -maxrenewlife "10 hours" + +allow_postdated -requires_preauth tktpolicy + Password for "cn=admin,o=org": + +.. _kdb5_ldap_util_modify_policy_end: + +view_policy +~~~~~~~~~~~ + +.. _kdb5_ldap_util_view_policy: + + **view_policy** + [**-r** *realm*] + *policy_name* + +Displays the attributes of a ticket policy. Options: + +*policy_name* + Specifies the name of the ticket policy. + +Example: + + :: + + kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu + view_policy -r ATHENA.MIT.EDU tktpolicy + Password for "cn=admin,o=org": + Ticket policy: tktpolicy + Maximum ticket life: 0 days 01:00:00 + Maximum renewable life: 0 days 10:00:00 + Ticket flags: DISALLOW_FORWARDABLE REQUIRES_PWCHANGE + +.. _kdb5_ldap_util_view_policy_end: + +destroy_policy +~~~~~~~~~~~~~~ + +.. _kdb5_ldap_util_destroy_policy: + + **destroy_policy** + [**-r** *realm*] + [**-force**] + *policy_name* + +Destroys an existing ticket policy. Options: + +**-r** *realm* + Specifies the Kerberos realm of the database. + +**-force** + Forces the deletion of the policy object. If not specified, the + user will be prompted for confirmation before deleting the policy. + +*policy_name* + Specifies the name of the ticket policy. + +Example: + + :: + + kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu + destroy_policy -r ATHENA.MIT.EDU tktpolicy + Password for "cn=admin,o=org": + This will delete the policy object 'tktpolicy', are you sure? + (type 'yes' to confirm)? yes + ** policy object 'tktpolicy' deleted. + +.. _kdb5_ldap_util_destroy_policy_end: + +list_policy +~~~~~~~~~~~ + +.. _kdb5_ldap_util_list_policy: + + **list_policy** + [**-r** *realm*] + +Lists the ticket policies in realm if specified or in the default +realm. Options: + +**-r** *realm* + Specifies the Kerberos realm of the database. + +Example: + + :: + + kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu + list_policy -r ATHENA.MIT.EDU + Password for "cn=admin,o=org": + tktpolicy + tmppolicy + userpolicy + +.. _kdb5_ldap_util_list_policy_end: + + +SEE ALSO +-------- + +:ref:`kadmin(1)` diff --git a/doc/admins/admin_commands/kdb5_util.rst b/doc/admins/admin_commands/kdb5_util.rst new file mode 100644 index 000000000..d866777c7 --- /dev/null +++ b/doc/admins/admin_commands/kdb5_util.rst @@ -0,0 +1,355 @@ +.. _kdb5_util(8): + +kdb5_util +========= + +SYNOPSIS +-------- + +.. _kdb5_util_synopsis: + +**kdb5_util** +[**-r** *realm*] +[**-d** *dbname*] +[**-k** *mkeytype*] +[**-M** *mkeyname*] +[**-kv** *mkeyVNO*] +[**-sf** *stashfilename*] +[**-m**] +*command* [*command_options*] + +.. _kdb5_util_synopsis_end: + +DESCRIPTION +----------- + +kdb5_util allows an administrator to perform maintenance procedures on +the KDC database. Databases can be created, destroyed, and dumped to +or loaded from ASCII files. kdb5_util can create a Kerberos master +key stash file or perform live rollover of the master key. + +When kdb5_util is run, it attempts to acquire the master key and open +the database. However, execution continues regardless of whether or +not kdb5_util successfully opens the database, because the database +may not exist yet or the stash file may be corrupt. + +Note that some KDC database modules may not support all kdb5_util +commands. + + +COMMAND-LINE OPTIONS +-------------------- + +.. _kdb5_util_options: + +**-r** *realm* + specifies the Kerberos realm of the database. + +**-d** *dbname* + specifies the name under which the principal database is stored; + by default the database is that listed in :ref:`kdc.conf(5)`. The + password policy database and lock files are also derived from this + value. + +**-k** *mkeytype* + specifies the key type of the master key in the database. The + default is given by the **master_key_type** variable in + :ref:`kdc.conf(5)`. + +**-kv** *mkeyVNO* + Specifies the version number of the master key in the database; + the default is 1. Note that 0 is not allowed. + +**-M** *mkeyname* + principal name for the master key in the database. If not + specified, the name is determined by the **master_key_name** + variable in :ref:`kdc.conf(5)`. + +**-m** + specifies that the master database password should be read from + the keyboard rather than fetched from a file on disk. + +**-sf** *stash_file* + specifies the stash filename of the master database password. If + not specified, the filename is determined by the + **key_stash_file** variable in :ref:`kdc.conf(5)`. + +**-P** *password* + specifies the master database password. Using this option may + expose the password to other users on the system via the process + list. + +.. _kdb5_util_options_end: + + +COMMANDS +-------- + +create +~~~~~~ + +.. _kdb5_util_create: + + **create** [**-s**] + +Creates a new database. If the **-s** option is specified, the stash +file is also created. This command fails if the database already +exists. If the command is successful, the database is opened just as +if it had already existed when the program was first run. + +.. _kdb5_util_create_end: + +destroy +~~~~~~~ + +.. _kdb5_util_destroy: + + **destroy** [**-f**] + +Destroys the database, first overwriting the disk sectors and then +unlinking the files, after prompting the user for confirmation. With +the **-f** argument, does not prompt the user. + +.. _kdb5_util_destroy_end: + +stash +~~~~~ + +.. _kdb5_util_stash: + + **stash** [**-f** *keyfile*] + +Stores the master principal's keys in a stash file. The **-f** +argument can be used to override the *keyfile* specified in +:ref:`kdc.conf(5)`. + +.. _kdb5_util_stash_end: + +dump +~~~~ + +.. _kdb5_util_dump: + + **dump** [**-old**\|\ **-b6**\|\ **-b7**\|\ **-ov**\|\ **-r13**] + [**-verbose**] [**-mkey_convert**] [**-new_mkey_file** *mkey_file*] + [**-rev**] [**-recurse**] [*filename* [*principals*...]] + +Dumps the current Kerberos and KADM5 database into an ASCII file. By +default, the database is dumped in current format, "kdb5_util +load_dump version 6". If filename is not specified, or is the string +"-", the dump is sent to standard output. Options: + +**-old** + causes the dump to be in the Kerberos 5 Beta 5 and earlier dump + format ("kdb5_edit load_dump version 2.0"). + +**-b6** + causes the dump to be in the Kerberos 5 Beta 6 format ("kdb5_edit + load_dump version 3.0"). + +**-b7** + causes the dump to be in the Kerberos 5 Beta 7 format ("kdb5_util + load_dump version 4"). This was the dump format produced on + releases prior to 1.2.2. + +**-ov** + causes the dump to be in "ovsec_adm_export" format. + +**-r13** + causes the dump to be in the Kerberos 5 1.3 format ("kdb5_util + load_dump version 5"). This was the dump format produced on + releases prior to 1.8. + +**-r18** + causes the dump to be in the Kerberos 5 1.8 format ("kdb5_util + load_dump version 6"). This was the dump format produced on + releases prior to 1.11. + +**-verbose** + causes the name of each principal and policy to be printed as it + is dumped. + +**-mkey_convert** + prompts for a new master key. This new master key will be used to + re-encrypt principal key data in the dumpfile. The principal keys + themselves will not be changed. + +**-new_mkey_file** *mkey_file* + the filename of a stash file. The master key in this stash file + will be used to re-encrypt the key data in the dumpfile. The key + data in the database will not be changed. + +**-rev** + dumps in reverse order. This may recover principals that do not + dump normally, in cases where database corruption has occurred. + +**-recurse** + causes the dump to walk the database recursively (btree only). + This may recover principals that do not dump normally, in cases + where database corruption has occurred. In cases of such + corruption, this option will probably retrieve more principals + than the **-rev** option will. + +.. _kdb5_util_dump_end: + +load +~~~~ + +.. _kdb5_util_load: + + **load** [**-old**\|\ **-b6**\|\ **-b7**\|\ **-ov**\|\ **-r13**] + [**-hash**] [**-verbose**] [**-update**] *filename* [*dbname*] + +Loads a database dump from the named file into the named database. If +no option is given to determine the format of the dump file, the +format is detected automatically and handled as appropriate. Unless +the **-update** option is given, **load** creates a new database +containing only the data in the dump file, overwriting the contents of +any previously existing database. Note that when using the LDAP KDC +database module, the **-update** flag is required. + +Options: + +**-old** + requires the database to be in the Kerberos 5 Beta 5 and earlier + format ("kdb5_edit load_dump version 2.0"). + +**-b6** + requires the database to be in the Kerberos 5 Beta 6 format + ("kdb5_edit load_dump version 3.0"). + +**-b7** + requires the database to be in the Kerberos 5 Beta 7 format + ("kdb5_util load_dump version 4"). + +**-ov** + requires the database to be in "ovsec_adm_import" format. Must be + used with the **-update** option. + +**-r13** + requires the database to be in Kerberos 5 1.3 format ("kdb5_util + load_dump version 5"). This was the dump format produced on + releases prior to 1.8. + +**-r18** + requires the database to be in Kerberos 5 1.8 format ("kdb5_util + load_dump version 6"). This was the dump format produced on + releases prior to 1.11. + +**-hash** + requires the database to be stored as a hash. If this option is + not specified, the database will be stored as a btree. This + option is not recommended, as databases stored in hash format are + known to corrupt data and lose principals. + +**-verbose** + causes the name of each principal and policy to be printed as it + is dumped. + +**-update** + records from the dump file are added to or updated in the existing + database. (This is useful in conjunction with an ovsec_adm_export + format dump if you want to preserve per-principal policy + information, since the current default format does not contain + this data.) Otherwise, a new database is created containing only + what is in the dump file and the old one destroyed upon successful + completion. + +If specified, *dbname* overrides the value specified on the command +line or the default. + +.. _kdb5_util_load_end: + +ark +~~~ + + **ark** [**-e** *enc*:*salt*,...] *principal* + +Adds new random keys to *principal* at the next available key version +number. Keys for the current highest key version number will be +preserved. The **-e** option specifies the list of encryption and +salt types to be used for the new keys. + +add_mkey +~~~~~~~~ + + **add_mkey** [**-e** *etype*] [**-s**] + +Adds a new master key to the master key principal, but does not mark +it as active. Existing master keys will remain. The **-e** option +specifies the encryption type of the new master key; see +:ref:`Encryption_and_salt_types` in :ref:`kdc.conf(5)` for a list of +possible values. The **-s** option stashes the new master key in the +stash file, which will be created if it doesn't already exist. + +After a new master key is added, it should be propagated to slave +servers via a manual or periodic invocation of :ref:`kprop(8)`. Then, +the stash files on the slave servers should be updated with the +kdb5_util **stash** command. Once those steps are complete, the key +is ready to be marked active with the kdb5_util **use_mkey** command. + +use_mkey +~~~~~~~~ + + **use_mkey** *mkeyVNO* [*time*] + +Sets the activation time of the master key specified by *mkeyVNO*. +Once a master key becomes active, it will be used to encrypt newly +created principal keys. If no *time* argument is given, the current +time is used, causing the specified master key version to become +active immediately. The format for *time* is :ref:`getdate` string. + +After a new master key becomes active, the kdb5_util +**update_princ_encryption** command can be used to update all +principal keys to be encrypted in the new master key. + +list_mkeys +~~~~~~~~~~ + + **list_mkeys** + +List all master keys, from most recent to earliest, in the master key +principal. The output will show the kvno, enctype, and salt type for +each mkey, similar to the output of :ref:`kadmin(1)` **getprinc**. A +``*`` following an mkey denotes the currently active master key. + +purge_mkeys +~~~~~~~~~~~ + + **purge_mkeys** [**-f**] [**-n**] [**-v**] + +Delete master keys from the master key principal that are not used to +protect any principals. This command can be used to remove old master +keys all principal keys are protected by a newer master key. + +**-f** + does not prompt for confirmation. + +**-n** + performs a dry run, showing master keys that would be purged, but + not actually purging any keys. + +**-v** + gives more verbose output. + +update_princ_encryption +~~~~~~~~~~~~~~~~~~~~~~~ + + **update_princ_encryption** [**-f**] [**-n**] [**-v**] + [*princ-pattern*] + +Update all principal records (or only those matching the +*princ-pattern* glob pattern) to re-encrypt the key data using the +active database master key, if they are encrypted using older +versions, and give a count at the end of the number of principals +updated. If the **-f** option is not given, ask for confirmation +before starting to make changes. The **-v** option causes each +principal processed to be listed, with an indication as to whether it +needed updating or not. The **-n** option performs a dry run, only +showing the actions which would have been taken. + + +SEE ALSO +-------- + +:ref:`kadmin(1)` diff --git a/doc/admins/admin_commands/kprop.rst b/doc/admins/admin_commands/kprop.rst new file mode 100644 index 000000000..726c8cc2f --- /dev/null +++ b/doc/admins/admin_commands/kprop.rst @@ -0,0 +1,60 @@ +.. _kprop(8): + +kprop +===== + +SYNOPSIS +-------- + +**kprop** +[**-r** *realm*] +[**-f** *file*] +[**-d**] +[**-P** *port*] +[**-s** *keytab*] +*slave_host* + + +DESCRIPTION +----------- + +kprop is used to securely propagate a Kerberos V5 database dump file +from the master Kerberos server to a slave Kerberos server, which is +specified by *slave_host*. The dump file must be created by +:ref:`kdb5_util(8)`. + + +OPTIONS +------- + +**-r** *realm* + Specifies the realm of the master server. + +**-f** *file* + Specifies the filename where the dumped principal database file is + to be found; by default the dumped database file is normally + |kdcdir|\ ``/slave_datatrans``. + +**-P** *port* + Specifies the port to use to contact the :ref:`kpropd(8)` server + on the remote host. + +**-d** + Prints debugging information. + +**-s** *keytab* + Specifies the location of the keytab file. + + +ENVIRONMENT +----------- + +*kprop* uses the following environment variable: + +* **KRB5_CONFIG** + + +SEE ALSO +-------- + +:ref:`kpropd(8)`, :ref:`kdb5_util(8)`, :ref:`krb5kdc(8)` diff --git a/doc/admins/admin_commands/kpropd.rst b/doc/admins/admin_commands/kpropd.rst new file mode 100644 index 000000000..b5cebcc47 --- /dev/null +++ b/doc/admins/admin_commands/kpropd.rst @@ -0,0 +1,123 @@ +.. _kpropd(8): + +kpropd +====== + +SYNOPSIS +-------- + +**kpropd** +[**-r** *realm*] +[**-a** *acl_file*] +[**-f** *slave_dumpfile*] +[**-F** *principal_database*] +[**-p** *kdb5_util_prog*] +[**-P** *port*] +[**-d**] + +DESCRIPTION +----------- + +The *kpropd* command runs on the slave KDC server. It listens for +update requests made by the :ref:`kprop(8)` program. If incremental +propagation is enabled, it periodically requests incremental updates +from the master KDC. + +When the slave receives a kprop request from the master, kpropd +accepts the dumped KDC database and places it in a file, and then runs +:ref:`kdb5_util(8)` to load the dumped database into the active +database which is used by :ref:`krb5kdc(8)`. This allows the master +Kerberos server to use :ref:`kprop(8)` to propagate its database to +the slave servers. Upon a successful download of the KDC database +file, the slave Kerberos server will have an up-to-date KDC database. + +Where incremental propagation is not used, kpropd is commonly invoked +out of inetd(8) as a nowait service. This is done by adding a line to +the ``/etc/inetd.conf`` file which looks like this: + + :: + + kprop stream tcp nowait root /usr/local/sbin/kpropd kpropd + +kpropd can also run as a standalone daemon. This is required for +incremental propagation. But this is also useful for debugging +purposes. + +Incremental propagation may be enabled with the **iprop_enable** +variable in :ref:`kdc.conf(5)`. If incremental propagation is +enabled, the slave periodically polls the master KDC for updates, at +an interval determined by the **iprop_slave_poll** variable. If the +slave receives updates, kpropd updates its log file with any updates +from the master. :ref:`kproplog(8)` can be used to view a summary of +the update entry log on the slave KDC. If incremental propagation is +enabled, the principal ``kiprop/slavehostname@REALM`` (where +*slavehostname* is the name of the slave KDC host, and *REALM* is the +name of the Kerberos realm) must be present in the slave's keytab +file. + +:ref:`kproplog(8)` can be used to force full replication when iprop is +enabled. + + +OPTIONS +-------- + +**-r** *realm* + Specifies the realm of the master server. + +**-f** *file* + Specifies the filename where the dumped principal database file is + to be stored; by default the dumped database file is |kdcdir|\ + ``/from_master``. + +**-p** + Allows the user to specify the pathname to the :ref:`kdb5_util(8)` + program; by default the pathname used is |sbindir|\ + ``/kdb5_util``. + +**-S** + [DEPRECATED] Enable standalone mode. Normally kpropd is invoked by + inetd(8) so it expects a network connection to be passed to it + from inetd(8). If the **-S** option is specified, or if standard + input is not a socket, kpropd will put itself into the background, + and wait for connections on port 754 (or the port specified with the + **-P** option if given). + +**-d** + Turn on debug mode. In this mode, if the **-S** option is + selected, kpropd will not detach itself from the current job and + run in the background. Instead, it will run in the foreground and + print out debugging messages during the database propagation. + +**-P** + Allow for an alternate port number for kpropd to listen on. This + is only useful in combination with the **-S** option. + +**-a** *acl_file* + Allows the user to specify the path to the kpropd.acl file; by + default the path used is |kdcdir|\ ``/kpropd.acl``. + + +ENVIRONMENT +----------- + +kpropd uses the following environment variables: + +* **KRB5_CONFIG** +* **KRB5_KDC_PROFILE** + + +FILES +----- + +kpropd.acl + Access file for kpropd; the default location is + ``/usr/local/var/krb5kdc/kpropd.acl``. Each entry is a line + containing the principal of a host from which the local machine + will allow Kerberos database propagation via :ref:`kprop(8)`. + + +SEE ALSO +-------- + +:ref:`kprop(8)`, :ref:`kdb5_util(8)`, :ref:`krb5kdc(8)`, inetd(8) diff --git a/doc/admins/admin_commands/kproplog.rst b/doc/admins/admin_commands/kproplog.rst new file mode 100644 index 000000000..c7a0ea417 --- /dev/null +++ b/doc/admins/admin_commands/kproplog.rst @@ -0,0 +1,87 @@ +.. _kproplog(8): + +kproplog +======== + +SYNOPSIS +-------- + +**kproplog** [**-h**] [**-e** *num*] [-v] +**kproplog** [-R] + + +DESCRIPTION +----------- + +The kproplog command displays the contents of the KDC database update +log to standard output. It can be used to keep track of incremental +updates to the principal database. The update log file contains the +update log maintained by the :ref:`kadmind(8)` process on the master +KDC server and the :ref:`kpropd(8)` process on the slave KDC servers. +When updates occur, they are logged to this file. Subsequently any +KDC slave configured for incremental updates will request the current +data from the master KDC and update their log file with any updates +returned. + +The kproplog command requires read access to the update log file. It +will display update entries only for the KDC it runs on. + +If no options are specified, kproplog displays a summary of the update +log. If invoked on the master, kproplog also displays all of the +update entries. If invoked on a slave KDC server, kproplog displays +only a summary of the updates, which includes the serial number of the +last update received and the associated time stamp of the last update. + + +OPTIONS +------- + +**-R** + Reset the update log. This forces full resynchronization. If used + on a slave then that slave will request a full resync. If used on + the master then all slaves will request full resyncs. + +**-h** + Display a summary of the update log. This information includes + the database version number, state of the database, the number of + updates in the log, the time stamp of the first and last update, + and the version number of the first and last update entry. + +**-e** *num* + Display the last *num* update entries in the log. This is useful + when debugging synchronization between KDC servers. + +**-v** + Display individual attributes per update. An example of the + output generated for one entry: + + :: + + Update Entry + Update serial # : 4 + Update operation : Add + Update principal : test@EXAMPLE.COM + Update size : 424 + Update committed : True + Update time stamp : Fri Feb 20 23:37:42 2004 + Attributes changed : 6 + Principal + Key data + Password last changed + Modifying principal + Modification time + TL data + + +ENVIRONMENT +----------- + +kproplog uses the following environment variables: + +* **KRB5_KDC_PROFILE** + + +SEE ALSO +-------- + +:ref:`kpropd(8)` diff --git a/doc/admins/admin_commands/krb5kdc.rst b/doc/admins/admin_commands/krb5kdc.rst new file mode 100644 index 000000000..62afca4ee --- /dev/null +++ b/doc/admins/admin_commands/krb5kdc.rst @@ -0,0 +1,142 @@ +.. _krb5kdc(8): + +krb5kdc +======= + +SYNOPSIS +-------- + +**krb5kdc** +[**-x** *db_args*] +[**-d** *dbname*] +[**-k** *keytype*] +[**-M** *mkeyname*] +[**-p** *portnum*] +[**-m**] +[**-r** *realm*] +[**-n**] +[**-w** *numworkers*] +[**-P** *pid_file*] +[**-T** *time_offset*] + + +DESCRIPTION +----------- + +krb5kdc is the Kerberos version 5 Authentication Service and Key +Distribution Center (AS/KDC). + + +OPTIONS +------- + +The **-r** *realm* option specifies the realm for which the server +should provide service. + +The **-d** *dbname* option specifies the name under which the +principal database can be found. This option does not apply to the +LDAP database. + +The **-k** *keytype* option specifies the key type of the master key +to be entered manually as a password when **-m** is given; the default +is ``des-cbc-crc``. + +The **-M** *mkeyname* option specifies the principal name for the +master key in the database (usually ``K/M`` in the KDC's realm). + +The **-m** option specifies that the master database password should +be fetched from the keyboard rather than from a stash file. + +The **-n** option specifies that the KDC does not put itself in the +background and does not disassociate itself from the terminal. In +normal operation, you should always allow the KDC to place itself in +the background. + +The **-P** *pid_file* option tells the KDC to write its PID into +*pid_file* after it starts up. This can be used to identify whether +the KDC is still running and to allow init scripts to stop the correct +process. + +The **-p** *portnum* option specifies the default UDP port numbers +which the KDC should listen on for Kerberos version 5 requests, as a +comma-separated list. This value overrides the UDP port numbers +specified in the :ref:`kdcdefaults` section of :ref:`kdc.conf(5)`, but +may be overridden by realm-specific values. If no value is given from +any source, the default ports are 88 and 750. + +The **-w** *numworkers* option tells the KDC to fork *numworkers* +processes to listen to the KDC ports and process requests in parallel. +The top level KDC process (whose pid is recorded in the pid file if +the **-P** option is also given) acts as a supervisor. The supervisor +will relay SIGHUP signals to the worker subprocesses, and will +terminate the worker subprocess if the it is itself terminated or if +any other worker process exits. + +.. note:: On operating systems which do not have *pktinfo* support, + using worker processes will prevent the KDC from listening + for UDP packets on network interfaces created after the KDC + starts. + +The **-x** *db_args* option specifies database-specific arguments. +Options supported for the LDAP database module are: + + **-x** nconns= + Specifies the number of connections to be maintained per + LDAP server. + + **-x** host= + Specifies the LDAP server to connect to by URI. + + **-x** binddn= + Specifies the DN of the object used by the KDC server to bind + to the LDAP server. This object should have read and write + privileges to the realm container, the principal container, + and the subtree that is referenced by the realm. + + **-x** bindpwd= + Specifies the password for the above mentioned binddn. Using + this option may expose the password to other users on the + system via the process list; to avoid this, instead stash the + password using the **stashsrvpw** command of + :ref:`kdb5_ldap_util(8)`. + +The **-T** *offset* option specifies a time offset, in seconds, which +the KDC will operate under. It is intended only for testing purposes. + +EXAMPLE +------- + +The KDC may service requests for multiple realms (maximum 32 realms). +The realms are listed on the command line. Per-realm options that can +be specified on the command line pertain for each realm that follows +it and are superseded by subsequent definitions of the same option. + +For example: + + :: + + krb5kdc -p 2001 -r REALM1 -p 2002 -r REALM2 -r REALM3 + +specifies that the KDC listen on port 2001 for REALM1 and on port 2002 +for REALM2 and REALM3. Additionally, per-realm parameters may be +specified in the :ref:`kdc.conf(5)` file. The location of this file +may be specified by the **KRB5_KDC_PROFILE** environment variable. +Per-realm parameters specified in this file take precedence over +options specified on the command line. See the :ref:`kdc.conf(5)` +description for further details. + + +ENVIRONMENT +----------- + +krb5kdc uses the following environment variables: + +* **KRB5_CONFIG** +* **KRB5_KDC_PROFILE** + + +SEE ALSO +-------- + +:ref:`kdb5_util(8)`, :ref:`kdc.conf(5)`, :ref:`krb5.conf(5)`, +:ref:`kdb5_ldap_util(8)` diff --git a/doc/admins/admin_commands/ktutil.rst b/doc/admins/admin_commands/ktutil.rst new file mode 100644 index 000000000..d55ddc894 --- /dev/null +++ b/doc/admins/admin_commands/ktutil.rst @@ -0,0 +1,133 @@ +.. _ktutil(1): + +ktutil +====== + +SYNOPSIS +-------- + +**ktutil** + + +DESCRIPTION +----------- + +The ktutil command invokes a command interface from which an +administrator can read, write, or edit entries in a keytab or Kerberos +V4 srvtab file. + + +COMMANDS +-------- + +list +~~~~ + + **list** + +Displays the current keylist. + +Alias: **l** + +read_kt +~~~~~~~ + + **read_kt** *keytab* + +Read the Kerberos V5 keytab file *keytab* into the current keylist. + +Alias: **rkt** + +read_st +~~~~~~~ + + **read_st** *srvtab* + +Read the Kerberos V4 srvtab file *srvtab* into the current keylist. + +Alias: **rst** + +write_kt +~~~~~~~~ + + **write_kt** *keytab* + +Write the current keylist into the Kerberos V5 keytab file *keytab*. + +Alias: **wkt** + +write_st +~~~~~~~~ + + **write_st** *srvtab* + +Write the current keylist into the Kerberos V4 srvtab file *srvtab*. + +Alias: **wst** + +clear_list +~~~~~~~~~~ + + **clear_list** + +Clear the current keylist. + +Alias: **clear** + +delete_entry +~~~~~~~~~~~~ + + **delete_entry** *slot* + +Delete the entry in slot number *slot* from the current keylist. + +Alias: **delent** + +add_entry +~~~~~~~~~ + + **add_entry** {**-key**\|\ **-password**} **-p** *principal* + **-k** *kvno* **-e** *enctype* + +Add *principal* to keylist using key or password. + +Alias: **addent** + +list_requests +~~~~~~~~~~~~~ + + **list_requests** + +Displays a listing of available commands. + +Aliases: **lr**, **?** + +quit +~~~~ + + **quit** + +Quits ktutil. + +Aliases: **exit**, **q** + + +EXAMPLE +------- + + :: + + ktutil: add_entry -password -p alice@BLEEP.COM -k 1 -e + aes128-cts-hmac-sha1-96 + Password for alice@BLEEP.COM: + ktutil: add_entry -password -p alice@BLEEP.COM -k 1 -e + aes256-cts-hmac-sha1-96 + Password for alice@BLEEP.COM: + ktutil: write_kt keytab + ktutil: + + +SEE ALSO +-------- + +:ref:`kadmin(1)`, :ref:`kdb5_util(8)` diff --git a/doc/admins/admin_commands/sserver.rst b/doc/admins/admin_commands/sserver.rst new file mode 100644 index 000000000..61826dfaf --- /dev/null +++ b/doc/admins/admin_commands/sserver.rst @@ -0,0 +1,121 @@ +.. _sserver(8): + +sserver +======= + +SYNOPSIS +-------- + +**sserver** +[ **-p** *port* ] +[ **-S** *keytab* ] +[ *server_port* ] + + +DESCRIPTION +----------- + +sserver and :ref:`sclient(1)` are a simple demonstration client/server +application. When sclient connects to sserver, it performs a Kerberos +authentication, and then sserver returns to sclient the Kerberos +principal which was used for the Kerberos authentication. It makes a +good test that Kerberos has been successfully installed on a machine. + +The service name used by sserver and sclient is sample. Hence, +sserver will require that there be a keytab entry for the service +``sample/hostname.domain.name@REALM.NAME``. This keytab is generated +using the :ref:`kadmin(1)` program. The keytab file is usually +installed as |keytab|. + +The **-S** option allows for a different keytab than the default. + +sserver is normally invoked out of inetd(8), using a line in +``/etc/inetd.conf`` that looks like this: + + :: + + sample stream tcp nowait root /usr/local/sbin/sserver sserver + +Since ``sample`` is normally not a port defined in ``/etc/services``, +you will usually have to add a line to ``/etc/services`` which looks +like this: + + :: + + sample 13135/tcp + +When using sclient, you will first have to have an entry in the +Kerberos database, by using :ref:`kadmin(1)`, and then you have to get +Kerberos tickets, by using :ref:`kinit(1)`. Also, if you are running +the sclient program on a different host than the sserver it will be +connecting to, be sure that both hosts have an entry in /etc/services +for the sample tcp port, and that the same port number is in both +files. + +When you run sclient you should see something like this: + + :: + + sendauth succeeded, reply is: + reply len 32, contents: + You are nlgilman@JIMI.MIT.EDU + + +COMMON ERROR MESSAGES +--------------------- + +1) kinit returns the error: + + :: + + kinit: Client not found in Kerberos database while getting + initial credentials + + This means that you didn't create an entry for your username in the + Kerberos database. + +2) sclient returns the error: + + :: + + unknown service sample/tcp; check /etc/services + + This means that you don't have an entry in /etc/services for the + sample tcp port. + +3) sclient returns the error: + + :: + + connect: Connection refused + + This probably means you didn't edit /etc/inetd.conf correctly, or + you didn't restart inetd after editing inetd.conf. + +4) sclient returns the error: + + :: + + sclient: Server not found in Kerberos database while using + sendauth + + This means that the ``sample/hostname@LOCAL.REALM`` service was not + defined in the Kerberos database; it should be created using + :ref:`kadmin(1)`, and a keytab file needs to be generated to make + the key for that service principal available for sclient. + +5) sclient returns the error: + + :: + + sendauth rejected, error reply is: + "No such file or directory" + + This probably means sserver couldn't find the keytab file. It was + probably not installed in the proper directory. + + +SEE ALSO +-------- + +:ref:`sclient(1)`, services(5), inetd(8) diff --git a/doc/admins/advanced/index.rst b/doc/admins/advanced/index.rst new file mode 100644 index 000000000..20112bd2d --- /dev/null +++ b/doc/admins/advanced/index.rst @@ -0,0 +1,10 @@ +Advanced topics +=============== + + +.. toctree:: + :maxdepth: 1 + + ldapbackend.rst + retiring-des.rst + diff --git a/doc/admins/advanced/ldapbackend.rst b/doc/admins/advanced/ldapbackend.rst new file mode 100644 index 000000000..59c9eaa3c --- /dev/null +++ b/doc/admins/advanced/ldapbackend.rst @@ -0,0 +1,143 @@ +.. _ldap_be_ubuntu: + +LDAP backend on Ubuntu 10.4 (lucid) +=================================== + +Setting up Kerberos v1.9 with LDAP backend on Ubuntu 10.4 (Lucid Lynx) + + +Prerequisites +------------- + +Install the following packages: *slapd, ldap-utils* and *libldap2-dev* + +You can install the necessary packages with these commands:: + + sudo apt-get install slapd + sudo apt-get install ldap-utils + sudo apt-get install libldap2-dev + +Extend the user schema using schemas from standart OpenLDAP +distribution: *cosine, mics, nis, inetcomperson* :: + + ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/cosine.ldif + ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/mics.ldif + ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/nis.ldif + ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/inetcomperson.ldif + + +Building Kerberos from source +----------------------------- + +:: + + ./configure --with-ldap + make + sudo make install + + +Setting up Kerberos +------------------- + +Configuration +~~~~~~~~~~~~~ + +Update kdc.conf with the LDAP back-end information:: + + [realms] + EXAMPLE.COM = { + database_module = LDAP + } + + [dbmodules] + LDAP = { + db_library = kldap + ldap_kerberos_container_dn = cn=krbContainer,dc=example,dc=com + ldap_kdc_dn = cn=admin,dc=example,dc=com + ldap_kadmind_dn = cn=admin,dc=example,dc=com + ldap_service_password_file = /usr/local/var/krb5kdc/admin.stash + ldap_servers = ldapi:/// + } + + +Schema +~~~~~~ + +From the source tree copy +``src/plugins/kdb/ldap/libkdb_ldap/kerberos.schema`` into +``/etc/ldap/schema`` + +Warning: this step should be done after slapd is installed to avoid +problems with slapd installation. + +To convert kerberos.schema to run-time configuration (``cn=config``) +do the following: + +#. Create a temporary file ``/tmp/schema_convert.conf`` with the + following content:: + + include /etc/ldap/schema/kerberos.schema + +#. Create a temporary directory ``/tmp/krb5_ldif``. + +#. Run:: + + slaptest -f /tmp/schema_convert.conf -F /tmp/krb5_ldif + + This should in a new file named + ``/tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif``. + +#. Edit ``/tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif`` by + replacing the lines:: + + dn: cn={0}kerberos + cn: {0}kerberos + + with + + dn: cn=kerberos,cn=schema,cn=config + cn: kerberos + + Also, remove following attribute-value pairs:: + + structuralObjectClass: olcSchemaConfig + entryUUID: ... + creatorsName: cn=config + createTimestamp: ... + entryCSN: ... + modifiersName: cn=config + modifyTimestamp: ... + +#. Load the new schema with ldapadd (with the proper authentication):: + + ldapadd -Y EXTERNAL -H ldapi:/// -f /tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif + + which should result the message ``adding new entry + "cn=kerberos,cn=schema,cn=config"``. + + +Create Kerberos database +------------------------ + +Using LDAP administrator credentials, create Kerberos database and +master key stash:: + + kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// create -s + +Stash the LDAP administrative passwords:: + + kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// stashsrvpw cn=admin,dc=example,dc=com + +Start :ref:`krb5kdc(8)`:: + + krb5kdc + +To destroy database run:: + + kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// destroy -f + + +Useful references +----------------- + +* `Kerberos and LDAP `_ diff --git a/doc/admins/advanced/retiring-des.rst b/doc/admins/advanced/retiring-des.rst new file mode 100644 index 000000000..30f96776f --- /dev/null +++ b/doc/admins/advanced/retiring-des.rst @@ -0,0 +1,129 @@ +.. _retiring-des: + +Retiring DES +======================= + +Version 5 of the Kerberos protocol was originally implemented using +the Data Encryption Standard (DES) as a block cipher for encryption. +While it was considered secure at the time, advancements in computational +ability have rendered it vulnerable to brute force attacks on its 56-bit +keyspace. As such, it is now considered insecure and should not be +used (:rfc:`6649`). + +History +------- + +DES was used in the original Kerberos implementation, and was the +only cryptosystem in krb5 1.0. Partial support for triple-DES (3DES) was +added in version 1.1, with full support following in version 1.2. +The Advanced Encryption Standard (AES), which supersedes DES, gained +partial support in version 1.3.0 of krb5 and full support in version 1.3.2. +However, deployments of krb5 using Kerberos databases created with older +versions of krb5 will not necessarily start using strong crypto for +ordinary operation without administrator intervention. + +Types of keys +------------- + +The entire Kerberos database is encrypted using the database master +key, presently stored as ``K/M`` by default. Each entry in the +Kerberos database has a set of keys with different encryption types, +corresponding to that principal's current key version number. +For a user principal, these keys are derived from the user's password +via the various string2key functions for those encryption types; +for a service principal with keys stored in a keytab, the keys of +different encryption types are all stored in the keytab. +When a new principal is added or a principal's key is updated (for +example, due to a user password change), new keys are generated for +that principal with all of the different encryption types that the +KDC is configured to use (the **supported_enctypes** variable in kdc.conf). +This list can be overridden on a case-by-case basis using arguments +to :ref:`kadmin(1)`. + +When a Kerberos client initiates a Kerberos transaction, the client +requests a service ticket for a given service from the KDC; this service +ticket will contain only a single key, of a particular encryption type. +When sending its request to the KDC, the client can request a particular +list of encryption types, as controlled by the client machine's +:ref:`krb5.conf(5)` configuration file or specific API calls in the +client software. +To choose the encryption type for the service ticket's key, the KDC +must accomodate the client's preference and also confirm that the service +principal has a key in the Kerberos database of that encryption type. +Note that the encryption types supported by the krb5 installation on +the server that will receive the service ticket is not a factor in +the KDC's choice of encryption type; this information is not available +in the Kerberos protocol. In order to allow uninterrupted operation to +clients while migrating away from DES, care must be taken to ensure that +the krb5 installation on server machines is configured to support newer +encryption types before keys of those new encryption types are created +in the Kerberos database for those server principals. + +Upgrade procedure +----------------- + +This procedure assumes that the KDC software has already been upgraded +to a modern version of krb5 that supports non-DES keys, so that the +only remaining task is to update the actual keys used to service requests. + +While it is possible to upgrade individual service principals to non-DES +keys before transitioning the entire realm, it is probably best to +start with upgrading the key for the ticket-granting service principal, +``krbtgt/REALM``. Since the server that will handle service tickets +for this principal is the KDC itself, it is easy to guarantee that it +will be configured to support any encryption types which might be +selected. However, just creating a new key version (and new keys) for +that principal will invalidate all existing tickets issued against that +principal, which in practice means all tickets obtained by clients. +Instead, a new key can be created with the old key retained, so that +existing tickets will still function until their scheduled expiry +(see :ref:`changing_krbtgt_key`). + +Once the krbtgt key is updated, users will get non-DES (usually AES in +modern releases) session keys for their TGT, but subsequent requests +for service tickets will still get DES keys, because the database +entry for the service principal still only has DES keys. Application service +remains uninterrupted due to the key-selection procedure on the KDC. + +At this point, service administrators can update their services and the +servers behind them. If necessary, the krb5 installation should be +upgraded to a version supporting non-DES keys, and :ref:`krb5.conf(5)` +edited so that the default enctype list includes the additional enctypes +needed. Only when the service is configured to accept non-DES keys should +the key version number be incremented and new keys generated. +Until the KDC's configuration is changed to generate non-DES keys by +default, it is necessary to use :ref:`kadmin(1)` to produce new keys +with the desired enctypes; the ``-keepold`` functionality may also be +desired in some cases. When a single service principal is shared by +multiple backend servers in a load-balanced environment, it may be +necessary to schedule downtime or adjust the population in the load-balanced +pool in order to propagate the updated keytab to all hosts in the pool +with minimal service interruption. + +Once the high-visibility services have been rekeyed, it is probably +appropriate to change :ref:`kdc.conf(5)` to generate keys with the new +encryption types by default. This enables server administrators to generate +new keys with :ref:`k5srvutil(1)` ``change``, and causes user password +changes to add new encryption types for their entries. It will probably +be necessary to implement administrative controls to cause all user +principal keys to be updated in a reasonable period of time, whether +by forcing password changes or a password synchronization service that +has access to the current password and can add the new keys. + +Once all principals have been re-keyed, DES support can be disabled on the +KDC, and client machines can remove **allow_weak_crypto = true** from +their :ref:`krb5.conf(5)` configuration files, completing the migration. +For completeness, the kadmin **purgekeys** command should be used to +remove the old keylist for ``krbtgt/REALM`` which includes the single-DES +key(s), though the KDC will only issue new tickets using the highest +available kvno, which at this point does not have single-DES keys available. + +This procedure does not alter ``K/M@REALM``, the key used to encrypt the +Kerberos database itself. (This is the key stored in the stash file +on the KDC if stash files are used.) However, the security risk of +a single-DES key for ``K/M`` is minimal, given that access to material +encrypted in ``K/M`` (the Kerberos database) is generally tightly controlled. +If an attacker can gain access to the encrypted database, they likely +have access to the stash file as well, rendering the weak cryptography +broken by non-cryptographic means. As such, upgrading ``K/M`` to a stronger +encryption type is unlikely to be a high-priority task. diff --git a/doc/admins/appl_servers.rst b/doc/admins/appl_servers.rst new file mode 100644 index 000000000..f6474cdbd --- /dev/null +++ b/doc/admins/appl_servers.rst @@ -0,0 +1,147 @@ +Application servers +=================== + +If you need to install the Kerberos V5 programs on an application +server, please refer to the Kerberos V5 Installation Guide. Once you +have installed the software, you need to add that host to the Kerberos +database (see :ref:`add_mod_del_princs`), and generate a keytab for +that host, that contains the host's key. You also need to make sure +the host's clock is within your maximum clock skew of the KDCs. + + +Keytabs +------- + +A keytab is a host's copy of its own keylist, which is analogous to a +user's password. An application server that needs to authenticate +itself to the KDC has to have a keytab that contains its own principal +and key. Just as it is important for users to protect their +passwords, it is equally important for hosts to protect their keytabs. +You should always store keytab files on local disk, and make them +readable only by root, and you should never send a keytab file over a +network in the clear. Ideally, you should run the :ref:`kadmin(1)` +command to extract a keytab on the host on which the keytab is to +reside. + + +.. _add_princ_kt: + +Adding principals to keytabs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To generate a keytab, or to add a principal to an existing keytab, use +the **ktadd** command from kadmin. + +.. include:: admin_commands/kadmin_local.rst + :start-after: _ktadd: + :end-before: _ktadd_end: + + +Examples +######## + +Here is a sample session, using configuration files that enable only +AES encryption:: + + kadmin: ktadd host/daffodil.mit.edu@ATHENA.MIT.EDU + Entry for principal host/daffodil.mit.edu with kvno 2, encryption type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab + Entry for principal host/daffodil.mit.edu with kvno 2, encryption type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab + kadmin: + + +Removing principals from keytabs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To remove a principal from an existing keytab, use the kadmin +**ktremove** command. + +.. include:: admin_commands/kadmin_local.rst + :start-after: _ktremove: + :end-before: _ktremove_end: + + +Clock Skew +---------- + +A Kerberos application server host must keep its clock synchronized or +it will reject authentication requests from clients. Modern operating +systems typically provide a facility to maintain the correct time; +make sure it is enabled. This is especially important on virtual +machines, where clocks tend to drift more rapidly than normal machine +clocks. + +The default allowable clock skew is controlled by the **clockskew** +variable in :ref:`libdefaults`. + + +Getting DNS information correct +------------------------------- + +Several aspects of Kerberos rely on name service. When a hostname is +used to name a service, the Kerberos library canonicalizes the +hostname using forward and reverse name resolution. (The reverse name +resolution step can be turned off using the **rdns** variable in +:ref:`libdefaults`.) The result of this canonicalization must match +the principal entry in the host's keytab, or authentication will fail. + +Each host's canonical name must be the fully-qualified host name +(including the domain), and each host's IP address must +reverse-resolve to the canonical name. + +Configuration of hostnames varies by operating system. On the +application server itself, canonicalization will typically use the +``/etc/hosts`` file rather than the DNS. Ensure that the line for the +server's hostname is in the following form:: + + IP address fully-qualified hostname aliases + +Here is a sample ``/etc/hosts`` file:: + + # this is a comment + 127.0.0.1 localhost localhost.mit.edu + 10.0.0.6 daffodil.mit.edu daffodil trillium wake-robin + +The output of ``klist -k`` for this example host should look like:: + + viola# klist -k + Keytab name: /etc/krb5.keytab + KVNO Principal + ---- ------------------------------------------------------------ + 2 host/daffodil.mit.edu@ATHENA.MIT.EDU + +If you were to ssh to this host with a fresh credentials cache (ticket +file), and then :ref:`klist(1)`, the output should list a service +principal of ``host/daffodil.mit.edu@ATHENA.MIT.EDU``. + + +.. _conf_firewall: + +Configuring your firewall to work with Kerberos V5 +-------------------------------------------------- + +If you need off-site users to be able to get Kerberos tickets in your +realm, they must be able to get to your KDC. This requires either +that you have a slave KDC outside your firewall, or that you configure +your firewall to allow UDP requests into at least one of your KDCs, on +whichever port the KDC is running. (The default is port 88; other +ports may be specified in the KDC's :ref:`kdc.conf(5)` file.) +Similarly, if you need off-site users to be able to change their +passwords in your realm, they must be able to get to your Kerberos +admin server on the kpasswd port (which defaults to 464). If you need +off-site users to be able to administer your Kerberos realm, they must +be able to get to your Kerberos admin server on the administrative +port (which defaults to 749). + +If your on-site users inside your firewall will need to get to KDCs in +other realms, you will also need to configure your firewall to allow +outgoing TCP and UDP requests to port 88, and to port 464 to allow +password changes. If your on-site users inside your firewall will +need to get to Kerberos admin servers in other realms, you will also +need to allow outgoing TCP and UDP requests to port 749. + +If any of your KDCs are outside your firewall, you will need to allow +kprop requests to get through to the remote KDC. :ref:`kprop(8)` uses +the ``krb5_prop`` service on port 754 (tcp). + +The book *UNIX System Security*, by David Curry, is a good starting +point for learning to configure firewalls. diff --git a/doc/admins/backup_host.rst b/doc/admins/backup_host.rst new file mode 100644 index 000000000..a0c2a2878 --- /dev/null +++ b/doc/admins/backup_host.rst @@ -0,0 +1,34 @@ +Backups of secure hosts +======================= + +When you back up a secure host, you should exclude the host's keytab +file from the backup. If someone obtained a copy of the keytab from a +backup, that person could make any host masquerade as the host whose +keytab was compromised. In many configurations, knowledge of the +host's keytab also allows root access to the host. This could be +particularly dangerous if the compromised keytab was from one of your +KDCs. If the machine has a disk crash and the keytab file is lost, it +is easy to generate another keytab file. (See :ref:`add_princ_kt`.) +If you are unable to exclude particular files from backups, you should +ensure that the backups are kept as secure as the host's root +password. + + +Backing up the Kerberos database +-------------------------------- + +As with any file, it is possible that your Kerberos database could +become corrupted. If this happens on one of the slave KDCs, you might +never notice, since the next automatic propagation of the database +would install a fresh copy. However, if it happens to the master KDC, +the corrupted database would be propagated to all of the slaves during +the next propagation. For this reason, MIT recommends that you back +up your Kerberos database regularly. Because the master KDC is +continuously dumping the database to a file in order to propagate it +to the slave KDCs, it is a simple matter to have a cron job +periodically copy the dump file to a secure machine elsewhere on your +network. (Of course, it is important to make the host where these +backups are stored as secure as your KDCs, and to encrypt its +transmission across your network.) Then if your database becomes +corrupted, you can load the most recent dump onto the master KDC. +(See :ref:`restore_from_dump`.) diff --git a/doc/admins/conf_files/index.rst b/doc/admins/conf_files/index.rst new file mode 100644 index 000000000..078a17304 --- /dev/null +++ b/doc/admins/conf_files/index.rst @@ -0,0 +1,9 @@ +Configuration Files +=================== + +.. toctree:: + :maxdepth: 1 + + krb5_conf + kdc_conf + kadm5_acl diff --git a/doc/admins/conf_files/kadm5_acl.rst b/doc/admins/conf_files/kadm5_acl.rst new file mode 100644 index 000000000..4a8e0741e --- /dev/null +++ b/doc/admins/conf_files/kadm5_acl.rst @@ -0,0 +1,136 @@ +.. _kadm5.acl(5): + +kadm5.acl +========= + +DESCRIPTION +----------- + +The Kerberos :ref:`kadmind(8)` daemon uses an Access Control List +(ACL) file to manage access rights to the Kerberos database. +For operations that affect principals, the ACL file also controls +which principals can operate on which other principals. + +The default location of the Kerberos ACL file is +|kdcdir|\ ``/kadm5.acl`` unless this is overridden by the *acl_file* +variable in :ref:`kdc.conf(5)`. + +SYNTAX +------ + +Empty lines and lines starting with the sharp sign (``#``) are +ignored. Lines containing ACL entries have the format: + + :: + + principal permissions [target_principal [restrictions] ] + +.. note:: Line order in the ACL file is important. The first matching entry + will control access for an actor principal on a target principal. + +*principal* + (Partially or fully qualified Kerberos principal name.) Specifies + the principal whose permissions are to be set. + + Each component of the name may be wildcarded using the ``*`` + character. + +*permissions* + Specifies what operations may or may not be performed by a + *principal* matching a particular entry. This is a string of one or + more of the following list of characters or their upper-case + counterparts. If the character is *upper-case*, then the operation + is disallowed. If the character is *lower-case*, then the operation + is permitted. + + == ====================================================== + a [Dis]allows the addition of principals or policies + c [Dis]allows the changing of passwords for principals + d [Dis]allows the deletion of principals or policies + i [Dis]allows inquiries about principals or policies + l [Dis]allows the listing of principals or policies + m [Dis]allows the modification of principals or policies + p [Dis]allows the propagation of the principal database (used in :ref:`incr_db_prop`) + s [Dis]allows the explicit setting of the key for a principal + x Short for admcil. All privileges + \* Same as x. + == ====================================================== + + +*target_principal* + (Optional. Partially or fully qualified Kerberos principal name.) + Specifies the principal on which *permissions* may be applied. + Each component of the name may be wildcarded using the ``*`` + character. + + *target_principal* can also include back-references to *principal*, + in which ``*number`` matches the component number in *principal*. + +*restrictions* + (Optional) A string of flags. Allowed restrictions are: + + {+\|-}\ *flagname* + flag is forced to the indicated value. The permissible flags + are the same as the + and - flags for the kadmin + :ref:`add_principal` and :ref:`modify_principal` commands. + + *-clearpolicy* + policy is forced to be empty. + + *-policy pol* + policy is forced to be *pol*. + + -{*expire, pwexpire, maxlife, maxrenewlife*} *time* + (:ref:`getdate` string) associated value will be forced to + MIN(*time*, requested value). + + The above flags act as restrictions on any add or modify operation + which is allowed due to that ACL line. + +.. warning:: + If the kadmind ACL file is modified, the kadmind daemon needs to be + restarted for changes to take effect. + +EXAMPLE +------- + +Here is an example of a kadm5.acl file. + + :: + + */admin@ATHENA.MIT.EDU * # line 1 + joeadmin@ATHENA.MIT.EDU ADMCIL # line 2 + joeadmin/*@ATHENA.MIT.EDU il */root@ATHENA.MIT.EDU # line 3 + */root@ATHENA.MIT.EDU cil *1@ATHENA.MIT.EDU # line 4 + */*@ATHENA.MIT.EDU i # line 5 + */admin@EXAMPLE.COM x * -maxlife 9h -postdateable # line 6 + +(line 1) Any principal in the ``ATHENA.MIT.EDU`` realm with +an ``admin`` instance has all administrative privileges. + +(lines 1-3) The user ``joeadmin`` has all permissions with his +``admin`` instance, ``joeadmin/admin@ATHENA.MIT.EDU`` (matches line +1). He has no permissions at all with his null instance, +``joeadmin@ATHENA.MIT.EDU`` (matches line 2). His ``root`` and other +non-``admin``, non-null instances (e.g., ``extra`` or ``dbadmin``) have +inquire and list permissions with any principal that has the +instance ``root`` (matches line 3). + +(line 4) Any ``root`` principal in ``ATHENA.MIT.EDU`` can inquire, list, +or change the password of their null instance, but not any other +null instance. (Here, "\*1" denotes a back-reference to the first +component of the actor principal.) + +(line 5) Any principal in the realm ``ATHENA.MIT.EDU`` (except for +``joeadmin@ATHENA.MIT.EDU``, as mentioned above) has inquire +privileges. + +(line 6) Finally, any principal with an ``admin`` instance in ``EXAMPLE.COM`` +has all permissions, but any principal that they create or modify will +not be able to get postdateable tickets or tickets with a life of +longer than 9 hours. + +SEE ALSO +-------- + +:ref:`kdc.conf(5)`, :ref:`kadmind(8)` diff --git a/doc/admins/conf_files/kdc_conf.rst b/doc/admins/conf_files/kdc_conf.rst new file mode 100644 index 000000000..7ded12dc0 --- /dev/null +++ b/doc/admins/conf_files/kdc_conf.rst @@ -0,0 +1,711 @@ +.. _kdc.conf(5): + +kdc.conf +======== + +The kdc.conf file supplements :ref:`krb5.conf(5)` for programs which +are typically only used on a KDC, such as the :ref:`krb5kdc(8)` and +:ref:`kadmind(8)` daemons and the :ref:`kdb5_util(8)` program. +Relations documented here may also be specified in krb5.conf. + +Normally, the kdc.conf file is found in the KDC state directory, +|kdcdir|. You can override the default location by setting the +environment variable **KRB5_KDC_PROFILE**. + +Please note that you need to restart the KDC daemon for any configuration +changes to take effect. + +Structure +--------- + +The kdc.conf file is set up in the same format as the +:ref:`krb5.conf(5)` file. + + +Sections +-------- + +The kdc.conf file may contain the following sections: + +==================== ================================================= +:ref:`kdcdefaults` Default values for KDC behavior +:ref:`kdc_realms` Realm-specific database configuration and settings +:ref:`dbdefaults` Default database settings +:ref:`dbmodules` Per-database settings +:ref:`logging` Controls how Kerberos daemons perform logging +==================== ================================================= + + +.. _kdcdefaults: + +[kdcdefaults] +~~~~~~~~~~~~~ + +With one exception, relations in the [kdcdefaults] section specify +default values for realm variables, to be used if the [realms] +subsection does not contain a relation for the tag. See the +:ref:`kdc_realms` section for the definitions of these relations. + +* **host_based_services** +* **kdc_ports** +* **kdc_tcp_ports** +* **no_host_referral** +* **restrict_anonymous_to_tgt** + +**kdc_max_dgram_reply_size** + Specifies the maximum packet size that can be sent over UDP. The + default value is 4096 bytes. + + +.. _kdc_realms: + +[realms] +~~~~~~~~ + +Each tag in the [realms] section is the name of a Kerberos realm. +The value of the tag is a subsection where the relations define KDC +parameters for that particular realm. + +For each realm, the following tags may be specified: + +**acl_file** + (String.) Location of the access control list file that + :ref:`kadmind(8)` uses to determine which principals are allowed + which permissions on the Kerberos database. The default value is + |kdcdir|\ ``/kadm5.acl``. For more information on Kerberos ACL + file see :ref:`kadm5.acl(5)`. + +**database_module** + This relation indicates the name of the configuration section + under :ref:`dbmodules` for database specific parameters used by + the loadable database library. + +**database_name** + (String.) This string specifies the location of the Kerberos + database for this realm, if the DB2 back-end is being used. If a + **database_module** is specified for the realm and the + corresponding module contains a **database_name** parameter, that + value will take precedence over this one. The default value is + |kdcdir|\ ``/principal``. + +**default_principal_expiration** + (:ref:`abstime` string.) Specifies the default expiration date of + principals created in this realm. The default value is 0, which + means no expiration date. + +**default_principal_flags** + (Flag string.) Specifies the default attributes of principals + created in this realm. The format for this string is a + comma-separated list of flags, with '+' before each flag that + should be enabled and '-' before each flag that should be + disabled. The **postdateable**, **forwardable**, **tgt-based**, + **renewable**, **proxiable**, **dup-skey**, **allow-tickets**, and + **service** flags default to enabled. + + There are a number of possible flags: + + **allow-tickets** + Enabling this flag means that the KDC will issue tickets for + this principal. Disabling this flag essentially deactivates + the principal within this realm. + + **dup-skey** + Enabling this flag allows the principal to obtain a session + key for another user, permitting user-to-user authentication + for this principal. + + **forwardable** + Enabling this flag allows the principal to obtain forwardable + tickets. + + **hwauth** + If this flag is enabled, then the principal is required to + preauthenticate using a hardware device before receiving any + tickets. + + **no-auth-data-required** + Enabling this flag prevents PAC data from being added to + service tickets for the principal. + + **ok-as-delegate** + If this flag is enabled, it hints the client that credentials + can and should be delegated when authenticating to the + service. + + **ok-to-auth-as-delegate** + Enabling this flag allows the principal to use S4USelf tickets. + + **postdateable** + Enabling this flag allows the principal to obtain postdateable + tickets. + + **preauth** + If this flag is enabled on a client principal, then that + principal is required to preauthenticate to the KDC before + receiving any tickets. On a service principal, enabling this + flag means that service tickets for this principal will only + be issued to clients with a TGT that has the preauthenticated + bit set. + + **proxiable** + Enabling this flag allows the principal to obtain proxy + tickets. + + **pwchange** + Enabling this flag forces a password change for this + principal. + + **pwservice** + If this flag is enabled, it marks this principal as a password + change service. This should only be used in special cases, + for example, if a user's password has expired, then the user + has to get tickets for that principal without going through + the normal password authentication in order to be able to + change the password. + + **renewable** + Enabling this flag allows the principal to obtain renewable + tickets. + + **service** + Enabling this flag allows the the KDC to issue service tickets + for this principal. + + **tgt-based** + Enabling this flag allows a principal to obtain tickets based + on a ticket-granting-ticket, rather than repeating the + authentication process that was used to obtain the TGT. + +**dict_file** + (String.) Location of the dictionary file containing strings that + are not allowed as passwords. If none is specified or if there is + no policy assigned to the principal, no dictionary checks of + passwords will be performed. + +**host_based_services** + (Whitespace- or comma-separated list.) Lists services which will + get host-based referral processing even if the server principal is + not marked as host-based by the client. + +**iprop_enable** + (Boolean value.) Specifies whether incremental database + propagation is enabled. The default value is false. + +**iprop_master_ulogsize** + (Integer.) Specifies the maximum number of log entries to be + retained for incremental propagation. The maximum value is 2500; + the default value is 1000. + +**iprop_slave_poll** + (Delta time string.) Specifies how often the slave KDC polls for + new updates from the master. The default value is ``2m`` (that + is, two minutes). + +**iprop_port** + (Port number.) Specifies the port number to be used for + incremental propagation. This is required in both master and + slave configuration files. + +**iprop_resync_timeout** + (Delta time string.) Specifies the amount of time to wait for a + full propagation to complete. This is optional in configuration + files, and is used by slave KDCs only. The default value is 5 + minutes (``5m``). + +**iprop_logfile** + (File name.) Specifies where the update log file for the realm + database is to be stored. The default is to use the + **database_name** entry from the realms section of the krb5 config + file, with ``.ulog`` appended. (NOTE: If **database_name** isn't + specified in the realms section, perhaps because the LDAP database + back end is being used, or the file name is specified in the + [dbmodules] section, then the hard-coded default for + **database_name** is used. Determination of the **iprop_logfile** + default value will not use values from the [dbmodules] section.) + +**kadmind_port** + (Port number.) Specifies the port on which the :ref:`kadmind(8)` + daemon is to listen for this realm. The assigned port for kadmind + is 749, which is used by default. + +**key_stash_file** + (String.) Specifies the location where the master key has been + stored (via kdb5_util stash). The default is |kdcdir|\ + ``/.k5.REALM``, where *REALM* is the Kerberos realm. + +**kdc_ports** + (Whitespace- or comma-separated list.) Lists the ports on which + the Kerberos server should listen for UDP requests, as a + comma-separated list of integers. The default value is + ``88,750``, which are the assigned Kerberos port and the port + historically used by Kerberos V4. + +**kdc_tcp_ports** + (Whitespace- or comma-separated list.) Lists the ports on which + the Kerberos server should listen for TCP connections, as a + comma-separated list of integers. If this relation is not + specified, the compiled-in default is not to listen for TCP + connections at all. + + If you wish to change this (note that the current implementation + has little protection against denial-of-service attacks), the + standard port number assigned for Kerberos TCP traffic is port 88. + +**master_key_name** + (String.) Specifies the name of the principal associated with the + master key. The default is ``K/M``. + +**master_key_type** + (Key type string.) Specifies the master key's key type. The + default value for this is |defmkey|. For a list of all possible + values, see :ref:`Encryption_and_salt_types`. + +**max_life** + (:ref:`duration` string.) Specifies the maximum time period for + which a ticket may be valid in this realm. The default value is + 24 hours. + +**max_renewable_life** + (:ref:`duration` string.) Specifies the maximum time period + during which a valid ticket may be renewed in this realm. + The default value is 0. + +**no_host_referral** + (Whitespace- or comma-separated list.) Lists services to block + from getting host-based referral processing, even if the client + marks the server principal as host-based or the service is also + listed in **host_based_services**. ``no_host_referral = *`` will + disable referral processing altogether. + +**des_crc_session_supported** + (Boolean value). If set to true, the KDC will assume that service + principals support des-cbc-crc for session key enctype negotiation + purposes. If **allow_weak_crypto** in :ref:`libdefaults` is + false, or if des-cbc-crc is not a permitted enctype, then this + variable has no effect. Defaults to true. + +**reject_bad_transit** + (Boolean value.) If set to true, the KDC will check the list of + transited realms for cross-realm tickets against the transit path + computed from the realm names and the capaths section of its + :ref:`krb5.conf(5)` file; if the path in the ticket to be issued + contains any realms not in the computed path, the ticket will not + be issued, and an error will be returned to the client instead. + If this value is set to false, such tickets will be issued + anyways, and it will be left up to the application server to + validate the realm transit path. + + If the disable-transited-check flag is set in the incoming + request, this check is not performed at all. Having the + **reject_bad_transit** option will cause such ticket requests to + be rejected always. + + This transit path checking and config file option currently apply + only to TGS requests. + + The default value is true. + +**restrict_anonymous_to_tgt** + (Boolean value.) If set to true, the KDC will reject ticket + requests from anonymous principals to service principals other + than the realm's ticket-granting service. This option allows + anonymous PKINIT to be enabled for use as FAST armor tickets + without allowing anonymous authentication to services. The + default value is false. + +**supported_enctypes** + (List of *key*:*salt* strings.) Specifies the default key/salt + combinations of principals for this realm. Any principals created + through :ref:`kadmin(1)` will have keys of these types. The + default value for this tag is |defkeysalts|. For lists of + possible values, see :ref:`Encryption_and_salt_types`. + + +.. _dbdefaults: + +[dbdefaults] +~~~~~~~~~~~~ + +The [dbdefaults] section specifies default values for some database +parameters, to be used if the [dbmodules] subsection does not contain +a relation for the tag. See the :ref:`dbmodules` section for the +definitions of these relations. + +* **ldap_kerberos_container_dn** +* **ldap_kdc_dn** +* **ldap_kadmind_dn** +* **ldap_service_password_file** +* **ldap_servers** +* **ldap_conns_per_server** + + +.. _dbmodules: + +[dbmodules] +~~~~~~~~~~~ + +The [dbmodules] section contains parameters used by the KDC database +library and database modules. + +The following tag may be specified in the [dbmodules] section: + +**db_module_dir** + This tag controls where the plugin system looks for modules. The + value should be an absolute path. + +Other tags in the [dbmodules] section name a configuration subsection +for parameters which can be referred to by a realm's +**database_module** parameter. The following tags may be specified in +the subsection: + +**database_name** + This DB2-specific tag indicates the location of the database in + the filesystem. The default is |kdcdir|\ ``/principal``. + +**db_library** + This tag indicates the name of the loadable database module. The + value should be ``db2`` for the DB2 module and ``kldap`` for the + LDAP module. + +**disable_last_success** + If set to ``true``, suppresses KDC updates to the "Last successful + authentication" field of principal entries requiring + preauthentication. Setting this flag may improve performance. + (Principal entries which do not require preauthentication never + update the "Last successful authentication" field.). First + introduced in version 1.9. + +**disable_lockout** + If set to ``true``, suppresses KDC updates to the "Last failed + authentication" and "Failed password attempts" fields of principal + entries requiring preauthentication. Setting this flag may + improve performance, but also disables account lockout. First + introduced in version 1.9. + +**ldap_conns_per_server** + This LDAP-specific tag indicates the number of connections to be + maintained per LDAP server. + +**ldap_kadmind_dn** + This LDAP-specific tag indicates the default bind DN for the + :ref:`kadmind(8)` daemon. kadmind does a login to the directory + as this object. This object should have the rights to read and + write the Kerberos data in the LDAP database. + +**ldap_kdc_dn** + This LDAP-specific tag indicates the default bind DN for the + :ref:`krb5kdc(8)` daemon. The KDC does a login to the directory + as this object. This object should have the rights to read the + Kerberos data in the LDAP database, and to write data unless + **disable_lockout** and **disable_last_success** are true. + +**ldap_kerberos_container_dn** + This LDAP-specific tag indicates the DN of the container object + where the realm objects will be located. + +**ldap_servers** + This LDAP-specific tag indicates the list of LDAP servers that the + Kerberos servers can connect to. The list of LDAP servers is + whitespace-separated. The LDAP server is specified by a LDAP URI. + It is recommended to use ``ldapi:`` or ``ldaps:`` URLs to connect + to the LDAP server. + +**ldap_service_password_file** + This LDAP-specific tag indicates the file containing the stashed + passwords (created by ``kdb5_ldap_util stashsrvpw``) for the + **ldap_kadmind_dn** and **ldap_kdc_dn** objects. This file must + be kept secure. + + +.. _logging: + +[logging] +~~~~~~~~~ + +The [logging] section indicates how :ref:`krb5kdc(8)` and +:ref:`kadmind(8)` perform logging. The keys in this section are +daemon names, which may be one of: + +**admin_server** + Specifies how :ref:`kadmind(8)` performs logging. + +**kdc** + Specifies how :ref:`krb5kdc(8)` performs logging. + +**default** + Specifies how either daemon performs logging in the absence of + relations specific to the daemon. + +Values are of the following forms: + +**FILE=**\ *filename* or **FILE:**\ *filename* + This value causes the daemon's logging messages to go to the + *filename*. If the ``=`` form is used, the file is overwritten. + If the ``:`` form is used, the file is appended to. + +**STDERR** + This value causes the daemon's logging messages to go to its + standard error stream. + +**CONSOLE** + This value causes the daemon's logging messages to go to the + console, if the system supports it. + +**DEVICE=**\ ** + This causes the daemon's logging messages to go to the specified + device. + +**SYSLOG**\ [\ **:**\ *severity*\ [\ **:**\ *facility*\ ]] + This causes the daemon's logging messages to go to the system log. + + The severity argument specifies the default severity of system log + messages. This may be any of the following severities supported + by the syslog(3) call, minus the ``LOG_`` prefix: **EMERG**, + **ALERT**, **CRIT**, **ERR**, **WARNING**, **NOTICE**, **INFO**, + and **DEBUG**. + + The facility argument specifies the facility under which the + messages are logged. This may be any of the following facilities + supported by the syslog(3) call minus the LOG\_ prefix: **KERN**, + **USER**, **MAIL**, **DAEMON**, **AUTH**, **LPR**, **NEWS**, + **UUCP**, **CRON**, and **LOCAL0** through **LOCAL7**. + + If no severity is specified, the default is **ERR**. If no + facility is specified, the default is **AUTH**. + +In the following example, the logging messages from the KDC will go to +the console and to the system log under the facility LOG_DAEMON with +default severity of LOG_INFO; and the logging messages from the +administrative server will be appended to the file +``/var/adm/kadmin.log`` and sent to the device ``/dev/tty04``. + + :: + + [logging] + kdc = CONSOLE + kdc = SYSLOG:INFO:DAEMON + admin_server = FILE:/var/adm/kadmin.log + admin_server = DEVICE=/dev/tty04 + + +PKINIT options +-------------- + +.. note:: The following are pkinit-specific options. These values may + be specified in [kdcdefaults] as global defaults, or within + a realm-specific subsection of [realms]. Also note that a + realm-specific value over-rides, does not add to, a generic + [kdcdefaults] specification. The search order is: + +1. realm-specific subsection of [realms], + + :: + + [realms] + EXAMPLE.COM = { + pkinit_anchors = FILE:/usr/local/example.com.crt + } + +2. generic value in the [kdcdefaults] section. + + :: + + [kdcdefaults] + pkinit_anchors = DIR:/usr/local/generic_trusted_cas/ + +For information about the syntax of some of these options, see +:ref:`Specifying PKINIT identity information ` in +:ref:`krb5.conf(5)`. + +**pkinit_anchors** + Specifies the location of trusted anchor (root) certificates which + the KDC trusts to sign client certificates. This option is + required if pkinit is to be supported by the KDC. This option may + be specified multiple times. + +**pkinit_dh_min_bits** + Specifies the minimum number of bits the KDC is willing to accept + for a client's Diffie-Hellman key. The default is 2048. + +**pkinit_allow_upn** + Specifies that the KDC is willing to accept client certificates + with the Microsoft UserPrincipalName (UPN) Subject Alternative + Name (SAN). This means the KDC accepts the binding of the UPN in + the certificate to the Kerberos principal name. The default value + is false. + + Without this option, the KDC will only accept certificates with + the id-pkinit-san as defined in :rfc:`4556`. There is currently + no option to disable SAN checking in the KDC. + +**pkinit_eku_checking** + This option specifies what Extended Key Usage (EKU) values the KDC + is willing to accept in client certificates. The values + recognized in the kdc.conf file are: + + **kpClientAuth** + This is the default value and specifies that client + certificates must have the id-pkinit-KPClientAuth EKU as + defined in :rfc:`4556`. + + **scLogin** + If scLogin is specified, client certificates with the + Microsoft Smart Card Login EKU (id-ms-kp-sc-logon) will be + accepted. + + **none** + If none is specified, then client certificates will not be + checked to verify they have an acceptable EKU. The use of + this option is not recommended. + +**pkinit_identity** + Specifies the location of the KDC's X.509 identity information. + This option is required if pkinit is to be supported by the KDC. + +**pkinit_kdc_ocsp** + Specifies the location of the KDC's OCSP. + +**pkinit_mapping_file** + Specifies the name of the ACL pkinit mapping file. This file maps + principals to the certificates that they can use. + +**pkinit_pool** + Specifies the location of intermediate certificates which may be + used by the KDC to complete the trust chain between a client's + certificate and a trusted anchor. This option may be specified + multiple times. + +**pkinit_revoke** + Specifies the location of Certificate Revocation List (CRL) + information to be used by the KDC when verifying the validity of + client certificates. This option may be specified multiple times. + +**pkinit_require_crl_checking** + The default certificate verification process will always check the + available revocation information to see if a certificate has been + revoked. If a match is found for the certificate in a CRL, + verification fails. If the certificate being verified is not + listed in a CRL, or there is no CRL present for its issuing CA, + and **pkinit_require_crl_checking** is false, then verification + succeeds. + + However, if **pkinit_require_crl_checking** is true and there is + no CRL information available for the issuing CA, then verification + fails. + + **pkinit_require_crl_checking** should be set to true if the + policy is such that up-to-date CRLs must be present for every CA. + + +.. _Encryption_and_salt_types: + +Encryption and salt types +------------------------- + +Any tag in the configuration files which requires a list of encryption +types can be set to some combination of the following strings. +Encryption types marked as "weak" are available for compatibility but +not recommended for use. + +==================================================== ========================================================= +des-cbc-crc DES cbc mode with CRC-32 (weak) +des-cbc-md4 DES cbc mode with RSA-MD4 (weak) +des-cbc-md5 DES cbc mode with RSA-MD5 (weak) +des-cbc-raw DES cbc mode raw (weak) +des3-cbc-raw Triple DES cbc mode raw (weak) +des3-cbc-sha1 des3-hmac-sha1 des3-cbc-sha1-kd Triple DES cbc mode with HMAC/sha1 +des-hmac-sha1 DES with HMAC/sha1 (weak) +aes256-cts-hmac-sha1-96 aes256-cts AES-256 CTS mode with 96-bit SHA-1 HMAC +aes128-cts-hmac-sha1-96 aes128-cts AES-128 CTS mode with 96-bit SHA-1 HMAC +arcfour-hmac rc4-hmac arcfour-hmac-md5 RC4 with HMAC/MD5 +arcfour-hmac-exp rc4-hmac-exp arcfour-hmac-md5-exp Exportable RC4 with HMAC/MD5 (weak) +des The DES family: des-cbc-crc, des-cbc-md5, and des-cbc-md4 (weak) +des3 The triple DES family: des3-cbc-sha1 +aes The AES family: aes256-cts-hmac-sha1-96 and aes128-cts-hmac-sha1-96 +rc4 The RC4 family: arcfour-hmac +==================================================== ========================================================= + +The string **DEFAULT** can be used to refer to the default set of +types for the variable in question. Types or families can be removed +from the current list by prefixing them with a minus sign ("-"). +Types or families can be prefixed with a plus sign ("+") for symmetry; +it has the same meaning as just listing the type or family. For +example, "``DEFAULT -des``" would be the default set of encryption +types with DES types removed, and "``des3 DEFAULT``" would be the +default set of encryption types with triple DES types moved to the +front. + +While **aes128-cts** and **aes256-cts** are supported for all Kerberos +operations, they are not supported by very old versions of our GSSAPI +implementation (krb5-1.3.1 and earlier). Services running versions of +krb5 without AES support must not be given AES keys in the KDC +database. + +Kerberos keys for users are usually derived from passwords. To ensure +that people who happen to pick the same password do not have the same +key, Kerberos 5 incorporates more information into the key using +something called a salt. The supported salt types are as follows: + +================= ============================================ +normal default for Kerberos Version 5 +v4 the only type used by Kerberos Version 4 (no salt) +norealm same as the default, without using realm information +onlyrealm uses only realm information as the salt +afs3 AFS version 3, only used for compatibility with Kerberos 4 in AFS +special generate a random salt +================= ============================================ + + +Sample kdc.conf File +-------------------- + +Here's an example of a kdc.conf file: + + :: + + [kdcdefaults] + kdc_ports = 88 + + [realms] + ATHENA.MIT.EDU = { + kadmind_port = 749 + max_life = 12h 0m 0s + max_renewable_life = 7d 0h 0m 0s + master_key_type = des3-hmac-sha1 + supported_enctypes = des3-hmac-sha1:normal des-cbc-crc:normal des-cbc-crc:v4 + database_module = openldap_ldapconf + } + + [logging] + kdc = FILE:/usr/local/var/krb5kdc/kdc.log + admin_server = FILE:/usr/local/var/krb5kdc/kadmin.log + + [dbdefaults] + ldap_kerberos_container_dn = cn=krbcontainer,dc=mit,dc=edu + + [dbmodules] + openldap_ldapconf = { + db_library = kldap + disable_last_success = true + ldap_kdc_dn = "cn=krbadmin,dc=mit,dc=edu" + # this object needs to have read rights on + # the realm container and principal subtrees + ldap_kadmind_dn = "cn=krbadmin,dc=mit,dc=edu" + # this object needs to have read and write rights on + # the realm container and principal subtrees + ldap_service_password_file = /etc/kerberos/service.keyfile + ldap_servers = ldaps://kerberos.mit.edu + ldap_conns_per_server = 5 + } + + +FILES +------ + +|kdcdir|\ ``/kdc.conf`` + + +SEE ALSO +--------- + +:ref:`krb5.conf(5)`, :ref:`krb5kdc(8)`, :ref:`kadm5.acl(5)` diff --git a/doc/admins/conf_files/krb5_conf.rst b/doc/admins/conf_files/krb5_conf.rst new file mode 100644 index 000000000..996f93bc7 --- /dev/null +++ b/doc/admins/conf_files/krb5_conf.rst @@ -0,0 +1,1056 @@ +.. _krb5.conf(5): + +krb5.conf +========= + +The krb5.conf file contains Kerberos configuration information, +including the locations of KDCs and admin servers for the Kerberos +realms of interest, defaults for the current realm and for Kerberos +applications, and mappings of hostnames onto Kerberos realms. +Normally, you should install your krb5.conf file in the directory +``/etc``. You can override the default location by setting the +environment variable **KRB5_CONFIG**. + + +Structure +--------- + +The krb5.conf file is set up in the style of a Windows INI file. +Sections are headed by the section name, in square brackets. Each +section may contain zero or more relations, of the form: + + :: + + foo = bar + +or + :: + + fubar = { + foo = bar + baz = quux + } + +Placing a '\*' at the end of a line indicates that this is the *final* +value for the tag. This means that neither the remainder of this +configuration file nor any other configuration file will be checked +for any other values for this tag. + +For example, if you have the following lines: + :: + + foo = bar* + foo = baz + +then the second value of ``foo`` (``baz``) would never be read. + +The krb5.conf file can include other files using either of the +following directives at the beginning of a line: + + :: + + include FILENAME + includedir DIRNAME + +*FILENAME* or *DIRNAME* should be an absolute path. The named file or +directory must exist and be readable. Including a directory includes +all files within the directory whose names consist solely of +alphanumeric characters, dashes, or underscores. Included profile +files are syntactically independent of their parents, so each included +file must begin with a section header. + +The krb5.conf file can specify that configuration should be obtained +from a loadable module, rather than the file itself, using the +following directive at the beginning of a line before any section +headers: + + :: + + module MODULEPATH:RESIDUAL + +*MODULEPATH* may be relative to the library path of the krb5 +installation, or it may be an absolute path. *RESIDUAL* is provided +to the module at initialization time. If krb5.conf uses a module +directive, :ref:`kdc.conf(5)` should also use one if it exists. + + +Sections +-------- + +The krb5.conf file may contain the following sections: + +=================== ======================================================= +:ref:`libdefaults` Settings used by the Kerberos V5 library +:ref:`realms` Realm-specific contact information and settings +:ref:`domain_realm` Maps server hostnames to Kerberos realms +:ref:`capaths` Authentication paths for non-hierarchical cross-realm +:ref:`appdefaults` Settings used by some Kerberos V5 applications +:ref:`plugins` Controls plugin module registration +=================== ======================================================= + +Additionally, krb5.conf may include any of the relations described in +:ref:`kdc.conf(5)`, but it is not a recommended practice. + +.. _libdefaults: + +[libdefaults] +~~~~~~~~~~~~~ + +The libdefaults section may contain any of the following relations: + +**allow_weak_crypto** + If this flag is set to false, then weak encryption types will be + filtered out of the previous three lists (as noted in + :ref:`Encryption_and_salt_types` in :ref:`kdc.conf(5)`). The + default value for this tag is false, which may cause + authentication failures in existing Kerberos infrastructures that + do not support strong crypto. Users in affected environments + should set this tag to true until their infrastructure adopts + stronger ciphers. + +**ap_req_checksum_type** + An integer which specifies the type of AP-REQ checksum to use in + authenticators. This variable should be unset so the appropriate + checksum for the encryption key in use will be used. This can be + set if backward compatibility requires a specific checksum type. + See the **kdc_req_checksum_type** configuration option for the + possible values and their meanings. + +**canonicalize** + If this flag is set to true, initial ticket requests to the KDC + will request canonicalization of the client principal name, and + answers with different client principals than the requested + principal will be accepted. The default value is false. + +**ccache_type** + This parameter determines the format of credential cache types + created by :ref:`kinit(1)` or other programs. The default value + is 4, which represents the most current format. Smaller values + can be used for compatibility with very old implementations of + Kerberos which interact with credential caches on the same host. + +**clockskew** + Sets the maximum allowable amount of clockskew in seconds that the + library will tolerate before assuming that a Kerberos message is + invalid. The default value is 300 seconds, or five minutes. + +**default_ccache_name** + This relation specifies the name of the default credential cache. + The default is |ccache|. This relation is subject to parameter + expansion (see below). + +**default_client_keytab_name** + This relation specifies the name of the default keytab for + obtaining client credentials. The default is |ckeytab|. This + relation is subject to parameter expansion (see below). + +**default_keytab_name** + This relation specifies the default keytab name to be used by + application servers such as sshd. The default is |keytab|. This + relation is subject to parameter expansion (see below). + +**default_realm** + Identifies the default Kerberos realm for the client. Set its + value to your Kerberos realm. If this value is not set, then a + realm must be specified with every Kerberos principal when + invoking programs such as :ref:`kinit(1)`. + +**default_tgs_enctypes** + Identifies the supported list of session key encryption types that + should be returned by the KDC, in order of preference from + highest to lowest. The list may be delimited with commas or + whitespace. See :ref:`Encryption_and_salt_types` in + :ref:`kdc.conf(5)` for a list of the accepted values for this tag. + The default value is |defetypes|, but single-DES encryption types + will be implicitly removed from this list if the value of + **allow_weak_crypto** is false. + +**default_tkt_enctypes** + Identifies the supported list of session key encryption types that + should be requested by the client, in order of preference from + highest to lowest. The format is the same as for + default_tgs_enctypes. The default value for this tag is + |defetypes|, but single-DES encryption types will be implicitly + removed from this list if the value of **allow_weak_crypto** is + false. + +**dns_lookup_kdc** + Indicate whether DNS SRV records should be used to locate the KDCs + and other servers for a realm, if they are not listed in the + krb5.conf information for the realm. (Note that the admin_server + entry must be in the krb5.conf realm information in order to + contact kadmind, because the DNS implementation for kadmin is + incomplete.) + + Enabling this option does open up a type of denial-of-service + attack, if someone spoofs the DNS records and redirects you to + another server. However, it's no worse than a denial of service, + because that fake KDC will be unable to decode anything you send + it (besides the initial ticket request, which has no encrypted + data), and anything the fake KDC sends will not be trusted without + verification using some secret that it won't know. + +**extra_addresses** + This allows a computer to use multiple local addresses, in order + to allow Kerberos to work in a network that uses NATs while still + using address-restricted tickets. The addresses should be in a + comma-separated list. This option has no effect if + **noaddresses** is true. + +**forwardable** + If this flag is true, initial tickets will be forwardable by + default, if allowed by the KDC. The default value is false. + +**ignore_acceptor_hostname** + When accepting GSSAPI or krb5 security contexts for host-based + service principals, ignore any hostname passed by the calling + application, and allow clients to authenticate to any service + principal in the keytab matching the service name and realm name + (if given). This option can improve the administrative + flexibility of server applications on multihomed hosts, but could + compromise the security of virtual hosting environments. The + default value is false. + +**k5login_authoritative** + If this flag is true, principals must be listed in a local user's + k5login file to be granted login access, if a :ref:`.k5login(5)` + file exists. If this flag is false, a principal may still be + granted login access through other mechanisms even if a k5login + file exists but does not list the principal. The default value is + true. + +**k5login_directory** + If set, the library will look for a local user's k5login file + within the named directory, with a filename corresponding to the + local username. If not set, the library will look for k5login + files in the user's home directory, with the filename .k5login. + For security reasons, .k5login files must be owned by + the local user or by root. + +**kdc_default_options** + Default KDC options (Xored for multiple values) when requesting + initial tickets. By default it is set to 0x00000010 + (KDC_OPT_RENEWABLE_OK). + +**kdc_timesync** + The value of this relation must be an integer. If it is nonzero, + client machines will compute the difference between their time and + the time returned by the KDC in the timestamps in the tickets and + use this value to correct for an inaccurate system clock when + requesting service tickets or authenticating to services. This + corrective factor is only used by the Kerberos library; it is not + used to change the system clock. The default value is 1. + +**kdc_req_checksum_type** + An integer which specifies the type of checksum to use for the KDC + requests, for compatibility with very old KDC implementations. + This value is only used for DES keys; other keys use the preferred + checksum type for those keys. + + The possible values and their meanings are as follows. + + ======== =============================== + 1 CRC32 + 2 RSA MD4 + 3 RSA MD4 DES + 4 DES CBC + 7 RSA MD5 + 8 RSA MD5 DES + 9 NIST SHA + 12 HMAC SHA1 DES3 + -138 Microsoft MD5 HMAC checksum type + ======== =============================== + +**noaddresses** + If this flag is true, requests for initial tickets will not be + made with address restrictions set, allowing the tickets to be + used across NATs. The default value is true. + +**permitted_enctypes** + Identifies all encryption types that are permitted for use in + session key encryption. The default value for this tag is + |defetypes|, but single-DES encryption types will be implicitly + removed from this list if the value of **allow_weak_crypto** is + false. + +**plugin_base_dir** + If set, determines the base directory where krb5 plugins are + located. The default value is the ``krb5/plugins`` subdirectory + of the krb5 library directory. + +**preferred_preauth_types** + This allows you to set the preferred preauthentication types which + the client will attempt before others which may be advertised by a + KDC. The default value for this setting is "17, 16, 15, 14", + which forces libkrb5 to attempt to use PKINIT if it is supported. + +**proxiable** + If this flag is true, initial tickets will be proxiable by + default, if allowed by the KDC. The default value is false. + +**rdns** + If this flag is true, reverse name lookup will be used in addition + to forward name lookup to canonicalizing hostnames for use in + service principal names. The default value is true. + +**realm_try_domains** + Indicate whether a host's domain components should be used to + determine the Kerberos realm of the host. The value of this + variable is an integer: -1 means not to search, 0 means to try the + host's domain itself, 1 means to also try the domain's immediate + parent, and so forth. The library's usual mechanism for locating + Kerberos realms is used to determine whether a domain is a valid + realm, which may involve consulting DNS if **dns_lookup_kdc** is + set. The default is not to search domain components. + +**renew_lifetime** + (:ref:`duration` string.) Sets the default renewable lifetime + for initial ticket requests. The default value is 0. + +**safe_checksum_type** + An integer which specifies the type of checksum to use for the + KRB-SAFE requests. By default it is set to 8 (RSA MD5 DES). For + compatibility with applications linked against DCE version 1.1 or + earlier Kerberos libraries, use a value of 3 to use the RSA MD4 + DES instead. This field is ignored when its value is incompatible + with the session key type. See the **kdc_req_checksum_type** + configuration option for the possible values and their meanings. + +**ticket_lifetime** + (:ref:`duration` string.) Sets the default lifetime for initial + ticket requests. The default value is 1 day. + +**udp_preference_limit** + When sending a message to the KDC, the library will try using TCP + before UDP if the size of the message is above + **udp_preference_limit**. If the message is smaller than + **udp_preference_limit**, then UDP will be tried before TCP. + Regardless of the size, both protocols will be tried if the first + attempt fails. + +**verify_ap_req_nofail** + If this flag is true, then an attempt to verify initial + credentials will fail if the client machine does not have a + keytab. The default value is false. + + +.. _realms: + +[realms] +~~~~~~~~ + +Each tag in the [realms] section of the file is the name of a Kerberos +realm. The value of the tag is a subsection with relations that +define the properties of that particular realm. For each realm, the +following tags may be specified in the realm's subsection: + +**admin_server** + Identifies the host where the administration server is running. + Typically, this is the master Kerberos server. This tag must be + given a value in order to communicate with the :ref:`kadmind(8)` + server for the realm. + +**auth_to_local** + This tag allows you to set a general rule for mapping principal + names to local user names. It will be used if there is not an + explicit mapping for the principal name that is being + translated. The possible values are: + + **RULE:**\ *exp* + The local name will be formulated from *exp*. + + The format for *exp* is **[**\ *n*\ **:**\ *string*\ **](**\ + *regexp*\ **)s/**\ *pattern*\ **/**\ *replacement*\ **/g**. + The integer *n* indicates how many components the target + principal should have. If this matches, then a string will be + formed from *string*, substituting the realm of the principal + for ``$0`` and the *n*'th component of the principal for + ``$n`` (e.g., if the principal was ``johndoe/admin`` then + ``[2:$2$1foo]`` would result in the string + ``adminjohndoefoo``). If this string matches *regexp*, then + the ``s//[g]`` substitution command will be run over the + string. The optional **g** will cause the substitution to be + global over the *string*, instead of replacing only the first + match in the *string*. + + **DEFAULT** + The principal name will be used as the local user name. If + the principal has more than one component or is not in the + default realm, this rule is not applicable and the conversion + will fail. + + For example: + :: + + [realms] + ATHENA.MIT.EDU = { + auth_to_local = RULE:[2:$1](johndoe)s/^.*$/guest/ + auth_to_local = RULE:[2:$1;$2](^.*;admin$)s/;admin$// + auth_to_local = RULE:[2:$2](^.*;root)s/^.*$/root/ + auto_to_local = DEFAULT + } + + would result in any principal without ``root`` or ``admin`` as the + second component to be translated with the default rule. A + principal with a second component of ``admin`` will become its + first component. ``root`` will be used as the local name for any + principal with a second component of ``root``. The exception to + these two rules are any principals ``johndoe/*``, which will + always get the local name ``guest``. + +**auth_to_local_names** + This subsection allows you to set explicit mappings from principal + names to local user names. The tag is the mapping name, and the + value is the corresponding local user name. + +**default_domain** + This tag specifies the domain used to expand hostnames when + translating Kerberos 4 service principals to Kerberos 5 principals + (for example, when converting ``rcmd.hostname`` to + ``host/hostname.domain``). + +**kdc** + The name or address of a host running a KDC for that realm. An + optional port number, separated from the hostname by a colon, may + be included. If the name or address contains colons (for example, + if it is an IPv6 address), enclose it in square brackets to + distinguish the colon from a port separator. For your computer to + be able to communicate with the KDC for each realm, this tag must + be given a value in each realm subsection in the configuration + file, or there must be DNS SRV records specifying the KDCs. + +**kpasswd_server** + Points to the server where all the password changes are performed. + If there is no such entry, the port 464 on the **admin_server** + host will be tried. + +**master_kdc** + Identifies the master KDC(s). Currently, this tag is used in only + one case: If an attempt to get credentials fails because of an + invalid password, the client software will attempt to contact the + master KDC, in case the user's password has just been changed, and + the updated database has not been propagated to the slave servers + yet. + +**v4_instance_convert** + This subsection allows the administrator to configure exceptions + to the **default_domain** mapping rule. It contains V4 instances + (the tag name) which should be translated to some specific + hostname (the tag value) as the second component in a Kerberos V5 + principal name. + +**v4_realm** + This relation is used by the krb524 library routines when + converting a V5 principal name to a V4 principal name. It is used + when the V4 realm name and the V5 realm name are not the same, but + still share the same principal names and passwords. The tag value + is the Kerberos V4 realm name. + + +.. _domain_realm: + +[domain_realm] +~~~~~~~~~~~~~~ + +The [domain_realm] section provides a translation from a domain name +or hostname to a Kerberos realm name. The tag name can be a host name +or domain name, where domain names are indicated by a prefix of a +period (``.``). The value of the relation is the Kerberos realm name +for that particular host or domain. The Kerberos realm may be +identified either in the realms_ section or using DNS SRV records. +Host names and domain names should be in lower case. For example: + + :: + + [domain_realm] + crash.mit.edu = TEST.ATHENA.MIT.EDU + .mit.edu = ATHENA.MIT.EDU + mit.edu = ATHENA.MIT.EDU + +maps the host with the exact name ``crash.mit.edu`` into the +TEST.ATHENA.MIT.EDU realm. The period prefix in ``.mit.edu`` denotes +that all systems in the ``mit.edu`` domain belong to +``ATHENA.MIT.EDU`` realm. The third entry maps the host ``mit.edu`` +itself to the ``ATHENA.MIT.EDU`` realm. + +If no translation entry applies to a hostname used for a service +principal for a service ticket request, the library will try to get a +referral to the appropriate realm from the client realm's KDC. If +that does not succeed, the host's realm is considered to be the +hostname's domain portion converted to uppercase, unless the +**realm_try_domains** setting in [libdefaults] causes a different +parent domain to be used. + + +.. _capaths: + +[capaths] +~~~~~~~~~ + +In order to perform direct (non-hierarchical) cross-realm +authentication, configuration is needed to determine the +authentication paths between realms. + +A client will use this section to find the authentication path between +its realm and the realm of the server. The server will use this +section to verify the authentication path used by the client, by +checking the transited field of the received ticket. + +There is a tag for each participating client realm, and each tag has +subtags for each of the server realms. The value of the subtags is an +intermediate realm which may participate in the cross-realm +authentication. The subtags may be repeated if there is more then one +intermediate realm. A value of "." means that the two realms share +keys directly, and no intermediate realms should be allowed to +participate. + +Only those entries which will be needed on the client or the server +need to be present. A client needs a tag for its local realm with +subtags for all the realms of servers it will need to authenticate to. +A server needs a tag for each realm of the clients it will serve, with +a subtag of the server realm. + +For example, ``ANL.GOV``, ``PNL.GOV``, and ``NERSC.GOV`` all wish to +use the ``ES.NET`` realm as an intermediate realm. ANL has a sub +realm of ``TEST.ANL.GOV`` which will authenticate with ``NERSC.GOV`` +but not ``PNL.GOV``. The [capaths] section for ``ANL.GOV`` systems +would look like this: + + :: + + [capaths] + ANL.GOV = { + TEST.ANL.GOV = . + PNL.GOV = ES.NET + NERSC.GOV = ES.NET + ES.NET = . + } + TEST.ANL.GOV = { + ANL.GOV = . + } + PNL.GOV = { + ANL.GOV = ES.NET + } + NERSC.GOV = { + ANL.GOV = ES.NET + } + ES.NET = { + ANL.GOV = . + } + +The [capaths] section of the configuration file used on ``NERSC.GOV`` +systems would look like this: + + :: + + [capaths] + NERSC.GOV = { + ANL.GOV = ES.NET + TEST.ANL.GOV = ES.NET + TEST.ANL.GOV = ANL.GOV + PNL.GOV = ES.NET + ES.NET = . + } + ANL.GOV = { + NERSC.GOV = ES.NET + } + PNL.GOV = { + NERSC.GOV = ES.NET + } + ES.NET = { + NERSC.GOV = . + } + TEST.ANL.GOV = { + NERSC.GOV = ANL.GOV + NERSC.GOV = ES.NET + } + +When a subtag is used more than once within a tag, clients will use +the order of values to determine the path. The order of values is not +important to servers. + + +.. _appdefaults: + +[appdefaults] +~~~~~~~~~~~~~ + +Each tag in the [appdefaults] section names a Kerberos V5 application +or an option that is used by some Kerberos V5 application[s]. The +value of the tag defines the default behaviors for that application. + +For example: + :: + + [appdefaults] + telnet = { + ATHENA.MIT.EDU = { + option1 = false + } + } + telnet = { + option1 = true + option2 = true + } + ATHENA.MIT.EDU = { + option2 = false + } + option2 = true + +The above four ways of specifying the value of an option are shown in +order of decreasing precedence. In this example, if telnet is running +in the realm EXAMPLE.COM, it should, by default, have option1 and +option2 set to true. However, a telnet program in the realm +``ATHENA.MIT.EDU`` should have ``option1`` set to false and +``option2`` set to true. Any other programs in ATHENA.MIT.EDU should +have ``option2`` set to false by default. Any programs running in +other realms should have ``option2`` set to true. + +The list of specifiable options for each application may be found in +that application's man pages. The application defaults specified here +are overridden by those specified in the realms_ section. + + +.. _plugins: + +[plugins] +~~~~~~~~~ + + * pwqual_ interface + * kadm5_hook_ interface + * clpreauth_ and kdcpreauth_ interfaces + +Tags in the [plugins] section can be used to register dynamic plugin +modules and to turn modules on and off. Not every krb5 pluggable +interface uses the [plugins] section; the ones that do are documented +here. + +Each pluggable interface corresponds to a subsection of [plugins]. +All subsections support the same tags: + +**disable** + This tag may have multiple values. If there are values for this + tag, then the named modules will be disabled for the pluggable + interface. + +**enable_only** + This tag may have multiple values. If there are values for this + tag, then only the named modules will be enabled for the pluggable + interface. + +**module** + This tag may have multiple values. Each value is a string of the + form ``modulename:pathname``, which causes the shared object + located at *pathname* to be registered as a dynamic module named + *modulename* for the pluggable interface. If *pathname* is not an + absolute path, it will be treated as relative to the + **plugin_base_dir** value from :ref:`libdefaults`. + +The following subsections are currently supported within the [plugins] +section: + +.. _ccselect: + +ccselect interface +################## + +The ccselect subsection controls modules for credential cache +selection within a cache collection. In addition to any registered +dynamic modules, the following built-in modules exist (and may be +disabled with the disable tag): + +**k5identity** + Uses a .k5identity file in the user's home directory to select a + client principal + +**realm** + Uses the service realm to guess an appropriate cache from the + collection + +.. _pwqual: + +pwqual interface +################ + +The pwqual subsection controls modules for the password quality +interface, which is used to reject weak passwords when passwords are +changed. The following built-in modules exist for this interface: + +**dict** + Checks against the realm dictionary file + +**empty** + Rejects empty passwords + +**hesiod** + Checks against user information stored in Hesiod (only if Kerberos + was built with Hesiod support) + +**princ** + Checks against components of the principal name + +.. _kadm5_hook: + +kadm5_hook interface +#################### + +The kadm5_hook interface provides plugins with information on +principal creation, modification, password changes and deletion. This +interface can be used to write a plugin to synchronize MIT Kerberos +with another database such as Active Directory. No plugins are built +in for this interface. + +.. _clpreauth: + +.. _kdcpreauth: + +clpreauth and kdcpreauth interfaces +################################### + +The clpreauth and kdcpreauth interfaces allow plugin modules to +provide client and KDC preauthentication mechanisms. The following +built-in modules exist for these interfaces: + +**pkinit** + This module implements the PKINIT preauthentication mechanism. + +**encrypted_challenge** + This module implements the encrypted challenge FAST factor. + +**encrypted_timestamp** + This module implements the encrypted timestamp mechanism. + + +PKINIT options +-------------- + +.. note:: The following are PKINIT-specific options. These values may + be specified in [libdefaults] as global defaults, or within + a realm-specific subsection of [libdefaults], or may be + specified as realm-specific values in the [realms] section. + A realm-specific value overrides, not adds to, a generic + [libdefaults] specification. The search order is: + +1. realm-specific subsection of [libdefaults]: + + :: + + [libdefaults] + EXAMPLE.COM = { + pkinit_anchors = FILE:/usr/local/example.com.crt + } + +2. realm-specific value in the [realms] section, + + :: + + [realms] + OTHERREALM.ORG = { + pkinit_anchors = FILE:/usr/local/otherrealm.org.crt + } + +3. generic value in the [libdefaults] section. + + :: + + [libdefaults] + pkinit_anchors = DIR:/usr/local/generic_trusted_cas/ + + +.. _pkinit_identity: + +Specifying PKINIT identity information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The syntax for specifying Public Key identity, trust, and revocation +information for PKINIT is as follows: + +**FILE:**\ *filename*\ [**,**\ *keyfilename*] + This option has context-specific behavior. + + In **pkinit_identity** or **pkinit_identities**, *filename* + specifies the name of a PEM-format file containing the user's + certificate. If *keyfilename* is not specified, the user's + private key is expected to be in *filename* as well. Otherwise, + *keyfilename* is the name of the file containing the private key. + + In **pkinit_anchors** or **pkinit_pool**, *filename* is assumed to + be the name of an OpenSSL-style ca-bundle file. + +**DIR:**\ *dirname* + This option has context-specific behavior. + + In **pkinit_identity** or **pkinit_identities**, *dirname* + specifies a directory with files named ``*.crt`` and ``*.key`` + where the first part of the file name is the same for matching + pairs of certificate and private key files. When a file with a + name ending with ``.crt`` is found, a matching file ending with + ``.key`` is assumed to contain the private key. If no such file + is found, then the certificate in the ``.crt`` is not used. + + In **pkinit_anchors** or **pkinit_pool**, *dirname* is assumed to + be an OpenSSL-style hashed CA directory where each CA cert is + stored in a file named ``hash-of-ca-cert.#``. This infrastructure + is encouraged, but all files in the directory will be examined and + if they contain certificates (in PEM format), they will be used. + + In **pkinit_revoke**, *dirname* is assumed to be an OpenSSL-style + hashed CA directory where each revocation list is stored in a file + named ``hash-of-ca-cert.r#``. This infrastructure is encouraged, + but all files in the directory will be examined and if they + contain a revocation list (in PEM format), they will be used. + +**PKCS12:**\ *filename* + *filename* is the name of a PKCS #12 format file, containing the + user's certificate and private key. + +**PKCS11:**\ [**module_name=**]\ *modname*\ [**:slotid=**\ *slot-id*][**:token=**\ *token-label*][**:certid=**\ *cert-id*][**:certlabel=**\ *cert-label*] + All keyword/values are optional. *modname* specifies the location + of a library implementing PKCS #11. If a value is encountered + with no keyword, it is assumed to be the *modname*. If no + module-name is specified, the default is ``opensc-pkcs11.so``. + ``slotid=`` and/or ``token=`` may be specified to force the use of + a particular smard card reader or token if there is more than one + available. ``certid=`` and/or ``certlabel=`` may be specified to + force the selection of a particular certificate on the device. + See the **pkinit_cert_match** configuration option for more ways + to select a particular certificate to use for PKINIT. + +**ENV:**\ *envvar* + *envvar* specifies the name of an environment variable which has + been set to a value conforming to one of the previous values. For + example, ``ENV:X509_PROXY``, where environment variable + ``X509_PROXY`` has been set to ``FILE:/tmp/my_proxy.pem``. + + +PKINIT krb5.conf options +~~~~~~~~~~~~~~~~~~~~~~~~ + +**pkinit_anchors** + Specifies the location of trusted anchor (root) certificates which + the client trusts to sign KDC certificates. This option may be + specified multiple times. These values from the config file are + not used if the user specifies X509_anchors on the command line. + +**pkinit_cert_match** + Specifies matching rules that the client certificate must match + before it is used to attempt PKINIT authentication. If a user has + multiple certificates available (on a smart card, or via other + media), there must be exactly one certificate chosen before + attempting PKINIT authentication. This option may be specified + multiple times. All the available certificates are checked + against each rule in order until there is a match of exactly one + certificate. + + The Subject and Issuer comparison strings are the :rfc:`2253` + string representations from the certificate Subject DN and Issuer + DN values. + + The syntax of the matching rules is: + + [*relation-operator*\ ]\ *component-rule* ... + + where: + + *relation-operator* + can be either ``&&``, meaning all component rules must match, + or ``||``, meaning only one component rule must match. The + default is ``&&``. + + *component-rule* + can be one of the following. Note that there is no + punctuation or whitespace between component rules. + + | ****\ *regular-expression* + | ****\ *regular-expression* + | ****\ *regular-expression* + | ****\ *extended-key-usage-list* + | ****\ *key-usage-list* + + *extended-key-usage-list* is a comma-separated list of + required Extended Key Usage values. All values in the list + must be present in the certificate. Extended Key Usage values + can be: + + * pkinit + * msScLogin + * clientAuth + * emailProtection + + *key-usage-list* is a comma-separated list of required Key + Usage values. All values in the list must be present in the + certificate. Key Usage values can be: + + * digitalSignature + * keyEncipherment + + Examples: + + :: + + pkinit_cert_match = ||.*DoE.*.*@EXAMPLE.COM + pkinit_cert_match = &&msScLogin,clientAuth.*DoE.* + pkinit_cert_match = msScLogin,clientAuthdigitalSignature + +**pkinit_eku_checking** + This option specifies what Extended Key Usage value the KDC + certificate presented to the client must contain. (Note that if + the KDC certificate has the pkinit SubjectAlternativeName encoded + as the Kerberos TGS name, EKU checking is not necessary since the + issuing CA has certified this as a KDC certificate.) The values + recognized in the krb5.conf file are: + + **kpKDC** + This is the default value and specifies that the KDC must have + the id-pkinit-KPKdc EKU as defined in :rfc:`4556`. + + **kpServerAuth** + If **kpServerAuth** is specified, a KDC certificate with the + id-kp-serverAuth EKU as used by Microsoft will be accepted. + + **none** + If **none** is specified, then the KDC certificate will not be + checked to verify it has an acceptable EKU. The use of this + option is not recommended. + +**pkinit_dh_min_bits** + Specifies the size of the Diffie-Hellman key the client will + attempt to use. The acceptable values are 1024, 2048, and 4096. + The default is 2048. + +**pkinit_identities** + Specifies the location(s) to be used to find the user's X.509 + identity information. This option may be specified multiple + times. Each value is attempted in order until identity + information is found and authentication is attempted. Note that + these values are not used if the user specifies + **X509_user_identity** on the command line. + +**pkinit_kdc_hostname** + The presense of this option indicates that the client is willing + to accept a KDC certificate with a dNSName SAN (Subject + Alternative Name) rather than requiring the id-pkinit-san as + defined in :rfc:`4556`. This option may be specified multiple + times. Its value should contain the acceptable hostname for the + KDC (as contained in its certificate). + +**pkinit_longhorn** + If this flag is set to true, we are talking to the Longhorn KDC. + +**pkinit_pool** + Specifies the location of intermediate certificates which may be + used by the client to complete the trust chain between a KDC + certificate and a trusted anchor. This option may be specified + multiple times. + +**pkinit_require_crl_checking** + The default certificate verification process will always check the + available revocation information to see if a certificate has been + revoked. If a match is found for the certificate in a CRL, + verification fails. If the certificate being verified is not + listed in a CRL, or there is no CRL present for its issuing CA, + and **pkinit_require_crl_checking** is false, then verification + succeeds. + + However, if **pkinit_require_crl_checking** is true and there is + no CRL information available for the issuing CA, then verification + fails. + + **pkinit_require_crl_checking** should be set to true if the + policy is such that up-to-date CRLs must be present for every CA. + +**pkinit_revoke** + Specifies the location of Certificate Revocation List (CRL) + information to be used by the client when verifying the validity + of the KDC certificate presented. This option may be specified + multiple times. + +**pkinit_win2k** + This flag specifies whether the target realm is assumed to support + only the old, pre-RFC version of the protocol. The default is + false. + +**pkinit_win2k_require_binding** + If this flag is set to true, it expects that the target KDC is + patched to return a reply with a checksum rather than a nonce. + The default is false. + + +.. _parameter_expansion: + +Parameter expansion +------------------- + +Several variables, such as **default_keytab_name**, allow parameters +to be expanded. Valid parameters are: + + ================= =================================================== + %{TEMP} Temporary directory + %{uid} Unix real UID or Windows SID + %{euid} Unix effective user ID or Windows SID + %{USERID} Same as %{uid} + %{null} Empty string + %{LIBDIR} Installation library directory + %{BINDIR} Installation binary directory + %{SBINDIR} Installation admin binary directory + %{username} (Unix) Username of effective user ID + %{APPDATA} (Windows) Roaming application data for current user + %{COMMON_APPDATA} (Windows) Application data for all users + %{LOCAL_APPDATA} (Windows) Local application data for current user + %{SYSTEM} (Windows) Windows system folder + %{WINDOWS} (Windows) Windows folder + %{USERCONFIG} (Windows) Per-user MIT krb5 config file directory + %{COMMONCONFIG} (Windows) Common MIT krb5 config file directory + ================= =================================================== + +Sample krb5.conf file +--------------------- + +Here is an example of a generic krb5.conf file: + + :: + + [libdefaults] + default_realm = ATHENA.MIT.EDU + default_tkt_enctypes = des3-hmac-sha1 des-cbc-crc + default_tgs_enctypes = des3-hmac-sha1 des-cbc-crc + dns_lookup_kdc = true + dns_lookup_realm = false + + [realms] + ATHENA.MIT.EDU = { + kdc = kerberos.mit.edu + kdc = kerberos-1.mit.edu + kdc = kerberos-2.mit.edu:750 + admin_server = kerberos.mit.edu + master_kdc = kerberos.mit.edu + default_domain = mit.edu + } + EXAMPLE.COM = { + kdc = kerberos.example.com + kdc = kerberos-1.example.com + admin_server = kerberos.example.com + } + + [domain_realm] + .mit.edu = ATHENA.MIT.EDU + mit.edu = ATHENA.MIT.EDU + + [capaths] + ATHENA.MIT.EDU = { + EXAMPLE.COM = . + } + EXAMPLE.COM = { + ATHENA.MIT.EDU = . + } + +FILES +----- + +|krb5conf| + + +SEE ALSO +-------- + +syslog(3) diff --git a/doc/admins/conf_ldap.rst b/doc/admins/conf_ldap.rst new file mode 100644 index 000000000..c8237d643 --- /dev/null +++ b/doc/admins/conf_ldap.rst @@ -0,0 +1,158 @@ +Configuring Kerberos with OpenLDAP back-end +=========================================== + + + 1. Set up SSL on the OpenLDAP server and client to ensure secure + communication when the KDC service and LDAP server are on different + machines. ``ldapi://`` can be used if the LDAP server and KDC + service are running on the same machine. + + A. Setting up SSL on the OpenLDAP server: + + i) Get a CA certificate using OpenSSL tools + ii) Configure OpenLDAP server for using SSL/TLS + + For the latter, you need to specify the location of CA + certificate location in *slapd.conf* file. + + Refer to the following link for more information: + http://www.openldap.org/doc/admin23/tls.html + + B. Setting up SSL on OpenLDAP client: + + i) For the KDC and Admin Server, you need to do the client-side + configuration in ldap.conf. For example:: + + TLS_CACERT /etc/openldap/certs/cacert.pem + + 2. Include the Kerberos schema file (kerberos.schema) in the + configuration file (slapd.conf) on the LDAP Server, by providing + the location where it is stored:: + + include /etc/openldap/schema/kerberos.schema + + 3. Choose DNs for the :ref:`krb5kdc(8)` and :ref:`kadmind(8)` servers + to bind to the LDAP server, and create them if necessary. These DNs + will be specified with the **ldap_kdc_dn** and **ldap_kadmind_dn** + directives in :ref:`kdc.conf(5)`; their passwords can be stashed + with "``kdb5_ldap_util stashsrvpw``" and the resulting file + specified with the **ldap_service_password_file** directive. + + 4. Choose a DN for the global Kerberos container entry (but do not + create the entry at this time). This DN will be specified with the + **ldap_kerberos_container_dn** directive in :ref:`kdc.conf(5)`. + Realm container entries will be created underneath this DN. + Principal entries may exist either underneath the realm container + (the default) or in separate trees referenced from the realm + container. + + 5. Configure the LDAP server ACLs to enable the KDC and kadmin server + DNs to read and write the Kerberos data. + + Sample access control information:: + + access to dn.base="" + by * read + + access to dn.base="cn=Subschema" + by * read + + access to attrs=userPassword,userPKCS12 + by self write + by * auth + + access to attrs=shadowLastChange + by self write + by * read + + # Providing access to realm container + access to dn.subtree= "cn=EXAMPLE.COM,cn=krbcontainer,dc=example,dc=com" + by dn.exact="cn=kdc-service,dc=example,dc=com" read + by dn.exact="cn=adm-service,dc=example,dc=com" write + by * none + + # Providing access to principals, if not underneath realm container + access to dn.subtree= "ou=users,dc=example,dc=com" + by dn.exact="cn=kdc-service,dc=example,dc=com" read + by dn.exact="cn=adm-service,dc=example,dc=com" write + by * none + + access to * + by * read + + If the locations of the container and principals or the DNs of + the service objects for a realm are changed then this + information should be updated. + + 6. Start the LDAP server as follows:: + + slapd -h "ldapi:/// ldaps:///" + + 7. Modify the :ref:`kdc.conf(5)` file to include LDAP specific items + listed below:: + + realms + database_module + + dbmodules + db_library + db_module_dir + ldap_kdc_dn + ldap_kadmind_dn + ldap_service_password_file + ldap_servers + ldap_conns_per_server + + 8. Create the realm using :ref:`kdb5_ldap_util(8)` (see + :ref:`ldap_create_realm`):: + + kdb5_ldap_util -D cn=admin,dc=example,dc=com create -subtrees ou=users,dc=example,dc=com -r EXAMPLE.COM -s + + Use the **-subtrees** option if the principals are to exist in a + separate subtree from the realm container. Before executing the + command, make sure that the subtree mentioned above + ``(ou=users,dc=example,dc=com)`` exists. If the principals will + exist underneath the realm container, omit the **-subtrees** option + and do not worry about creating the principal subtree. + + For more information, refer to the section :ref:`ops_on_ldap`. + + The realm object is created under the + **ldap_kerberos_container_dn** specified in the configuration file. + This operation will also create the Kerberos container, if not + present already. This will be used to store information related to + all realms. + + 9. Stash the password of the service object used by the KDC and + Administration service to bind to the LDAP server using the + :ref:`kdb5_ldap_util(8)` **stashsrvpw** command (see + :ref:`stash_ldap`). The object DN should be the same as + **ldap_kdc_dn** and **ldap_kadmind_dn** values specified in the + :ref:`kdc.conf(5)` file:: + + kdb5_ldap_util -D cn=admin,dc=example,dc=com stashsrvpw -f /etc/kerberos/service.keyfile cn=krbadmin,dc=example,dc=com + + 10. Add ``krbPrincipalName`` to the indexes in slapd.conf to speed up + the access. + +With the LDAP back end it is possible to provide aliases for principal +entries. Currently we provide no mechanism provided for creating +aliases, so it must be done by direct manipulation of the LDAP +entries. + +An entry with aliases contains multiple values of the +*krbPrincipalName* attribute. Since LDAP attribute values are not +ordered, it is necessary to specify which principal name is canonical, +by using the *krbCanonicalName* attribute. Therefore, to create +aliases for an entry, first set the *krbCanonicalName* attribute of +the entry to the canonical principal name (which should be identical +to the pre-existing *krbPrincipalName* value), and then add additional +*krbPrincipalName* attributes for the aliases. + +Principal aliases are only returned by the KDC when the client +requests canonicalization. Canonicalization is normally requested for +service principals; for client principals, an explicit flag is often +required (e.g., ``kinit -C``) and canonicalization is only performed +for initial ticket requests. + +.. seealso:: :ref:`ldap_be_ubuntu` diff --git a/doc/admins/database.rst b/doc/admins/database.rst new file mode 100644 index 000000000..d7d6aa9b7 --- /dev/null +++ b/doc/admins/database.rst @@ -0,0 +1,785 @@ +Database administration +======================= + +A Kerberos database contains all of a realm's Kerberos principals, +their passwords, and other administrative information about each +principal. For the most part, you will use the :ref:`kdb5_util(8)` +program to manipulate the Kerberos database as a whole, and the +:ref:`kadmin(1)` program to make changes to the entries in the +database. (One notable exception is that users will use the +:ref:`kpasswd(1)` program to change their own passwords.) The kadmin +program has its own command-line interface, to which you type the +database administrating commands. + +:ref:`kdb5_util(8)` provides a means to create, delete, load, or dump +a Kerberos database. It also contains commands to roll over the +database master key, and to stash a copy of the key so that the +:ref:`kadmind(8)` and :ref:`krb5kdc(8)` daemons can use the database +without manual input. + +:ref:`kadmin(1)` provides for the maintenance of Kerberos principals, +password policies, and service key tables (keytabs). Normally it +operates as a network client using Kerberos authentication to +communicate with :ref:`kadmind(8)`, but there is also a variant, named +kadmin.local, which directly accesses the Kerberos database on the +local filesystem (or through LDAP). kadmin.local is necessary to set +up enough of the database to be able to use the remote version. + +kadmin can authenticate to the admin server using the service +principal ``kadmin/HOST`` (where *HOST* is the hostname of the admin +server) or ``kadmin/admin``. If the credentials cache contains a +ticket for either service principal and the **-c** ccache option is +specified, that ticket is used to authenticate to KADM5. Otherwise, +the **-p** and **-k** options are used to specify the client Kerberos +principal name used to authenticate. Once kadmin has determined the +principal name, it requests a ``kadmin/admin`` Kerberos service ticket +from the KDC, and uses that service ticket to authenticate to KADM5. + +See :ref:`kadmin(1)` for the available kadmin and kadmin.local +commands and options. + + +kadmin options +-------------- + +You can invoke :ref:`kadmin(1)` or kadmin.local with any of the +following options: + +.. include:: admin_commands/kadmin_local.rst + :start-after: kadmin_synopsis: + :end-before: kadmin_synopsis_end: + +**OPTIONS** + +.. include:: admin_commands/kadmin_local.rst + :start-after: _kadmin_options: + :end-before: _kadmin_options_end: + + +Date Format +----------- + +For the supported date-time formats see :ref:`getdate` section +in :ref:`datetime`. + + +Principals +---------- + +Each entry in the Kerberos database contains a Kerberos principal and +the attributes and policies associated with that principal. + + +.. _add_mod_del_princs: + +Adding, modifying and deleting principals +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To add a principal to the database, use the :ref:`kadmin(1)` +**add_principal** command. + +To modify attributes of a principal, use the kadmin +**modify_principal** command. + +To delete a principal, use the kadmin **delete_principal** command. + +.. include:: admin_commands/kadmin_local.rst + :start-after: _add_principal: + :end-before: _add_principal_end: + +.. include:: admin_commands/kadmin_local.rst + :start-after: _modify_principal: + :end-before: _modify_principal_end: + +.. include:: admin_commands/kadmin_local.rst + :start-after: _delete_principal: + :end-before: _delete_principal_end: + + +Examples +######## + +If you want to create a principal which is contained by a LDAP object, +all you need to do is:: + + kadmin: addprinc -x dn=cn=jennifer,dc=example,dc=com jennifer + WARNING: no policy specified for "jennifer@ATHENA.MIT.EDU"; + defaulting to no policy. + Enter password for principal jennifer@ATHENA.MIT.EDU: <= Type the password. + Re-enter password for principal jennifer@ATHENA.MIT.EDU: <=Type it again. + Principal "jennifer@ATHENA.MIT.EDU" created. + kadmin: + +If you want to create a principal under a specific LDAP container and +link to an existing LDAP object, all you need to do is:: + + kadmin: addprinc -x containerdn=dc=example,dc=com -x linkdn=cn=david,dc=example,dc=com david + WARNING: no policy specified for "david@ATHENA.MIT.EDU"; + defaulting to no policy. + Enter password for principal david@ATHENA.MIT.EDU: <= Type the password. + Re-enter password for principal david@ATHENA.MIT.EDU: <=Type it again. + Principal "david@ATHENA.MIT.EDU" created. + kadmin: + +If you want to associate a ticket policy to a principal, all you need +to do is:: + + kadmin: modprinc -x tktpolicy=userpolicy david + Principal "david@ATHENA.MIT.EDU" modified. + kadmin: + +If, on the other hand, you want to set up an account that expires on +January 1, 2000, that uses a policy called "stduser", with a temporary +password (which you want the user to change immediately), you would +type the following:: + + kadmin: addprinc david -expire "1/1/2000 12:01am EST" -policy stduser +needchange + Enter password for principal david@ATHENA.MIT.EDU: <= Type the password. + Re-enter password for principal + david@ATHENA.MIT.EDU: <= Type it again. + Principal "david@ATHENA.MIT.EDU" created. + kadmin: + +If you want to delete a principal :: + + kadmin: delprinc jennifer + Are you sure you want to delete the principal + "jennifer@ATHENA.MIT.EDU"? (yes/no): yes + Principal "jennifer@ATHENA.MIT.EDU" deleted. + Make sure that you have removed this principal from + all ACLs before reusing. + kadmin: + + +Retrieving information about a principal +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To retrieve a listing of the attributes and/or policies associated +with a principal, use the :ref:`kadmin(1)` **get_principal** command. + +To generate a listing of principals, use the kadmin +**list_principals** command. + +.. include:: admin_commands/kadmin_local.rst + :start-after: _get_principal: + :end-before: _get_principal_end: + +.. include:: admin_commands/kadmin_local.rst + :start-after: _list_principals: + :end-before: _list_principals_end: + + +Changing passwords +~~~~~~~~~~~~~~~~~~ + +To change a principal's password use the :ref:`kadmin(1)` +**change_password** command. + +.. include:: admin_commands/kadmin_local.rst + :start-after: _change_password: + :end-before: _change_password_end: + +.. note:: Password changes through kadmin are subject to the same + password policies as would apply to password changes through + :ref:`kpasswd(1)`. + + +Policies +-------- + +A policy is a set of rules governing passwords. Policies can dictate +minimum and maximum password lifetimes, minimum number of characters +and character classes a password must contain, and the number of old +passwords kept in the database. + + +Adding, modifying and deleting policies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To add a new policy, use the :ref:`kadmin(1)` **add_policy** command. + +To modify attributes of a principal, use the kadmin **modify_policy** +command. + +To delete a policy, use the kadmin **delete_policy** command. + +.. include:: admin_commands/kadmin_local.rst + :start-after: _add_policy: + :end-before: _add_policy_end: + +.. include:: admin_commands/kadmin_local.rst + :start-after: _modify_policy: + :end-before: _modify_policy_end: + +.. include:: admin_commands/kadmin_local.rst + :start-after: _delete_policy: + :end-before: _delete_policy_end: + +.. note:: You must cancel the policy from *all* principals before + deleting it. The *delete_policy* command will fail if the policy + is in use by any principals. + + +Retrieving policies +~~~~~~~~~~~~~~~~~~~ + +To retrieve a policy, use the :ref:`kadmin(1)` **get_policy** command. + +You can retrieve the list of policies with the kadmin +**list_policies** command. + +.. include:: admin_commands/kadmin_local.rst + :start-after: _get_policy: + :end-before: _get_policy_end: + +.. include:: admin_commands/kadmin_local.rst + :start-after: _list_policies: + :end-before: _list_policies_end: + + +Updating the history key +~~~~~~~~~~~~~~~~~~~~~~~~ + +If a policy specifies a number of old keys kept of two or more, the +stored old keys are encrypted in a history key, which is found in the +key data of the ``kadmin/history`` principal. + +Currently there is no support for proper rollover of the history key, +but you can change the history key (for example, to use a better +encryption type) at the cost of invalidating currently stored old +keys. To change the history key, run:: + + kadmin: change_password -randkey kadmin/history + +This command will fail if you specify the **-keepold** flag. Only one +new history key will be created, even if you specify multiple key/salt +combinations. + +In the future, we plan to migrate towards encrypting old keys in the +master key instead of the history key, and implementing proper +rollover support for stored old keys. + + +.. _privileges: + +Privileges +---------- + +Administrative privileges for the Kerberos database are stored in the +file :ref:`kadm5.acl(5)`. + +.. note:: A common use of an admin instance is so you can grant + separate permissions (such as administrator access to the + Kerberos database) to a separate Kerberos principal. For + example, the user ``joeadmin`` might have a principal for + his administrative use, called ``joeadmin/admin``. This + way, ``joeadmin`` would obtain ``joeadmin/admin`` tickets + only when he actually needs to use those permissions. + + +.. _db_operations: + +Operations on the Kerberos database +----------------------------------- + +The :ref:`kdb5_util(8)` command is the primary tool for administrating +the Kerberos database. + +.. include:: admin_commands/kdb5_util.rst + :start-after: _kdb5_util_synopsis: + :end-before: _kdb5_util_synopsis_end: + +**OPTIONS** + +.. include:: admin_commands/kdb5_util.rst + :start-after: _kdb5_util_options: + :end-before: _kdb5_util_options_end: + +.. toctree:: + :maxdepth: 1 + + +Dumping a Kerberos database to a file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To dump a Kerberos database into a file, use the :ref:`kdb5_util(8)` +**dump** command on one of the KDCs. + +.. include:: admin_commands/kdb5_util.rst + :start-after: _kdb5_util_dump: + :end-before: _kdb5_util_dump_end: + + +Examples +######## + +:: + + shell% kdb5_util dump dumpfile + shell% + + shell% kbd5_util dump -verbose dumpfile + kadmin/admin@ATHENA.MIT.EDU + krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU + kadmin/history@ATHENA.MIT.EDU + K/M@ATHENA.MIT.EDU + kadmin/changepw@ATHENA.MIT.EDU + shell% + +If you specify which principals to dump, you must use the full +principal, as in the following example:: + + shell% kdb5_util dump -verbose dumpfile K/M@ATHENA.MIT.EDU kadmin/admin@ATHENA.MIT.EDU + kadmin/admin@ATHENA.MIT.EDU + K/M@ATHENA.MIT.EDU + shell% + +Otherwise, the principals will not match those in the database and +will not be dumped:: + + shell% kdb5_util dump -verbose dumpfile K/M kadmin/admin + shell% + +If you do not specify a dump file, kdb5_util will dump the database to +the standard output. + + +.. _restore_from_dump: + +Restoring a Kerberos database from a dump file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To restore a Kerberos database dump from a file, use the +:ref:`kdb5_util(8)` **load** command on one of the KDCs. + +.. include:: admin_commands/kdb5_util.rst + :start-after: _kdb5_util_load: + :end-before: _kdb5_util_load_end: + + +Examples +######## + +To load a single principal, either replacing or updating the database: + +:: + + shell% kdb5_util load dumpfile principal + shell% + + shell% kdb5_util load -update dumpfile principal + shell% + + +.. note:: If the database file exists, and the *-update* flag was not + given, *kdb5_util* will overwrite the existing database. + +Using kdb5_util to upgrade a master KDC from krb5 1.1.x: + +:: + + shell% kdb5_util dump old-kdb-dump + shell% kdb5_util dump -ov old-kdb-dump.ov + [Create a new KDC installation, using the old stash file/master password] + shell% kdb5_util load old-kdb-dump + shell% kdb5_util load -update old-kdb-dump.ov + +The use of old-kdb-dump.ov for an extra dump and load is necessary +to preserve per-principal policy information, which is not included in +the default dump format of krb5 1.1.x. + +.. note:: Using kdb5_util to dump and reload the principal database is + only necessary when upgrading from versions of krb5 prior + to 1.2.0---newer versions will use the existing database as-is. + + +.. _create_stash: + +Creating a stash file +~~~~~~~~~~~~~~~~~~~~~ + +A stash file allows a KDC to authenticate itself to the database +utilities, such as :ref:`kadmind(8)`, :ref:`krb5kdc(8)`, and +:ref:`kdb5_util(8)`. + +To create a stash file, use the :ref:`kdb5_util(8)` **stash** command. + +.. include:: admin_commands/kdb5_util.rst + :start-after: _kdb5_util_stash: + :end-before: _kdb5_util_stash_end: + + +Example +####### + + shell% kdb5_util stash + kdb5_util: Cannot find/read stored master key while reading master key + kdb5_util: Warning: proceeding without master key + Enter KDC database master key: <= Type the KDC database master password. + shell% + +If you do not specify a stash file, kdb5_util will stash the key in +the file specified in your :ref:`kdc.conf(5)` file. + + +Creating and destroying a Kerberos database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need to create a new Kerberos database, use the +:ref:`kdb5_util(8)` **create** command. + +.. include:: admin_commands/kdb5_util.rst + :start-after: _kdb5_util_create: + :end-before: _kdb5_util_create_end: + +If you need to destroy the current Kerberos database, use the +:ref:`kdb5_util(8)` **destroy** command. + +.. include:: admin_commands/kdb5_util.rst + :start-after: _kdb5_util_destroy: + :end-before: _kdb5_util_destroy_end: + + +Examples +######## + +:: + + shell% kdb5_util -r ATHENA.MIT.EDU create -s + Loading random data + Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU', + master key name 'K/M@ATHENA.MIT.EDU' + You will be prompted for the database Master Password. + It is important that you NOT FORGET this password. + Enter KDC database master key: <= Type the master password. + Re-enter KDC database master key to verify: <= Type it again. + shell% + + shell% kdb5_util -r ATHENA.MIT.EDU destroy + Deleting KDC database stored in '/usr/local/var/krb5kdc/principal', are you sure? + (type 'yes' to confirm)? <= yes + OK, deleting database '/usr/local/var/krb5kdc/principal'... + ** Database '/usr/local/var/krb5kdc/principal' destroyed. + shell% + + +.. _ops_on_ldap: + +Operations on the LDAP database +------------------------------- + +The :ref:`kdb5_ldap_util(8)` is the primary tool for administrating +the Kerberos LDAP database. It allows an administrator to manage +realms, Kerberos services (KDC and Admin Server) and ticket policies. + +.. include:: admin_commands/kdb5_ldap_util.rst + :start-after: _kdb5_ldap_util_synopsis: + :end-before: _kdb5_ldap_util_synopsis_end: + +**OPTIONS** + +.. include:: admin_commands/kdb5_ldap_util.rst + :start-after: _kdb5_ldap_util_options: + :end-before: _kdb5_ldap_util_options_end: + + +.. _ldap_create_realm: + +Creating a Kerberos realm +~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need to create a new realm, use the :ref:`kdb5_ldap_util(8)` +**create** command as follows. + +.. include:: admin_commands/kdb5_ldap_util.rst + :start-after: _kdb5_ldap_util_create: + :end-before: _kdb5_ldap_util_create_end: + + +.. _ldap_mod_realm: + +Modifying a Kerberos realm +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need to modify a realm, use the :ref:`kdb5_ldap_util(8)` +**modify** command as follows. + +.. include:: admin_commands/kdb5_ldap_util.rst + :start-after: _kdb5_ldap_util_modify: + :end-before: _kdb5_ldap_util_modify_end: + + +Destroying a Kerberos realm +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need to destroy a Kerberos realm, use the +:ref:`kdb5_ldap_util(8)` **destroy** command as follows. + +.. include:: admin_commands/kdb5_ldap_util.rst + :start-after: _kdb5_ldap_util_destroy: + :end-before: _kdb5_ldap_util_destroy_end: + + +Retrieving information about a Kerberos realm +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need to display the attributes of a realm, use the +:ref:`kdb5_ldap_util(8)` **view** command as follows. + +.. include:: admin_commands/kdb5_ldap_util.rst + :start-after: _kdb5_ldap_util_view: + :end-before: _kdb5_ldap_util_view_end: + + +Listing available Kerberos realms +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need to display the list of the realms, use the +:ref:`kdb5_ldap_util(8)` **list** command as follows. + +.. include:: admin_commands/kdb5_ldap_util.rst + :start-after: _kdb5_ldap_util_list: + :end-before: _kdb5_ldap_util_list_end: + + +.. _stash_ldap: + +Stashing service object's password +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :ref:`kdb5_ldap_util(8)` **stashsrvpw** command allows an +administrator to store the password of service object in a file. The +KDC and Administration server uses this password to authenticate to +the LDAP server. + +.. include:: admin_commands/kdb5_ldap_util.rst + :start-after: _kdb5_ldap_util_stashsrvpw: + :end-before: _kdb5_ldap_util_stashsrvpw_end: + + +Ticket Policy operations +~~~~~~~~~~~~~~~~~~~~~~~~ + +Creating a Ticket Policy +######################## + +To create a new ticket policy in directory , use the +:ref:`kdb5_ldap_util(8)` **create_policy** command. Ticket policy +objects are created under the realm container. + +.. include:: admin_commands/kdb5_ldap_util.rst + :start-after: _kdb5_ldap_util_create_policy: + :end-before: _kdb5_ldap_util_create_policy_end: + + +Modifying a Ticket Policy +######################### + +To modify a ticket policy in directory, use the +:ref:`kdb5_ldap_util(8)` **modify_policy** command. + +.. include:: admin_commands/kdb5_ldap_util.rst + :start-after: _kdb5_ldap_util_modify_policy: + :end-before: _kdb5_ldap_util_modify_policy_end: + + +Retrieving Information About a Ticket Policy +############################################ + +To display the attributes of a ticket policy, use the +:ref:`kdb5_ldap_util(8)` **view_policy** command. + +.. include:: admin_commands/kdb5_ldap_util.rst + :start-after: _kdb5_ldap_util_view_policy: + :end-before: _kdb5_ldap_util_view_policy_end: + + +Destroying a Ticket Policy +########################## + +To destroy an existing ticket policy, use the :ref:`kdb5_ldap_util(8)` +**destroy_policy** command. + +.. include:: admin_commands/kdb5_ldap_util.rst + :start-after: _kdb5_ldap_util_destroy_policy: + :end-before: _kdb5_ldap_util_destroy_policy_end: + + +Listing available Ticket Policies +################################# + +To list the name of ticket policies in a realm, use the +:ref:`kdb5_ldap_util(8)` **list_policy** command. + +.. include:: admin_commands/kdb5_ldap_util.rst + :start-after: _kdb5_ldap_util_list_policy: + :end-before: _kdb5_ldap_util_list_policy_end: + + +.. _xrealm_authn: + +Cross-realm authentication +-------------------------- + +In order for a KDC in one realm to authenticate Kerberos users in a +different realm, it must share a key with the KDC in the other realm. +In both databases, there must be krbtgt service principals for both realms. +For example, if you need to do cross-realm authentication between the realms +``ATHENA.MIT.EDU`` and ``EXAMPLE.COM``, you would need to add the +principals ``krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU`` and +``krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM`` to both databases. +These principals must all have the same passwords, key version +numbers, and encryption types; this may require explicitly setting +the key version number with the **-kvno** option. + +In the ATHENA.MIT.EDU and EXAMPLE.COM cross-realm case, the administrators +would run the following commands on the KDCs in both realms:: + + shell%: kadmin.local -e "aes256-cts:normal" + kadmin: addprinc -requires_preauth krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM + Enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM: + Re-enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM: + kadmin: addprinc -requires_preauth krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU + Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU: + Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU: + kadmin: + +.. note:: Even if most principals in a realm are generally created + with the **requires_preauth** flag enabled, this flag is not + desirable on cross-realm authentication keys because doing + so makes it impossible to disable preauthentication on a + service-by-service basis. Disabling it as in the example + above is recommended. + +.. note:: It is very important that these principals have good + passwords. MIT recommends that TGT principal passwords be + at least 26 characters of random ASCII text. + + +.. _changing_krbtgt_key: + +Changing the krbtgt key +----------------------- + +A Kerberos Ticket Granting Ticket (TGT) is a service ticket for the +principal ``krbtgt/REALM``. The key for this principal is created +when the Kerberos database is initialized and need not be changed. +However, it will only have the encryption types supported by the KDC +at the time of the initial database creation. To allow use of newer +encryption types for the TGT, this key has to be changed. + +Changing this key using the normal :ref:`kadmin(1)` +**change_password** command would invalidate any previously issued +TGTs. Therefore, when changing this key, normally one should use the +**-keepold** flag to change_password to retain the previous key in the +database as well as the new key. For example:: + + kadmin: change_password -randkey -keepold krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU + +.. warning:: After issuing this command, the old key is still valid + and is still vulnerable to (for instance) brute force + attacks. To completely retire an old key or encryption + type, run the kadmin **purgekeys** command to delete keys + with older kvnos, ideally first making sure that all + tickets issued with the old keys have expired. + + +.. _incr_db_prop: + +Incremental database propagation +-------------------------------- + +Overview +~~~~~~~~ + +At some very large sites, dumping and transmitting the database can +take more time than is desirable for changes to propagate from the +master KDC to the slave KDCs. The incremental propagation support +added in the 1.7 release is intended to address this. + +With incremental propagation enabled, all programs on the master KDC +that change the database also write information about the changes to +an "update log" file, maintained as a circular buffer of a certain +size. A process on each slave KDC connects to a service on the master +KDC (currently implemented in the :ref:`kadmind(8)` server) and +periodically requests the changes that have been made since the last +check. By default, this check is done every two minutes. If the +database has just been modified in the previous several seconds +(currently the threshold is hard-coded at 10 seconds), the slave will +not retrieve updates, but instead will pause and try again soon after. +This reduces the likelihood that incremental update queries will cause +delays for an administrator trying to make a bunch of changes to the +database at the same time. + +Incremental propagation uses the following entries in the per-realm +data in the KDC config file (See :ref:`kdc.conf(5)`): + +====================== =============== =========================================== +iprop_enable *boolean* If *true*, then incremental propagation is enabled, and (as noted below) normal kprop propagation is disabled. The default is *false*. +iprop_master_ulogsize *integer* Indicates the number of entries that should be retained in the update log. The default is 1000; the maximum number is 2500. +iprop_slave_poll *time interval* Indicates how often the slave should poll the master KDC for changes to the database. The default is two minutes. +iprop_port *integer* Specifies the port number to be used for incremental propagation. This is required in both master and slave configuration files. +iprop_resync_timeout *integer* Specifies the number of seconds to wait for a full propagation to complete. This is optional on slave configurations. Defaults to 300 seconds (5 minutes). +iprop_logfile *file name* Specifies where the update log file for the realm database is to be stored. The default is to use the *database_name* entry from the realms section of the config file :ref:`kdc.conf(5)`, with *.ulog* appended. (NOTE: If database_name isn't specified in the realms section, perhaps because the LDAP database back end is being used, or the file name is specified in the *dbmodules* section, then the hard-coded default for *database_name* is used. Determination of the *iprop_logfile* default value will not use values from the *dbmodules* section.) +====================== =============== =========================================== + +Both master and slave sides must have a principal named +``kiprop/hostname`` (where *hostname* is the lowercase, +fully-qualified, canonical name for the host) registered in the +Kerberos database, and have keys for that principal stored in the +default keytab file (|keytab|). + +On the master KDC side, the ``kiprop/hostname`` principal must be +listed in the kadmind ACL file :ref:`kadm5.acl(5)`, and given the +**p** privilege (see :ref:`privileges`). + +On the slave KDC side, :ref:`kpropd(8)` should be run. When +incremental propagation is enabled, it will connect to the kadmind on +the master KDC and start requesting updates. + +The normal kprop mechanism is disabled by the incremental propagation +support. However, if the slave has been unable to fetch changes from +the master KDC for too long (network problems, perhaps), the log on +the master may wrap around and overwrite some of the updates that the +slave has not yet retrieved. In this case, the slave will instruct +the master KDC to dump the current database out to a file and invoke a +one-time kprop propagation, with special options to also convey the +point in the update log at which the slave should resume fetching +incremental updates. Thus, all the keytab and ACL setup previously +described for kprop propagation is still needed. + +There are several known bugs and restrictions in the current +implementation: + +- The "call out to kprop" mechanism is a bit fragile; if the kprop + propagation fails to connect for some reason, the process on the + slave may hang waiting for it, and will need to be restarted. +- The master and slave must be able to initiate TCP connections in + both directions, without an intervening NAT. + + +Sun/MIT incremental propagation differences +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sun donated the original code for supporting incremental database +propagation to MIT. Some changes have been made in the MIT source +tree that will be visible to administrators. (These notes are based +on Sun's patches. Changes to Sun's implementation since then may not +be reflected here.) + +The Sun config file support looks for ``sunw_dbprop_enable``, +``sunw_dbprop_master_ulogsize``, and ``sunw_dbprop_slave_poll``. + +The incremental propagation service is implemented as an ONC RPC +service. In the Sun implementation, the service is registered with +rpcbind (also known as portmapper) and the client looks up the port +number to contact. In the MIT implementation, where interaction with +some modern versions of rpcbind doesn't always work well, the port +number must be specified in the config file on both the master and +slave sides. + +The Sun implementation hard-codes pathnames in ``/var/krb5`` for the +update log and the per-slave kprop dump files. In the MIT +implementation, the pathname for the update log is specified in the +config file, and the per-slave dump files are stored in +|kdcdir|\ ``/slave_datatrans_hostname``. diff --git a/doc/admins/env_variables.rst b/doc/admins/env_variables.rst new file mode 100644 index 000000000..e85d54da0 --- /dev/null +++ b/doc/admins/env_variables.rst @@ -0,0 +1,45 @@ +Environment variables +===================== + +The following environment variables can be used during runtime: + +**KRB5_CONFIG** + Main Kerberos configuration file. (See :ref:`mitK5defaults` for + the default name.) + +**KRB5_KDC_PROFILE** + KDC configuration file. (See :ref:`mitK5defaults` for the default + name.) + +**KRB5_KTNAME** + Default keytab file name. (See :ref:`mitK5defaults` for the + default name.) + +**KRB5_CLIENT_KTNAME** + Default client keytab file name. (See :ref:`mitK5defaults` for + the default name.) + +**KRB5CCNAME** + Default name for the credentials cache file, in the form *type*\:\ + *residual*. The type of the default cache may determine the + availability of a cache collection. For instance, a default cache + of type ``DIR`` causes caches within the directory to be present + in the global cache collection. + +**KRB5RCACHETYPE** + Default replay cache type. Defaults to ``dfl``. A value of + ``none`` disables the replay cache. + +**KRB5RCACHEDIR** + Default replay cache directory. (See :ref:`mitK5defaults` for the + default location.) + +**KPROP_PORT** + :ref:`kprop(8)` port to use. Defaults to 754. + +**KRB5_TRACE** + Filename for trace-logging output (introduced in release 1.9). + For example, ``env KRB5_TRACE=/dev/stdout kinit`` would send + tracing information for kinit to ``/dev/stdout``. Some programs + may ignore this variable (particularly setuid or login system + programs). diff --git a/doc/admins/host_config.rst b/doc/admins/host_config.rst new file mode 100644 index 000000000..e5ef06bf1 --- /dev/null +++ b/doc/admins/host_config.rst @@ -0,0 +1,110 @@ +Host configuration +================== + +All hosts running Kerberos software, whether they are clients, +application servers, or KDCs, can be configured using +:ref:`krb5.conf(5)`. Here we describe some of the behavior changes +you might want to make. + + +.. _plugin_config: + +Plugin module configuration +--------------------------- + +Many aspects of Kerberos behavior, such as client preauthentication +and KDC service location, can be modified through the use of plugin +modules. For most of these behaviors, you can use the :ref:`plugins` +section of krb5.conf to register third-party modules, and to switch +off registered or built-in modules. + +A plugin module takes the form of a Unix shared object +(``modname.so``) or Windows DLL (``modname.dll``). If you have +installed a third-party plugin module and want to register it, you do +so using the **module** relation in the appropriate subsection of the +[plugins] section. The value for **module** must give the module name +and the path to the module, separated by a colon. The module name +will often be the same as the shared object's name, but in unusual +cases (such as a shared object which implements multiple modules for +the same interface) it might not be. For example, to register a +client preauthentication module named ``otp`` installed at +``/path/to/otp.so``, you could write:: + + [plugins] + clpreauth = { + module = otp:/path/to/otp.so + } + +Many of the pluggable behaviors in MIT krb5 contain built-in modules +which can be switched off. You can disable a built-in module (or one +you have registered) using the **disable** directive in the +appropriate subsection of the [plugins] section. For example, to +disable the use of .k5identity files to select credential caches, you +could write:: + + [plugins] + ccselect = { + disable = k5identity + } + +If you want to disable multiple modules, specify the **disable** +directive multiple times, giving one module to disable each time. + +Alternatively, you can explicitly specify which modules you want to be +enabled for that behavior using the **enable_only** directive. For +example, to make :ref:`kadmind(8)` check password quality using only a +module you have registered, and no other mechanism, you could write:: + + [plugins] + pwqual = { + module = mymodule:/path/to/mymodule.so + enable_only = mymodule + } + +Again, if you want to specify multiple modules, specify the +**enable_only** directive multiple times, giving one module to enable +each time. + +Some Kerberos interfaces use different mechanisms to register plugin +modules. + + +KDC location modules +~~~~~~~~~~~~~~~~~~~~ + +For historical reasons, modules to control how KDC servers are located +are registered simply by placing the shared object or DLL into the +"libkrb5" subdirectory of the krb5 plugin directory, which defaults to +|libdir|\ ``/krb5/plugins``. For example, Samba's winbind krb5 +locator plugin would be registered by placing its shared object in +|libdir|\ ``/krb5/plugins/libkrb5/winbind_krb5_locator.so``. + + +GSSAPI mechanism modules +~~~~~~~~~~~~~~~~~~~~~~~~ + +GSSAPI mechanism module are registered using the file +``/etc/gss/mech``. Each line in this file has the form:: + + oid pathname [options] + +where *oid* is the object identifier of the GSSAPI mechanism to be +registered, *pathname* is a path to the module shared object or DLL, +and *options* (if present) are options provided to the plugin module, +surrounded in square brackets. + + +.. _profile_plugin_config: + +Configuration profile modules +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A configuration profile module replaces the information source for +:ref:`krb5.conf(5)` itself. To use a profile module, begin krb5.conf +with the line:: + + module PATHNAME:STRING + +where *PATHNAME* is a path to the module shared object or DLL, and +*STRING* is a string to provide to the module. The module will then +take over, and the rest of krb5.conf will be ignored. diff --git a/doc/admins/index.rst b/doc/admins/index.rst new file mode 100644 index 000000000..96f1a310d --- /dev/null +++ b/doc/admins/index.rst @@ -0,0 +1,24 @@ +For administrators +================== + +.. toctree:: + :maxdepth: 1 + + install.rst + conf_files/index.rst + realm_config.rst + database.rst + conf_ldap.rst + appl_servers.rst + host_config.rst + backup_host.rst + +.. toctree:: + :maxdepth: 1 + + admin_commands/index.rst + ../mitK5defaults.rst + env_variables.rst + troubleshoot.rst + advanced/index.rst + various_envs.rst diff --git a/doc/admins/install.rst b/doc/admins/install.rst new file mode 100644 index 000000000..a79bda952 --- /dev/null +++ b/doc/admins/install.rst @@ -0,0 +1,21 @@ +Installation guide +================== + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + install_kdc.rst + install_clients.rst + install_appl_srv.rst + + +Additional references +--------------------- + +#. Debian: `Setting up MIT Kerberos 5 + `_ +#. Solaris: `Configuring the Kerberos Service + `_ diff --git a/doc/admins/install_appl_srv.rst b/doc/admins/install_appl_srv.rst new file mode 100644 index 000000000..149050098 --- /dev/null +++ b/doc/admins/install_appl_srv.rst @@ -0,0 +1,83 @@ +UNIX Application Servers +======================== + +An application server is a host that provides one or more services +over the network. Application servers can be "secure" or "insecure." +A "secure" host is set up to require authentication from every client +connecting to it. An "insecure" host will still provide Kerberos +authentication, but will also allow unauthenticated clients to +connect. + +If you have Kerberos V5 installed on all of your client machines, MIT +recommends that you make your hosts secure, to take advantage of the +security that Kerberos authentication affords. However, if you have +some clients that do not have Kerberos V5 installed, you can run an +insecure server, and still take advantage of Kerberos V5's single +sign-on capability. + + +.. _keytab_file: + +The keytab file +--------------- + +All Kerberos server machines need a keytab file to authenticate to the +KDC. By default on UNIX-like systems this file is named |keytab|. +The keytab file is an local copy of the host's key. The keytab file +is a potential point of entry for a break-in, and if compromised, +would allow unrestricted access to its host. The keytab file should +be readable only by root, and should exist only on the machine's local +disk. The file should not be part of any backup of the machine, +unless access to the backup data is secured as tightly as access to +the machine's root password. + +In order to generate a keytab for a host, the host must have a +principal in the Kerberos database. The procedure for adding hosts to +the database is described fully in :ref:`add_mod_del_princs`. (See +:ref:`slave_host_key` for a brief description.) The keytab is +generated by running :ref:`kadmin(1)` and issuing the :ref:`ktadd` +command. + +For example, to generate a keytab file to allow the host +``trillium.mit.edu`` to authenticate for the services host, ftp, and +pop, the administrator ``joeadmin`` would issue the command (on +``trillium.mit.edu``):: + + trillium% kadmin + kadmin5: ktadd host/trillium.mit.edu ftp/trillium.mit.edu + pop/trillium.mit.edu + kadmin: Entry for principal host/trillium.mit.edu@ATHENA.MIT.EDU with + kvno 3, encryption type DES-CBC-CRC added to keytab + FILE:/etc/krb5.keytab. + kadmin: Entry for principal ftp/trillium.mit.edu@ATHENA.MIT.EDU with + kvno 3, encryption type DES-CBC-CRC added to keytab + FILE:/etc/krb5.keytab. + kadmin: Entry for principal pop/trillium.mit.edu@ATHENA.MIT.EDU with + kvno 3, encryption type DES-CBC-CRC added to keytab + FILE:/etc/krb5.keytab. + kadmin5: quit + trillium% + +If you generate the keytab file on another host, you need to get a +copy of the keytab file onto the destination host (``trillium``, in +the above example) without sending it unencrypted over the network. + + +Some advice about secure hosts +------------------------------ + +Kerberos V5 can protect your host from certain types of break-ins, but +it is possible to install Kerberos V5 and still leave your host +vulnerable to attack. Obviously an installation guide is not the +place to try to include an exhaustive list of countermeasures for +every possible attack, but it is worth noting some of the larger holes +and how to close them. + +We recommend that backups of secure machines exclude the keytab file +(|keytab|). If this is not possible, the backups should at least be +done locally, rather than over a network, and the backup tapes should +be physically secured. + +The keytab file and any programs run by root, including the Kerberos +V5 binaries, should be kept on local disk. The keytab file should be +readable only by root. diff --git a/doc/admins/install_clients.rst b/doc/admins/install_clients.rst new file mode 100644 index 000000000..ec2cd8125 --- /dev/null +++ b/doc/admins/install_clients.rst @@ -0,0 +1,57 @@ +Installing and configuring UNIX client machines +=============================================== + +The Kerberized client programs include :ref:`kinit(1)`, +:ref:`klist(1)`, :ref:`kdestroy(1)`, and :ref:`kpasswd(1)`. All of +these programs are in the directory |bindir|. + +You can often integrate Kerberos with the login system on client +machines, typically through the use of PAM. The details vary by +operating system, and should be covered in your operating system's +documentation. If you do this, you will need to make sure your users +know to use their Kerberos passwords when they log in. + +You will also need to educate your users to use the ticket management +programs kinit, klist, and kdestroy. If you do not have Kerberos +password changing integrated into the native password program (again, +typically through PAM), you will need to educate users to use kpasswd +in place of its non-Kerberos counterparts passwd. + + +Client machine configuration files +---------------------------------- + +Each machine running Kerberos should have a :ref:`krb5.conf(5)` file. +At a minimum, it should define a **default_realm** setting in +:ref:`libdefaults`. If you are not using DNS SRV records, it must +also contain a :ref:`realms` section containing information for your +realm's KDCs. + +Consider setting **rdns** to false in order to reduce your dependence +on precisely correct DNS information for service hostnames. Turning +this flag off means that service hostnames will be canonicalized +through forward name resolution (which adds your domain name to +unqualified hostnames, and resolves CNAME records in DNS), but not +through reverse address lookup. The default value of this flag is +true for historical reasons only. + +If you anticipate users frequently logging into remote hosts +(e.g., using ssh) using forwardable credentials, consider setting +**forwardable** to true so that users obtain forwardable tickets by +default. Otherwise users will need to use ``kinit -f`` to get +forwardable tickets. + +Consider adjusting the **ticket_lifetime** setting to match the likely +length of sessions for your users. For instance, if most of your +users will be logging in for an eight-hour workday, you could set the +default to ten hours so that tickets obtained in the morning expire +shortly after the end of the workday. Users can still manually +request longer tickets when necessary, up to the maximum allowed by +each user's principal record on the KDC. + +If a client host may access services in different realms, it may be +useful to define a :ref:`domain_realm` mapping so that clients know +which hosts belong to which realms. However, if your clients and KDC +are running release 1.7 or later, it is also reasonable to leave this +section out on client machines and just define it in the KDC's +krb5.conf. diff --git a/doc/admins/install_kdc.rst b/doc/admins/install_kdc.rst new file mode 100644 index 000000000..3d0d0f1f4 --- /dev/null +++ b/doc/admins/install_kdc.rst @@ -0,0 +1,525 @@ +Installing KDCs +=============== + +When setting up Kerberos in a production environment, it is best to +have multiple slave KDCs alongside with a master KDC to ensure the +continued availability of the Kerberized services. Each KDC contains +a copy of the Kerberos database. The master KDC contains the writable +copy of the realm database, which it replicates to the slave KDCs at +regular intervals. All database changes (such as password changes) +are made on the master KDC. Slave KDCs provide Kerberos +ticket-granting services, but not database administration, when the +master KDC is unavailable. MIT recommends that you install all of +your KDCs to be able to function as either the master or one of the +slaves. This will enable you to easily switch your master KDC with +one of the slaves if necessary (see :ref:`switch_master_slave`). This +installation procedure is based on that recommendation. + +.. warning:: + - The Kerberos system relies on the availability of correct time + information. Ensure that the master and all slave KDCs have + properly synchronized clocks. + + - It is best to install and run KDCs on secured and dedicated + hardware with limited access. If your KDC is also a file + server, FTP server, Web server, or even just a client machine, + someone who obtained root access through a security hole in any + of those areas could potentially gain access to the Kerberos + database. + + +Install and configure the master KDC +------------------------------------ + +Install Kerberos either from the OS-provided packages or from the +source (See :ref:`do_build`). + +.. note:: For the purpose of this document we will use the following + names:: + + kerberos.mit.edu - master KDC + kerberos-1.mit.edu - slave KDC + ATHENA.MIT.EDU - realm name + .k5.ATHENA.MIT.EDU - stash file + admin/admin - admin principal + + See :ref:`mitK5defaults` for the default names and locations + of the relevant to this topic files. Adjust the names and + paths to your system environment. + + +Edit KDC configuration files +---------------------------- + +Modify the configuration files, :ref:`krb5.conf(5)` and +:ref:`kdc.conf(5)`, to reflect the correct information (such as +domain-realm mappings and Kerberos servers names) for your realm. +(See :ref:`mitK5defaults` for the recommended default locations for +these files). + +Most of the tags in the configuration have default values that will +work well for most sites. There are some tags in the +:ref:`krb5.conf(5)` file whose values must be specified, and this +section will explain those. + +If the locations for these configuration files differs from the +default ones, set **KRB5_CONFIG** and **KRB5_KDC_PROFILE** environment +variables to point to the krb5.conf and kdc.conf respectively. For +example:: + + export KRB5_CONFIG=/yourdir/krb5.conf + export KRB5_KDC_PROFILE=/yourdir/kdc.conf + + +krb5.conf +~~~~~~~~~ + +If you are not using DNS TXT records (see :ref:`mapping_hostnames`), +you must specify the **default_realm** in the :ref:`libdefaults` +section. If you are not using DNS SRV records (see +:ref:`kdc_hostnames`), you must include the **kdc** tag for each +*realm* in the :ref:`realms` section. To communicate with the kadmin +server in each realm, the **admin_server** tag must be set in the +:ref:`realms` section. + +An example krb5.conf file:: + + [libdefaults] + default_realm = ATHENA.MIT.EDU + + [realms] + ATHENA.MIT.EDU = { + kdc = kerberos.mit.edu + kdc = kerberos-1.mit.edu + admin_server = kerberos.mit.edu + } + + +kdc.conf +~~~~~~~~ + +The kdc.conf file can be used to control the listening ports of the +KDC and kadmind, as well as realm-specific defaults, the database type +and location, and logging. + +An example kdc.conf file:: + + [kdcdefaults] + kdc_ports = 88,750 + + [realms] + ATHENA.MIT.EDU = { + kadmind_port = 749 + max_life = 12h 0m 0s + max_renewable_life = 7d 0h 0m 0s + master_key_type = aes256-cts + supported_enctypes = aes256-cts:normal aes128-cts:normal + # If the default location does not suit your setup, + # explicitly configure the following values: + # database_name = /var/krb5kdc/principal + # key_stash_file = /var/krb5kdc/.k5.ATHENA.MIT.EDU + # acl_file = /var/krb5kdc/kadm5.acl + } + + [logging] + # By default, the KDC and kadmind will log output using + # syslog. You can instead send log output to files like this: + kdc = FILE:/var/log/krb5kdc.log + admin_server = FILE:/var/log/kadmin.log + default = FILE:/var/log/krb5lib.log + +Replace ``ATHENA.MIT.EDU`` and ``kerberos.mit.edu`` with the name of +your Kerberos realm and server respectively. + +.. note:: You have to have write permission on the target directories + (these directories must exist) used by **database_name**, + **key_stash_file**, and **acl_file**. + + +.. _create_db: + +Create the KDC database +----------------------- + +You will use the :ref:`kdb5_util(8)` command on the master KDC to +create the Kerberos database and the optional :ref:`stash_definition`. + +.. note:: If you choose not to install a stash file, the KDC will + prompt you for the master key each time it starts up. This + means that the KDC will not be able to start automatically, + such as after a system reboot. + +:ref:`kdb5_util(8)` will prompt you for the master password for the +Kerberos database. This password can be any string. A good password +is one you can remember, but that no one else can guess. Examples of +bad passwords are words that can be found in a dictionary, any common +or popular name, especially a famous person (or cartoon character), +your username in any form (e.g., forward, backward, repeated twice, +etc.), and any of the sample passwords that appear in this manual. +One example of a password which might be good if it did not appear in +this manual is "MITiys4K5!", which represents the sentence "MIT is +your source for Kerberos 5!" (It's the first letter of each word, +substituting the numeral "4" for the word "for", and includes the +punctuation mark at the end.) + +The following is an example of how to create a Kerberos database and +stash file on the master KDC, using the :ref:`kdb5_util(8)` command. +Replace ``ATHENA.MIT.EDU`` with the name of your Kerberos realm:: + + shell% kdb5_util create -r ATHENA.MIT.EDU -s + + Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU', + master key name 'K/M@ATHENA.MIT.EDU' + You will be prompted for the database Master Password. + It is important that you NOT FORGET this password. + Enter KDC database master key: <= Type the master password. + Re-enter KDC database master key to verify: <= Type it again. + shell% + +This will create five files in |kdcdir| (or at the locations specified +in :ref:`kdc.conf(5)`): + +* two Kerberos database files, ``principal``, and ``principal.ok`` +* the Kerberos administrative database file, ``principal.kadm5`` +* the administrative database lock file, ``principal.kadm5.lock`` +* the stash file, in this example ``.k5.ATHENA.MIT.EDU``. If you do + not want a stash file, run the above command without the **-s** + option. + +For more information on administrating Kerberos database see +:ref:`db_operations`. + + +.. _admin_acl: + +Add administrators to the ACL file +---------------------------------- + +Next, you need create an Access Control List (ACL) file and put the +Kerberos principal of at least one of the administrators into it. +This file is used by the :ref:`kadmind(8)` daemon to control which +principals may view and make privileged modifications to the Kerberos +database files. The ACL filename is determined by the **acl_file** +variable in :ref:`kdc.conf(5)`; the default is |kdcdir|\ +``/kadm5.acl``. + +For more information on Kerberos ACL file see :ref:`kadm5.acl(5)`. + +.. _addadmin_kdb: + +Add administrators to the Kerberos database +------------------------------------------- + +Next you need to add administrative principals (i.e., principals who +are allowed to administer Kerberos database) to the Kerberos database. +You *must* add at least one principal now to allow communication +between the Kerberos administration daemon kadmind and the kadmin +program over the network for further administration. To do this, use +the kadmin.local utility on the master KDC. kadmin.local is designed +to be run on the master KDC host without using Kerberos authentication +to an admin server; instead, it must have read and write access to the +Kerberos database on the local filesystem. + +The administrative principals you create should be the ones you added +to the ACL file (see :ref:`admin_acl`). + +In the following example, the administrative principal ``admin/admin`` +is created:: + + shell% kadmin.local + + kadmin.local: addprinc admin/admin@ATHENA.MIT.EDU + + WARNING: no policy specified for "admin/admin@ATHENA.MIT.EDU"; + assigning "default". + Enter password for principal admin/admin@ATHENA.MIT.EDU: <= Enter a password. + Re-enter password for principal admin/admin@ATHENA.MIT.EDU: <= Type it again. + Principal "admin/admin@ATHENA.MIT.EDU" created. + kadmin.local: + +.. _start_kdc_daemons: + +Start the Kerberos daemons on the master KDC +-------------------------------------------- + +At this point, you are ready to start the Kerberos KDC +(:ref:`krb5kdc(8)`) and administrative daemons on the Master KDC. To +do so, type:: + + shell% krb5kdc + shell% kadmind + +Each server daemon will fork and run in the background. + +.. note:: Assuming you want these daemons to start up automatically at + boot time, you can add them to the KDC's ``/etc/rc`` or + ``/etc/inittab`` file. You need to have a + :ref:`stash_definition` in order to do this. + +You can verify that they started properly by checking for their +startup messages in the logging locations you defined in +:ref:`krb5.conf(5)` (see :ref:`logging`). For example:: + + shell% tail /var/log/krb5kdc.log + Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation + shell% tail /var/log/kadmin.log + Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting + +Any errors the daemons encounter while starting will also be listed in +the logging output. + +As an additional verification, check if :ref:`kinit(1)` succeeds +against the principals that you have created on the previous step +(:ref:`addadmin_kdb`). Run:: + + shell% kinit admin/admin@ATHENA.MIT.EDU + + +Install the slave KDCs +---------------------- + +You are now ready to start configuring the slave KDCs. + +.. note:: Assuming you are setting the KDCs up so that you can easily + switch the master KDC with one of the slaves, you should + perform each of these steps on the master KDC as well as the + slave KDCs, unless these instructions specify otherwise. + + +.. _slave_host_key: + +Create host keytabs for slave KDCs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Each KDC needs a ``host`` key in the Kerberos database. These keys +are used for mutual authentication when propagating the database dump +file from the master KDC to the secondary KDC servers. + +On the master KDC, connect to administrative interface and create the +host principal for each of the KDCs' ``host`` services. For example, +if the master KDC were called ``kerberos.mit.edu``, and you had a +slave KDC named ``kerberos-1.mit.edu``, you would type the following:: + + shell% kadmin + kadmin: addprinc -randkey host/kerberos.mit.edu + NOTICE: no policy specified for "host/kerberos.mit.edu@ATHENA.MIT.EDU"; assigning "default" + Principal "host/kerberos.mit.edu@ATHENA.MIT.EDU" created. + + kadmin: addprinc -randkey host/kerberos-1.mit.edu + NOTICE: no policy specified for "host/kerberos-1.mit.edu@ATHENA.MIT.EDU"; assigning "default" + Principal "host/kerberos-1.mit.edu@ATHENA.MIT.EDU" created. + +It is not strictly necessary to have the master KDC server in the +Kerberos database, but it can be handy if you want to be able to swap +the master KDC with one of the slaves. + +Next, extract ``host`` random keys for all participating KDCs and +store them in each host's default keytab file. Ideally, you should +extract each keytab locally on its own KDC. If this is not feasible, +you should use an encrypted session to send them across the network. +To extract a keytab on a slave KDC called ``kerberos-1.mit.edu``, you +would execute the following command:: + + kadmin: ktadd host/kerberos-1.mit.edu + Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption + type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab. + Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption + type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab. + Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption + type des3-cbc-sha1 added to keytab FILE:/etc/krb5.keytab. + Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption + type arcfour-hmac added to keytab FILE:/etc/krb5.keytab. + + +Configure slave KDCs +~~~~~~~~~~~~~~~~~~~~ + +Database propagation copies the contents of the master's database, but +does not propagate configuration files, stash files, or the kadm5 ACL +file. The following files must be copied by hand to each slave (see +:ref:`mitK5defaults` for the default locations for these files): + +* krb5.conf +* kdc.conf +* kadm5.acl +* master key stash file + +Move the copied files into their appropriate directories, exactly as +on the master KDC. kadm5.acl is only needed to allow a slave to swap +with the master KDC. + +The database is propagated from the master KDC to the slave KDCs via +the :ref:`kpropd(8)` daemon. You must explicitly specify the +principals which are allowed to provide Kerberos dump updates on the +slave machine with a new database. Create a file named kpropd.acl in +the KDC state directory containing the ``host`` principals for each of +the KDCs:: + + host/kerberos.mit.edu@ATHENA.MIT.EDU + host/kerberos-1.mit.edu@ATHENA.MIT.EDU + +.. note:: If you expect that the master and slave KDCs will be + switched at some point of time, list the host principals + from all participating KDC servers in kpropd.acl files on + all of the KDCs. Otherwise, you only need to list the + master KDC's host principal in the kpropd.acl files of the + slave KDCs. + +Then, add the following line to ``/etc/inetd.conf`` on each KDC +(adjust the path to kpropd):: + + krb5_prop stream tcp nowait root /usr/local/sbin/kpropd kpropd + +You also need to add the following line to ``/etc/services`` on each +KDC, if it is not already present (assuming that the default port is +used):: + + krb5_prop 754/tcp # Kerberos slave propagation + +Restart inetd daemon. + +Alternatively, start :ref:`kpropd(8)` as a stand-alone daemon. This is +required when incremental propagation is enabled. + +Now that the slave KDC is able to accept database propagation, you’ll +need to propagate the database from the master server. + +NOTE: Do not start the slave KDC yet; you still do not have a copy of +the master's database. + + +.. _kprop_to_slaves: + +Propagate the database to each slave KDC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, create a dump file of the database on the master KDC, as +follows:: + + shell% kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans + +Then, manually propagate the database to each slave KDC, as in the +following example:: + + shell% kprop -f /usr/local/var/krb5kdc/slave_datatrans kerberos-1.mit.edu + + Database propagation to kerberos-1.mit.edu: SUCCEEDED + +You will need a script to dump and propagate the database. The +following is an example of a Bourne shell script that will do this. + +.. note:: Remember that you need to replace ``/usr/local/var/krb5kdc`` + with the name of the KDC state directory. + +:: + + #!/bin/sh + + kdclist = "kerberos-1.mit.edu kerberos-2.mit.edu" + + kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans + + for kdc in $kdclist + do + kprop -f /usr/local/var/krb5kdc/slave_datatrans $kdc + done + +You will need to set up a cron job to run this script at the intervals +you decided on earlier (see :ref:`db_prop`). + +Now that the slave KDC has a copy of the Kerberos database, you can +start the krb5kdc daemon:: + + shell% krb5kdc + +As with the master KDC, you will probably want to add this command to +the KDCs' ``/etc/rc`` or ``/etc/inittab`` files, so they will start +the krb5kdc daemon automatically at boot time. + + +Propagation failed? +################### + +.. _prop_failed_start: + +.. error:: kprop: No route to host while connecting to server + +Make sure that the hostname of the slave (as given to kprop) is +correct, and that any firewalls beween the master and the slave allow +a connection on port 754. + +.. error:: kprop: Connection refused in call to connect while opening + connection + +If the slave is intended to run kpropd out of inetd, make sure that +inetd is configured to accept krb5_prop connections. inetd may need +to be restarted or sent a SIGHUP to recognize the new configuration. +If the slave is intended to run kpropd in standalone mode, make sure +that it is running. + +.. error:: kprop: Server rejected authentication while authenticating + to server + +Make sure that: + +#. The time is syncronized between the master and slave KDCs. +#. The master stash file was copied from the master to the expected + location on the slave. +#. The slave has a keytab file in the default location containing a + ``host`` principal for the slave's hostname. + +.. _prop_failed_end: + + +Add Kerberos principals to the database +--------------------------------------- + +Once your KDCs are set up and running, you are ready to use +:ref:`kadmin(1)` to load principals for your users, hosts, and other +services into the Kerberos database. This procedure is described +fully in :ref:`add_mod_del_princs`. + +You may occasionally want to use one of your slave KDCs as the master. +This might happen if you are upgrading the master KDC, or if your +master KDC has a disk crash. See the following section for the +instructions. + + +.. _switch_master_slave: + +Switching master and slave KDCs +------------------------------- + +You may occasionally want to use one of your slave KDCs as the master. +This might happen if you are upgrading the master KDC, or if your +master KDC has a disk crash. + +Assuming you have configured all of your KDCs to be able to function +as either the master KDC or a slave KDC (as this document recommends), +all you need to do to make the changeover is: + +If the master KDC is still running, do the following on the *old* +master KDC: + +#. Kill the kadmind process. +#. Disable the cron job that propagates the database. +#. Run your database propagation script manually, to ensure that the + slaves all have the latest copy of the database (see + :ref:`kprop_to_slaves`). + +On the *new* master KDC: + +#. Start the :ref:`kadmind(8)` daemon (see :ref:`start_kdc_daemons`). +#. Set up the cron job to propagate the database (see + :ref:`kprop_to_slaves`). +#. Switch the CNAMEs of the old and new master KDCs. If you can't do + this, you'll need to change the :ref:`krb5.conf(5)` file on every + client machine in your Kerberos realm. + + +Incremental database propagation +-------------------------------- + +If you expect your Kerberos database to become large, you may wish to +set up incremental propagation to slave KDCs. See :ref:`incr_db_prop` +for details. diff --git a/doc/admins/realm_config.rst b/doc/admins/realm_config.rst new file mode 100644 index 000000000..374703885 --- /dev/null +++ b/doc/admins/realm_config.rst @@ -0,0 +1,217 @@ +Realm configuration decisions +============================= + +Before installing Kerberos V5, it is necessary to consider the +following issues: + +* The name of your Kerberos realm (or the name of each realm, if you + need more than one). +* How you will assign your hostnames to Kerberos realms. +* Which ports your KDC and and kadmind services will use, if they will + not be using the default ports. +* How many slave KDCs you need and where they should be located. +* The hostnames of your master and slave KDCs. +* How frequently you will propagate the database from the master KDC + to the slave KDCs. + + +Realm name +---------- + +Although your Kerberos realm can be any ASCII string, convention is to +make it the same as your domain name, in upper-case letters. + +For example, hosts in the domain ``example.com`` would be in the +Kerberos realm:: + + EXAMPLE.COM + +If you need multiple Kerberos realms, MIT recommends that you use +descriptive names which end with your domain name, such as:: + + BOSTON.EXAMPLE.COM + HOUSTON.EXAMPLE.COM + + +.. _mapping_hostnames: + +Mapping hostnames onto Kerberos realms +-------------------------------------- + +Mapping hostnames onto Kerberos realms is done in one of three ways. + +The first mechanism works through a set of rules in the +:ref:`domain_realm` section of :ref:`krb5.conf(5)`. You can specify +mappings for an entire domain or on a per-hostname basis. Typically +you would do this by specifying the mappings for a given domain or +subdomain and listing the exceptions. + +The second mechanism is to use KDC host-based service referrals. With +this method, the KDC's krb5.conf has a full [domain_realm] mapping for +hosts, but the clients do not, or have mappings for only a subset of +the hosts they might contact. When a client needs to contact a server +host for which it has no mapping, it will ask the client realm's KDC +for the service ticket, and will receive a referral to the appropriate +service realm. + +To use referrals, clients must be running MIT krb5 1.6 or later, and +the KDC must be running MIT krb5 1.7 or later. The +**host_based_services** and **no_host_referral** variables in the +:ref:`kdc_realms` section of :ref:`kdc.conf(5)` can be used to +fine-tune referral behavior on the KDC. + +It is also possible for clients to use DNS TXT records, if +**dns_lookup_realm** is enabled in :ref:`krb5.conf(5)`. Such lookups +are disabled by default because DNS is an insecure protocol and security +holes could result if DNS records are spoofed. If enabled, the client +will try to look up a TXT record formed by prepending the prefix +``_kerberos`` to the hostname in question. If that record is not +found, the client will attempt a lookup by prepending ``_kerberos`` to the +host's domain name, then its parent domain, up to the top-level domain. +For the hostname ``boston.engineering.example.com``, the names looked up +would be:: + + _kerberos.boston.engineering.example.com + _kerberos.engineering.example.com + _kerberos.example.com + _kerberos.com + +The value of the first TXT record found is taken as the realm name. + +Even if you do not choose to use this mechanism within your site, +you may wish to set it up anyway, for use when interacting with other sites. + + +Ports for the KDC and admin services +------------------------------------ + +The default ports used by Kerberos are port 88 for the KDC and port +749 for the admin server. You can, however, choose to run on other +ports, as long as they are specified in each host's +:ref:`krb5.conf(5)` files or in DNS SRV records, and the +:ref:`kdc.conf(5)` file on each KDC. For a more thorough treatment of +port numbers used by the Kerberos V5 programs, refer to the +:ref:`conf_firewall`. + + +Slave KDCs +---------- + +Slave KDCs provide an additional source of Kerberos ticket-granting +services in the event of inaccessibility of the master KDC. The +number of slave KDCs you need and the decision of where to place them, +both physically and logically, depends on the specifics of your +network. + +Kerberos authentication requires that each client be able to contact a +KDC. Therefore, you need to anticipate any likely reason a KDC might +be unavailable and have a slave KDC to take up the slack. + +Some considerations include: + +* Have at least one slave KDC as a backup, for when the master KDC is + down, is being upgraded, or is otherwise unavailable. +* If your network is split such that a network outage is likely to + cause a network partition (some segment or segments of the network + to become cut off or isolated from other segments), have a slave KDC + accessible to each segment. +* If possible, have at least one slave KDC in a different building + from the master, in case of power outages, fires, or other localized + disasters. + + +.. _kdc_hostnames: + +Hostnames for KDCs +------------------ + +MIT recommends that your KDCs have a predefined set of CNAME records +(DNS hostname aliases), such as ``kerberos`` for the master KDC and +``kerberos-1``, ``kerberos-2``, ... for the slave KDCs. This way, if +you need to swap a machine, you only need to change a DNS entry, +rather than having to change hostnames. + +As of MIT krb5 1.4, clients can locate a realm's KDCs through DNS +using SRV records (:rfc:`2782`), assuming the Kerberos realm name is +also a DNS domain name. These records indicate the hostname and port +number to contact for that service, optionally with weighting and +prioritization. The domain name used in the SRV record name is the +realm name. Several different Kerberos-related service names are +used: + +_kerberos._udp + This is for contacting any KDC by UDP. This entry will be used + the most often. Normally you should list port 88 on each of your + KDCs. +_kerberos._tcp + This is for contacting any KDC by TCP. The MIT KDC by default + will not listen on any TCP ports, so unless you've changed the + configuration or you're running another KDC implementation, you + should leave this unspecified. If you do enable TCP support, + normally you should use port 88. +_kerberos-master._udp + This entry should refer to those KDCs, if any, that will + immediately see password changes to the Kerberos database. If a + user is logging in and the password appears to be incorrect, the + client will retry with the master KDC before failing with an + "incorrect password" error given. + + If you have only one KDC, or for whatever reason there is no + accessible KDC that would get database changes faster than the + others, you do not need to define this entry. +_kerberos-adm._tcp + This should list port 749 on your master KDC. Support for it is + not complete at this time, but it will eventually be used by the + :ref:`kadmin(1)` program and related utilities. For now, you will + also need the **admin_server** variable in :ref:`krb5.conf(5)`. +_kpasswd._udp + This should list port 464 on your master KDC. It is used when a + user changes her password. If this entry is not defined but a + _kerberos-adm._tcp entry is defined, the client will use the + _kerberos-adm._tcp entry with the port number changed to 749. + +The DNS SRV specification requires that the hostnames listed be the +canonical names, not aliases. So, for example, you might include the +following records in your (BIND-style) zone file:: + + $ORIGIN foobar.com. + _kerberos TXT "FOOBAR.COM" + kerberos CNAME daisy + kerberos-1 CNAME use-the-force-luke + kerberos-2 CNAME bunny-rabbit + _kerberos._udp SRV 0 0 88 daisy + SRV 0 0 88 use-the-force-luke + SRV 0 0 88 bunny-rabbit + _kerberos-master._udp SRV 0 0 88 daisy + _kerberos-adm._tcp SRV 0 0 749 daisy + _kpasswd._udp SRV 0 0 464 daisy + +Clients can also be configured with the explicit location of services +using the **kdc**, **master_kdc**, **admin_server**, and +**kpasswd_server** variables in the :ref:`realms` section of +:ref:`krb5.conf(5)`. Even if some clients will be configured with +explicit server locations, providing SRV records will still benefit +unconfigured clients, and be useful for other sites. + + +.. _db_prop: + +Database propagation +-------------------- + +The Kerberos database resides on the master KDC, and must be +propagated regularly (usually by a cron job) to the slave KDCs. In +deciding how frequently the propagation should happen, you will need +to balance the amount of time the propagation takes against the +maximum reasonable amount of time a user should have to wait for a +password change to take effect. + +If the propagation time is longer than this maximum reasonable time +(e.g., you have a particularly large database, you have a lot of +slaves, or you experience frequent network delays), you may wish to +cut down on your propagation delay by performing the propagation in +parallel. To do this, have the master KDC propagate the database to +one set of slaves, and then have each of these slaves propagate the +database to additional slaves. + +See also :ref:`incr_db_prop` diff --git a/doc/admins/troubleshoot.rst b/doc/admins/troubleshoot.rst new file mode 100644 index 000000000..7dc25795d --- /dev/null +++ b/doc/admins/troubleshoot.rst @@ -0,0 +1,53 @@ +Troubleshooting +=============== + +Trace logging +------------- + +Most programs using MIT krb5 1.9 or later can be made to provide +information about internal krb5 library operations using trace +logging. To enable this, set the **KRB5_TRACE** environment variable +to a filename before running the program. On many operating systems, +the filename ``/dev/stdout`` can be used to send trace logging output +to standard output. + +Some programs do not honor **KRB5_TRACE**, either because they use +secure library contexts (this generally applies to setuid programs and +parts of the login system) or because they take direct control of the +trace logging system using the API. + +Here is a short example showing trace logging output for an invocation +of the :ref:`kvno(1)` command:: + + shell% env KRB5_TRACE=/dev/stdout kvno krbtgt/KRBTEST.COM + [9138] 1332348778.823276: Getting credentials user@KRBTEST.COM -> + krbtgt/KRBTEST.COM@KRBTEST.COM using ccache + FILE:/me/krb5/build/testdir/ccache + [9138] 1332348778.823381: Retrieving user@KRBTEST.COM -> + krbtgt/KRBTEST.COM@KRBTEST.COM from + FILE:/me/krb5/build/testdir/ccache with result: 0/Unknown code 0 + krbtgt/KRBTEST.COM@KRBTEST.COM: kvno = 1 + +List +---- + +.. error:: KDC has no support for encryption type while getting + initial credentials + +.. error:: credential verification failed: KDC has no support for + encryption type + +This most commonly happens when trying to use a principal with only +DES keys, in a release (MIT krb5 1.7 or later) which disables DES by +default. DES encryption is considered weak due to its inadequate key +size. If you cannot migrate away from its use, you can re-enable DES +by adding ``allow_weak_crypto = true`` to the :ref:`libdefaults` +section of :ref:`krb5.conf(5)`. + +Seen in: clients + +---- + +.. include:: ./install_kdc.rst + :start-after: _prop_failed_start: + :end-before: _prop_failed_end: diff --git a/doc/admins/various_envs.rst b/doc/admins/various_envs.rst new file mode 100644 index 000000000..c32ac05f6 --- /dev/null +++ b/doc/admins/various_envs.rst @@ -0,0 +1,33 @@ +Various links +============= + +Whitepapers +----------- + +#. http://kerberos.org/software/whitepapers.html + + +Tutorials +--------- + +#. Fulvio Ricciardi _ + + +Troubleshooting +--------------- + +#. http://www.ncsa.illinois.edu/UserInfo/Resources/Software/kerberos/troubleshooting.html + +#. http://nfsv4.bullopensource.org/doc/kerberosnfs/krbnfs_howto_v3.pdf + +#. http://sysdoc.doors.ch/HP/T1417-90005.pdf + +#. http://www.shrubbery.net/solaris9ab/SUNWaadm/SYSADV6/p27.html + +#. http://download.oracle.com/docs/cd/E19253-01/816-4557/trouble-1/index.html + +#. http://technet.microsoft.com/en-us/library/bb463167.aspx#EBAA + +#. https://bugs.launchpad.net/ubuntu/+source/libpam-heimdal/+bug/86528 + +#. http://h71000.www7.hp.com/doc/83final/ba548_90007/ch06s05.html diff --git a/doc/appldev/gssapi.rst b/doc/appldev/gssapi.rst new file mode 100644 index 000000000..29c06b565 --- /dev/null +++ b/doc/appldev/gssapi.rst @@ -0,0 +1,220 @@ +Developing with GSSAPI +====================== + +The GSSAPI (Generic Security Services API) allows applications to +communicate securely using Kerberos 5 or other security mechanisms. +We recommend using the GSSAPI (or a higher-level framework which +encompasses GSSAPI, such as SASL) for secure network communication +over using the libkrb5 API directly. + +GSSAPIv2 is specified in :rfc:`2743` and :rfc:`2744`. This +documentation will describe how various ways of using GSSAPI will +behave with the krb5 mechanism as implemented in MIT krb5, as well as +krb5-specific extensions to the GSSAPI. + + +Name types +---------- + +A GSSAPI application can name a local or remote entity by calling +gss_import_name_, specifying a name type and a value. The following +name types are supported by the krb5 mechanism: + +* **GSS_C_NT_HOSTBASED_SERVICE**: The value should be a string of the + form ``service`` or ``service@hostname``. This is the most common + way to name target services when initiating a security context, and + is the most likely name type to work across multiple mechanisms. + +* **GSS_KRB5_NT_PRINCIPAL_NAME**: The value should be a principal name + string. This name type only works with the krb5 mechanism, and is + defined in the ```` header. + +* **GSS_C_NT_USER_NAME** or **GSS_C_NULL_OID**: The value is treated + as an unparsed principal name string, as above. These name types + may work with mechanisms other than krb5, but will have different + interpretations in those mechanisms. **GSS_C_NT_USER_NAME** is + intended to be used with a local username, which will parse into a + single-component principal in the default realm. + +* **GSS_C_NT_ANONYMOUS**: The value is ignored. The anonymous + principal is used, allowing a client to authenticate to a server + without asserting a particular identity (which may or may not be + allowed by a particular server or Kerberos realm). + +* **GSS_C_NT_MACHINE_UID_NAME**: The value is uid_t object. On + Unix-like systems, the username of the uid is looked up in the + system user database and the resulting username is parsed as a + principal name. + +* **GSS_C_NT_STRING_UID_NAME**: As above, but the value is a decimal + string representation of the uid. + +* **GSS_C_NT_EXPORT_NAME**: The value must be the result of a + gss_export_name_ call. + + +Initiator credentials +--------------------- + +A GSSAPI client application uses gss_init_sec_context_ to establish a +security context. The *initiator_cred_handle* parameter determines +what tickets are used to establish the connection. An application can +either pass **GSS_C_NO_CREDENTIAL** to use the default client +credential, or it can use gss_acquire_cred_ beforehand to acquire an +initiator credential. The call to gss_acquire_cred_ may include a +*desired_name* parameter, or it may pass **GSS_C_NO_NAME** if it does +not have a specific name preference. + +If the desired name for a krb5 initiator credential is a host-based +name, it is converted to a principal name of the form +``service/hostname`` in the local realm, where *hostname* is the local +hostname if not specified. The hostname will be canonicalized using +forward name resolution, and possibly also using reverse name +resolution depending on the value of the **rdns** variable in +:ref:`libdefaults`. + +If a desired name is specified in the call to gss_acquire_cred_, the +krb5 mechanism will attempt to find existing tickets for that client +principal name in the default credential cache or collection. If the +default cache type does not support a collection, and the default +cache contains credentials for a different principal than the desired +name, a **GSS_S_CRED_UNAVAIL** error will be returned with a minor +code indicating a mismatch. + +If no existing tickets are available for the desired name, but the +name has an entry in the default client :ref:`keytab_definition`, the +krb5 mechanism will acquire initial tickets for the name using the +default client keytab. + +If no desired name is specified, credential acquisition will be +deferred until the credential is used in a call to +gss_init_sec_context_ or gss_inquire_cred_. If the call is to +gss_init_sec_context_, the target name will be used to choose a client +principal name using the credential cache selection facility. (This +facility might, for instance, try to choose existing tickets for a +client principal in the same realm as the target service). If there +are no existing tickets for the chosen principal, but it is present in +the default client keytab, the krb5 mechanism will acquire initial +tickets using the keytab. + +If the target name cannot be used to select a client principal +(because the credentials are used in a call to gss_inquire_cred_), or +if the credential cache selection facility cannot choose a principal +for it, the default credential cache will be selected if it exists and +contains tickets. + +If the default credential cache does not exist, but the default client +keytab does, the krb5 mechanism will try to acquire initial tickets +for the first principal in the default client keytab. + +If the krb5 mechanism acquires initial tickets using the default +client keytab, the resulting tickets will be stored in the default +cache or collection, and will be refreshed by future calls to +gss_acquire_cred_ as they approach their expire time. + + +Acceptor names +-------------- + +A GSSAPI server application uses gss_accept_sec_context_ to establish +a security context based on tokens provided by the client. The +*acceptor_cred_handle* parameter determines what +:ref:`keytab_definition` entries may be authenticated to by the +client, if the krb5 mechanism is used. + +The simplest choice is to pass **GSS_C_NO_CREDENTIAL** as the acceptor +credential. In this case, clients may authenticate to any service +principal in the default keytab (typically |keytab|, or the value of +the **KRB5_KTNAME** environment variable). This is the recommended +approach if the server application has no specific requirements to the +contrary. + +A server may acquire an acceptor credential with gss_acquire_cred_ and +a *cred_usage* of **GSS_C_ACCEPT** or **GSS_C_BOTH**. If the +*desired_name* parameter is **GSS_C_NO_NAME**, then clients will be +allowed to authenticate to any service principal in the default +keytab, just as if no acceptor credential was supplied. + +If a server wishes to specify a *desired_name* to gss_acquire_cred_, +the most common choice is a host-based name. If the host-based +*desired_name* contains just a *service*, then clients will be allowed +to authenticate to any host-based service principal (that is, a +principal of the form ``service/hostname@REALM``) for the named +service, regardless of hostname or realm, as long as it is present in +the default keytab. If the input name contains both a *service* and a +*hostname*, clients will be allowed to authenticate to any host-based +principal for the named service and hostname, regardless of realm. + +.. note:: If a *hostname* is specified, it will be canonicalized + using forward name resolution, and possibly also using + reverse name resolution depending on the value of the + **rdns** variable in :ref:`libdefaults`. + +.. note:: If the **ignore_acceptor_hostname** variable in + :ref:`libdefaults` is enabled, then *hostname* will be + ignored even if one is specified in the input name. + +.. note:: In MIT krb5 versions prior to 1.10, and in Heimdal's + implementation of the krb5 mechanism, an input name with + just a *service* is treated like an input name of + ``service@localhostname``, where *localhostname* is the + string returned by gethostname(). + +If the *desired_name* is a krb5 principal name or a local system name +type which is mapped to a krb5 principal name, clients will only be +allowed to authenticate to that principal in the default keytab. + + +Importing and exporting credentials +----------------------------------- + +The following GSSAPI extensions can be used to import and export +credentials (declared in ````):: + + OM_uint32 gss_export_cred(OM_uint32 *minor_status, + gss_cred_id_t cred_handle, + gss_buffer_t token); + + OM_uint32 gss_import_cred(OM_uint32 *minor_status, + gss_buffer_t token, + gss_cred_id_t *cred_handle); + +The first function serializes a GSSAPI credential handle into a +buffer; the second unseralizes a buffer into a GSSAPI credential +handle. Serializing a credential does not destroy it. If any of the +mechanisms used in *cred_handle* do not support serialization, +gss_export_cred will return **GSS_S_UNAVAILABLE**. As with other +GSSAPI serialization functions, these extensions are only intended to +work with a matching implementation on the other side; they do not +serialize credentials in a standardized format. + +A serialized credential may contain secret information such as ticket +session keys. The serialization format does not protect this +information from eavesdropping or tampering. The calling application +must take care to protect the serialized credential when communicating +it over an insecure channel or to an untrusted party. + +A krb5 GSSAPI credential may contain references to a credential cache, +a client keytab, an acceptor keytab, and a replay cache. These +resources are normally serialized as references to their external +locations (such as the filename of the credential cache). Because of +this, a serialized krb5 credential can only be imported by a process +with similar privileges to the exporter. A serialized credential +should not be trusted if it originates from a source with lower +privileges than the importer, as it may contain references to external +credential cache, keytab, or replay cache resources not accessible to +the originator. + +An exception to the above rule applies when a krb5 GSSAPI credential +refers to a memory credential cache, as is normally the case for +delegated credentials received by gss_accept_sec_context_. In this +case, the contents of the credential cache are serialized, so that the +resulting token may be imported even if the original memory credential +cache no longer exists. + +.. _gss_accept_sec_context: http://tools.ietf.org/html/rfc2744.html#section-5.1 +.. _gss_acquire_cred: http://tools.ietf.org/html/rfc2744.html#section-5.2 +.. _gss_export_name: http://tools.ietf.org/html/rfc2744.html#section-5.13 +.. _gss_import_name: http://tools.ietf.org/html/rfc2744.html#section-5.16 +.. _gss_init_sec_context: http://tools.ietf.org/html/rfc2744.html#section-5.19 +.. _gss_inquire_cred: http://tools.ietf.org/html/rfc2744.html#section-5.21 diff --git a/doc/appldev/h5l_mit_apidiff.rst b/doc/appldev/h5l_mit_apidiff.rst new file mode 100644 index 000000000..33da60211 --- /dev/null +++ b/doc/appldev/h5l_mit_apidiff.rst @@ -0,0 +1,28 @@ +Differences between Heimdal and MIT Kerberos API +================================================ + + + ======================================== ================================================= + :c:func:`krb5_auth_con_getaddrs()` H5l: If either of the pointers to local_addr + and remote_addr is not NULL, it is freed + first and then reallocated before being + populated with the content of corresponding + address from authentication context. + :c:func:`krb5_auth_con_setaddrs()` H5l: If either address is NULL, the previous + address remains in place + :c:func:`krb5_auth_con_setports()` H5l: Not implemented as of version 1.3.3 + :c:func:`krb5_auth_con_setrecvsubkey()` H5l: If either port is NULL, the previous + port remains in place + :c:func:`krb5_auth_con_setsendsubkey()` H5l: Not implemented as of version 1.3.3 + :c:func:`krb5_cc_set_config()` MIT: Before version 1.10 it was assumed that + the last argument *data* is ALWAYS non-zero. + :c:func:`krb5_cccol_last_change_time()` H5l takes 3 arguments: krb5_context context, + const char \*type, krb5_timestamp \*change_time + MIT takes two arguments: krb5_context context, + krb5_timestamp \*change_time + :c:func:`krb5_set_default_realm()` H5l: Caches the computed default realm context + field. If the second argument is NULL, + it tries to retrieve it from libdefaults or DNS. + MIT: Computes the default realm each time + if it wasn't explicitly set in the context + ======================================== ================================================= diff --git a/doc/appldev/index.rst b/doc/appldev/index.rst new file mode 100644 index 000000000..3d62045ca --- /dev/null +++ b/doc/appldev/index.rst @@ -0,0 +1,15 @@ +For application developers +========================== + +.. toctree:: + :maxdepth: 1 + + gssapi.rst + h5l_mit_apidiff.rst + init_creds.rst + princ_handle.rst + +.. toctree:: + :maxdepth: 1 + + refs/index.rst diff --git a/doc/appldev/init_creds.rst b/doc/appldev/init_creds.rst new file mode 100644 index 000000000..b9528e737 --- /dev/null +++ b/doc/appldev/init_creds.rst @@ -0,0 +1,59 @@ +Initial credentials +=================== + +Software that performs tasks such as logging users into a computer +when they type their Kerberos password needs to get initial +credentials (usually ticket granting tickets) from Kerberos. Such +software shares some behavior with the :ref:`kinit(1)` program. + +Whenever a program grants access to a resource (such as a local login +session on a desktop computer) based on a user successfully getting +initial Kerberos credentials, it must verify those credentials against +a secure shared secret (e.g., a host keytab) to ensure that the user +credentials actually originate from a legitimate KDC. Failure to +perform this verification is a critical vulnerability, because a +malicious user can execute the "Zanarotti attack": the user constructs +a fake response that appears to come from the legitimate KDC, but +whose contents come from an attacker-controlled KDC. + +Some applications read a Kerberos password over the network (ideally +over a secure channel), which they then verify against the KDC. While +this technique may be the only practical way to integrate Kerberos +into some existing legacy systems, its use is contrary to the original +design goals of Kerberos. + +The function :c:func:`krb5_get_init_creds_password` will get initial +credentials for a client using a password. An application that needs +to verify the credentials can call :c:func:`krb5_verify_init_creds`. + +Options for get_init_creds +-------------------------- + +The function :c:func:`krb5_get_init_creds_password` takes an options +parameter (which can be a null pointer). Use the function +:c:func:`krb5_get_init_creds_opt_alloc` to allocate an options +structure, and :c:func:`krb5_get_init_creds_opt_free` to free it. + +Verifying initial credentials +----------------------------- + +Use the function :c:func:`krb5_verify_init_creds` to verify initial +credentials. It takes an options structure (which can be a null +pointer). Use :c:func:`krb5_verify_init_creds_opt_init` to initialize +the caller-allocated options structure, and +:c:func:`krb5_verify_init_creds_opt_set_ap_req_nofail` to set the +"nofail" option. + +The confusingly named "nofail" option, when set, means that the +verification must actually succeed in order for +:c:func:`krb5_verify_init_creds` to indicate success. The default +state of this option (cleared) means that if there is no key material +available to verify the user credentials, the verification will +succeed anyway. (The default can be changed by a configuration file +setting.) + +This accommodates a use case where a large number of unkeyed shared +desktop workstations need to allow users to log in using Kerberos. +The security risks from this practice are mitigated by the absence of +valuable state on the shared workstations---any valuable resources +that the users would access reside on networked servers. diff --git a/doc/appldev/princ_handle.rst b/doc/appldev/princ_handle.rst new file mode 100644 index 000000000..455f00a4b --- /dev/null +++ b/doc/appldev/princ_handle.rst @@ -0,0 +1,79 @@ +Principal manipulation and parsing +================================== + +Kerberos principal structure + +.. + +:c:type:`krb5_principal_data` + +:c:type:`krb5_principal` + +.. + +Create and free principal + +.. + +:c:func:`krb5_build_principal()` + +:c:func:`krb5_build_principal_alloc_va()` + +:c:func:`krb5_build_principal_ext()` + +:c:func:`krb5_copy_principal()` + +:c:func:`krb5_free_principal()` + +:c:func:`krb5_cc_get_principal()` + +.. + +Comparing + +.. + +:c:func:`krb5_principal_compare()` + +:c:func:`krb5_principal_compare_flags()` + +:c:func:`krb5_principal_compare_any_realm()` + +:c:func:`krb5_sname_match()` + +:c:func:`krb5_sname_to_principal()` + +.. + + +Parsing: + +.. + +:c:func:`krb5_parse_name()` + +:c:func:`krb5_parse_name_flags()` + +:c:func:`krb5_unparse_name()` + +:c:func:`krb5_unparse_name_flags()` + +.. + +Utilities: + +.. + +:c:func:`krb5_is_config_principal()` + +:c:func:`krb5_kuserok()` + +:c:func:`krb5_set_password()` + +:c:func:`krb5_set_password_using_ccache()` + +:c:func:`krb5_set_principal_realm()` + +:c:func:`krb5_realm_compare()` + +.. diff --git a/doc/appldev/refs/api/index.rst b/doc/appldev/refs/api/index.rst new file mode 100644 index 000000000..26b7f8633 --- /dev/null +++ b/doc/appldev/refs/api/index.rst @@ -0,0 +1,397 @@ +krb5 API +======== + + +Frequently used public interfaces +---------------------------------- + +.. toctree:: + :maxdepth: 1 + + krb5_build_principal.rst + krb5_build_principal_alloc_va.rst + krb5_build_principal_ext.rst + krb5_cc_close.rst + krb5_cc_default.rst + krb5_cc_default_name.rst + krb5_cc_destroy.rst + krb5_cc_dup.rst + krb5_cc_get_name.rst + krb5_cc_get_principal.rst + krb5_cc_get_type.rst + krb5_cc_initialize.rst + krb5_cc_new_unique.rst + krb5_cc_resolve.rst + krb5_change_password.rst + krb5_chpw_message.rst + krb5_free_context.rst + krb5_free_error_message.rst + krb5_free_principal.rst + krb5_fwd_tgt_creds.rst + krb5_get_default_realm.rst + krb5_get_error_message.rst + krb5_get_host_realm.rst + krb5_get_credentials.rst + krb5_get_fallback_host_realm.rst + krb5_get_init_creds_keytab.rst + krb5_get_init_creds_opt_alloc.rst + krb5_get_init_creds_opt_free.rst + krb5_get_init_creds_opt_get_fast_flags.rst + krb5_get_init_creds_opt_set_address_list.rst + krb5_get_init_creds_opt_set_anonymous.rst + krb5_get_init_creds_opt_set_canonicalize.rst + krb5_get_init_creds_opt_set_change_password_prompt.rst + krb5_get_init_creds_opt_set_etype_list.rst + krb5_get_init_creds_opt_set_expire_callback.rst + krb5_get_init_creds_opt_set_fast_ccache.rst + krb5_get_init_creds_opt_set_fast_ccache_name.rst + krb5_get_init_creds_opt_set_fast_flags.rst + krb5_get_init_creds_opt_set_forwardable.rst + krb5_get_init_creds_opt_set_out_ccache.rst + krb5_get_init_creds_opt_set_pa.rst + krb5_get_init_creds_opt_set_preauth_list.rst + krb5_get_init_creds_opt_set_proxiable.rst + krb5_get_init_creds_opt_set_renew_life.rst + krb5_get_init_creds_opt_set_responder.rst + krb5_get_init_creds_opt_set_salt.rst + krb5_get_init_creds_opt_set_tkt_life.rst + krb5_get_init_creds_password.rst + krb5_get_profile.rst + krb5_get_prompt_types.rst + krb5_get_renewed_creds.rst + krb5_get_validated_creds.rst + krb5_init_context.rst + krb5_init_secure_context.rst + krb5_is_config_principal.rst + krb5_is_thread_safe.rst + krb5_kt_close.rst + krb5_kt_client_default.rst + krb5_kt_default.rst + krb5_kt_default_name.rst + krb5_kt_get_name.rst + krb5_kt_get_type.rst + krb5_kt_resolve.rst + krb5_kuserok.rst + krb5_parse_name.rst + krb5_parse_name_flags.rst + krb5_principal_compare.rst + krb5_principal_compare_any_realm.rst + krb5_principal_compare_flags.rst + krb5_prompter_posix.rst + krb5_realm_compare.rst + krb5_responder_get_challenge.rst + krb5_responder_list_questions.rst + krb5_responder_set_answer.rst + krb5_responder_otp_get_challenge.rst + krb5_responder_otp_set_answer.rst + krb5_responder_otp_challenge_free.rst + krb5_set_default_realm.rst + krb5_set_password.rst + krb5_set_password_using_ccache.rst + krb5_set_principal_realm.rst + krb5_set_trace_callback.rst + krb5_set_trace_filename.rst + krb5_sname_match.rst + krb5_sname_to_principal.rst + krb5_unparse_name.rst + krb5_unparse_name_ext.rst + krb5_unparse_name_flags.rst + krb5_unparse_name_flags_ext.rst + krb5_us_timeofday.rst + krb5_verify_authdata_kdc_issued.rst + +Rarely used public interfaces +-------------------------------- + +.. toctree:: + :maxdepth: 1 + + krb5_425_conv_principal.rst + krb5_524_conv_principal.rst + krb5_address_compare.rst + krb5_address_order.rst + krb5_address_search.rst + krb5_allow_weak_crypto.rst + krb5_aname_to_localname.rst + krb5_anonymous_principal.rst + krb5_anonymous_realm.rst + krb5_appdefault_boolean.rst + krb5_appdefault_string.rst + krb5_auth_con_free.rst + krb5_auth_con_genaddrs.rst + krb5_auth_con_get_checksum_func.rst + krb5_auth_con_getaddrs.rst + krb5_auth_con_getauthenticator.rst + krb5_auth_con_getflags.rst + krb5_auth_con_getkey.rst + krb5_auth_con_getkey_k.rst + krb5_auth_con_getlocalseqnumber.rst + krb5_auth_con_getrcache.rst + krb5_auth_con_getrecvsubkey.rst + krb5_auth_con_getrecvsubkey_k.rst + krb5_auth_con_getremoteseqnumber.rst + krb5_auth_con_getsendsubkey.rst + krb5_auth_con_getsendsubkey_k.rst + krb5_auth_con_init.rst + krb5_auth_con_set_checksum_func.rst + krb5_auth_con_set_req_cksumtype.rst + krb5_auth_con_setaddrs.rst + krb5_auth_con_setflags.rst + krb5_auth_con_setports.rst + krb5_auth_con_setrcache.rst + krb5_auth_con_setrecvsubkey.rst + krb5_auth_con_setrecvsubkey_k.rst + krb5_auth_con_setsendsubkey.rst + krb5_auth_con_setsendsubkey_k.rst + krb5_auth_con_setuseruserkey.rst + krb5_cc_cache_match.rst + krb5_cc_copy_creds.rst + krb5_cc_end_seq_get.rst + krb5_cc_get_config.rst + krb5_cc_get_flags.rst + krb5_cc_get_full_name.rst + krb5_cc_last_change_time.rst + krb5_cc_lock.rst + krb5_cc_move.rst + krb5_cc_next_cred.rst + krb5_cc_remove_cred.rst + krb5_cc_retrieve_cred.rst + krb5_cc_select.rst + krb5_cc_set_config.rst + krb5_cc_set_default_name.rst + krb5_cc_set_flags.rst + krb5_cc_start_seq_get.rst + krb5_cc_store_cred.rst + krb5_cc_support_switch.rst + krb5_cc_switch.rst + krb5_cc_unlock.rst + krb5_cccol_cursor_free.rst + krb5_cccol_cursor_new.rst + krb5_cccol_cursor_next.rst + krb5_cccol_have_content.rst + krb5_cccol_last_change_time.rst + krb5_cccol_lock.rst + krb5_cccol_unlock.rst + krb5_clear_error_message.rst + krb5_check_clockskew.rst + krb5_copy_addresses.rst + krb5_copy_authdata.rst + krb5_copy_authenticator.rst + krb5_copy_checksum.rst + krb5_copy_context.rst + krb5_copy_creds.rst + krb5_copy_data.rst + krb5_copy_error_message.rst + krb5_copy_keyblock.rst + krb5_copy_keyblock_contents.rst + krb5_copy_principal.rst + krb5_copy_ticket.rst + krb5_find_authdata.rst + krb5_free_addresses.rst + krb5_free_ap_rep_enc_part.rst + krb5_free_authdata.rst + krb5_free_authenticator.rst + krb5_free_cred_contents.rst + krb5_free_creds.rst + krb5_free_data.rst + krb5_free_data_contents.rst + krb5_free_default_realm.rst + krb5_free_error.rst + krb5_free_host_realm.rst + krb5_free_keyblock.rst + krb5_free_keyblock_contents.rst + krb5_free_keytab_entry_contents.rst + krb5_free_octet_data.rst + krb5_free_string.rst + krb5_free_ticket.rst + krb5_free_unparsed_name.rst + krb5_get_permitted_enctypes.rst + krb5_get_server_rcache.rst + krb5_get_time_offsets.rst + krb5_init_context_profile.rst + krb5_init_creds_free.rst + krb5_init_creds_get.rst + krb5_init_creds_get_creds.rst + krb5_init_creds_get_error.rst + krb5_init_creds_get_times.rst + krb5_init_creds_init.rst + krb5_init_creds_set_keytab.rst + krb5_init_creds_set_password.rst + krb5_init_creds_set_service.rst + krb5_init_creds_step.rst + krb5_init_keyblock.rst + krb5_is_referral_realm.rst + krb5_kt_add_entry.rst + krb5_kt_end_seq_get.rst + krb5_kt_get_entry.rst + krb5_kt_have_content.rst + krb5_kt_next_entry.rst + krb5_kt_read_service_key.rst + krb5_kt_remove_entry.rst + krb5_kt_start_seq_get.rst + krb5_make_authdata_kdc_issued.rst + krb5_merge_authdata.rst + krb5_mk_1cred.rst + krb5_mk_error.rst + krb5_mk_ncred.rst + krb5_mk_priv.rst + krb5_mk_rep.rst + krb5_mk_rep_dce.rst + krb5_mk_req.rst + krb5_mk_req_extended.rst + krb5_mk_safe.rst + krb5_os_localaddr.rst + krb5_pac_add_buffer.rst + krb5_pac_free.rst + krb5_pac_get_buffer.rst + krb5_pac_get_types.rst + krb5_pac_init.rst + krb5_pac_parse.rst + krb5_pac_sign.rst + krb5_pac_verify.rst + krb5_principal2salt.rst + krb5_rd_cred.rst + krb5_rd_error.rst + krb5_rd_priv.rst + krb5_rd_rep.rst + krb5_rd_rep_dce.rst + krb5_rd_req.rst + krb5_rd_safe.rst + krb5_read_password.rst + krb5_salttype_to_string.rst + krb5_server_decrypt_ticket_keytab.rst + krb5_set_default_tgs_enctypes.rst + krb5_set_error_message.rst + krb5_set_real_time.rst + krb5_string_to_cksumtype.rst + krb5_string_to_deltat.rst + krb5_string_to_enctype.rst + krb5_string_to_salttype.rst + krb5_string_to_timestamp.rst + krb5_timeofday.rst + krb5_timestamp_to_sfstring.rst + krb5_timestamp_to_string.rst + krb5_tkt_creds_free.rst + krb5_tkt_creds_get.rst + krb5_tkt_creds_get_creds.rst + krb5_tkt_creds_get_times.rst + krb5_tkt_creds_init.rst + krb5_tkt_creds_step.rst + krb5_verify_init_creds.rst + krb5_verify_init_creds_opt_init.rst + krb5_verify_init_creds_opt_set_ap_req_nofail.rst + krb5_vset_error_message.rst + + +Public interfaces that should not be called directly +------------------------------------------------------- + +.. toctree:: + :maxdepth: 1 + + krb5_c_block_size.rst + krb5_c_checksum_length.rst + krb5_c_crypto_length.rst + krb5_c_crypto_length_iov.rst + krb5_c_decrypt.rst + krb5_c_decrypt_iov.rst + krb5_c_encrypt.rst + krb5_c_encrypt_iov.rst + krb5_c_encrypt_length.rst + krb5_c_enctype_compare.rst + krb5_c_free_state.rst + krb5_c_fx_cf2_simple.rst + krb5_c_init_state.rst + krb5_c_is_coll_proof_cksum.rst + krb5_c_is_keyed_cksum.rst + krb5_c_keyed_checksum_types.rst + krb5_c_keylengths.rst + krb5_c_make_checksum.rst + krb5_c_make_checksum_iov.rst + krb5_c_make_random_key.rst + krb5_c_padding_length.rst + krb5_c_prf.rst + krb5_c_prf_length.rst + krb5_c_random_add_entropy.rst + krb5_c_random_make_octets.rst + krb5_c_random_os_entropy.rst + krb5_c_random_to_key.rst + krb5_c_string_to_key.rst + krb5_c_string_to_key_with_params.rst + krb5_c_valid_cksumtype.rst + krb5_c_valid_enctype.rst + krb5_c_verify_checksum.rst + krb5_c_verify_checksum_iov.rst + krb5_cksumtype_to_string.rst + krb5_decode_authdata_container.rst + krb5_decode_ticket.rst + krb5_deltat_to_string.rst + krb5_encode_authdata_container.rst + krb5_enctype_to_name.rst + krb5_enctype_to_string.rst + krb5_free_checksum.rst + krb5_free_checksum_contents.rst + krb5_free_cksumtypes.rst + krb5_free_tgt_creds.rst + krb5_k_create_key.rst + krb5_k_decrypt.rst + krb5_k_decrypt_iov.rst + krb5_k_encrypt.rst + krb5_k_encrypt_iov.rst + krb5_k_free_key.rst + krb5_k_key_enctype.rst + krb5_k_key_keyblock.rst + krb5_k_make_checksum.rst + krb5_k_make_checksum_iov.rst + krb5_k_prf.rst + krb5_k_reference_key.rst + krb5_k_verify_checksum.rst + krb5_k_verify_checksum_iov.rst + + +Legacy convenience interfaces +------------------------------ + +.. toctree:: + :maxdepth: 1 + + krb5_recvauth.rst + krb5_recvauth_version.rst + krb5_sendauth.rst + + +Deprecated public interfaces +------------------------------ + +.. toctree:: + :maxdepth: 1 + + krb5_524_convert_creds.rst + krb5_auth_con_getlocalsubkey.rst + krb5_auth_con_getremotesubkey.rst + krb5_auth_con_initivector.rst + krb5_build_principal_va.rst + krb5_c_random_seed.rst + krb5_calculate_checksum.rst + krb5_checksum_size.rst + krb5_encrypt.rst + krb5_decrypt.rst + krb5_eblock_enctype.rst + krb5_encrypt_size.rst + krb5_finish_key.rst + krb5_finish_random_key.rst + krb5_cc_gen_new.rst + krb5_get_credentials_renew.rst + krb5_get_credentials_validate.rst + krb5_get_in_tkt_with_password.rst + krb5_get_in_tkt_with_skey.rst + krb5_get_in_tkt_with_keytab.rst + krb5_get_init_creds_opt_init.rst + krb5_init_random_key.rst + krb5_kt_free_entry.rst + krb5_random_key.rst + krb5_process_key.rst + krb5_string_to_key.rst + krb5_use_enctype.rst + krb5_verify_checksum.rst + diff --git a/doc/appldev/refs/index.rst b/doc/appldev/refs/index.rst new file mode 100644 index 000000000..e0f6d57f3 --- /dev/null +++ b/doc/appldev/refs/index.rst @@ -0,0 +1,10 @@ +Complete reference - API and datatypes +========================================================== + +.. toctree:: + :maxdepth: 1 + + api/index.rst + types/index.rst + macros/index.rst + diff --git a/doc/appldev/refs/macros/index.rst b/doc/appldev/refs/macros/index.rst new file mode 100644 index 000000000..b26581059 --- /dev/null +++ b/doc/appldev/refs/macros/index.rst @@ -0,0 +1,355 @@ +krb5 simple macros +========================= + +Public +------- + +.. toctree:: + :maxdepth: 1 + + ADDRTYPE_ADDRPORT.rst + ADDRTYPE_CHAOS.rst + ADDRTYPE_DDP.rst + ADDRTYPE_INET.rst + ADDRTYPE_INET6.rst + ADDRTYPE_IPPORT.rst + ADDRTYPE_ISO.rst + ADDRTYPE_IS_LOCAL.rst + ADDRTYPE_NETBIOS.rst + ADDRTYPE_XNS.rst + AD_TYPE_EXTERNAL.rst + AD_TYPE_FIELD_TYPE_MASK.rst + AD_TYPE_REGISTERED.rst + AD_TYPE_RESERVED.rst + AP_OPTS_ETYPE_NEGOTIATION.rst + AP_OPTS_MUTUAL_REQUIRED.rst + AP_OPTS_RESERVED.rst + AP_OPTS_USE_SESSION_KEY.rst + AP_OPTS_USE_SUBKEY.rst + AP_OPTS_WIRE_MASK.rst + CKSUMTYPE_CRC32.rst + CKSUMTYPE_DESCBC.rst + CKSUMTYPE_HMAC_MD5_ARCFOUR.rst + CKSUMTYPE_HMAC_SHA1_96_AES128.rst + CKSUMTYPE_HMAC_SHA1_96_AES256.rst + CKSUMTYPE_HMAC_SHA1_DES3.rst + CKSUMTYPE_MD5_HMAC_ARCFOUR.rst + CKSUMTYPE_NIST_SHA.rst + CKSUMTYPE_RSA_MD4.rst + CKSUMTYPE_RSA_MD4_DES.rst + CKSUMTYPE_RSA_MD5.rst + CKSUMTYPE_RSA_MD5_DES.rst + ENCTYPE_AES128_CTS_HMAC_SHA1_96.rst + ENCTYPE_AES256_CTS_HMAC_SHA1_96.rst + ENCTYPE_ARCFOUR_HMAC.rst + ENCTYPE_ARCFOUR_HMAC_EXP.rst + ENCTYPE_DES3_CBC_ENV.rst + ENCTYPE_DES3_CBC_RAW.rst + ENCTYPE_DES3_CBC_SHA.rst + ENCTYPE_DES3_CBC_SHA1.rst + ENCTYPE_DES_CBC_CRC.rst + ENCTYPE_DES_CBC_MD4.rst + ENCTYPE_DES_CBC_MD5.rst + ENCTYPE_DES_CBC_RAW.rst + ENCTYPE_DES_HMAC_SHA1.rst + ENCTYPE_DSA_SHA1_CMS.rst + ENCTYPE_MD5_RSA_CMS.rst + ENCTYPE_NULL.rst + ENCTYPE_RC2_CBC_ENV.rst + ENCTYPE_RSA_ENV.rst + ENCTYPE_RSA_ES_OAEP_ENV.rst + ENCTYPE_SHA1_RSA_CMS.rst + ENCTYPE_UNKNOWN.rst + KDC_OPT_ALLOW_POSTDATE.rst + KDC_OPT_CANONICALIZE.rst + KDC_OPT_CNAME_IN_ADDL_TKT.rst + KDC_OPT_DISABLE_TRANSITED_CHECK.rst + KDC_OPT_ENC_TKT_IN_SKEY.rst + KDC_OPT_FORWARDABLE.rst + KDC_OPT_FORWARDED.rst + KDC_OPT_POSTDATED.rst + KDC_OPT_PROXIABLE.rst + KDC_OPT_PROXY.rst + KDC_OPT_RENEW.rst + KDC_OPT_RENEWABLE.rst + KDC_OPT_RENEWABLE_OK.rst + KDC_OPT_REQUEST_ANONYMOUS.rst + KDC_OPT_VALIDATE.rst + KDC_TKT_COMMON_MASK.rst + KRB5_ALTAUTH_ATT_CHALLENGE_RESPONSE.rst + KRB5_ANONYMOUS_PRINCSTR.rst + KRB5_ANONYMOUS_REALMSTR.rst + KRB5_AP_REP.rst + KRB5_AP_REQ.rst + KRB5_AS_REP.rst + KRB5_AS_REQ.rst + KRB5_AUTHDATA_AND_OR.rst + KRB5_AUTHDATA_ETYPE_NEGOTIATION.rst + KRB5_AUTHDATA_FX_ARMOR.rst + KRB5_AUTHDATA_IF_RELEVANT.rst + KRB5_AUTHDATA_INITIAL_VERIFIED_CAS.rst + KRB5_AUTHDATA_KDC_ISSUED.rst + KRB5_AUTHDATA_MANDATORY_FOR_KDC.rst + KRB5_AUTHDATA_OSF_DCE.rst + KRB5_AUTHDATA_SESAME.rst + KRB5_AUTHDATA_SIGNTICKET.rst + KRB5_AUTHDATA_WIN2K_PAC.rst + KRB5_AUTH_CONTEXT_DO_SEQUENCE.rst + KRB5_AUTH_CONTEXT_DO_TIME.rst + KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR.rst + KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR.rst + KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR.rst + KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR.rst + KRB5_AUTH_CONTEXT_PERMIT_ALL.rst + KRB5_AUTH_CONTEXT_RET_SEQUENCE.rst + KRB5_AUTH_CONTEXT_RET_TIME.rst + KRB5_AUTH_CONTEXT_USE_SUBKEY.rst + KRB5_CRED.rst + KRB5_CRYPTO_TYPE_CHECKSUM.rst + KRB5_CRYPTO_TYPE_DATA.rst + KRB5_CRYPTO_TYPE_EMPTY.rst + KRB5_CRYPTO_TYPE_HEADER.rst + KRB5_CRYPTO_TYPE_PADDING.rst + KRB5_CRYPTO_TYPE_SIGN_ONLY.rst + KRB5_CRYPTO_TYPE_STREAM.rst + KRB5_CRYPTO_TYPE_TRAILER.rst + KRB5_CYBERSAFE_SECUREID.rst + KRB5_DOMAIN_X500_COMPRESS.rst + KRB5_ENCPADATA_REQ_ENC_PA_REP.rst + KRB5_ERROR.rst + KRB5_FAST_REQUIRED.rst + KRB5_GC_CACHED.rst + KRB5_GC_CANONICALIZE.rst + KRB5_GC_CONSTRAINED_DELEGATION.rst + KRB5_GC_FORWARDABLE.rst + KRB5_GC_NO_STORE.rst + KRB5_GC_NO_TRANSIT_CHECK.rst + KRB5_GC_USER_USER.rst + KRB5_GET_INIT_CREDS_OPT_ADDRESS_LIST.rst + KRB5_GET_INIT_CREDS_OPT_ANONYMOUS.rst + KRB5_GET_INIT_CREDS_OPT_CANONICALIZE.rst + KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT.rst + KRB5_GET_INIT_CREDS_OPT_ETYPE_LIST.rst + KRB5_GET_INIT_CREDS_OPT_FORWARDABLE.rst + KRB5_GET_INIT_CREDS_OPT_PREAUTH_LIST.rst + KRB5_GET_INIT_CREDS_OPT_PROXIABLE.rst + KRB5_GET_INIT_CREDS_OPT_RENEW_LIFE.rst + KRB5_GET_INIT_CREDS_OPT_SALT.rst + KRB5_GET_INIT_CREDS_OPT_TKT_LIFE.rst + KRB5_INIT_CONTEXT_SECURE.rst + KRB5_INIT_CONTEXT_KDC.rst + KRB5_INIT_CREDS_STEP_FLAG_CONTINUE.rst + KRB5_INT16_MAX.rst + KRB5_INT16_MIN.rst + KRB5_INT32_MAX.rst + KRB5_INT32_MIN.rst + KRB5_KEYUSAGE_AD_ITE.rst + KRB5_KEYUSAGE_AD_KDCISSUED_CKSUM.rst + KRB5_KEYUSAGE_AD_MTE.rst + KRB5_KEYUSAGE_AD_SIGNEDPATH.rst + KRB5_KEYUSAGE_APP_DATA_CKSUM.rst + KRB5_KEYUSAGE_APP_DATA_ENCRYPT.rst + KRB5_KEYUSAGE_AP_REP_ENCPART.rst + KRB5_KEYUSAGE_AP_REQ_AUTH.rst + KRB5_KEYUSAGE_AP_REQ_AUTH_CKSUM.rst + KRB5_KEYUSAGE_AS_REP_ENCPART.rst + KRB5_KEYUSAGE_AS_REQ.rst + KRB5_KEYUSAGE_AS_REQ_PA_ENC_TS.rst + KRB5_KEYUSAGE_ENC_CHALLENGE_CLIENT.rst + KRB5_KEYUSAGE_ENC_CHALLENGE_KDC.rst + KRB5_KEYUSAGE_FAST_ENC.rst + KRB5_KEYUSAGE_FAST_FINISHED.rst + KRB5_KEYUSAGE_FAST_REP.rst + KRB5_KEYUSAGE_FAST_REQ_CHKSUM.rst + KRB5_KEYUSAGE_GSS_TOK_MIC.rst + KRB5_KEYUSAGE_GSS_TOK_WRAP_INTEG.rst + KRB5_KEYUSAGE_GSS_TOK_WRAP_PRIV.rst + KRB5_KEYUSAGE_IAKERB_FINISHED.rst + KRB5_KEYUSAGE_KDC_REP_TICKET.rst + KRB5_KEYUSAGE_KRB_CRED_ENCPART.rst + KRB5_KEYUSAGE_KRB_ERROR_CKSUM.rst + KRB5_KEYUSAGE_KRB_PRIV_ENCPART.rst + KRB5_KEYUSAGE_KRB_SAFE_CKSUM.rst + KRB5_KEYUSAGE_PA_OTP_REQUEST.rst + KRB5_KEYUSAGE_PA_PKINIT_KX.rst + KRB5_KEYUSAGE_PA_REFERRAL.rst + KRB5_KEYUSAGE_PA_S4U_X509_USER_REPLY.rst + KRB5_KEYUSAGE_PA_S4U_X509_USER_REQUEST.rst + KRB5_KEYUSAGE_PA_SAM_CHALLENGE_CKSUM.rst + KRB5_KEYUSAGE_PA_SAM_CHALLENGE_TRACKID.rst + KRB5_KEYUSAGE_PA_SAM_RESPONSE.rst + KRB5_KEYUSAGE_TGS_REP_ENCPART_SESSKEY.rst + KRB5_KEYUSAGE_TGS_REP_ENCPART_SUBKEY.rst + KRB5_KEYUSAGE_TGS_REQ_AD_SESSKEY.rst + KRB5_KEYUSAGE_TGS_REQ_AD_SUBKEY.rst + KRB5_KEYUSAGE_TGS_REQ_AUTH.rst + KRB5_KEYUSAGE_TGS_REQ_AUTH_CKSUM.rst + KRB5_KPASSWD_ACCESSDENIED.rst + KRB5_KPASSWD_AUTHERROR.rst + KRB5_KPASSWD_BAD_VERSION.rst + KRB5_KPASSWD_HARDERROR.rst + KRB5_KPASSWD_INITIAL_FLAG_NEEDED.rst + KRB5_KPASSWD_MALFORMED.rst + KRB5_KPASSWD_SOFTERROR.rst + KRB5_KPASSWD_SUCCESS.rst + KRB5_LRQ_ALL_ACCT_EXPTIME.rst + KRB5_LRQ_ALL_LAST_INITIAL.rst + KRB5_LRQ_ALL_LAST_RENEWAL.rst + KRB5_LRQ_ALL_LAST_REQ.rst + KRB5_LRQ_ALL_LAST_TGT.rst + KRB5_LRQ_ALL_LAST_TGT_ISSUED.rst + KRB5_LRQ_ALL_PW_EXPTIME.rst + KRB5_LRQ_NONE.rst + KRB5_LRQ_ONE_ACCT_EXPTIME.rst + KRB5_LRQ_ONE_LAST_INITIAL.rst + KRB5_LRQ_ONE_LAST_RENEWAL.rst + KRB5_LRQ_ONE_LAST_REQ.rst + KRB5_LRQ_ONE_LAST_TGT.rst + KRB5_LRQ_ONE_LAST_TGT_ISSUED.rst + KRB5_LRQ_ONE_PW_EXPTIME.rst + KRB5_NT_ENTERPRISE_PRINCIPAL.rst + KRB5_NT_ENT_PRINCIPAL_AND_ID.rst + KRB5_NT_MS_PRINCIPAL.rst + KRB5_NT_MS_PRINCIPAL_AND_ID.rst + KRB5_NT_PRINCIPAL.rst + KRB5_NT_SMTP_NAME.rst + KRB5_NT_SRV_HST.rst + KRB5_NT_SRV_INST.rst + KRB5_NT_SRV_XHST.rst + KRB5_NT_UID.rst + KRB5_NT_UNKNOWN.rst + KRB5_NT_WELLKNOWN.rst + KRB5_NT_X500_PRINCIPAL.rst + KRB5_OLD_CRYPTO.rst + KRB5_PAC_CLIENT_INFO.rst + KRB5_PAC_CREDENTIALS_INFO.rst + KRB5_PAC_DELEGATION_INFO.rst + KRB5_PAC_LOGON_INFO.rst + KRB5_PAC_PRIVSVR_CHECKSUM.rst + KRB5_PAC_SERVER_CHECKSUM.rst + KRB5_PAC_UPN_DNS_INFO.rst + KRB5_PADATA_AFS3_SALT.rst + KRB5_PADATA_AP_REQ.rst + KRB5_PADATA_ENCRYPTED_CHALLENGE.rst + KRB5_PADATA_ENC_SANDIA_SECURID.rst + KRB5_PADATA_ENC_TIMESTAMP.rst + KRB5_PADATA_ENC_UNIX_TIME.rst + KRB5_PADATA_ETYPE_INFO.rst + KRB5_PADATA_ETYPE_INFO2.rst + KRB5_PADATA_FOR_USER.rst + KRB5_PADATA_FX_COOKIE.rst + KRB5_PADATA_FX_ERROR.rst + KRB5_PADATA_FX_FAST.rst + KRB5_PADATA_GET_FROM_TYPED_DATA.rst + KRB5_PADATA_NONE.rst + KRB5_PADATA_OSF_DCE.rst + KRB5_PADATA_OTP_CHALLENGE.rst + KRB5_PADATA_OTP_PIN_CHANGE.rst + KRB5_PADATA_OTP_REQUEST.rst + KRB5_PADATA_PAC_REQUEST.rst + KRB5_PADATA_PKINIT_KX.rst + KRB5_PADATA_PK_AS_REP.rst + KRB5_PADATA_PK_AS_REP_OLD.rst + KRB5_PADATA_PK_AS_REQ.rst + KRB5_PADATA_PK_AS_REQ_OLD.rst + KRB5_PADATA_PW_SALT.rst + KRB5_PADATA_REFERRAL.rst + KRB5_PADATA_S4U_X509_USER.rst + KRB5_PADATA_SAM_CHALLENGE.rst + KRB5_PADATA_SAM_CHALLENGE_2.rst + KRB5_PADATA_SAM_REDIRECT.rst + KRB5_PADATA_SAM_RESPONSE.rst + KRB5_PADATA_SAM_RESPONSE_2.rst + KRB5_PADATA_SESAME.rst + KRB5_PADATA_SVR_REFERRAL_INFO.rst + KRB5_PADATA_TGS_REQ.rst + KRB5_PADATA_USE_SPECIFIED_KVNO.rst + KRB5_PRINCIPAL_COMPARE_CASEFOLD.rst + KRB5_PRINCIPAL_COMPARE_ENTERPRISE.rst + KRB5_PRINCIPAL_COMPARE_IGNORE_REALM.rst + KRB5_PRINCIPAL_COMPARE_UTF8.rst + KRB5_PRINCIPAL_PARSE_ENTERPRISE.rst + KRB5_PRINCIPAL_PARSE_NO_REALM.rst + KRB5_PRINCIPAL_PARSE_REQUIRE_REALM.rst + KRB5_PRINCIPAL_UNPARSE_DISPLAY.rst + KRB5_PRINCIPAL_UNPARSE_NO_REALM.rst + KRB5_PRINCIPAL_UNPARSE_SHORT.rst + KRB5_PRIV.rst + KRB5_PROMPT_TYPE_NEW_PASSWORD.rst + KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN.rst + KRB5_PROMPT_TYPE_PASSWORD.rst + KRB5_PROMPT_TYPE_PREAUTH.rst + KRB5_PVNO.rst + KRB5_REALM_BRANCH_CHAR.rst + KRB5_RECVAUTH_BADAUTHVERS.rst + KRB5_RECVAUTH_SKIP_VERSION.rst + KRB5_REFERRAL_REALM.rst + KRB5_SAFE.rst + KRB5_SAM_MUST_PK_ENCRYPT_SAD.rst + KRB5_SAM_SEND_ENCRYPTED_SAD.rst + KRB5_SAM_USE_SAD_AS_KEY.rst + KRB5_TC_MATCH_2ND_TKT.rst + KRB5_TC_MATCH_AUTHDATA.rst + KRB5_TC_MATCH_FLAGS.rst + KRB5_TC_MATCH_FLAGS_EXACT.rst + KRB5_TC_MATCH_IS_SKEY.rst + KRB5_TC_MATCH_KTYPE.rst + KRB5_TC_MATCH_SRV_NAMEONLY.rst + KRB5_TC_MATCH_TIMES.rst + KRB5_TC_MATCH_TIMES_EXACT.rst + KRB5_TC_NOTICKET.rst + KRB5_TC_OPENCLOSE.rst + KRB5_TC_SUPPORTED_KTYPES.rst + KRB5_TGS_NAME.rst + KRB5_TGS_NAME_SIZE.rst + KRB5_TGS_REP.rst + KRB5_TGS_REQ.rst + KRB5_TKT_CREDS_STEP_FLAG_CONTINUE.rst + KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL.rst + KRB5_WELLKNOWN_NAMESTR.rst + LR_TYPE_INTERPRETATION_MASK.rst + LR_TYPE_THIS_SERVER_ONLY.rst + MAX_KEYTAB_NAME_LEN.rst + MSEC_DIRBIT.rst + MSEC_VAL_MASK.rst + SALT_TYPE_AFS_LENGTH.rst + SALT_TYPE_NO_LENGTH.rst + THREEPARAMOPEN.rst + TKT_FLG_ANONYMOUS.rst + TKT_FLG_ENC_PA_REP.rst + TKT_FLG_FORWARDABLE.rst + TKT_FLG_FORWARDED.rst + TKT_FLG_HW_AUTH.rst + TKT_FLG_INITIAL.rst + TKT_FLG_INVALID.rst + TKT_FLG_MAY_POSTDATE.rst + TKT_FLG_OK_AS_DELEGATE.rst + TKT_FLG_POSTDATED.rst + TKT_FLG_PRE_AUTH.rst + TKT_FLG_PROXIABLE.rst + TKT_FLG_PROXY.rst + TKT_FLG_RENEWABLE.rst + TKT_FLG_TRANSIT_POLICY_CHECKED.rst + VALID_INT_BITS.rst + VALID_UINT_BITS.rst + krb5_const.rst + krb5_princ_component.rst + krb5_princ_name.rst + krb5_princ_realm.rst + krb5_princ_set_realm.rst + krb5_princ_set_realm_data.rst + krb5_princ_set_realm_length.rst + krb5_princ_size.rst + krb5_princ_type.rst + krb5_roundup.rst + krb5_x.rst + krb5_xc.rst + +Deprecated macros +------------------------------ + +.. toctree:: + :maxdepth: 1 + + krb524_convert_creds_kdc.rst + krb524_init_ets.rst diff --git a/doc/appldev/refs/types/index.rst b/doc/appldev/refs/types/index.rst new file mode 100644 index 000000000..9e9190d3d --- /dev/null +++ b/doc/appldev/refs/types/index.rst @@ -0,0 +1,102 @@ +krb5 types and structures +========================= + +Public +------- + +.. toctree:: + :maxdepth: 1 + + krb5_address.rst + krb5_addrtype.rst + krb5_ap_req.rst + krb5_ap_rep.rst + krb5_ap_rep_enc_part.rst + krb5_authdata.rst + krb5_authdatatype.rst + krb5_authenticator.rst + krb5_boolean.rst + krb5_checksum.rst + krb5_const_pointer.rst + krb5_const_principal.rst + krb5_cred.rst + krb5_cred_enc_part.rst + krb5_cred_info.rst + krb5_creds.rst + krb5_crypto_iov.rst + krb5_cryptotype.rst + krb5_data.rst + krb5_deltat.rst + krb5_enc_data.rst + krb5_enc_kdc_rep_part.rst + krb5_enc_tkt_part.rst + krb5_encrypt_block.rst + krb5_enctype.rst + krb5_error.rst + krb5_error_code.rst + krb5_expire_callback_func.rst + krb5_flags.rst + krb5_get_init_creds_opt.rst + krb5_gic_opt_pa_data.rst + krb5_int32.rst + krb5_kdc_rep.rst + krb5_kdc_req.rst + krb5_keyblock.rst + krb5_keytab_entry.rst + krb5_keyusage.rst + krb5_kt_cursor.rst + krb5_kvno.rst + krb5_last_req_entry.rst + krb5_magic.rst + krb5_mk_req_checksum_func.rst + krb5_msgtype.rst + krb5_octet.rst + krb5_octet_data.rst + krb5_pa_pac_req.rst + krb5_pa_server_referral_data.rst + krb5_pa_svr_referral_data.rst + krb5_pa_data.rst + krb5_pointer.rst + krb5_preauthtype.rst + krb5_principal.rst + krb5_principal_data.rst + krb5_const_principal.rst + krb5_prompt.rst + krb5_prompt_type.rst + krb5_prompter_fct.rst + krb5_pwd_data.rst + krb5_response.rst + krb5_replay_data.rst + krb5_ticket.rst + krb5_ticket_times.rst + krb5_timestamp.rst + krb5_tkt_authent.rst + krb5_trace_callback.rst + krb5_trace_info.rst + krb5_transited.rst + krb5_typed_data.rst + krb5_ui_4.rst + krb5_verify_init_creds_opt.rst + passwd_phrase_element.rst + + +Internal +--------- + +.. toctree:: + :maxdepth: 1 + + krb5_auth_context.rst + krb5_cksumtype + krb5_context.rst + krb5_cc_cursor.rst + krb5_ccache.rst + krb5_cccol_cursor.rst + krb5_init_creds_context.rst + krb5_key.rst + krb5_keytab.rst + krb5_pac.rst + krb5_rcache.rst + krb5_tkt_creds_context.rst + + diff --git a/doc/appldev/refs/types/krb5_int32.rst b/doc/appldev/refs/types/krb5_int32.rst new file mode 100644 index 000000000..2bc914b3c --- /dev/null +++ b/doc/appldev/refs/types/krb5_int32.rst @@ -0,0 +1,12 @@ +.. highlightlang:: c + +.. _krb5-int32-struct: + +krb5_int32 +========== + +.. +.. c:type:: krb5_int32 +.. + +krb5_int32 is a signed 32-bit integer type diff --git a/doc/appldev/refs/types/krb5_ui_4.rst b/doc/appldev/refs/types/krb5_ui_4.rst new file mode 100644 index 000000000..de79bafe1 --- /dev/null +++ b/doc/appldev/refs/types/krb5_ui_4.rst @@ -0,0 +1,12 @@ +.. highlightlang:: c + +.. _krb5-ui4-struct: + +krb5_ui_4 +========== + +.. +.. c:type:: krb5_ui_4 +.. + +krb5_ui_4 is an unsigned 32-bit integer type. diff --git a/doc/basic/date_format.rst b/doc/basic/date_format.rst new file mode 100644 index 000000000..bb8925144 --- /dev/null +++ b/doc/basic/date_format.rst @@ -0,0 +1,138 @@ +.. _datetime: + +Supported date and time formats +=============================== + +.. _duration: + +Time duration +------------- + +This format is used to express a time duration in the Kerberos +configuration files and user commands. The allowed formats are: + + ====================== ============== ============ + Format Example Value + ---------------------- -------------- ------------ + h:m[:s] 36:00 36 hours + NdNhNmNs 8h30s 8 hours 30 seconds + N (number of seconds) 3600 1 hour + ====================== ============== ============ + +Here *N* denotes a number, *d* - days, *h* - hours, *m* - minutes, +*s* - seconds. + +.. note:: + The time interval should not exceed 2147483647 seconds. + +Examples:: + + Request a ticket valid for one hour, five hours, 30 minutes + and 10 days respectively: + + kinit -l 3600 + kinit -l 5:00 + kinit -l 30m + kinit -l "10d 0h 0m 0s" + + +.. _getdate: + +getdate time +------------ + +Some of the kadmin and kdb5_util commands take a date-time in a +human-readable format. Some of the acceptable date-time +strings are: + + +-----------+------------------+-----------------+ + | | Format | Example | + +===========+==================+=================+ + | Date | mm/dd/yy | 07/27/12 | + | +------------------+-----------------+ + | | month dd, yyyy | Jul 27, 2012 | + | +------------------+-----------------+ + | | yyyy-mm-dd | 2012-07-27 | + +-----------+------------------+-----------------+ + | Absolute | HH:mm[:ss]pp | 08:30 PM | + | time +------------------+-----------------+ + | | hh:mm[:ss] | 20:30 | + +-----------+------------------+-----------------+ + | Relative | N tt | 30 sec | + | time | | | + +-----------+------------------+-----------------+ + | Time zone | Z | EST | + | +------------------+-----------------+ + | | z | -0400 | + +-----------+------------------+-----------------+ + +(See :ref:`abbreviation`.) + +Examples:: + + Create a principal that expires on the date indicated: + addprinc test1 -expire "3/27/12 10:00:07 EST" + addprinc test2 -expire "January 23, 2015 10:05pm" + addprinc test3 -expire "22:00 GMT" + Add a principal that will expire in 30 minutes: + addprinc test4 -expire "30 minutes" + + +.. _abstime: + +Absolute time +------------- + +This rarely used date-time format can be noted in one of the +following ways: + + + +------------------------+----------------------+--------------+ + | Format | Example | Value | + +========================+======================+==============+ + | yyyymmddhhmmss | 20141231235900 | One minute | + +------------------------+----------------------+ before 2015 | + | yyyy.mm.dd.hh.mm.ss | 2014.12.31.23.59.00 | | + +------------------------+----------------------+ | + | yymmddhhmmss | 141231235900 | | + +------------------------+----------------------+ | + | yy.mm.dd.hh.mm.ss | 14.12.31.23.59.00 | | + +------------------------+----------------------+ | + | dd-month-yyyy:hh:mm:ss | 31-Dec-2014:23:59:00 | | + +------------------------+----------------------+--------------+ + | hh:mm:ss | 20:00:00 | 8 o'clock in | + +------------------------+----------------------+ the evening | + | hhmmss | 200000 | | + +------------------------+----------------------+--------------+ + +(See :ref:`abbreviation`.) + +Example :: + + Set the default expiration date to July 27, 2012 at 20:30 + default_principal_expiration = 20120727203000 + + +.. _abbreviation: + +Abbreviations used in this document +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +| *month* : locale’s month name or its abbreviation; +| *dd* : day of month (01-31); +| *HH* : hours (00-12); +| *hh* : hours (00-23); +| *mm* : in time - minutes (00-59); in date - month (01-12); +| *N* : number; +| *pp* : AM or PM; +| *ss* : seconds (00-60); +| *tt* : time units (hours, minutes, min, seconds, sec); +| *yyyy* : year; +| *yy* : last two digits of the year; +| *Z* : alphabetic time zone abbreviation; +| *z* : numeric time zone; + +.. note:: + - If the date specification contains spaces, you may need to + enclose it in double quotes; + - All keywords are case-insensitive. diff --git a/doc/basic/index.rst b/doc/basic/index.rst new file mode 100644 index 000000000..e7a69301d --- /dev/null +++ b/doc/basic/index.rst @@ -0,0 +1,13 @@ +.. _basic_concepts: + +Kerberos V5 concepts +==================== + + +.. toctree:: + :maxdepth: 1 + + keytab_def + rcache_def + stash_file_def + date_format diff --git a/doc/basic/keytab_def.rst b/doc/basic/keytab_def.rst new file mode 100644 index 000000000..33ae67c6c --- /dev/null +++ b/doc/basic/keytab_def.rst @@ -0,0 +1,61 @@ +.. _keytab_definition: + +keytab +====== + +A keytab (short for "key table") stores long-term keys for one or more +principals. Keytabs are normally represented by files in a standard +format, although in rare cases they can be represented in other ways. +Keytabs are used most often to allow server applications to accept +authentications from clients, but can also be used to obtain initial +credentials for client applications. + +Keytabs are named using the format *type*\ ``:``\ *value*. Usually +*type* is ``FILE`` and *value* is the absolute pathname of the file. +Other possible values for *type* are ``SRVTAB``, which indicates a +file in the deprecated Kerberos 4 srvtab format, and ``MEMORY``, which +indicates a temporary keytab stored in the memory of the current +process. + +A keytab contains one or more entries, where each entry consists of a +timestamp (indicating when the entry was written to the keytab), a +principal name, a key version number, an encryption type, and the +encryption key itself. + +A keytab can be displayed using the :ref:`klist(1)` command with the +``-k`` option. Keytabs can be created or appended to by extracting +keys from the KDC database using the :ref:`kadmin(1)` :ref:`ktadd` +command. Keytabs can be manipulated using the :ref:`ktutil(1)` and +:ref:`k5srvutil(1)` commands. + + +Default keytab +-------------- + +The default keytab is used by server applications if the application +does not request a specific keytab. The name of the default keytab is +determined by the following, in decreasing order of preference: + +#. The **KRB5_KTNAME** environment variable. + +#. The **default_keytab_name** profile variable in :ref:`libdefaults`. + +#. The hardcoded default, |keytab|. + + +Default client keytab +--------------------- + +The default client keytab is used, if it is present and readable, to +automatically obtain initial credentials for GSSAPI client +applications. The principal name of the first entry in the client +keytab is used by default when obtaining initial credentials. The +name of the default client keytab is determined by the following, in +decreasing order of preference: + +#. The **KRB5_CLIENT_KTNAME** environment variable. + +#. The **default_client_keytab_name** profile variable in + :ref:`libdefaults`. + +#. The hardcoded default, |ckeytab|. diff --git a/doc/basic/rcache_def.rst b/doc/basic/rcache_def.rst new file mode 100644 index 000000000..2de953354 --- /dev/null +++ b/doc/basic/rcache_def.rst @@ -0,0 +1,97 @@ +.. _rcache_definition: + +replay cache +============ + +A replay cache (or "rcache") keeps track of all authenticators +recently presented to a service. If a duplicate authentication +request is detected in the replay cache, an error message is sent to +the application program. + +The replay cache interface, like the credential cache and +:ref:`keytab_definition` interfaces, uses `type:value` strings to +indicate the type of replay cache and any associated cache naming +data to use. + +Background information +---------------------- + +Some Kerberos or GSSAPI services use a simple authentication mechanism +where a message is sent containing an authenticator, which establishes +the encryption key that the client will use for talking to the +service. But nothing about that prevents an eavesdropper from +recording the messages sent by the client, establishing a new +connection, and re-sending or "replaying" the same messages; the +replayed authenticator will establish the same encryption key for the +new session, and the following messages will be decrypted and +processed. The attacker may not know what the messages say, and can't +generate new messages under the same encryption key, but in some +instances it may be harmful to the user (or helpful to the attacker) +to cause the server to see the same messages again a second time. For +example, if the legitimate client sends "delete first message in +mailbox", a replay from an attacker may delete another, different +"first" message. (Protocol design to guard against such problems has +been discussed in :rfc:`4120#section-10`.) + +Even if one protocol uses further protection to verify that the client +side of the connection actually knows the encryption keys (and thus is +presumably a legitimate user), if another service uses the same +service principal name, it may be possible to record an authenticator +used with the first protocol and "replay" it against the second. + +The replay cache mitigates these attacks somewhat, by keeping track of +authenticators that have been seen until their five-minute window +expires. Different authenticators generated by multiple connections +from the same legitimate client will generally have different +timestamps, and thus will not be considered the same. + +This mechanism isn't perfect. If a message is sent to one application +server but a man-in-the-middle attacker can prevent it from actually +arriving at that server, the attacker could then use the authenticator +(once!) against a different service on the same host. This could be a +problem if the message from the client included something more than +authentication in the first message that could be useful to the +attacker (which is uncommon; in most protocols the server has to +indicate a successful authentication before the client sends +additional messages), or if the simple act of presenting the +authenticator triggers some interesting action in the service being +attacked. + +Default rcache type +------------------- + +There is currently only one implemented kind of replay cache, called +**dfl**. It stores replay data in one file, occasionally rewriting it +to purge old, expired entries. + +The default type can be overridden by the **KRB5RCACHETYPE** +environment variable. + +The placement of the replay cache file is determined by the following: + +#. The **KRB5RCACHEDIR** environment variable; + +#. If KRB5RCACHEDIR is unspecified, on UNIX, the library + will fall back to the environment variable **TMPDIR**, and then to + a temporary directory determined at configuration time such as + */tmp* or */var/tmp*; on Windows, it will check the environment + variables *TEMP* and *TMP*, and fall back to the directory C:\\. + +Performance issues +------------------ + +Several known minor performance issues that may occur when replay +cache is enabled on the Kerberos system include: delays due to writing +the authenticator data to disk slowing down response time for very +heavily loaded servers, and delays during the rewrite that may be +unacceptable to high-performance services. + +For use cases where replays are adequately defended against for all +protocols using a given service principal name, or where performance +or other considerations outweigh the risk of replays, the special +replay cache type "none" can be specified:: + + KRB5RCACHETYPE=none + +It doesn't record any information about authenticators, and reports +that any authenticator seen is not a replay. diff --git a/doc/basic/stash_file_def.rst b/doc/basic/stash_file_def.rst new file mode 100644 index 000000000..cd6cca47b --- /dev/null +++ b/doc/basic/stash_file_def.rst @@ -0,0 +1,23 @@ +.. _stash_definition: + + +stash file +============ + +The stash file is a local copy of the master key that resides in +encrypted form on the KDC's local disk. The stash file is used to +authenticate the KDC to itself automatically before starting the +:ref:`kadmind(8)` and :ref:`krb5kdc(8)` daemons (e.g., as part of the +machine's boot sequence). The stash file, like the keytab file (see +:ref:`keytab_file`) is a potential point-of-entry for a break-in, and +if compromised, would allow unrestricted access to the Kerberos +database. If you choose to install a stash file, it should be +readable only by root, and should exist only on the KDC's local disk. +The file should not be part of any backup of the machine, unless +access to the backup data is secured as tightly as access to the +master password itself. + +.. note:: If you choose not to install a stash file, the KDC will prompt you for the master key each time it starts up. + This means that the KDC will not be able to start automatically, such as after a system reboot. + + diff --git a/doc/build/directory_org.rst b/doc/build/directory_org.rst new file mode 100644 index 000000000..928c20377 --- /dev/null +++ b/doc/build/directory_org.rst @@ -0,0 +1,76 @@ +Organization of the source directory +==================================== + +Below is a brief overview of the organization of the complete source +directory. More detailed descriptions follow. + +=============== ============================================== +appl Kerberos application client and server programs +ccapi Credential cache services +clients Kerberos V5 user programs (See :ref:`user_commands`) +config Configure scripts +config-files Sample Kerberos configuration files +gen-manpages manpages for Kerberos V5 and the Kerberos V5 login program +include include files needed to build the Kerberos system +kadmin Administrative interface to the Kerberos master database: :ref:`kadmin(1)`, :ref:`kdb5_util(8)`, :ref:`ktutil(1)`. +kdc Kerberos V5 Authentication Service and Key Distribution Center +lib_ Libraries for use with/by Kerberos V5 +plugins Kerberos plugins directory +po Localization infrastructure +prototype Templates files containing the MIT copyright message and a placeholder for the title and description of the file. +slave Utilities for propagating the database to slave KDCs :ref:`kprop(8)` and :ref:`kpropd(8)` +tests Test suite +util_ Various utilities for building/configuring the code, sending bug reports, etc. +windows Source code for building Kerberos V5 on Windows (see windows/README) +=============== ============================================== + + +.. _lib: + +lib +--- + +The lib directory contain several subdirectories as well as some +definition and glue files. + + - The apputils directory contains the code for the generic network + servicing. + - The crypto subdirectory contains the Kerberos V5 encryption + library. + - The gssapi library contains the Generic Security Services API, + which is a library of commands to be used in secure client-server + communication. + - The kadm5 directory contains the libraries for the KADM5 + administration utilities. + - The Kerberos 5 database libraries are contained in kdb. + - The krb5 directory contains Kerberos 5 API. + - The rpc directory contains the API for the Kerberos Remote + Procedure Call protocol. + + +.. _util: + +util +---- + +The util directory contains several utility programs and libraries. + - the programs used to configure and build the code, such as + autoconf, lndir, kbuild, reconf, and makedepend, are in this + directory. + - the profile directory contains most of the functions which parse + the Kerberos configuration files (krb5.conf and kdc.conf). + - the Kerberos error table library and utilities (et); + - the Sub-system library and utilities (ss); + - database utilities (db2); + - pseudo-terminal utilities (pty); + - bug-reporting program send-pr; + - a generic support library support used by several of our other + libraries; + - the build infrastructure for building lightweight Kerberos client + (collected-client-lib) + - the tool for validating Kerberos configuration files + (confvalidator); + - the toolkit for kernel integrators for building krb5 code subsets + (gss-kernel-lib); + - source code for building Kerberos V5 on MacOS (mac) + - Windows getopt operations (windows) diff --git a/doc/build/doing_build.rst b/doc/build/doing_build.rst new file mode 100644 index 000000000..bc438c849 --- /dev/null +++ b/doc/build/doing_build.rst @@ -0,0 +1,172 @@ +Doing the build +=============== + +Using autoconf +-------------- + +(If you are not a developer, you can skip this section.) + +In the Kerberos V5 source directory, there is a configure script which +automatically determines the compilation environment and creates the +proper Makefiles for a particular platform. This configure script is +generated using autoconf, which you should already have installed. + +Normal users will not need to worry about running autoconf; the +distribution comes with the configure script already prebuilt. + +One tool which is provided for the convenience of developers can be +found in ``src/util/reconf``. This program should be run while the +current directory is the top source directory. It will automatically +rebuild the configure script if it needs rebuilding. If you know that +you have made a change that will require that the configure file be +rebuilt from scratch, specify the **-**\ **-force** option:: + + cd /u1/krb5-VERSION/src + ./util/reconf --force + +Then follow the instructions for building packaged source trees +(below). To install the binaries into a binary tree, do:: + + cd /u1/krb5-VERSION/src + make all + make install DESTDIR=somewhere-else + +You have a number of different options in how to build Kerberos. + +.. _do_build: + +Building within a single tree +----------------------------- + +If you only need to build Kerberos for one platform, using a single +directory tree which contains both the source files and the object +files is the simplest. However, if you need to maintain Kerberos for +a large number of platforms, you will probably want to use separate +build trees for each platform. We recommend that you look at OS +Incompatibilities, for notes that we have on particular operating +systems. + +If you don't want separate build trees for each architecture, then use +the following abbreviated procedure:: + + cd /u1/krb5-VERSION/src + ./configure + make + +That's it! + +Building with separate build directories +---------------------------------------- + +If you wish to keep separate build directories for each platform, you +can do so using the following procedure. (Note, this requires that +your make program support VPATH. GNU's make will provide this +functionality, for example.) If your make program does not support +this, see the next section. + +For example, if you wish to store the binaries in ``tmpbuild`` build +directory you might use the following procedure:: + + mkdir /u1/tmpbuild + cd /u1/tmpbuild + /u1/krb5-VERSION/src/configure + make + + +Building using lndir +-------------------- + +If you wish to keep separate build directories for each platform, and +you do not have access to a make program which supports VPATH, all is +not lost. You can use the lndir program to create symbolic link trees +in your build directory. + +For example, if you wish to create a build directory for solaris +binaries you might use the following procedure:: + + mkdir /u1/krb5-VERSION/solaris + cd /u1/krb5-VERSION/solaris + /u1/krb5-VERSION/src/util/lndir `pwd`/../src + ./configure + make + +You must give an absolute pathname to lndir because it has a bug that +makes it fail for relative pathnames. Note that this version differs +from the latest version as distributed and installed by the +XConsortium with X11R6. Either version should be acceptable. + + +Installing the binaries +----------------------- + +Once you have built Kerberos, you should install the binaries. You can +do this by running:: + + make install + +If you want to install the binaries into a destination directory that +is not their final destination, which may be convenient if you want to +build a binary distribution to be deployed on multiple hosts, you may +use:: + + make install DESTDIR=/path/to/destdir + +This will install the binaries under *DESTDIR/PREFIX*, e.g., the user +programs will install into *DESTDIR/PREFIX/bin*, the libraries into +*DESTDIR/PREFIX/lib*, etc. + +Some implementations of make allow multiple commands to be run in +parallel, for faster builds. We test our Makefiles in parallel builds +with GNU make only; they may not be compatible with other parallel +build implementations. + + +Testing the build +----------------- + +The Kerberos V5 distribution comes with built-in regression tests. To +run them, simply type the following command while in the top-level +build directory (i.e., the directory where you sent typed make to +start building Kerberos; see :ref:`do_build`):: + + make check + +However, there are several prerequisites that must be satisfied first: + +* Configure and build Kerberos with Tcl support. Tcl is used to drive + the test suite. This often means passing **-**\ **-with-tcl** to + configure to tell it the location of the Tcl configuration + script. (See :ref:`options2configure`.) +* In addition to Tcl, DejaGnu must be available on the system for some + of the tests to run. The test suite will still run the other tests + if DejaGnu is not present, but the test coverage will be reduced + accordingly. +* On some operating systems, you have to run ``make install`` before + running ``make check``, or the test suite will pick up installed + versions of Kerberos libraries rather than the newly built ones. + You can install into a prefix that isn't in the system library + search path, though. Alternatively, you can configure with + **-**\ **-disable-rpath**, which renders the build tree less suitable for + installation, but allows testing without interference from + previously installed libraries. +* In order to test the RPC layer, the local system has to be running + the portmap daemon and it has to be listening to the regular network + interface (not just localhost). + +There are additional regression tests available, which are not run +by ``make check``. These tests require manual setup and teardown of +support infrastructure which is not easily automated, or require +excessive resources for ordinary use. The procedure for running +the manual tests is documented at +http://k5wiki.kerberos.org/wiki/Manual_Testing. + + +Cleaning up the build +--------------------- + +* Use ``make clean`` to remove all files generated by running make + command. +* Use ``make distclean`` to remove all files generated by running + ./configure script. After running ``make distclean`` your source + tree (ideally) should look like the raw (just un-tarred) source tree + with executed ``util/reconf`` command. diff --git a/doc/build/index.rst b/doc/build/index.rst new file mode 100644 index 000000000..b39b242db --- /dev/null +++ b/doc/build/index.rst @@ -0,0 +1,60 @@ +.. _build_V5: + +Building Kerberos V5 +==================== + +This section details how to build and install MIT Kerberos software +from the source. + +Prerequisites +------------- + +In order to build Kerberos V5, you will need approximately 60-70 +megabytes of disk space. The exact amount will vary depending on the +platform and whether the distribution is compiled with debugging +symbol tables or not. + +Your C compiler must conform to ANSI C (ISO/IEC 9899:1990, "c89"). +Some operating systems do not have an ANSI C compiler, or their +default compiler requires extra command-line options to enable ANSI C +conformance. + +If you wish to keep a separate build tree, which contains the compiled +\*.o file and executables, separate from your source tree, you will +need a make program which supports **VPATH**, or you will need to use +a tool such as lndir to produce a symbolic link tree for your build +tree. + +Obtaining the software +---------------------- + +The source code can be obtained from MIT Kerberos Distribution page, +at http://web.mit.edu/kerberos/dist/index.html. +The MIT Kerberos distribution comes in an archive file, generally named +krb5-VERSION.tar, where *VERSION* is a placeholder for the major and minor +versions of MIT Kerberos. (For example, MIT Kerberos 1.9 +has major version "1" and minor version "9".) + +The krb5-VERSION.tar contains a compressed tar file consisting of the +sources for all of Kerberos (generally krb5-VERSION.tar.gz) and +a PGP signature file for this source tree (generally +krb5-VERSION.tar.gz.asc). MIT highly recommends that you verify +the integrity of the source code using this signature. + +Unpack krb5-VERSION.tar.gz in some directory. In this section we will assume +that you have chosen the top directory of the distribution the directory +``/u1/krb5-VERSION``. + +Review the README file for the license, copyright and other sprecific to the +distribution information. + +Contents +-------- +.. toctree:: + :maxdepth: 1 + + directory_org.rst + doing_build.rst + options2configure.rst + osconf.rst + test_cov.rst diff --git a/doc/build/options2configure.rst b/doc/build/options2configure.rst new file mode 100644 index 000000000..211df7ea8 --- /dev/null +++ b/doc/build/options2configure.rst @@ -0,0 +1,408 @@ +.. _options2configure: + +Options to *configure* +====================== + +There are a number of options to configure which you can use to +control how the Kerberos distribution is built. + +Most commonly used options +-------------------------- + +**-**\ **-help** + Provides help to configure. This will list the set of commonly + used options for building Kerberos. + +**-**\ **-prefix=**\ *PREFIX* + By default, Kerberos will install the package's files rooted at + ``/usr/local``. If you desire to place the binaries into the + directory *PREFIX*, use this option. + +**-**\ **-exec-prefix=**\ *EXECPREFIX* + This option allows one to separate the architecture independent + programs from the host-dependent files (configuration files, + manual pages). Use this option to install architecture-dependent + programs in *EXECPREFIX*. The default location is the value of + specified by **-**\ **-prefix** option. + +**-**\ **-localstatedir=**\ *LOCALSTATEDIR* + This option sets the directory for locally modifiable + single-machine data. In Kerberos, this mostly is useful for + setting a location for the KDC data files, as they will be + installed in ``LOCALSTATEDIR/krb5kdc``, which is by default + ``PREFIX/var/krb5kdc``. + +**-**\ **-with-netlib**\ [=\ *libs*] + Allows for suppression of or replacement of network libraries. By + default, Kerberos V5 configuration will look for ``-lnsl`` and + ``-lsocket``. If your operating system has a broken resolver + library or fails to pass the tests in ``src/tests/resolv``, you + will need to use this option. + +**-**\ **-with-tcl=**\ *TCLPATH* + Some of the unit-tests in the build tree rely upon using a program + in Tcl. The directory specified by *TCLPATH* specifies where the + Tcl header file (TCLPATH/include/tcl.h) as well as where the Tcl + library (TCLPATH/lib) should be found. + +**-**\ **-enable-dns-for-realm** + Enable the use of DNS to look up a host's Kerberos realm, + if the information is not provided in + :ref:`krb5.conf(5)`. See + :ref:`mapping_hostnames` + for information about using DNS to determine the default realm. + DNS lookups for realm names are disabled by default. + +**-**\ **-with-system-et** + Use an installed version of the error-table (et) support software, + the compile_et program, the com_err.h header file and the com_err + library. If these are not in the default locations, you may wish + to specify ``CPPFLAGS=-I/some/dir`` and + ``LDFLAGS=-L/some/other/dir`` options at configuration time as + well. + + If this option is not given, a version supplied with the Kerberos + sources will be built and installed along with the rest of the + Kerberos tree, for Kerberos applications to link against. + +**-**\ **-with-system-ss** + Use an installed version of the subsystem command-line interface + software, the mk_cmds program, the ``ss/ss.h`` header file and the + ss library. If these are not in the default locations, you may + wish to specify ``CPPFLAGS=-I/some/dir`` and + ``LDFLAGS=-L/some/other/dir`` options at configuration time as + well. See also the **SS_LIB** option. + + If this option is not given, the ss library supplied with the + Kerberos sources will be compiled and linked into those programs + that need it; it will not be installed separately. + +**-**\ **-with-system-db** + Use an installed version of the Berkeley DB package, which must + provide an API compatible with version 1.85. This option is + unsupported and untested. In particular, we do not know if the + database-rename code used in the dumpfile load operation will + behave properly. + + If this option is not given, a version supplied with the Kerberos + sources will be built and installed. (We are not updating this + version at this time because of licensing issues with newer + versions that we haven't investigated sufficiently yet.) + + +Environment variables +--------------------- + +**CC=**\ *COMPILER* + Use *COMPILER* as the C compiler. + +**CFLAGS=**\ *FLAGS* + Use *FLAGS* as the default set of C compiler flags. + +**CPP=**\ *CPP* + C preprocessor to use. (e.g., ``CPP='gcc -E'``) + +**CPPFLAGS=**\ *CPPOPTS* + Use *CPPOPTS* as the default set of C preprocessor flags. The + most common use of this option is to select certain #define's for + use with the operating system's include files. + + +**DB_HEADER=**\ *headername* + If db.h is not the correct header file to include to compile + against the Berkeley DB 1.85 API, specify the correct header file + name with this option. For example, ``DB_HEADER=db3/db_185.h``. + +**DB_LIB=**\ *libs*... + If ``-ldb`` is not the correct library specification for the + Berkeley DB library version to be used, override it with this + option. For example, ``DB_LIB=-ldb-3.3``. + +**DEFCCNAME=**\ *ccachename* + Override the built-in default credential cache name. + +**DEFCKTNAME=**\ *keytabname* + Override the built-in default client keytab name. + +**DEFKTNAME=**\ *keytabname* + Override the built-in default keytab name. + +**LD=**\ *LINKER* + Use *LINKER* as the default loader if it should be different from + C compiler as specified above. + +**LDFLAGS=**\ *LDOPTS* + This option informs the linker where to get additional libraries + (e.g., ``-L``). + +**LIBS=**\ *LDNAME* + This option allows one to specify libraries to be passed to the + linker (e.g., ``-l``) + +**SS_LIB=**\ *libs*... + If ``-lss`` is not the correct way to link in your installed ss + library, for example if additional support libraries are needed, + specify the correct link options here. Some variants of this + library are around which allow for Emacs-like line editing, but + different versions require different support libraries to be + explicitly specified. + + This option is ignored if **-**\ **-with-system-ss** is not specified. + +**YACC** + The 'Yet Another C Compiler' implementation to use. Defaults to + the first program found out of: '`bison -y`', '`byacc`', + '`yacc`'. + +**YFLAGS** + The list of arguments that will be passed by default to $YACC. + This script will default YFLAGS to the empty string to avoid a + default value of ``-d`` given by some make applications. + + +Fine tuning of the installation directories +------------------------------------------- + +**-**\ **-bindir=**\ *DIR* + User executables. Defaults to ``EXECPREFIX/bin``, where + *EXECPREFIX* is the path specified by **-**\ **-exec-prefix** + configuration option. + +**-**\ **-sbindir=**\ *DIR* + System admin executables. Defaults to ``EXECPREFIX/sbin``, where + *EXECPREFIX* is the path specified by **-**\ **-exec-prefix** + configuration option. + +**-**\ **-sysconfdir=**\ *DIR* + Read-only single-machine data such as krb5.conf. + Defaults to ``PREFIX/etc``, where + *PREFIX* is the path specified by **-**\ **-prefix** configuration + option. + +**-**\ **-libdir=**\ *DIR* + Object code libraries. Defaults to ``EXECPREFIX/lib``, where + *EXECPREFIX* is the path specified by **-**\ **-exec-prefix** + configuration option. + +**-**\ **-includedir=**\ *DIR* + C header files. Defaults to ``PREFIX/include``, where *PREFIX* is + the path specified by **-**\ **-prefix** configuration option. + +**-**\ **-datarootdir=**\ *DATAROOTDIR* + Read-only architecture-independent data root. Defaults to + ``PREFIX/share``, where *PREFIX* is the path specified by + **-**\ **-prefix** configuration option. + +**-**\ **-datadir=**\ *DIR* + Read-only architecture-independent data. Defaults to path + specified by **-**\ **-datarootdir** configuration option. + +**-**\ **-localedir=**\ *DIR* + Locale-dependent data. Defaults to ``DATAROOTDIR/locale``, where + *DATAROOTDIR* is the path specified by **-**\ **-datarootdir** + configuration option. + +**-**\ **-mandir=**\ *DIR* + Man documentation. Defaults to ``DATAROOTDIR/man``, where + *DATAROOTDIR* is the path specified by **-**\ **-datarootdir** + configuration option. + + +Program names +------------- + +**-**\ **-program-prefix=**\ *PREFIX* + Prepend *PREFIX* to the names of the programs when installing + them. For example, specifying ``--program-prefix=mit-`` at the + configure time will cause the program named ``abc`` to be + installed as ``mit-abc``. + +**-**\ **-program-suffix=**\ *SUFFIX* + Append *SUFFIX* to the names of the programs when installing them. + For example, specifying ``--program-suffix=-mit`` at the configure + time will cause the program named ``abc`` to be installed as + ``abc-mit``. + +**-**\ **-program-transform-name=**\ *PROGRAM* + Run ``sed -e PROGRAM`` on installed program names. (*PROGRAM* is a + sed script). + + +System types +------------ + +**-**\ **-build=**\ *BUILD* + Configure for building on *BUILD* + (e.g., ``--build=x86_64-linux-gnu``). + +**-**\ **-host=**\ *HOST* + Cross-compile to build programs to run on *HOST* + (e.g., ``--host=x86_64-linux-gnu``). By default, Kerberos V5 + configuration will look for "build" option. + + +Optional features +----------------- + +**-**\ **-disable-option-checking** + Ignore unrecognized --enable/--with options. + +**-**\ **-disable-**\ *FEATURE* + Do not include *FEATURE* (same as --enable-FEATURE=no). + +**-**\ **-enable-**\ *FEATURE*\ [=\ *ARG*] + Include *FEATURE* [ARG=yes]. + +**-**\ **-enable-maintainer-mode** + Enable rebuilding of source files, Makefiles, etc. + +**-**\ **-disable-delayed-initialization** + Initialize library code when loaded. Defaults to delay until + first use. + +**-**\ **-disable-thread-support** + Don't enable thread support. Defaults to enabled. + +**-**\ **-disable-rpath** + Suppress run path flags in link lines. + +**-**\ **-enable-athena** + Build with MIT Project Athena configuration. + +**-**\ **-disable-kdc-lookaside-cache** + Disable the cache which detects client retransmits. + +**-**\ **-disable-pkinit** + Disable PKINIT plugin support. + + +Optional packages +----------------- + +**-**\ **-with-**\ *PACKAGE*\ [=ARG\] + Use *PACKAGE* (e.g., ``--with-imap``). The default value of *ARG* + is ``yes``. + +**-**\ **-without-**\ *PACKAGE* + Do not use *PACKAGE* (same as ``--with-PACKAGE=no``) + (e.g., ``--without-libedit``). + +**-**\ **-with-size-optimizations** + Enable a few optimizations to reduce code size possibly at some + run-time cost. + +**-**\ **-with-system-et** + Use the com_err library and compile_et utility that are already + installed on the system, instead of building and installing + local versions. + +**-**\ **-with-system-ss** + Use the ss library and mk_cmds utility that are already installed + on the system, instead of building and using private versions. + +**-**\ **-with-system-db** + Use the berkeley db utility already installed on the system, + instead of using a private version. This option is not + recommended; enabling it may result in incompatibility with key + databases originating on other systems. + +**-**\ **-with-netlib=**\ *LIBS* + Use the resolver library specified in *LIBS*. Use this variable + if the C library resolver is insufficient or broken. + +**-**\ **-with-hesiod=**\ *path* + Compile with Hesiod support. The *path* points to the Hesiod + directory. By default Hesiod is unsupported. + +**-**\ **-with-ldap** + Compile OpenLDAP database backend module. + +**-**\ **-with-tcl=**\ *path* + Specifies that *path* is the location of a Tcl installation. + Tcl is needed for some of the tests run by 'make check'; such tests + will be skipped if this option is not set. + +**-**\ **-with-vague-errors** + Do not send helpful errors to client. For example, if the KDC + should return only vague error codes to clients. + +**-**\ **-with-crypto-impl=**\ *IMPL* + Use specified crypto implementation (e.g., **-**\ **-with-crypto=**\ + *openssl*). Default is a native MIT Kerberos implementation + ``builtin``. The other currently implemented crypto backends are + ``openssl`` and ``nss``. (See :ref:`mitK5features`) + +**-**\ **-with-prng-alg=**\ *ALG* + Use specified PRNG algorithm. For example, to use the OS native + prng specify ``--with-prng-alg=os``. + + Default is the ``fortuna`` PRNG algorithm. For the ``nss`` crypto + backend use one must explicitly specify ``--with-prng-alg=nss``. + (See :ref:`mitK5features`) + +**-**\ **-with-pkinit-crypto-impl=**\ *IMPL* + Use the specified pkinit crypto implementation *IMPL*. + Defaults to using OpenSSL. + +**-**\ **-with-kdc-kdb-update** + Update the KDC database with the information about + + * the last successful authentication; + * the last failed authentication attempt; + * the number of the failed authentication attempts. + + By default the kdb is not updated with this information. + +**-**\ **-without-libedit** + Do not compile and link against libedit. Some utilities will no + longer offer command history or completion in interactive mode if + libedit is disabled. + +**-**\ **-with-readline** + Compile and link against GNU readline, as an alternative to libedit. + Building with readline breaks the dejagnu test suite, which is a + subset of the tests run by 'make check'. + +**-**\ **-with-system-verto** + Use an installed version of libverto. If the libverto header and + library are not in default locations, you may wish to specify + ``CPPFLAGS=-I/some/dir`` and ``LDFLAGS=-L/some/other/dir`` options + at configuration time as well. + + If this option is not given, the build system will try to detect + an installed version of libverto and use it if it is found. + Otherwise, a version supplied with the Kerberos sources will be + built and installed. The built-in version does not contain the + full set of back-end modules and is not a suitable general + replacement for the upstream version, but will work for the + purposes of Kerberos. + + Specifying **-**\ **-without-system-verto** will cause the built-in + version of libverto to be used unconditionally. + +**-**\ **-with-krb5-config=**\ *PATH* + Use the krb5-config program at *PATH* to obtain the build-time + default credential cache, keytab, and client keytab names. The + default is to use ``krb5-config`` from the program path. Specify + ``--without-krb5-config`` to disable the use of krb5-config and + use the usual built-in defaults. + + +Examples +-------- + +For example, in order to configure Kerberos on a Solaris machine using +the suncc compiler with the optimizer turned on, run the configure +script with the following options:: + + % ./configure CC=suncc CFLAGS=-O + +For a slightly more complicated example, consider a system where +several packages to be used by Kerberos are installed in +``/usr/foobar``, including Berkeley DB 3.3, and an ss library that +needs to link against the curses library. The configuration of +Kerberos might be done thus:: + + ./configure CPPFLAGS=-I/usr/foobar/include LDFLAGS=-L/usr/foobar/lib \ + --with-system-et --with-system-ss --with-system-db \ + SS_LIB='-lss -lcurses' DB_HEADER=db3/db_185.h DB_LIB=-ldb-3.3 diff --git a/doc/build/osconf.rst b/doc/build/osconf.rst new file mode 100644 index 000000000..22ee6804e --- /dev/null +++ b/doc/build/osconf.rst @@ -0,0 +1,26 @@ +osconf.hin +========== + +There is one configuration file which you may wish to edit to control +various compile-time parameters in the Kerberos distribution:: + + include/osconf.hin + +The list that follows is by no means complete, just some of the more +interesting variables. + +**DEFAULT_PROFILE_PATH** + The pathname to the file which contains the profiles for the known + realms, their KDCs, etc. The default value is |krb5conf|. +**DEFAULT_KEYTAB_NAME** + The type and pathname to the default server keytab file. The + default is |keytab|. +**DEFAULT_KDC_ENCTYPE** + The default encryption type for the KDC database master key. The + default value is |defmkey|. +**RCTMPDIR** + The directory which stores replay caches. The default is + ``/var/tmp``. +**DEFAULT_KDB_FILE** + The location of the default database. The default value is + |kdcdir|\ ``/principal``. diff --git a/doc/build/test_cov.rst b/doc/build/test_cov.rst new file mode 100644 index 000000000..ccd6c1367 --- /dev/null +++ b/doc/build/test_cov.rst @@ -0,0 +1,31 @@ +Test coverage +============= + +It is considered good practice to develop and maintain the test suite +with high level of test coverage, i.e., the tests that execute every +single statement, every line of the code and then validate the result. + +The GNU's gcov is a tool that analyses the frequency of execution of +each line of the code. For more details see GNU documentation +http://gcc.gnu.org/onlinedocs/gcc/Gcov.html + +To invoke gcov on krb5 tree, do configure with the following options +and run the tests:: + + ./configure CFLAGS="-fprofile-arcs -ftest-coverage -O0" LIBS=-lgcov + make + make check + +It will result into creation of the new helper files with the +extentions gcno and gcda. + +To validate the test coverage of the specific file, change the +directory to its location and run :: + + gcov -o filename.so.gcno filename.c + +To see the test coverage of the filename.c open a newly created file +filename.c.gcov in the editor. + +Some recent test coverage result can be found at the +http://k5wiki.kerberos.org/wiki/Test_coverage diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 000000000..f5edecac1 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,280 @@ +# -*- coding: utf-8 -*- +# +# MIT Kerberos documentation build configuration file, created by +# sphinx-quickstart on Wed Oct 13 09:14:03 2010. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +#extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.doxylink'] +extensions = ['sphinx.ext.autodoc'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'MIT Kerberos' +copyright = u'2012, MIT' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.0.1' +# The full version, including alpha/beta/rc tags. +release = '0.0.1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +today = ' ' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# html_theme = 'default' +html_theme = 'agogo' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +html_theme_options = { "linkcolor": "#a63019", "footerbg": "#59121e", + "bgcolor": "#59121e", "documentwidth": "900px", + "pagewidth": "960px", "sidebarwidth": "40px" } + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +html_title = "MIT Kerberos Documentation" + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = "" + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +html_split_index = True + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g., ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'MIT Kerberos' + +pointsize = '10pt' + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'MIT Kerberos.tex', u'MIT Kerberos Documentation', + u'MIT', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + +if 'mansubs' in tags: + bindir = '``@BINDIR@``' + sbindir = '``@SBINDIR@``' + libdir = '``@LIBDIR@``' + localstatedir = '``@LOCALSTATEDIR@``' + sysconfdir = '``@SYSCONFDIR@``' + ccache = '``@CCNAME@``' + keytab = '``@KTNAME@``' + ckeytab = '``@CKTNAME@``' +elif 'pathsubs' in tags: + # Read configured paths from a file produced by the build system. + execfile('paths.py') +else: + bindir = ':ref:`BINDIR `' + sbindir = ':ref:`SBINDIR `' + libdir = ':ref:`LIBDIR `' + localstatedir = ':ref:`LOCALSTATEDIR `' + sysconfdir = ':ref:`SYSCONFDIR `' + ccache = ':ref:`DEFCCNAME `' + keytab = ':ref:`DEFKTNAME `' + ckeytab = ':ref:`DEFCKTNAME `' + +rst_epilog = '\n' +rst_epilog += '.. |bindir| replace:: %s\n' % bindir +rst_epilog += '.. |sbindir| replace:: %s\n' % sbindir +rst_epilog += '.. |libdir| replace:: %s\n' % libdir +rst_epilog += '.. |kdcdir| replace:: %s\\ ``/krb5kdc``\n' % localstatedir +rst_epilog += '.. |sysconfdir| replace:: %s\n' % sysconfdir +rst_epilog += '.. |ccache| replace:: %s\n' % ccache +rst_epilog += '.. |keytab| replace:: %s\n' % keytab +rst_epilog += '.. |ckeytab| replace:: %s\n' % ckeytab +rst_epilog += ''' +.. |krb5conf| replace:: ``/etc/krb5.conf`` +.. |defkeysalts| replace:: ``aes256-cts-hmac-sha1-96:normal aes128-cts-hmac-sha1-96:normal des3-cbc-sha1:normal arcfour-hmac-md5:normal`` +.. |defetypes| replace:: ``aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 arcfour-hmac-md5 des-cbc-crc des-cbc-md5 des-cbc-md4`` +.. |defmkey| replace:: ``aes256-cts-hmac-sha1-96`` +''' + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('krb_users/user_commands/kinit', 'kinit', u'obtain and cache Kerberos ticket-granting ticket', [u'MIT'], 1), + ('krb_users/user_commands/klist', 'klist', u'list cached Kerberos tickets', [u'MIT'], 1), + ('krb_users/user_commands/kdestroy', 'kdestroy', u'destroy Kerberos tickets', [u'MIT'], 1), + ('krb_users/user_commands/kswitch', 'kswitch', u'switch primary ticket cache', [u'MIT'], 1), + ('krb_users/user_commands/kpasswd', 'kpasswd', u'change a user\'s Kerberos password', [u'MIT'], 1), + ('krb_users/user_commands/kvno', 'kvno', u'print key version numbers of Kerberos principals', [u'MIT'], 1), + ('krb_users/user_commands/ksu', 'ksu', u'Kerberized super-user', [u'MIT'], 1), + ('krb_users/user_config/k5login', 'k5login', u'Kerberos V5 acl file for host access', [u'MIT'], 5), + ('krb_users/user_config/k5identity', 'k5identity', u'Kerberos V5 client principal selection rules', [u'MIT'], 5), + ('krb_admins/admin_commands/krb5kdc', 'krb5kdc', u'Kerberos V5 KDC', [u'MIT'], 8), + ('krb_admins/admin_commands/kadmin_local', 'kadmin', u'Kerberos V5 database administration program', [u'MIT'], 1), + ('krb_admins/admin_commands/kprop', 'kprop', u'propagate a Kerberos V5 principal database to a slave server', [u'MIT'], 8), + ('krb_admins/admin_commands/kproplog', 'kproplog', u'display the contents of the Kerberos principal update log', [u'MIT'], 8), + ('krb_admins/admin_commands/kpropd', 'kpropd', u'Kerberos V5 slave KDC update server', [u'MIT'], 8), + ('krb_admins/admin_commands/kdb5_util', 'kdb5_util', u'Kerberos database maintenance utility', [u'MIT'], 8), + ('krb_admins/admin_commands/ktutil', 'ktutil', u'Kerberos keytab file maintenance utility', [u'MIT'], 1), + ('krb_admins/admin_commands/k5srvutil', 'k5srvutil', u'host key table (keytab) manipulation utility', [u'MIT'], 1), + ('krb_admins/admin_commands/kadmind', 'kadmind', u'KADM5 administration server', [u'MIT'], 8), + ('krb_admins/admin_commands/kdb5_ldap_util', 'kdb5_ldap_util', u'Kerberos configuration utility', [u'MIT'], 8), + ('krb_admins/conf_files/krb5_conf', 'krb5.conf', u'Kerberos configuration file', [u'MIT'], 5), + ('krb_admins/conf_files/kdc_conf', 'kdc.conf', u'Kerberos V5 KDC configuration file', [u'MIT'], 5), + ('krb_admins/conf_files/kadm5_acl', 'kadm5.acl', u'Kerberos ACL file', [u'MIT'], 5), + ('krb_users/user_commands/sclient', 'sclient', u'sample Kerberos version 5 client', [u'MIT'], 1), + ('krb_admins/admin_commands/sserver', 'sserver', u'sample Kerberos version 5 server', [u'MIT'], 8), +] diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 000000000..fb1012bc1 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,22 @@ +MIT Kerberos Documentation +========================== + + +.. toctree:: + :maxdepth: 1 + + krb_users/index.rst + krb_admins/index.rst + krb_appldev/index.rst + krb_plugindev/index.rst + krb_build/index.rst + krb_basic/index.rst + mitK5features.rst + relay/index.rst + resources + + +.. _reference: + +:Release: |version| + diff --git a/doc/mitK5defaults.rst b/doc/mitK5defaults.rst new file mode 100644 index 000000000..84b9df881 --- /dev/null +++ b/doc/mitK5defaults.rst @@ -0,0 +1,76 @@ +.. _mitK5defaults: + +MIT Kerberos defaults +===================== + +General defaults +---------------- + +========================================== ============================= ==================== +Description Default Environment +========================================== ============================= ==================== +:ref:`keytab_definition` file |keytab| **KRB5_KTNAME** +Client :ref:`keytab_definition` file |ckeytab| **KRB5_CLIENT_KTNAME** +Kerberos config file :ref:`krb5.conf(5)` |krb5conf|\ ``:``\ **KRB5_CONFIG** + |sysconfdir|\ ``/krb5.conf`` +KDC config file :ref:`kdc.conf(5)` |kdcdir|\ ``/kdc.conf`` **KRB5_KDC_PROFILE** +KDC database path (DB2) |kdcdir|\ ``/principal`` +Master key :ref:`stash_definition` |kdcdir|\ ``/.k5.``\ *realm* +Admin server ACL file :ref:`kadm5.acl(5)` |kdcdir|\ ``/kadm5.acl`` +Plugin base directory |libdir|\ ``/krb5/plugins`` +:ref:`rcache_definition` directory ``/var/tmp`` **KRB5RCACHEDIR** +Master key default enctype |defmkey| +Supported :ref:`Encryption_and_salt_types` |defkeysalts| +Permitted enctypes |defetypes| +KDC default port 88 +Second KDC default port 750 +Admin server port 749 +Password change port 464 +========================================== ============================= ==================== + + +Slave KDC propagation defaults +------------------------------ + +This table shows defaults used by the :ref:`kprop(8)` and +:ref:`kpropd(8)` programs. + +========================== ============================== =========== +Description Default Environment +========================== ============================== =========== +kprop database dump file |kdcdir|\ ``/slave_datatrans`` +kpropd temporary dump file |kdcdir|\ ``/from_master`` +kdb5_util location |sbindir|\ ``/kdb5_util`` +kprop location |sbindir|\ ``/kprop`` +kpropd ACL file |kdcdir|\ ``/kpropd.acl`` +kprop port 754 KPROP_PORT +========================== ============================== =========== + + +.. _paths: + +Default paths for Unix-like systems +----------------------------------- + +On Unix-like systems, some paths used by MIT krb5 depend on parameters +chosen at build time. For a custom build, these paths default to +subdirectories of ``/usr/local``. When MIT krb5 is integrated into an +operating system, the paths are generally chosen to match the +operating system's filesystem layout. + +========================== ============= =========================== =========================== +Description Symbolic name Custom build path Typical OS path +========================== ============= =========================== =========================== +User programs BINDIR ``/usr/local/bin`` ``/usr/bin`` +Libraries and plugins LIBDIR ``/usr/local/lib`` ``/usr/lib`` +Parent of KDC state dir LOCALSTATEDIR ``/usr/local/var`` ``/var`` +Administrative programs SBINDIR ``/usr/local/sbin`` ``/usr/sbin`` +Alternate krb5.conf dir SYSCONFDIR ``/usr/local/etc`` ``/etc`` +Default ccache name DEFCCNAME ``FILE:/tmp/krb5cc_%{uid}`` ``FILE:/tmp/krb5cc_%{uid}`` +Default keytab name DEFKTNAME ``FILE:/etc/krb5.keytab`` ``FILE:/etc/krb5.keytab`` +========================== ============= =========================== =========================== + +The default client keytab name (DEFCKTNAME) typically defaults to +``FILE:/usr/local/var/krb5/user/%{euid}/client.keytab`` for a custom +build. A native build will typically use a path which will vary +according to the operating system's layout of ``/var``. diff --git a/doc/mitK5features.rst b/doc/mitK5features.rst new file mode 100644 index 000000000..db79066bc --- /dev/null +++ b/doc/mitK5features.rst @@ -0,0 +1,140 @@ +.. highlight:: rst + +.. _mitK5features: + +MIT Kerberos Features +===================== + +http://web.mit.edu/kerberos + + +Quick facts +----------- + + ====================================================== ======================================= ============================================================================= + Latest stable version 1.10.3 http://web.mit.edu/kerberos/krb5-1.10/ + Supported versions 1.9.4, 1.10.3 http://web.mit.edu/kerberos/krb5-1.9/ + Release cycle 9 - 12 months + Supported platforms/OS distributions Solaris + - SPARC + - x86_64/x86 + GNU/Linux + - Debian x86_64/x86 + - Ubuntu x86_64/x86 + - RedHat x86_64/x86 + BSD + - NetBSD x86_64/x86 + Crypto backends - OpenSSL 1.0\+ - http://www.openssl.org + - builtin - MIT Kerberos native crypto library + - NSS 3.12.9\+ - Mozilla's Network Security Services. + http://www.mozilla.org/projects/security/pki/nss + Database backends - LDAP + - DB2 + krb4 support < 1.8 + DES support configurable http://k5wiki.kerberos.org/wiki/Projects/Disable_DES + GSS-API S4U extensions 1.8+ http://msdn.microsoft.com/en-us/library/cc246071 + - S4U2Self + - S4U2Proxy + GSS-API naming extensions 1.8+ http://tools.ietf.org/html/draft-ietf-kitten-gssapi-naming-exts-11 + + GSS-API extensions for storing delegated credentials 1.8+ :rfc:`5588` + + License :ref:`mitK5license` + ====================================================== ======================================= ============================================================================= + + +Interoperabiity +--------------- + +Microsoft +~~~~~~~~~ + +Starting from version 1.7: + +* Follow client principal referrals in the client library when + obtaining initial tickets. + +* KDC can issue realm referrals for service principals based on domain names. + +* Extensions supporting DCE RPC, including three-leg GSS context setup + and unencapsulated GSS tokens inside SPNEGO. + +* Microsoft GSS_WrapEX, implemented using the gss_iov API, which is + similar to the equivalent SSPI functionality. This is needed to + support some instances of DCE RPC. + +* NTLM recognition support in GSS-API, to facilitate dropping in an + NTLM implementation for improved compatibility with older releases + of Microsoft Windows. + +* KDC support for principal aliases, if the back end supports them. + Currently, only the LDAP back end supports aliases. + +* Support Microsoft set/change password (RFC 3244) protocol in + kadmind. + +* Implement client and KDC support for GSS_C_DELEG_POLICY_FLAG, which + allows a GSS application to request credential delegation only if + permitted by KDC policy. + + +Starting from version 1.8: + +* Microsoft Services for User (S4U) compatibility` + + +Heimdal +~~~~~~~ + +* Support for reading Heimdal database starting from version 1.8 + + +Feature list +------------ + + =============================================== =========== ============================================ + \ Available Additional information + =============================================== =========== ============================================ + Credentials delegation 1.7 :rfc:`5896` + Cross-realm authentication and referrals 1.7 http://tools.ietf.org/html/draft-ietf-krb-wg-kerberos-referrals-12 + Master key migration 1.7 http://k5wiki.kerberos.org/wiki/Projects/Master_Key_Migration + PKINIT 1.7 :rfc:`4556` + Anonymous PKINIT 1.8 :rfc:`6112` http://k5wiki.kerberos.org/wiki/Projects/Anonymous_pkinit + Constrained delegation 1.8 http://k5wiki.kerberos.org/wiki/Projects/ConstrainedDelegation + IAKERB 1.8 http://tools.ietf.org/html/draft-ietf-krb-wg-iakerb-02 + Heimdal bridge plugin for KDC backend 1.8 + Advance warning on password expiry 1.9 + Camellia encryption (CTS-CMAC mode) 1.9 experimental http://tools.ietf.org/html/draft-ietf-krb-wg-camellia-cts-00 + KDC support for SecurID preauthentication 1.9 http://k5wiki.kerberos.org/wiki/Projects/SecurID_SAM_support + kadmin over IPv6 1.9 + Trace logging 1.9 http://k5wiki.kerberos.org/wiki/Projects/Trace_logging + GSSAPI/KRB5 multi-realm support + Plugin to test password quality 1.9 http://k5wiki.kerberos.org/wiki/Projects/Password_quality_pluggable_interface + Plugin to synchronize password changes 1.9 + Parallel KDC 1.9 + GS2 1.9 :rfc:`5801` :rfc:`5587` http://k5wiki.kerberos.org/wiki/Projects/GS2 + Purging old keys 1.9 + Naming extensions for delegation chain 1.9 + Password expiration API 1.9 + Windows client support (build-only) 1.9 + pre-auth mechanisms: + - PW-SALT :rfc:`4120#section-5.2.7.3` + - ENC-TIMESTAMP :rfc:`4120#section-5.2.7.2` + - SAM-2 + - FAST negotiation framework 1.8 :rfc:`6113` + - PKINIT with FAST on client 1.10 :rfc:`6113` + - PKINIT :rfc:`4556` + - FX-COOKIE :rfc:`6113#section-5.2` + - S4U-X509-USER 1.8 http://msdn.microsoft.com/en-us/library/cc246091 + + PRNG + - modularity: 1.9 + - Yarrow PRNG < 1.10 + - Fortuna PRNG 1.9 http://www.schneier.com/book-practical.html + - OS PRNG 1.10 OS's native PRNG + Zero configuration + IPv6 support in iprop + Plugin interface for configuration 1.10 http://k5wiki.kerberos.org/wiki/Projects/Pluggable_configuration + Credentials for multiple identities 1.10 http://k5wiki.kerberos.org/wiki/Projects/Client_principal_selection + =============================================== =========== ============================================ + diff --git a/doc/mitK5license.rst b/doc/mitK5license.rst new file mode 100644 index 000000000..6b837b90f --- /dev/null +++ b/doc/mitK5license.rst @@ -0,0 +1,6 @@ +.. _mitK5license: + +MIT Kerberos License information +================================ + +.. include:: notice.rst diff --git a/doc/notice.rst b/doc/notice.rst new file mode 100644 index 000000000..9fe8f7957 --- /dev/null +++ b/doc/notice.rst @@ -0,0 +1,1124 @@ +.. include:: + +Copyright |copy| 1985-2012 by the Massachusetts Institute of Technology. + +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +1. Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +Downloading of this software may constitute an export of cryptographic +software from the United States of America that is subject to the +United States Export Administration Regulations (EAR), 15 CFR 730-774. +Additional laws or regulations may apply. It is the responsibility of +the person or entity contemplating export to comply with all +applicable export laws and regulations, including obtaining any +required license from the U.S. government. + +The U.S. government prohibits export of encryption source code to +certain countries and individuals, including, but not limited to, the +countries of Cuba, Iran, North Korea, Sudan, Syria, and residents and +nationals of those countries. + +Documentation components of this software distribution are licensed +under a Creative Commons Attribution-ShareAlike 3.0 Unported License. +(http://creativecommons.org/licenses/by-sa/3.0/) + +Individual source code files are copyright MIT, Cygnus Support, +Novell, OpenVision Technologies, Oracle, Red Hat, Sun Microsystems, +FundsXpress, and others. + +Project Athena, Athena, Athena MUSE, Discuss, Hesiod, Kerberos, Moira, +and Zephyr are trademarks of the Massachusetts Institute of Technology +(MIT). No commercial use of these trademarks may be made without +prior written permission of MIT. + +"Commercial use" means use of a name in a product or other for-profit +manner. It does NOT prevent a commercial firm from referring to the +MIT trademarks in order to convey information (although in doing so, +recognition of their trademark status should be given). + +------------------- + +The following copyright and permission notice applies to the +OpenVision Kerberos Administration system located in +``kadmin/create``, ``kadmin/dbutil``, ``kadmin/passwd``, +``kadmin/server``, ``lib/kadm5``, and portions of +``lib/rpc``: + + Copyright, OpenVision Technologies, Inc., 1993-1996, All Rights Reserved + + WARNING: Retrieving the OpenVision Kerberos Administration system source + code, as described below, indicates your acceptance of the following + terms. If you do not agree to the following terms, do not retrieve the + OpenVision Kerberos administration system. + + You may freely use and distribute the Source Code and Object Code + compiled from it, with or without modification, but this Source Code is + provided to you "AS IS" EXCLUSIVE OF ANY WARRANTY, INCLUDING, WITHOUT + LIMITATION, ANY WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A + PARTICULAR PURPOSE, OR ANY OTHER WARRANTY, WHETHER EXPRESS OR IMPLIED. + IN NO EVENT WILL OPENVISION HAVE ANY LIABILITY FOR ANY LOST PROFITS, + LOSS OF DATA OR COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR + FOR ANY SPECIAL, INDIRECT, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THIS + AGREEMENT, INCLUDING, WITHOUT LIMITATION, THOSE RESULTING FROM THE USE + OF THE SOURCE CODE, OR THE FAILURE OF THE SOURCE CODE TO PERFORM, OR FOR + ANY OTHER REASON. + + OpenVision retains all copyrights in the donated Source Code. OpenVision + also retains copyright to derivative works of the Source Code, whether + created by OpenVision or by a third party. The OpenVision copyright + notice must be preserved if derivative works are made based on the + donated Source Code. + + OpenVision Technologies, Inc. has donated this Kerberos Administration + system to MIT for inclusion in the standard Kerberos 5 distribution. + This donation underscores our commitment to continuing Kerberos + technology development and our gratitude for the valuable work which has + been performed by MIT and the Kerberos community. + +------------------- + + Portions contributed by Matt Crawford ``crawdad@fnal.gov`` were work + performed at Fermi National Accelerator Laboratory, which is operated + by Universities Research Association, Inc., under contract + DE-AC02-76CHO3000 with the U.S. Department of Energy. + +------------------- + +Portions of ``src/lib/crypto`` have the following copyright: + + Copyright |copy| 1998 by the FundsXpress, INC. + + All rights reserved. + + Export of this software from the United States of America may require + a specific license from the United States Government. It is the + responsibility of any person or organization contemplating export to + obtain such a license before exporting. + + WITHIN THAT CONSTRAINT, permission to use, copy, modify, and + distribute this software and its documentation for any purpose and + without fee is hereby granted, provided that the above copyright + notice appear in all copies and that both that copyright notice and + this permission notice appear in supporting documentation, and that + the name of FundsXpress. not be used in advertising or publicity pertaining + to distribution of the software without specific, written prior + permission. FundsXpress makes no representations about the suitability of + this software for any purpose. It is provided "as is" without express + or implied warranty. + + THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED + WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. + +------------------- + +The implementation of the AES encryption algorithm in +``src/lib/crypto/builtin/aes`` has the following copyright: + + | Copyright |copy| 2001, Dr Brian Gladman ``brg@gladman.uk.net``, + Worcester, UK. + | All rights reserved. + + LICENSE TERMS + + The free distribution and use of this software in both source and binary + form is allowed (with or without changes) provided that: + + 1. distributions of this source code include the above copyright + notice, this list of conditions and the following disclaimer; + 2. distributions in binary form include the above copyright + notice, this list of conditions and the following disclaimer + in the documentation and/or other associated materials; + 3. the copyright holder's name is not used to endorse products + built using this software without specific written permission. + + DISCLAIMER + + This software is provided 'as is' with no explcit or implied warranties + in respect of any properties, including, but not limited to, correctness + and fitness for purpose. + +------------------- + +Portions contributed by Red Hat, including the pre-authentication +plug-in framework and the NSS crypto implementation, contain the +following copyright: + + | Copyright |copy| 2006 Red Hat, Inc. + | Portions copyright |copy| 2006 Massachusetts Institute of Technology + | All Rights Reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are + met: + + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + 3. Neither the name of Red Hat, Inc., nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS + IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED + TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A + PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER + OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +------------------- + +The bundled verto source code is subject to the following license: + + Copyright 2011 Red Hat, Inc. + + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation files + (the "Software"), to deal in the Software without restriction, + including without limitation the rights to use, copy, modify, merge, + publish, distribute, sublicense, and/or sell copies of the Software, + and to permit persons to whom the Software is furnished to do so, + subject to the following conditions: + + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS + BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN + ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + +------------------- + +The implementations of GSSAPI mechglue in GSSAPI-SPNEGO in +``src/lib/gssapi``, including the following files: + +.. parsed-literal:: + + lib/gssapi/generic/gssapi_err_generic.et + lib/gssapi/mechglue/g_accept_sec_context.c + lib/gssapi/mechglue/g_acquire_cred.c + lib/gssapi/mechglue/g_canon_name.c + lib/gssapi/mechglue/g_compare_name.c + lib/gssapi/mechglue/g_context_time.c + lib/gssapi/mechglue/g_delete_sec_context.c + lib/gssapi/mechglue/g_dsp_name.c + lib/gssapi/mechglue/g_dsp_status.c + lib/gssapi/mechglue/g_dup_name.c + lib/gssapi/mechglue/g_exp_sec_context.c + lib/gssapi/mechglue/g_export_name.c + lib/gssapi/mechglue/g_glue.c + lib/gssapi/mechglue/g_imp_name.c + lib/gssapi/mechglue/g_imp_sec_context.c + lib/gssapi/mechglue/g_init_sec_context.c + lib/gssapi/mechglue/g_initialize.c + lib/gssapi/mechglue/g_inquire_context.c + lib/gssapi/mechglue/g_inquire_cred.c + lib/gssapi/mechglue/g_inquire_names.c + lib/gssapi/mechglue/g_process_context.c + lib/gssapi/mechglue/g_rel_buffer.c + lib/gssapi/mechglue/g_rel_cred.c + lib/gssapi/mechglue/g_rel_name.c + lib/gssapi/mechglue/g_rel_oid_set.c + lib/gssapi/mechglue/g_seal.c + lib/gssapi/mechglue/g_sign.c + lib/gssapi/mechglue/g_store_cred.c + lib/gssapi/mechglue/g_unseal.c + lib/gssapi/mechglue/g_userok.c + lib/gssapi/mechglue/g_utils.c + lib/gssapi/mechglue/g_verify.c + lib/gssapi/mechglue/gssd_pname_to_uid.c + lib/gssapi/mechglue/mglueP.h + lib/gssapi/mechglue/oid_ops.c + lib/gssapi/spnego/gssapiP_spnego.h + lib/gssapi/spnego/spnego_mech.c + +and the initial implementation of incremental propagation, including +the following new or changed files: + +.. parsed-literal:: + + include/iprop_hdr.h + kadmin/server/ipropd_svc.c + lib/kdb/iprop.x + lib/kdb/kdb_convert.c + lib/kdb/kdb_log.c + lib/kdb/kdb_log.h + lib/krb5/error_tables/kdb5_err.et + slave/kpropd_rpc.c + slave/kproplog.c + +are subject to the following license: + + Copyright |copy| 2004 Sun Microsystems, Inc. + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. + IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY + CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, + TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE + SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +------------------- + +Kerberos V5 includes documentation and software developed at the +University of California at Berkeley, which includes this copyright +notice: + + | Copyright |copy| 1983 Regents of the University of California. + | All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are + met: + + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + 3. Neither the name of the University nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND + ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE + FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + SUCH DAMAGE. + +------------------- + +Portions contributed by Novell, Inc., including the LDAP database +backend, are subject to the following license: + + | Copyright |copy| 2004-2005, Novell, Inc. + | All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are met: + + 1. Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + 3. The copyright holder's name is not used to endorse or promote products + derived from this software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + +------------------- + +Portions funded by Sandia National Laboratory +and developed by the University of Michigan's +Center for Information Technology Integration, +including the PKINIT implementation, are subject +to the following license: + + | COPYRIGHT |copy| 2006-2007 + | THE REGENTS OF THE UNIVERSITY OF MICHIGAN + | ALL RIGHTS RESERVED + + Permission is granted to use, copy, create derivative works + and redistribute this software and such derivative works + for any purpose, so long as the name of The University of + Michigan is not used in any advertising or publicity + pertaining to the use of distribution of this software + without specific, written prior authorization. If the + above copyright notice or any other identification of the + University of Michigan is included in any copy of any + portion of this software, then the disclaimer below must + also be included. + + THIS SOFTWARE IS PROVIDED AS IS, WITHOUT REPRESENTATION + FROM THE UNIVERSITY OF MICHIGAN AS TO ITS FITNESS FOR ANY + PURPOSE, AND WITHOUT WARRANTY BY THE UNIVERSITY OF + MICHIGAN OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING + WITHOUT LIMITATION THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE + REGENTS OF THE UNIVERSITY OF MICHIGAN SHALL NOT BE LIABLE + FOR ANY DAMAGES, INCLUDING SPECIAL, INDIRECT, INCIDENTAL, OR + CONSEQUENTIAL DAMAGES, WITH RESPECT TO ANY CLAIM ARISING + OUT OF OR IN CONNECTION WITH THE USE OF THE SOFTWARE, EVEN + IF IT HAS BEEN OR IS HEREAFTER ADVISED OF THE POSSIBILITY OF + SUCH DAMAGES. + +------------------- + +The pkcs11.h file included in the PKINIT code has the +following license: + + | Copyright 2006 g10 Code GmbH + | Copyright 2006 Andreas Jellinghaus + + This file is free software; as a special exception the author gives + unlimited permission to copy and/or distribute it, with or without + modifications, as long as this notice is preserved. + + This file is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY, to the extent permitted by law; without even + the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR + PURPOSE. + +------------------- + +Portions contributed by Apple Inc. are subject to the following license: + + Copyright 2004-2008 Apple Inc. All Rights Reserved. + + Export of this software from the United States of America may require + a specific license from the United States Government. It is the + responsibility of any person or organization contemplating export to + obtain such a license before exporting. + + WITHIN THAT CONSTRAINT, permission to use, copy, modify, and + distribute this software and its documentation for any purpose and + without fee is hereby granted, provided that the above copyright + notice appear in all copies and that both that copyright notice and + this permission notice appear in supporting documentation, and that + the name of Apple Inc. not be used in advertising or publicity pertaining + to distribution of the software without specific, written prior + permission. Apple Inc. makes no representations about the suitability of + this software for any purpose. It is provided "as is" without express + or implied warranty. + + THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED + WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. + +------------------- + +The implementations of UTF-8 string handling in src/util/support and +src/lib/krb5/unicode are subject to the following copyright and +permission notice: + + | The OpenLDAP Public License + | Version 2.8, 17 August 2003 + + Redistribution and use of this software and associated documentation + ("Software"), with or without modification, are permitted provided + that the following conditions are met: + + 1. Redistributions in source form must retain copyright statements + and notices, + 2. Redistributions in binary form must reproduce applicable copyright + statements and notices, this list of conditions, and the following + disclaimer in the documentation and/or other materials provided + with the distribution, and + 3. Redistributions must contain a verbatim copy of this document. + + The OpenLDAP Foundation may revise this license from time to time. + Each revision is distinguished by a version number. You may use + this Software under terms of this license revision or under the + terms of any subsequent revision of the license. + + THIS SOFTWARE IS PROVIDED BY THE OPENLDAP FOUNDATION AND ITS + CONTRIBUTORS "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY + AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT + SHALL THE OPENLDAP FOUNDATION, ITS CONTRIBUTORS, OR THE AUTHOR(S) + OR OWNER(S) OF THE SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, + INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, + BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER + CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + The names of the authors and copyright holders must not be used in + advertising or otherwise to promote the sale, use or other dealing + in this Software without specific, written prior permission. Title + to copyright in this Software shall at all times remain with copyright + holders. + + OpenLDAP is a registered trademark of the OpenLDAP Foundation. + + Copyright 1999-2003 The OpenLDAP Foundation, Redwood City, + California, USA. All Rights Reserved. Permission to copy and + distribute verbatim copies of this document is granted. + +------------------- + +Marked test programs in src/lib/krb5/krb have the following copyright: + + | Copyright |copy| 2006 Kungliga Tekniska Högskola + | (Royal Institute of Technology, Stockholm, Sweden). + | All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + 3. Neither the name of KTH nor the names of its contributors may be + used to endorse or promote products derived from this software without + specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY KTH AND ITS CONTRIBUTORS "AS IS" AND ANY + EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL KTH OR ITS CONTRIBUTORS BE + LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR + OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF + ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +------------------- + +Portions of the RPC implementation in src/lib/rpc and src/include/gssrpc +have the following copyright and permission notice: + + Copyright |copy| 2010, Oracle America, Inc. + + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are met: + + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + 3. Neither the name of the "Oracle America, Inc." nor the names of + its contributors may be used to endorse or promote products + derived from this software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS + IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED + TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A + PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED + TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +------------------- + + Copyright |copy| 2006,2007,2009 + NTT (Nippon Telegraph and Telephone Corporation). All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer as + the first lines of this file unmodified. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + + THIS SOFTWARE IS PROVIDED BY NTT "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. + IN NO EVENT SHALL NTT BE LIABLE FOR ANY DIRECT, INDIRECT, + INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF + THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +------------------- + + Copyright 2000 by Carnegie Mellon University + + All Rights Reserved + + Permission to use, copy, modify, and distribute this software and its + documentation for any purpose and without fee is hereby granted, + provided that the above copyright notice appear in all copies and that + both that copyright notice and this permission notice appear in + supporting documentation, and that the name of Carnegie Mellon + University not be used in advertising or publicity pertaining to + distribution of the software without specific, written prior + permission. + + CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO + THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE FOR + ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT + OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +------------------- + + Copyright |copy| 2002 Naval Research Laboratory (NRL/CCS) + + Permission to use, copy, modify and distribute this software and its + documentation is hereby granted, provided that both the copyright + notice and this permission notice appear in all copies of the software, + derivative works or modified versions, and any portions thereof. + + NRL ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" CONDITION AND + DISCLAIMS ANY LIABILITY OF ANY KIND FOR ANY DAMAGES WHATSOEVER + RESULTING FROM THE USE OF THIS SOFTWARE. + +------------------- + +Portions extracted from Internet RFCs have the following copyright +notice: + + Copyright |copy| The Internet Society (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +------------------- + + Copyright |copy| 1991, 1992, 1994 by Cygnus Support. + + Permission to use, copy, modify, and + distribute this software and its documentation for any purpose and + without fee is hereby granted, provided that the above copyright + notice appear in all copies and that both that copyright notice and + this permission notice appear in supporting documentation. + Cygnus Support makes no representations about the suitability of + this software for any purpose. It is provided "as is" without express + or implied warranty. + +------------------- + + Copyright |copy| 2006 Secure Endpoints Inc. + + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, copy, + modify, merge, publish, distribute, sublicense, and/or sell copies + of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS + BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN + ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. + +------------------- + +Portions of the implementation of the Fortuna-like PRNG are subject to +the following notice: + + | Copyright |copy| 2005 Marko Kreen + | All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + + THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND + ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE + FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + SUCH DAMAGE. + +.. + + Copyright |copy| 1994 by the University of Southern California + + EXPORT OF THIS SOFTWARE from the United States of America may + require a specific license from the United States Government. + It is the responsibility of any person or organization contemplating + export to obtain such a license before exporting. + + WITHIN THAT CONSTRAINT, permission to copy, modify, and distribute + this software and its documentation in source and binary forms is + hereby granted, provided that any documentation or other materials + related to such distribution or use acknowledge that the software + was developed by the University of Southern California. + + DISCLAIMER OF WARRANTY. THIS SOFTWARE IS PROVIDED "AS IS". The + University of Southern California MAKES NO REPRESENTATIONS OR + WARRANTIES, EXPRESS OR IMPLIED. By way of example, but not + limitation, the University of Southern California MAKES NO + REPRESENTATIONS OR WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY + PARTICULAR PURPOSE. The University of Southern + California shall not be held liable for any liability nor for any + direct, indirect, or consequential damages with respect to any + claim by the user or distributor of the ksu software. + +------------------- + + | Copyright |copy| 1995 + | The President and Fellows of Harvard University + + This code is derived from software contributed to Harvard by + Jeremy Rassen. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + 3. All advertising materials mentioning features or use of this software + must display the following acknowledgement: + + This product includes software developed by the University of + California, Berkeley and its contributors. + + 4. Neither the name of the University nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND + ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE + FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + SUCH DAMAGE. + +------------------- + + | Copyright |copy| 2008 by the Massachusetts Institute of Technology. + | Copyright 1995 by Richard P. Basch. All Rights Reserved. + | Copyright 1995 by Lehman Brothers, Inc. All Rights Reserved. + + Export of this software from the United States of America may + require a specific license from the United States Government. + It is the responsibility of any person or organization contemplating + export to obtain such a license before exporting. + + WITHIN THAT CONSTRAINT, permission to use, copy, modify, and + distribute this software and its documentation for any purpose and + without fee is hereby granted, provided that the above copyright + notice appear in all copies and that both that copyright notice and + this permission notice appear in supporting documentation, and that + the name of Richard P. Basch, Lehman Brothers and M.I.T. not be used + in advertising or publicity pertaining to distribution of the software + without specific, written prior permission. Richard P. Basch, + Lehman Brothers and M.I.T. make no representations about the suitability + of this software for any purpose. It is provided "as is" without + express or implied warranty. + +------------------- + +The following notice applies to ``src/lib/krb5/krb/strptime.c`` and +``src/include/k5-queue.h``. + + | Copyright |copy| 1997, 1998 The NetBSD Foundation, Inc. + | All rights reserved. + + This code was contributed to The NetBSD Foundation by Klaus Klein. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + 3. All advertising materials mentioning features or use of this software + must display the following acknowledgement: + + This product includes software developed by the NetBSD + Foundation, Inc. and its contributors. + + 4. Neither the name of The NetBSD Foundation nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED + TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS + BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + +------------------- + +The following notice applies to Unicode library files in +``src/lib/krb5/unicode``: + + | Copyright 1997, 1998, 1999 Computing Research Labs, + | New Mexico State University + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE COMPUTING RESEARCH LAB OR NEW MEXICO STATE UNIVERSITY BE LIABLE FOR ANY + CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT + OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR + THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +------------------- + +The following notice applies to ``src/util/support/strlcpy.c``: + + Copyright |copy| 1998 Todd C. Miller ``Todd.Miller@courtesan.com`` + + Permission to use, copy, modify, and distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +------------------- + +The following notice applies to ``src/util/profile/argv_parse.c`` and +``src/util/profile/argv_parse.h``: + + Copyright 1999 by Theodore Ts'o. + + Permission to use, copy, modify, and distribute this software for + any purpose with or without fee is hereby granted, provided that + the above copyright notice and this permission notice appear in all + copies. THE SOFTWARE IS PROVIDED "AS IS" AND THEODORE TS'O (THE + AUTHOR) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, + INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. + IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, + INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER + RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION + OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR + IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. (Isn't + it sick that the U.S. culture of lawsuit-happy lawyers requires + this kind of disclaimer?) + +------------------- + +The following notice applies to SWIG-generated code in +``src/util/profile/profile_tcl.c``: + + Copyright |copy| 1999-2000, The University of Chicago + + This file may be freely redistributed without license or fee provided + this copyright message remains intact. + +------------------- + +The following notice applies to portiions of ``src/lib/rpc`` and +``src/include/gssrpc``: + + Copyright |copy| 2000 The Regents of the University of Michigan. + All rights reserved. + + Copyright |copy| 2000 Dug Song ``dugsong@UMICH.EDU``. + All rights reserved, all wrongs reversed. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + 3. Neither the name of the University nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED + WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE + FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR + BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF + LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +------------------- + +Implementations of the MD4 algorithm are subject to the following +notice: + + Copyright |copy| 1990, RSA Data Security, Inc. All rights reserved. + + License to copy and use this software is granted provided that + it is identified as the "RSA Data Security, Inc. MD4 Message + Digest Algorithm" in all material mentioning or referencing this + software or this function. + + License is also granted to make and use derivative works + provided that such works are identified as "derived from the RSA + Data Security, Inc. MD4 Message Digest Algorithm" in all + material mentioning or referencing the derived work. + + RSA Data Security, Inc. makes no representations concerning + either the merchantability of this software or the suitability + of this software for any particular purpose. It is provided "as + is" without express or implied warranty of any kind. + + These notices must be retained in any copies of any part of this + documentation and/or software. + +------------------- + +Implementations of the MD5 algorithm are subject to the following +notice: + + Copyright |copy| 1990, RSA Data Security, Inc. All rights reserved. + + License to copy and use this software is granted provided that + it is identified as the "RSA Data Security, Inc. MD5 Message- + Digest Algorithm" in all material mentioning or referencing this + software or this function. + + License is also granted to make and use derivative works + provided that such works are identified as "derived from the RSA + Data Security, Inc. MD5 Message-Digest Algorithm" in all + material mentioning or referencing the derived work. + + RSA Data Security, Inc. makes no representations concerning + either the merchantability of this software or the suitability + of this software for any particular purpose. It is provided "as + is" without express or implied warranty of any kind. + + These notices must be retained in any copies of any part of this + documentation and/or software. + +------------------- + +The following notice applies to ``src/lib/crypto/crypto_tests/t_mddriver.c``: + + Copyright |copy| 1990-2, RSA Data Security, Inc. Created 1990. All + rights reserved. + + RSA Data Security, Inc. makes no representations concerning either + the merchantability of this software or the suitability of this + software for any particular purpose. It is provided "as is" + without express or implied warranty of any kind. + + These notices must be retained in any copies of any part of this + documentation and/or software. + +------------------- + +Portions of ``src/lib/krb5`` are subject to the following notice: + + | Copyright |copy| 1994 CyberSAFE Corporation. + | Copyright 1990,1991,2007,2008 by the Massachusetts + Institute of Technology. + | All Rights Reserved. + + Export of this software from the United States of America may + require a specific license from the United States Government. + It is the responsibility of any person or organization contemplating + export to obtain such a license before exporting. + + WITHIN THAT CONSTRAINT, permission to use, copy, modify, and + distribute this software and its documentation for any purpose and + without fee is hereby granted, provided that the above copyright + notice appear in all copies and that both that copyright notice and + this permission notice appear in supporting documentation, and that + the name of M.I.T. not be used in advertising or publicity pertaining + to distribution of the software without specific, written prior + permission. Furthermore if you modify this software you must label + your software as modified software and not distribute it in such a + fashion that it might be confused with the original M.I.T. software. + Neither M.I.T., the Open Computing Security Group, nor + CyberSAFE Corporation make any representations about the suitability of + this software for any purpose. It is provided "as is" without express + or implied warranty. + +------------------- + +Portions contributed by PADL Software are subject to the following +license: + + Copyright (c) 2011, PADL Software Pty Ltd. + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + + 3. Neither the name of PADL Software nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY PADL SOFTWARE AND CONTRIBUTORS "AS IS" AND + ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + ARE DISCLAIMED. IN NO EVENT SHALL PADL SOFTWARE OR CONTRIBUTORS BE LIABLE + FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + SUCH DAMAGE. + +------------------- + +The bundled libev source code is subject to the following license: + + All files in libev are Copyright (C)2007,2008,2009 Marc Alexander Lehmann. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are + met: + + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + Alternatively, the contents of this package may be used under the terms + of the GNU General Public License ("GPL") version 2 or any later version, + in which case the provisions of the GPL are applicable instead of the + above. If you wish to allow the use of your version of this package only + under the terms of the GPL and not to allow others to use your version of + this file under the BSD license, indicate your decision by deleting the + provisions above and replace them with the notice and other provisions + required by the GPL in this and the other files of this package. If you do + not delete the provisions above, a recipient may use your version of this + file under either the BSD or the GPL. diff --git a/doc/plugindev/ccselect.rst b/doc/plugindev/ccselect.rst new file mode 100644 index 000000000..00133d944 --- /dev/null +++ b/doc/plugindev/ccselect.rst @@ -0,0 +1,26 @@ +Credential cache selection interface (ccselect) +=============================================== + +The ccselect interface allows modules to control how credential caches +are chosen when a GSSAPI client contacts a service. For a detailed +description of the ccselect interface, see the header file +````. + +The primary ccselect method is **choose**, which accepts a server +principal as input and returns a ccache and/or principal name as +output. A module can use the krb5_cccol APIs to iterate over the +cache collection in order to find an appropriate ccache to use. + +.. TODO: add reference to the admin guide for ccaches and cache + collections when we have appropriate sections. + +A module can create and destroy per-library-context state objects by +implementing the **init** and **fini** methods. State objects have +the type krb5_ccselect_moddata, which is an abstract pointer type. A +module should typically cast this to an internal type for the state +object. + +A module can have one of two priorities, "authoritative" or +"heuristic". Results from authoritative modules, if any are +available, will take priority over results from heuristic modules. A +module communicates its priority as a result of the **init** method. diff --git a/doc/plugindev/clpreauth.rst b/doc/plugindev/clpreauth.rst new file mode 100644 index 000000000..68e56aa5f --- /dev/null +++ b/doc/plugindev/clpreauth.rst @@ -0,0 +1,53 @@ +Client preauthentication interface (clpreauth) +============================================== + +During an initial ticket request, a KDC may ask a client to prove its +knowledge of the password before issuing an encrypted ticket, or to +use credentials other than a password. This process is called +preauthentication, and is described in :rfc:`4120` and :rfc:`6113`. +The clpreauth interface allows the addition of client support for +preauthentication mechanisms beyond those included in the core MIT +krb5 code base. For a detailed description of the clpreauth +interface, see the header file ````. + +A clpreauth module is generally responsible for: + +* Supplying a list of preauth type numbers used by the module in the + **pa_type_list** field of the vtable structure. + +* Indicating what kind of preauthentication mechanism it implements, + with the **flags** method. In the most common case, this method + just returns ``PA_REAL``, indicating that it implements a normal + preauthentication type. + +* Examining the padata information included in the preauth_required + error and producing padata values for the next AS request. This is + done with the **process** method. + +* Examining the padata information included in a successful ticket + reply, possibly verifying the KDC identity and computing a reply + key. This is also done with the **process** method. + +* For preauthentication types which support it, recovering from errors + by examining the error data from the KDC and producing a padata + value for another AS request. This is done with the **tryagain** + method. + +* Receiving option information (supplied by ``kinit -X`` or by an + application), with the **gic_opts** method. + +A clpreauth module can create and destroy per-library-context and +per-request state objects by implementing the **init**, **fini**, +**request_init**, and **request_fini** methods. Per-context state +objects have the type krb5_clpreauth_moddata, and per-request state +objects have the type krb5_clpreauth_modreq. These are abstract +pointer types; a module should typically cast these to internal +types for the state objects. + +The **process** and **tryagain** methods have access to a callback +function and handle (called a "rock") which can be used to get +additional information about the current request, including the +expected enctype of the AS reply, the FAST armor key, and the client +long-term key (prompting for the user password if necessary). A +callback can also be used to replace the AS reply key if the +preauthentication mechanism computes one. diff --git a/doc/plugindev/general.rst b/doc/plugindev/general.rst new file mode 100644 index 000000000..dff680762 --- /dev/null +++ b/doc/plugindev/general.rst @@ -0,0 +1,98 @@ +General plugin concepts +======================= + +A krb5 dynamic plugin module is a Unix shared object or Windows DLL. +Typically, the source code for a dynamic plugin module should live in +its own project with a build system using automake_ and libtool_, or +tools with similar functionality. + +A plugin module must define a specific symbol name, which depends on +the pluggable interface and module name. For most pluggable +interfaces, the exported symbol is a function named +``INTERFACE_MODULE_initvt``, where *INTERFACE* is the name of the +pluggable interface and *MODULE* is the name of the module. For these +interfaces, it is possible for one shared object or DLL to implement +multiple plugin modules, either for the same pluggable interface or +for different ones. For example, a shared object could implement both +KDC and client preauthentication mechanisms, by exporting functions +named ``kdcpreauth_mymech_initvt`` and ``clpreauth_mymech_initvt``. + +.. note: The profile, locate, and GSSAPI mechglue pluggable interfaces + follow different conventions. See the documentation for + those interfaces for details. The remainder of this section + applies to pluggable interfaces which use the standard + conventions. + +A plugin module implementation should include the header file +````, where *INTERFACE* is the name of the +pluggable interface. For instance, a ccselect plugin module +implementation should use ``#include ``. + +.. note: clpreauth and kdcpreauth module implementations should + include . + +initvt functions have the following prototype:: + + krb5_error_code interface_modname_initvt(krb5_context context, + int maj_ver, int min_ver, + krb5_plugin_vtable vtable); + +and should do the following: + +1. Check that the supplied maj_ver argument is supported by the + module. If it is not supported, the function should return + KRB5_PLUGIN_VER_NOTSUPP. + +2. Cast the supplied vtable pointer to the structure type + corresponding to the major version, as documented in the pluggable + interface header file. + +3. Fill in the structure fields with pointers to method functions and + static data, stopping at the field indicated by the supplied minor + version. Fields for unimplemented optional methods can be left + alone; it is not necessary to initialize them to NULL. + +In most cases, the context argument will not be used. The initvt +function should not allocate memory; think of it as a glorified +structure initializer. Each pluggable interface defines methods for +allocating and freeing module state if doing so is necessary for the +interface. + +Pluggable interfaces typically include a **name** field in the vtable +structure, which should be filled in with a pointer to a string +literal containing the module name. + +Here is an example of what an initvt function might look like for a +fictional pluggable interface named fences, for a module named +"wicker":: + + krb5_error_code + fences_wicker_initvt(krb5_context context, int maj_ver, + int min_ver, krb5_plugin_vtable vtable) + { + krb5_ccselect_vtable vt; + + if (maj_ver == 1) { + krb5_fences_vtable vt = (krb5_fences_vtable)vtable; + vt->name = "wicker"; + vt->slats = wicker_slats; + vt->braces = wicker_braces; + } else if (maj_ver == 2) { + krb5_fences_vtable_v2 vt = (krb5_fences_vtable_v2)vtable; + vt->name = "wicker"; + vt->material = wicker_material; + vt->construction = wicker_construction; + if (min_ver < 2) + return 0; + vt->footing = wicker_footing; + if (min_ver < 3) + return 0; + vt->appearance = wicker_appearance; + } else { + return KRB5_PLUGIN_VER_NOTSUPP; + } + return 0; + } + +.. _automake: http://www.gnu.org/software/automake/ +.. _libtool: http://www.gnu.org/software/libtool/ diff --git a/doc/plugindev/index.rst b/doc/plugindev/index.rst new file mode 100644 index 000000000..e913810bb --- /dev/null +++ b/doc/plugindev/index.rst @@ -0,0 +1,32 @@ +For plugin module developers +============================ + +Kerberos plugin modules allow increased control over MIT krb5 library +and server behavior. This guide describes how to create dynamic +plugin modules and the currently available pluggable interfaces. + +See :ref:`plugin_config` for information on how to register dynamic +plugin modules and how to enable and disable modules via +:ref:`krb5.conf(5)`. + +.. TODO: update the above reference when we have a free-form section + in the admin guide about plugin configuration + + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + general.rst + clpreauth.rst + kdcpreauth.rst + ccselect.rst + pwqual.rst + kadm5_hook.rst + locate.rst + profile.rst + internal.rst + +.. TODO: GSSAPI mechanism plugins diff --git a/doc/plugindev/internal.rst b/doc/plugindev/internal.rst new file mode 100644 index 000000000..99e30bb79 --- /dev/null +++ b/doc/plugindev/internal.rst @@ -0,0 +1,32 @@ +Internal pluggable interfaces +============================= + +Following are brief discussions of pluggable interfaces which have not +yet been made public. These interfaces are functional, but the +interfaces are likely to change in incompatible ways from release to +release. In some cases, it may be necessary to copy header files from +the krb5 source tree to use an internal interface. Use these with +care, and expect to need to update your modules for each new release +of MIT krb5. + + +Kerberos database interface (KDB) +--------------------------------- + +A KDB module implements a database back end for KDC principal and +policy information, and can also control many aspects of KDC behavior. +For a full description of the interface, see the header file +````. + +The KDB pluggable interface is often referred to as the DAL (Database +Access Layer). + + +Authorization data interface (authdata) +--------------------------------------- + +The authdata interface allows a module to provide (from the KDC) or +consume (in application servers) authorization data of types beyond +those handled by the core MIT krb5 code base. The interface is +defined in the header file ````, which is not +installed by the build. diff --git a/doc/plugindev/kadm5_hook.rst b/doc/plugindev/kadm5_hook.rst new file mode 100644 index 000000000..01d330e8e --- /dev/null +++ b/doc/plugindev/kadm5_hook.rst @@ -0,0 +1,24 @@ +KADM5 hook interface (kadm5_hook) +================================= + +The kadm5_hook interface allows modules to perform actions when +changes are made to the Kerberos database through :ref:`kadmin(1)`. +For a detailed description of the kadm5_hook interface, see the header +file ````. + +The kadm5_hook interface has four primary methods: **chpass**, +**create**, **modify**, and **remove**. Each of these methods is +called twice when the corresponding administrative action takes place, +once before the action is committed and once afterwards. A module can +prevent the action from taking place by returning an error code during +the pre-commit stage. + +A module can create and destroy per-process state objects by +implementing the **init** and **fini** methods. State objects have +the type kadm5_hook_modinfo, which is an abstract pointer type. A +module should typically cast this to an internal type for the state +object. + +Because the kadm5_hook interface is tied closely to the kadmin +interface (which is explicitly unstable), it may not remain as stable +across versions as other public pluggable interfaces. diff --git a/doc/plugindev/kdcpreauth.rst b/doc/plugindev/kdcpreauth.rst new file mode 100644 index 000000000..e6ba9e531 --- /dev/null +++ b/doc/plugindev/kdcpreauth.rst @@ -0,0 +1,61 @@ +KDC preauthentication interface (kdcpreauth) +============================================ + +The kdcpreauth interface allows the addition of KDC support for +preauthentication mechanisms beyond those included in the core MIT +krb5 code base. For a detailed description of the kdcpreauth +interface, see the header file ````. + +A kdcpreauth module is generally responsible for: + +* Supplying a list of preauth type numbers used by the module in the + **pa_type_list** field of the vtable structure. + +* Indicating what kind of preauthentication mechanism it implements, + with the **flags** method. If the mechanism computes a new reply + key, it must specify the ``PA_REPLACES_KEY`` flag. If the mechanism + is generally only used with hardware tokens, the ``PA_HARDWARE`` + flag allows the mechanism to work with principals which have the + **requires_hwauth** flag set. + +* Producing a padata value to be sent with a preauth_required error, + with the **edata** method. + +* Examining a padata value sent by a client and verifying that it + proves knowledge of the appropriate client credential information. + This is done with the **verify** method. + +* Producing a padata response value for the client, and possibly + computing a reply key. This is done with the **return_padata** + method. + +A module can create and destroy per-KDC state objects by implementing +the **init** and **fini** methods. Per-KDC state objects have the +type krb5_kdcpreauth_moddata, which is an abstract pointer types. A +module should typically cast this to an internal type for the state +object. + +A module can create a per-request state object by returning one in the +**verify** method, receiving it in the **return_padata** method, and +destroying it in the **free_modreq** method. Note that these state +objects only apply to the processing of a single AS request packet, +not to an entire authentication exchange (since an authentication +exchange may remain unfinished by the client or may involve multiple +different KDC hosts). Per-request state objects have the type +krb5_kdcpreauth_modreq, which is an abstract pointer type. + +The **edata**, **verify**, and **return_padata** methods have access +to a callback function and handle (called a "rock") which can be used +to get additional information about the current request, including the +maximum allowable clock skew, the client's long-term keys, the +DER-encoded request body, the FAST armor key, string attributes on the +client's database entry, and the client's database entry itself. + +The **edata** and **verify** methods can be implemented +asynchronously. Because of this, they do not return values directly +to the caller, but must instead invoke responder functions with their +results. A synchronous implementation can invoke the responder +function immediately. An asynchronous implementation can use the +callback to get an event context for use with the libverto_ API. + +.. _libverto: https://fedorahosted.org/libverto/ diff --git a/doc/plugindev/locate.rst b/doc/plugindev/locate.rst new file mode 100644 index 000000000..fca6a4da7 --- /dev/null +++ b/doc/plugindev/locate.rst @@ -0,0 +1,32 @@ +Server location interface (locate) +================================== + +The locate interface allows modules to control how KDCs and similar +services are located by clients. For a detailed description of the +ccselect interface, see the header file ````. + +.. note: The locate interface does not follow the normal conventions + for MIT krb5 pluggable interfaces, because it was made public + before those conventions were established. + +A locate module exports a structure object of type +krb5plugin_service_locate_ftable, with the name ``service_locator``. +The structure contains a minor version and pointers to the module's +methods. + +The primary locate method is **lookup**, which accepts a service type, +realm name, desired socket type, and desired address family (which +will be AF_UNSPEC if no specific address family is desired). The +method should invoke the callback function once for each server +address it wants to return, passing a socket type (SOCK_STREAM for TCP +or SOCK_DGRAM for UDP) and socket address. The **lookup** method +should return 0 if it has authoritatively determined the server +addresses for the realm, KRB5_PLUGIN_NO_HANDLE if it wants to let +other location mechanisms determine the server addresses, or another +code if it experienced a failure which should abort the location +process. + +A module can create and destroy per-library-context state objects by +implementing the **init** and **fini** methods. State objects have +the type void \*, and should be cast to an internal type for the state +object. diff --git a/doc/plugindev/profile.rst b/doc/plugindev/profile.rst new file mode 100644 index 000000000..671d4c18c --- /dev/null +++ b/doc/plugindev/profile.rst @@ -0,0 +1,92 @@ +Configuration interface (profile) +================================= + +The profile interface allows a module to control how krb5 +configuration information is obtained by the Kerberos library and +applications. For a detailed description of the profile interface, +see the header file ````. + +.. note:: The profile interface does not follow the normal conventions + for MIT krb5 pluggable interfaces, because it is part of a + lower-level component of the krb5 library. + +As with other types of plugin modules, a profile module is a Unix +shared object or Windows DLL, built separately from the krb5 tree. +The krb5 library will dynamically load and use a profile plugin module +if it reads a ``module`` directive at the beginning of krb5.conf, as +described in :ref:`profile_plugin_config`. + +A profile module exports a function named ``profile_module_init`` +matching the signature of the profile_module_init_fn type. This +function accepts a residual string, which may be used to help locate +the configuration source. The function fills in a vtable and may also +create a per-profile state object. If the module uses state objects, +it should implement the **copy** and **cleanup** methods to manage +them. + +A basic read-only profile module need only implement the +**get_values** and **free_values** methods. The **get_values** method +accepts a null-terminated list of C string names (e.g., an array +containing "libdefaults", "clockskew", and NULL for the **clockskew** +variable in the :ref:`libdefaults` section) and returns a +null-terminated list of values, which will be cleaned up with the +**free_values** method when the caller is done with them. + +Iterable profile modules must also define the **iterator_create**, +**iterator**, **iterator_free**, and **free_string** methods. The +core krb5 code does not require profiles to be iterable, but some +applications may iterate over the krb5 profile object in order to +present configuration interfaces. + +Writable profile modules must also define the **writable**, +**modified**, **update_relation**, **rename_section**, +**add_relation**, and **flush** methods. The core krb5 code does not +require profiles to be writable, but some applications may write to +the krb5 profile in order to present configuration interfaces. + +The following is an example of a very basic read-only profile module +which returns a hardcoded value for the **default_realm** variable in +:ref:`libdefaults`, and provides no other configuration information. +(For conciseness, the example omits code for checking the return +values of malloc and strdup.) :: + + #include + #include + #include + + static long + get_values(void *cbdata, const char *const *names, char ***values) + { + if (names[0] != NULL && strcmp(names[0], "libdefaults") == 0 && + names[1] != NULL && strcmp(names[1], "default_realm") == 0) { + *values = malloc(2 * sizeof(char *)); + (*values)[0] = strdup("ATHENA.MIT.EDU"); + (*values)[1] = NULL; + return 0; + } + return PROF_NO_RELATION; + } + + static void + free_values(void *cbdata, char **values) + { + char **v; + + for (v = values; *v; v++) + free(*v); + free(values); + } + + long + profile_module_init(const char *residual, struct profile_vtable *vtable, + void **cb_ret); + + long + profile_module_init(const char *residual, struct profile_vtable *vtable, + void **cb_ret) + { + *cb_ret = NULL; + vtable->get_values = get_values; + vtable->free_values = free_values; + return 0; + } diff --git a/doc/plugindev/pwqual.rst b/doc/plugindev/pwqual.rst new file mode 100644 index 000000000..a981e7903 --- /dev/null +++ b/doc/plugindev/pwqual.rst @@ -0,0 +1,23 @@ +Password quality interface (pwqual) +=================================== + +The pwqual interface allows modules to control what passwords are +allowed when a user changes passwords. For a detailed description of +the pwqual interface, see the header file ````. + +The primary pwqual method is **check**, which receives a password as +input and returns success (0) or a ``KADM5_PASS_Q_`` failure code +depending on whether the password is allowed. The **check** method +also receives the principal name and the name of the principal's +password policy as input; although there is no stable interface for +the module to obtain the fields of the password policy, it can define +its own configuration or data store based on the policy name. + +A module can create and destroy per-process state objects by +implementing the **open** and **close** methods. State objects have +the type krb5_pwqual_moddata, which is an abstract pointer type. A +module should typically cast this to an internal type for the state +object. The **open** method also receives the name of the realm's +dictionary file (as configured by the **dict_file** variable in the +:ref:`kdc_realms` section of :ref:`kdc.conf(5)`) if it wishes to use +it. diff --git a/doc/relay/build_this.rst b/doc/relay/build_this.rst new file mode 100644 index 000000000..f51d1047d --- /dev/null +++ b/doc/relay/build_this.rst @@ -0,0 +1,81 @@ +How to build this documentation from the source +=============================================== + +Pre-requisites for the simple build, or to update man pages: + +* Sphinx 1.0.4 or higher (See http://sphinx.pocoo.org) with “autodoc” + extension installed. + +Additional prerequisites to include the API reference based on Doxygen +markup: + +* python 2.5 with the Cheetah, lxml, and xml modules +* Doxygen + + +Simple build without API reference +---------------------------------- + +To test simple changes to the RST sources, you can build the +documentation without the Doxygen reference by running, from the doc +directory:: + + sphinx-build rst_source test_html + +You will see a number of warnings about missing files. This is +expected. + + +Updating man pages +------------------ + +Man pages are generated from the RST sources and checked into the +``src/man`` directory of the repository. This allows man pages to be +installed without requiring Sphinx when using a source checkout. To +regenerate these files, run ``make rstman`` from the man subdirectory +of a configured build tree. You can also do this from an unconfigured +source tree with:: + + cd src/man + make -f Makefile.in top_srcdir=.. srcdir=. rstman + make clean + +As with the simple build, it is normal to see warnings about missing +files when rebuilding the man pages. + + +Building for a release tarball or web site +------------------------------------------ + +To generate documentation in HTML format, run ``make rsthtml`` in the +``doc`` subdirectory of a configured build tree (the build directory +corresponding to ``src/doc``, not the top-level ``doc`` directory). +The output will be placed in the top-level ``doc/rst_html`` directory. +This build will include the API reference generated from Doxygen +markup in the source tree. + +Documentation generated this way will use symbolic names for paths +(like ``BINDIR`` for the directory containing user programs), with the +symbolic names being links to a table showing typical values for those +paths. + +You can also do this from an unconfigured source tree with:: + + cd src/doc + make -f Makefile.in top_srcdir=.. PYTHON=python rsthml + make -f Makefile.in clean + + +Building for an OS package or site documentation +------------------------------------------------ + +To generate documentation specific to a build of MIT krb5 as you have +configured it, run ``make substhtml`` in the ``doc`` subdirectory of a +configured build tree (the build directory corresponding to +``src/doc``, not the top-level ``doc`` directory). The output will be +placed in the ``rst_html_subst`` subdirectory of that build directory. +This build will include the API reference. + +Documentation generated this way will use concrete paths (like +``/usr/local/bin`` for the directory containing user programs, for a +default custom build). diff --git a/doc/relay/index.rst b/doc/relay/index.rst new file mode 100644 index 000000000..45e3e1f14 --- /dev/null +++ b/doc/relay/index.rst @@ -0,0 +1,9 @@ +About this project +================== + +.. toctree:: + :maxdepth: 1 + + philosophy.rst + build_this.rst + diff --git a/doc/relay/philosophy.rst b/doc/relay/philosophy.rst new file mode 100644 index 000000000..2771f84a8 --- /dev/null +++ b/doc/relay/philosophy.rst @@ -0,0 +1,28 @@ +Kerberos Documentation Relay +============================ + +Philosophy +---------- + +- The documentation must be useful; + +- The documentation must be correct; + +- The documentation must be detailed, but optimized. No verbose mode; + +- The documentation should be built incrementally; + +- The documentation should be easy to maintain; + +- The documentation should be examined to identify the approaches + that do not work; + +Feedback and Comments +--------------------- + +At the moment the comments should be sent via email to +krb5-bugs@mit.edu. + +The html version of this documentation has a "FEEDBACK" link +(at the bottom of every page) to the krb5-bugs@mit.edu email address +with the pre-constructed subject line. diff --git a/doc/resources.rst b/doc/resources.rst new file mode 100644 index 000000000..74e93003b --- /dev/null +++ b/doc/resources.rst @@ -0,0 +1,55 @@ +Resources +========= + +Mailing lists +------------- + +* kerberos@mit.edu is a community resource for discussion and + questions about MIT krb5 and other Kerberos implementations. To + subscribe to the list, please follow the instructions at + http://mailman.mit.edu/mailman/listinfo/kerberos. +* krbdev@mit.edu is the primary list for developers of MIT Kerberos. + To subscribe to the list, please follow the instructions at + http://mailman.mit.edu/mailman/listinfo/krbdev. +* krb5-bugs@mit.edu is notified when a ticket is created or updated. + This list helps track bugs and feature requests. + In addition, this list is used to track documentation criticism + and recommendations for improvements. +* krbcore@mit.edu is a private list for the MIT krb5 core team. Send + mail to this list if you need to contact the core team. +* krbcore-security@mit.edu is the point of contact for security problems + with MIT Kerberos. Please use PGP-encrypted mail to report possible + vulnerabilities to this list. + + +IRC channels +------------ + +The main IRC channel for MIT Kerberos development is #krbdev on +irc.freenode.net. + +There is a separate channel, `#kerberos`, for general Kerberos +discussion and support. + +For more information about freenode, see http://freenode.net/. + +The `#krbdev` channel is logged at +http://colabti.org/irclogger/irclogger_logs/krbdev using the +colabti.org service, which generously offers IRC logging +to Free / Open Source projects. + +The `#krbdev` channel was previously logged by lopbot, courtesy +of Brandon Allbery. These logs are no longer readily available online. +Despite the possible existence of logging, please summarize important +conversations to more permanent places, such as an appropriate +mailing list or wiki page. + + +Archives +-------- + +* The archive http://mailman.mit.edu/pipermail/kerberos/ contains past + posting from `kerberos@mit.edu` list. + +* The http://mailman.mit.edu/pipermail/krbdev/ contains past + posting from `krbdev@mit.edu` list. diff --git a/doc/rst_source/README b/doc/rst_source/README deleted file mode 100644 index 8bb1c47cc..000000000 --- a/doc/rst_source/README +++ /dev/null @@ -1,69 +0,0 @@ -HTML -==== - -To build the documentation as HTML pages run: - -sphinx-build source_dir destination_dir - -where -source_dir is the source directory which includes configuration file conf.py and all source files; -destination_dir is the directory for the built documentation. - -Once completed, the newly generated HTML documentation can be viewed from the browser by pointing to destination_dir/index.html - - -MAN PAGES -========= - -Similarly, to build the documentation as man pages run: - -sphinx-build -b man source_dir destination_dir - -The list of manual pages to be built should be constructed under man_pages section on conf.py - - -CONVENTIONS -=========== - -We use the following conventions: - -* Use four-space indentation where indentation levels are arbitrary. - Do not use tabs anywhere. Avoid trailing whitespace at the end of - lines or files. - -* Fill lines to 70 columns (the emacs default) where lines can be - wrapped. - -* For section headers, use === underlines for page titles, --- for - sections, ~~~ for subsections, and ### for sub-subsections. Make - underlines exactly as long as titles. Do not include trailing - punctuation in section headers. Do not capitalize section headers - (except for the first word) except in source files intended to - generate man pages. - -* For bullet lists, use * for top-level bullets and - for sub-bullets. - Do not indent bullet or enumerated lists relative to the surrounding - text. - -* Use italics (*word*) for words representing variables or parameters. - Use boldface (**word**) for command options, subcommands of programs - like kadmin, and krb5.conf/kdc.conf parameter names. Use literal - text (``text``) for examples and multi-component pathnames. For - command names, single-component filenames, and krb5.conf/kdc.conf - section names, use references (like :ref:`kadmin(1)`) if introducing - them, or just use them unadorned otherwise. - -* In man pages for commands with subcommands, make a subsection for - each subcommand. Start the subcommand with an indented synopsis, - then follow with non-indented text describing the subcommand and its - options. See kadmin_local.rst for an example. - -* In man page synopses, put a newline in the RST source before each - option. Put all parts of the synopsis at the same indentation - level. Ideally we would want a hanging indent to the width of the - command or subcommand name, but RST doesn't support that. Use - boldface for literal text in the synopsis, italics for variable - text, and unadorned text for syntax symbols (such as square brackets - to indicate optional parameters). If immediately following one kind - of inline markup with another or putting inline markup next to - punctuation, you may need to use "\ " as a dummy separator. diff --git a/doc/rst_source/_static/kerb.css b/doc/rst_source/_static/kerb.css deleted file mode 100644 index f28349662..000000000 --- a/doc/rst_source/_static/kerb.css +++ /dev/null @@ -1,150 +0,0 @@ -/* - * kerb.css - * ~~~~~~~~~~~ - * - * Sphinx stylesheet -- modification to agogo theme. - * - */ -div.body { - padding-right: .5em; - text-align: left; - overflow-x: hidden; -} - -/* Page layout */ - -div.header, div.content, div.footer { - margin-left: auto; - margin-right: auto; -} - -div.header-wrapper { - background: white; - border-bottom: 3px solid #2e3436; - border-top: 13px solid #59121e; -} - -/* Header */ - -div.header { - padding-top: 10px; - padding-bottom: 10px; -} - -div.header h1 { - font-family: "Georgia", "Times New Roman", serif, black; - font-weight: normal; -} - -div.header div.right a { - color: #fcaf3e; - letter-spacing: .1em; - text-transform: lowercase; - float: right; -} - -/* Content */ - -div.document { - width: 80%; - float: left; - margin: 0; - background-color: white; - padding-top: 20px; - padding-bottom: 20px; -} - -div.document div.section h1 { - margin-bottom: 20px; - padding: 1px; - line-height: 130%; -} - -div.document div.section dl { - margin-top: 15px; - margin-bottom: 5px; - padding: 1px; - text-align: left; -} - -/* Sidebar */ - -div.sidebar { - float: right; - font-size: .9em; - width: 20%; - margin: 0; - padding: 0; - background-color: white; -} - -div.sidebar ul { - list-style-type: none; - margin-left: .5em; -} - -div.sidebar li.toctree-l1 a { - margin-left: .5em; -} - -div.sidebar li.toctree-l2 a { - margin-left: .5em; -} - -div.sidebar li.toctree-l3 a { - margin-left: .5em; -} - -div.sidebar li.toctree-l2.current a { - border-right: 2px solid #fcaf3e !important; -} - -div.sidebar li.toctree-l3.current a { - font-weight: bold; -} - -div.sidebar li.toctree-l4 a { - display: none; -} - -/* Other body styles */ - -dt:target, .highlighted { - background-color: #c1c1c1; -} - -/* Code displays */ - -pre { - overflow: auto; - overflow-y: hidden; -} - -td.linenos pre { - padding: 5px 0px; - border: 0; - background-color: transparent; - color: #aaa; -} - -/* ordered lists */ - -ol.arabic { - list-style: decimal; -} - -ol.loweralpha { - list-style: lower-alpha; -} - -ol.upperalpha { - list-style: upper-alpha; -} - -ol.lowerroman { - list-style-type: lower-roman; -} - -ol.upperroman { - list-style-type: upper-roman; -} diff --git a/doc/rst_source/_templates/layout.html b/doc/rst_source/_templates/layout.html deleted file mode 100644 index 2cf03a18d..000000000 --- a/doc/rst_source/_templates/layout.html +++ /dev/null @@ -1,86 +0,0 @@ -{% extends "!layout.html" %} -{% set rellinks = [('search', 'Enter search criteria', 'C', 'Search')] + - rellinks + - [('index', 'Full Table of Contents', 'C', 'Contents')] %} -{% set css_files = css_files + ["_static/kerb.css"] %} - -{# Add a "feedback" button to the footer #} -{% macro feedback_rellinks() %} -
-
-
- {%- for rellink in rellinks|reverse %} - {{ rellink[3] }} - {{ reldelim2 }} - {%- endfor %} - {%- block rootrellink %} - feedback - {%- endblock %} -
-
-
-{%- endmacro %} - -{% block footer %} {{ feedback_rellinks() }}{% endblock %} - -{% block header %} -
-
- {% if logo %} - - {% endif %} - {% block headertitle %} -

{{ shorttitle|e }}

- {% endblock %} -
- {%- for rellink in rellinks|reverse %} - {{ rellink[3] }} - {{ reldelim2 }} - {%- endfor %} - feedback -
-

-
-{% endblock %} - -{%- block content %} -
-
- {%- block sidebar2 %} {%- endblock %} - {%- block sidebar1 %} -
-

{{ _('On this page') }}

- {{ toc }} -
-

{{ _('Table of contents') }}

- {{ toctree(collapse=true, maxdepth=-1, titles_only=true) }} -
-

Full Table of Contents -

-

{{ _('Search') }}

-
- - - - -
-
- {%- endblock %} -
- {%- block document %}{{ super() }}{%- endblock %} -
-
-
-
-{% endblock %} diff --git a/doc/rst_source/conf.py b/doc/rst_source/conf.py deleted file mode 100644 index f5edecac1..000000000 --- a/doc/rst_source/conf.py +++ /dev/null @@ -1,280 +0,0 @@ -# -*- coding: utf-8 -*- -# -# MIT Kerberos documentation build configuration file, created by -# sphinx-quickstart on Wed Oct 13 09:14:03 2010. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -#extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.doxylink'] -extensions = ['sphinx.ext.autodoc'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'MIT Kerberos' -copyright = u'2012, MIT' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '0.0.1' -# The full version, including alpha/beta/rc tags. -release = '0.0.1' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -today = ' ' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = [] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# html_theme = 'default' -html_theme = 'agogo' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -html_theme_options = { "linkcolor": "#a63019", "footerbg": "#59121e", - "bgcolor": "#59121e", "documentwidth": "900px", - "pagewidth": "960px", "sidebarwidth": "40px" } - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -html_title = "MIT Kerberos Documentation" - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = "" - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -html_split_index = True - -# If true, links to the reST sources are added to the pages. -html_show_sourcelink = False - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g., ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'MIT Kerberos' - -pointsize = '10pt' - -# -- Options for LaTeX output -------------------------------------------------- - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'MIT Kerberos.tex', u'MIT Kerberos Documentation', - u'MIT', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - -if 'mansubs' in tags: - bindir = '``@BINDIR@``' - sbindir = '``@SBINDIR@``' - libdir = '``@LIBDIR@``' - localstatedir = '``@LOCALSTATEDIR@``' - sysconfdir = '``@SYSCONFDIR@``' - ccache = '``@CCNAME@``' - keytab = '``@KTNAME@``' - ckeytab = '``@CKTNAME@``' -elif 'pathsubs' in tags: - # Read configured paths from a file produced by the build system. - execfile('paths.py') -else: - bindir = ':ref:`BINDIR `' - sbindir = ':ref:`SBINDIR `' - libdir = ':ref:`LIBDIR `' - localstatedir = ':ref:`LOCALSTATEDIR `' - sysconfdir = ':ref:`SYSCONFDIR `' - ccache = ':ref:`DEFCCNAME `' - keytab = ':ref:`DEFKTNAME `' - ckeytab = ':ref:`DEFCKTNAME `' - -rst_epilog = '\n' -rst_epilog += '.. |bindir| replace:: %s\n' % bindir -rst_epilog += '.. |sbindir| replace:: %s\n' % sbindir -rst_epilog += '.. |libdir| replace:: %s\n' % libdir -rst_epilog += '.. |kdcdir| replace:: %s\\ ``/krb5kdc``\n' % localstatedir -rst_epilog += '.. |sysconfdir| replace:: %s\n' % sysconfdir -rst_epilog += '.. |ccache| replace:: %s\n' % ccache -rst_epilog += '.. |keytab| replace:: %s\n' % keytab -rst_epilog += '.. |ckeytab| replace:: %s\n' % ckeytab -rst_epilog += ''' -.. |krb5conf| replace:: ``/etc/krb5.conf`` -.. |defkeysalts| replace:: ``aes256-cts-hmac-sha1-96:normal aes128-cts-hmac-sha1-96:normal des3-cbc-sha1:normal arcfour-hmac-md5:normal`` -.. |defetypes| replace:: ``aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96 des3-cbc-sha1 arcfour-hmac-md5 des-cbc-crc des-cbc-md5 des-cbc-md4`` -.. |defmkey| replace:: ``aes256-cts-hmac-sha1-96`` -''' - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('krb_users/user_commands/kinit', 'kinit', u'obtain and cache Kerberos ticket-granting ticket', [u'MIT'], 1), - ('krb_users/user_commands/klist', 'klist', u'list cached Kerberos tickets', [u'MIT'], 1), - ('krb_users/user_commands/kdestroy', 'kdestroy', u'destroy Kerberos tickets', [u'MIT'], 1), - ('krb_users/user_commands/kswitch', 'kswitch', u'switch primary ticket cache', [u'MIT'], 1), - ('krb_users/user_commands/kpasswd', 'kpasswd', u'change a user\'s Kerberos password', [u'MIT'], 1), - ('krb_users/user_commands/kvno', 'kvno', u'print key version numbers of Kerberos principals', [u'MIT'], 1), - ('krb_users/user_commands/ksu', 'ksu', u'Kerberized super-user', [u'MIT'], 1), - ('krb_users/user_config/k5login', 'k5login', u'Kerberos V5 acl file for host access', [u'MIT'], 5), - ('krb_users/user_config/k5identity', 'k5identity', u'Kerberos V5 client principal selection rules', [u'MIT'], 5), - ('krb_admins/admin_commands/krb5kdc', 'krb5kdc', u'Kerberos V5 KDC', [u'MIT'], 8), - ('krb_admins/admin_commands/kadmin_local', 'kadmin', u'Kerberos V5 database administration program', [u'MIT'], 1), - ('krb_admins/admin_commands/kprop', 'kprop', u'propagate a Kerberos V5 principal database to a slave server', [u'MIT'], 8), - ('krb_admins/admin_commands/kproplog', 'kproplog', u'display the contents of the Kerberos principal update log', [u'MIT'], 8), - ('krb_admins/admin_commands/kpropd', 'kpropd', u'Kerberos V5 slave KDC update server', [u'MIT'], 8), - ('krb_admins/admin_commands/kdb5_util', 'kdb5_util', u'Kerberos database maintenance utility', [u'MIT'], 8), - ('krb_admins/admin_commands/ktutil', 'ktutil', u'Kerberos keytab file maintenance utility', [u'MIT'], 1), - ('krb_admins/admin_commands/k5srvutil', 'k5srvutil', u'host key table (keytab) manipulation utility', [u'MIT'], 1), - ('krb_admins/admin_commands/kadmind', 'kadmind', u'KADM5 administration server', [u'MIT'], 8), - ('krb_admins/admin_commands/kdb5_ldap_util', 'kdb5_ldap_util', u'Kerberos configuration utility', [u'MIT'], 8), - ('krb_admins/conf_files/krb5_conf', 'krb5.conf', u'Kerberos configuration file', [u'MIT'], 5), - ('krb_admins/conf_files/kdc_conf', 'kdc.conf', u'Kerberos V5 KDC configuration file', [u'MIT'], 5), - ('krb_admins/conf_files/kadm5_acl', 'kadm5.acl', u'Kerberos ACL file', [u'MIT'], 5), - ('krb_users/user_commands/sclient', 'sclient', u'sample Kerberos version 5 client', [u'MIT'], 1), - ('krb_admins/admin_commands/sserver', 'sserver', u'sample Kerberos version 5 server', [u'MIT'], 8), -] diff --git a/doc/rst_source/index.rst b/doc/rst_source/index.rst deleted file mode 100644 index fb1012bc1..000000000 --- a/doc/rst_source/index.rst +++ /dev/null @@ -1,22 +0,0 @@ -MIT Kerberos Documentation -========================== - - -.. toctree:: - :maxdepth: 1 - - krb_users/index.rst - krb_admins/index.rst - krb_appldev/index.rst - krb_plugindev/index.rst - krb_build/index.rst - krb_basic/index.rst - mitK5features.rst - relay/index.rst - resources - - -.. _reference: - -:Release: |version| - diff --git a/doc/rst_source/krb_admins/admin_commands/index.rst b/doc/rst_source/krb_admins/admin_commands/index.rst deleted file mode 100644 index e8dc76524..000000000 --- a/doc/rst_source/krb_admins/admin_commands/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -Administration programs -======================== - -.. toctree:: - :maxdepth: 1 - - kadmin_local.rst - kadmind.rst - kdb5_util.rst - kdb5_ldap_util.rst - krb5kdc.rst - kprop.rst - kpropd.rst - kproplog.rst - ktutil.rst - k5srvutil.rst - sserver.rst diff --git a/doc/rst_source/krb_admins/admin_commands/k5srvutil.rst b/doc/rst_source/krb_admins/admin_commands/k5srvutil.rst deleted file mode 100644 index 493c17653..000000000 --- a/doc/rst_source/krb_admins/admin_commands/k5srvutil.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. _k5srvutil(1): - -k5srvutil -========= - -SYNOPSIS --------- - -**k5srvutil** *operation* -[**-i**] -[**-f** *filename*] - -DESCRIPTION ------------ - -k5srvutil allows an administrator to list or change keys currently in -a keytab or to add new keys to the keytab. - -*operation* must be one of the following: - -**list** - Lists the keys in a keytab showing version number and principal - name. - -**change** - Uses the kadmin protocol to update the keys in the Kerberos - database to new randomly-generated keys, and updates the keys in - the keytab to match. If a key's version number doesn't match the - version number stored in the Kerberos server's database, then the - operation will fail. Old keys are retained in the keytab so that - existing tickets continue to work. If the **-i** flag is given, - k5srvutil will prompt for confirmation before changing each key. - If the **-k** option is given, the old and new keys will be - displayed. - -**delold** - Deletes keys that are not the most recent version from the keytab. - This operation should be used some time after a change operation - to remove old keys, after existing tickets issued for the service - have expired. If the **-i** flag is given, then k5srvutil will - prompt for confirmation for each principal. - -**delete** - Deletes particular keys in the keytab, interactively prompting for - each key. - -In all cases, the default keytab is used unless this is overridden by -the **-f** option. - -k5srvutil uses the :ref:`kadmin(1)` program to edit the keytab in -place. - - -SEE ALSO --------- - -:ref:`kadmin(1)`, :ref:`ktutil(1)` diff --git a/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst b/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst deleted file mode 100644 index 396e25524..000000000 --- a/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst +++ /dev/null @@ -1,883 +0,0 @@ -.. _kadmin(1): - -kadmin -====== - -SYNOPSIS --------- - -.. _kadmin_synopsis: - -**kadmin** -[**-O**\|\ **-N**] -[**-r** *realm*] -[**-p** *principal*] -[**-q** *query*] -[[**-c** *cache_name*]\|[**-k** [**-t** *keytab*]]\|\ **-n**] -[**-w** *password*] -[**-s** *admin_server*\ [:*port*]] - -**kadmin.local** -[**-r** *realm*] -[**-p** *principal*] -[**-q** *query*] -[**-d** *dbname*] -[**-e** *enc*:*salt* ...] -[**-m**] -[**-x** *db_args*] - -.. _kadmin_synopsis_end: - - -DESCRIPTION ------------ - -kadmin and kadmin.local are command-line interfaces to the Kerberos V5 -administration system. They provide nearly identical functionalities; -the difference is that kadmin.local directly accesses the KDC -database, while kadmin performs operations using :ref:`kadmind(8)`. -Except as explicitly noted otherwise, this man page will use "kadmin" -to refer to both versions. kadmin provides for the maintenance of -Kerberos principals, password policies, and service key tables -(keytabs). - -The remote kadmin client uses Kerberos to authenticate to kadmind -using the service principal ``kadmin/ADMINHOST`` (where *ADMINHOST* is -the fully-qualified hostname of the admin server) or ``kadmin/admin``. -If the credentials cache contains a ticket for one of these -principals, and the **-c** credentials_cache option is specified, that -ticket is used to authenticate to kadmind. Otherwise, the **-p** and -**-k** options are used to specify the client Kerberos principal name -used to authenticate. Once kadmin has determined the principal name, -it requests a service ticket from the KDC, and uses that service -ticket to authenticate to kadmind. - -Since kadmin.local directly accesses the KDC database, it usually must -be run directly on the master KDC with sufficient permissions to read -the KDC database. If the KDC database uses the LDAP database module, -kadmin.local can be run on any host which can access the LDAP server. - - -OPTIONS -------- - -.. _kadmin_options: - -**-r** *realm* - Use *realm* as the default database realm. - -**-p** *principal* - Use *principal* to authenticate. Otherwise, kadmin will append - ``/admin`` to the primary principal name of the default ccache, - the value of the **USER** environment variable, or the username as - obtained with getpwuid, in order of preference. - -**-k** - Use a keytab to decrypt the KDC response instead of prompting for - a password. In this case, the default principal will be - ``host/hostname``. If there is no keytab specified with the - **-t** option, then the default keytab will be used. - -**-t** *keytab* - Use *keytab* to decrypt the KDC response. This can only be used - with the **-k** option. - -**-n** - Requests anonymous processing. Two types of anonymous principals - are supported. For fully anonymous Kerberos, configure PKINIT on - the KDC and configure **pkinit_anchors** in the client's - :ref:`krb5.conf(5)`. Then use the **-n** option with a principal - of the form ``@REALM`` (an empty principal name followed by the - at-sign and a realm name). If permitted by the KDC, an anonymous - ticket will be returned. A second form of anonymous tickets is - supported; these realm-exposed tickets hide the identity of the - client but not the client's realm. For this mode, use ``kinit - -n`` with a normal principal name. If supported by the KDC, the - principal (but not realm) will be replaced by the anonymous - principal. As of release 1.8, the MIT Kerberos KDC only supports - fully anonymous operation. - -**-c** *credentials_cache* - Use *credentials_cache* as the credentials cache. The - cache should contain a service ticket for the ``kadmin/ADMINHOST`` - (where *ADMINHOST* is the fully-qualified hostname of the admin - server) or ``kadmin/admin`` service; it can be acquired with the - :ref:`kinit(1)` program. If this option is not specified, kadmin - requests a new service ticket from the KDC, and stores it in its - own temporary ccache. - -**-w** *password* - Use *password* instead of prompting for one. Use this option with - care, as it may expose the password to other users on the system - via the process list. - -**-q** *query* - Perform the specified query and then exit. This can be useful for - writing scripts. - -**-d** *dbname* - Specifies the name of the KDC database. This option does not - apply to the LDAP database module. - -**-s** *admin_server*\ [:*port*] - Specifies the admin server which kadmin should contact. - -**-m** - If using kadmin.local, prompt for the database master password - instead of reading it from a stash file. - -**-e** "*enc*:*salt* ..." - Sets the list of encryption types and salt types to be used for - any new keys created. See :ref:`Encryption_and_salt_types` in - :ref:`kdc.conf(5)` for a list of possible values. - -**-O** - Force use of old AUTH_GSSAPI authentication flavor. - -**-N** - Prevent fallback to AUTH_GSSAPI authentication flavor. - -**-x** *db_args* - Specifies the database specific arguments. Options supported for - the LDAP database module are: - - **-x host=**\ *hostname* - Specifies the LDAP server to connect to by a LDAP URI. - - **-x binddn=**\ *bind_dn* - Specifies the DN of the object used by the administration - server to bind to the LDAP server. This object should have - the read and write privileges on the realm container, the - principal container, and the subtree that is referenced by the - realm. - - **-x bindpwd=**\ *bind_password* - Specifies the password for the above mentioned binddn. Using - this option may expose the password to other users on the - system via the process list; to avoid this, instead stash the - password using the **stashsrvpw** command of - :ref:`kdb5_ldap_util(8)`. - -.. _kadmin_options_end: - - -COMMANDS --------- - -When using the remote client, available commands may be restricted -according to the privileges specified in the :ref:`kadm5.acl(5)` file -on the admin server. - -.. _add_principal: - -add_principal -~~~~~~~~~~~~~ - - **add_principal** [*options*] *newprinc* - -Creates the principal *newprinc*, prompting twice for a password. If -no password policy is specified with the **-policy** option, and the -policy named ``default`` is assigned to the principal if it exists. -However, creating a policy named ``default`` will not automatically -assign this policy to previously existing principals. This policy -assignment can be suppressed with the **-clearpolicy** option. - -This command requires the **add** privilege. - -Aliases: **addprinc**, **ank** - -Options: - -**-expire** *expdate* - (:ref:`getdate` string) The expiration date of the principal. - -**-pwexpire** *pwexpdate* - (:ref:`getdate` string) The password expiration date. - -**-maxlife** *maxlife* - (:ref:`getdate` string) The maximum ticket life for the principal. - -**-maxrenewlife** *maxrenewlife* - (:ref:`getdate` string) The maximum renewable life of tickets for - the principal. - -**-kvno** *kvno* - The initial key version number. - -**-policy** *policy* - The password policy used by this principal. If not specified, the - policy ``default`` is used if it exists (unless **-clearpolicy** - is specified). - -**-clearpolicy** - Prevents any policy from being assigned when **-policy** is not - specified. - -{-\|+}\ **allow_postdated** - **-allow_postdated** prohibits this principal from obtaining - postdated tickets. **+allow_postdated** clears this flag. - -{-\|+}\ **allow_forwardable** - **-allow_forwardable** prohibits this principal from obtaining - forwardable tickets. **+allow_forwardable** clears this flag. - -{-\|+}\ **allow_renewable** - **-allow_renewable** prohibits this principal from obtaining - renewable tickets. **+allow_renewable** clears this flag. - -{-\|+}\ **allow_proxiable** - **-allow_proxiable** prohibits this principal from obtaining - proxiable tickets. **+allow_proxiable** clears this flag. - -{-\|+}\ **allow_dup_skey** - **-allow_dup_skey** disables user-to-user authentication for this - principal by prohibiting this principal from obtaining a session - key for another user. **+allow_dup_skey** clears this flag. - -{-\|+}\ **requires_preauth** - **+requires_preauth** requires this principal to preauthenticate - before being allowed to kinit. **-requires_preauth** clears this - flag. - -{-\|+}\ **requires_hwauth** - **+requires_hwauth** requires this principal to preauthenticate - using a hardware device before being allowed to kinit. - **-requires_hwauth** clears this flag. - -{-\|+}\ **ok_as_delegate** - **+ok_as_delegate** sets the **okay as delegate** flag on tickets - issued with this principal as the service. Clients may use this - flag as a hint that credentials should be delegated when - authenticating to the service. **-ok_as_delegate** clears this - flag. - -{-\|+}\ **allow_svr** - **-allow_svr** prohibits the issuance of service tickets for this - principal. **+allow_svr** clears this flag. - -{-\|+}\ **allow_tgs_req** - **-allow_tgs_req** specifies that a Ticket-Granting Service (TGS) - request for a service ticket for this principal is not permitted. - **+allow_tgs_req** clears this flag. - -{-\|+}\ **allow_tix** - **-allow_tix** forbids the issuance of any tickets for this - principal. **+allow_tix** clears this flag. - -{-\|+}\ **needchange** - **+needchange** forces a password change on the next initial - authentication to this principal. **-needchange** clears this - flag. - -{-\|+}\ **password_changing_service** - **+password_changing_service** marks this principal as a password - change service principal. - -**-randkey** - Sets the key of the principal to a random value. - -**-pw** *password* - Sets the password of the principal to the specified string and - does not prompt for a password. Note: using this option in a - shell script may expose the password to other users on the system - via the process list. - -**-e** *enc*:*salt*,... - Uses the specified list of enctype-salttype pairs for setting the - key of the principal. - -**-x** *db_princ_args* - Indicates database-specific options. The options for the LDAP - database module are: - - **-x dn=**\ *dn* - Specifies the LDAP object that will contain the Kerberos - principal being created. - - **-x linkdn=**\ *dn* - Specifies the LDAP object to which the newly created Kerberos - principal object will point. - - **-x containerdn=**\ *container_dn* - Specifies the container object under which the Kerberos - principal is to be created. - - **-x tktpolicy=**\ *policy* - Associates a ticket policy to the Kerberos principal. - - .. note:: - - The **containerdn** and **linkdn** options cannot be - specified with the **dn** option. - - If the *dn* or *containerdn* options are not specified while - adding the principal, the principals are created under the - principal container configured in the realm or the realm - container. - - *dn* and *containerdn* should be within the subtrees or - principal container configured in the realm. - -Example: - - :: - - kadmin: addprinc jennifer - WARNING: no policy specified for "jennifer@ATHENA.MIT.EDU"; - defaulting to no policy. - Enter password for principal jennifer@ATHENA.MIT.EDU: - Re-enter password for principal jennifer@ATHENA.MIT.EDU: - Principal "jennifer@ATHENA.MIT.EDU" created. - kadmin: - -.. _add_principal_end: - -.. _modify_principal: - -modify_principal -~~~~~~~~~~~~~~~~ - - **modify_principal** [*options*] *principal* - -Modifies the specified principal, changing the fields as specified. -The options to **add_principal** also apply to this command, except -for the **-randkey**, **-pw**, and **-e** options. In addition, the -option **-clearpolicy** will clear the current policy of a principal. - -This command requires the *modify* privilege. - -Alias: **modprinc** - -Options (in addition to the **addprinc** options): - -**-unlock** - Unlocks a locked principal (one which has received too many failed - authentication attempts without enough time between them according - to its password policy) so that it can successfully authenticate. - -.. _modify_principal_end: - -.. _rename_principal: - -rename_principal -~~~~~~~~~~~~~~~~ - - **rename_principal** [**-force**] *old_principal* *new_principal* - -Renames the specified *old_principal* to *new_principal*. This -command prompts for confirmation, unless the **-force** option is -given. - -This command requires the **add** and **delete** privileges. - -Alias: **renprinc** - -.. _rename_principal_end: - -.. _delete_principal: - -delete_principal -~~~~~~~~~~~~~~~~ - - **delete_principal** [**-force**] *principal* - -Deletes the specified *principal* from the database. This command -prompts for deletion, unless the **-force** option is given. - -This command requires the **delete** privilege. - -Alias: **delprinc** - -.. _delete_principal_end: - -.. _change_password: - -change_password -~~~~~~~~~~~~~~~ - - **change_password** [*options*] *principal* - -Changes the password of *principal*. Prompts for a new password if -neither **-randkey** or **-pw** is specified. - -This command requires the **changepw** privilege, or that the -principal running the program is the same as the principal being -changed. - -Alias: **cpw** - -The following options are available: - -**-randkey** - Sets the key of the principal to a random value. - -**-pw** *password* - Set the password to the specified string. Using this option in a - script may expose the password to other users on the system via - the process list. - -**-e** *enc*:*salt*,... - Uses the specified list of enctype-salttype pairs for setting the - key of the principal. - -**-keepold** - Keeps the existing keys in the database. This flag is usually not - necessary except perhaps for ``krbtgt`` principals. - -Example: - - :: - - kadmin: cpw systest - Enter password for principal systest@BLEEP.COM: - Re-enter password for principal systest@BLEEP.COM: - Password for systest@BLEEP.COM changed. - kadmin: - -.. _change_password_end: - -.. _purgekeys: - -purgekeys -~~~~~~~~~ - - **purgekeys** [**-keepkvno** *oldest_kvno_to_keep*] *principal* - -Purges previously retained old keys (e.g., from **change_password --keepold**) from *principal*. If **-keepkvno** is specified, then -only purges keys with kvnos lower than *oldest_kvno_to_keep*. - -This command requires the **modify** privilege. - -.. _purgekeys_end: - -.. _get_principal: - -get_principal -~~~~~~~~~~~~~ - - **get_principal** [**-terse**] *principal* - -Gets the attributes of principal. With the **-terse** option, outputs -fields as quoted tab-separated strings. - -This command requires the **inquire** privilege, or that the principal -running the the program to be the same as the one being listed. - -Alias: **getprinc** - -Examples: - - :: - - kadmin: getprinc tlyu/admin - Principal: tlyu/admin@BLEEP.COM - Expiration date: [never] - Last password change: Mon Aug 12 14:16:47 EDT 1996 - Password expiration date: [none] - Maximum ticket life: 0 days 10:00:00 - Maximum renewable life: 7 days 00:00:00 - Last modified: Mon Aug 12 14:16:47 EDT 1996 (bjaspan/admin@BLEEP.COM) - Last successful authentication: [never] - Last failed authentication: [never] - Failed password attempts: 0 - Number of keys: 2 - Key: vno 1, DES cbc mode with CRC-32, no salt - Key: vno 1, DES cbc mode with CRC-32, Version 4 - Attributes: - Policy: [none] - - kadmin: getprinc -terse systest - systest@BLEEP.COM 3 86400 604800 1 - 785926535 753241234 785900000 - tlyu/admin@BLEEP.COM 786100034 0 0 - kadmin: - -.. _get_principal_end: - -.. _list_principals: - -list_principals -~~~~~~~~~~~~~~~ - - **list_principals** [*expression*] - -Retrieves all or some principal names. *expression* is a shell-style -glob expression that can contain the wild-card characters ``?``, -``*``, and ``[]``. All principal names matching the expression are -printed. If no expression is provided, all principal names are -printed. If the expression does not contain an ``@`` character, an -``@`` character followed by the local realm is appended to the -expression. - -This command requires the **list** privilege. - -Alias: **listprincs**, **get_principals**, **get_princs** - -Example: - - :: - - kadmin: listprincs test* - test3@SECURE-TEST.OV.COM - test2@SECURE-TEST.OV.COM - test1@SECURE-TEST.OV.COM - testuser@SECURE-TEST.OV.COM - kadmin: - -.. _list_principals_end: - -.. _get_strings: - -get_strings -~~~~~~~~~~~ - - **get_strings** *principal* - -Displays string attributes on *principal*. - -This command requires the **inquire** privilege. - -Alias: **getstr** - -.. _get_strings_end: - -.. _set_string: - -set_string -~~~~~~~~~~ - - **set_string** *principal* *key* *value* - -Sets a string attribute on *principal*. String attributes are used to -supply per-principal configuration to the KDC and some KDC plugin -modules. The following string attributes are recognized by the KDC: - -**session_enctypes** - Specifies the encryption types supported for session keys when the - principal is authenticated to as a server. See - :ref:`Encryption_and_salt_types` in :ref:`kdc.conf(5)` for a list - of the accepted values. - -This command requires the **modify** privilege. - -Alias: **setstr** - -.. _set_string_end: - -.. _del_string: - -del_string -~~~~~~~~~~ - - **del_string** *principal* *key* - -Deletes a string attribute from *principal*. - -This command requires the **delete** privilege. - -Alias: **delstr** - -.. _del_string_end: - -.. _add_policy: - -add_policy -~~~~~~~~~~ - - **add_policy** [*options*] *policy* - -Adds a password policy named *policy* to the database. - -This command requires the **add** privilege. - -Alias: **addpol** - -The following options are available: - -**-maxlife** *time* - (:ref:`getdate` string) Sets the maximum lifetime of a password. - -**-minlife** *time* - (:ref:`getdate` string) Sets the minimum lifetime of a password. - -**-minlength** *length* - Sets the minimum length of a password. - -**-minclasses** *number* - Sets the minimum number of character classes required in a - password. The five character classes are lower case, upper case, - numbers, punctuation, and whitespace/unprintable characters. - -**-history** *number* - Sets the number of past keys kept for a principal. This option is - not supported with the LDAP KDC database module. - -**-maxfailure** *maxnumber* - Sets the maximum number of authentication failures before the - principal is locked. Authentication failures are only tracked for - principals which require preauthentication. - -**-failurecountinterval** *failuretime* - (:ref:`getdate` string) Sets the allowable time between - authentication failures. If an authentication failure happens - after *failuretime* has elapsed since the previous failure, - the number of authentication failures is reset to 1. - -**-lockoutduration** *lockouttime* - (:ref:`getdate` string) Sets the duration for which the principal - is locked from authenticating if too many authentication failures - occur without the specified failure count interval elapsing. - A duration of 0 means forever. - -**-allowedkeysalts** - Specifies the key/salt tuples supported for long-term keys when - setting or changing a principal's password/keys. See - :ref:`Encryption_and_salt_types` in :ref:`kdc.conf(5)` for a list - of the accepted values, but note that key/salt tuples must be - separated with commas (',') only. To clear the allowed key/salt - policy use a value of '-'. - -Example: - - :: - - kadmin: add_policy -maxlife "2 days" -minlength 5 guests - kadmin: - -.. _add_policy_end: - -.. _modify_policy: - -modify_policy -~~~~~~~~~~~~~ - - **modify_policy** [*options*] *policy* - -Modifies the password policy named *policy*. Options are as described -for **add_policy**. - -This command requires the **modify** privilege. - -Alias: **modpol** - -.. _modify_policy_end: - -.. _delete_policy: - -delete_policy -~~~~~~~~~~~~~ - - **delete_policy** [**-force**] *policy* - -Deletes the password policy named *policy*. Prompts for confirmation -before deletion. The command will fail if the policy is in use by any -principals. - -This command requires the **delete** privilege. - -Alias: **delpol** - -Example: - - :: - - kadmin: del_policy guests - Are you sure you want to delete the policy "guests"? - (yes/no): yes - kadmin: - -.. _delete_policy_end: - -.. _get_policy: - -get_policy -~~~~~~~~~~ - - **get_policy** [ **-terse** ] *policy* - -Displays the values of the password policy named *policy*. With the -**-terse** flag, outputs the fields as quoted strings separated by -tabs. - -This command requires the **inquire** privilege. - -Alias: getpol - -Examples: - - :: - - kadmin: get_policy admin - Policy: admin - Maximum password life: 180 days 00:00:00 - Minimum password life: 00:00:00 - Minimum password length: 6 - Minimum number of password character classes: 2 - Number of old keys kept: 5 - Reference count: 17 - - kadmin: get_policy -terse admin - admin 15552000 0 6 2 5 17 - kadmin: - -The "Reference count" is the number of principals using that policy. -With the LDAP KDC database module, the reference count field is not -meaningful. - -.. _get_policy_end: - -.. _list_policies: - -list_policies -~~~~~~~~~~~~~ - - **list_policies** [*expression*] - -Retrieves all or some policy names. *expression* is a shell-style -glob expression that can contain the wild-card characters ``?``, -``*``, and ``[]``. All policy names matching the expression are -printed. If no expression is provided, all existing policy names are -printed. - -This command requires the **list** privilege. - -Aliases: **listpols**, **get_policies**, **getpols**. - -Examples: - - :: - - kadmin: listpols - test-pol - dict-only - once-a-min - test-pol-nopw - - kadmin: listpols t* - test-pol - test-pol-nopw - kadmin: - -.. _list_policies_end: - -.. _ktadd: - -ktadd -~~~~~ - - | **ktadd** [options] *principal* - | **ktadd** [options] **-glob** *princ-exp* - -Adds a *principal*, or all principals matching *princ-exp*, to a -keytab file. Each principal's keys are randomized in the process. -The rules for *princ-exp* are described in the **list_principals** -command. - -This command requires the **inquire** and **changepw** privileges. -With the **-glob** form, it also requires the **list** privilege. - -The options are: - -**-k[eytab]** *keytab* - Use *keytab* as the keytab file. Otherwise, the default keytab is - used. - -**-e** *enc*:*salt*,... - Use the specified list of enctype-salttype pairs for setting the - new keys of the principal. - -**-q** - Display less verbose information. - -**-norandkey** - Do not randomize the keys. The keys and their version numbers stay - unchanged. This option is only available in kadmin.local, and - cannot be specified in combination with the **-e** option. - -An entry for each of the principal's unique encryption types is added, -ignoring multiple keys with the same encryption type but different -salt types. - -Example: - - :: - - kadmin: ktadd -k /tmp/foo-new-keytab host/foo.mit.edu - Entry for principal host/foo.mit.edu@ATHENA.MIT.EDU with kvno 3, - encryption type aes256-cts-hmac-sha1-96 added to keytab - FILE:/tmp/foo-new-keytab - kadmin: - -.. _ktadd_end: - -.. _ktremove: - -ktremove -~~~~~~~~ - - **ktremove** [options] *principal* [*kvno* | *all* | *old*] - -Removes entries for the specified *principal* from a keytab. Requires -no permissions, since this does not require database access. - -If the string "all" is specified, all entries for that principal are -removed; if the string "old" is specified, all entries for that -principal except those with the highest kvno are removed. Otherwise, -the value specified is parsed as an integer, and all entries whose -kvno match that integer are removed. - -The options are: - -**-k[eytab]** *keytab* - Use *keytab* as the keytab file. Otherwise, the default keytab is - used. - -**-q** - Display less verbose information. - -Example: - - :: - - kadmin: ktremove kadmin/admin all - Entry for principal kadmin/admin with kvno 3 removed from keytab - FILE:/etc/krb5.keytab - kadmin: - -.. _ktremove_end: - -lock -~~~~ - -Lock database exclusively. Use with extreme caution! This command -only works with the DB2 KDC database module. - -unlock -~~~~~~ - -Release the exclusive database lock. - -list_requests -~~~~~~~~~~~~~ - -Lists available for kadmin requests. - -Aliases: **lr**, **?** - -quit -~~~~ - -Exit program. If the database was locked, the lock is released. - -Aliases: **exit**, **q** - - -HISTORY -------- - -The kadmin program was originally written by Tom Yu at MIT, as an -interface to the OpenVision Kerberos administration program. - - -SEE ALSO --------- - -:ref:`kpasswd(1)`, :ref:`kadmind(8)` diff --git a/doc/rst_source/krb_admins/admin_commands/kadmind.rst b/doc/rst_source/krb_admins/admin_commands/kadmind.rst deleted file mode 100644 index 10fc672cb..000000000 --- a/doc/rst_source/krb_admins/admin_commands/kadmind.rst +++ /dev/null @@ -1,130 +0,0 @@ -.. _kadmind(8): - -kadmind -======= - -SYNOPSIS --------- - -**kadmind** -[**-x** *db_args*] -[**-r** *realm*] -[**-m**] -[**-nofork**] -[**-port** *port-number*] -[**-P** *pid_file*] -[**-p** *kdb5_util_path*] -[**-K** *kprop_path*] -[**-F** *dump_file*] - -DESCRIPTION ------------ - -kadmind starts the Kerberos administration server. kadmind typically -runs on the master Kerberos server, which stores the KDC database. If -the KDC database uses the LDAP module, the administration server and -the KDC server need not run on the same machine. kadmind accepts -remote requests from programs such as :ref:`kadmin(1)` and -:ref:`kpasswd(1)` to administer the information in these database. - -kadmind requires a number of configuration files to be set up in order -for it to work: - -:ref:`kdc.conf(5)` - The KDC configuration file contains configuration information for - the KDC and admin servers. kadmind uses settings in this file to - locate the Kerberos database, and is also affected by the - **acl_file**, **dict_file**, **kadmind_port**, and iprop-related - settings. - -:ref:`kadm5.acl(5)` - kadmind's ACL (access control list) tells it which principals are - allowed to perform administration actions. The pathname to the - ACL file can be specified with the **acl_file** :ref:`kdc.conf(5)` - variable; by default, it is |kdcdir|\ ``/kadm5.acl``. - -After the server begins running, it puts itself in the background and -disassociates itself from its controlling terminal. - -kadmind can be configured for incremental database propagation. -Incremental propagation allows slave KDC servers to receive principal -and policy updates incrementally instead of receiving full dumps of -the database. This facility can be enabled in the :ref:`kdc.conf(5)` -file with the **iprop_enable** option. Incremental propagation -requires the principal ``kiprop/MASTER\@REALM`` (where MASTER is the -master KDC's canonical host name, and REALM the realm name) to be -registered in the database. - - -OPTIONS -------- - -**-r** *realm* - specifies the realm that kadmind will serve; if it is not - specified, the default realm of the host is used. - -**-m** - causes the master database password to be fetched from the - keyboard (before the server puts itself in the background, if not - invoked with the **-nofork** option) rather than from a file on - disk. - -**-nofork** - causes the server to remain in the foreground and remain - associated to the terminal. In normal operation, you should allow - the server to place itself in the background. - -**-port** *port-number* - specifies the port on which the administration server listens for - connections. The default port is determined by the - **kadmind_port** configuration variable in :ref:`kdc.conf(5)`. - -**-P** *pid_file* - specifies the file to which the PID of kadmind process should be - written after it starts up. This file can be used to identify - whether kadmind is still running and to allow init scripts to stop - the correct process. - -**-p** *kdb5_util_path* - specifies the path to the kdb5_util command to use when dumping the - KDB in response to full resync requests when iprop is enabled. - -**-K** *kprop_path* - specifies the path to the kprop command to use to send full dumps - to slaves in response to full resync requests. - -**-F** *dump_file* - specifies the file path to be used for dumping the KDB in response - to full resync requests when iprop is enabled. - -**-x** *db_args* - specifies database-specific arguments. - - Options supported for LDAP database are: - - **-x nconns=**\ *number_of_connections* - specifies the number of connections to be maintained per - LDAP server. - - **-x host=**\ *ldapuri* - specifies the LDAP server to connect to by URI. - - **-x binddn=**\ *binddn* - specifies the DN of the object used by the administration - server to bind to the LDAP server. This object should - have read and write privileges on the realm container, the - principal container, and the subtree that is referenced by - the realm. - - **-x bindpwd=**\ *bind_password* - specifies the password for the above mentioned binddn. - Using this option may expose the password to other users - on the system via the process list; to avoid this, instead - stash the password using the **stashsrvpw** command of - :ref:`kdb5_ldap_util(8)`. - -SEE ALSO --------- - -:ref:`kpasswd(1)`, :ref:`kadmin(1)`, :ref:`kdb5_util(8)`, -:ref:`kdb5_ldap_util(8)`, :ref:`kadm5.acl(5)` diff --git a/doc/rst_source/krb_admins/admin_commands/kdb5_ldap_util.rst b/doc/rst_source/krb_admins/admin_commands/kdb5_ldap_util.rst deleted file mode 100644 index e5c037db4..000000000 --- a/doc/rst_source/krb_admins/admin_commands/kdb5_ldap_util.rst +++ /dev/null @@ -1,478 +0,0 @@ -.. _kdb5_ldap_util(8): - -kdb5_ldap_util -=============== - -SYNOPSIS --------- - -.. _kdb5_ldap_util_synopsis: - -**kdb5_ldap_util** -[**-D** *user_dn* [**-w** *passwd*]] -[**-H** *ldapuri*] -**command** -[*command_options*] - -.. _kdb5_ldap_util_synopsis_end: - - -DESCRIPTION ------------ - -kdb5_ldap_util allows an administrator to manage realms, Kerberos -services and ticket policies. - - -COMMAND-LINE OPTIONS --------------------- - -.. _kdb5_ldap_util_options: - -**-D** *user_dn* - Specifies the Distinguished Name (DN) of the user who has - sufficient rights to perform the operation on the LDAP server. - -**-w** *passwd* - Specifies the password of *user_dn*. This option is not - recommended. - -**-H** *ldapuri* - Specifies the URI of the LDAP server. It is recommended to use - ``ldapi://`` or ``ldaps://`` to connect to the LDAP server. - -.. _kdb5_ldap_util_options_end: - - -COMMANDS --------- - -create -~~~~~~ - -.. _kdb5_ldap_util_create: - - **create** - [**-subtrees** *subtree_dn_list*] - [**-sscope** *search_scope*] - [**-containerref** *container_reference_dn*] - [**-k** *mkeytype*] - [**-kv** *mkeyVNO*] - [**-m|-P** *password*\|\ **-sf** *stashfilename*] - [**-s**] - [**-r** *realm*] - [**-maxtktlife** *max_ticket_life*] - [**-maxrenewlife** *max_renewable_ticket_life*] - [*ticket_flags*] - -Creates realm in directory. Options: - -**-subtrees** *subtree_dn_list* - Specifies the list of subtrees containing the principals of a - realm. The list contains the DNs of the subtree objects separated - by colon (``:``). - -**-sscope** *search_scope* - Specifies the scope for searching the principals under the - subtree. The possible values are 1 or one (one level), 2 or sub - (subtrees). - -**-containerref** *container_reference_dn* - Specifies the DN of the container object in which the principals - of a realm will be created. If the container reference is not - configured for a realm, the principals will be created in the - realm container. - -**-k** *mkeytype* - Specifies the key type of the master key in the database. The - default is given by the **master_key_type** variable in - :ref:`kdc.conf(5)`. - -**-kv** *mkeyVNO* - Specifies the version number of the master key in the database; - the default is 1. Note that 0 is not allowed. - -**-m** - Specifies that the master database password should be read from - the TTY rather than fetched from a file on the disk. - -**-P** *password* - Specifies the master database password. This option is not - recommended. - -**-r** *realm* - Specifies the Kerberos realm of the database. - -**-sf** *stashfilename* - Specifies the stash file of the master database password. - -**-s** - Specifies that the stash file is to be created. - -**-maxtktlife** *max_ticket_life* - (:ref:`getdate` string) Specifies maximum ticket life for - principals in this realm. - -**-maxrenewlife** *max_renewable_ticket_life* - (:ref:`getdate` string) Specifies maximum renewable life of - tickets for principals in this realm. - -*ticket_flags* - Specifies global ticket flags for the realm. Allowable flags are - documented in the description of the **add_principal** command in - :ref:`kadmin(1)`. - -Example: - - :: - - kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu - create -subtrees o=org -sscope SUB -r ATHENA.MIT.EDU - Password for "cn=admin,o=org": - Initializing database for realm 'ATHENA.MIT.EDU' - You will be prompted for the database Master Password. - It is important that you NOT FORGET this password. - Enter KDC database master key: - Re-enter KDC database master key to verify: - -.. _kdb5_ldap_util_create_end: - -modify -~~~~~~ - -.. _kdb5_ldap_util_modify: - - **modify** - [**-subtrees** *subtree_dn_list*] - [**-sscope** *search_scope*] - [**-containerref** *container_reference_dn*] - [**-r** *realm*] - [**-maxtktlife** *max_ticket_life*] - [**-maxrenewlife** *max_renewable_ticket_life*] - [*ticket_flags*] - -Modifies the attributes of a realm. Options: - -**-subtrees** *subtree_dn_list* - Specifies the list of subtrees containing the principals of a - realm. The list contains the DNs of the subtree objects separated - by colon (``:``). This list replaces the existing list. - -**-sscope** *search_scope* - Specifies the scope for searching the principals under the - subtrees. The possible values are 1 or one (one level), 2 or sub - (subtrees). - -**-containerref** *container_reference_dn* Specifies the DN of the - container object in which the principals of a realm will be - created. - -**-r** *realm* - Specifies the Kerberos realm of the database. - -**-maxtktlife** *max_ticket_life* - (:ref:`getdate` string) Specifies maximum ticket life for - principals in this realm. - -**-maxrenewlife** *max_renewable_ticket_life* - (:ref:`getdate` string) Specifies maximum renewable life of - tickets for principals in this realm. - -*ticket_flags* - Specifies global ticket flags for the realm. Allowable flags are - documented in the description of the **add_principal** command in - :ref:`kadmin(1)`. - -Example: - - :: - - shell% kdb5_ldap_util -D cn=admin,o=org -H - ldaps://ldap-server1.mit.edu modify +requires_preauth -r - ATHENA.MIT.EDU - Password for "cn=admin,o=org": - shell% - -.. _kdb5_ldap_util_modify_end: - -view -~~~~ - -.. _kdb5_ldap_util_view: - - **view** [**-r** *realm*] - -Displays the attributes of a realm. Options: - -**-r** *realm* - Specifies the Kerberos realm of the database. - -Example: - - :: - - kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu - view -r ATHENA.MIT.EDU - Password for "cn=admin,o=org": - Realm Name: ATHENA.MIT.EDU - Subtree: ou=users,o=org - Subtree: ou=servers,o=org - SearchScope: ONE - Maximum ticket life: 0 days 01:00:00 - Maximum renewable life: 0 days 10:00:00 - Ticket flags: DISALLOW_FORWARDABLE REQUIRES_PWCHANGE - -.. _kdb5_ldap_util_view_end: - -destroy -~~~~~~~ - -.. _kdb5_ldap_util_destroy: - - **destroy** [**-f**] [**-r** *realm*] - -Destroys an existing realm. Options: - -**-f** - If specified, will not prompt the user for confirmation. - -**-r** *realm* - Specifies the Kerberos realm of the database. - -Example: - - :: - - shell% kdb5_ldap_util -D cn=admin,o=org -H - ldaps://ldap-server1.mit.edu destroy -r ATHENA.MIT.EDU - Password for "cn=admin,o=org": - Deleting KDC database of 'ATHENA.MIT.EDU', are you sure? - (type 'yes' to confirm)? yes - OK, deleting database of 'ATHENA.MIT.EDU'... - shell% - -.. _kdb5_ldap_util_destroy_end: - -list -~~~~ - -.. _kdb5_ldap_util_list: - - **list** - -Lists the name of realms. - -Example: - - :: - - shell% kdb5_ldap_util -D cn=admin,o=org -H - ldaps://ldap-server1.mit.edu list - Password for "cn=admin,o=org": - ATHENA.MIT.EDU - OPENLDAP.MIT.EDU - MEDIA-LAB.MIT.EDU - shell% - -.. _kdb5_ldap_util_list_end: - -stashsrvpw -~~~~~~~~~~ - -.. _kdb5_ldap_util_stashsrvpw: - - **stashsrvpw** - [**-f** *filename*] - *servicedn* - -Allows an administrator to store the password for service object in a -file so that KDC and Administration server can use it to authenticate -to the LDAP server. Options: - -**-f** *filename* - Specifies the complete path of the service password file. By - default, ``/usr/local/var/service_passwd`` is used. - -*servicedn* - Specifies Distinguished Name (DN) of the service object whose - password is to be stored in file. - -Example: - - :: - - kdb5_ldap_util stashsrvpw -f /home/andrew/conf_keyfile - cn=service-kdc,o=org - Password for "cn=service-kdc,o=org": - Re-enter password for "cn=service-kdc,o=org": - -.. _kdb5_ldap_util_stashsrvpw_end: - -create_policy -~~~~~~~~~~~~~ - -.. _kdb5_ldap_util_create_policy: - - **create_policy** - [**-r** *realm*] - [**-maxtktlife** *max_ticket_life*] - [**-maxrenewlife** *max_renewable_ticket_life*] - [*ticket_flags*] - *policy_name* - -Creates a ticket policy in the directory. Options: - -**-r** *realm* - Specifies the Kerberos realm of the database. - -**-maxtktlife** *max_ticket_life* - (:ref:`getdate` string) Specifies maximum ticket life for - principals. - -**-maxrenewlife** *max_renewable_ticket_life* - (:ref:`getdate` string) Specifies maximum renewable life of - tickets for principals. - -*ticket_flags* - Specifies the ticket flags. If this option is not specified, by - default, no restriction will be set by the policy. Allowable - flags are documented in the description of the **add_principal** - command in :ref:`kadmin(1)`. - -*policy_name* - Specifies the name of the ticket policy. - -Example: - - :: - - kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu - create_policy -r ATHENA.MIT.EDU -maxtktlife "1 day" - -maxrenewlife "1 week" -allow_postdated +needchange - -allow_forwardable tktpolicy - Password for "cn=admin,o=org": - -.. _kdb5_ldap_util_create_policy_end: - -modify_policy -~~~~~~~~~~~~~ - -.. _kdb5_ldap_util_modify_policy: - - **modify_policy** - [**-r** *realm*] - [**-maxtktlife** *max_ticket_life*] - [**-maxrenewlife** *max_renewable_ticket_life*] - [*ticket_flags*] - *policy_name* - -Modifies the attributes of a ticket policy. Options are same as for -**create_policy**. - -Example: - - :: - - kdb5_ldap_util -D cn=admin,o=org -H - ldaps://ldap-server1.mit.edu modify_policy -r ATHENA.MIT.EDU - -maxtktlife "60 minutes" -maxrenewlife "10 hours" - +allow_postdated -requires_preauth tktpolicy - Password for "cn=admin,o=org": - -.. _kdb5_ldap_util_modify_policy_end: - -view_policy -~~~~~~~~~~~ - -.. _kdb5_ldap_util_view_policy: - - **view_policy** - [**-r** *realm*] - *policy_name* - -Displays the attributes of a ticket policy. Options: - -*policy_name* - Specifies the name of the ticket policy. - -Example: - - :: - - kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu - view_policy -r ATHENA.MIT.EDU tktpolicy - Password for "cn=admin,o=org": - Ticket policy: tktpolicy - Maximum ticket life: 0 days 01:00:00 - Maximum renewable life: 0 days 10:00:00 - Ticket flags: DISALLOW_FORWARDABLE REQUIRES_PWCHANGE - -.. _kdb5_ldap_util_view_policy_end: - -destroy_policy -~~~~~~~~~~~~~~ - -.. _kdb5_ldap_util_destroy_policy: - - **destroy_policy** - [**-r** *realm*] - [**-force**] - *policy_name* - -Destroys an existing ticket policy. Options: - -**-r** *realm* - Specifies the Kerberos realm of the database. - -**-force** - Forces the deletion of the policy object. If not specified, the - user will be prompted for confirmation before deleting the policy. - -*policy_name* - Specifies the name of the ticket policy. - -Example: - - :: - - kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu - destroy_policy -r ATHENA.MIT.EDU tktpolicy - Password for "cn=admin,o=org": - This will delete the policy object 'tktpolicy', are you sure? - (type 'yes' to confirm)? yes - ** policy object 'tktpolicy' deleted. - -.. _kdb5_ldap_util_destroy_policy_end: - -list_policy -~~~~~~~~~~~ - -.. _kdb5_ldap_util_list_policy: - - **list_policy** - [**-r** *realm*] - -Lists the ticket policies in realm if specified or in the default -realm. Options: - -**-r** *realm* - Specifies the Kerberos realm of the database. - -Example: - - :: - - kdb5_ldap_util -D cn=admin,o=org -H ldaps://ldap-server1.mit.edu - list_policy -r ATHENA.MIT.EDU - Password for "cn=admin,o=org": - tktpolicy - tmppolicy - userpolicy - -.. _kdb5_ldap_util_list_policy_end: - - -SEE ALSO --------- - -:ref:`kadmin(1)` diff --git a/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst b/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst deleted file mode 100644 index d866777c7..000000000 --- a/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst +++ /dev/null @@ -1,355 +0,0 @@ -.. _kdb5_util(8): - -kdb5_util -========= - -SYNOPSIS --------- - -.. _kdb5_util_synopsis: - -**kdb5_util** -[**-r** *realm*] -[**-d** *dbname*] -[**-k** *mkeytype*] -[**-M** *mkeyname*] -[**-kv** *mkeyVNO*] -[**-sf** *stashfilename*] -[**-m**] -*command* [*command_options*] - -.. _kdb5_util_synopsis_end: - -DESCRIPTION ------------ - -kdb5_util allows an administrator to perform maintenance procedures on -the KDC database. Databases can be created, destroyed, and dumped to -or loaded from ASCII files. kdb5_util can create a Kerberos master -key stash file or perform live rollover of the master key. - -When kdb5_util is run, it attempts to acquire the master key and open -the database. However, execution continues regardless of whether or -not kdb5_util successfully opens the database, because the database -may not exist yet or the stash file may be corrupt. - -Note that some KDC database modules may not support all kdb5_util -commands. - - -COMMAND-LINE OPTIONS --------------------- - -.. _kdb5_util_options: - -**-r** *realm* - specifies the Kerberos realm of the database. - -**-d** *dbname* - specifies the name under which the principal database is stored; - by default the database is that listed in :ref:`kdc.conf(5)`. The - password policy database and lock files are also derived from this - value. - -**-k** *mkeytype* - specifies the key type of the master key in the database. The - default is given by the **master_key_type** variable in - :ref:`kdc.conf(5)`. - -**-kv** *mkeyVNO* - Specifies the version number of the master key in the database; - the default is 1. Note that 0 is not allowed. - -**-M** *mkeyname* - principal name for the master key in the database. If not - specified, the name is determined by the **master_key_name** - variable in :ref:`kdc.conf(5)`. - -**-m** - specifies that the master database password should be read from - the keyboard rather than fetched from a file on disk. - -**-sf** *stash_file* - specifies the stash filename of the master database password. If - not specified, the filename is determined by the - **key_stash_file** variable in :ref:`kdc.conf(5)`. - -**-P** *password* - specifies the master database password. Using this option may - expose the password to other users on the system via the process - list. - -.. _kdb5_util_options_end: - - -COMMANDS --------- - -create -~~~~~~ - -.. _kdb5_util_create: - - **create** [**-s**] - -Creates a new database. If the **-s** option is specified, the stash -file is also created. This command fails if the database already -exists. If the command is successful, the database is opened just as -if it had already existed when the program was first run. - -.. _kdb5_util_create_end: - -destroy -~~~~~~~ - -.. _kdb5_util_destroy: - - **destroy** [**-f**] - -Destroys the database, first overwriting the disk sectors and then -unlinking the files, after prompting the user for confirmation. With -the **-f** argument, does not prompt the user. - -.. _kdb5_util_destroy_end: - -stash -~~~~~ - -.. _kdb5_util_stash: - - **stash** [**-f** *keyfile*] - -Stores the master principal's keys in a stash file. The **-f** -argument can be used to override the *keyfile* specified in -:ref:`kdc.conf(5)`. - -.. _kdb5_util_stash_end: - -dump -~~~~ - -.. _kdb5_util_dump: - - **dump** [**-old**\|\ **-b6**\|\ **-b7**\|\ **-ov**\|\ **-r13**] - [**-verbose**] [**-mkey_convert**] [**-new_mkey_file** *mkey_file*] - [**-rev**] [**-recurse**] [*filename* [*principals*...]] - -Dumps the current Kerberos and KADM5 database into an ASCII file. By -default, the database is dumped in current format, "kdb5_util -load_dump version 6". If filename is not specified, or is the string -"-", the dump is sent to standard output. Options: - -**-old** - causes the dump to be in the Kerberos 5 Beta 5 and earlier dump - format ("kdb5_edit load_dump version 2.0"). - -**-b6** - causes the dump to be in the Kerberos 5 Beta 6 format ("kdb5_edit - load_dump version 3.0"). - -**-b7** - causes the dump to be in the Kerberos 5 Beta 7 format ("kdb5_util - load_dump version 4"). This was the dump format produced on - releases prior to 1.2.2. - -**-ov** - causes the dump to be in "ovsec_adm_export" format. - -**-r13** - causes the dump to be in the Kerberos 5 1.3 format ("kdb5_util - load_dump version 5"). This was the dump format produced on - releases prior to 1.8. - -**-r18** - causes the dump to be in the Kerberos 5 1.8 format ("kdb5_util - load_dump version 6"). This was the dump format produced on - releases prior to 1.11. - -**-verbose** - causes the name of each principal and policy to be printed as it - is dumped. - -**-mkey_convert** - prompts for a new master key. This new master key will be used to - re-encrypt principal key data in the dumpfile. The principal keys - themselves will not be changed. - -**-new_mkey_file** *mkey_file* - the filename of a stash file. The master key in this stash file - will be used to re-encrypt the key data in the dumpfile. The key - data in the database will not be changed. - -**-rev** - dumps in reverse order. This may recover principals that do not - dump normally, in cases where database corruption has occurred. - -**-recurse** - causes the dump to walk the database recursively (btree only). - This may recover principals that do not dump normally, in cases - where database corruption has occurred. In cases of such - corruption, this option will probably retrieve more principals - than the **-rev** option will. - -.. _kdb5_util_dump_end: - -load -~~~~ - -.. _kdb5_util_load: - - **load** [**-old**\|\ **-b6**\|\ **-b7**\|\ **-ov**\|\ **-r13**] - [**-hash**] [**-verbose**] [**-update**] *filename* [*dbname*] - -Loads a database dump from the named file into the named database. If -no option is given to determine the format of the dump file, the -format is detected automatically and handled as appropriate. Unless -the **-update** option is given, **load** creates a new database -containing only the data in the dump file, overwriting the contents of -any previously existing database. Note that when using the LDAP KDC -database module, the **-update** flag is required. - -Options: - -**-old** - requires the database to be in the Kerberos 5 Beta 5 and earlier - format ("kdb5_edit load_dump version 2.0"). - -**-b6** - requires the database to be in the Kerberos 5 Beta 6 format - ("kdb5_edit load_dump version 3.0"). - -**-b7** - requires the database to be in the Kerberos 5 Beta 7 format - ("kdb5_util load_dump version 4"). - -**-ov** - requires the database to be in "ovsec_adm_import" format. Must be - used with the **-update** option. - -**-r13** - requires the database to be in Kerberos 5 1.3 format ("kdb5_util - load_dump version 5"). This was the dump format produced on - releases prior to 1.8. - -**-r18** - requires the database to be in Kerberos 5 1.8 format ("kdb5_util - load_dump version 6"). This was the dump format produced on - releases prior to 1.11. - -**-hash** - requires the database to be stored as a hash. If this option is - not specified, the database will be stored as a btree. This - option is not recommended, as databases stored in hash format are - known to corrupt data and lose principals. - -**-verbose** - causes the name of each principal and policy to be printed as it - is dumped. - -**-update** - records from the dump file are added to or updated in the existing - database. (This is useful in conjunction with an ovsec_adm_export - format dump if you want to preserve per-principal policy - information, since the current default format does not contain - this data.) Otherwise, a new database is created containing only - what is in the dump file and the old one destroyed upon successful - completion. - -If specified, *dbname* overrides the value specified on the command -line or the default. - -.. _kdb5_util_load_end: - -ark -~~~ - - **ark** [**-e** *enc*:*salt*,...] *principal* - -Adds new random keys to *principal* at the next available key version -number. Keys for the current highest key version number will be -preserved. The **-e** option specifies the list of encryption and -salt types to be used for the new keys. - -add_mkey -~~~~~~~~ - - **add_mkey** [**-e** *etype*] [**-s**] - -Adds a new master key to the master key principal, but does not mark -it as active. Existing master keys will remain. The **-e** option -specifies the encryption type of the new master key; see -:ref:`Encryption_and_salt_types` in :ref:`kdc.conf(5)` for a list of -possible values. The **-s** option stashes the new master key in the -stash file, which will be created if it doesn't already exist. - -After a new master key is added, it should be propagated to slave -servers via a manual or periodic invocation of :ref:`kprop(8)`. Then, -the stash files on the slave servers should be updated with the -kdb5_util **stash** command. Once those steps are complete, the key -is ready to be marked active with the kdb5_util **use_mkey** command. - -use_mkey -~~~~~~~~ - - **use_mkey** *mkeyVNO* [*time*] - -Sets the activation time of the master key specified by *mkeyVNO*. -Once a master key becomes active, it will be used to encrypt newly -created principal keys. If no *time* argument is given, the current -time is used, causing the specified master key version to become -active immediately. The format for *time* is :ref:`getdate` string. - -After a new master key becomes active, the kdb5_util -**update_princ_encryption** command can be used to update all -principal keys to be encrypted in the new master key. - -list_mkeys -~~~~~~~~~~ - - **list_mkeys** - -List all master keys, from most recent to earliest, in the master key -principal. The output will show the kvno, enctype, and salt type for -each mkey, similar to the output of :ref:`kadmin(1)` **getprinc**. A -``*`` following an mkey denotes the currently active master key. - -purge_mkeys -~~~~~~~~~~~ - - **purge_mkeys** [**-f**] [**-n**] [**-v**] - -Delete master keys from the master key principal that are not used to -protect any principals. This command can be used to remove old master -keys all principal keys are protected by a newer master key. - -**-f** - does not prompt for confirmation. - -**-n** - performs a dry run, showing master keys that would be purged, but - not actually purging any keys. - -**-v** - gives more verbose output. - -update_princ_encryption -~~~~~~~~~~~~~~~~~~~~~~~ - - **update_princ_encryption** [**-f**] [**-n**] [**-v**] - [*princ-pattern*] - -Update all principal records (or only those matching the -*princ-pattern* glob pattern) to re-encrypt the key data using the -active database master key, if they are encrypted using older -versions, and give a count at the end of the number of principals -updated. If the **-f** option is not given, ask for confirmation -before starting to make changes. The **-v** option causes each -principal processed to be listed, with an indication as to whether it -needed updating or not. The **-n** option performs a dry run, only -showing the actions which would have been taken. - - -SEE ALSO --------- - -:ref:`kadmin(1)` diff --git a/doc/rst_source/krb_admins/admin_commands/kprop.rst b/doc/rst_source/krb_admins/admin_commands/kprop.rst deleted file mode 100644 index 726c8cc2f..000000000 --- a/doc/rst_source/krb_admins/admin_commands/kprop.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. _kprop(8): - -kprop -===== - -SYNOPSIS --------- - -**kprop** -[**-r** *realm*] -[**-f** *file*] -[**-d**] -[**-P** *port*] -[**-s** *keytab*] -*slave_host* - - -DESCRIPTION ------------ - -kprop is used to securely propagate a Kerberos V5 database dump file -from the master Kerberos server to a slave Kerberos server, which is -specified by *slave_host*. The dump file must be created by -:ref:`kdb5_util(8)`. - - -OPTIONS -------- - -**-r** *realm* - Specifies the realm of the master server. - -**-f** *file* - Specifies the filename where the dumped principal database file is - to be found; by default the dumped database file is normally - |kdcdir|\ ``/slave_datatrans``. - -**-P** *port* - Specifies the port to use to contact the :ref:`kpropd(8)` server - on the remote host. - -**-d** - Prints debugging information. - -**-s** *keytab* - Specifies the location of the keytab file. - - -ENVIRONMENT ------------ - -*kprop* uses the following environment variable: - -* **KRB5_CONFIG** - - -SEE ALSO --------- - -:ref:`kpropd(8)`, :ref:`kdb5_util(8)`, :ref:`krb5kdc(8)` diff --git a/doc/rst_source/krb_admins/admin_commands/kpropd.rst b/doc/rst_source/krb_admins/admin_commands/kpropd.rst deleted file mode 100644 index b5cebcc47..000000000 --- a/doc/rst_source/krb_admins/admin_commands/kpropd.rst +++ /dev/null @@ -1,123 +0,0 @@ -.. _kpropd(8): - -kpropd -====== - -SYNOPSIS --------- - -**kpropd** -[**-r** *realm*] -[**-a** *acl_file*] -[**-f** *slave_dumpfile*] -[**-F** *principal_database*] -[**-p** *kdb5_util_prog*] -[**-P** *port*] -[**-d**] - -DESCRIPTION ------------ - -The *kpropd* command runs on the slave KDC server. It listens for -update requests made by the :ref:`kprop(8)` program. If incremental -propagation is enabled, it periodically requests incremental updates -from the master KDC. - -When the slave receives a kprop request from the master, kpropd -accepts the dumped KDC database and places it in a file, and then runs -:ref:`kdb5_util(8)` to load the dumped database into the active -database which is used by :ref:`krb5kdc(8)`. This allows the master -Kerberos server to use :ref:`kprop(8)` to propagate its database to -the slave servers. Upon a successful download of the KDC database -file, the slave Kerberos server will have an up-to-date KDC database. - -Where incremental propagation is not used, kpropd is commonly invoked -out of inetd(8) as a nowait service. This is done by adding a line to -the ``/etc/inetd.conf`` file which looks like this: - - :: - - kprop stream tcp nowait root /usr/local/sbin/kpropd kpropd - -kpropd can also run as a standalone daemon. This is required for -incremental propagation. But this is also useful for debugging -purposes. - -Incremental propagation may be enabled with the **iprop_enable** -variable in :ref:`kdc.conf(5)`. If incremental propagation is -enabled, the slave periodically polls the master KDC for updates, at -an interval determined by the **iprop_slave_poll** variable. If the -slave receives updates, kpropd updates its log file with any updates -from the master. :ref:`kproplog(8)` can be used to view a summary of -the update entry log on the slave KDC. If incremental propagation is -enabled, the principal ``kiprop/slavehostname@REALM`` (where -*slavehostname* is the name of the slave KDC host, and *REALM* is the -name of the Kerberos realm) must be present in the slave's keytab -file. - -:ref:`kproplog(8)` can be used to force full replication when iprop is -enabled. - - -OPTIONS --------- - -**-r** *realm* - Specifies the realm of the master server. - -**-f** *file* - Specifies the filename where the dumped principal database file is - to be stored; by default the dumped database file is |kdcdir|\ - ``/from_master``. - -**-p** - Allows the user to specify the pathname to the :ref:`kdb5_util(8)` - program; by default the pathname used is |sbindir|\ - ``/kdb5_util``. - -**-S** - [DEPRECATED] Enable standalone mode. Normally kpropd is invoked by - inetd(8) so it expects a network connection to be passed to it - from inetd(8). If the **-S** option is specified, or if standard - input is not a socket, kpropd will put itself into the background, - and wait for connections on port 754 (or the port specified with the - **-P** option if given). - -**-d** - Turn on debug mode. In this mode, if the **-S** option is - selected, kpropd will not detach itself from the current job and - run in the background. Instead, it will run in the foreground and - print out debugging messages during the database propagation. - -**-P** - Allow for an alternate port number for kpropd to listen on. This - is only useful in combination with the **-S** option. - -**-a** *acl_file* - Allows the user to specify the path to the kpropd.acl file; by - default the path used is |kdcdir|\ ``/kpropd.acl``. - - -ENVIRONMENT ------------ - -kpropd uses the following environment variables: - -* **KRB5_CONFIG** -* **KRB5_KDC_PROFILE** - - -FILES ------ - -kpropd.acl - Access file for kpropd; the default location is - ``/usr/local/var/krb5kdc/kpropd.acl``. Each entry is a line - containing the principal of a host from which the local machine - will allow Kerberos database propagation via :ref:`kprop(8)`. - - -SEE ALSO --------- - -:ref:`kprop(8)`, :ref:`kdb5_util(8)`, :ref:`krb5kdc(8)`, inetd(8) diff --git a/doc/rst_source/krb_admins/admin_commands/kproplog.rst b/doc/rst_source/krb_admins/admin_commands/kproplog.rst deleted file mode 100644 index c7a0ea417..000000000 --- a/doc/rst_source/krb_admins/admin_commands/kproplog.rst +++ /dev/null @@ -1,87 +0,0 @@ -.. _kproplog(8): - -kproplog -======== - -SYNOPSIS --------- - -**kproplog** [**-h**] [**-e** *num*] [-v] -**kproplog** [-R] - - -DESCRIPTION ------------ - -The kproplog command displays the contents of the KDC database update -log to standard output. It can be used to keep track of incremental -updates to the principal database. The update log file contains the -update log maintained by the :ref:`kadmind(8)` process on the master -KDC server and the :ref:`kpropd(8)` process on the slave KDC servers. -When updates occur, they are logged to this file. Subsequently any -KDC slave configured for incremental updates will request the current -data from the master KDC and update their log file with any updates -returned. - -The kproplog command requires read access to the update log file. It -will display update entries only for the KDC it runs on. - -If no options are specified, kproplog displays a summary of the update -log. If invoked on the master, kproplog also displays all of the -update entries. If invoked on a slave KDC server, kproplog displays -only a summary of the updates, which includes the serial number of the -last update received and the associated time stamp of the last update. - - -OPTIONS -------- - -**-R** - Reset the update log. This forces full resynchronization. If used - on a slave then that slave will request a full resync. If used on - the master then all slaves will request full resyncs. - -**-h** - Display a summary of the update log. This information includes - the database version number, state of the database, the number of - updates in the log, the time stamp of the first and last update, - and the version number of the first and last update entry. - -**-e** *num* - Display the last *num* update entries in the log. This is useful - when debugging synchronization between KDC servers. - -**-v** - Display individual attributes per update. An example of the - output generated for one entry: - - :: - - Update Entry - Update serial # : 4 - Update operation : Add - Update principal : test@EXAMPLE.COM - Update size : 424 - Update committed : True - Update time stamp : Fri Feb 20 23:37:42 2004 - Attributes changed : 6 - Principal - Key data - Password last changed - Modifying principal - Modification time - TL data - - -ENVIRONMENT ------------ - -kproplog uses the following environment variables: - -* **KRB5_KDC_PROFILE** - - -SEE ALSO --------- - -:ref:`kpropd(8)` diff --git a/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst b/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst deleted file mode 100644 index 62afca4ee..000000000 --- a/doc/rst_source/krb_admins/admin_commands/krb5kdc.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. _krb5kdc(8): - -krb5kdc -======= - -SYNOPSIS --------- - -**krb5kdc** -[**-x** *db_args*] -[**-d** *dbname*] -[**-k** *keytype*] -[**-M** *mkeyname*] -[**-p** *portnum*] -[**-m**] -[**-r** *realm*] -[**-n**] -[**-w** *numworkers*] -[**-P** *pid_file*] -[**-T** *time_offset*] - - -DESCRIPTION ------------ - -krb5kdc is the Kerberos version 5 Authentication Service and Key -Distribution Center (AS/KDC). - - -OPTIONS -------- - -The **-r** *realm* option specifies the realm for which the server -should provide service. - -The **-d** *dbname* option specifies the name under which the -principal database can be found. This option does not apply to the -LDAP database. - -The **-k** *keytype* option specifies the key type of the master key -to be entered manually as a password when **-m** is given; the default -is ``des-cbc-crc``. - -The **-M** *mkeyname* option specifies the principal name for the -master key in the database (usually ``K/M`` in the KDC's realm). - -The **-m** option specifies that the master database password should -be fetched from the keyboard rather than from a stash file. - -The **-n** option specifies that the KDC does not put itself in the -background and does not disassociate itself from the terminal. In -normal operation, you should always allow the KDC to place itself in -the background. - -The **-P** *pid_file* option tells the KDC to write its PID into -*pid_file* after it starts up. This can be used to identify whether -the KDC is still running and to allow init scripts to stop the correct -process. - -The **-p** *portnum* option specifies the default UDP port numbers -which the KDC should listen on for Kerberos version 5 requests, as a -comma-separated list. This value overrides the UDP port numbers -specified in the :ref:`kdcdefaults` section of :ref:`kdc.conf(5)`, but -may be overridden by realm-specific values. If no value is given from -any source, the default ports are 88 and 750. - -The **-w** *numworkers* option tells the KDC to fork *numworkers* -processes to listen to the KDC ports and process requests in parallel. -The top level KDC process (whose pid is recorded in the pid file if -the **-P** option is also given) acts as a supervisor. The supervisor -will relay SIGHUP signals to the worker subprocesses, and will -terminate the worker subprocess if the it is itself terminated or if -any other worker process exits. - -.. note:: On operating systems which do not have *pktinfo* support, - using worker processes will prevent the KDC from listening - for UDP packets on network interfaces created after the KDC - starts. - -The **-x** *db_args* option specifies database-specific arguments. -Options supported for the LDAP database module are: - - **-x** nconns= - Specifies the number of connections to be maintained per - LDAP server. - - **-x** host= - Specifies the LDAP server to connect to by URI. - - **-x** binddn= - Specifies the DN of the object used by the KDC server to bind - to the LDAP server. This object should have read and write - privileges to the realm container, the principal container, - and the subtree that is referenced by the realm. - - **-x** bindpwd= - Specifies the password for the above mentioned binddn. Using - this option may expose the password to other users on the - system via the process list; to avoid this, instead stash the - password using the **stashsrvpw** command of - :ref:`kdb5_ldap_util(8)`. - -The **-T** *offset* option specifies a time offset, in seconds, which -the KDC will operate under. It is intended only for testing purposes. - -EXAMPLE -------- - -The KDC may service requests for multiple realms (maximum 32 realms). -The realms are listed on the command line. Per-realm options that can -be specified on the command line pertain for each realm that follows -it and are superseded by subsequent definitions of the same option. - -For example: - - :: - - krb5kdc -p 2001 -r REALM1 -p 2002 -r REALM2 -r REALM3 - -specifies that the KDC listen on port 2001 for REALM1 and on port 2002 -for REALM2 and REALM3. Additionally, per-realm parameters may be -specified in the :ref:`kdc.conf(5)` file. The location of this file -may be specified by the **KRB5_KDC_PROFILE** environment variable. -Per-realm parameters specified in this file take precedence over -options specified on the command line. See the :ref:`kdc.conf(5)` -description for further details. - - -ENVIRONMENT ------------ - -krb5kdc uses the following environment variables: - -* **KRB5_CONFIG** -* **KRB5_KDC_PROFILE** - - -SEE ALSO --------- - -:ref:`kdb5_util(8)`, :ref:`kdc.conf(5)`, :ref:`krb5.conf(5)`, -:ref:`kdb5_ldap_util(8)` diff --git a/doc/rst_source/krb_admins/admin_commands/ktutil.rst b/doc/rst_source/krb_admins/admin_commands/ktutil.rst deleted file mode 100644 index d55ddc894..000000000 --- a/doc/rst_source/krb_admins/admin_commands/ktutil.rst +++ /dev/null @@ -1,133 +0,0 @@ -.. _ktutil(1): - -ktutil -====== - -SYNOPSIS --------- - -**ktutil** - - -DESCRIPTION ------------ - -The ktutil command invokes a command interface from which an -administrator can read, write, or edit entries in a keytab or Kerberos -V4 srvtab file. - - -COMMANDS --------- - -list -~~~~ - - **list** - -Displays the current keylist. - -Alias: **l** - -read_kt -~~~~~~~ - - **read_kt** *keytab* - -Read the Kerberos V5 keytab file *keytab* into the current keylist. - -Alias: **rkt** - -read_st -~~~~~~~ - - **read_st** *srvtab* - -Read the Kerberos V4 srvtab file *srvtab* into the current keylist. - -Alias: **rst** - -write_kt -~~~~~~~~ - - **write_kt** *keytab* - -Write the current keylist into the Kerberos V5 keytab file *keytab*. - -Alias: **wkt** - -write_st -~~~~~~~~ - - **write_st** *srvtab* - -Write the current keylist into the Kerberos V4 srvtab file *srvtab*. - -Alias: **wst** - -clear_list -~~~~~~~~~~ - - **clear_list** - -Clear the current keylist. - -Alias: **clear** - -delete_entry -~~~~~~~~~~~~ - - **delete_entry** *slot* - -Delete the entry in slot number *slot* from the current keylist. - -Alias: **delent** - -add_entry -~~~~~~~~~ - - **add_entry** {**-key**\|\ **-password**} **-p** *principal* - **-k** *kvno* **-e** *enctype* - -Add *principal* to keylist using key or password. - -Alias: **addent** - -list_requests -~~~~~~~~~~~~~ - - **list_requests** - -Displays a listing of available commands. - -Aliases: **lr**, **?** - -quit -~~~~ - - **quit** - -Quits ktutil. - -Aliases: **exit**, **q** - - -EXAMPLE -------- - - :: - - ktutil: add_entry -password -p alice@BLEEP.COM -k 1 -e - aes128-cts-hmac-sha1-96 - Password for alice@BLEEP.COM: - ktutil: add_entry -password -p alice@BLEEP.COM -k 1 -e - aes256-cts-hmac-sha1-96 - Password for alice@BLEEP.COM: - ktutil: write_kt keytab - ktutil: - - -SEE ALSO --------- - -:ref:`kadmin(1)`, :ref:`kdb5_util(8)` diff --git a/doc/rst_source/krb_admins/admin_commands/sserver.rst b/doc/rst_source/krb_admins/admin_commands/sserver.rst deleted file mode 100644 index 61826dfaf..000000000 --- a/doc/rst_source/krb_admins/admin_commands/sserver.rst +++ /dev/null @@ -1,121 +0,0 @@ -.. _sserver(8): - -sserver -======= - -SYNOPSIS --------- - -**sserver** -[ **-p** *port* ] -[ **-S** *keytab* ] -[ *server_port* ] - - -DESCRIPTION ------------ - -sserver and :ref:`sclient(1)` are a simple demonstration client/server -application. When sclient connects to sserver, it performs a Kerberos -authentication, and then sserver returns to sclient the Kerberos -principal which was used for the Kerberos authentication. It makes a -good test that Kerberos has been successfully installed on a machine. - -The service name used by sserver and sclient is sample. Hence, -sserver will require that there be a keytab entry for the service -``sample/hostname.domain.name@REALM.NAME``. This keytab is generated -using the :ref:`kadmin(1)` program. The keytab file is usually -installed as |keytab|. - -The **-S** option allows for a different keytab than the default. - -sserver is normally invoked out of inetd(8), using a line in -``/etc/inetd.conf`` that looks like this: - - :: - - sample stream tcp nowait root /usr/local/sbin/sserver sserver - -Since ``sample`` is normally not a port defined in ``/etc/services``, -you will usually have to add a line to ``/etc/services`` which looks -like this: - - :: - - sample 13135/tcp - -When using sclient, you will first have to have an entry in the -Kerberos database, by using :ref:`kadmin(1)`, and then you have to get -Kerberos tickets, by using :ref:`kinit(1)`. Also, if you are running -the sclient program on a different host than the sserver it will be -connecting to, be sure that both hosts have an entry in /etc/services -for the sample tcp port, and that the same port number is in both -files. - -When you run sclient you should see something like this: - - :: - - sendauth succeeded, reply is: - reply len 32, contents: - You are nlgilman@JIMI.MIT.EDU - - -COMMON ERROR MESSAGES ---------------------- - -1) kinit returns the error: - - :: - - kinit: Client not found in Kerberos database while getting - initial credentials - - This means that you didn't create an entry for your username in the - Kerberos database. - -2) sclient returns the error: - - :: - - unknown service sample/tcp; check /etc/services - - This means that you don't have an entry in /etc/services for the - sample tcp port. - -3) sclient returns the error: - - :: - - connect: Connection refused - - This probably means you didn't edit /etc/inetd.conf correctly, or - you didn't restart inetd after editing inetd.conf. - -4) sclient returns the error: - - :: - - sclient: Server not found in Kerberos database while using - sendauth - - This means that the ``sample/hostname@LOCAL.REALM`` service was not - defined in the Kerberos database; it should be created using - :ref:`kadmin(1)`, and a keytab file needs to be generated to make - the key for that service principal available for sclient. - -5) sclient returns the error: - - :: - - sendauth rejected, error reply is: - "No such file or directory" - - This probably means sserver couldn't find the keytab file. It was - probably not installed in the proper directory. - - -SEE ALSO --------- - -:ref:`sclient(1)`, services(5), inetd(8) diff --git a/doc/rst_source/krb_admins/advanced/index.rst b/doc/rst_source/krb_admins/advanced/index.rst deleted file mode 100644 index 20112bd2d..000000000 --- a/doc/rst_source/krb_admins/advanced/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -Advanced topics -=============== - - -.. toctree:: - :maxdepth: 1 - - ldapbackend.rst - retiring-des.rst - diff --git a/doc/rst_source/krb_admins/advanced/ldapbackend.rst b/doc/rst_source/krb_admins/advanced/ldapbackend.rst deleted file mode 100644 index 59c9eaa3c..000000000 --- a/doc/rst_source/krb_admins/advanced/ldapbackend.rst +++ /dev/null @@ -1,143 +0,0 @@ -.. _ldap_be_ubuntu: - -LDAP backend on Ubuntu 10.4 (lucid) -=================================== - -Setting up Kerberos v1.9 with LDAP backend on Ubuntu 10.4 (Lucid Lynx) - - -Prerequisites -------------- - -Install the following packages: *slapd, ldap-utils* and *libldap2-dev* - -You can install the necessary packages with these commands:: - - sudo apt-get install slapd - sudo apt-get install ldap-utils - sudo apt-get install libldap2-dev - -Extend the user schema using schemas from standart OpenLDAP -distribution: *cosine, mics, nis, inetcomperson* :: - - ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/cosine.ldif - ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/mics.ldif - ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/nis.ldif - ldapadd -Y EXTERNAL -H ldapi:/// -f /etc/ldap/schema/inetcomperson.ldif - - -Building Kerberos from source ------------------------------ - -:: - - ./configure --with-ldap - make - sudo make install - - -Setting up Kerberos -------------------- - -Configuration -~~~~~~~~~~~~~ - -Update kdc.conf with the LDAP back-end information:: - - [realms] - EXAMPLE.COM = { - database_module = LDAP - } - - [dbmodules] - LDAP = { - db_library = kldap - ldap_kerberos_container_dn = cn=krbContainer,dc=example,dc=com - ldap_kdc_dn = cn=admin,dc=example,dc=com - ldap_kadmind_dn = cn=admin,dc=example,dc=com - ldap_service_password_file = /usr/local/var/krb5kdc/admin.stash - ldap_servers = ldapi:/// - } - - -Schema -~~~~~~ - -From the source tree copy -``src/plugins/kdb/ldap/libkdb_ldap/kerberos.schema`` into -``/etc/ldap/schema`` - -Warning: this step should be done after slapd is installed to avoid -problems with slapd installation. - -To convert kerberos.schema to run-time configuration (``cn=config``) -do the following: - -#. Create a temporary file ``/tmp/schema_convert.conf`` with the - following content:: - - include /etc/ldap/schema/kerberos.schema - -#. Create a temporary directory ``/tmp/krb5_ldif``. - -#. Run:: - - slaptest -f /tmp/schema_convert.conf -F /tmp/krb5_ldif - - This should in a new file named - ``/tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif``. - -#. Edit ``/tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif`` by - replacing the lines:: - - dn: cn={0}kerberos - cn: {0}kerberos - - with - - dn: cn=kerberos,cn=schema,cn=config - cn: kerberos - - Also, remove following attribute-value pairs:: - - structuralObjectClass: olcSchemaConfig - entryUUID: ... - creatorsName: cn=config - createTimestamp: ... - entryCSN: ... - modifiersName: cn=config - modifyTimestamp: ... - -#. Load the new schema with ldapadd (with the proper authentication):: - - ldapadd -Y EXTERNAL -H ldapi:/// -f /tmp/krb5_ldif/cn=config/cn=schema/cn={0}kerberos.ldif - - which should result the message ``adding new entry - "cn=kerberos,cn=schema,cn=config"``. - - -Create Kerberos database ------------------------- - -Using LDAP administrator credentials, create Kerberos database and -master key stash:: - - kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// create -s - -Stash the LDAP administrative passwords:: - - kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// stashsrvpw cn=admin,dc=example,dc=com - -Start :ref:`krb5kdc(8)`:: - - krb5kdc - -To destroy database run:: - - kdb5_ldap_util -D cn=admin,dc=example,dc=com -H ldapi:/// destroy -f - - -Useful references ------------------ - -* `Kerberos and LDAP `_ diff --git a/doc/rst_source/krb_admins/advanced/retiring-des.rst b/doc/rst_source/krb_admins/advanced/retiring-des.rst deleted file mode 100644 index 30f96776f..000000000 --- a/doc/rst_source/krb_admins/advanced/retiring-des.rst +++ /dev/null @@ -1,129 +0,0 @@ -.. _retiring-des: - -Retiring DES -======================= - -Version 5 of the Kerberos protocol was originally implemented using -the Data Encryption Standard (DES) as a block cipher for encryption. -While it was considered secure at the time, advancements in computational -ability have rendered it vulnerable to brute force attacks on its 56-bit -keyspace. As such, it is now considered insecure and should not be -used (:rfc:`6649`). - -History -------- - -DES was used in the original Kerberos implementation, and was the -only cryptosystem in krb5 1.0. Partial support for triple-DES (3DES) was -added in version 1.1, with full support following in version 1.2. -The Advanced Encryption Standard (AES), which supersedes DES, gained -partial support in version 1.3.0 of krb5 and full support in version 1.3.2. -However, deployments of krb5 using Kerberos databases created with older -versions of krb5 will not necessarily start using strong crypto for -ordinary operation without administrator intervention. - -Types of keys -------------- - -The entire Kerberos database is encrypted using the database master -key, presently stored as ``K/M`` by default. Each entry in the -Kerberos database has a set of keys with different encryption types, -corresponding to that principal's current key version number. -For a user principal, these keys are derived from the user's password -via the various string2key functions for those encryption types; -for a service principal with keys stored in a keytab, the keys of -different encryption types are all stored in the keytab. -When a new principal is added or a principal's key is updated (for -example, due to a user password change), new keys are generated for -that principal with all of the different encryption types that the -KDC is configured to use (the **supported_enctypes** variable in kdc.conf). -This list can be overridden on a case-by-case basis using arguments -to :ref:`kadmin(1)`. - -When a Kerberos client initiates a Kerberos transaction, the client -requests a service ticket for a given service from the KDC; this service -ticket will contain only a single key, of a particular encryption type. -When sending its request to the KDC, the client can request a particular -list of encryption types, as controlled by the client machine's -:ref:`krb5.conf(5)` configuration file or specific API calls in the -client software. -To choose the encryption type for the service ticket's key, the KDC -must accomodate the client's preference and also confirm that the service -principal has a key in the Kerberos database of that encryption type. -Note that the encryption types supported by the krb5 installation on -the server that will receive the service ticket is not a factor in -the KDC's choice of encryption type; this information is not available -in the Kerberos protocol. In order to allow uninterrupted operation to -clients while migrating away from DES, care must be taken to ensure that -the krb5 installation on server machines is configured to support newer -encryption types before keys of those new encryption types are created -in the Kerberos database for those server principals. - -Upgrade procedure ------------------ - -This procedure assumes that the KDC software has already been upgraded -to a modern version of krb5 that supports non-DES keys, so that the -only remaining task is to update the actual keys used to service requests. - -While it is possible to upgrade individual service principals to non-DES -keys before transitioning the entire realm, it is probably best to -start with upgrading the key for the ticket-granting service principal, -``krbtgt/REALM``. Since the server that will handle service tickets -for this principal is the KDC itself, it is easy to guarantee that it -will be configured to support any encryption types which might be -selected. However, just creating a new key version (and new keys) for -that principal will invalidate all existing tickets issued against that -principal, which in practice means all tickets obtained by clients. -Instead, a new key can be created with the old key retained, so that -existing tickets will still function until their scheduled expiry -(see :ref:`changing_krbtgt_key`). - -Once the krbtgt key is updated, users will get non-DES (usually AES in -modern releases) session keys for their TGT, but subsequent requests -for service tickets will still get DES keys, because the database -entry for the service principal still only has DES keys. Application service -remains uninterrupted due to the key-selection procedure on the KDC. - -At this point, service administrators can update their services and the -servers behind them. If necessary, the krb5 installation should be -upgraded to a version supporting non-DES keys, and :ref:`krb5.conf(5)` -edited so that the default enctype list includes the additional enctypes -needed. Only when the service is configured to accept non-DES keys should -the key version number be incremented and new keys generated. -Until the KDC's configuration is changed to generate non-DES keys by -default, it is necessary to use :ref:`kadmin(1)` to produce new keys -with the desired enctypes; the ``-keepold`` functionality may also be -desired in some cases. When a single service principal is shared by -multiple backend servers in a load-balanced environment, it may be -necessary to schedule downtime or adjust the population in the load-balanced -pool in order to propagate the updated keytab to all hosts in the pool -with minimal service interruption. - -Once the high-visibility services have been rekeyed, it is probably -appropriate to change :ref:`kdc.conf(5)` to generate keys with the new -encryption types by default. This enables server administrators to generate -new keys with :ref:`k5srvutil(1)` ``change``, and causes user password -changes to add new encryption types for their entries. It will probably -be necessary to implement administrative controls to cause all user -principal keys to be updated in a reasonable period of time, whether -by forcing password changes or a password synchronization service that -has access to the current password and can add the new keys. - -Once all principals have been re-keyed, DES support can be disabled on the -KDC, and client machines can remove **allow_weak_crypto = true** from -their :ref:`krb5.conf(5)` configuration files, completing the migration. -For completeness, the kadmin **purgekeys** command should be used to -remove the old keylist for ``krbtgt/REALM`` which includes the single-DES -key(s), though the KDC will only issue new tickets using the highest -available kvno, which at this point does not have single-DES keys available. - -This procedure does not alter ``K/M@REALM``, the key used to encrypt the -Kerberos database itself. (This is the key stored in the stash file -on the KDC if stash files are used.) However, the security risk of -a single-DES key for ``K/M`` is minimal, given that access to material -encrypted in ``K/M`` (the Kerberos database) is generally tightly controlled. -If an attacker can gain access to the encrypted database, they likely -have access to the stash file as well, rendering the weak cryptography -broken by non-cryptographic means. As such, upgrading ``K/M`` to a stronger -encryption type is unlikely to be a high-priority task. diff --git a/doc/rst_source/krb_admins/appl_servers.rst b/doc/rst_source/krb_admins/appl_servers.rst deleted file mode 100644 index f6474cdbd..000000000 --- a/doc/rst_source/krb_admins/appl_servers.rst +++ /dev/null @@ -1,147 +0,0 @@ -Application servers -=================== - -If you need to install the Kerberos V5 programs on an application -server, please refer to the Kerberos V5 Installation Guide. Once you -have installed the software, you need to add that host to the Kerberos -database (see :ref:`add_mod_del_princs`), and generate a keytab for -that host, that contains the host's key. You also need to make sure -the host's clock is within your maximum clock skew of the KDCs. - - -Keytabs -------- - -A keytab is a host's copy of its own keylist, which is analogous to a -user's password. An application server that needs to authenticate -itself to the KDC has to have a keytab that contains its own principal -and key. Just as it is important for users to protect their -passwords, it is equally important for hosts to protect their keytabs. -You should always store keytab files on local disk, and make them -readable only by root, and you should never send a keytab file over a -network in the clear. Ideally, you should run the :ref:`kadmin(1)` -command to extract a keytab on the host on which the keytab is to -reside. - - -.. _add_princ_kt: - -Adding principals to keytabs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To generate a keytab, or to add a principal to an existing keytab, use -the **ktadd** command from kadmin. - -.. include:: admin_commands/kadmin_local.rst - :start-after: _ktadd: - :end-before: _ktadd_end: - - -Examples -######## - -Here is a sample session, using configuration files that enable only -AES encryption:: - - kadmin: ktadd host/daffodil.mit.edu@ATHENA.MIT.EDU - Entry for principal host/daffodil.mit.edu with kvno 2, encryption type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab - Entry for principal host/daffodil.mit.edu with kvno 2, encryption type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab - kadmin: - - -Removing principals from keytabs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To remove a principal from an existing keytab, use the kadmin -**ktremove** command. - -.. include:: admin_commands/kadmin_local.rst - :start-after: _ktremove: - :end-before: _ktremove_end: - - -Clock Skew ----------- - -A Kerberos application server host must keep its clock synchronized or -it will reject authentication requests from clients. Modern operating -systems typically provide a facility to maintain the correct time; -make sure it is enabled. This is especially important on virtual -machines, where clocks tend to drift more rapidly than normal machine -clocks. - -The default allowable clock skew is controlled by the **clockskew** -variable in :ref:`libdefaults`. - - -Getting DNS information correct -------------------------------- - -Several aspects of Kerberos rely on name service. When a hostname is -used to name a service, the Kerberos library canonicalizes the -hostname using forward and reverse name resolution. (The reverse name -resolution step can be turned off using the **rdns** variable in -:ref:`libdefaults`.) The result of this canonicalization must match -the principal entry in the host's keytab, or authentication will fail. - -Each host's canonical name must be the fully-qualified host name -(including the domain), and each host's IP address must -reverse-resolve to the canonical name. - -Configuration of hostnames varies by operating system. On the -application server itself, canonicalization will typically use the -``/etc/hosts`` file rather than the DNS. Ensure that the line for the -server's hostname is in the following form:: - - IP address fully-qualified hostname aliases - -Here is a sample ``/etc/hosts`` file:: - - # this is a comment - 127.0.0.1 localhost localhost.mit.edu - 10.0.0.6 daffodil.mit.edu daffodil trillium wake-robin - -The output of ``klist -k`` for this example host should look like:: - - viola# klist -k - Keytab name: /etc/krb5.keytab - KVNO Principal - ---- ------------------------------------------------------------ - 2 host/daffodil.mit.edu@ATHENA.MIT.EDU - -If you were to ssh to this host with a fresh credentials cache (ticket -file), and then :ref:`klist(1)`, the output should list a service -principal of ``host/daffodil.mit.edu@ATHENA.MIT.EDU``. - - -.. _conf_firewall: - -Configuring your firewall to work with Kerberos V5 --------------------------------------------------- - -If you need off-site users to be able to get Kerberos tickets in your -realm, they must be able to get to your KDC. This requires either -that you have a slave KDC outside your firewall, or that you configure -your firewall to allow UDP requests into at least one of your KDCs, on -whichever port the KDC is running. (The default is port 88; other -ports may be specified in the KDC's :ref:`kdc.conf(5)` file.) -Similarly, if you need off-site users to be able to change their -passwords in your realm, they must be able to get to your Kerberos -admin server on the kpasswd port (which defaults to 464). If you need -off-site users to be able to administer your Kerberos realm, they must -be able to get to your Kerberos admin server on the administrative -port (which defaults to 749). - -If your on-site users inside your firewall will need to get to KDCs in -other realms, you will also need to configure your firewall to allow -outgoing TCP and UDP requests to port 88, and to port 464 to allow -password changes. If your on-site users inside your firewall will -need to get to Kerberos admin servers in other realms, you will also -need to allow outgoing TCP and UDP requests to port 749. - -If any of your KDCs are outside your firewall, you will need to allow -kprop requests to get through to the remote KDC. :ref:`kprop(8)` uses -the ``krb5_prop`` service on port 754 (tcp). - -The book *UNIX System Security*, by David Curry, is a good starting -point for learning to configure firewalls. diff --git a/doc/rst_source/krb_admins/backup_host.rst b/doc/rst_source/krb_admins/backup_host.rst deleted file mode 100644 index a0c2a2878..000000000 --- a/doc/rst_source/krb_admins/backup_host.rst +++ /dev/null @@ -1,34 +0,0 @@ -Backups of secure hosts -======================= - -When you back up a secure host, you should exclude the host's keytab -file from the backup. If someone obtained a copy of the keytab from a -backup, that person could make any host masquerade as the host whose -keytab was compromised. In many configurations, knowledge of the -host's keytab also allows root access to the host. This could be -particularly dangerous if the compromised keytab was from one of your -KDCs. If the machine has a disk crash and the keytab file is lost, it -is easy to generate another keytab file. (See :ref:`add_princ_kt`.) -If you are unable to exclude particular files from backups, you should -ensure that the backups are kept as secure as the host's root -password. - - -Backing up the Kerberos database --------------------------------- - -As with any file, it is possible that your Kerberos database could -become corrupted. If this happens on one of the slave KDCs, you might -never notice, since the next automatic propagation of the database -would install a fresh copy. However, if it happens to the master KDC, -the corrupted database would be propagated to all of the slaves during -the next propagation. For this reason, MIT recommends that you back -up your Kerberos database regularly. Because the master KDC is -continuously dumping the database to a file in order to propagate it -to the slave KDCs, it is a simple matter to have a cron job -periodically copy the dump file to a secure machine elsewhere on your -network. (Of course, it is important to make the host where these -backups are stored as secure as your KDCs, and to encrypt its -transmission across your network.) Then if your database becomes -corrupted, you can load the most recent dump onto the master KDC. -(See :ref:`restore_from_dump`.) diff --git a/doc/rst_source/krb_admins/conf_files/index.rst b/doc/rst_source/krb_admins/conf_files/index.rst deleted file mode 100644 index 078a17304..000000000 --- a/doc/rst_source/krb_admins/conf_files/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -Configuration Files -=================== - -.. toctree:: - :maxdepth: 1 - - krb5_conf - kdc_conf - kadm5_acl diff --git a/doc/rst_source/krb_admins/conf_files/kadm5_acl.rst b/doc/rst_source/krb_admins/conf_files/kadm5_acl.rst deleted file mode 100644 index 4a8e0741e..000000000 --- a/doc/rst_source/krb_admins/conf_files/kadm5_acl.rst +++ /dev/null @@ -1,136 +0,0 @@ -.. _kadm5.acl(5): - -kadm5.acl -========= - -DESCRIPTION ------------ - -The Kerberos :ref:`kadmind(8)` daemon uses an Access Control List -(ACL) file to manage access rights to the Kerberos database. -For operations that affect principals, the ACL file also controls -which principals can operate on which other principals. - -The default location of the Kerberos ACL file is -|kdcdir|\ ``/kadm5.acl`` unless this is overridden by the *acl_file* -variable in :ref:`kdc.conf(5)`. - -SYNTAX ------- - -Empty lines and lines starting with the sharp sign (``#``) are -ignored. Lines containing ACL entries have the format: - - :: - - principal permissions [target_principal [restrictions] ] - -.. note:: Line order in the ACL file is important. The first matching entry - will control access for an actor principal on a target principal. - -*principal* - (Partially or fully qualified Kerberos principal name.) Specifies - the principal whose permissions are to be set. - - Each component of the name may be wildcarded using the ``*`` - character. - -*permissions* - Specifies what operations may or may not be performed by a - *principal* matching a particular entry. This is a string of one or - more of the following list of characters or their upper-case - counterparts. If the character is *upper-case*, then the operation - is disallowed. If the character is *lower-case*, then the operation - is permitted. - - == ====================================================== - a [Dis]allows the addition of principals or policies - c [Dis]allows the changing of passwords for principals - d [Dis]allows the deletion of principals or policies - i [Dis]allows inquiries about principals or policies - l [Dis]allows the listing of principals or policies - m [Dis]allows the modification of principals or policies - p [Dis]allows the propagation of the principal database (used in :ref:`incr_db_prop`) - s [Dis]allows the explicit setting of the key for a principal - x Short for admcil. All privileges - \* Same as x. - == ====================================================== - - -*target_principal* - (Optional. Partially or fully qualified Kerberos principal name.) - Specifies the principal on which *permissions* may be applied. - Each component of the name may be wildcarded using the ``*`` - character. - - *target_principal* can also include back-references to *principal*, - in which ``*number`` matches the component number in *principal*. - -*restrictions* - (Optional) A string of flags. Allowed restrictions are: - - {+\|-}\ *flagname* - flag is forced to the indicated value. The permissible flags - are the same as the + and - flags for the kadmin - :ref:`add_principal` and :ref:`modify_principal` commands. - - *-clearpolicy* - policy is forced to be empty. - - *-policy pol* - policy is forced to be *pol*. - - -{*expire, pwexpire, maxlife, maxrenewlife*} *time* - (:ref:`getdate` string) associated value will be forced to - MIN(*time*, requested value). - - The above flags act as restrictions on any add or modify operation - which is allowed due to that ACL line. - -.. warning:: - If the kadmind ACL file is modified, the kadmind daemon needs to be - restarted for changes to take effect. - -EXAMPLE -------- - -Here is an example of a kadm5.acl file. - - :: - - */admin@ATHENA.MIT.EDU * # line 1 - joeadmin@ATHENA.MIT.EDU ADMCIL # line 2 - joeadmin/*@ATHENA.MIT.EDU il */root@ATHENA.MIT.EDU # line 3 - */root@ATHENA.MIT.EDU cil *1@ATHENA.MIT.EDU # line 4 - */*@ATHENA.MIT.EDU i # line 5 - */admin@EXAMPLE.COM x * -maxlife 9h -postdateable # line 6 - -(line 1) Any principal in the ``ATHENA.MIT.EDU`` realm with -an ``admin`` instance has all administrative privileges. - -(lines 1-3) The user ``joeadmin`` has all permissions with his -``admin`` instance, ``joeadmin/admin@ATHENA.MIT.EDU`` (matches line -1). He has no permissions at all with his null instance, -``joeadmin@ATHENA.MIT.EDU`` (matches line 2). His ``root`` and other -non-``admin``, non-null instances (e.g., ``extra`` or ``dbadmin``) have -inquire and list permissions with any principal that has the -instance ``root`` (matches line 3). - -(line 4) Any ``root`` principal in ``ATHENA.MIT.EDU`` can inquire, list, -or change the password of their null instance, but not any other -null instance. (Here, "\*1" denotes a back-reference to the first -component of the actor principal.) - -(line 5) Any principal in the realm ``ATHENA.MIT.EDU`` (except for -``joeadmin@ATHENA.MIT.EDU``, as mentioned above) has inquire -privileges. - -(line 6) Finally, any principal with an ``admin`` instance in ``EXAMPLE.COM`` -has all permissions, but any principal that they create or modify will -not be able to get postdateable tickets or tickets with a life of -longer than 9 hours. - -SEE ALSO --------- - -:ref:`kdc.conf(5)`, :ref:`kadmind(8)` diff --git a/doc/rst_source/krb_admins/conf_files/kdc_conf.rst b/doc/rst_source/krb_admins/conf_files/kdc_conf.rst deleted file mode 100644 index 7ded12dc0..000000000 --- a/doc/rst_source/krb_admins/conf_files/kdc_conf.rst +++ /dev/null @@ -1,711 +0,0 @@ -.. _kdc.conf(5): - -kdc.conf -======== - -The kdc.conf file supplements :ref:`krb5.conf(5)` for programs which -are typically only used on a KDC, such as the :ref:`krb5kdc(8)` and -:ref:`kadmind(8)` daemons and the :ref:`kdb5_util(8)` program. -Relations documented here may also be specified in krb5.conf. - -Normally, the kdc.conf file is found in the KDC state directory, -|kdcdir|. You can override the default location by setting the -environment variable **KRB5_KDC_PROFILE**. - -Please note that you need to restart the KDC daemon for any configuration -changes to take effect. - -Structure ---------- - -The kdc.conf file is set up in the same format as the -:ref:`krb5.conf(5)` file. - - -Sections --------- - -The kdc.conf file may contain the following sections: - -==================== ================================================= -:ref:`kdcdefaults` Default values for KDC behavior -:ref:`kdc_realms` Realm-specific database configuration and settings -:ref:`dbdefaults` Default database settings -:ref:`dbmodules` Per-database settings -:ref:`logging` Controls how Kerberos daemons perform logging -==================== ================================================= - - -.. _kdcdefaults: - -[kdcdefaults] -~~~~~~~~~~~~~ - -With one exception, relations in the [kdcdefaults] section specify -default values for realm variables, to be used if the [realms] -subsection does not contain a relation for the tag. See the -:ref:`kdc_realms` section for the definitions of these relations. - -* **host_based_services** -* **kdc_ports** -* **kdc_tcp_ports** -* **no_host_referral** -* **restrict_anonymous_to_tgt** - -**kdc_max_dgram_reply_size** - Specifies the maximum packet size that can be sent over UDP. The - default value is 4096 bytes. - - -.. _kdc_realms: - -[realms] -~~~~~~~~ - -Each tag in the [realms] section is the name of a Kerberos realm. -The value of the tag is a subsection where the relations define KDC -parameters for that particular realm. - -For each realm, the following tags may be specified: - -**acl_file** - (String.) Location of the access control list file that - :ref:`kadmind(8)` uses to determine which principals are allowed - which permissions on the Kerberos database. The default value is - |kdcdir|\ ``/kadm5.acl``. For more information on Kerberos ACL - file see :ref:`kadm5.acl(5)`. - -**database_module** - This relation indicates the name of the configuration section - under :ref:`dbmodules` for database specific parameters used by - the loadable database library. - -**database_name** - (String.) This string specifies the location of the Kerberos - database for this realm, if the DB2 back-end is being used. If a - **database_module** is specified for the realm and the - corresponding module contains a **database_name** parameter, that - value will take precedence over this one. The default value is - |kdcdir|\ ``/principal``. - -**default_principal_expiration** - (:ref:`abstime` string.) Specifies the default expiration date of - principals created in this realm. The default value is 0, which - means no expiration date. - -**default_principal_flags** - (Flag string.) Specifies the default attributes of principals - created in this realm. The format for this string is a - comma-separated list of flags, with '+' before each flag that - should be enabled and '-' before each flag that should be - disabled. The **postdateable**, **forwardable**, **tgt-based**, - **renewable**, **proxiable**, **dup-skey**, **allow-tickets**, and - **service** flags default to enabled. - - There are a number of possible flags: - - **allow-tickets** - Enabling this flag means that the KDC will issue tickets for - this principal. Disabling this flag essentially deactivates - the principal within this realm. - - **dup-skey** - Enabling this flag allows the principal to obtain a session - key for another user, permitting user-to-user authentication - for this principal. - - **forwardable** - Enabling this flag allows the principal to obtain forwardable - tickets. - - **hwauth** - If this flag is enabled, then the principal is required to - preauthenticate using a hardware device before receiving any - tickets. - - **no-auth-data-required** - Enabling this flag prevents PAC data from being added to - service tickets for the principal. - - **ok-as-delegate** - If this flag is enabled, it hints the client that credentials - can and should be delegated when authenticating to the - service. - - **ok-to-auth-as-delegate** - Enabling this flag allows the principal to use S4USelf tickets. - - **postdateable** - Enabling this flag allows the principal to obtain postdateable - tickets. - - **preauth** - If this flag is enabled on a client principal, then that - principal is required to preauthenticate to the KDC before - receiving any tickets. On a service principal, enabling this - flag means that service tickets for this principal will only - be issued to clients with a TGT that has the preauthenticated - bit set. - - **proxiable** - Enabling this flag allows the principal to obtain proxy - tickets. - - **pwchange** - Enabling this flag forces a password change for this - principal. - - **pwservice** - If this flag is enabled, it marks this principal as a password - change service. This should only be used in special cases, - for example, if a user's password has expired, then the user - has to get tickets for that principal without going through - the normal password authentication in order to be able to - change the password. - - **renewable** - Enabling this flag allows the principal to obtain renewable - tickets. - - **service** - Enabling this flag allows the the KDC to issue service tickets - for this principal. - - **tgt-based** - Enabling this flag allows a principal to obtain tickets based - on a ticket-granting-ticket, rather than repeating the - authentication process that was used to obtain the TGT. - -**dict_file** - (String.) Location of the dictionary file containing strings that - are not allowed as passwords. If none is specified or if there is - no policy assigned to the principal, no dictionary checks of - passwords will be performed. - -**host_based_services** - (Whitespace- or comma-separated list.) Lists services which will - get host-based referral processing even if the server principal is - not marked as host-based by the client. - -**iprop_enable** - (Boolean value.) Specifies whether incremental database - propagation is enabled. The default value is false. - -**iprop_master_ulogsize** - (Integer.) Specifies the maximum number of log entries to be - retained for incremental propagation. The maximum value is 2500; - the default value is 1000. - -**iprop_slave_poll** - (Delta time string.) Specifies how often the slave KDC polls for - new updates from the master. The default value is ``2m`` (that - is, two minutes). - -**iprop_port** - (Port number.) Specifies the port number to be used for - incremental propagation. This is required in both master and - slave configuration files. - -**iprop_resync_timeout** - (Delta time string.) Specifies the amount of time to wait for a - full propagation to complete. This is optional in configuration - files, and is used by slave KDCs only. The default value is 5 - minutes (``5m``). - -**iprop_logfile** - (File name.) Specifies where the update log file for the realm - database is to be stored. The default is to use the - **database_name** entry from the realms section of the krb5 config - file, with ``.ulog`` appended. (NOTE: If **database_name** isn't - specified in the realms section, perhaps because the LDAP database - back end is being used, or the file name is specified in the - [dbmodules] section, then the hard-coded default for - **database_name** is used. Determination of the **iprop_logfile** - default value will not use values from the [dbmodules] section.) - -**kadmind_port** - (Port number.) Specifies the port on which the :ref:`kadmind(8)` - daemon is to listen for this realm. The assigned port for kadmind - is 749, which is used by default. - -**key_stash_file** - (String.) Specifies the location where the master key has been - stored (via kdb5_util stash). The default is |kdcdir|\ - ``/.k5.REALM``, where *REALM* is the Kerberos realm. - -**kdc_ports** - (Whitespace- or comma-separated list.) Lists the ports on which - the Kerberos server should listen for UDP requests, as a - comma-separated list of integers. The default value is - ``88,750``, which are the assigned Kerberos port and the port - historically used by Kerberos V4. - -**kdc_tcp_ports** - (Whitespace- or comma-separated list.) Lists the ports on which - the Kerberos server should listen for TCP connections, as a - comma-separated list of integers. If this relation is not - specified, the compiled-in default is not to listen for TCP - connections at all. - - If you wish to change this (note that the current implementation - has little protection against denial-of-service attacks), the - standard port number assigned for Kerberos TCP traffic is port 88. - -**master_key_name** - (String.) Specifies the name of the principal associated with the - master key. The default is ``K/M``. - -**master_key_type** - (Key type string.) Specifies the master key's key type. The - default value for this is |defmkey|. For a list of all possible - values, see :ref:`Encryption_and_salt_types`. - -**max_life** - (:ref:`duration` string.) Specifies the maximum time period for - which a ticket may be valid in this realm. The default value is - 24 hours. - -**max_renewable_life** - (:ref:`duration` string.) Specifies the maximum time period - during which a valid ticket may be renewed in this realm. - The default value is 0. - -**no_host_referral** - (Whitespace- or comma-separated list.) Lists services to block - from getting host-based referral processing, even if the client - marks the server principal as host-based or the service is also - listed in **host_based_services**. ``no_host_referral = *`` will - disable referral processing altogether. - -**des_crc_session_supported** - (Boolean value). If set to true, the KDC will assume that service - principals support des-cbc-crc for session key enctype negotiation - purposes. If **allow_weak_crypto** in :ref:`libdefaults` is - false, or if des-cbc-crc is not a permitted enctype, then this - variable has no effect. Defaults to true. - -**reject_bad_transit** - (Boolean value.) If set to true, the KDC will check the list of - transited realms for cross-realm tickets against the transit path - computed from the realm names and the capaths section of its - :ref:`krb5.conf(5)` file; if the path in the ticket to be issued - contains any realms not in the computed path, the ticket will not - be issued, and an error will be returned to the client instead. - If this value is set to false, such tickets will be issued - anyways, and it will be left up to the application server to - validate the realm transit path. - - If the disable-transited-check flag is set in the incoming - request, this check is not performed at all. Having the - **reject_bad_transit** option will cause such ticket requests to - be rejected always. - - This transit path checking and config file option currently apply - only to TGS requests. - - The default value is true. - -**restrict_anonymous_to_tgt** - (Boolean value.) If set to true, the KDC will reject ticket - requests from anonymous principals to service principals other - than the realm's ticket-granting service. This option allows - anonymous PKINIT to be enabled for use as FAST armor tickets - without allowing anonymous authentication to services. The - default value is false. - -**supported_enctypes** - (List of *key*:*salt* strings.) Specifies the default key/salt - combinations of principals for this realm. Any principals created - through :ref:`kadmin(1)` will have keys of these types. The - default value for this tag is |defkeysalts|. For lists of - possible values, see :ref:`Encryption_and_salt_types`. - - -.. _dbdefaults: - -[dbdefaults] -~~~~~~~~~~~~ - -The [dbdefaults] section specifies default values for some database -parameters, to be used if the [dbmodules] subsection does not contain -a relation for the tag. See the :ref:`dbmodules` section for the -definitions of these relations. - -* **ldap_kerberos_container_dn** -* **ldap_kdc_dn** -* **ldap_kadmind_dn** -* **ldap_service_password_file** -* **ldap_servers** -* **ldap_conns_per_server** - - -.. _dbmodules: - -[dbmodules] -~~~~~~~~~~~ - -The [dbmodules] section contains parameters used by the KDC database -library and database modules. - -The following tag may be specified in the [dbmodules] section: - -**db_module_dir** - This tag controls where the plugin system looks for modules. The - value should be an absolute path. - -Other tags in the [dbmodules] section name a configuration subsection -for parameters which can be referred to by a realm's -**database_module** parameter. The following tags may be specified in -the subsection: - -**database_name** - This DB2-specific tag indicates the location of the database in - the filesystem. The default is |kdcdir|\ ``/principal``. - -**db_library** - This tag indicates the name of the loadable database module. The - value should be ``db2`` for the DB2 module and ``kldap`` for the - LDAP module. - -**disable_last_success** - If set to ``true``, suppresses KDC updates to the "Last successful - authentication" field of principal entries requiring - preauthentication. Setting this flag may improve performance. - (Principal entries which do not require preauthentication never - update the "Last successful authentication" field.). First - introduced in version 1.9. - -**disable_lockout** - If set to ``true``, suppresses KDC updates to the "Last failed - authentication" and "Failed password attempts" fields of principal - entries requiring preauthentication. Setting this flag may - improve performance, but also disables account lockout. First - introduced in version 1.9. - -**ldap_conns_per_server** - This LDAP-specific tag indicates the number of connections to be - maintained per LDAP server. - -**ldap_kadmind_dn** - This LDAP-specific tag indicates the default bind DN for the - :ref:`kadmind(8)` daemon. kadmind does a login to the directory - as this object. This object should have the rights to read and - write the Kerberos data in the LDAP database. - -**ldap_kdc_dn** - This LDAP-specific tag indicates the default bind DN for the - :ref:`krb5kdc(8)` daemon. The KDC does a login to the directory - as this object. This object should have the rights to read the - Kerberos data in the LDAP database, and to write data unless - **disable_lockout** and **disable_last_success** are true. - -**ldap_kerberos_container_dn** - This LDAP-specific tag indicates the DN of the container object - where the realm objects will be located. - -**ldap_servers** - This LDAP-specific tag indicates the list of LDAP servers that the - Kerberos servers can connect to. The list of LDAP servers is - whitespace-separated. The LDAP server is specified by a LDAP URI. - It is recommended to use ``ldapi:`` or ``ldaps:`` URLs to connect - to the LDAP server. - -**ldap_service_password_file** - This LDAP-specific tag indicates the file containing the stashed - passwords (created by ``kdb5_ldap_util stashsrvpw``) for the - **ldap_kadmind_dn** and **ldap_kdc_dn** objects. This file must - be kept secure. - - -.. _logging: - -[logging] -~~~~~~~~~ - -The [logging] section indicates how :ref:`krb5kdc(8)` and -:ref:`kadmind(8)` perform logging. The keys in this section are -daemon names, which may be one of: - -**admin_server** - Specifies how :ref:`kadmind(8)` performs logging. - -**kdc** - Specifies how :ref:`krb5kdc(8)` performs logging. - -**default** - Specifies how either daemon performs logging in the absence of - relations specific to the daemon. - -Values are of the following forms: - -**FILE=**\ *filename* or **FILE:**\ *filename* - This value causes the daemon's logging messages to go to the - *filename*. If the ``=`` form is used, the file is overwritten. - If the ``:`` form is used, the file is appended to. - -**STDERR** - This value causes the daemon's logging messages to go to its - standard error stream. - -**CONSOLE** - This value causes the daemon's logging messages to go to the - console, if the system supports it. - -**DEVICE=**\ ** - This causes the daemon's logging messages to go to the specified - device. - -**SYSLOG**\ [\ **:**\ *severity*\ [\ **:**\ *facility*\ ]] - This causes the daemon's logging messages to go to the system log. - - The severity argument specifies the default severity of system log - messages. This may be any of the following severities supported - by the syslog(3) call, minus the ``LOG_`` prefix: **EMERG**, - **ALERT**, **CRIT**, **ERR**, **WARNING**, **NOTICE**, **INFO**, - and **DEBUG**. - - The facility argument specifies the facility under which the - messages are logged. This may be any of the following facilities - supported by the syslog(3) call minus the LOG\_ prefix: **KERN**, - **USER**, **MAIL**, **DAEMON**, **AUTH**, **LPR**, **NEWS**, - **UUCP**, **CRON**, and **LOCAL0** through **LOCAL7**. - - If no severity is specified, the default is **ERR**. If no - facility is specified, the default is **AUTH**. - -In the following example, the logging messages from the KDC will go to -the console and to the system log under the facility LOG_DAEMON with -default severity of LOG_INFO; and the logging messages from the -administrative server will be appended to the file -``/var/adm/kadmin.log`` and sent to the device ``/dev/tty04``. - - :: - - [logging] - kdc = CONSOLE - kdc = SYSLOG:INFO:DAEMON - admin_server = FILE:/var/adm/kadmin.log - admin_server = DEVICE=/dev/tty04 - - -PKINIT options --------------- - -.. note:: The following are pkinit-specific options. These values may - be specified in [kdcdefaults] as global defaults, or within - a realm-specific subsection of [realms]. Also note that a - realm-specific value over-rides, does not add to, a generic - [kdcdefaults] specification. The search order is: - -1. realm-specific subsection of [realms], - - :: - - [realms] - EXAMPLE.COM = { - pkinit_anchors = FILE:/usr/local/example.com.crt - } - -2. generic value in the [kdcdefaults] section. - - :: - - [kdcdefaults] - pkinit_anchors = DIR:/usr/local/generic_trusted_cas/ - -For information about the syntax of some of these options, see -:ref:`Specifying PKINIT identity information ` in -:ref:`krb5.conf(5)`. - -**pkinit_anchors** - Specifies the location of trusted anchor (root) certificates which - the KDC trusts to sign client certificates. This option is - required if pkinit is to be supported by the KDC. This option may - be specified multiple times. - -**pkinit_dh_min_bits** - Specifies the minimum number of bits the KDC is willing to accept - for a client's Diffie-Hellman key. The default is 2048. - -**pkinit_allow_upn** - Specifies that the KDC is willing to accept client certificates - with the Microsoft UserPrincipalName (UPN) Subject Alternative - Name (SAN). This means the KDC accepts the binding of the UPN in - the certificate to the Kerberos principal name. The default value - is false. - - Without this option, the KDC will only accept certificates with - the id-pkinit-san as defined in :rfc:`4556`. There is currently - no option to disable SAN checking in the KDC. - -**pkinit_eku_checking** - This option specifies what Extended Key Usage (EKU) values the KDC - is willing to accept in client certificates. The values - recognized in the kdc.conf file are: - - **kpClientAuth** - This is the default value and specifies that client - certificates must have the id-pkinit-KPClientAuth EKU as - defined in :rfc:`4556`. - - **scLogin** - If scLogin is specified, client certificates with the - Microsoft Smart Card Login EKU (id-ms-kp-sc-logon) will be - accepted. - - **none** - If none is specified, then client certificates will not be - checked to verify they have an acceptable EKU. The use of - this option is not recommended. - -**pkinit_identity** - Specifies the location of the KDC's X.509 identity information. - This option is required if pkinit is to be supported by the KDC. - -**pkinit_kdc_ocsp** - Specifies the location of the KDC's OCSP. - -**pkinit_mapping_file** - Specifies the name of the ACL pkinit mapping file. This file maps - principals to the certificates that they can use. - -**pkinit_pool** - Specifies the location of intermediate certificates which may be - used by the KDC to complete the trust chain between a client's - certificate and a trusted anchor. This option may be specified - multiple times. - -**pkinit_revoke** - Specifies the location of Certificate Revocation List (CRL) - information to be used by the KDC when verifying the validity of - client certificates. This option may be specified multiple times. - -**pkinit_require_crl_checking** - The default certificate verification process will always check the - available revocation information to see if a certificate has been - revoked. If a match is found for the certificate in a CRL, - verification fails. If the certificate being verified is not - listed in a CRL, or there is no CRL present for its issuing CA, - and **pkinit_require_crl_checking** is false, then verification - succeeds. - - However, if **pkinit_require_crl_checking** is true and there is - no CRL information available for the issuing CA, then verification - fails. - - **pkinit_require_crl_checking** should be set to true if the - policy is such that up-to-date CRLs must be present for every CA. - - -.. _Encryption_and_salt_types: - -Encryption and salt types -------------------------- - -Any tag in the configuration files which requires a list of encryption -types can be set to some combination of the following strings. -Encryption types marked as "weak" are available for compatibility but -not recommended for use. - -==================================================== ========================================================= -des-cbc-crc DES cbc mode with CRC-32 (weak) -des-cbc-md4 DES cbc mode with RSA-MD4 (weak) -des-cbc-md5 DES cbc mode with RSA-MD5 (weak) -des-cbc-raw DES cbc mode raw (weak) -des3-cbc-raw Triple DES cbc mode raw (weak) -des3-cbc-sha1 des3-hmac-sha1 des3-cbc-sha1-kd Triple DES cbc mode with HMAC/sha1 -des-hmac-sha1 DES with HMAC/sha1 (weak) -aes256-cts-hmac-sha1-96 aes256-cts AES-256 CTS mode with 96-bit SHA-1 HMAC -aes128-cts-hmac-sha1-96 aes128-cts AES-128 CTS mode with 96-bit SHA-1 HMAC -arcfour-hmac rc4-hmac arcfour-hmac-md5 RC4 with HMAC/MD5 -arcfour-hmac-exp rc4-hmac-exp arcfour-hmac-md5-exp Exportable RC4 with HMAC/MD5 (weak) -des The DES family: des-cbc-crc, des-cbc-md5, and des-cbc-md4 (weak) -des3 The triple DES family: des3-cbc-sha1 -aes The AES family: aes256-cts-hmac-sha1-96 and aes128-cts-hmac-sha1-96 -rc4 The RC4 family: arcfour-hmac -==================================================== ========================================================= - -The string **DEFAULT** can be used to refer to the default set of -types for the variable in question. Types or families can be removed -from the current list by prefixing them with a minus sign ("-"). -Types or families can be prefixed with a plus sign ("+") for symmetry; -it has the same meaning as just listing the type or family. For -example, "``DEFAULT -des``" would be the default set of encryption -types with DES types removed, and "``des3 DEFAULT``" would be the -default set of encryption types with triple DES types moved to the -front. - -While **aes128-cts** and **aes256-cts** are supported for all Kerberos -operations, they are not supported by very old versions of our GSSAPI -implementation (krb5-1.3.1 and earlier). Services running versions of -krb5 without AES support must not be given AES keys in the KDC -database. - -Kerberos keys for users are usually derived from passwords. To ensure -that people who happen to pick the same password do not have the same -key, Kerberos 5 incorporates more information into the key using -something called a salt. The supported salt types are as follows: - -================= ============================================ -normal default for Kerberos Version 5 -v4 the only type used by Kerberos Version 4 (no salt) -norealm same as the default, without using realm information -onlyrealm uses only realm information as the salt -afs3 AFS version 3, only used for compatibility with Kerberos 4 in AFS -special generate a random salt -================= ============================================ - - -Sample kdc.conf File --------------------- - -Here's an example of a kdc.conf file: - - :: - - [kdcdefaults] - kdc_ports = 88 - - [realms] - ATHENA.MIT.EDU = { - kadmind_port = 749 - max_life = 12h 0m 0s - max_renewable_life = 7d 0h 0m 0s - master_key_type = des3-hmac-sha1 - supported_enctypes = des3-hmac-sha1:normal des-cbc-crc:normal des-cbc-crc:v4 - database_module = openldap_ldapconf - } - - [logging] - kdc = FILE:/usr/local/var/krb5kdc/kdc.log - admin_server = FILE:/usr/local/var/krb5kdc/kadmin.log - - [dbdefaults] - ldap_kerberos_container_dn = cn=krbcontainer,dc=mit,dc=edu - - [dbmodules] - openldap_ldapconf = { - db_library = kldap - disable_last_success = true - ldap_kdc_dn = "cn=krbadmin,dc=mit,dc=edu" - # this object needs to have read rights on - # the realm container and principal subtrees - ldap_kadmind_dn = "cn=krbadmin,dc=mit,dc=edu" - # this object needs to have read and write rights on - # the realm container and principal subtrees - ldap_service_password_file = /etc/kerberos/service.keyfile - ldap_servers = ldaps://kerberos.mit.edu - ldap_conns_per_server = 5 - } - - -FILES ------- - -|kdcdir|\ ``/kdc.conf`` - - -SEE ALSO ---------- - -:ref:`krb5.conf(5)`, :ref:`krb5kdc(8)`, :ref:`kadm5.acl(5)` diff --git a/doc/rst_source/krb_admins/conf_files/krb5_conf.rst b/doc/rst_source/krb_admins/conf_files/krb5_conf.rst deleted file mode 100644 index 996f93bc7..000000000 --- a/doc/rst_source/krb_admins/conf_files/krb5_conf.rst +++ /dev/null @@ -1,1056 +0,0 @@ -.. _krb5.conf(5): - -krb5.conf -========= - -The krb5.conf file contains Kerberos configuration information, -including the locations of KDCs and admin servers for the Kerberos -realms of interest, defaults for the current realm and for Kerberos -applications, and mappings of hostnames onto Kerberos realms. -Normally, you should install your krb5.conf file in the directory -``/etc``. You can override the default location by setting the -environment variable **KRB5_CONFIG**. - - -Structure ---------- - -The krb5.conf file is set up in the style of a Windows INI file. -Sections are headed by the section name, in square brackets. Each -section may contain zero or more relations, of the form: - - :: - - foo = bar - -or - :: - - fubar = { - foo = bar - baz = quux - } - -Placing a '\*' at the end of a line indicates that this is the *final* -value for the tag. This means that neither the remainder of this -configuration file nor any other configuration file will be checked -for any other values for this tag. - -For example, if you have the following lines: - :: - - foo = bar* - foo = baz - -then the second value of ``foo`` (``baz``) would never be read. - -The krb5.conf file can include other files using either of the -following directives at the beginning of a line: - - :: - - include FILENAME - includedir DIRNAME - -*FILENAME* or *DIRNAME* should be an absolute path. The named file or -directory must exist and be readable. Including a directory includes -all files within the directory whose names consist solely of -alphanumeric characters, dashes, or underscores. Included profile -files are syntactically independent of their parents, so each included -file must begin with a section header. - -The krb5.conf file can specify that configuration should be obtained -from a loadable module, rather than the file itself, using the -following directive at the beginning of a line before any section -headers: - - :: - - module MODULEPATH:RESIDUAL - -*MODULEPATH* may be relative to the library path of the krb5 -installation, or it may be an absolute path. *RESIDUAL* is provided -to the module at initialization time. If krb5.conf uses a module -directive, :ref:`kdc.conf(5)` should also use one if it exists. - - -Sections --------- - -The krb5.conf file may contain the following sections: - -=================== ======================================================= -:ref:`libdefaults` Settings used by the Kerberos V5 library -:ref:`realms` Realm-specific contact information and settings -:ref:`domain_realm` Maps server hostnames to Kerberos realms -:ref:`capaths` Authentication paths for non-hierarchical cross-realm -:ref:`appdefaults` Settings used by some Kerberos V5 applications -:ref:`plugins` Controls plugin module registration -=================== ======================================================= - -Additionally, krb5.conf may include any of the relations described in -:ref:`kdc.conf(5)`, but it is not a recommended practice. - -.. _libdefaults: - -[libdefaults] -~~~~~~~~~~~~~ - -The libdefaults section may contain any of the following relations: - -**allow_weak_crypto** - If this flag is set to false, then weak encryption types will be - filtered out of the previous three lists (as noted in - :ref:`Encryption_and_salt_types` in :ref:`kdc.conf(5)`). The - default value for this tag is false, which may cause - authentication failures in existing Kerberos infrastructures that - do not support strong crypto. Users in affected environments - should set this tag to true until their infrastructure adopts - stronger ciphers. - -**ap_req_checksum_type** - An integer which specifies the type of AP-REQ checksum to use in - authenticators. This variable should be unset so the appropriate - checksum for the encryption key in use will be used. This can be - set if backward compatibility requires a specific checksum type. - See the **kdc_req_checksum_type** configuration option for the - possible values and their meanings. - -**canonicalize** - If this flag is set to true, initial ticket requests to the KDC - will request canonicalization of the client principal name, and - answers with different client principals than the requested - principal will be accepted. The default value is false. - -**ccache_type** - This parameter determines the format of credential cache types - created by :ref:`kinit(1)` or other programs. The default value - is 4, which represents the most current format. Smaller values - can be used for compatibility with very old implementations of - Kerberos which interact with credential caches on the same host. - -**clockskew** - Sets the maximum allowable amount of clockskew in seconds that the - library will tolerate before assuming that a Kerberos message is - invalid. The default value is 300 seconds, or five minutes. - -**default_ccache_name** - This relation specifies the name of the default credential cache. - The default is |ccache|. This relation is subject to parameter - expansion (see below). - -**default_client_keytab_name** - This relation specifies the name of the default keytab for - obtaining client credentials. The default is |ckeytab|. This - relation is subject to parameter expansion (see below). - -**default_keytab_name** - This relation specifies the default keytab name to be used by - application servers such as sshd. The default is |keytab|. This - relation is subject to parameter expansion (see below). - -**default_realm** - Identifies the default Kerberos realm for the client. Set its - value to your Kerberos realm. If this value is not set, then a - realm must be specified with every Kerberos principal when - invoking programs such as :ref:`kinit(1)`. - -**default_tgs_enctypes** - Identifies the supported list of session key encryption types that - should be returned by the KDC, in order of preference from - highest to lowest. The list may be delimited with commas or - whitespace. See :ref:`Encryption_and_salt_types` in - :ref:`kdc.conf(5)` for a list of the accepted values for this tag. - The default value is |defetypes|, but single-DES encryption types - will be implicitly removed from this list if the value of - **allow_weak_crypto** is false. - -**default_tkt_enctypes** - Identifies the supported list of session key encryption types that - should be requested by the client, in order of preference from - highest to lowest. The format is the same as for - default_tgs_enctypes. The default value for this tag is - |defetypes|, but single-DES encryption types will be implicitly - removed from this list if the value of **allow_weak_crypto** is - false. - -**dns_lookup_kdc** - Indicate whether DNS SRV records should be used to locate the KDCs - and other servers for a realm, if they are not listed in the - krb5.conf information for the realm. (Note that the admin_server - entry must be in the krb5.conf realm information in order to - contact kadmind, because the DNS implementation for kadmin is - incomplete.) - - Enabling this option does open up a type of denial-of-service - attack, if someone spoofs the DNS records and redirects you to - another server. However, it's no worse than a denial of service, - because that fake KDC will be unable to decode anything you send - it (besides the initial ticket request, which has no encrypted - data), and anything the fake KDC sends will not be trusted without - verification using some secret that it won't know. - -**extra_addresses** - This allows a computer to use multiple local addresses, in order - to allow Kerberos to work in a network that uses NATs while still - using address-restricted tickets. The addresses should be in a - comma-separated list. This option has no effect if - **noaddresses** is true. - -**forwardable** - If this flag is true, initial tickets will be forwardable by - default, if allowed by the KDC. The default value is false. - -**ignore_acceptor_hostname** - When accepting GSSAPI or krb5 security contexts for host-based - service principals, ignore any hostname passed by the calling - application, and allow clients to authenticate to any service - principal in the keytab matching the service name and realm name - (if given). This option can improve the administrative - flexibility of server applications on multihomed hosts, but could - compromise the security of virtual hosting environments. The - default value is false. - -**k5login_authoritative** - If this flag is true, principals must be listed in a local user's - k5login file to be granted login access, if a :ref:`.k5login(5)` - file exists. If this flag is false, a principal may still be - granted login access through other mechanisms even if a k5login - file exists but does not list the principal. The default value is - true. - -**k5login_directory** - If set, the library will look for a local user's k5login file - within the named directory, with a filename corresponding to the - local username. If not set, the library will look for k5login - files in the user's home directory, with the filename .k5login. - For security reasons, .k5login files must be owned by - the local user or by root. - -**kdc_default_options** - Default KDC options (Xored for multiple values) when requesting - initial tickets. By default it is set to 0x00000010 - (KDC_OPT_RENEWABLE_OK). - -**kdc_timesync** - The value of this relation must be an integer. If it is nonzero, - client machines will compute the difference between their time and - the time returned by the KDC in the timestamps in the tickets and - use this value to correct for an inaccurate system clock when - requesting service tickets or authenticating to services. This - corrective factor is only used by the Kerberos library; it is not - used to change the system clock. The default value is 1. - -**kdc_req_checksum_type** - An integer which specifies the type of checksum to use for the KDC - requests, for compatibility with very old KDC implementations. - This value is only used for DES keys; other keys use the preferred - checksum type for those keys. - - The possible values and their meanings are as follows. - - ======== =============================== - 1 CRC32 - 2 RSA MD4 - 3 RSA MD4 DES - 4 DES CBC - 7 RSA MD5 - 8 RSA MD5 DES - 9 NIST SHA - 12 HMAC SHA1 DES3 - -138 Microsoft MD5 HMAC checksum type - ======== =============================== - -**noaddresses** - If this flag is true, requests for initial tickets will not be - made with address restrictions set, allowing the tickets to be - used across NATs. The default value is true. - -**permitted_enctypes** - Identifies all encryption types that are permitted for use in - session key encryption. The default value for this tag is - |defetypes|, but single-DES encryption types will be implicitly - removed from this list if the value of **allow_weak_crypto** is - false. - -**plugin_base_dir** - If set, determines the base directory where krb5 plugins are - located. The default value is the ``krb5/plugins`` subdirectory - of the krb5 library directory. - -**preferred_preauth_types** - This allows you to set the preferred preauthentication types which - the client will attempt before others which may be advertised by a - KDC. The default value for this setting is "17, 16, 15, 14", - which forces libkrb5 to attempt to use PKINIT if it is supported. - -**proxiable** - If this flag is true, initial tickets will be proxiable by - default, if allowed by the KDC. The default value is false. - -**rdns** - If this flag is true, reverse name lookup will be used in addition - to forward name lookup to canonicalizing hostnames for use in - service principal names. The default value is true. - -**realm_try_domains** - Indicate whether a host's domain components should be used to - determine the Kerberos realm of the host. The value of this - variable is an integer: -1 means not to search, 0 means to try the - host's domain itself, 1 means to also try the domain's immediate - parent, and so forth. The library's usual mechanism for locating - Kerberos realms is used to determine whether a domain is a valid - realm, which may involve consulting DNS if **dns_lookup_kdc** is - set. The default is not to search domain components. - -**renew_lifetime** - (:ref:`duration` string.) Sets the default renewable lifetime - for initial ticket requests. The default value is 0. - -**safe_checksum_type** - An integer which specifies the type of checksum to use for the - KRB-SAFE requests. By default it is set to 8 (RSA MD5 DES). For - compatibility with applications linked against DCE version 1.1 or - earlier Kerberos libraries, use a value of 3 to use the RSA MD4 - DES instead. This field is ignored when its value is incompatible - with the session key type. See the **kdc_req_checksum_type** - configuration option for the possible values and their meanings. - -**ticket_lifetime** - (:ref:`duration` string.) Sets the default lifetime for initial - ticket requests. The default value is 1 day. - -**udp_preference_limit** - When sending a message to the KDC, the library will try using TCP - before UDP if the size of the message is above - **udp_preference_limit**. If the message is smaller than - **udp_preference_limit**, then UDP will be tried before TCP. - Regardless of the size, both protocols will be tried if the first - attempt fails. - -**verify_ap_req_nofail** - If this flag is true, then an attempt to verify initial - credentials will fail if the client machine does not have a - keytab. The default value is false. - - -.. _realms: - -[realms] -~~~~~~~~ - -Each tag in the [realms] section of the file is the name of a Kerberos -realm. The value of the tag is a subsection with relations that -define the properties of that particular realm. For each realm, the -following tags may be specified in the realm's subsection: - -**admin_server** - Identifies the host where the administration server is running. - Typically, this is the master Kerberos server. This tag must be - given a value in order to communicate with the :ref:`kadmind(8)` - server for the realm. - -**auth_to_local** - This tag allows you to set a general rule for mapping principal - names to local user names. It will be used if there is not an - explicit mapping for the principal name that is being - translated. The possible values are: - - **RULE:**\ *exp* - The local name will be formulated from *exp*. - - The format for *exp* is **[**\ *n*\ **:**\ *string*\ **](**\ - *regexp*\ **)s/**\ *pattern*\ **/**\ *replacement*\ **/g**. - The integer *n* indicates how many components the target - principal should have. If this matches, then a string will be - formed from *string*, substituting the realm of the principal - for ``$0`` and the *n*'th component of the principal for - ``$n`` (e.g., if the principal was ``johndoe/admin`` then - ``[2:$2$1foo]`` would result in the string - ``adminjohndoefoo``). If this string matches *regexp*, then - the ``s//[g]`` substitution command will be run over the - string. The optional **g** will cause the substitution to be - global over the *string*, instead of replacing only the first - match in the *string*. - - **DEFAULT** - The principal name will be used as the local user name. If - the principal has more than one component or is not in the - default realm, this rule is not applicable and the conversion - will fail. - - For example: - :: - - [realms] - ATHENA.MIT.EDU = { - auth_to_local = RULE:[2:$1](johndoe)s/^.*$/guest/ - auth_to_local = RULE:[2:$1;$2](^.*;admin$)s/;admin$// - auth_to_local = RULE:[2:$2](^.*;root)s/^.*$/root/ - auto_to_local = DEFAULT - } - - would result in any principal without ``root`` or ``admin`` as the - second component to be translated with the default rule. A - principal with a second component of ``admin`` will become its - first component. ``root`` will be used as the local name for any - principal with a second component of ``root``. The exception to - these two rules are any principals ``johndoe/*``, which will - always get the local name ``guest``. - -**auth_to_local_names** - This subsection allows you to set explicit mappings from principal - names to local user names. The tag is the mapping name, and the - value is the corresponding local user name. - -**default_domain** - This tag specifies the domain used to expand hostnames when - translating Kerberos 4 service principals to Kerberos 5 principals - (for example, when converting ``rcmd.hostname`` to - ``host/hostname.domain``). - -**kdc** - The name or address of a host running a KDC for that realm. An - optional port number, separated from the hostname by a colon, may - be included. If the name or address contains colons (for example, - if it is an IPv6 address), enclose it in square brackets to - distinguish the colon from a port separator. For your computer to - be able to communicate with the KDC for each realm, this tag must - be given a value in each realm subsection in the configuration - file, or there must be DNS SRV records specifying the KDCs. - -**kpasswd_server** - Points to the server where all the password changes are performed. - If there is no such entry, the port 464 on the **admin_server** - host will be tried. - -**master_kdc** - Identifies the master KDC(s). Currently, this tag is used in only - one case: If an attempt to get credentials fails because of an - invalid password, the client software will attempt to contact the - master KDC, in case the user's password has just been changed, and - the updated database has not been propagated to the slave servers - yet. - -**v4_instance_convert** - This subsection allows the administrator to configure exceptions - to the **default_domain** mapping rule. It contains V4 instances - (the tag name) which should be translated to some specific - hostname (the tag value) as the second component in a Kerberos V5 - principal name. - -**v4_realm** - This relation is used by the krb524 library routines when - converting a V5 principal name to a V4 principal name. It is used - when the V4 realm name and the V5 realm name are not the same, but - still share the same principal names and passwords. The tag value - is the Kerberos V4 realm name. - - -.. _domain_realm: - -[domain_realm] -~~~~~~~~~~~~~~ - -The [domain_realm] section provides a translation from a domain name -or hostname to a Kerberos realm name. The tag name can be a host name -or domain name, where domain names are indicated by a prefix of a -period (``.``). The value of the relation is the Kerberos realm name -for that particular host or domain. The Kerberos realm may be -identified either in the realms_ section or using DNS SRV records. -Host names and domain names should be in lower case. For example: - - :: - - [domain_realm] - crash.mit.edu = TEST.ATHENA.MIT.EDU - .mit.edu = ATHENA.MIT.EDU - mit.edu = ATHENA.MIT.EDU - -maps the host with the exact name ``crash.mit.edu`` into the -TEST.ATHENA.MIT.EDU realm. The period prefix in ``.mit.edu`` denotes -that all systems in the ``mit.edu`` domain belong to -``ATHENA.MIT.EDU`` realm. The third entry maps the host ``mit.edu`` -itself to the ``ATHENA.MIT.EDU`` realm. - -If no translation entry applies to a hostname used for a service -principal for a service ticket request, the library will try to get a -referral to the appropriate realm from the client realm's KDC. If -that does not succeed, the host's realm is considered to be the -hostname's domain portion converted to uppercase, unless the -**realm_try_domains** setting in [libdefaults] causes a different -parent domain to be used. - - -.. _capaths: - -[capaths] -~~~~~~~~~ - -In order to perform direct (non-hierarchical) cross-realm -authentication, configuration is needed to determine the -authentication paths between realms. - -A client will use this section to find the authentication path between -its realm and the realm of the server. The server will use this -section to verify the authentication path used by the client, by -checking the transited field of the received ticket. - -There is a tag for each participating client realm, and each tag has -subtags for each of the server realms. The value of the subtags is an -intermediate realm which may participate in the cross-realm -authentication. The subtags may be repeated if there is more then one -intermediate realm. A value of "." means that the two realms share -keys directly, and no intermediate realms should be allowed to -participate. - -Only those entries which will be needed on the client or the server -need to be present. A client needs a tag for its local realm with -subtags for all the realms of servers it will need to authenticate to. -A server needs a tag for each realm of the clients it will serve, with -a subtag of the server realm. - -For example, ``ANL.GOV``, ``PNL.GOV``, and ``NERSC.GOV`` all wish to -use the ``ES.NET`` realm as an intermediate realm. ANL has a sub -realm of ``TEST.ANL.GOV`` which will authenticate with ``NERSC.GOV`` -but not ``PNL.GOV``. The [capaths] section for ``ANL.GOV`` systems -would look like this: - - :: - - [capaths] - ANL.GOV = { - TEST.ANL.GOV = . - PNL.GOV = ES.NET - NERSC.GOV = ES.NET - ES.NET = . - } - TEST.ANL.GOV = { - ANL.GOV = . - } - PNL.GOV = { - ANL.GOV = ES.NET - } - NERSC.GOV = { - ANL.GOV = ES.NET - } - ES.NET = { - ANL.GOV = . - } - -The [capaths] section of the configuration file used on ``NERSC.GOV`` -systems would look like this: - - :: - - [capaths] - NERSC.GOV = { - ANL.GOV = ES.NET - TEST.ANL.GOV = ES.NET - TEST.ANL.GOV = ANL.GOV - PNL.GOV = ES.NET - ES.NET = . - } - ANL.GOV = { - NERSC.GOV = ES.NET - } - PNL.GOV = { - NERSC.GOV = ES.NET - } - ES.NET = { - NERSC.GOV = . - } - TEST.ANL.GOV = { - NERSC.GOV = ANL.GOV - NERSC.GOV = ES.NET - } - -When a subtag is used more than once within a tag, clients will use -the order of values to determine the path. The order of values is not -important to servers. - - -.. _appdefaults: - -[appdefaults] -~~~~~~~~~~~~~ - -Each tag in the [appdefaults] section names a Kerberos V5 application -or an option that is used by some Kerberos V5 application[s]. The -value of the tag defines the default behaviors for that application. - -For example: - :: - - [appdefaults] - telnet = { - ATHENA.MIT.EDU = { - option1 = false - } - } - telnet = { - option1 = true - option2 = true - } - ATHENA.MIT.EDU = { - option2 = false - } - option2 = true - -The above four ways of specifying the value of an option are shown in -order of decreasing precedence. In this example, if telnet is running -in the realm EXAMPLE.COM, it should, by default, have option1 and -option2 set to true. However, a telnet program in the realm -``ATHENA.MIT.EDU`` should have ``option1`` set to false and -``option2`` set to true. Any other programs in ATHENA.MIT.EDU should -have ``option2`` set to false by default. Any programs running in -other realms should have ``option2`` set to true. - -The list of specifiable options for each application may be found in -that application's man pages. The application defaults specified here -are overridden by those specified in the realms_ section. - - -.. _plugins: - -[plugins] -~~~~~~~~~ - - * pwqual_ interface - * kadm5_hook_ interface - * clpreauth_ and kdcpreauth_ interfaces - -Tags in the [plugins] section can be used to register dynamic plugin -modules and to turn modules on and off. Not every krb5 pluggable -interface uses the [plugins] section; the ones that do are documented -here. - -Each pluggable interface corresponds to a subsection of [plugins]. -All subsections support the same tags: - -**disable** - This tag may have multiple values. If there are values for this - tag, then the named modules will be disabled for the pluggable - interface. - -**enable_only** - This tag may have multiple values. If there are values for this - tag, then only the named modules will be enabled for the pluggable - interface. - -**module** - This tag may have multiple values. Each value is a string of the - form ``modulename:pathname``, which causes the shared object - located at *pathname* to be registered as a dynamic module named - *modulename* for the pluggable interface. If *pathname* is not an - absolute path, it will be treated as relative to the - **plugin_base_dir** value from :ref:`libdefaults`. - -The following subsections are currently supported within the [plugins] -section: - -.. _ccselect: - -ccselect interface -################## - -The ccselect subsection controls modules for credential cache -selection within a cache collection. In addition to any registered -dynamic modules, the following built-in modules exist (and may be -disabled with the disable tag): - -**k5identity** - Uses a .k5identity file in the user's home directory to select a - client principal - -**realm** - Uses the service realm to guess an appropriate cache from the - collection - -.. _pwqual: - -pwqual interface -################ - -The pwqual subsection controls modules for the password quality -interface, which is used to reject weak passwords when passwords are -changed. The following built-in modules exist for this interface: - -**dict** - Checks against the realm dictionary file - -**empty** - Rejects empty passwords - -**hesiod** - Checks against user information stored in Hesiod (only if Kerberos - was built with Hesiod support) - -**princ** - Checks against components of the principal name - -.. _kadm5_hook: - -kadm5_hook interface -#################### - -The kadm5_hook interface provides plugins with information on -principal creation, modification, password changes and deletion. This -interface can be used to write a plugin to synchronize MIT Kerberos -with another database such as Active Directory. No plugins are built -in for this interface. - -.. _clpreauth: - -.. _kdcpreauth: - -clpreauth and kdcpreauth interfaces -################################### - -The clpreauth and kdcpreauth interfaces allow plugin modules to -provide client and KDC preauthentication mechanisms. The following -built-in modules exist for these interfaces: - -**pkinit** - This module implements the PKINIT preauthentication mechanism. - -**encrypted_challenge** - This module implements the encrypted challenge FAST factor. - -**encrypted_timestamp** - This module implements the encrypted timestamp mechanism. - - -PKINIT options --------------- - -.. note:: The following are PKINIT-specific options. These values may - be specified in [libdefaults] as global defaults, or within - a realm-specific subsection of [libdefaults], or may be - specified as realm-specific values in the [realms] section. - A realm-specific value overrides, not adds to, a generic - [libdefaults] specification. The search order is: - -1. realm-specific subsection of [libdefaults]: - - :: - - [libdefaults] - EXAMPLE.COM = { - pkinit_anchors = FILE:/usr/local/example.com.crt - } - -2. realm-specific value in the [realms] section, - - :: - - [realms] - OTHERREALM.ORG = { - pkinit_anchors = FILE:/usr/local/otherrealm.org.crt - } - -3. generic value in the [libdefaults] section. - - :: - - [libdefaults] - pkinit_anchors = DIR:/usr/local/generic_trusted_cas/ - - -.. _pkinit_identity: - -Specifying PKINIT identity information -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The syntax for specifying Public Key identity, trust, and revocation -information for PKINIT is as follows: - -**FILE:**\ *filename*\ [**,**\ *keyfilename*] - This option has context-specific behavior. - - In **pkinit_identity** or **pkinit_identities**, *filename* - specifies the name of a PEM-format file containing the user's - certificate. If *keyfilename* is not specified, the user's - private key is expected to be in *filename* as well. Otherwise, - *keyfilename* is the name of the file containing the private key. - - In **pkinit_anchors** or **pkinit_pool**, *filename* is assumed to - be the name of an OpenSSL-style ca-bundle file. - -**DIR:**\ *dirname* - This option has context-specific behavior. - - In **pkinit_identity** or **pkinit_identities**, *dirname* - specifies a directory with files named ``*.crt`` and ``*.key`` - where the first part of the file name is the same for matching - pairs of certificate and private key files. When a file with a - name ending with ``.crt`` is found, a matching file ending with - ``.key`` is assumed to contain the private key. If no such file - is found, then the certificate in the ``.crt`` is not used. - - In **pkinit_anchors** or **pkinit_pool**, *dirname* is assumed to - be an OpenSSL-style hashed CA directory where each CA cert is - stored in a file named ``hash-of-ca-cert.#``. This infrastructure - is encouraged, but all files in the directory will be examined and - if they contain certificates (in PEM format), they will be used. - - In **pkinit_revoke**, *dirname* is assumed to be an OpenSSL-style - hashed CA directory where each revocation list is stored in a file - named ``hash-of-ca-cert.r#``. This infrastructure is encouraged, - but all files in the directory will be examined and if they - contain a revocation list (in PEM format), they will be used. - -**PKCS12:**\ *filename* - *filename* is the name of a PKCS #12 format file, containing the - user's certificate and private key. - -**PKCS11:**\ [**module_name=**]\ *modname*\ [**:slotid=**\ *slot-id*][**:token=**\ *token-label*][**:certid=**\ *cert-id*][**:certlabel=**\ *cert-label*] - All keyword/values are optional. *modname* specifies the location - of a library implementing PKCS #11. If a value is encountered - with no keyword, it is assumed to be the *modname*. If no - module-name is specified, the default is ``opensc-pkcs11.so``. - ``slotid=`` and/or ``token=`` may be specified to force the use of - a particular smard card reader or token if there is more than one - available. ``certid=`` and/or ``certlabel=`` may be specified to - force the selection of a particular certificate on the device. - See the **pkinit_cert_match** configuration option for more ways - to select a particular certificate to use for PKINIT. - -**ENV:**\ *envvar* - *envvar* specifies the name of an environment variable which has - been set to a value conforming to one of the previous values. For - example, ``ENV:X509_PROXY``, where environment variable - ``X509_PROXY`` has been set to ``FILE:/tmp/my_proxy.pem``. - - -PKINIT krb5.conf options -~~~~~~~~~~~~~~~~~~~~~~~~ - -**pkinit_anchors** - Specifies the location of trusted anchor (root) certificates which - the client trusts to sign KDC certificates. This option may be - specified multiple times. These values from the config file are - not used if the user specifies X509_anchors on the command line. - -**pkinit_cert_match** - Specifies matching rules that the client certificate must match - before it is used to attempt PKINIT authentication. If a user has - multiple certificates available (on a smart card, or via other - media), there must be exactly one certificate chosen before - attempting PKINIT authentication. This option may be specified - multiple times. All the available certificates are checked - against each rule in order until there is a match of exactly one - certificate. - - The Subject and Issuer comparison strings are the :rfc:`2253` - string representations from the certificate Subject DN and Issuer - DN values. - - The syntax of the matching rules is: - - [*relation-operator*\ ]\ *component-rule* ... - - where: - - *relation-operator* - can be either ``&&``, meaning all component rules must match, - or ``||``, meaning only one component rule must match. The - default is ``&&``. - - *component-rule* - can be one of the following. Note that there is no - punctuation or whitespace between component rules. - - | ****\ *regular-expression* - | ****\ *regular-expression* - | ****\ *regular-expression* - | ****\ *extended-key-usage-list* - | ****\ *key-usage-list* - - *extended-key-usage-list* is a comma-separated list of - required Extended Key Usage values. All values in the list - must be present in the certificate. Extended Key Usage values - can be: - - * pkinit - * msScLogin - * clientAuth - * emailProtection - - *key-usage-list* is a comma-separated list of required Key - Usage values. All values in the list must be present in the - certificate. Key Usage values can be: - - * digitalSignature - * keyEncipherment - - Examples: - - :: - - pkinit_cert_match = ||.*DoE.*.*@EXAMPLE.COM - pkinit_cert_match = &&msScLogin,clientAuth.*DoE.* - pkinit_cert_match = msScLogin,clientAuthdigitalSignature - -**pkinit_eku_checking** - This option specifies what Extended Key Usage value the KDC - certificate presented to the client must contain. (Note that if - the KDC certificate has the pkinit SubjectAlternativeName encoded - as the Kerberos TGS name, EKU checking is not necessary since the - issuing CA has certified this as a KDC certificate.) The values - recognized in the krb5.conf file are: - - **kpKDC** - This is the default value and specifies that the KDC must have - the id-pkinit-KPKdc EKU as defined in :rfc:`4556`. - - **kpServerAuth** - If **kpServerAuth** is specified, a KDC certificate with the - id-kp-serverAuth EKU as used by Microsoft will be accepted. - - **none** - If **none** is specified, then the KDC certificate will not be - checked to verify it has an acceptable EKU. The use of this - option is not recommended. - -**pkinit_dh_min_bits** - Specifies the size of the Diffie-Hellman key the client will - attempt to use. The acceptable values are 1024, 2048, and 4096. - The default is 2048. - -**pkinit_identities** - Specifies the location(s) to be used to find the user's X.509 - identity information. This option may be specified multiple - times. Each value is attempted in order until identity - information is found and authentication is attempted. Note that - these values are not used if the user specifies - **X509_user_identity** on the command line. - -**pkinit_kdc_hostname** - The presense of this option indicates that the client is willing - to accept a KDC certificate with a dNSName SAN (Subject - Alternative Name) rather than requiring the id-pkinit-san as - defined in :rfc:`4556`. This option may be specified multiple - times. Its value should contain the acceptable hostname for the - KDC (as contained in its certificate). - -**pkinit_longhorn** - If this flag is set to true, we are talking to the Longhorn KDC. - -**pkinit_pool** - Specifies the location of intermediate certificates which may be - used by the client to complete the trust chain between a KDC - certificate and a trusted anchor. This option may be specified - multiple times. - -**pkinit_require_crl_checking** - The default certificate verification process will always check the - available revocation information to see if a certificate has been - revoked. If a match is found for the certificate in a CRL, - verification fails. If the certificate being verified is not - listed in a CRL, or there is no CRL present for its issuing CA, - and **pkinit_require_crl_checking** is false, then verification - succeeds. - - However, if **pkinit_require_crl_checking** is true and there is - no CRL information available for the issuing CA, then verification - fails. - - **pkinit_require_crl_checking** should be set to true if the - policy is such that up-to-date CRLs must be present for every CA. - -**pkinit_revoke** - Specifies the location of Certificate Revocation List (CRL) - information to be used by the client when verifying the validity - of the KDC certificate presented. This option may be specified - multiple times. - -**pkinit_win2k** - This flag specifies whether the target realm is assumed to support - only the old, pre-RFC version of the protocol. The default is - false. - -**pkinit_win2k_require_binding** - If this flag is set to true, it expects that the target KDC is - patched to return a reply with a checksum rather than a nonce. - The default is false. - - -.. _parameter_expansion: - -Parameter expansion -------------------- - -Several variables, such as **default_keytab_name**, allow parameters -to be expanded. Valid parameters are: - - ================= =================================================== - %{TEMP} Temporary directory - %{uid} Unix real UID or Windows SID - %{euid} Unix effective user ID or Windows SID - %{USERID} Same as %{uid} - %{null} Empty string - %{LIBDIR} Installation library directory - %{BINDIR} Installation binary directory - %{SBINDIR} Installation admin binary directory - %{username} (Unix) Username of effective user ID - %{APPDATA} (Windows) Roaming application data for current user - %{COMMON_APPDATA} (Windows) Application data for all users - %{LOCAL_APPDATA} (Windows) Local application data for current user - %{SYSTEM} (Windows) Windows system folder - %{WINDOWS} (Windows) Windows folder - %{USERCONFIG} (Windows) Per-user MIT krb5 config file directory - %{COMMONCONFIG} (Windows) Common MIT krb5 config file directory - ================= =================================================== - -Sample krb5.conf file ---------------------- - -Here is an example of a generic krb5.conf file: - - :: - - [libdefaults] - default_realm = ATHENA.MIT.EDU - default_tkt_enctypes = des3-hmac-sha1 des-cbc-crc - default_tgs_enctypes = des3-hmac-sha1 des-cbc-crc - dns_lookup_kdc = true - dns_lookup_realm = false - - [realms] - ATHENA.MIT.EDU = { - kdc = kerberos.mit.edu - kdc = kerberos-1.mit.edu - kdc = kerberos-2.mit.edu:750 - admin_server = kerberos.mit.edu - master_kdc = kerberos.mit.edu - default_domain = mit.edu - } - EXAMPLE.COM = { - kdc = kerberos.example.com - kdc = kerberos-1.example.com - admin_server = kerberos.example.com - } - - [domain_realm] - .mit.edu = ATHENA.MIT.EDU - mit.edu = ATHENA.MIT.EDU - - [capaths] - ATHENA.MIT.EDU = { - EXAMPLE.COM = . - } - EXAMPLE.COM = { - ATHENA.MIT.EDU = . - } - -FILES ------ - -|krb5conf| - - -SEE ALSO --------- - -syslog(3) diff --git a/doc/rst_source/krb_admins/conf_ldap.rst b/doc/rst_source/krb_admins/conf_ldap.rst deleted file mode 100644 index c8237d643..000000000 --- a/doc/rst_source/krb_admins/conf_ldap.rst +++ /dev/null @@ -1,158 +0,0 @@ -Configuring Kerberos with OpenLDAP back-end -=========================================== - - - 1. Set up SSL on the OpenLDAP server and client to ensure secure - communication when the KDC service and LDAP server are on different - machines. ``ldapi://`` can be used if the LDAP server and KDC - service are running on the same machine. - - A. Setting up SSL on the OpenLDAP server: - - i) Get a CA certificate using OpenSSL tools - ii) Configure OpenLDAP server for using SSL/TLS - - For the latter, you need to specify the location of CA - certificate location in *slapd.conf* file. - - Refer to the following link for more information: - http://www.openldap.org/doc/admin23/tls.html - - B. Setting up SSL on OpenLDAP client: - - i) For the KDC and Admin Server, you need to do the client-side - configuration in ldap.conf. For example:: - - TLS_CACERT /etc/openldap/certs/cacert.pem - - 2. Include the Kerberos schema file (kerberos.schema) in the - configuration file (slapd.conf) on the LDAP Server, by providing - the location where it is stored:: - - include /etc/openldap/schema/kerberos.schema - - 3. Choose DNs for the :ref:`krb5kdc(8)` and :ref:`kadmind(8)` servers - to bind to the LDAP server, and create them if necessary. These DNs - will be specified with the **ldap_kdc_dn** and **ldap_kadmind_dn** - directives in :ref:`kdc.conf(5)`; their passwords can be stashed - with "``kdb5_ldap_util stashsrvpw``" and the resulting file - specified with the **ldap_service_password_file** directive. - - 4. Choose a DN for the global Kerberos container entry (but do not - create the entry at this time). This DN will be specified with the - **ldap_kerberos_container_dn** directive in :ref:`kdc.conf(5)`. - Realm container entries will be created underneath this DN. - Principal entries may exist either underneath the realm container - (the default) or in separate trees referenced from the realm - container. - - 5. Configure the LDAP server ACLs to enable the KDC and kadmin server - DNs to read and write the Kerberos data. - - Sample access control information:: - - access to dn.base="" - by * read - - access to dn.base="cn=Subschema" - by * read - - access to attrs=userPassword,userPKCS12 - by self write - by * auth - - access to attrs=shadowLastChange - by self write - by * read - - # Providing access to realm container - access to dn.subtree= "cn=EXAMPLE.COM,cn=krbcontainer,dc=example,dc=com" - by dn.exact="cn=kdc-service,dc=example,dc=com" read - by dn.exact="cn=adm-service,dc=example,dc=com" write - by * none - - # Providing access to principals, if not underneath realm container - access to dn.subtree= "ou=users,dc=example,dc=com" - by dn.exact="cn=kdc-service,dc=example,dc=com" read - by dn.exact="cn=adm-service,dc=example,dc=com" write - by * none - - access to * - by * read - - If the locations of the container and principals or the DNs of - the service objects for a realm are changed then this - information should be updated. - - 6. Start the LDAP server as follows:: - - slapd -h "ldapi:/// ldaps:///" - - 7. Modify the :ref:`kdc.conf(5)` file to include LDAP specific items - listed below:: - - realms - database_module - - dbmodules - db_library - db_module_dir - ldap_kdc_dn - ldap_kadmind_dn - ldap_service_password_file - ldap_servers - ldap_conns_per_server - - 8. Create the realm using :ref:`kdb5_ldap_util(8)` (see - :ref:`ldap_create_realm`):: - - kdb5_ldap_util -D cn=admin,dc=example,dc=com create -subtrees ou=users,dc=example,dc=com -r EXAMPLE.COM -s - - Use the **-subtrees** option if the principals are to exist in a - separate subtree from the realm container. Before executing the - command, make sure that the subtree mentioned above - ``(ou=users,dc=example,dc=com)`` exists. If the principals will - exist underneath the realm container, omit the **-subtrees** option - and do not worry about creating the principal subtree. - - For more information, refer to the section :ref:`ops_on_ldap`. - - The realm object is created under the - **ldap_kerberos_container_dn** specified in the configuration file. - This operation will also create the Kerberos container, if not - present already. This will be used to store information related to - all realms. - - 9. Stash the password of the service object used by the KDC and - Administration service to bind to the LDAP server using the - :ref:`kdb5_ldap_util(8)` **stashsrvpw** command (see - :ref:`stash_ldap`). The object DN should be the same as - **ldap_kdc_dn** and **ldap_kadmind_dn** values specified in the - :ref:`kdc.conf(5)` file:: - - kdb5_ldap_util -D cn=admin,dc=example,dc=com stashsrvpw -f /etc/kerberos/service.keyfile cn=krbadmin,dc=example,dc=com - - 10. Add ``krbPrincipalName`` to the indexes in slapd.conf to speed up - the access. - -With the LDAP back end it is possible to provide aliases for principal -entries. Currently we provide no mechanism provided for creating -aliases, so it must be done by direct manipulation of the LDAP -entries. - -An entry with aliases contains multiple values of the -*krbPrincipalName* attribute. Since LDAP attribute values are not -ordered, it is necessary to specify which principal name is canonical, -by using the *krbCanonicalName* attribute. Therefore, to create -aliases for an entry, first set the *krbCanonicalName* attribute of -the entry to the canonical principal name (which should be identical -to the pre-existing *krbPrincipalName* value), and then add additional -*krbPrincipalName* attributes for the aliases. - -Principal aliases are only returned by the KDC when the client -requests canonicalization. Canonicalization is normally requested for -service principals; for client principals, an explicit flag is often -required (e.g., ``kinit -C``) and canonicalization is only performed -for initial ticket requests. - -.. seealso:: :ref:`ldap_be_ubuntu` diff --git a/doc/rst_source/krb_admins/database.rst b/doc/rst_source/krb_admins/database.rst deleted file mode 100644 index d7d6aa9b7..000000000 --- a/doc/rst_source/krb_admins/database.rst +++ /dev/null @@ -1,785 +0,0 @@ -Database administration -======================= - -A Kerberos database contains all of a realm's Kerberos principals, -their passwords, and other administrative information about each -principal. For the most part, you will use the :ref:`kdb5_util(8)` -program to manipulate the Kerberos database as a whole, and the -:ref:`kadmin(1)` program to make changes to the entries in the -database. (One notable exception is that users will use the -:ref:`kpasswd(1)` program to change their own passwords.) The kadmin -program has its own command-line interface, to which you type the -database administrating commands. - -:ref:`kdb5_util(8)` provides a means to create, delete, load, or dump -a Kerberos database. It also contains commands to roll over the -database master key, and to stash a copy of the key so that the -:ref:`kadmind(8)` and :ref:`krb5kdc(8)` daemons can use the database -without manual input. - -:ref:`kadmin(1)` provides for the maintenance of Kerberos principals, -password policies, and service key tables (keytabs). Normally it -operates as a network client using Kerberos authentication to -communicate with :ref:`kadmind(8)`, but there is also a variant, named -kadmin.local, which directly accesses the Kerberos database on the -local filesystem (or through LDAP). kadmin.local is necessary to set -up enough of the database to be able to use the remote version. - -kadmin can authenticate to the admin server using the service -principal ``kadmin/HOST`` (where *HOST* is the hostname of the admin -server) or ``kadmin/admin``. If the credentials cache contains a -ticket for either service principal and the **-c** ccache option is -specified, that ticket is used to authenticate to KADM5. Otherwise, -the **-p** and **-k** options are used to specify the client Kerberos -principal name used to authenticate. Once kadmin has determined the -principal name, it requests a ``kadmin/admin`` Kerberos service ticket -from the KDC, and uses that service ticket to authenticate to KADM5. - -See :ref:`kadmin(1)` for the available kadmin and kadmin.local -commands and options. - - -kadmin options --------------- - -You can invoke :ref:`kadmin(1)` or kadmin.local with any of the -following options: - -.. include:: admin_commands/kadmin_local.rst - :start-after: kadmin_synopsis: - :end-before: kadmin_synopsis_end: - -**OPTIONS** - -.. include:: admin_commands/kadmin_local.rst - :start-after: _kadmin_options: - :end-before: _kadmin_options_end: - - -Date Format ------------ - -For the supported date-time formats see :ref:`getdate` section -in :ref:`datetime`. - - -Principals ----------- - -Each entry in the Kerberos database contains a Kerberos principal and -the attributes and policies associated with that principal. - - -.. _add_mod_del_princs: - -Adding, modifying and deleting principals -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To add a principal to the database, use the :ref:`kadmin(1)` -**add_principal** command. - -To modify attributes of a principal, use the kadmin -**modify_principal** command. - -To delete a principal, use the kadmin **delete_principal** command. - -.. include:: admin_commands/kadmin_local.rst - :start-after: _add_principal: - :end-before: _add_principal_end: - -.. include:: admin_commands/kadmin_local.rst - :start-after: _modify_principal: - :end-before: _modify_principal_end: - -.. include:: admin_commands/kadmin_local.rst - :start-after: _delete_principal: - :end-before: _delete_principal_end: - - -Examples -######## - -If you want to create a principal which is contained by a LDAP object, -all you need to do is:: - - kadmin: addprinc -x dn=cn=jennifer,dc=example,dc=com jennifer - WARNING: no policy specified for "jennifer@ATHENA.MIT.EDU"; - defaulting to no policy. - Enter password for principal jennifer@ATHENA.MIT.EDU: <= Type the password. - Re-enter password for principal jennifer@ATHENA.MIT.EDU: <=Type it again. - Principal "jennifer@ATHENA.MIT.EDU" created. - kadmin: - -If you want to create a principal under a specific LDAP container and -link to an existing LDAP object, all you need to do is:: - - kadmin: addprinc -x containerdn=dc=example,dc=com -x linkdn=cn=david,dc=example,dc=com david - WARNING: no policy specified for "david@ATHENA.MIT.EDU"; - defaulting to no policy. - Enter password for principal david@ATHENA.MIT.EDU: <= Type the password. - Re-enter password for principal david@ATHENA.MIT.EDU: <=Type it again. - Principal "david@ATHENA.MIT.EDU" created. - kadmin: - -If you want to associate a ticket policy to a principal, all you need -to do is:: - - kadmin: modprinc -x tktpolicy=userpolicy david - Principal "david@ATHENA.MIT.EDU" modified. - kadmin: - -If, on the other hand, you want to set up an account that expires on -January 1, 2000, that uses a policy called "stduser", with a temporary -password (which you want the user to change immediately), you would -type the following:: - - kadmin: addprinc david -expire "1/1/2000 12:01am EST" -policy stduser +needchange - Enter password for principal david@ATHENA.MIT.EDU: <= Type the password. - Re-enter password for principal - david@ATHENA.MIT.EDU: <= Type it again. - Principal "david@ATHENA.MIT.EDU" created. - kadmin: - -If you want to delete a principal :: - - kadmin: delprinc jennifer - Are you sure you want to delete the principal - "jennifer@ATHENA.MIT.EDU"? (yes/no): yes - Principal "jennifer@ATHENA.MIT.EDU" deleted. - Make sure that you have removed this principal from - all ACLs before reusing. - kadmin: - - -Retrieving information about a principal -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To retrieve a listing of the attributes and/or policies associated -with a principal, use the :ref:`kadmin(1)` **get_principal** command. - -To generate a listing of principals, use the kadmin -**list_principals** command. - -.. include:: admin_commands/kadmin_local.rst - :start-after: _get_principal: - :end-before: _get_principal_end: - -.. include:: admin_commands/kadmin_local.rst - :start-after: _list_principals: - :end-before: _list_principals_end: - - -Changing passwords -~~~~~~~~~~~~~~~~~~ - -To change a principal's password use the :ref:`kadmin(1)` -**change_password** command. - -.. include:: admin_commands/kadmin_local.rst - :start-after: _change_password: - :end-before: _change_password_end: - -.. note:: Password changes through kadmin are subject to the same - password policies as would apply to password changes through - :ref:`kpasswd(1)`. - - -Policies --------- - -A policy is a set of rules governing passwords. Policies can dictate -minimum and maximum password lifetimes, minimum number of characters -and character classes a password must contain, and the number of old -passwords kept in the database. - - -Adding, modifying and deleting policies -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To add a new policy, use the :ref:`kadmin(1)` **add_policy** command. - -To modify attributes of a principal, use the kadmin **modify_policy** -command. - -To delete a policy, use the kadmin **delete_policy** command. - -.. include:: admin_commands/kadmin_local.rst - :start-after: _add_policy: - :end-before: _add_policy_end: - -.. include:: admin_commands/kadmin_local.rst - :start-after: _modify_policy: - :end-before: _modify_policy_end: - -.. include:: admin_commands/kadmin_local.rst - :start-after: _delete_policy: - :end-before: _delete_policy_end: - -.. note:: You must cancel the policy from *all* principals before - deleting it. The *delete_policy* command will fail if the policy - is in use by any principals. - - -Retrieving policies -~~~~~~~~~~~~~~~~~~~ - -To retrieve a policy, use the :ref:`kadmin(1)` **get_policy** command. - -You can retrieve the list of policies with the kadmin -**list_policies** command. - -.. include:: admin_commands/kadmin_local.rst - :start-after: _get_policy: - :end-before: _get_policy_end: - -.. include:: admin_commands/kadmin_local.rst - :start-after: _list_policies: - :end-before: _list_policies_end: - - -Updating the history key -~~~~~~~~~~~~~~~~~~~~~~~~ - -If a policy specifies a number of old keys kept of two or more, the -stored old keys are encrypted in a history key, which is found in the -key data of the ``kadmin/history`` principal. - -Currently there is no support for proper rollover of the history key, -but you can change the history key (for example, to use a better -encryption type) at the cost of invalidating currently stored old -keys. To change the history key, run:: - - kadmin: change_password -randkey kadmin/history - -This command will fail if you specify the **-keepold** flag. Only one -new history key will be created, even if you specify multiple key/salt -combinations. - -In the future, we plan to migrate towards encrypting old keys in the -master key instead of the history key, and implementing proper -rollover support for stored old keys. - - -.. _privileges: - -Privileges ----------- - -Administrative privileges for the Kerberos database are stored in the -file :ref:`kadm5.acl(5)`. - -.. note:: A common use of an admin instance is so you can grant - separate permissions (such as administrator access to the - Kerberos database) to a separate Kerberos principal. For - example, the user ``joeadmin`` might have a principal for - his administrative use, called ``joeadmin/admin``. This - way, ``joeadmin`` would obtain ``joeadmin/admin`` tickets - only when he actually needs to use those permissions. - - -.. _db_operations: - -Operations on the Kerberos database ------------------------------------ - -The :ref:`kdb5_util(8)` command is the primary tool for administrating -the Kerberos database. - -.. include:: admin_commands/kdb5_util.rst - :start-after: _kdb5_util_synopsis: - :end-before: _kdb5_util_synopsis_end: - -**OPTIONS** - -.. include:: admin_commands/kdb5_util.rst - :start-after: _kdb5_util_options: - :end-before: _kdb5_util_options_end: - -.. toctree:: - :maxdepth: 1 - - -Dumping a Kerberos database to a file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To dump a Kerberos database into a file, use the :ref:`kdb5_util(8)` -**dump** command on one of the KDCs. - -.. include:: admin_commands/kdb5_util.rst - :start-after: _kdb5_util_dump: - :end-before: _kdb5_util_dump_end: - - -Examples -######## - -:: - - shell% kdb5_util dump dumpfile - shell% - - shell% kbd5_util dump -verbose dumpfile - kadmin/admin@ATHENA.MIT.EDU - krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU - kadmin/history@ATHENA.MIT.EDU - K/M@ATHENA.MIT.EDU - kadmin/changepw@ATHENA.MIT.EDU - shell% - -If you specify which principals to dump, you must use the full -principal, as in the following example:: - - shell% kdb5_util dump -verbose dumpfile K/M@ATHENA.MIT.EDU kadmin/admin@ATHENA.MIT.EDU - kadmin/admin@ATHENA.MIT.EDU - K/M@ATHENA.MIT.EDU - shell% - -Otherwise, the principals will not match those in the database and -will not be dumped:: - - shell% kdb5_util dump -verbose dumpfile K/M kadmin/admin - shell% - -If you do not specify a dump file, kdb5_util will dump the database to -the standard output. - - -.. _restore_from_dump: - -Restoring a Kerberos database from a dump file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To restore a Kerberos database dump from a file, use the -:ref:`kdb5_util(8)` **load** command on one of the KDCs. - -.. include:: admin_commands/kdb5_util.rst - :start-after: _kdb5_util_load: - :end-before: _kdb5_util_load_end: - - -Examples -######## - -To load a single principal, either replacing or updating the database: - -:: - - shell% kdb5_util load dumpfile principal - shell% - - shell% kdb5_util load -update dumpfile principal - shell% - - -.. note:: If the database file exists, and the *-update* flag was not - given, *kdb5_util* will overwrite the existing database. - -Using kdb5_util to upgrade a master KDC from krb5 1.1.x: - -:: - - shell% kdb5_util dump old-kdb-dump - shell% kdb5_util dump -ov old-kdb-dump.ov - [Create a new KDC installation, using the old stash file/master password] - shell% kdb5_util load old-kdb-dump - shell% kdb5_util load -update old-kdb-dump.ov - -The use of old-kdb-dump.ov for an extra dump and load is necessary -to preserve per-principal policy information, which is not included in -the default dump format of krb5 1.1.x. - -.. note:: Using kdb5_util to dump and reload the principal database is - only necessary when upgrading from versions of krb5 prior - to 1.2.0---newer versions will use the existing database as-is. - - -.. _create_stash: - -Creating a stash file -~~~~~~~~~~~~~~~~~~~~~ - -A stash file allows a KDC to authenticate itself to the database -utilities, such as :ref:`kadmind(8)`, :ref:`krb5kdc(8)`, and -:ref:`kdb5_util(8)`. - -To create a stash file, use the :ref:`kdb5_util(8)` **stash** command. - -.. include:: admin_commands/kdb5_util.rst - :start-after: _kdb5_util_stash: - :end-before: _kdb5_util_stash_end: - - -Example -####### - - shell% kdb5_util stash - kdb5_util: Cannot find/read stored master key while reading master key - kdb5_util: Warning: proceeding without master key - Enter KDC database master key: <= Type the KDC database master password. - shell% - -If you do not specify a stash file, kdb5_util will stash the key in -the file specified in your :ref:`kdc.conf(5)` file. - - -Creating and destroying a Kerberos database -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you need to create a new Kerberos database, use the -:ref:`kdb5_util(8)` **create** command. - -.. include:: admin_commands/kdb5_util.rst - :start-after: _kdb5_util_create: - :end-before: _kdb5_util_create_end: - -If you need to destroy the current Kerberos database, use the -:ref:`kdb5_util(8)` **destroy** command. - -.. include:: admin_commands/kdb5_util.rst - :start-after: _kdb5_util_destroy: - :end-before: _kdb5_util_destroy_end: - - -Examples -######## - -:: - - shell% kdb5_util -r ATHENA.MIT.EDU create -s - Loading random data - Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU', - master key name 'K/M@ATHENA.MIT.EDU' - You will be prompted for the database Master Password. - It is important that you NOT FORGET this password. - Enter KDC database master key: <= Type the master password. - Re-enter KDC database master key to verify: <= Type it again. - shell% - - shell% kdb5_util -r ATHENA.MIT.EDU destroy - Deleting KDC database stored in '/usr/local/var/krb5kdc/principal', are you sure? - (type 'yes' to confirm)? <= yes - OK, deleting database '/usr/local/var/krb5kdc/principal'... - ** Database '/usr/local/var/krb5kdc/principal' destroyed. - shell% - - -.. _ops_on_ldap: - -Operations on the LDAP database -------------------------------- - -The :ref:`kdb5_ldap_util(8)` is the primary tool for administrating -the Kerberos LDAP database. It allows an administrator to manage -realms, Kerberos services (KDC and Admin Server) and ticket policies. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_synopsis: - :end-before: _kdb5_ldap_util_synopsis_end: - -**OPTIONS** - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_options: - :end-before: _kdb5_ldap_util_options_end: - - -.. _ldap_create_realm: - -Creating a Kerberos realm -~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you need to create a new realm, use the :ref:`kdb5_ldap_util(8)` -**create** command as follows. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_create: - :end-before: _kdb5_ldap_util_create_end: - - -.. _ldap_mod_realm: - -Modifying a Kerberos realm -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you need to modify a realm, use the :ref:`kdb5_ldap_util(8)` -**modify** command as follows. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_modify: - :end-before: _kdb5_ldap_util_modify_end: - - -Destroying a Kerberos realm -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you need to destroy a Kerberos realm, use the -:ref:`kdb5_ldap_util(8)` **destroy** command as follows. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_destroy: - :end-before: _kdb5_ldap_util_destroy_end: - - -Retrieving information about a Kerberos realm -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you need to display the attributes of a realm, use the -:ref:`kdb5_ldap_util(8)` **view** command as follows. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_view: - :end-before: _kdb5_ldap_util_view_end: - - -Listing available Kerberos realms -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you need to display the list of the realms, use the -:ref:`kdb5_ldap_util(8)` **list** command as follows. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_list: - :end-before: _kdb5_ldap_util_list_end: - - -.. _stash_ldap: - -Stashing service object's password -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The :ref:`kdb5_ldap_util(8)` **stashsrvpw** command allows an -administrator to store the password of service object in a file. The -KDC and Administration server uses this password to authenticate to -the LDAP server. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_stashsrvpw: - :end-before: _kdb5_ldap_util_stashsrvpw_end: - - -Ticket Policy operations -~~~~~~~~~~~~~~~~~~~~~~~~ - -Creating a Ticket Policy -######################## - -To create a new ticket policy in directory , use the -:ref:`kdb5_ldap_util(8)` **create_policy** command. Ticket policy -objects are created under the realm container. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_create_policy: - :end-before: _kdb5_ldap_util_create_policy_end: - - -Modifying a Ticket Policy -######################### - -To modify a ticket policy in directory, use the -:ref:`kdb5_ldap_util(8)` **modify_policy** command. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_modify_policy: - :end-before: _kdb5_ldap_util_modify_policy_end: - - -Retrieving Information About a Ticket Policy -############################################ - -To display the attributes of a ticket policy, use the -:ref:`kdb5_ldap_util(8)` **view_policy** command. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_view_policy: - :end-before: _kdb5_ldap_util_view_policy_end: - - -Destroying a Ticket Policy -########################## - -To destroy an existing ticket policy, use the :ref:`kdb5_ldap_util(8)` -**destroy_policy** command. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_destroy_policy: - :end-before: _kdb5_ldap_util_destroy_policy_end: - - -Listing available Ticket Policies -################################# - -To list the name of ticket policies in a realm, use the -:ref:`kdb5_ldap_util(8)` **list_policy** command. - -.. include:: admin_commands/kdb5_ldap_util.rst - :start-after: _kdb5_ldap_util_list_policy: - :end-before: _kdb5_ldap_util_list_policy_end: - - -.. _xrealm_authn: - -Cross-realm authentication --------------------------- - -In order for a KDC in one realm to authenticate Kerberos users in a -different realm, it must share a key with the KDC in the other realm. -In both databases, there must be krbtgt service principals for both realms. -For example, if you need to do cross-realm authentication between the realms -``ATHENA.MIT.EDU`` and ``EXAMPLE.COM``, you would need to add the -principals ``krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU`` and -``krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM`` to both databases. -These principals must all have the same passwords, key version -numbers, and encryption types; this may require explicitly setting -the key version number with the **-kvno** option. - -In the ATHENA.MIT.EDU and EXAMPLE.COM cross-realm case, the administrators -would run the following commands on the KDCs in both realms:: - - shell%: kadmin.local -e "aes256-cts:normal" - kadmin: addprinc -requires_preauth krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM - Enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM: - Re-enter password for principal krbtgt/ATHENA.MIT.EDU@EXAMPLE.COM: - kadmin: addprinc -requires_preauth krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU - Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU: - Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU: - kadmin: - -.. note:: Even if most principals in a realm are generally created - with the **requires_preauth** flag enabled, this flag is not - desirable on cross-realm authentication keys because doing - so makes it impossible to disable preauthentication on a - service-by-service basis. Disabling it as in the example - above is recommended. - -.. note:: It is very important that these principals have good - passwords. MIT recommends that TGT principal passwords be - at least 26 characters of random ASCII text. - - -.. _changing_krbtgt_key: - -Changing the krbtgt key ------------------------ - -A Kerberos Ticket Granting Ticket (TGT) is a service ticket for the -principal ``krbtgt/REALM``. The key for this principal is created -when the Kerberos database is initialized and need not be changed. -However, it will only have the encryption types supported by the KDC -at the time of the initial database creation. To allow use of newer -encryption types for the TGT, this key has to be changed. - -Changing this key using the normal :ref:`kadmin(1)` -**change_password** command would invalidate any previously issued -TGTs. Therefore, when changing this key, normally one should use the -**-keepold** flag to change_password to retain the previous key in the -database as well as the new key. For example:: - - kadmin: change_password -randkey -keepold krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU - -.. warning:: After issuing this command, the old key is still valid - and is still vulnerable to (for instance) brute force - attacks. To completely retire an old key or encryption - type, run the kadmin **purgekeys** command to delete keys - with older kvnos, ideally first making sure that all - tickets issued with the old keys have expired. - - -.. _incr_db_prop: - -Incremental database propagation --------------------------------- - -Overview -~~~~~~~~ - -At some very large sites, dumping and transmitting the database can -take more time than is desirable for changes to propagate from the -master KDC to the slave KDCs. The incremental propagation support -added in the 1.7 release is intended to address this. - -With incremental propagation enabled, all programs on the master KDC -that change the database also write information about the changes to -an "update log" file, maintained as a circular buffer of a certain -size. A process on each slave KDC connects to a service on the master -KDC (currently implemented in the :ref:`kadmind(8)` server) and -periodically requests the changes that have been made since the last -check. By default, this check is done every two minutes. If the -database has just been modified in the previous several seconds -(currently the threshold is hard-coded at 10 seconds), the slave will -not retrieve updates, but instead will pause and try again soon after. -This reduces the likelihood that incremental update queries will cause -delays for an administrator trying to make a bunch of changes to the -database at the same time. - -Incremental propagation uses the following entries in the per-realm -data in the KDC config file (See :ref:`kdc.conf(5)`): - -====================== =============== =========================================== -iprop_enable *boolean* If *true*, then incremental propagation is enabled, and (as noted below) normal kprop propagation is disabled. The default is *false*. -iprop_master_ulogsize *integer* Indicates the number of entries that should be retained in the update log. The default is 1000; the maximum number is 2500. -iprop_slave_poll *time interval* Indicates how often the slave should poll the master KDC for changes to the database. The default is two minutes. -iprop_port *integer* Specifies the port number to be used for incremental propagation. This is required in both master and slave configuration files. -iprop_resync_timeout *integer* Specifies the number of seconds to wait for a full propagation to complete. This is optional on slave configurations. Defaults to 300 seconds (5 minutes). -iprop_logfile *file name* Specifies where the update log file for the realm database is to be stored. The default is to use the *database_name* entry from the realms section of the config file :ref:`kdc.conf(5)`, with *.ulog* appended. (NOTE: If database_name isn't specified in the realms section, perhaps because the LDAP database back end is being used, or the file name is specified in the *dbmodules* section, then the hard-coded default for *database_name* is used. Determination of the *iprop_logfile* default value will not use values from the *dbmodules* section.) -====================== =============== =========================================== - -Both master and slave sides must have a principal named -``kiprop/hostname`` (where *hostname* is the lowercase, -fully-qualified, canonical name for the host) registered in the -Kerberos database, and have keys for that principal stored in the -default keytab file (|keytab|). - -On the master KDC side, the ``kiprop/hostname`` principal must be -listed in the kadmind ACL file :ref:`kadm5.acl(5)`, and given the -**p** privilege (see :ref:`privileges`). - -On the slave KDC side, :ref:`kpropd(8)` should be run. When -incremental propagation is enabled, it will connect to the kadmind on -the master KDC and start requesting updates. - -The normal kprop mechanism is disabled by the incremental propagation -support. However, if the slave has been unable to fetch changes from -the master KDC for too long (network problems, perhaps), the log on -the master may wrap around and overwrite some of the updates that the -slave has not yet retrieved. In this case, the slave will instruct -the master KDC to dump the current database out to a file and invoke a -one-time kprop propagation, with special options to also convey the -point in the update log at which the slave should resume fetching -incremental updates. Thus, all the keytab and ACL setup previously -described for kprop propagation is still needed. - -There are several known bugs and restrictions in the current -implementation: - -- The "call out to kprop" mechanism is a bit fragile; if the kprop - propagation fails to connect for some reason, the process on the - slave may hang waiting for it, and will need to be restarted. -- The master and slave must be able to initiate TCP connections in - both directions, without an intervening NAT. - - -Sun/MIT incremental propagation differences -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sun donated the original code for supporting incremental database -propagation to MIT. Some changes have been made in the MIT source -tree that will be visible to administrators. (These notes are based -on Sun's patches. Changes to Sun's implementation since then may not -be reflected here.) - -The Sun config file support looks for ``sunw_dbprop_enable``, -``sunw_dbprop_master_ulogsize``, and ``sunw_dbprop_slave_poll``. - -The incremental propagation service is implemented as an ONC RPC -service. In the Sun implementation, the service is registered with -rpcbind (also known as portmapper) and the client looks up the port -number to contact. In the MIT implementation, where interaction with -some modern versions of rpcbind doesn't always work well, the port -number must be specified in the config file on both the master and -slave sides. - -The Sun implementation hard-codes pathnames in ``/var/krb5`` for the -update log and the per-slave kprop dump files. In the MIT -implementation, the pathname for the update log is specified in the -config file, and the per-slave dump files are stored in -|kdcdir|\ ``/slave_datatrans_hostname``. diff --git a/doc/rst_source/krb_admins/env_variables.rst b/doc/rst_source/krb_admins/env_variables.rst deleted file mode 100644 index e85d54da0..000000000 --- a/doc/rst_source/krb_admins/env_variables.rst +++ /dev/null @@ -1,45 +0,0 @@ -Environment variables -===================== - -The following environment variables can be used during runtime: - -**KRB5_CONFIG** - Main Kerberos configuration file. (See :ref:`mitK5defaults` for - the default name.) - -**KRB5_KDC_PROFILE** - KDC configuration file. (See :ref:`mitK5defaults` for the default - name.) - -**KRB5_KTNAME** - Default keytab file name. (See :ref:`mitK5defaults` for the - default name.) - -**KRB5_CLIENT_KTNAME** - Default client keytab file name. (See :ref:`mitK5defaults` for - the default name.) - -**KRB5CCNAME** - Default name for the credentials cache file, in the form *type*\:\ - *residual*. The type of the default cache may determine the - availability of a cache collection. For instance, a default cache - of type ``DIR`` causes caches within the directory to be present - in the global cache collection. - -**KRB5RCACHETYPE** - Default replay cache type. Defaults to ``dfl``. A value of - ``none`` disables the replay cache. - -**KRB5RCACHEDIR** - Default replay cache directory. (See :ref:`mitK5defaults` for the - default location.) - -**KPROP_PORT** - :ref:`kprop(8)` port to use. Defaults to 754. - -**KRB5_TRACE** - Filename for trace-logging output (introduced in release 1.9). - For example, ``env KRB5_TRACE=/dev/stdout kinit`` would send - tracing information for kinit to ``/dev/stdout``. Some programs - may ignore this variable (particularly setuid or login system - programs). diff --git a/doc/rst_source/krb_admins/host_config.rst b/doc/rst_source/krb_admins/host_config.rst deleted file mode 100644 index e5ef06bf1..000000000 --- a/doc/rst_source/krb_admins/host_config.rst +++ /dev/null @@ -1,110 +0,0 @@ -Host configuration -================== - -All hosts running Kerberos software, whether they are clients, -application servers, or KDCs, can be configured using -:ref:`krb5.conf(5)`. Here we describe some of the behavior changes -you might want to make. - - -.. _plugin_config: - -Plugin module configuration ---------------------------- - -Many aspects of Kerberos behavior, such as client preauthentication -and KDC service location, can be modified through the use of plugin -modules. For most of these behaviors, you can use the :ref:`plugins` -section of krb5.conf to register third-party modules, and to switch -off registered or built-in modules. - -A plugin module takes the form of a Unix shared object -(``modname.so``) or Windows DLL (``modname.dll``). If you have -installed a third-party plugin module and want to register it, you do -so using the **module** relation in the appropriate subsection of the -[plugins] section. The value for **module** must give the module name -and the path to the module, separated by a colon. The module name -will often be the same as the shared object's name, but in unusual -cases (such as a shared object which implements multiple modules for -the same interface) it might not be. For example, to register a -client preauthentication module named ``otp`` installed at -``/path/to/otp.so``, you could write:: - - [plugins] - clpreauth = { - module = otp:/path/to/otp.so - } - -Many of the pluggable behaviors in MIT krb5 contain built-in modules -which can be switched off. You can disable a built-in module (or one -you have registered) using the **disable** directive in the -appropriate subsection of the [plugins] section. For example, to -disable the use of .k5identity files to select credential caches, you -could write:: - - [plugins] - ccselect = { - disable = k5identity - } - -If you want to disable multiple modules, specify the **disable** -directive multiple times, giving one module to disable each time. - -Alternatively, you can explicitly specify which modules you want to be -enabled for that behavior using the **enable_only** directive. For -example, to make :ref:`kadmind(8)` check password quality using only a -module you have registered, and no other mechanism, you could write:: - - [plugins] - pwqual = { - module = mymodule:/path/to/mymodule.so - enable_only = mymodule - } - -Again, if you want to specify multiple modules, specify the -**enable_only** directive multiple times, giving one module to enable -each time. - -Some Kerberos interfaces use different mechanisms to register plugin -modules. - - -KDC location modules -~~~~~~~~~~~~~~~~~~~~ - -For historical reasons, modules to control how KDC servers are located -are registered simply by placing the shared object or DLL into the -"libkrb5" subdirectory of the krb5 plugin directory, which defaults to -|libdir|\ ``/krb5/plugins``. For example, Samba's winbind krb5 -locator plugin would be registered by placing its shared object in -|libdir|\ ``/krb5/plugins/libkrb5/winbind_krb5_locator.so``. - - -GSSAPI mechanism modules -~~~~~~~~~~~~~~~~~~~~~~~~ - -GSSAPI mechanism module are registered using the file -``/etc/gss/mech``. Each line in this file has the form:: - - oid pathname [options] - -where *oid* is the object identifier of the GSSAPI mechanism to be -registered, *pathname* is a path to the module shared object or DLL, -and *options* (if present) are options provided to the plugin module, -surrounded in square brackets. - - -.. _profile_plugin_config: - -Configuration profile modules -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A configuration profile module replaces the information source for -:ref:`krb5.conf(5)` itself. To use a profile module, begin krb5.conf -with the line:: - - module PATHNAME:STRING - -where *PATHNAME* is a path to the module shared object or DLL, and -*STRING* is a string to provide to the module. The module will then -take over, and the rest of krb5.conf will be ignored. diff --git a/doc/rst_source/krb_admins/index.rst b/doc/rst_source/krb_admins/index.rst deleted file mode 100644 index 96f1a310d..000000000 --- a/doc/rst_source/krb_admins/index.rst +++ /dev/null @@ -1,24 +0,0 @@ -For administrators -================== - -.. toctree:: - :maxdepth: 1 - - install.rst - conf_files/index.rst - realm_config.rst - database.rst - conf_ldap.rst - appl_servers.rst - host_config.rst - backup_host.rst - -.. toctree:: - :maxdepth: 1 - - admin_commands/index.rst - ../mitK5defaults.rst - env_variables.rst - troubleshoot.rst - advanced/index.rst - various_envs.rst diff --git a/doc/rst_source/krb_admins/install.rst b/doc/rst_source/krb_admins/install.rst deleted file mode 100644 index a79bda952..000000000 --- a/doc/rst_source/krb_admins/install.rst +++ /dev/null @@ -1,21 +0,0 @@ -Installation guide -================== - -Contents --------- - -.. toctree:: - :maxdepth: 2 - - install_kdc.rst - install_clients.rst - install_appl_srv.rst - - -Additional references ---------------------- - -#. Debian: `Setting up MIT Kerberos 5 - `_ -#. Solaris: `Configuring the Kerberos Service - `_ diff --git a/doc/rst_source/krb_admins/install_appl_srv.rst b/doc/rst_source/krb_admins/install_appl_srv.rst deleted file mode 100644 index 149050098..000000000 --- a/doc/rst_source/krb_admins/install_appl_srv.rst +++ /dev/null @@ -1,83 +0,0 @@ -UNIX Application Servers -======================== - -An application server is a host that provides one or more services -over the network. Application servers can be "secure" or "insecure." -A "secure" host is set up to require authentication from every client -connecting to it. An "insecure" host will still provide Kerberos -authentication, but will also allow unauthenticated clients to -connect. - -If you have Kerberos V5 installed on all of your client machines, MIT -recommends that you make your hosts secure, to take advantage of the -security that Kerberos authentication affords. However, if you have -some clients that do not have Kerberos V5 installed, you can run an -insecure server, and still take advantage of Kerberos V5's single -sign-on capability. - - -.. _keytab_file: - -The keytab file ---------------- - -All Kerberos server machines need a keytab file to authenticate to the -KDC. By default on UNIX-like systems this file is named |keytab|. -The keytab file is an local copy of the host's key. The keytab file -is a potential point of entry for a break-in, and if compromised, -would allow unrestricted access to its host. The keytab file should -be readable only by root, and should exist only on the machine's local -disk. The file should not be part of any backup of the machine, -unless access to the backup data is secured as tightly as access to -the machine's root password. - -In order to generate a keytab for a host, the host must have a -principal in the Kerberos database. The procedure for adding hosts to -the database is described fully in :ref:`add_mod_del_princs`. (See -:ref:`slave_host_key` for a brief description.) The keytab is -generated by running :ref:`kadmin(1)` and issuing the :ref:`ktadd` -command. - -For example, to generate a keytab file to allow the host -``trillium.mit.edu`` to authenticate for the services host, ftp, and -pop, the administrator ``joeadmin`` would issue the command (on -``trillium.mit.edu``):: - - trillium% kadmin - kadmin5: ktadd host/trillium.mit.edu ftp/trillium.mit.edu - pop/trillium.mit.edu - kadmin: Entry for principal host/trillium.mit.edu@ATHENA.MIT.EDU with - kvno 3, encryption type DES-CBC-CRC added to keytab - FILE:/etc/krb5.keytab. - kadmin: Entry for principal ftp/trillium.mit.edu@ATHENA.MIT.EDU with - kvno 3, encryption type DES-CBC-CRC added to keytab - FILE:/etc/krb5.keytab. - kadmin: Entry for principal pop/trillium.mit.edu@ATHENA.MIT.EDU with - kvno 3, encryption type DES-CBC-CRC added to keytab - FILE:/etc/krb5.keytab. - kadmin5: quit - trillium% - -If you generate the keytab file on another host, you need to get a -copy of the keytab file onto the destination host (``trillium``, in -the above example) without sending it unencrypted over the network. - - -Some advice about secure hosts ------------------------------- - -Kerberos V5 can protect your host from certain types of break-ins, but -it is possible to install Kerberos V5 and still leave your host -vulnerable to attack. Obviously an installation guide is not the -place to try to include an exhaustive list of countermeasures for -every possible attack, but it is worth noting some of the larger holes -and how to close them. - -We recommend that backups of secure machines exclude the keytab file -(|keytab|). If this is not possible, the backups should at least be -done locally, rather than over a network, and the backup tapes should -be physically secured. - -The keytab file and any programs run by root, including the Kerberos -V5 binaries, should be kept on local disk. The keytab file should be -readable only by root. diff --git a/doc/rst_source/krb_admins/install_clients.rst b/doc/rst_source/krb_admins/install_clients.rst deleted file mode 100644 index ec2cd8125..000000000 --- a/doc/rst_source/krb_admins/install_clients.rst +++ /dev/null @@ -1,57 +0,0 @@ -Installing and configuring UNIX client machines -=============================================== - -The Kerberized client programs include :ref:`kinit(1)`, -:ref:`klist(1)`, :ref:`kdestroy(1)`, and :ref:`kpasswd(1)`. All of -these programs are in the directory |bindir|. - -You can often integrate Kerberos with the login system on client -machines, typically through the use of PAM. The details vary by -operating system, and should be covered in your operating system's -documentation. If you do this, you will need to make sure your users -know to use their Kerberos passwords when they log in. - -You will also need to educate your users to use the ticket management -programs kinit, klist, and kdestroy. If you do not have Kerberos -password changing integrated into the native password program (again, -typically through PAM), you will need to educate users to use kpasswd -in place of its non-Kerberos counterparts passwd. - - -Client machine configuration files ----------------------------------- - -Each machine running Kerberos should have a :ref:`krb5.conf(5)` file. -At a minimum, it should define a **default_realm** setting in -:ref:`libdefaults`. If you are not using DNS SRV records, it must -also contain a :ref:`realms` section containing information for your -realm's KDCs. - -Consider setting **rdns** to false in order to reduce your dependence -on precisely correct DNS information for service hostnames. Turning -this flag off means that service hostnames will be canonicalized -through forward name resolution (which adds your domain name to -unqualified hostnames, and resolves CNAME records in DNS), but not -through reverse address lookup. The default value of this flag is -true for historical reasons only. - -If you anticipate users frequently logging into remote hosts -(e.g., using ssh) using forwardable credentials, consider setting -**forwardable** to true so that users obtain forwardable tickets by -default. Otherwise users will need to use ``kinit -f`` to get -forwardable tickets. - -Consider adjusting the **ticket_lifetime** setting to match the likely -length of sessions for your users. For instance, if most of your -users will be logging in for an eight-hour workday, you could set the -default to ten hours so that tickets obtained in the morning expire -shortly after the end of the workday. Users can still manually -request longer tickets when necessary, up to the maximum allowed by -each user's principal record on the KDC. - -If a client host may access services in different realms, it may be -useful to define a :ref:`domain_realm` mapping so that clients know -which hosts belong to which realms. However, if your clients and KDC -are running release 1.7 or later, it is also reasonable to leave this -section out on client machines and just define it in the KDC's -krb5.conf. diff --git a/doc/rst_source/krb_admins/install_kdc.rst b/doc/rst_source/krb_admins/install_kdc.rst deleted file mode 100644 index 3d0d0f1f4..000000000 --- a/doc/rst_source/krb_admins/install_kdc.rst +++ /dev/null @@ -1,525 +0,0 @@ -Installing KDCs -=============== - -When setting up Kerberos in a production environment, it is best to -have multiple slave KDCs alongside with a master KDC to ensure the -continued availability of the Kerberized services. Each KDC contains -a copy of the Kerberos database. The master KDC contains the writable -copy of the realm database, which it replicates to the slave KDCs at -regular intervals. All database changes (such as password changes) -are made on the master KDC. Slave KDCs provide Kerberos -ticket-granting services, but not database administration, when the -master KDC is unavailable. MIT recommends that you install all of -your KDCs to be able to function as either the master or one of the -slaves. This will enable you to easily switch your master KDC with -one of the slaves if necessary (see :ref:`switch_master_slave`). This -installation procedure is based on that recommendation. - -.. warning:: - - The Kerberos system relies on the availability of correct time - information. Ensure that the master and all slave KDCs have - properly synchronized clocks. - - - It is best to install and run KDCs on secured and dedicated - hardware with limited access. If your KDC is also a file - server, FTP server, Web server, or even just a client machine, - someone who obtained root access through a security hole in any - of those areas could potentially gain access to the Kerberos - database. - - -Install and configure the master KDC ------------------------------------- - -Install Kerberos either from the OS-provided packages or from the -source (See :ref:`do_build`). - -.. note:: For the purpose of this document we will use the following - names:: - - kerberos.mit.edu - master KDC - kerberos-1.mit.edu - slave KDC - ATHENA.MIT.EDU - realm name - .k5.ATHENA.MIT.EDU - stash file - admin/admin - admin principal - - See :ref:`mitK5defaults` for the default names and locations - of the relevant to this topic files. Adjust the names and - paths to your system environment. - - -Edit KDC configuration files ----------------------------- - -Modify the configuration files, :ref:`krb5.conf(5)` and -:ref:`kdc.conf(5)`, to reflect the correct information (such as -domain-realm mappings and Kerberos servers names) for your realm. -(See :ref:`mitK5defaults` for the recommended default locations for -these files). - -Most of the tags in the configuration have default values that will -work well for most sites. There are some tags in the -:ref:`krb5.conf(5)` file whose values must be specified, and this -section will explain those. - -If the locations for these configuration files differs from the -default ones, set **KRB5_CONFIG** and **KRB5_KDC_PROFILE** environment -variables to point to the krb5.conf and kdc.conf respectively. For -example:: - - export KRB5_CONFIG=/yourdir/krb5.conf - export KRB5_KDC_PROFILE=/yourdir/kdc.conf - - -krb5.conf -~~~~~~~~~ - -If you are not using DNS TXT records (see :ref:`mapping_hostnames`), -you must specify the **default_realm** in the :ref:`libdefaults` -section. If you are not using DNS SRV records (see -:ref:`kdc_hostnames`), you must include the **kdc** tag for each -*realm* in the :ref:`realms` section. To communicate with the kadmin -server in each realm, the **admin_server** tag must be set in the -:ref:`realms` section. - -An example krb5.conf file:: - - [libdefaults] - default_realm = ATHENA.MIT.EDU - - [realms] - ATHENA.MIT.EDU = { - kdc = kerberos.mit.edu - kdc = kerberos-1.mit.edu - admin_server = kerberos.mit.edu - } - - -kdc.conf -~~~~~~~~ - -The kdc.conf file can be used to control the listening ports of the -KDC and kadmind, as well as realm-specific defaults, the database type -and location, and logging. - -An example kdc.conf file:: - - [kdcdefaults] - kdc_ports = 88,750 - - [realms] - ATHENA.MIT.EDU = { - kadmind_port = 749 - max_life = 12h 0m 0s - max_renewable_life = 7d 0h 0m 0s - master_key_type = aes256-cts - supported_enctypes = aes256-cts:normal aes128-cts:normal - # If the default location does not suit your setup, - # explicitly configure the following values: - # database_name = /var/krb5kdc/principal - # key_stash_file = /var/krb5kdc/.k5.ATHENA.MIT.EDU - # acl_file = /var/krb5kdc/kadm5.acl - } - - [logging] - # By default, the KDC and kadmind will log output using - # syslog. You can instead send log output to files like this: - kdc = FILE:/var/log/krb5kdc.log - admin_server = FILE:/var/log/kadmin.log - default = FILE:/var/log/krb5lib.log - -Replace ``ATHENA.MIT.EDU`` and ``kerberos.mit.edu`` with the name of -your Kerberos realm and server respectively. - -.. note:: You have to have write permission on the target directories - (these directories must exist) used by **database_name**, - **key_stash_file**, and **acl_file**. - - -.. _create_db: - -Create the KDC database ------------------------ - -You will use the :ref:`kdb5_util(8)` command on the master KDC to -create the Kerberos database and the optional :ref:`stash_definition`. - -.. note:: If you choose not to install a stash file, the KDC will - prompt you for the master key each time it starts up. This - means that the KDC will not be able to start automatically, - such as after a system reboot. - -:ref:`kdb5_util(8)` will prompt you for the master password for the -Kerberos database. This password can be any string. A good password -is one you can remember, but that no one else can guess. Examples of -bad passwords are words that can be found in a dictionary, any common -or popular name, especially a famous person (or cartoon character), -your username in any form (e.g., forward, backward, repeated twice, -etc.), and any of the sample passwords that appear in this manual. -One example of a password which might be good if it did not appear in -this manual is "MITiys4K5!", which represents the sentence "MIT is -your source for Kerberos 5!" (It's the first letter of each word, -substituting the numeral "4" for the word "for", and includes the -punctuation mark at the end.) - -The following is an example of how to create a Kerberos database and -stash file on the master KDC, using the :ref:`kdb5_util(8)` command. -Replace ``ATHENA.MIT.EDU`` with the name of your Kerberos realm:: - - shell% kdb5_util create -r ATHENA.MIT.EDU -s - - Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU', - master key name 'K/M@ATHENA.MIT.EDU' - You will be prompted for the database Master Password. - It is important that you NOT FORGET this password. - Enter KDC database master key: <= Type the master password. - Re-enter KDC database master key to verify: <= Type it again. - shell% - -This will create five files in |kdcdir| (or at the locations specified -in :ref:`kdc.conf(5)`): - -* two Kerberos database files, ``principal``, and ``principal.ok`` -* the Kerberos administrative database file, ``principal.kadm5`` -* the administrative database lock file, ``principal.kadm5.lock`` -* the stash file, in this example ``.k5.ATHENA.MIT.EDU``. If you do - not want a stash file, run the above command without the **-s** - option. - -For more information on administrating Kerberos database see -:ref:`db_operations`. - - -.. _admin_acl: - -Add administrators to the ACL file ----------------------------------- - -Next, you need create an Access Control List (ACL) file and put the -Kerberos principal of at least one of the administrators into it. -This file is used by the :ref:`kadmind(8)` daemon to control which -principals may view and make privileged modifications to the Kerberos -database files. The ACL filename is determined by the **acl_file** -variable in :ref:`kdc.conf(5)`; the default is |kdcdir|\ -``/kadm5.acl``. - -For more information on Kerberos ACL file see :ref:`kadm5.acl(5)`. - -.. _addadmin_kdb: - -Add administrators to the Kerberos database -------------------------------------------- - -Next you need to add administrative principals (i.e., principals who -are allowed to administer Kerberos database) to the Kerberos database. -You *must* add at least one principal now to allow communication -between the Kerberos administration daemon kadmind and the kadmin -program over the network for further administration. To do this, use -the kadmin.local utility on the master KDC. kadmin.local is designed -to be run on the master KDC host without using Kerberos authentication -to an admin server; instead, it must have read and write access to the -Kerberos database on the local filesystem. - -The administrative principals you create should be the ones you added -to the ACL file (see :ref:`admin_acl`). - -In the following example, the administrative principal ``admin/admin`` -is created:: - - shell% kadmin.local - - kadmin.local: addprinc admin/admin@ATHENA.MIT.EDU - - WARNING: no policy specified for "admin/admin@ATHENA.MIT.EDU"; - assigning "default". - Enter password for principal admin/admin@ATHENA.MIT.EDU: <= Enter a password. - Re-enter password for principal admin/admin@ATHENA.MIT.EDU: <= Type it again. - Principal "admin/admin@ATHENA.MIT.EDU" created. - kadmin.local: - -.. _start_kdc_daemons: - -Start the Kerberos daemons on the master KDC --------------------------------------------- - -At this point, you are ready to start the Kerberos KDC -(:ref:`krb5kdc(8)`) and administrative daemons on the Master KDC. To -do so, type:: - - shell% krb5kdc - shell% kadmind - -Each server daemon will fork and run in the background. - -.. note:: Assuming you want these daemons to start up automatically at - boot time, you can add them to the KDC's ``/etc/rc`` or - ``/etc/inittab`` file. You need to have a - :ref:`stash_definition` in order to do this. - -You can verify that they started properly by checking for their -startup messages in the logging locations you defined in -:ref:`krb5.conf(5)` (see :ref:`logging`). For example:: - - shell% tail /var/log/krb5kdc.log - Dec 02 12:35:47 beeblebrox krb5kdc[3187](info): commencing operation - shell% tail /var/log/kadmin.log - Dec 02 12:35:52 beeblebrox kadmind[3189](info): starting - -Any errors the daemons encounter while starting will also be listed in -the logging output. - -As an additional verification, check if :ref:`kinit(1)` succeeds -against the principals that you have created on the previous step -(:ref:`addadmin_kdb`). Run:: - - shell% kinit admin/admin@ATHENA.MIT.EDU - - -Install the slave KDCs ----------------------- - -You are now ready to start configuring the slave KDCs. - -.. note:: Assuming you are setting the KDCs up so that you can easily - switch the master KDC with one of the slaves, you should - perform each of these steps on the master KDC as well as the - slave KDCs, unless these instructions specify otherwise. - - -.. _slave_host_key: - -Create host keytabs for slave KDCs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Each KDC needs a ``host`` key in the Kerberos database. These keys -are used for mutual authentication when propagating the database dump -file from the master KDC to the secondary KDC servers. - -On the master KDC, connect to administrative interface and create the -host principal for each of the KDCs' ``host`` services. For example, -if the master KDC were called ``kerberos.mit.edu``, and you had a -slave KDC named ``kerberos-1.mit.edu``, you would type the following:: - - shell% kadmin - kadmin: addprinc -randkey host/kerberos.mit.edu - NOTICE: no policy specified for "host/kerberos.mit.edu@ATHENA.MIT.EDU"; assigning "default" - Principal "host/kerberos.mit.edu@ATHENA.MIT.EDU" created. - - kadmin: addprinc -randkey host/kerberos-1.mit.edu - NOTICE: no policy specified for "host/kerberos-1.mit.edu@ATHENA.MIT.EDU"; assigning "default" - Principal "host/kerberos-1.mit.edu@ATHENA.MIT.EDU" created. - -It is not strictly necessary to have the master KDC server in the -Kerberos database, but it can be handy if you want to be able to swap -the master KDC with one of the slaves. - -Next, extract ``host`` random keys for all participating KDCs and -store them in each host's default keytab file. Ideally, you should -extract each keytab locally on its own KDC. If this is not feasible, -you should use an encrypted session to send them across the network. -To extract a keytab on a slave KDC called ``kerberos-1.mit.edu``, you -would execute the following command:: - - kadmin: ktadd host/kerberos-1.mit.edu - Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption - type aes256-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab. - Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption - type aes128-cts-hmac-sha1-96 added to keytab FILE:/etc/krb5.keytab. - Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption - type des3-cbc-sha1 added to keytab FILE:/etc/krb5.keytab. - Entry for principal host/kerberos-1.mit.edu with kvno 2, encryption - type arcfour-hmac added to keytab FILE:/etc/krb5.keytab. - - -Configure slave KDCs -~~~~~~~~~~~~~~~~~~~~ - -Database propagation copies the contents of the master's database, but -does not propagate configuration files, stash files, or the kadm5 ACL -file. The following files must be copied by hand to each slave (see -:ref:`mitK5defaults` for the default locations for these files): - -* krb5.conf -* kdc.conf -* kadm5.acl -* master key stash file - -Move the copied files into their appropriate directories, exactly as -on the master KDC. kadm5.acl is only needed to allow a slave to swap -with the master KDC. - -The database is propagated from the master KDC to the slave KDCs via -the :ref:`kpropd(8)` daemon. You must explicitly specify the -principals which are allowed to provide Kerberos dump updates on the -slave machine with a new database. Create a file named kpropd.acl in -the KDC state directory containing the ``host`` principals for each of -the KDCs:: - - host/kerberos.mit.edu@ATHENA.MIT.EDU - host/kerberos-1.mit.edu@ATHENA.MIT.EDU - -.. note:: If you expect that the master and slave KDCs will be - switched at some point of time, list the host principals - from all participating KDC servers in kpropd.acl files on - all of the KDCs. Otherwise, you only need to list the - master KDC's host principal in the kpropd.acl files of the - slave KDCs. - -Then, add the following line to ``/etc/inetd.conf`` on each KDC -(adjust the path to kpropd):: - - krb5_prop stream tcp nowait root /usr/local/sbin/kpropd kpropd - -You also need to add the following line to ``/etc/services`` on each -KDC, if it is not already present (assuming that the default port is -used):: - - krb5_prop 754/tcp # Kerberos slave propagation - -Restart inetd daemon. - -Alternatively, start :ref:`kpropd(8)` as a stand-alone daemon. This is -required when incremental propagation is enabled. - -Now that the slave KDC is able to accept database propagation, you’ll -need to propagate the database from the master server. - -NOTE: Do not start the slave KDC yet; you still do not have a copy of -the master's database. - - -.. _kprop_to_slaves: - -Propagate the database to each slave KDC -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First, create a dump file of the database on the master KDC, as -follows:: - - shell% kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans - -Then, manually propagate the database to each slave KDC, as in the -following example:: - - shell% kprop -f /usr/local/var/krb5kdc/slave_datatrans kerberos-1.mit.edu - - Database propagation to kerberos-1.mit.edu: SUCCEEDED - -You will need a script to dump and propagate the database. The -following is an example of a Bourne shell script that will do this. - -.. note:: Remember that you need to replace ``/usr/local/var/krb5kdc`` - with the name of the KDC state directory. - -:: - - #!/bin/sh - - kdclist = "kerberos-1.mit.edu kerberos-2.mit.edu" - - kdb5_util dump /usr/local/var/krb5kdc/slave_datatrans - - for kdc in $kdclist - do - kprop -f /usr/local/var/krb5kdc/slave_datatrans $kdc - done - -You will need to set up a cron job to run this script at the intervals -you decided on earlier (see :ref:`db_prop`). - -Now that the slave KDC has a copy of the Kerberos database, you can -start the krb5kdc daemon:: - - shell% krb5kdc - -As with the master KDC, you will probably want to add this command to -the KDCs' ``/etc/rc`` or ``/etc/inittab`` files, so they will start -the krb5kdc daemon automatically at boot time. - - -Propagation failed? -################### - -.. _prop_failed_start: - -.. error:: kprop: No route to host while connecting to server - -Make sure that the hostname of the slave (as given to kprop) is -correct, and that any firewalls beween the master and the slave allow -a connection on port 754. - -.. error:: kprop: Connection refused in call to connect while opening - connection - -If the slave is intended to run kpropd out of inetd, make sure that -inetd is configured to accept krb5_prop connections. inetd may need -to be restarted or sent a SIGHUP to recognize the new configuration. -If the slave is intended to run kpropd in standalone mode, make sure -that it is running. - -.. error:: kprop: Server rejected authentication while authenticating - to server - -Make sure that: - -#. The time is syncronized between the master and slave KDCs. -#. The master stash file was copied from the master to the expected - location on the slave. -#. The slave has a keytab file in the default location containing a - ``host`` principal for the slave's hostname. - -.. _prop_failed_end: - - -Add Kerberos principals to the database ---------------------------------------- - -Once your KDCs are set up and running, you are ready to use -:ref:`kadmin(1)` to load principals for your users, hosts, and other -services into the Kerberos database. This procedure is described -fully in :ref:`add_mod_del_princs`. - -You may occasionally want to use one of your slave KDCs as the master. -This might happen if you are upgrading the master KDC, or if your -master KDC has a disk crash. See the following section for the -instructions. - - -.. _switch_master_slave: - -Switching master and slave KDCs -------------------------------- - -You may occasionally want to use one of your slave KDCs as the master. -This might happen if you are upgrading the master KDC, or if your -master KDC has a disk crash. - -Assuming you have configured all of your KDCs to be able to function -as either the master KDC or a slave KDC (as this document recommends), -all you need to do to make the changeover is: - -If the master KDC is still running, do the following on the *old* -master KDC: - -#. Kill the kadmind process. -#. Disable the cron job that propagates the database. -#. Run your database propagation script manually, to ensure that the - slaves all have the latest copy of the database (see - :ref:`kprop_to_slaves`). - -On the *new* master KDC: - -#. Start the :ref:`kadmind(8)` daemon (see :ref:`start_kdc_daemons`). -#. Set up the cron job to propagate the database (see - :ref:`kprop_to_slaves`). -#. Switch the CNAMEs of the old and new master KDCs. If you can't do - this, you'll need to change the :ref:`krb5.conf(5)` file on every - client machine in your Kerberos realm. - - -Incremental database propagation --------------------------------- - -If you expect your Kerberos database to become large, you may wish to -set up incremental propagation to slave KDCs. See :ref:`incr_db_prop` -for details. diff --git a/doc/rst_source/krb_admins/realm_config.rst b/doc/rst_source/krb_admins/realm_config.rst deleted file mode 100644 index 374703885..000000000 --- a/doc/rst_source/krb_admins/realm_config.rst +++ /dev/null @@ -1,217 +0,0 @@ -Realm configuration decisions -============================= - -Before installing Kerberos V5, it is necessary to consider the -following issues: - -* The name of your Kerberos realm (or the name of each realm, if you - need more than one). -* How you will assign your hostnames to Kerberos realms. -* Which ports your KDC and and kadmind services will use, if they will - not be using the default ports. -* How many slave KDCs you need and where they should be located. -* The hostnames of your master and slave KDCs. -* How frequently you will propagate the database from the master KDC - to the slave KDCs. - - -Realm name ----------- - -Although your Kerberos realm can be any ASCII string, convention is to -make it the same as your domain name, in upper-case letters. - -For example, hosts in the domain ``example.com`` would be in the -Kerberos realm:: - - EXAMPLE.COM - -If you need multiple Kerberos realms, MIT recommends that you use -descriptive names which end with your domain name, such as:: - - BOSTON.EXAMPLE.COM - HOUSTON.EXAMPLE.COM - - -.. _mapping_hostnames: - -Mapping hostnames onto Kerberos realms --------------------------------------- - -Mapping hostnames onto Kerberos realms is done in one of three ways. - -The first mechanism works through a set of rules in the -:ref:`domain_realm` section of :ref:`krb5.conf(5)`. You can specify -mappings for an entire domain or on a per-hostname basis. Typically -you would do this by specifying the mappings for a given domain or -subdomain and listing the exceptions. - -The second mechanism is to use KDC host-based service referrals. With -this method, the KDC's krb5.conf has a full [domain_realm] mapping for -hosts, but the clients do not, or have mappings for only a subset of -the hosts they might contact. When a client needs to contact a server -host for which it has no mapping, it will ask the client realm's KDC -for the service ticket, and will receive a referral to the appropriate -service realm. - -To use referrals, clients must be running MIT krb5 1.6 or later, and -the KDC must be running MIT krb5 1.7 or later. The -**host_based_services** and **no_host_referral** variables in the -:ref:`kdc_realms` section of :ref:`kdc.conf(5)` can be used to -fine-tune referral behavior on the KDC. - -It is also possible for clients to use DNS TXT records, if -**dns_lookup_realm** is enabled in :ref:`krb5.conf(5)`. Such lookups -are disabled by default because DNS is an insecure protocol and security -holes could result if DNS records are spoofed. If enabled, the client -will try to look up a TXT record formed by prepending the prefix -``_kerberos`` to the hostname in question. If that record is not -found, the client will attempt a lookup by prepending ``_kerberos`` to the -host's domain name, then its parent domain, up to the top-level domain. -For the hostname ``boston.engineering.example.com``, the names looked up -would be:: - - _kerberos.boston.engineering.example.com - _kerberos.engineering.example.com - _kerberos.example.com - _kerberos.com - -The value of the first TXT record found is taken as the realm name. - -Even if you do not choose to use this mechanism within your site, -you may wish to set it up anyway, for use when interacting with other sites. - - -Ports for the KDC and admin services ------------------------------------- - -The default ports used by Kerberos are port 88 for the KDC and port -749 for the admin server. You can, however, choose to run on other -ports, as long as they are specified in each host's -:ref:`krb5.conf(5)` files or in DNS SRV records, and the -:ref:`kdc.conf(5)` file on each KDC. For a more thorough treatment of -port numbers used by the Kerberos V5 programs, refer to the -:ref:`conf_firewall`. - - -Slave KDCs ----------- - -Slave KDCs provide an additional source of Kerberos ticket-granting -services in the event of inaccessibility of the master KDC. The -number of slave KDCs you need and the decision of where to place them, -both physically and logically, depends on the specifics of your -network. - -Kerberos authentication requires that each client be able to contact a -KDC. Therefore, you need to anticipate any likely reason a KDC might -be unavailable and have a slave KDC to take up the slack. - -Some considerations include: - -* Have at least one slave KDC as a backup, for when the master KDC is - down, is being upgraded, or is otherwise unavailable. -* If your network is split such that a network outage is likely to - cause a network partition (some segment or segments of the network - to become cut off or isolated from other segments), have a slave KDC - accessible to each segment. -* If possible, have at least one slave KDC in a different building - from the master, in case of power outages, fires, or other localized - disasters. - - -.. _kdc_hostnames: - -Hostnames for KDCs ------------------- - -MIT recommends that your KDCs have a predefined set of CNAME records -(DNS hostname aliases), such as ``kerberos`` for the master KDC and -``kerberos-1``, ``kerberos-2``, ... for the slave KDCs. This way, if -you need to swap a machine, you only need to change a DNS entry, -rather than having to change hostnames. - -As of MIT krb5 1.4, clients can locate a realm's KDCs through DNS -using SRV records (:rfc:`2782`), assuming the Kerberos realm name is -also a DNS domain name. These records indicate the hostname and port -number to contact for that service, optionally with weighting and -prioritization. The domain name used in the SRV record name is the -realm name. Several different Kerberos-related service names are -used: - -_kerberos._udp - This is for contacting any KDC by UDP. This entry will be used - the most often. Normally you should list port 88 on each of your - KDCs. -_kerberos._tcp - This is for contacting any KDC by TCP. The MIT KDC by default - will not listen on any TCP ports, so unless you've changed the - configuration or you're running another KDC implementation, you - should leave this unspecified. If you do enable TCP support, - normally you should use port 88. -_kerberos-master._udp - This entry should refer to those KDCs, if any, that will - immediately see password changes to the Kerberos database. If a - user is logging in and the password appears to be incorrect, the - client will retry with the master KDC before failing with an - "incorrect password" error given. - - If you have only one KDC, or for whatever reason there is no - accessible KDC that would get database changes faster than the - others, you do not need to define this entry. -_kerberos-adm._tcp - This should list port 749 on your master KDC. Support for it is - not complete at this time, but it will eventually be used by the - :ref:`kadmin(1)` program and related utilities. For now, you will - also need the **admin_server** variable in :ref:`krb5.conf(5)`. -_kpasswd._udp - This should list port 464 on your master KDC. It is used when a - user changes her password. If this entry is not defined but a - _kerberos-adm._tcp entry is defined, the client will use the - _kerberos-adm._tcp entry with the port number changed to 749. - -The DNS SRV specification requires that the hostnames listed be the -canonical names, not aliases. So, for example, you might include the -following records in your (BIND-style) zone file:: - - $ORIGIN foobar.com. - _kerberos TXT "FOOBAR.COM" - kerberos CNAME daisy - kerberos-1 CNAME use-the-force-luke - kerberos-2 CNAME bunny-rabbit - _kerberos._udp SRV 0 0 88 daisy - SRV 0 0 88 use-the-force-luke - SRV 0 0 88 bunny-rabbit - _kerberos-master._udp SRV 0 0 88 daisy - _kerberos-adm._tcp SRV 0 0 749 daisy - _kpasswd._udp SRV 0 0 464 daisy - -Clients can also be configured with the explicit location of services -using the **kdc**, **master_kdc**, **admin_server**, and -**kpasswd_server** variables in the :ref:`realms` section of -:ref:`krb5.conf(5)`. Even if some clients will be configured with -explicit server locations, providing SRV records will still benefit -unconfigured clients, and be useful for other sites. - - -.. _db_prop: - -Database propagation --------------------- - -The Kerberos database resides on the master KDC, and must be -propagated regularly (usually by a cron job) to the slave KDCs. In -deciding how frequently the propagation should happen, you will need -to balance the amount of time the propagation takes against the -maximum reasonable amount of time a user should have to wait for a -password change to take effect. - -If the propagation time is longer than this maximum reasonable time -(e.g., you have a particularly large database, you have a lot of -slaves, or you experience frequent network delays), you may wish to -cut down on your propagation delay by performing the propagation in -parallel. To do this, have the master KDC propagate the database to -one set of slaves, and then have each of these slaves propagate the -database to additional slaves. - -See also :ref:`incr_db_prop` diff --git a/doc/rst_source/krb_admins/troubleshoot.rst b/doc/rst_source/krb_admins/troubleshoot.rst deleted file mode 100644 index 7dc25795d..000000000 --- a/doc/rst_source/krb_admins/troubleshoot.rst +++ /dev/null @@ -1,53 +0,0 @@ -Troubleshooting -=============== - -Trace logging -------------- - -Most programs using MIT krb5 1.9 or later can be made to provide -information about internal krb5 library operations using trace -logging. To enable this, set the **KRB5_TRACE** environment variable -to a filename before running the program. On many operating systems, -the filename ``/dev/stdout`` can be used to send trace logging output -to standard output. - -Some programs do not honor **KRB5_TRACE**, either because they use -secure library contexts (this generally applies to setuid programs and -parts of the login system) or because they take direct control of the -trace logging system using the API. - -Here is a short example showing trace logging output for an invocation -of the :ref:`kvno(1)` command:: - - shell% env KRB5_TRACE=/dev/stdout kvno krbtgt/KRBTEST.COM - [9138] 1332348778.823276: Getting credentials user@KRBTEST.COM -> - krbtgt/KRBTEST.COM@KRBTEST.COM using ccache - FILE:/me/krb5/build/testdir/ccache - [9138] 1332348778.823381: Retrieving user@KRBTEST.COM -> - krbtgt/KRBTEST.COM@KRBTEST.COM from - FILE:/me/krb5/build/testdir/ccache with result: 0/Unknown code 0 - krbtgt/KRBTEST.COM@KRBTEST.COM: kvno = 1 - -List ----- - -.. error:: KDC has no support for encryption type while getting - initial credentials - -.. error:: credential verification failed: KDC has no support for - encryption type - -This most commonly happens when trying to use a principal with only -DES keys, in a release (MIT krb5 1.7 or later) which disables DES by -default. DES encryption is considered weak due to its inadequate key -size. If you cannot migrate away from its use, you can re-enable DES -by adding ``allow_weak_crypto = true`` to the :ref:`libdefaults` -section of :ref:`krb5.conf(5)`. - -Seen in: clients - ----- - -.. include:: ./install_kdc.rst - :start-after: _prop_failed_start: - :end-before: _prop_failed_end: diff --git a/doc/rst_source/krb_admins/various_envs.rst b/doc/rst_source/krb_admins/various_envs.rst deleted file mode 100644 index c32ac05f6..000000000 --- a/doc/rst_source/krb_admins/various_envs.rst +++ /dev/null @@ -1,33 +0,0 @@ -Various links -============= - -Whitepapers ------------ - -#. http://kerberos.org/software/whitepapers.html - - -Tutorials ---------- - -#. Fulvio Ricciardi _ - - -Troubleshooting ---------------- - -#. http://www.ncsa.illinois.edu/UserInfo/Resources/Software/kerberos/troubleshooting.html - -#. http://nfsv4.bullopensource.org/doc/kerberosnfs/krbnfs_howto_v3.pdf - -#. http://sysdoc.doors.ch/HP/T1417-90005.pdf - -#. http://www.shrubbery.net/solaris9ab/SUNWaadm/SYSADV6/p27.html - -#. http://download.oracle.com/docs/cd/E19253-01/816-4557/trouble-1/index.html - -#. http://technet.microsoft.com/en-us/library/bb463167.aspx#EBAA - -#. https://bugs.launchpad.net/ubuntu/+source/libpam-heimdal/+bug/86528 - -#. http://h71000.www7.hp.com/doc/83final/ba548_90007/ch06s05.html diff --git a/doc/rst_source/krb_appldev/gssapi.rst b/doc/rst_source/krb_appldev/gssapi.rst deleted file mode 100644 index 29c06b565..000000000 --- a/doc/rst_source/krb_appldev/gssapi.rst +++ /dev/null @@ -1,220 +0,0 @@ -Developing with GSSAPI -====================== - -The GSSAPI (Generic Security Services API) allows applications to -communicate securely using Kerberos 5 or other security mechanisms. -We recommend using the GSSAPI (or a higher-level framework which -encompasses GSSAPI, such as SASL) for secure network communication -over using the libkrb5 API directly. - -GSSAPIv2 is specified in :rfc:`2743` and :rfc:`2744`. This -documentation will describe how various ways of using GSSAPI will -behave with the krb5 mechanism as implemented in MIT krb5, as well as -krb5-specific extensions to the GSSAPI. - - -Name types ----------- - -A GSSAPI application can name a local or remote entity by calling -gss_import_name_, specifying a name type and a value. The following -name types are supported by the krb5 mechanism: - -* **GSS_C_NT_HOSTBASED_SERVICE**: The value should be a string of the - form ``service`` or ``service@hostname``. This is the most common - way to name target services when initiating a security context, and - is the most likely name type to work across multiple mechanisms. - -* **GSS_KRB5_NT_PRINCIPAL_NAME**: The value should be a principal name - string. This name type only works with the krb5 mechanism, and is - defined in the ```` header. - -* **GSS_C_NT_USER_NAME** or **GSS_C_NULL_OID**: The value is treated - as an unparsed principal name string, as above. These name types - may work with mechanisms other than krb5, but will have different - interpretations in those mechanisms. **GSS_C_NT_USER_NAME** is - intended to be used with a local username, which will parse into a - single-component principal in the default realm. - -* **GSS_C_NT_ANONYMOUS**: The value is ignored. The anonymous - principal is used, allowing a client to authenticate to a server - without asserting a particular identity (which may or may not be - allowed by a particular server or Kerberos realm). - -* **GSS_C_NT_MACHINE_UID_NAME**: The value is uid_t object. On - Unix-like systems, the username of the uid is looked up in the - system user database and the resulting username is parsed as a - principal name. - -* **GSS_C_NT_STRING_UID_NAME**: As above, but the value is a decimal - string representation of the uid. - -* **GSS_C_NT_EXPORT_NAME**: The value must be the result of a - gss_export_name_ call. - - -Initiator credentials ---------------------- - -A GSSAPI client application uses gss_init_sec_context_ to establish a -security context. The *initiator_cred_handle* parameter determines -what tickets are used to establish the connection. An application can -either pass **GSS_C_NO_CREDENTIAL** to use the default client -credential, or it can use gss_acquire_cred_ beforehand to acquire an -initiator credential. The call to gss_acquire_cred_ may include a -*desired_name* parameter, or it may pass **GSS_C_NO_NAME** if it does -not have a specific name preference. - -If the desired name for a krb5 initiator credential is a host-based -name, it is converted to a principal name of the form -``service/hostname`` in the local realm, where *hostname* is the local -hostname if not specified. The hostname will be canonicalized using -forward name resolution, and possibly also using reverse name -resolution depending on the value of the **rdns** variable in -:ref:`libdefaults`. - -If a desired name is specified in the call to gss_acquire_cred_, the -krb5 mechanism will attempt to find existing tickets for that client -principal name in the default credential cache or collection. If the -default cache type does not support a collection, and the default -cache contains credentials for a different principal than the desired -name, a **GSS_S_CRED_UNAVAIL** error will be returned with a minor -code indicating a mismatch. - -If no existing tickets are available for the desired name, but the -name has an entry in the default client :ref:`keytab_definition`, the -krb5 mechanism will acquire initial tickets for the name using the -default client keytab. - -If no desired name is specified, credential acquisition will be -deferred until the credential is used in a call to -gss_init_sec_context_ or gss_inquire_cred_. If the call is to -gss_init_sec_context_, the target name will be used to choose a client -principal name using the credential cache selection facility. (This -facility might, for instance, try to choose existing tickets for a -client principal in the same realm as the target service). If there -are no existing tickets for the chosen principal, but it is present in -the default client keytab, the krb5 mechanism will acquire initial -tickets using the keytab. - -If the target name cannot be used to select a client principal -(because the credentials are used in a call to gss_inquire_cred_), or -if the credential cache selection facility cannot choose a principal -for it, the default credential cache will be selected if it exists and -contains tickets. - -If the default credential cache does not exist, but the default client -keytab does, the krb5 mechanism will try to acquire initial tickets -for the first principal in the default client keytab. - -If the krb5 mechanism acquires initial tickets using the default -client keytab, the resulting tickets will be stored in the default -cache or collection, and will be refreshed by future calls to -gss_acquire_cred_ as they approach their expire time. - - -Acceptor names --------------- - -A GSSAPI server application uses gss_accept_sec_context_ to establish -a security context based on tokens provided by the client. The -*acceptor_cred_handle* parameter determines what -:ref:`keytab_definition` entries may be authenticated to by the -client, if the krb5 mechanism is used. - -The simplest choice is to pass **GSS_C_NO_CREDENTIAL** as the acceptor -credential. In this case, clients may authenticate to any service -principal in the default keytab (typically |keytab|, or the value of -the **KRB5_KTNAME** environment variable). This is the recommended -approach if the server application has no specific requirements to the -contrary. - -A server may acquire an acceptor credential with gss_acquire_cred_ and -a *cred_usage* of **GSS_C_ACCEPT** or **GSS_C_BOTH**. If the -*desired_name* parameter is **GSS_C_NO_NAME**, then clients will be -allowed to authenticate to any service principal in the default -keytab, just as if no acceptor credential was supplied. - -If a server wishes to specify a *desired_name* to gss_acquire_cred_, -the most common choice is a host-based name. If the host-based -*desired_name* contains just a *service*, then clients will be allowed -to authenticate to any host-based service principal (that is, a -principal of the form ``service/hostname@REALM``) for the named -service, regardless of hostname or realm, as long as it is present in -the default keytab. If the input name contains both a *service* and a -*hostname*, clients will be allowed to authenticate to any host-based -principal for the named service and hostname, regardless of realm. - -.. note:: If a *hostname* is specified, it will be canonicalized - using forward name resolution, and possibly also using - reverse name resolution depending on the value of the - **rdns** variable in :ref:`libdefaults`. - -.. note:: If the **ignore_acceptor_hostname** variable in - :ref:`libdefaults` is enabled, then *hostname* will be - ignored even if one is specified in the input name. - -.. note:: In MIT krb5 versions prior to 1.10, and in Heimdal's - implementation of the krb5 mechanism, an input name with - just a *service* is treated like an input name of - ``service@localhostname``, where *localhostname* is the - string returned by gethostname(). - -If the *desired_name* is a krb5 principal name or a local system name -type which is mapped to a krb5 principal name, clients will only be -allowed to authenticate to that principal in the default keytab. - - -Importing and exporting credentials ------------------------------------ - -The following GSSAPI extensions can be used to import and export -credentials (declared in ````):: - - OM_uint32 gss_export_cred(OM_uint32 *minor_status, - gss_cred_id_t cred_handle, - gss_buffer_t token); - - OM_uint32 gss_import_cred(OM_uint32 *minor_status, - gss_buffer_t token, - gss_cred_id_t *cred_handle); - -The first function serializes a GSSAPI credential handle into a -buffer; the second unseralizes a buffer into a GSSAPI credential -handle. Serializing a credential does not destroy it. If any of the -mechanisms used in *cred_handle* do not support serialization, -gss_export_cred will return **GSS_S_UNAVAILABLE**. As with other -GSSAPI serialization functions, these extensions are only intended to -work with a matching implementation on the other side; they do not -serialize credentials in a standardized format. - -A serialized credential may contain secret information such as ticket -session keys. The serialization format does not protect this -information from eavesdropping or tampering. The calling application -must take care to protect the serialized credential when communicating -it over an insecure channel or to an untrusted party. - -A krb5 GSSAPI credential may contain references to a credential cache, -a client keytab, an acceptor keytab, and a replay cache. These -resources are normally serialized as references to their external -locations (such as the filename of the credential cache). Because of -this, a serialized krb5 credential can only be imported by a process -with similar privileges to the exporter. A serialized credential -should not be trusted if it originates from a source with lower -privileges than the importer, as it may contain references to external -credential cache, keytab, or replay cache resources not accessible to -the originator. - -An exception to the above rule applies when a krb5 GSSAPI credential -refers to a memory credential cache, as is normally the case for -delegated credentials received by gss_accept_sec_context_. In this -case, the contents of the credential cache are serialized, so that the -resulting token may be imported even if the original memory credential -cache no longer exists. - -.. _gss_accept_sec_context: http://tools.ietf.org/html/rfc2744.html#section-5.1 -.. _gss_acquire_cred: http://tools.ietf.org/html/rfc2744.html#section-5.2 -.. _gss_export_name: http://tools.ietf.org/html/rfc2744.html#section-5.13 -.. _gss_import_name: http://tools.ietf.org/html/rfc2744.html#section-5.16 -.. _gss_init_sec_context: http://tools.ietf.org/html/rfc2744.html#section-5.19 -.. _gss_inquire_cred: http://tools.ietf.org/html/rfc2744.html#section-5.21 diff --git a/doc/rst_source/krb_appldev/h5l_mit_apidiff.rst b/doc/rst_source/krb_appldev/h5l_mit_apidiff.rst deleted file mode 100644 index 33da60211..000000000 --- a/doc/rst_source/krb_appldev/h5l_mit_apidiff.rst +++ /dev/null @@ -1,28 +0,0 @@ -Differences between Heimdal and MIT Kerberos API -================================================ - - - ======================================== ================================================= - :c:func:`krb5_auth_con_getaddrs()` H5l: If either of the pointers to local_addr - and remote_addr is not NULL, it is freed - first and then reallocated before being - populated with the content of corresponding - address from authentication context. - :c:func:`krb5_auth_con_setaddrs()` H5l: If either address is NULL, the previous - address remains in place - :c:func:`krb5_auth_con_setports()` H5l: Not implemented as of version 1.3.3 - :c:func:`krb5_auth_con_setrecvsubkey()` H5l: If either port is NULL, the previous - port remains in place - :c:func:`krb5_auth_con_setsendsubkey()` H5l: Not implemented as of version 1.3.3 - :c:func:`krb5_cc_set_config()` MIT: Before version 1.10 it was assumed that - the last argument *data* is ALWAYS non-zero. - :c:func:`krb5_cccol_last_change_time()` H5l takes 3 arguments: krb5_context context, - const char \*type, krb5_timestamp \*change_time - MIT takes two arguments: krb5_context context, - krb5_timestamp \*change_time - :c:func:`krb5_set_default_realm()` H5l: Caches the computed default realm context - field. If the second argument is NULL, - it tries to retrieve it from libdefaults or DNS. - MIT: Computes the default realm each time - if it wasn't explicitly set in the context - ======================================== ================================================= diff --git a/doc/rst_source/krb_appldev/index.rst b/doc/rst_source/krb_appldev/index.rst deleted file mode 100644 index 3d62045ca..000000000 --- a/doc/rst_source/krb_appldev/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -For application developers -========================== - -.. toctree:: - :maxdepth: 1 - - gssapi.rst - h5l_mit_apidiff.rst - init_creds.rst - princ_handle.rst - -.. toctree:: - :maxdepth: 1 - - refs/index.rst diff --git a/doc/rst_source/krb_appldev/init_creds.rst b/doc/rst_source/krb_appldev/init_creds.rst deleted file mode 100644 index b9528e737..000000000 --- a/doc/rst_source/krb_appldev/init_creds.rst +++ /dev/null @@ -1,59 +0,0 @@ -Initial credentials -=================== - -Software that performs tasks such as logging users into a computer -when they type their Kerberos password needs to get initial -credentials (usually ticket granting tickets) from Kerberos. Such -software shares some behavior with the :ref:`kinit(1)` program. - -Whenever a program grants access to a resource (such as a local login -session on a desktop computer) based on a user successfully getting -initial Kerberos credentials, it must verify those credentials against -a secure shared secret (e.g., a host keytab) to ensure that the user -credentials actually originate from a legitimate KDC. Failure to -perform this verification is a critical vulnerability, because a -malicious user can execute the "Zanarotti attack": the user constructs -a fake response that appears to come from the legitimate KDC, but -whose contents come from an attacker-controlled KDC. - -Some applications read a Kerberos password over the network (ideally -over a secure channel), which they then verify against the KDC. While -this technique may be the only practical way to integrate Kerberos -into some existing legacy systems, its use is contrary to the original -design goals of Kerberos. - -The function :c:func:`krb5_get_init_creds_password` will get initial -credentials for a client using a password. An application that needs -to verify the credentials can call :c:func:`krb5_verify_init_creds`. - -Options for get_init_creds --------------------------- - -The function :c:func:`krb5_get_init_creds_password` takes an options -parameter (which can be a null pointer). Use the function -:c:func:`krb5_get_init_creds_opt_alloc` to allocate an options -structure, and :c:func:`krb5_get_init_creds_opt_free` to free it. - -Verifying initial credentials ------------------------------ - -Use the function :c:func:`krb5_verify_init_creds` to verify initial -credentials. It takes an options structure (which can be a null -pointer). Use :c:func:`krb5_verify_init_creds_opt_init` to initialize -the caller-allocated options structure, and -:c:func:`krb5_verify_init_creds_opt_set_ap_req_nofail` to set the -"nofail" option. - -The confusingly named "nofail" option, when set, means that the -verification must actually succeed in order for -:c:func:`krb5_verify_init_creds` to indicate success. The default -state of this option (cleared) means that if there is no key material -available to verify the user credentials, the verification will -succeed anyway. (The default can be changed by a configuration file -setting.) - -This accommodates a use case where a large number of unkeyed shared -desktop workstations need to allow users to log in using Kerberos. -The security risks from this practice are mitigated by the absence of -valuable state on the shared workstations---any valuable resources -that the users would access reside on networked servers. diff --git a/doc/rst_source/krb_appldev/princ_handle.rst b/doc/rst_source/krb_appldev/princ_handle.rst deleted file mode 100644 index 455f00a4b..000000000 --- a/doc/rst_source/krb_appldev/princ_handle.rst +++ /dev/null @@ -1,79 +0,0 @@ -Principal manipulation and parsing -================================== - -Kerberos principal structure - -.. - -:c:type:`krb5_principal_data` - -:c:type:`krb5_principal` - -.. - -Create and free principal - -.. - -:c:func:`krb5_build_principal()` - -:c:func:`krb5_build_principal_alloc_va()` - -:c:func:`krb5_build_principal_ext()` - -:c:func:`krb5_copy_principal()` - -:c:func:`krb5_free_principal()` - -:c:func:`krb5_cc_get_principal()` - -.. - -Comparing - -.. - -:c:func:`krb5_principal_compare()` - -:c:func:`krb5_principal_compare_flags()` - -:c:func:`krb5_principal_compare_any_realm()` - -:c:func:`krb5_sname_match()` - -:c:func:`krb5_sname_to_principal()` - -.. - - -Parsing: - -.. - -:c:func:`krb5_parse_name()` - -:c:func:`krb5_parse_name_flags()` - -:c:func:`krb5_unparse_name()` - -:c:func:`krb5_unparse_name_flags()` - -.. - -Utilities: - -.. - -:c:func:`krb5_is_config_principal()` - -:c:func:`krb5_kuserok()` - -:c:func:`krb5_set_password()` - -:c:func:`krb5_set_password_using_ccache()` - -:c:func:`krb5_set_principal_realm()` - -:c:func:`krb5_realm_compare()` - -.. diff --git a/doc/rst_source/krb_appldev/refs/api/index.rst b/doc/rst_source/krb_appldev/refs/api/index.rst deleted file mode 100644 index 26b7f8633..000000000 --- a/doc/rst_source/krb_appldev/refs/api/index.rst +++ /dev/null @@ -1,397 +0,0 @@ -krb5 API -======== - - -Frequently used public interfaces ----------------------------------- - -.. toctree:: - :maxdepth: 1 - - krb5_build_principal.rst - krb5_build_principal_alloc_va.rst - krb5_build_principal_ext.rst - krb5_cc_close.rst - krb5_cc_default.rst - krb5_cc_default_name.rst - krb5_cc_destroy.rst - krb5_cc_dup.rst - krb5_cc_get_name.rst - krb5_cc_get_principal.rst - krb5_cc_get_type.rst - krb5_cc_initialize.rst - krb5_cc_new_unique.rst - krb5_cc_resolve.rst - krb5_change_password.rst - krb5_chpw_message.rst - krb5_free_context.rst - krb5_free_error_message.rst - krb5_free_principal.rst - krb5_fwd_tgt_creds.rst - krb5_get_default_realm.rst - krb5_get_error_message.rst - krb5_get_host_realm.rst - krb5_get_credentials.rst - krb5_get_fallback_host_realm.rst - krb5_get_init_creds_keytab.rst - krb5_get_init_creds_opt_alloc.rst - krb5_get_init_creds_opt_free.rst - krb5_get_init_creds_opt_get_fast_flags.rst - krb5_get_init_creds_opt_set_address_list.rst - krb5_get_init_creds_opt_set_anonymous.rst - krb5_get_init_creds_opt_set_canonicalize.rst - krb5_get_init_creds_opt_set_change_password_prompt.rst - krb5_get_init_creds_opt_set_etype_list.rst - krb5_get_init_creds_opt_set_expire_callback.rst - krb5_get_init_creds_opt_set_fast_ccache.rst - krb5_get_init_creds_opt_set_fast_ccache_name.rst - krb5_get_init_creds_opt_set_fast_flags.rst - krb5_get_init_creds_opt_set_forwardable.rst - krb5_get_init_creds_opt_set_out_ccache.rst - krb5_get_init_creds_opt_set_pa.rst - krb5_get_init_creds_opt_set_preauth_list.rst - krb5_get_init_creds_opt_set_proxiable.rst - krb5_get_init_creds_opt_set_renew_life.rst - krb5_get_init_creds_opt_set_responder.rst - krb5_get_init_creds_opt_set_salt.rst - krb5_get_init_creds_opt_set_tkt_life.rst - krb5_get_init_creds_password.rst - krb5_get_profile.rst - krb5_get_prompt_types.rst - krb5_get_renewed_creds.rst - krb5_get_validated_creds.rst - krb5_init_context.rst - krb5_init_secure_context.rst - krb5_is_config_principal.rst - krb5_is_thread_safe.rst - krb5_kt_close.rst - krb5_kt_client_default.rst - krb5_kt_default.rst - krb5_kt_default_name.rst - krb5_kt_get_name.rst - krb5_kt_get_type.rst - krb5_kt_resolve.rst - krb5_kuserok.rst - krb5_parse_name.rst - krb5_parse_name_flags.rst - krb5_principal_compare.rst - krb5_principal_compare_any_realm.rst - krb5_principal_compare_flags.rst - krb5_prompter_posix.rst - krb5_realm_compare.rst - krb5_responder_get_challenge.rst - krb5_responder_list_questions.rst - krb5_responder_set_answer.rst - krb5_responder_otp_get_challenge.rst - krb5_responder_otp_set_answer.rst - krb5_responder_otp_challenge_free.rst - krb5_set_default_realm.rst - krb5_set_password.rst - krb5_set_password_using_ccache.rst - krb5_set_principal_realm.rst - krb5_set_trace_callback.rst - krb5_set_trace_filename.rst - krb5_sname_match.rst - krb5_sname_to_principal.rst - krb5_unparse_name.rst - krb5_unparse_name_ext.rst - krb5_unparse_name_flags.rst - krb5_unparse_name_flags_ext.rst - krb5_us_timeofday.rst - krb5_verify_authdata_kdc_issued.rst - -Rarely used public interfaces --------------------------------- - -.. toctree:: - :maxdepth: 1 - - krb5_425_conv_principal.rst - krb5_524_conv_principal.rst - krb5_address_compare.rst - krb5_address_order.rst - krb5_address_search.rst - krb5_allow_weak_crypto.rst - krb5_aname_to_localname.rst - krb5_anonymous_principal.rst - krb5_anonymous_realm.rst - krb5_appdefault_boolean.rst - krb5_appdefault_string.rst - krb5_auth_con_free.rst - krb5_auth_con_genaddrs.rst - krb5_auth_con_get_checksum_func.rst - krb5_auth_con_getaddrs.rst - krb5_auth_con_getauthenticator.rst - krb5_auth_con_getflags.rst - krb5_auth_con_getkey.rst - krb5_auth_con_getkey_k.rst - krb5_auth_con_getlocalseqnumber.rst - krb5_auth_con_getrcache.rst - krb5_auth_con_getrecvsubkey.rst - krb5_auth_con_getrecvsubkey_k.rst - krb5_auth_con_getremoteseqnumber.rst - krb5_auth_con_getsendsubkey.rst - krb5_auth_con_getsendsubkey_k.rst - krb5_auth_con_init.rst - krb5_auth_con_set_checksum_func.rst - krb5_auth_con_set_req_cksumtype.rst - krb5_auth_con_setaddrs.rst - krb5_auth_con_setflags.rst - krb5_auth_con_setports.rst - krb5_auth_con_setrcache.rst - krb5_auth_con_setrecvsubkey.rst - krb5_auth_con_setrecvsubkey_k.rst - krb5_auth_con_setsendsubkey.rst - krb5_auth_con_setsendsubkey_k.rst - krb5_auth_con_setuseruserkey.rst - krb5_cc_cache_match.rst - krb5_cc_copy_creds.rst - krb5_cc_end_seq_get.rst - krb5_cc_get_config.rst - krb5_cc_get_flags.rst - krb5_cc_get_full_name.rst - krb5_cc_last_change_time.rst - krb5_cc_lock.rst - krb5_cc_move.rst - krb5_cc_next_cred.rst - krb5_cc_remove_cred.rst - krb5_cc_retrieve_cred.rst - krb5_cc_select.rst - krb5_cc_set_config.rst - krb5_cc_set_default_name.rst - krb5_cc_set_flags.rst - krb5_cc_start_seq_get.rst - krb5_cc_store_cred.rst - krb5_cc_support_switch.rst - krb5_cc_switch.rst - krb5_cc_unlock.rst - krb5_cccol_cursor_free.rst - krb5_cccol_cursor_new.rst - krb5_cccol_cursor_next.rst - krb5_cccol_have_content.rst - krb5_cccol_last_change_time.rst - krb5_cccol_lock.rst - krb5_cccol_unlock.rst - krb5_clear_error_message.rst - krb5_check_clockskew.rst - krb5_copy_addresses.rst - krb5_copy_authdata.rst - krb5_copy_authenticator.rst - krb5_copy_checksum.rst - krb5_copy_context.rst - krb5_copy_creds.rst - krb5_copy_data.rst - krb5_copy_error_message.rst - krb5_copy_keyblock.rst - krb5_copy_keyblock_contents.rst - krb5_copy_principal.rst - krb5_copy_ticket.rst - krb5_find_authdata.rst - krb5_free_addresses.rst - krb5_free_ap_rep_enc_part.rst - krb5_free_authdata.rst - krb5_free_authenticator.rst - krb5_free_cred_contents.rst - krb5_free_creds.rst - krb5_free_data.rst - krb5_free_data_contents.rst - krb5_free_default_realm.rst - krb5_free_error.rst - krb5_free_host_realm.rst - krb5_free_keyblock.rst - krb5_free_keyblock_contents.rst - krb5_free_keytab_entry_contents.rst - krb5_free_octet_data.rst - krb5_free_string.rst - krb5_free_ticket.rst - krb5_free_unparsed_name.rst - krb5_get_permitted_enctypes.rst - krb5_get_server_rcache.rst - krb5_get_time_offsets.rst - krb5_init_context_profile.rst - krb5_init_creds_free.rst - krb5_init_creds_get.rst - krb5_init_creds_get_creds.rst - krb5_init_creds_get_error.rst - krb5_init_creds_get_times.rst - krb5_init_creds_init.rst - krb5_init_creds_set_keytab.rst - krb5_init_creds_set_password.rst - krb5_init_creds_set_service.rst - krb5_init_creds_step.rst - krb5_init_keyblock.rst - krb5_is_referral_realm.rst - krb5_kt_add_entry.rst - krb5_kt_end_seq_get.rst - krb5_kt_get_entry.rst - krb5_kt_have_content.rst - krb5_kt_next_entry.rst - krb5_kt_read_service_key.rst - krb5_kt_remove_entry.rst - krb5_kt_start_seq_get.rst - krb5_make_authdata_kdc_issued.rst - krb5_merge_authdata.rst - krb5_mk_1cred.rst - krb5_mk_error.rst - krb5_mk_ncred.rst - krb5_mk_priv.rst - krb5_mk_rep.rst - krb5_mk_rep_dce.rst - krb5_mk_req.rst - krb5_mk_req_extended.rst - krb5_mk_safe.rst - krb5_os_localaddr.rst - krb5_pac_add_buffer.rst - krb5_pac_free.rst - krb5_pac_get_buffer.rst - krb5_pac_get_types.rst - krb5_pac_init.rst - krb5_pac_parse.rst - krb5_pac_sign.rst - krb5_pac_verify.rst - krb5_principal2salt.rst - krb5_rd_cred.rst - krb5_rd_error.rst - krb5_rd_priv.rst - krb5_rd_rep.rst - krb5_rd_rep_dce.rst - krb5_rd_req.rst - krb5_rd_safe.rst - krb5_read_password.rst - krb5_salttype_to_string.rst - krb5_server_decrypt_ticket_keytab.rst - krb5_set_default_tgs_enctypes.rst - krb5_set_error_message.rst - krb5_set_real_time.rst - krb5_string_to_cksumtype.rst - krb5_string_to_deltat.rst - krb5_string_to_enctype.rst - krb5_string_to_salttype.rst - krb5_string_to_timestamp.rst - krb5_timeofday.rst - krb5_timestamp_to_sfstring.rst - krb5_timestamp_to_string.rst - krb5_tkt_creds_free.rst - krb5_tkt_creds_get.rst - krb5_tkt_creds_get_creds.rst - krb5_tkt_creds_get_times.rst - krb5_tkt_creds_init.rst - krb5_tkt_creds_step.rst - krb5_verify_init_creds.rst - krb5_verify_init_creds_opt_init.rst - krb5_verify_init_creds_opt_set_ap_req_nofail.rst - krb5_vset_error_message.rst - - -Public interfaces that should not be called directly -------------------------------------------------------- - -.. toctree:: - :maxdepth: 1 - - krb5_c_block_size.rst - krb5_c_checksum_length.rst - krb5_c_crypto_length.rst - krb5_c_crypto_length_iov.rst - krb5_c_decrypt.rst - krb5_c_decrypt_iov.rst - krb5_c_encrypt.rst - krb5_c_encrypt_iov.rst - krb5_c_encrypt_length.rst - krb5_c_enctype_compare.rst - krb5_c_free_state.rst - krb5_c_fx_cf2_simple.rst - krb5_c_init_state.rst - krb5_c_is_coll_proof_cksum.rst - krb5_c_is_keyed_cksum.rst - krb5_c_keyed_checksum_types.rst - krb5_c_keylengths.rst - krb5_c_make_checksum.rst - krb5_c_make_checksum_iov.rst - krb5_c_make_random_key.rst - krb5_c_padding_length.rst - krb5_c_prf.rst - krb5_c_prf_length.rst - krb5_c_random_add_entropy.rst - krb5_c_random_make_octets.rst - krb5_c_random_os_entropy.rst - krb5_c_random_to_key.rst - krb5_c_string_to_key.rst - krb5_c_string_to_key_with_params.rst - krb5_c_valid_cksumtype.rst - krb5_c_valid_enctype.rst - krb5_c_verify_checksum.rst - krb5_c_verify_checksum_iov.rst - krb5_cksumtype_to_string.rst - krb5_decode_authdata_container.rst - krb5_decode_ticket.rst - krb5_deltat_to_string.rst - krb5_encode_authdata_container.rst - krb5_enctype_to_name.rst - krb5_enctype_to_string.rst - krb5_free_checksum.rst - krb5_free_checksum_contents.rst - krb5_free_cksumtypes.rst - krb5_free_tgt_creds.rst - krb5_k_create_key.rst - krb5_k_decrypt.rst - krb5_k_decrypt_iov.rst - krb5_k_encrypt.rst - krb5_k_encrypt_iov.rst - krb5_k_free_key.rst - krb5_k_key_enctype.rst - krb5_k_key_keyblock.rst - krb5_k_make_checksum.rst - krb5_k_make_checksum_iov.rst - krb5_k_prf.rst - krb5_k_reference_key.rst - krb5_k_verify_checksum.rst - krb5_k_verify_checksum_iov.rst - - -Legacy convenience interfaces ------------------------------- - -.. toctree:: - :maxdepth: 1 - - krb5_recvauth.rst - krb5_recvauth_version.rst - krb5_sendauth.rst - - -Deprecated public interfaces ------------------------------- - -.. toctree:: - :maxdepth: 1 - - krb5_524_convert_creds.rst - krb5_auth_con_getlocalsubkey.rst - krb5_auth_con_getremotesubkey.rst - krb5_auth_con_initivector.rst - krb5_build_principal_va.rst - krb5_c_random_seed.rst - krb5_calculate_checksum.rst - krb5_checksum_size.rst - krb5_encrypt.rst - krb5_decrypt.rst - krb5_eblock_enctype.rst - krb5_encrypt_size.rst - krb5_finish_key.rst - krb5_finish_random_key.rst - krb5_cc_gen_new.rst - krb5_get_credentials_renew.rst - krb5_get_credentials_validate.rst - krb5_get_in_tkt_with_password.rst - krb5_get_in_tkt_with_skey.rst - krb5_get_in_tkt_with_keytab.rst - krb5_get_init_creds_opt_init.rst - krb5_init_random_key.rst - krb5_kt_free_entry.rst - krb5_random_key.rst - krb5_process_key.rst - krb5_string_to_key.rst - krb5_use_enctype.rst - krb5_verify_checksum.rst - diff --git a/doc/rst_source/krb_appldev/refs/index.rst b/doc/rst_source/krb_appldev/refs/index.rst deleted file mode 100644 index e0f6d57f3..000000000 --- a/doc/rst_source/krb_appldev/refs/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -Complete reference - API and datatypes -========================================================== - -.. toctree:: - :maxdepth: 1 - - api/index.rst - types/index.rst - macros/index.rst - diff --git a/doc/rst_source/krb_appldev/refs/macros/index.rst b/doc/rst_source/krb_appldev/refs/macros/index.rst deleted file mode 100644 index b26581059..000000000 --- a/doc/rst_source/krb_appldev/refs/macros/index.rst +++ /dev/null @@ -1,355 +0,0 @@ -krb5 simple macros -========================= - -Public -------- - -.. toctree:: - :maxdepth: 1 - - ADDRTYPE_ADDRPORT.rst - ADDRTYPE_CHAOS.rst - ADDRTYPE_DDP.rst - ADDRTYPE_INET.rst - ADDRTYPE_INET6.rst - ADDRTYPE_IPPORT.rst - ADDRTYPE_ISO.rst - ADDRTYPE_IS_LOCAL.rst - ADDRTYPE_NETBIOS.rst - ADDRTYPE_XNS.rst - AD_TYPE_EXTERNAL.rst - AD_TYPE_FIELD_TYPE_MASK.rst - AD_TYPE_REGISTERED.rst - AD_TYPE_RESERVED.rst - AP_OPTS_ETYPE_NEGOTIATION.rst - AP_OPTS_MUTUAL_REQUIRED.rst - AP_OPTS_RESERVED.rst - AP_OPTS_USE_SESSION_KEY.rst - AP_OPTS_USE_SUBKEY.rst - AP_OPTS_WIRE_MASK.rst - CKSUMTYPE_CRC32.rst - CKSUMTYPE_DESCBC.rst - CKSUMTYPE_HMAC_MD5_ARCFOUR.rst - CKSUMTYPE_HMAC_SHA1_96_AES128.rst - CKSUMTYPE_HMAC_SHA1_96_AES256.rst - CKSUMTYPE_HMAC_SHA1_DES3.rst - CKSUMTYPE_MD5_HMAC_ARCFOUR.rst - CKSUMTYPE_NIST_SHA.rst - CKSUMTYPE_RSA_MD4.rst - CKSUMTYPE_RSA_MD4_DES.rst - CKSUMTYPE_RSA_MD5.rst - CKSUMTYPE_RSA_MD5_DES.rst - ENCTYPE_AES128_CTS_HMAC_SHA1_96.rst - ENCTYPE_AES256_CTS_HMAC_SHA1_96.rst - ENCTYPE_ARCFOUR_HMAC.rst - ENCTYPE_ARCFOUR_HMAC_EXP.rst - ENCTYPE_DES3_CBC_ENV.rst - ENCTYPE_DES3_CBC_RAW.rst - ENCTYPE_DES3_CBC_SHA.rst - ENCTYPE_DES3_CBC_SHA1.rst - ENCTYPE_DES_CBC_CRC.rst - ENCTYPE_DES_CBC_MD4.rst - ENCTYPE_DES_CBC_MD5.rst - ENCTYPE_DES_CBC_RAW.rst - ENCTYPE_DES_HMAC_SHA1.rst - ENCTYPE_DSA_SHA1_CMS.rst - ENCTYPE_MD5_RSA_CMS.rst - ENCTYPE_NULL.rst - ENCTYPE_RC2_CBC_ENV.rst - ENCTYPE_RSA_ENV.rst - ENCTYPE_RSA_ES_OAEP_ENV.rst - ENCTYPE_SHA1_RSA_CMS.rst - ENCTYPE_UNKNOWN.rst - KDC_OPT_ALLOW_POSTDATE.rst - KDC_OPT_CANONICALIZE.rst - KDC_OPT_CNAME_IN_ADDL_TKT.rst - KDC_OPT_DISABLE_TRANSITED_CHECK.rst - KDC_OPT_ENC_TKT_IN_SKEY.rst - KDC_OPT_FORWARDABLE.rst - KDC_OPT_FORWARDED.rst - KDC_OPT_POSTDATED.rst - KDC_OPT_PROXIABLE.rst - KDC_OPT_PROXY.rst - KDC_OPT_RENEW.rst - KDC_OPT_RENEWABLE.rst - KDC_OPT_RENEWABLE_OK.rst - KDC_OPT_REQUEST_ANONYMOUS.rst - KDC_OPT_VALIDATE.rst - KDC_TKT_COMMON_MASK.rst - KRB5_ALTAUTH_ATT_CHALLENGE_RESPONSE.rst - KRB5_ANONYMOUS_PRINCSTR.rst - KRB5_ANONYMOUS_REALMSTR.rst - KRB5_AP_REP.rst - KRB5_AP_REQ.rst - KRB5_AS_REP.rst - KRB5_AS_REQ.rst - KRB5_AUTHDATA_AND_OR.rst - KRB5_AUTHDATA_ETYPE_NEGOTIATION.rst - KRB5_AUTHDATA_FX_ARMOR.rst - KRB5_AUTHDATA_IF_RELEVANT.rst - KRB5_AUTHDATA_INITIAL_VERIFIED_CAS.rst - KRB5_AUTHDATA_KDC_ISSUED.rst - KRB5_AUTHDATA_MANDATORY_FOR_KDC.rst - KRB5_AUTHDATA_OSF_DCE.rst - KRB5_AUTHDATA_SESAME.rst - KRB5_AUTHDATA_SIGNTICKET.rst - KRB5_AUTHDATA_WIN2K_PAC.rst - KRB5_AUTH_CONTEXT_DO_SEQUENCE.rst - KRB5_AUTH_CONTEXT_DO_TIME.rst - KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR.rst - KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR.rst - KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR.rst - KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR.rst - KRB5_AUTH_CONTEXT_PERMIT_ALL.rst - KRB5_AUTH_CONTEXT_RET_SEQUENCE.rst - KRB5_AUTH_CONTEXT_RET_TIME.rst - KRB5_AUTH_CONTEXT_USE_SUBKEY.rst - KRB5_CRED.rst - KRB5_CRYPTO_TYPE_CHECKSUM.rst - KRB5_CRYPTO_TYPE_DATA.rst - KRB5_CRYPTO_TYPE_EMPTY.rst - KRB5_CRYPTO_TYPE_HEADER.rst - KRB5_CRYPTO_TYPE_PADDING.rst - KRB5_CRYPTO_TYPE_SIGN_ONLY.rst - KRB5_CRYPTO_TYPE_STREAM.rst - KRB5_CRYPTO_TYPE_TRAILER.rst - KRB5_CYBERSAFE_SECUREID.rst - KRB5_DOMAIN_X500_COMPRESS.rst - KRB5_ENCPADATA_REQ_ENC_PA_REP.rst - KRB5_ERROR.rst - KRB5_FAST_REQUIRED.rst - KRB5_GC_CACHED.rst - KRB5_GC_CANONICALIZE.rst - KRB5_GC_CONSTRAINED_DELEGATION.rst - KRB5_GC_FORWARDABLE.rst - KRB5_GC_NO_STORE.rst - KRB5_GC_NO_TRANSIT_CHECK.rst - KRB5_GC_USER_USER.rst - KRB5_GET_INIT_CREDS_OPT_ADDRESS_LIST.rst - KRB5_GET_INIT_CREDS_OPT_ANONYMOUS.rst - KRB5_GET_INIT_CREDS_OPT_CANONICALIZE.rst - KRB5_GET_INIT_CREDS_OPT_CHG_PWD_PRMPT.rst - KRB5_GET_INIT_CREDS_OPT_ETYPE_LIST.rst - KRB5_GET_INIT_CREDS_OPT_FORWARDABLE.rst - KRB5_GET_INIT_CREDS_OPT_PREAUTH_LIST.rst - KRB5_GET_INIT_CREDS_OPT_PROXIABLE.rst - KRB5_GET_INIT_CREDS_OPT_RENEW_LIFE.rst - KRB5_GET_INIT_CREDS_OPT_SALT.rst - KRB5_GET_INIT_CREDS_OPT_TKT_LIFE.rst - KRB5_INIT_CONTEXT_SECURE.rst - KRB5_INIT_CONTEXT_KDC.rst - KRB5_INIT_CREDS_STEP_FLAG_CONTINUE.rst - KRB5_INT16_MAX.rst - KRB5_INT16_MIN.rst - KRB5_INT32_MAX.rst - KRB5_INT32_MIN.rst - KRB5_KEYUSAGE_AD_ITE.rst - KRB5_KEYUSAGE_AD_KDCISSUED_CKSUM.rst - KRB5_KEYUSAGE_AD_MTE.rst - KRB5_KEYUSAGE_AD_SIGNEDPATH.rst - KRB5_KEYUSAGE_APP_DATA_CKSUM.rst - KRB5_KEYUSAGE_APP_DATA_ENCRYPT.rst - KRB5_KEYUSAGE_AP_REP_ENCPART.rst - KRB5_KEYUSAGE_AP_REQ_AUTH.rst - KRB5_KEYUSAGE_AP_REQ_AUTH_CKSUM.rst - KRB5_KEYUSAGE_AS_REP_ENCPART.rst - KRB5_KEYUSAGE_AS_REQ.rst - KRB5_KEYUSAGE_AS_REQ_PA_ENC_TS.rst - KRB5_KEYUSAGE_ENC_CHALLENGE_CLIENT.rst - KRB5_KEYUSAGE_ENC_CHALLENGE_KDC.rst - KRB5_KEYUSAGE_FAST_ENC.rst - KRB5_KEYUSAGE_FAST_FINISHED.rst - KRB5_KEYUSAGE_FAST_REP.rst - KRB5_KEYUSAGE_FAST_REQ_CHKSUM.rst - KRB5_KEYUSAGE_GSS_TOK_MIC.rst - KRB5_KEYUSAGE_GSS_TOK_WRAP_INTEG.rst - KRB5_KEYUSAGE_GSS_TOK_WRAP_PRIV.rst - KRB5_KEYUSAGE_IAKERB_FINISHED.rst - KRB5_KEYUSAGE_KDC_REP_TICKET.rst - KRB5_KEYUSAGE_KRB_CRED_ENCPART.rst - KRB5_KEYUSAGE_KRB_ERROR_CKSUM.rst - KRB5_KEYUSAGE_KRB_PRIV_ENCPART.rst - KRB5_KEYUSAGE_KRB_SAFE_CKSUM.rst - KRB5_KEYUSAGE_PA_OTP_REQUEST.rst - KRB5_KEYUSAGE_PA_PKINIT_KX.rst - KRB5_KEYUSAGE_PA_REFERRAL.rst - KRB5_KEYUSAGE_PA_S4U_X509_USER_REPLY.rst - KRB5_KEYUSAGE_PA_S4U_X509_USER_REQUEST.rst - KRB5_KEYUSAGE_PA_SAM_CHALLENGE_CKSUM.rst - KRB5_KEYUSAGE_PA_SAM_CHALLENGE_TRACKID.rst - KRB5_KEYUSAGE_PA_SAM_RESPONSE.rst - KRB5_KEYUSAGE_TGS_REP_ENCPART_SESSKEY.rst - KRB5_KEYUSAGE_TGS_REP_ENCPART_SUBKEY.rst - KRB5_KEYUSAGE_TGS_REQ_AD_SESSKEY.rst - KRB5_KEYUSAGE_TGS_REQ_AD_SUBKEY.rst - KRB5_KEYUSAGE_TGS_REQ_AUTH.rst - KRB5_KEYUSAGE_TGS_REQ_AUTH_CKSUM.rst - KRB5_KPASSWD_ACCESSDENIED.rst - KRB5_KPASSWD_AUTHERROR.rst - KRB5_KPASSWD_BAD_VERSION.rst - KRB5_KPASSWD_HARDERROR.rst - KRB5_KPASSWD_INITIAL_FLAG_NEEDED.rst - KRB5_KPASSWD_MALFORMED.rst - KRB5_KPASSWD_SOFTERROR.rst - KRB5_KPASSWD_SUCCESS.rst - KRB5_LRQ_ALL_ACCT_EXPTIME.rst - KRB5_LRQ_ALL_LAST_INITIAL.rst - KRB5_LRQ_ALL_LAST_RENEWAL.rst - KRB5_LRQ_ALL_LAST_REQ.rst - KRB5_LRQ_ALL_LAST_TGT.rst - KRB5_LRQ_ALL_LAST_TGT_ISSUED.rst - KRB5_LRQ_ALL_PW_EXPTIME.rst - KRB5_LRQ_NONE.rst - KRB5_LRQ_ONE_ACCT_EXPTIME.rst - KRB5_LRQ_ONE_LAST_INITIAL.rst - KRB5_LRQ_ONE_LAST_RENEWAL.rst - KRB5_LRQ_ONE_LAST_REQ.rst - KRB5_LRQ_ONE_LAST_TGT.rst - KRB5_LRQ_ONE_LAST_TGT_ISSUED.rst - KRB5_LRQ_ONE_PW_EXPTIME.rst - KRB5_NT_ENTERPRISE_PRINCIPAL.rst - KRB5_NT_ENT_PRINCIPAL_AND_ID.rst - KRB5_NT_MS_PRINCIPAL.rst - KRB5_NT_MS_PRINCIPAL_AND_ID.rst - KRB5_NT_PRINCIPAL.rst - KRB5_NT_SMTP_NAME.rst - KRB5_NT_SRV_HST.rst - KRB5_NT_SRV_INST.rst - KRB5_NT_SRV_XHST.rst - KRB5_NT_UID.rst - KRB5_NT_UNKNOWN.rst - KRB5_NT_WELLKNOWN.rst - KRB5_NT_X500_PRINCIPAL.rst - KRB5_OLD_CRYPTO.rst - KRB5_PAC_CLIENT_INFO.rst - KRB5_PAC_CREDENTIALS_INFO.rst - KRB5_PAC_DELEGATION_INFO.rst - KRB5_PAC_LOGON_INFO.rst - KRB5_PAC_PRIVSVR_CHECKSUM.rst - KRB5_PAC_SERVER_CHECKSUM.rst - KRB5_PAC_UPN_DNS_INFO.rst - KRB5_PADATA_AFS3_SALT.rst - KRB5_PADATA_AP_REQ.rst - KRB5_PADATA_ENCRYPTED_CHALLENGE.rst - KRB5_PADATA_ENC_SANDIA_SECURID.rst - KRB5_PADATA_ENC_TIMESTAMP.rst - KRB5_PADATA_ENC_UNIX_TIME.rst - KRB5_PADATA_ETYPE_INFO.rst - KRB5_PADATA_ETYPE_INFO2.rst - KRB5_PADATA_FOR_USER.rst - KRB5_PADATA_FX_COOKIE.rst - KRB5_PADATA_FX_ERROR.rst - KRB5_PADATA_FX_FAST.rst - KRB5_PADATA_GET_FROM_TYPED_DATA.rst - KRB5_PADATA_NONE.rst - KRB5_PADATA_OSF_DCE.rst - KRB5_PADATA_OTP_CHALLENGE.rst - KRB5_PADATA_OTP_PIN_CHANGE.rst - KRB5_PADATA_OTP_REQUEST.rst - KRB5_PADATA_PAC_REQUEST.rst - KRB5_PADATA_PKINIT_KX.rst - KRB5_PADATA_PK_AS_REP.rst - KRB5_PADATA_PK_AS_REP_OLD.rst - KRB5_PADATA_PK_AS_REQ.rst - KRB5_PADATA_PK_AS_REQ_OLD.rst - KRB5_PADATA_PW_SALT.rst - KRB5_PADATA_REFERRAL.rst - KRB5_PADATA_S4U_X509_USER.rst - KRB5_PADATA_SAM_CHALLENGE.rst - KRB5_PADATA_SAM_CHALLENGE_2.rst - KRB5_PADATA_SAM_REDIRECT.rst - KRB5_PADATA_SAM_RESPONSE.rst - KRB5_PADATA_SAM_RESPONSE_2.rst - KRB5_PADATA_SESAME.rst - KRB5_PADATA_SVR_REFERRAL_INFO.rst - KRB5_PADATA_TGS_REQ.rst - KRB5_PADATA_USE_SPECIFIED_KVNO.rst - KRB5_PRINCIPAL_COMPARE_CASEFOLD.rst - KRB5_PRINCIPAL_COMPARE_ENTERPRISE.rst - KRB5_PRINCIPAL_COMPARE_IGNORE_REALM.rst - KRB5_PRINCIPAL_COMPARE_UTF8.rst - KRB5_PRINCIPAL_PARSE_ENTERPRISE.rst - KRB5_PRINCIPAL_PARSE_NO_REALM.rst - KRB5_PRINCIPAL_PARSE_REQUIRE_REALM.rst - KRB5_PRINCIPAL_UNPARSE_DISPLAY.rst - KRB5_PRINCIPAL_UNPARSE_NO_REALM.rst - KRB5_PRINCIPAL_UNPARSE_SHORT.rst - KRB5_PRIV.rst - KRB5_PROMPT_TYPE_NEW_PASSWORD.rst - KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN.rst - KRB5_PROMPT_TYPE_PASSWORD.rst - KRB5_PROMPT_TYPE_PREAUTH.rst - KRB5_PVNO.rst - KRB5_REALM_BRANCH_CHAR.rst - KRB5_RECVAUTH_BADAUTHVERS.rst - KRB5_RECVAUTH_SKIP_VERSION.rst - KRB5_REFERRAL_REALM.rst - KRB5_SAFE.rst - KRB5_SAM_MUST_PK_ENCRYPT_SAD.rst - KRB5_SAM_SEND_ENCRYPTED_SAD.rst - KRB5_SAM_USE_SAD_AS_KEY.rst - KRB5_TC_MATCH_2ND_TKT.rst - KRB5_TC_MATCH_AUTHDATA.rst - KRB5_TC_MATCH_FLAGS.rst - KRB5_TC_MATCH_FLAGS_EXACT.rst - KRB5_TC_MATCH_IS_SKEY.rst - KRB5_TC_MATCH_KTYPE.rst - KRB5_TC_MATCH_SRV_NAMEONLY.rst - KRB5_TC_MATCH_TIMES.rst - KRB5_TC_MATCH_TIMES_EXACT.rst - KRB5_TC_NOTICKET.rst - KRB5_TC_OPENCLOSE.rst - KRB5_TC_SUPPORTED_KTYPES.rst - KRB5_TGS_NAME.rst - KRB5_TGS_NAME_SIZE.rst - KRB5_TGS_REP.rst - KRB5_TGS_REQ.rst - KRB5_TKT_CREDS_STEP_FLAG_CONTINUE.rst - KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL.rst - KRB5_WELLKNOWN_NAMESTR.rst - LR_TYPE_INTERPRETATION_MASK.rst - LR_TYPE_THIS_SERVER_ONLY.rst - MAX_KEYTAB_NAME_LEN.rst - MSEC_DIRBIT.rst - MSEC_VAL_MASK.rst - SALT_TYPE_AFS_LENGTH.rst - SALT_TYPE_NO_LENGTH.rst - THREEPARAMOPEN.rst - TKT_FLG_ANONYMOUS.rst - TKT_FLG_ENC_PA_REP.rst - TKT_FLG_FORWARDABLE.rst - TKT_FLG_FORWARDED.rst - TKT_FLG_HW_AUTH.rst - TKT_FLG_INITIAL.rst - TKT_FLG_INVALID.rst - TKT_FLG_MAY_POSTDATE.rst - TKT_FLG_OK_AS_DELEGATE.rst - TKT_FLG_POSTDATED.rst - TKT_FLG_PRE_AUTH.rst - TKT_FLG_PROXIABLE.rst - TKT_FLG_PROXY.rst - TKT_FLG_RENEWABLE.rst - TKT_FLG_TRANSIT_POLICY_CHECKED.rst - VALID_INT_BITS.rst - VALID_UINT_BITS.rst - krb5_const.rst - krb5_princ_component.rst - krb5_princ_name.rst - krb5_princ_realm.rst - krb5_princ_set_realm.rst - krb5_princ_set_realm_data.rst - krb5_princ_set_realm_length.rst - krb5_princ_size.rst - krb5_princ_type.rst - krb5_roundup.rst - krb5_x.rst - krb5_xc.rst - -Deprecated macros ------------------------------- - -.. toctree:: - :maxdepth: 1 - - krb524_convert_creds_kdc.rst - krb524_init_ets.rst diff --git a/doc/rst_source/krb_appldev/refs/types/index.rst b/doc/rst_source/krb_appldev/refs/types/index.rst deleted file mode 100644 index 9e9190d3d..000000000 --- a/doc/rst_source/krb_appldev/refs/types/index.rst +++ /dev/null @@ -1,102 +0,0 @@ -krb5 types and structures -========================= - -Public -------- - -.. toctree:: - :maxdepth: 1 - - krb5_address.rst - krb5_addrtype.rst - krb5_ap_req.rst - krb5_ap_rep.rst - krb5_ap_rep_enc_part.rst - krb5_authdata.rst - krb5_authdatatype.rst - krb5_authenticator.rst - krb5_boolean.rst - krb5_checksum.rst - krb5_const_pointer.rst - krb5_const_principal.rst - krb5_cred.rst - krb5_cred_enc_part.rst - krb5_cred_info.rst - krb5_creds.rst - krb5_crypto_iov.rst - krb5_cryptotype.rst - krb5_data.rst - krb5_deltat.rst - krb5_enc_data.rst - krb5_enc_kdc_rep_part.rst - krb5_enc_tkt_part.rst - krb5_encrypt_block.rst - krb5_enctype.rst - krb5_error.rst - krb5_error_code.rst - krb5_expire_callback_func.rst - krb5_flags.rst - krb5_get_init_creds_opt.rst - krb5_gic_opt_pa_data.rst - krb5_int32.rst - krb5_kdc_rep.rst - krb5_kdc_req.rst - krb5_keyblock.rst - krb5_keytab_entry.rst - krb5_keyusage.rst - krb5_kt_cursor.rst - krb5_kvno.rst - krb5_last_req_entry.rst - krb5_magic.rst - krb5_mk_req_checksum_func.rst - krb5_msgtype.rst - krb5_octet.rst - krb5_octet_data.rst - krb5_pa_pac_req.rst - krb5_pa_server_referral_data.rst - krb5_pa_svr_referral_data.rst - krb5_pa_data.rst - krb5_pointer.rst - krb5_preauthtype.rst - krb5_principal.rst - krb5_principal_data.rst - krb5_const_principal.rst - krb5_prompt.rst - krb5_prompt_type.rst - krb5_prompter_fct.rst - krb5_pwd_data.rst - krb5_response.rst - krb5_replay_data.rst - krb5_ticket.rst - krb5_ticket_times.rst - krb5_timestamp.rst - krb5_tkt_authent.rst - krb5_trace_callback.rst - krb5_trace_info.rst - krb5_transited.rst - krb5_typed_data.rst - krb5_ui_4.rst - krb5_verify_init_creds_opt.rst - passwd_phrase_element.rst - - -Internal ---------- - -.. toctree:: - :maxdepth: 1 - - krb5_auth_context.rst - krb5_cksumtype - krb5_context.rst - krb5_cc_cursor.rst - krb5_ccache.rst - krb5_cccol_cursor.rst - krb5_init_creds_context.rst - krb5_key.rst - krb5_keytab.rst - krb5_pac.rst - krb5_rcache.rst - krb5_tkt_creds_context.rst - - diff --git a/doc/rst_source/krb_appldev/refs/types/krb5_int32.rst b/doc/rst_source/krb_appldev/refs/types/krb5_int32.rst deleted file mode 100644 index 2bc914b3c..000000000 --- a/doc/rst_source/krb_appldev/refs/types/krb5_int32.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlightlang:: c - -.. _krb5-int32-struct: - -krb5_int32 -========== - -.. -.. c:type:: krb5_int32 -.. - -krb5_int32 is a signed 32-bit integer type diff --git a/doc/rst_source/krb_appldev/refs/types/krb5_ui_4.rst b/doc/rst_source/krb_appldev/refs/types/krb5_ui_4.rst deleted file mode 100644 index de79bafe1..000000000 --- a/doc/rst_source/krb_appldev/refs/types/krb5_ui_4.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. highlightlang:: c - -.. _krb5-ui4-struct: - -krb5_ui_4 -========== - -.. -.. c:type:: krb5_ui_4 -.. - -krb5_ui_4 is an unsigned 32-bit integer type. diff --git a/doc/rst_source/krb_basic/date_format.rst b/doc/rst_source/krb_basic/date_format.rst deleted file mode 100644 index bb8925144..000000000 --- a/doc/rst_source/krb_basic/date_format.rst +++ /dev/null @@ -1,138 +0,0 @@ -.. _datetime: - -Supported date and time formats -=============================== - -.. _duration: - -Time duration -------------- - -This format is used to express a time duration in the Kerberos -configuration files and user commands. The allowed formats are: - - ====================== ============== ============ - Format Example Value - ---------------------- -------------- ------------ - h:m[:s] 36:00 36 hours - NdNhNmNs 8h30s 8 hours 30 seconds - N (number of seconds) 3600 1 hour - ====================== ============== ============ - -Here *N* denotes a number, *d* - days, *h* - hours, *m* - minutes, -*s* - seconds. - -.. note:: - The time interval should not exceed 2147483647 seconds. - -Examples:: - - Request a ticket valid for one hour, five hours, 30 minutes - and 10 days respectively: - - kinit -l 3600 - kinit -l 5:00 - kinit -l 30m - kinit -l "10d 0h 0m 0s" - - -.. _getdate: - -getdate time ------------- - -Some of the kadmin and kdb5_util commands take a date-time in a -human-readable format. Some of the acceptable date-time -strings are: - - +-----------+------------------+-----------------+ - | | Format | Example | - +===========+==================+=================+ - | Date | mm/dd/yy | 07/27/12 | - | +------------------+-----------------+ - | | month dd, yyyy | Jul 27, 2012 | - | +------------------+-----------------+ - | | yyyy-mm-dd | 2012-07-27 | - +-----------+------------------+-----------------+ - | Absolute | HH:mm[:ss]pp | 08:30 PM | - | time +------------------+-----------------+ - | | hh:mm[:ss] | 20:30 | - +-----------+------------------+-----------------+ - | Relative | N tt | 30 sec | - | time | | | - +-----------+------------------+-----------------+ - | Time zone | Z | EST | - | +------------------+-----------------+ - | | z | -0400 | - +-----------+------------------+-----------------+ - -(See :ref:`abbreviation`.) - -Examples:: - - Create a principal that expires on the date indicated: - addprinc test1 -expire "3/27/12 10:00:07 EST" - addprinc test2 -expire "January 23, 2015 10:05pm" - addprinc test3 -expire "22:00 GMT" - Add a principal that will expire in 30 minutes: - addprinc test4 -expire "30 minutes" - - -.. _abstime: - -Absolute time -------------- - -This rarely used date-time format can be noted in one of the -following ways: - - - +------------------------+----------------------+--------------+ - | Format | Example | Value | - +========================+======================+==============+ - | yyyymmddhhmmss | 20141231235900 | One minute | - +------------------------+----------------------+ before 2015 | - | yyyy.mm.dd.hh.mm.ss | 2014.12.31.23.59.00 | | - +------------------------+----------------------+ | - | yymmddhhmmss | 141231235900 | | - +------------------------+----------------------+ | - | yy.mm.dd.hh.mm.ss | 14.12.31.23.59.00 | | - +------------------------+----------------------+ | - | dd-month-yyyy:hh:mm:ss | 31-Dec-2014:23:59:00 | | - +------------------------+----------------------+--------------+ - | hh:mm:ss | 20:00:00 | 8 o'clock in | - +------------------------+----------------------+ the evening | - | hhmmss | 200000 | | - +------------------------+----------------------+--------------+ - -(See :ref:`abbreviation`.) - -Example :: - - Set the default expiration date to July 27, 2012 at 20:30 - default_principal_expiration = 20120727203000 - - -.. _abbreviation: - -Abbreviations used in this document -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -| *month* : locale’s month name or its abbreviation; -| *dd* : day of month (01-31); -| *HH* : hours (00-12); -| *hh* : hours (00-23); -| *mm* : in time - minutes (00-59); in date - month (01-12); -| *N* : number; -| *pp* : AM or PM; -| *ss* : seconds (00-60); -| *tt* : time units (hours, minutes, min, seconds, sec); -| *yyyy* : year; -| *yy* : last two digits of the year; -| *Z* : alphabetic time zone abbreviation; -| *z* : numeric time zone; - -.. note:: - - If the date specification contains spaces, you may need to - enclose it in double quotes; - - All keywords are case-insensitive. diff --git a/doc/rst_source/krb_basic/index.rst b/doc/rst_source/krb_basic/index.rst deleted file mode 100644 index e7a69301d..000000000 --- a/doc/rst_source/krb_basic/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _basic_concepts: - -Kerberos V5 concepts -==================== - - -.. toctree:: - :maxdepth: 1 - - keytab_def - rcache_def - stash_file_def - date_format diff --git a/doc/rst_source/krb_basic/keytab_def.rst b/doc/rst_source/krb_basic/keytab_def.rst deleted file mode 100644 index 33ae67c6c..000000000 --- a/doc/rst_source/krb_basic/keytab_def.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. _keytab_definition: - -keytab -====== - -A keytab (short for "key table") stores long-term keys for one or more -principals. Keytabs are normally represented by files in a standard -format, although in rare cases they can be represented in other ways. -Keytabs are used most often to allow server applications to accept -authentications from clients, but can also be used to obtain initial -credentials for client applications. - -Keytabs are named using the format *type*\ ``:``\ *value*. Usually -*type* is ``FILE`` and *value* is the absolute pathname of the file. -Other possible values for *type* are ``SRVTAB``, which indicates a -file in the deprecated Kerberos 4 srvtab format, and ``MEMORY``, which -indicates a temporary keytab stored in the memory of the current -process. - -A keytab contains one or more entries, where each entry consists of a -timestamp (indicating when the entry was written to the keytab), a -principal name, a key version number, an encryption type, and the -encryption key itself. - -A keytab can be displayed using the :ref:`klist(1)` command with the -``-k`` option. Keytabs can be created or appended to by extracting -keys from the KDC database using the :ref:`kadmin(1)` :ref:`ktadd` -command. Keytabs can be manipulated using the :ref:`ktutil(1)` and -:ref:`k5srvutil(1)` commands. - - -Default keytab --------------- - -The default keytab is used by server applications if the application -does not request a specific keytab. The name of the default keytab is -determined by the following, in decreasing order of preference: - -#. The **KRB5_KTNAME** environment variable. - -#. The **default_keytab_name** profile variable in :ref:`libdefaults`. - -#. The hardcoded default, |keytab|. - - -Default client keytab ---------------------- - -The default client keytab is used, if it is present and readable, to -automatically obtain initial credentials for GSSAPI client -applications. The principal name of the first entry in the client -keytab is used by default when obtaining initial credentials. The -name of the default client keytab is determined by the following, in -decreasing order of preference: - -#. The **KRB5_CLIENT_KTNAME** environment variable. - -#. The **default_client_keytab_name** profile variable in - :ref:`libdefaults`. - -#. The hardcoded default, |ckeytab|. diff --git a/doc/rst_source/krb_basic/rcache_def.rst b/doc/rst_source/krb_basic/rcache_def.rst deleted file mode 100644 index 2de953354..000000000 --- a/doc/rst_source/krb_basic/rcache_def.rst +++ /dev/null @@ -1,97 +0,0 @@ -.. _rcache_definition: - -replay cache -============ - -A replay cache (or "rcache") keeps track of all authenticators -recently presented to a service. If a duplicate authentication -request is detected in the replay cache, an error message is sent to -the application program. - -The replay cache interface, like the credential cache and -:ref:`keytab_definition` interfaces, uses `type:value` strings to -indicate the type of replay cache and any associated cache naming -data to use. - -Background information ----------------------- - -Some Kerberos or GSSAPI services use a simple authentication mechanism -where a message is sent containing an authenticator, which establishes -the encryption key that the client will use for talking to the -service. But nothing about that prevents an eavesdropper from -recording the messages sent by the client, establishing a new -connection, and re-sending or "replaying" the same messages; the -replayed authenticator will establish the same encryption key for the -new session, and the following messages will be decrypted and -processed. The attacker may not know what the messages say, and can't -generate new messages under the same encryption key, but in some -instances it may be harmful to the user (or helpful to the attacker) -to cause the server to see the same messages again a second time. For -example, if the legitimate client sends "delete first message in -mailbox", a replay from an attacker may delete another, different -"first" message. (Protocol design to guard against such problems has -been discussed in :rfc:`4120#section-10`.) - -Even if one protocol uses further protection to verify that the client -side of the connection actually knows the encryption keys (and thus is -presumably a legitimate user), if another service uses the same -service principal name, it may be possible to record an authenticator -used with the first protocol and "replay" it against the second. - -The replay cache mitigates these attacks somewhat, by keeping track of -authenticators that have been seen until their five-minute window -expires. Different authenticators generated by multiple connections -from the same legitimate client will generally have different -timestamps, and thus will not be considered the same. - -This mechanism isn't perfect. If a message is sent to one application -server but a man-in-the-middle attacker can prevent it from actually -arriving at that server, the attacker could then use the authenticator -(once!) against a different service on the same host. This could be a -problem if the message from the client included something more than -authentication in the first message that could be useful to the -attacker (which is uncommon; in most protocols the server has to -indicate a successful authentication before the client sends -additional messages), or if the simple act of presenting the -authenticator triggers some interesting action in the service being -attacked. - -Default rcache type -------------------- - -There is currently only one implemented kind of replay cache, called -**dfl**. It stores replay data in one file, occasionally rewriting it -to purge old, expired entries. - -The default type can be overridden by the **KRB5RCACHETYPE** -environment variable. - -The placement of the replay cache file is determined by the following: - -#. The **KRB5RCACHEDIR** environment variable; - -#. If KRB5RCACHEDIR is unspecified, on UNIX, the library - will fall back to the environment variable **TMPDIR**, and then to - a temporary directory determined at configuration time such as - */tmp* or */var/tmp*; on Windows, it will check the environment - variables *TEMP* and *TMP*, and fall back to the directory C:\\. - -Performance issues ------------------- - -Several known minor performance issues that may occur when replay -cache is enabled on the Kerberos system include: delays due to writing -the authenticator data to disk slowing down response time for very -heavily loaded servers, and delays during the rewrite that may be -unacceptable to high-performance services. - -For use cases where replays are adequately defended against for all -protocols using a given service principal name, or where performance -or other considerations outweigh the risk of replays, the special -replay cache type "none" can be specified:: - - KRB5RCACHETYPE=none - -It doesn't record any information about authenticators, and reports -that any authenticator seen is not a replay. diff --git a/doc/rst_source/krb_basic/stash_file_def.rst b/doc/rst_source/krb_basic/stash_file_def.rst deleted file mode 100644 index cd6cca47b..000000000 --- a/doc/rst_source/krb_basic/stash_file_def.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _stash_definition: - - -stash file -============ - -The stash file is a local copy of the master key that resides in -encrypted form on the KDC's local disk. The stash file is used to -authenticate the KDC to itself automatically before starting the -:ref:`kadmind(8)` and :ref:`krb5kdc(8)` daemons (e.g., as part of the -machine's boot sequence). The stash file, like the keytab file (see -:ref:`keytab_file`) is a potential point-of-entry for a break-in, and -if compromised, would allow unrestricted access to the Kerberos -database. If you choose to install a stash file, it should be -readable only by root, and should exist only on the KDC's local disk. -The file should not be part of any backup of the machine, unless -access to the backup data is secured as tightly as access to the -master password itself. - -.. note:: If you choose not to install a stash file, the KDC will prompt you for the master key each time it starts up. - This means that the KDC will not be able to start automatically, such as after a system reboot. - - diff --git a/doc/rst_source/krb_build/directory_org.rst b/doc/rst_source/krb_build/directory_org.rst deleted file mode 100644 index 928c20377..000000000 --- a/doc/rst_source/krb_build/directory_org.rst +++ /dev/null @@ -1,76 +0,0 @@ -Organization of the source directory -==================================== - -Below is a brief overview of the organization of the complete source -directory. More detailed descriptions follow. - -=============== ============================================== -appl Kerberos application client and server programs -ccapi Credential cache services -clients Kerberos V5 user programs (See :ref:`user_commands`) -config Configure scripts -config-files Sample Kerberos configuration files -gen-manpages manpages for Kerberos V5 and the Kerberos V5 login program -include include files needed to build the Kerberos system -kadmin Administrative interface to the Kerberos master database: :ref:`kadmin(1)`, :ref:`kdb5_util(8)`, :ref:`ktutil(1)`. -kdc Kerberos V5 Authentication Service and Key Distribution Center -lib_ Libraries for use with/by Kerberos V5 -plugins Kerberos plugins directory -po Localization infrastructure -prototype Templates files containing the MIT copyright message and a placeholder for the title and description of the file. -slave Utilities for propagating the database to slave KDCs :ref:`kprop(8)` and :ref:`kpropd(8)` -tests Test suite -util_ Various utilities for building/configuring the code, sending bug reports, etc. -windows Source code for building Kerberos V5 on Windows (see windows/README) -=============== ============================================== - - -.. _lib: - -lib ---- - -The lib directory contain several subdirectories as well as some -definition and glue files. - - - The apputils directory contains the code for the generic network - servicing. - - The crypto subdirectory contains the Kerberos V5 encryption - library. - - The gssapi library contains the Generic Security Services API, - which is a library of commands to be used in secure client-server - communication. - - The kadm5 directory contains the libraries for the KADM5 - administration utilities. - - The Kerberos 5 database libraries are contained in kdb. - - The krb5 directory contains Kerberos 5 API. - - The rpc directory contains the API for the Kerberos Remote - Procedure Call protocol. - - -.. _util: - -util ----- - -The util directory contains several utility programs and libraries. - - the programs used to configure and build the code, such as - autoconf, lndir, kbuild, reconf, and makedepend, are in this - directory. - - the profile directory contains most of the functions which parse - the Kerberos configuration files (krb5.conf and kdc.conf). - - the Kerberos error table library and utilities (et); - - the Sub-system library and utilities (ss); - - database utilities (db2); - - pseudo-terminal utilities (pty); - - bug-reporting program send-pr; - - a generic support library support used by several of our other - libraries; - - the build infrastructure for building lightweight Kerberos client - (collected-client-lib) - - the tool for validating Kerberos configuration files - (confvalidator); - - the toolkit for kernel integrators for building krb5 code subsets - (gss-kernel-lib); - - source code for building Kerberos V5 on MacOS (mac) - - Windows getopt operations (windows) diff --git a/doc/rst_source/krb_build/doing_build.rst b/doc/rst_source/krb_build/doing_build.rst deleted file mode 100644 index bc438c849..000000000 --- a/doc/rst_source/krb_build/doing_build.rst +++ /dev/null @@ -1,172 +0,0 @@ -Doing the build -=============== - -Using autoconf --------------- - -(If you are not a developer, you can skip this section.) - -In the Kerberos V5 source directory, there is a configure script which -automatically determines the compilation environment and creates the -proper Makefiles for a particular platform. This configure script is -generated using autoconf, which you should already have installed. - -Normal users will not need to worry about running autoconf; the -distribution comes with the configure script already prebuilt. - -One tool which is provided for the convenience of developers can be -found in ``src/util/reconf``. This program should be run while the -current directory is the top source directory. It will automatically -rebuild the configure script if it needs rebuilding. If you know that -you have made a change that will require that the configure file be -rebuilt from scratch, specify the **-**\ **-force** option:: - - cd /u1/krb5-VERSION/src - ./util/reconf --force - -Then follow the instructions for building packaged source trees -(below). To install the binaries into a binary tree, do:: - - cd /u1/krb5-VERSION/src - make all - make install DESTDIR=somewhere-else - -You have a number of different options in how to build Kerberos. - -.. _do_build: - -Building within a single tree ------------------------------ - -If you only need to build Kerberos for one platform, using a single -directory tree which contains both the source files and the object -files is the simplest. However, if you need to maintain Kerberos for -a large number of platforms, you will probably want to use separate -build trees for each platform. We recommend that you look at OS -Incompatibilities, for notes that we have on particular operating -systems. - -If you don't want separate build trees for each architecture, then use -the following abbreviated procedure:: - - cd /u1/krb5-VERSION/src - ./configure - make - -That's it! - -Building with separate build directories ----------------------------------------- - -If you wish to keep separate build directories for each platform, you -can do so using the following procedure. (Note, this requires that -your make program support VPATH. GNU's make will provide this -functionality, for example.) If your make program does not support -this, see the next section. - -For example, if you wish to store the binaries in ``tmpbuild`` build -directory you might use the following procedure:: - - mkdir /u1/tmpbuild - cd /u1/tmpbuild - /u1/krb5-VERSION/src/configure - make - - -Building using lndir --------------------- - -If you wish to keep separate build directories for each platform, and -you do not have access to a make program which supports VPATH, all is -not lost. You can use the lndir program to create symbolic link trees -in your build directory. - -For example, if you wish to create a build directory for solaris -binaries you might use the following procedure:: - - mkdir /u1/krb5-VERSION/solaris - cd /u1/krb5-VERSION/solaris - /u1/krb5-VERSION/src/util/lndir `pwd`/../src - ./configure - make - -You must give an absolute pathname to lndir because it has a bug that -makes it fail for relative pathnames. Note that this version differs -from the latest version as distributed and installed by the -XConsortium with X11R6. Either version should be acceptable. - - -Installing the binaries ------------------------ - -Once you have built Kerberos, you should install the binaries. You can -do this by running:: - - make install - -If you want to install the binaries into a destination directory that -is not their final destination, which may be convenient if you want to -build a binary distribution to be deployed on multiple hosts, you may -use:: - - make install DESTDIR=/path/to/destdir - -This will install the binaries under *DESTDIR/PREFIX*, e.g., the user -programs will install into *DESTDIR/PREFIX/bin*, the libraries into -*DESTDIR/PREFIX/lib*, etc. - -Some implementations of make allow multiple commands to be run in -parallel, for faster builds. We test our Makefiles in parallel builds -with GNU make only; they may not be compatible with other parallel -build implementations. - - -Testing the build ------------------ - -The Kerberos V5 distribution comes with built-in regression tests. To -run them, simply type the following command while in the top-level -build directory (i.e., the directory where you sent typed make to -start building Kerberos; see :ref:`do_build`):: - - make check - -However, there are several prerequisites that must be satisfied first: - -* Configure and build Kerberos with Tcl support. Tcl is used to drive - the test suite. This often means passing **-**\ **-with-tcl** to - configure to tell it the location of the Tcl configuration - script. (See :ref:`options2configure`.) -* In addition to Tcl, DejaGnu must be available on the system for some - of the tests to run. The test suite will still run the other tests - if DejaGnu is not present, but the test coverage will be reduced - accordingly. -* On some operating systems, you have to run ``make install`` before - running ``make check``, or the test suite will pick up installed - versions of Kerberos libraries rather than the newly built ones. - You can install into a prefix that isn't in the system library - search path, though. Alternatively, you can configure with - **-**\ **-disable-rpath**, which renders the build tree less suitable for - installation, but allows testing without interference from - previously installed libraries. -* In order to test the RPC layer, the local system has to be running - the portmap daemon and it has to be listening to the regular network - interface (not just localhost). - -There are additional regression tests available, which are not run -by ``make check``. These tests require manual setup and teardown of -support infrastructure which is not easily automated, or require -excessive resources for ordinary use. The procedure for running -the manual tests is documented at -http://k5wiki.kerberos.org/wiki/Manual_Testing. - - -Cleaning up the build ---------------------- - -* Use ``make clean`` to remove all files generated by running make - command. -* Use ``make distclean`` to remove all files generated by running - ./configure script. After running ``make distclean`` your source - tree (ideally) should look like the raw (just un-tarred) source tree - with executed ``util/reconf`` command. diff --git a/doc/rst_source/krb_build/index.rst b/doc/rst_source/krb_build/index.rst deleted file mode 100644 index b39b242db..000000000 --- a/doc/rst_source/krb_build/index.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. _build_V5: - -Building Kerberos V5 -==================== - -This section details how to build and install MIT Kerberos software -from the source. - -Prerequisites -------------- - -In order to build Kerberos V5, you will need approximately 60-70 -megabytes of disk space. The exact amount will vary depending on the -platform and whether the distribution is compiled with debugging -symbol tables or not. - -Your C compiler must conform to ANSI C (ISO/IEC 9899:1990, "c89"). -Some operating systems do not have an ANSI C compiler, or their -default compiler requires extra command-line options to enable ANSI C -conformance. - -If you wish to keep a separate build tree, which contains the compiled -\*.o file and executables, separate from your source tree, you will -need a make program which supports **VPATH**, or you will need to use -a tool such as lndir to produce a symbolic link tree for your build -tree. - -Obtaining the software ----------------------- - -The source code can be obtained from MIT Kerberos Distribution page, -at http://web.mit.edu/kerberos/dist/index.html. -The MIT Kerberos distribution comes in an archive file, generally named -krb5-VERSION.tar, where *VERSION* is a placeholder for the major and minor -versions of MIT Kerberos. (For example, MIT Kerberos 1.9 -has major version "1" and minor version "9".) - -The krb5-VERSION.tar contains a compressed tar file consisting of the -sources for all of Kerberos (generally krb5-VERSION.tar.gz) and -a PGP signature file for this source tree (generally -krb5-VERSION.tar.gz.asc). MIT highly recommends that you verify -the integrity of the source code using this signature. - -Unpack krb5-VERSION.tar.gz in some directory. In this section we will assume -that you have chosen the top directory of the distribution the directory -``/u1/krb5-VERSION``. - -Review the README file for the license, copyright and other sprecific to the -distribution information. - -Contents --------- -.. toctree:: - :maxdepth: 1 - - directory_org.rst - doing_build.rst - options2configure.rst - osconf.rst - test_cov.rst diff --git a/doc/rst_source/krb_build/options2configure.rst b/doc/rst_source/krb_build/options2configure.rst deleted file mode 100644 index 211df7ea8..000000000 --- a/doc/rst_source/krb_build/options2configure.rst +++ /dev/null @@ -1,408 +0,0 @@ -.. _options2configure: - -Options to *configure* -====================== - -There are a number of options to configure which you can use to -control how the Kerberos distribution is built. - -Most commonly used options --------------------------- - -**-**\ **-help** - Provides help to configure. This will list the set of commonly - used options for building Kerberos. - -**-**\ **-prefix=**\ *PREFIX* - By default, Kerberos will install the package's files rooted at - ``/usr/local``. If you desire to place the binaries into the - directory *PREFIX*, use this option. - -**-**\ **-exec-prefix=**\ *EXECPREFIX* - This option allows one to separate the architecture independent - programs from the host-dependent files (configuration files, - manual pages). Use this option to install architecture-dependent - programs in *EXECPREFIX*. The default location is the value of - specified by **-**\ **-prefix** option. - -**-**\ **-localstatedir=**\ *LOCALSTATEDIR* - This option sets the directory for locally modifiable - single-machine data. In Kerberos, this mostly is useful for - setting a location for the KDC data files, as they will be - installed in ``LOCALSTATEDIR/krb5kdc``, which is by default - ``PREFIX/var/krb5kdc``. - -**-**\ **-with-netlib**\ [=\ *libs*] - Allows for suppression of or replacement of network libraries. By - default, Kerberos V5 configuration will look for ``-lnsl`` and - ``-lsocket``. If your operating system has a broken resolver - library or fails to pass the tests in ``src/tests/resolv``, you - will need to use this option. - -**-**\ **-with-tcl=**\ *TCLPATH* - Some of the unit-tests in the build tree rely upon using a program - in Tcl. The directory specified by *TCLPATH* specifies where the - Tcl header file (TCLPATH/include/tcl.h) as well as where the Tcl - library (TCLPATH/lib) should be found. - -**-**\ **-enable-dns-for-realm** - Enable the use of DNS to look up a host's Kerberos realm, - if the information is not provided in - :ref:`krb5.conf(5)`. See - :ref:`mapping_hostnames` - for information about using DNS to determine the default realm. - DNS lookups for realm names are disabled by default. - -**-**\ **-with-system-et** - Use an installed version of the error-table (et) support software, - the compile_et program, the com_err.h header file and the com_err - library. If these are not in the default locations, you may wish - to specify ``CPPFLAGS=-I/some/dir`` and - ``LDFLAGS=-L/some/other/dir`` options at configuration time as - well. - - If this option is not given, a version supplied with the Kerberos - sources will be built and installed along with the rest of the - Kerberos tree, for Kerberos applications to link against. - -**-**\ **-with-system-ss** - Use an installed version of the subsystem command-line interface - software, the mk_cmds program, the ``ss/ss.h`` header file and the - ss library. If these are not in the default locations, you may - wish to specify ``CPPFLAGS=-I/some/dir`` and - ``LDFLAGS=-L/some/other/dir`` options at configuration time as - well. See also the **SS_LIB** option. - - If this option is not given, the ss library supplied with the - Kerberos sources will be compiled and linked into those programs - that need it; it will not be installed separately. - -**-**\ **-with-system-db** - Use an installed version of the Berkeley DB package, which must - provide an API compatible with version 1.85. This option is - unsupported and untested. In particular, we do not know if the - database-rename code used in the dumpfile load operation will - behave properly. - - If this option is not given, a version supplied with the Kerberos - sources will be built and installed. (We are not updating this - version at this time because of licensing issues with newer - versions that we haven't investigated sufficiently yet.) - - -Environment variables ---------------------- - -**CC=**\ *COMPILER* - Use *COMPILER* as the C compiler. - -**CFLAGS=**\ *FLAGS* - Use *FLAGS* as the default set of C compiler flags. - -**CPP=**\ *CPP* - C preprocessor to use. (e.g., ``CPP='gcc -E'``) - -**CPPFLAGS=**\ *CPPOPTS* - Use *CPPOPTS* as the default set of C preprocessor flags. The - most common use of this option is to select certain #define's for - use with the operating system's include files. - - -**DB_HEADER=**\ *headername* - If db.h is not the correct header file to include to compile - against the Berkeley DB 1.85 API, specify the correct header file - name with this option. For example, ``DB_HEADER=db3/db_185.h``. - -**DB_LIB=**\ *libs*... - If ``-ldb`` is not the correct library specification for the - Berkeley DB library version to be used, override it with this - option. For example, ``DB_LIB=-ldb-3.3``. - -**DEFCCNAME=**\ *ccachename* - Override the built-in default credential cache name. - -**DEFCKTNAME=**\ *keytabname* - Override the built-in default client keytab name. - -**DEFKTNAME=**\ *keytabname* - Override the built-in default keytab name. - -**LD=**\ *LINKER* - Use *LINKER* as the default loader if it should be different from - C compiler as specified above. - -**LDFLAGS=**\ *LDOPTS* - This option informs the linker where to get additional libraries - (e.g., ``-L``). - -**LIBS=**\ *LDNAME* - This option allows one to specify libraries to be passed to the - linker (e.g., ``-l``) - -**SS_LIB=**\ *libs*... - If ``-lss`` is not the correct way to link in your installed ss - library, for example if additional support libraries are needed, - specify the correct link options here. Some variants of this - library are around which allow for Emacs-like line editing, but - different versions require different support libraries to be - explicitly specified. - - This option is ignored if **-**\ **-with-system-ss** is not specified. - -**YACC** - The 'Yet Another C Compiler' implementation to use. Defaults to - the first program found out of: '`bison -y`', '`byacc`', - '`yacc`'. - -**YFLAGS** - The list of arguments that will be passed by default to $YACC. - This script will default YFLAGS to the empty string to avoid a - default value of ``-d`` given by some make applications. - - -Fine tuning of the installation directories -------------------------------------------- - -**-**\ **-bindir=**\ *DIR* - User executables. Defaults to ``EXECPREFIX/bin``, where - *EXECPREFIX* is the path specified by **-**\ **-exec-prefix** - configuration option. - -**-**\ **-sbindir=**\ *DIR* - System admin executables. Defaults to ``EXECPREFIX/sbin``, where - *EXECPREFIX* is the path specified by **-**\ **-exec-prefix** - configuration option. - -**-**\ **-sysconfdir=**\ *DIR* - Read-only single-machine data such as krb5.conf. - Defaults to ``PREFIX/etc``, where - *PREFIX* is the path specified by **-**\ **-prefix** configuration - option. - -**-**\ **-libdir=**\ *DIR* - Object code libraries. Defaults to ``EXECPREFIX/lib``, where - *EXECPREFIX* is the path specified by **-**\ **-exec-prefix** - configuration option. - -**-**\ **-includedir=**\ *DIR* - C header files. Defaults to ``PREFIX/include``, where *PREFIX* is - the path specified by **-**\ **-prefix** configuration option. - -**-**\ **-datarootdir=**\ *DATAROOTDIR* - Read-only architecture-independent data root. Defaults to - ``PREFIX/share``, where *PREFIX* is the path specified by - **-**\ **-prefix** configuration option. - -**-**\ **-datadir=**\ *DIR* - Read-only architecture-independent data. Defaults to path - specified by **-**\ **-datarootdir** configuration option. - -**-**\ **-localedir=**\ *DIR* - Locale-dependent data. Defaults to ``DATAROOTDIR/locale``, where - *DATAROOTDIR* is the path specified by **-**\ **-datarootdir** - configuration option. - -**-**\ **-mandir=**\ *DIR* - Man documentation. Defaults to ``DATAROOTDIR/man``, where - *DATAROOTDIR* is the path specified by **-**\ **-datarootdir** - configuration option. - - -Program names -------------- - -**-**\ **-program-prefix=**\ *PREFIX* - Prepend *PREFIX* to the names of the programs when installing - them. For example, specifying ``--program-prefix=mit-`` at the - configure time will cause the program named ``abc`` to be - installed as ``mit-abc``. - -**-**\ **-program-suffix=**\ *SUFFIX* - Append *SUFFIX* to the names of the programs when installing them. - For example, specifying ``--program-suffix=-mit`` at the configure - time will cause the program named ``abc`` to be installed as - ``abc-mit``. - -**-**\ **-program-transform-name=**\ *PROGRAM* - Run ``sed -e PROGRAM`` on installed program names. (*PROGRAM* is a - sed script). - - -System types ------------- - -**-**\ **-build=**\ *BUILD* - Configure for building on *BUILD* - (e.g., ``--build=x86_64-linux-gnu``). - -**-**\ **-host=**\ *HOST* - Cross-compile to build programs to run on *HOST* - (e.g., ``--host=x86_64-linux-gnu``). By default, Kerberos V5 - configuration will look for "build" option. - - -Optional features ------------------ - -**-**\ **-disable-option-checking** - Ignore unrecognized --enable/--with options. - -**-**\ **-disable-**\ *FEATURE* - Do not include *FEATURE* (same as --enable-FEATURE=no). - -**-**\ **-enable-**\ *FEATURE*\ [=\ *ARG*] - Include *FEATURE* [ARG=yes]. - -**-**\ **-enable-maintainer-mode** - Enable rebuilding of source files, Makefiles, etc. - -**-**\ **-disable-delayed-initialization** - Initialize library code when loaded. Defaults to delay until - first use. - -**-**\ **-disable-thread-support** - Don't enable thread support. Defaults to enabled. - -**-**\ **-disable-rpath** - Suppress run path flags in link lines. - -**-**\ **-enable-athena** - Build with MIT Project Athena configuration. - -**-**\ **-disable-kdc-lookaside-cache** - Disable the cache which detects client retransmits. - -**-**\ **-disable-pkinit** - Disable PKINIT plugin support. - - -Optional packages ------------------ - -**-**\ **-with-**\ *PACKAGE*\ [=ARG\] - Use *PACKAGE* (e.g., ``--with-imap``). The default value of *ARG* - is ``yes``. - -**-**\ **-without-**\ *PACKAGE* - Do not use *PACKAGE* (same as ``--with-PACKAGE=no``) - (e.g., ``--without-libedit``). - -**-**\ **-with-size-optimizations** - Enable a few optimizations to reduce code size possibly at some - run-time cost. - -**-**\ **-with-system-et** - Use the com_err library and compile_et utility that are already - installed on the system, instead of building and installing - local versions. - -**-**\ **-with-system-ss** - Use the ss library and mk_cmds utility that are already installed - on the system, instead of building and using private versions. - -**-**\ **-with-system-db** - Use the berkeley db utility already installed on the system, - instead of using a private version. This option is not - recommended; enabling it may result in incompatibility with key - databases originating on other systems. - -**-**\ **-with-netlib=**\ *LIBS* - Use the resolver library specified in *LIBS*. Use this variable - if the C library resolver is insufficient or broken. - -**-**\ **-with-hesiod=**\ *path* - Compile with Hesiod support. The *path* points to the Hesiod - directory. By default Hesiod is unsupported. - -**-**\ **-with-ldap** - Compile OpenLDAP database backend module. - -**-**\ **-with-tcl=**\ *path* - Specifies that *path* is the location of a Tcl installation. - Tcl is needed for some of the tests run by 'make check'; such tests - will be skipped if this option is not set. - -**-**\ **-with-vague-errors** - Do not send helpful errors to client. For example, if the KDC - should return only vague error codes to clients. - -**-**\ **-with-crypto-impl=**\ *IMPL* - Use specified crypto implementation (e.g., **-**\ **-with-crypto=**\ - *openssl*). Default is a native MIT Kerberos implementation - ``builtin``. The other currently implemented crypto backends are - ``openssl`` and ``nss``. (See :ref:`mitK5features`) - -**-**\ **-with-prng-alg=**\ *ALG* - Use specified PRNG algorithm. For example, to use the OS native - prng specify ``--with-prng-alg=os``. - - Default is the ``fortuna`` PRNG algorithm. For the ``nss`` crypto - backend use one must explicitly specify ``--with-prng-alg=nss``. - (See :ref:`mitK5features`) - -**-**\ **-with-pkinit-crypto-impl=**\ *IMPL* - Use the specified pkinit crypto implementation *IMPL*. - Defaults to using OpenSSL. - -**-**\ **-with-kdc-kdb-update** - Update the KDC database with the information about - - * the last successful authentication; - * the last failed authentication attempt; - * the number of the failed authentication attempts. - - By default the kdb is not updated with this information. - -**-**\ **-without-libedit** - Do not compile and link against libedit. Some utilities will no - longer offer command history or completion in interactive mode if - libedit is disabled. - -**-**\ **-with-readline** - Compile and link against GNU readline, as an alternative to libedit. - Building with readline breaks the dejagnu test suite, which is a - subset of the tests run by 'make check'. - -**-**\ **-with-system-verto** - Use an installed version of libverto. If the libverto header and - library are not in default locations, you may wish to specify - ``CPPFLAGS=-I/some/dir`` and ``LDFLAGS=-L/some/other/dir`` options - at configuration time as well. - - If this option is not given, the build system will try to detect - an installed version of libverto and use it if it is found. - Otherwise, a version supplied with the Kerberos sources will be - built and installed. The built-in version does not contain the - full set of back-end modules and is not a suitable general - replacement for the upstream version, but will work for the - purposes of Kerberos. - - Specifying **-**\ **-without-system-verto** will cause the built-in - version of libverto to be used unconditionally. - -**-**\ **-with-krb5-config=**\ *PATH* - Use the krb5-config program at *PATH* to obtain the build-time - default credential cache, keytab, and client keytab names. The - default is to use ``krb5-config`` from the program path. Specify - ``--without-krb5-config`` to disable the use of krb5-config and - use the usual built-in defaults. - - -Examples --------- - -For example, in order to configure Kerberos on a Solaris machine using -the suncc compiler with the optimizer turned on, run the configure -script with the following options:: - - % ./configure CC=suncc CFLAGS=-O - -For a slightly more complicated example, consider a system where -several packages to be used by Kerberos are installed in -``/usr/foobar``, including Berkeley DB 3.3, and an ss library that -needs to link against the curses library. The configuration of -Kerberos might be done thus:: - - ./configure CPPFLAGS=-I/usr/foobar/include LDFLAGS=-L/usr/foobar/lib \ - --with-system-et --with-system-ss --with-system-db \ - SS_LIB='-lss -lcurses' DB_HEADER=db3/db_185.h DB_LIB=-ldb-3.3 diff --git a/doc/rst_source/krb_build/osconf.rst b/doc/rst_source/krb_build/osconf.rst deleted file mode 100644 index 22ee6804e..000000000 --- a/doc/rst_source/krb_build/osconf.rst +++ /dev/null @@ -1,26 +0,0 @@ -osconf.hin -========== - -There is one configuration file which you may wish to edit to control -various compile-time parameters in the Kerberos distribution:: - - include/osconf.hin - -The list that follows is by no means complete, just some of the more -interesting variables. - -**DEFAULT_PROFILE_PATH** - The pathname to the file which contains the profiles for the known - realms, their KDCs, etc. The default value is |krb5conf|. -**DEFAULT_KEYTAB_NAME** - The type and pathname to the default server keytab file. The - default is |keytab|. -**DEFAULT_KDC_ENCTYPE** - The default encryption type for the KDC database master key. The - default value is |defmkey|. -**RCTMPDIR** - The directory which stores replay caches. The default is - ``/var/tmp``. -**DEFAULT_KDB_FILE** - The location of the default database. The default value is - |kdcdir|\ ``/principal``. diff --git a/doc/rst_source/krb_build/test_cov.rst b/doc/rst_source/krb_build/test_cov.rst deleted file mode 100644 index ccd6c1367..000000000 --- a/doc/rst_source/krb_build/test_cov.rst +++ /dev/null @@ -1,31 +0,0 @@ -Test coverage -============= - -It is considered good practice to develop and maintain the test suite -with high level of test coverage, i.e., the tests that execute every -single statement, every line of the code and then validate the result. - -The GNU's gcov is a tool that analyses the frequency of execution of -each line of the code. For more details see GNU documentation -http://gcc.gnu.org/onlinedocs/gcc/Gcov.html - -To invoke gcov on krb5 tree, do configure with the following options -and run the tests:: - - ./configure CFLAGS="-fprofile-arcs -ftest-coverage -O0" LIBS=-lgcov - make - make check - -It will result into creation of the new helper files with the -extentions gcno and gcda. - -To validate the test coverage of the specific file, change the -directory to its location and run :: - - gcov -o filename.so.gcno filename.c - -To see the test coverage of the filename.c open a newly created file -filename.c.gcov in the editor. - -Some recent test coverage result can be found at the -http://k5wiki.kerberos.org/wiki/Test_coverage diff --git a/doc/rst_source/krb_plugindev/ccselect.rst b/doc/rst_source/krb_plugindev/ccselect.rst deleted file mode 100644 index 00133d944..000000000 --- a/doc/rst_source/krb_plugindev/ccselect.rst +++ /dev/null @@ -1,26 +0,0 @@ -Credential cache selection interface (ccselect) -=============================================== - -The ccselect interface allows modules to control how credential caches -are chosen when a GSSAPI client contacts a service. For a detailed -description of the ccselect interface, see the header file -````. - -The primary ccselect method is **choose**, which accepts a server -principal as input and returns a ccache and/or principal name as -output. A module can use the krb5_cccol APIs to iterate over the -cache collection in order to find an appropriate ccache to use. - -.. TODO: add reference to the admin guide for ccaches and cache - collections when we have appropriate sections. - -A module can create and destroy per-library-context state objects by -implementing the **init** and **fini** methods. State objects have -the type krb5_ccselect_moddata, which is an abstract pointer type. A -module should typically cast this to an internal type for the state -object. - -A module can have one of two priorities, "authoritative" or -"heuristic". Results from authoritative modules, if any are -available, will take priority over results from heuristic modules. A -module communicates its priority as a result of the **init** method. diff --git a/doc/rst_source/krb_plugindev/clpreauth.rst b/doc/rst_source/krb_plugindev/clpreauth.rst deleted file mode 100644 index 68e56aa5f..000000000 --- a/doc/rst_source/krb_plugindev/clpreauth.rst +++ /dev/null @@ -1,53 +0,0 @@ -Client preauthentication interface (clpreauth) -============================================== - -During an initial ticket request, a KDC may ask a client to prove its -knowledge of the password before issuing an encrypted ticket, or to -use credentials other than a password. This process is called -preauthentication, and is described in :rfc:`4120` and :rfc:`6113`. -The clpreauth interface allows the addition of client support for -preauthentication mechanisms beyond those included in the core MIT -krb5 code base. For a detailed description of the clpreauth -interface, see the header file ````. - -A clpreauth module is generally responsible for: - -* Supplying a list of preauth type numbers used by the module in the - **pa_type_list** field of the vtable structure. - -* Indicating what kind of preauthentication mechanism it implements, - with the **flags** method. In the most common case, this method - just returns ``PA_REAL``, indicating that it implements a normal - preauthentication type. - -* Examining the padata information included in the preauth_required - error and producing padata values for the next AS request. This is - done with the **process** method. - -* Examining the padata information included in a successful ticket - reply, possibly verifying the KDC identity and computing a reply - key. This is also done with the **process** method. - -* For preauthentication types which support it, recovering from errors - by examining the error data from the KDC and producing a padata - value for another AS request. This is done with the **tryagain** - method. - -* Receiving option information (supplied by ``kinit -X`` or by an - application), with the **gic_opts** method. - -A clpreauth module can create and destroy per-library-context and -per-request state objects by implementing the **init**, **fini**, -**request_init**, and **request_fini** methods. Per-context state -objects have the type krb5_clpreauth_moddata, and per-request state -objects have the type krb5_clpreauth_modreq. These are abstract -pointer types; a module should typically cast these to internal -types for the state objects. - -The **process** and **tryagain** methods have access to a callback -function and handle (called a "rock") which can be used to get -additional information about the current request, including the -expected enctype of the AS reply, the FAST armor key, and the client -long-term key (prompting for the user password if necessary). A -callback can also be used to replace the AS reply key if the -preauthentication mechanism computes one. diff --git a/doc/rst_source/krb_plugindev/general.rst b/doc/rst_source/krb_plugindev/general.rst deleted file mode 100644 index dff680762..000000000 --- a/doc/rst_source/krb_plugindev/general.rst +++ /dev/null @@ -1,98 +0,0 @@ -General plugin concepts -======================= - -A krb5 dynamic plugin module is a Unix shared object or Windows DLL. -Typically, the source code for a dynamic plugin module should live in -its own project with a build system using automake_ and libtool_, or -tools with similar functionality. - -A plugin module must define a specific symbol name, which depends on -the pluggable interface and module name. For most pluggable -interfaces, the exported symbol is a function named -``INTERFACE_MODULE_initvt``, where *INTERFACE* is the name of the -pluggable interface and *MODULE* is the name of the module. For these -interfaces, it is possible for one shared object or DLL to implement -multiple plugin modules, either for the same pluggable interface or -for different ones. For example, a shared object could implement both -KDC and client preauthentication mechanisms, by exporting functions -named ``kdcpreauth_mymech_initvt`` and ``clpreauth_mymech_initvt``. - -.. note: The profile, locate, and GSSAPI mechglue pluggable interfaces - follow different conventions. See the documentation for - those interfaces for details. The remainder of this section - applies to pluggable interfaces which use the standard - conventions. - -A plugin module implementation should include the header file -````, where *INTERFACE* is the name of the -pluggable interface. For instance, a ccselect plugin module -implementation should use ``#include ``. - -.. note: clpreauth and kdcpreauth module implementations should - include . - -initvt functions have the following prototype:: - - krb5_error_code interface_modname_initvt(krb5_context context, - int maj_ver, int min_ver, - krb5_plugin_vtable vtable); - -and should do the following: - -1. Check that the supplied maj_ver argument is supported by the - module. If it is not supported, the function should return - KRB5_PLUGIN_VER_NOTSUPP. - -2. Cast the supplied vtable pointer to the structure type - corresponding to the major version, as documented in the pluggable - interface header file. - -3. Fill in the structure fields with pointers to method functions and - static data, stopping at the field indicated by the supplied minor - version. Fields for unimplemented optional methods can be left - alone; it is not necessary to initialize them to NULL. - -In most cases, the context argument will not be used. The initvt -function should not allocate memory; think of it as a glorified -structure initializer. Each pluggable interface defines methods for -allocating and freeing module state if doing so is necessary for the -interface. - -Pluggable interfaces typically include a **name** field in the vtable -structure, which should be filled in with a pointer to a string -literal containing the module name. - -Here is an example of what an initvt function might look like for a -fictional pluggable interface named fences, for a module named -"wicker":: - - krb5_error_code - fences_wicker_initvt(krb5_context context, int maj_ver, - int min_ver, krb5_plugin_vtable vtable) - { - krb5_ccselect_vtable vt; - - if (maj_ver == 1) { - krb5_fences_vtable vt = (krb5_fences_vtable)vtable; - vt->name = "wicker"; - vt->slats = wicker_slats; - vt->braces = wicker_braces; - } else if (maj_ver == 2) { - krb5_fences_vtable_v2 vt = (krb5_fences_vtable_v2)vtable; - vt->name = "wicker"; - vt->material = wicker_material; - vt->construction = wicker_construction; - if (min_ver < 2) - return 0; - vt->footing = wicker_footing; - if (min_ver < 3) - return 0; - vt->appearance = wicker_appearance; - } else { - return KRB5_PLUGIN_VER_NOTSUPP; - } - return 0; - } - -.. _automake: http://www.gnu.org/software/automake/ -.. _libtool: http://www.gnu.org/software/libtool/ diff --git a/doc/rst_source/krb_plugindev/index.rst b/doc/rst_source/krb_plugindev/index.rst deleted file mode 100644 index e913810bb..000000000 --- a/doc/rst_source/krb_plugindev/index.rst +++ /dev/null @@ -1,32 +0,0 @@ -For plugin module developers -============================ - -Kerberos plugin modules allow increased control over MIT krb5 library -and server behavior. This guide describes how to create dynamic -plugin modules and the currently available pluggable interfaces. - -See :ref:`plugin_config` for information on how to register dynamic -plugin modules and how to enable and disable modules via -:ref:`krb5.conf(5)`. - -.. TODO: update the above reference when we have a free-form section - in the admin guide about plugin configuration - - -Contents --------- - -.. toctree:: - :maxdepth: 2 - - general.rst - clpreauth.rst - kdcpreauth.rst - ccselect.rst - pwqual.rst - kadm5_hook.rst - locate.rst - profile.rst - internal.rst - -.. TODO: GSSAPI mechanism plugins diff --git a/doc/rst_source/krb_plugindev/internal.rst b/doc/rst_source/krb_plugindev/internal.rst deleted file mode 100644 index 99e30bb79..000000000 --- a/doc/rst_source/krb_plugindev/internal.rst +++ /dev/null @@ -1,32 +0,0 @@ -Internal pluggable interfaces -============================= - -Following are brief discussions of pluggable interfaces which have not -yet been made public. These interfaces are functional, but the -interfaces are likely to change in incompatible ways from release to -release. In some cases, it may be necessary to copy header files from -the krb5 source tree to use an internal interface. Use these with -care, and expect to need to update your modules for each new release -of MIT krb5. - - -Kerberos database interface (KDB) ---------------------------------- - -A KDB module implements a database back end for KDC principal and -policy information, and can also control many aspects of KDC behavior. -For a full description of the interface, see the header file -````. - -The KDB pluggable interface is often referred to as the DAL (Database -Access Layer). - - -Authorization data interface (authdata) ---------------------------------------- - -The authdata interface allows a module to provide (from the KDC) or -consume (in application servers) authorization data of types beyond -those handled by the core MIT krb5 code base. The interface is -defined in the header file ````, which is not -installed by the build. diff --git a/doc/rst_source/krb_plugindev/kadm5_hook.rst b/doc/rst_source/krb_plugindev/kadm5_hook.rst deleted file mode 100644 index 01d330e8e..000000000 --- a/doc/rst_source/krb_plugindev/kadm5_hook.rst +++ /dev/null @@ -1,24 +0,0 @@ -KADM5 hook interface (kadm5_hook) -================================= - -The kadm5_hook interface allows modules to perform actions when -changes are made to the Kerberos database through :ref:`kadmin(1)`. -For a detailed description of the kadm5_hook interface, see the header -file ````. - -The kadm5_hook interface has four primary methods: **chpass**, -**create**, **modify**, and **remove**. Each of these methods is -called twice when the corresponding administrative action takes place, -once before the action is committed and once afterwards. A module can -prevent the action from taking place by returning an error code during -the pre-commit stage. - -A module can create and destroy per-process state objects by -implementing the **init** and **fini** methods. State objects have -the type kadm5_hook_modinfo, which is an abstract pointer type. A -module should typically cast this to an internal type for the state -object. - -Because the kadm5_hook interface is tied closely to the kadmin -interface (which is explicitly unstable), it may not remain as stable -across versions as other public pluggable interfaces. diff --git a/doc/rst_source/krb_plugindev/kdcpreauth.rst b/doc/rst_source/krb_plugindev/kdcpreauth.rst deleted file mode 100644 index e6ba9e531..000000000 --- a/doc/rst_source/krb_plugindev/kdcpreauth.rst +++ /dev/null @@ -1,61 +0,0 @@ -KDC preauthentication interface (kdcpreauth) -============================================ - -The kdcpreauth interface allows the addition of KDC support for -preauthentication mechanisms beyond those included in the core MIT -krb5 code base. For a detailed description of the kdcpreauth -interface, see the header file ````. - -A kdcpreauth module is generally responsible for: - -* Supplying a list of preauth type numbers used by the module in the - **pa_type_list** field of the vtable structure. - -* Indicating what kind of preauthentication mechanism it implements, - with the **flags** method. If the mechanism computes a new reply - key, it must specify the ``PA_REPLACES_KEY`` flag. If the mechanism - is generally only used with hardware tokens, the ``PA_HARDWARE`` - flag allows the mechanism to work with principals which have the - **requires_hwauth** flag set. - -* Producing a padata value to be sent with a preauth_required error, - with the **edata** method. - -* Examining a padata value sent by a client and verifying that it - proves knowledge of the appropriate client credential information. - This is done with the **verify** method. - -* Producing a padata response value for the client, and possibly - computing a reply key. This is done with the **return_padata** - method. - -A module can create and destroy per-KDC state objects by implementing -the **init** and **fini** methods. Per-KDC state objects have the -type krb5_kdcpreauth_moddata, which is an abstract pointer types. A -module should typically cast this to an internal type for the state -object. - -A module can create a per-request state object by returning one in the -**verify** method, receiving it in the **return_padata** method, and -destroying it in the **free_modreq** method. Note that these state -objects only apply to the processing of a single AS request packet, -not to an entire authentication exchange (since an authentication -exchange may remain unfinished by the client or may involve multiple -different KDC hosts). Per-request state objects have the type -krb5_kdcpreauth_modreq, which is an abstract pointer type. - -The **edata**, **verify**, and **return_padata** methods have access -to a callback function and handle (called a "rock") which can be used -to get additional information about the current request, including the -maximum allowable clock skew, the client's long-term keys, the -DER-encoded request body, the FAST armor key, string attributes on the -client's database entry, and the client's database entry itself. - -The **edata** and **verify** methods can be implemented -asynchronously. Because of this, they do not return values directly -to the caller, but must instead invoke responder functions with their -results. A synchronous implementation can invoke the responder -function immediately. An asynchronous implementation can use the -callback to get an event context for use with the libverto_ API. - -.. _libverto: https://fedorahosted.org/libverto/ diff --git a/doc/rst_source/krb_plugindev/locate.rst b/doc/rst_source/krb_plugindev/locate.rst deleted file mode 100644 index fca6a4da7..000000000 --- a/doc/rst_source/krb_plugindev/locate.rst +++ /dev/null @@ -1,32 +0,0 @@ -Server location interface (locate) -================================== - -The locate interface allows modules to control how KDCs and similar -services are located by clients. For a detailed description of the -ccselect interface, see the header file ````. - -.. note: The locate interface does not follow the normal conventions - for MIT krb5 pluggable interfaces, because it was made public - before those conventions were established. - -A locate module exports a structure object of type -krb5plugin_service_locate_ftable, with the name ``service_locator``. -The structure contains a minor version and pointers to the module's -methods. - -The primary locate method is **lookup**, which accepts a service type, -realm name, desired socket type, and desired address family (which -will be AF_UNSPEC if no specific address family is desired). The -method should invoke the callback function once for each server -address it wants to return, passing a socket type (SOCK_STREAM for TCP -or SOCK_DGRAM for UDP) and socket address. The **lookup** method -should return 0 if it has authoritatively determined the server -addresses for the realm, KRB5_PLUGIN_NO_HANDLE if it wants to let -other location mechanisms determine the server addresses, or another -code if it experienced a failure which should abort the location -process. - -A module can create and destroy per-library-context state objects by -implementing the **init** and **fini** methods. State objects have -the type void \*, and should be cast to an internal type for the state -object. diff --git a/doc/rst_source/krb_plugindev/profile.rst b/doc/rst_source/krb_plugindev/profile.rst deleted file mode 100644 index 671d4c18c..000000000 --- a/doc/rst_source/krb_plugindev/profile.rst +++ /dev/null @@ -1,92 +0,0 @@ -Configuration interface (profile) -================================= - -The profile interface allows a module to control how krb5 -configuration information is obtained by the Kerberos library and -applications. For a detailed description of the profile interface, -see the header file ````. - -.. note:: The profile interface does not follow the normal conventions - for MIT krb5 pluggable interfaces, because it is part of a - lower-level component of the krb5 library. - -As with other types of plugin modules, a profile module is a Unix -shared object or Windows DLL, built separately from the krb5 tree. -The krb5 library will dynamically load and use a profile plugin module -if it reads a ``module`` directive at the beginning of krb5.conf, as -described in :ref:`profile_plugin_config`. - -A profile module exports a function named ``profile_module_init`` -matching the signature of the profile_module_init_fn type. This -function accepts a residual string, which may be used to help locate -the configuration source. The function fills in a vtable and may also -create a per-profile state object. If the module uses state objects, -it should implement the **copy** and **cleanup** methods to manage -them. - -A basic read-only profile module need only implement the -**get_values** and **free_values** methods. The **get_values** method -accepts a null-terminated list of C string names (e.g., an array -containing "libdefaults", "clockskew", and NULL for the **clockskew** -variable in the :ref:`libdefaults` section) and returns a -null-terminated list of values, which will be cleaned up with the -**free_values** method when the caller is done with them. - -Iterable profile modules must also define the **iterator_create**, -**iterator**, **iterator_free**, and **free_string** methods. The -core krb5 code does not require profiles to be iterable, but some -applications may iterate over the krb5 profile object in order to -present configuration interfaces. - -Writable profile modules must also define the **writable**, -**modified**, **update_relation**, **rename_section**, -**add_relation**, and **flush** methods. The core krb5 code does not -require profiles to be writable, but some applications may write to -the krb5 profile in order to present configuration interfaces. - -The following is an example of a very basic read-only profile module -which returns a hardcoded value for the **default_realm** variable in -:ref:`libdefaults`, and provides no other configuration information. -(For conciseness, the example omits code for checking the return -values of malloc and strdup.) :: - - #include - #include - #include - - static long - get_values(void *cbdata, const char *const *names, char ***values) - { - if (names[0] != NULL && strcmp(names[0], "libdefaults") == 0 && - names[1] != NULL && strcmp(names[1], "default_realm") == 0) { - *values = malloc(2 * sizeof(char *)); - (*values)[0] = strdup("ATHENA.MIT.EDU"); - (*values)[1] = NULL; - return 0; - } - return PROF_NO_RELATION; - } - - static void - free_values(void *cbdata, char **values) - { - char **v; - - for (v = values; *v; v++) - free(*v); - free(values); - } - - long - profile_module_init(const char *residual, struct profile_vtable *vtable, - void **cb_ret); - - long - profile_module_init(const char *residual, struct profile_vtable *vtable, - void **cb_ret) - { - *cb_ret = NULL; - vtable->get_values = get_values; - vtable->free_values = free_values; - return 0; - } diff --git a/doc/rst_source/krb_plugindev/pwqual.rst b/doc/rst_source/krb_plugindev/pwqual.rst deleted file mode 100644 index a981e7903..000000000 --- a/doc/rst_source/krb_plugindev/pwqual.rst +++ /dev/null @@ -1,23 +0,0 @@ -Password quality interface (pwqual) -=================================== - -The pwqual interface allows modules to control what passwords are -allowed when a user changes passwords. For a detailed description of -the pwqual interface, see the header file ````. - -The primary pwqual method is **check**, which receives a password as -input and returns success (0) or a ``KADM5_PASS_Q_`` failure code -depending on whether the password is allowed. The **check** method -also receives the principal name and the name of the principal's -password policy as input; although there is no stable interface for -the module to obtain the fields of the password policy, it can define -its own configuration or data store based on the policy name. - -A module can create and destroy per-process state objects by -implementing the **open** and **close** methods. State objects have -the type krb5_pwqual_moddata, which is an abstract pointer type. A -module should typically cast this to an internal type for the state -object. The **open** method also receives the name of the realm's -dictionary file (as configured by the **dict_file** variable in the -:ref:`kdc_realms` section of :ref:`kdc.conf(5)`) if it wishes to use -it. diff --git a/doc/rst_source/krb_users/index.rst b/doc/rst_source/krb_users/index.rst deleted file mode 100644 index 233c3ef55..000000000 --- a/doc/rst_source/krb_users/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -For users -========= - -.. toctree:: - :maxdepth: 2 - - pwd_mgmt.rst - tkt_mgmt.rst - user_config/index.rst - user_commands/index.rst diff --git a/doc/rst_source/krb_users/pwd_mgmt.rst b/doc/rst_source/krb_users/pwd_mgmt.rst deleted file mode 100644 index ed7d459f0..000000000 --- a/doc/rst_source/krb_users/pwd_mgmt.rst +++ /dev/null @@ -1,106 +0,0 @@ -Password management -=================== - -Your password is the only way Kerberos has of verifying your identity. -If someone finds out your password, that person can masquerade as -you---send email that comes from you, read, edit, or delete your files, -or log into other hosts as you---and no one will be able to tell the -difference. For this reason, it is important that you choose a good -password, and keep it secret. If you need to give access to your -account to someone else, you can do so through Kerberos (see -:ref:`grant_access`). You should never tell your password to anyone, -including your system administrator, for any reason. You should -change your password frequently, particularly any time you think -someone may have found out what it is. - - -Changing your password ----------------------- - -To change your Kerberos password, use the :ref:`kpasswd(1)` command. -It will ask you for your old password (to prevent someone else from -walking up to your computer when you're not there and changing your -password), and then prompt you for the new one twice. (The reason you -have to type it twice is to make sure you have typed it correctly.) -For example, user ``david`` would do the following:: - - shell% kpasswd - Password for david: <- Type your old password. - Enter new password: <- Type your new password. - Enter it again: <- Type the new password again. - Password changed. - shell% - -If ``david`` typed the incorrect old password, he would get the -following message:: - - shell% kpasswd - Password for david: <- Type the incorrect old password. - kpasswd: Password incorrect while getting initial ticket - shell% - -If you make a mistake and don't type the new password the same way -twice, kpasswd will ask you to try again:: - - shell% kpasswd - Password for david: <- Type the old password. - Enter new password: <- Type the new password. - Enter it again: <- Type a different new password. - kpasswd: Password mismatch while reading password - shell% - -Once you change your password, it takes some time for the change to -propagate through the system. Depending on how your system is set up, -this might be anywhere from a few minutes to an hour or more. If you -need to get new Kerberos tickets shortly after changing your password, -try the new password. If the new password doesn't work, try again -using the old one. - - -.. _grant_access: - -Granting access to your account -------------------------------- - -If you need to give someone access to log into your account, you can -do so through Kerberos, without telling the person your password. -Simply create a file called :ref:`.k5login(5)` in your home directory. -This file should contain the Kerberos principal of each person to whom -you wish to give access. Each principal must be on a separate line. -Here is a sample .k5login file:: - - jennifer@ATHENA.MIT.EDU - david@EXAMPLE.COM - -This file would allow the users ``jennifer`` and ``david`` to use your -user ID, provided that they had Kerberos tickets in their respective -realms. If you will be logging into other hosts across a network, you -will want to include your own Kerberos principal in your .k5login file -on each of these hosts. - -Using a .k5login file is much safer than giving out your password, -because: - -* You can take access away any time simply by removing the principal - from your .k5login file. - -* Although the user has full access to your account on one particular - host (or set of hosts if your .k5login file is shared, e.g., over - NFS), that user does not inherit your network privileges. - -* Kerberos keeps a log of who obtains tickets, so a system - administrator could find out, if necessary, who was capable of using - your user ID at a particular time. - -One common application is to have a .k5login file in root's home -directory, giving root access to that machine to the Kerberos -principals listed. This allows system administrators to allow users -to become root locally, or to log in remotely as root, without their -having to give out the root password, and without anyone having to -type the root password over the network. - - -Password quality verification ------------------------------ - -TODO diff --git a/doc/rst_source/krb_users/tkt_mgmt.rst b/doc/rst_source/krb_users/tkt_mgmt.rst deleted file mode 100644 index 0ca95accd..000000000 --- a/doc/rst_source/krb_users/tkt_mgmt.rst +++ /dev/null @@ -1,312 +0,0 @@ -Ticket management -================= - -On many systems, Kerberos is built into the login program, and you get -tickets automatically when you log in. Other programs, such as ssh, -can forward copies of your tickets to a remote host. Most of these -programs also automatically destroy your tickets when they exit. -However, MIT recommends that you explicitly destroy your Kerberos -tickets when you are through with them, just to be sure. One way to -help ensure that this happens is to add the :ref:`kdestroy(1)` command -to your .logout file. Additionally, if you are going to be away from -your machine and are concerned about an intruder using your -permissions, it is safest to either destroy all copies of your -tickets, or use a screensaver that locks the screen. - - -Kerberos ticket properties --------------------------- - -There are various properties that Kerberos tickets can have: - -If a ticket is **forwardable**, then the KDC can issue a new ticket -(with a different network address, if necessary) based on the -forwardable ticket. This allows for authentication forwarding without -requiring a password to be typed in again. For example, if a user -with a forwardable TGT logs into a remote system, the KDC could issue -a new TGT for that user with the netword address of the remote system, -allowing authentication on that host to work as though the user were -logged in locally. - -When the KDC creates a new ticket based on a forwardable ticket, it -sets the **forwarded** flag on that new ticket. Any tickets that are -created based on a ticket with the forwarded flag set will also have -their forwarded flags set. - -A **proxiable** ticket is similar to a forwardable ticket in that it -allows a service to take on the identity of the client. Unlike a -forwardable ticket, however, a proxiable ticket is only issued for -specific services. In other words, a ticket-granting ticket cannot be -issued based on a ticket that is proxiable but not forwardable. - -A **proxy** ticket is one that was issued based on a proxiable ticket. - -A **postdated** ticket is issued with the invalid flag set. After the -starting time listed on the ticket, it can be presented to the KDC to -obtain valid tickets. - -Ticket-granting tickets with the **postdateable** flag set can be used -to obtain postdated service tickets. - -**Renewable** tickets can be used to obtain new session keys without -the user entering their password again. A renewable ticket has two -expiration times. The first is the time at which this particular -ticket expires. The second is the latest possible expiration time for -any ticket issued based on this renewable ticket. - -A ticket with the **initial flag** set was issued based on the -authentication protocol, and not on a ticket-granting ticket. -Application servers that wish to ensure that the user's key has been -recently presented for verification could specify that this flag must -be set to accept the ticket. - -An **invalid** ticket must be rejected by application servers. -Postdated tickets are usually issued with this flag set, and must be -validated by the KDC before they can be used. - -A **preauthenticated** ticket is one that was only issued after the -client requesting the ticket had authenticated itself to the KDC. - -The **hardware authentication** flag is set on a ticket which required -the use of hardware for authentication. The hardware is expected to -be possessed only by the client which requested the tickets. - -If a ticket has the **transit policy** checked flag set, then the KDC -that issued this ticket implements the transited-realm check policy -and checked the transited-realms list on the ticket. The -transited-realms list contains a list of all intermediate realms -between the realm of the KDC that issued the first ticket and that of -the one that issued the current ticket. If this flag is not set, then -the application server must check the transited realms itself or else -reject the ticket. - -The **okay as delegate** flag indicates that the server specified in -the ticket is suitable as a delegate as determined by the policy of -that realm. Some client applications may use this flag to decide -whether to forward tickets to a remote host, although many -applications do not honor it. - -An **anonymous** ticket is one in which the named principal is a -generic principal for that realm; it does not actually specify the -individual that will be using the ticket. This ticket is meant only -to securely distribute a session key. - - -.. _obtain_tkt: - -Obtaining tickets with kinit ----------------------------- - -If your site has integrated Kerberos V5 with the login system, you -will get Kerberos tickets automatically when you log in. Otherwise, -you may need to explicitly obtain your Kerberos tickets, using the -:ref:`kinit(1)` program. Similarly, if your Kerberos tickets expire, -use the kinit program to obtain new ones. - -To use the kinit program, simply type ``kinit`` and then type your -password at the prompt. For example, Jennifer (whose username is -``jennifer``) works for Bleep, Inc. (a fictitious company with the -domain name mit.edu and the Kerberos realm ATHENA.MIT.EDU). She would -type:: - - shell% kinit - Password for jennifer@ATHENA.MIT.EDU: <-- [Type jennifer's password here.] - shell% - -If you type your password incorrectly, kinit will give you the -following error message:: - - shell% kinit - Password for jennifer@ATHENA.MIT.EDU: <-- [Type the wrong password here.] - kinit: Password incorrect - shell% - -and you won't get Kerberos tickets. - -By default, kinit assumes you want tickets for your own username in -your default realm. Suppose Jennifer's friend David is visiting, and -he wants to borrow a window to check his mail. David needs to get -tickets for himself in his own realm, EXAMPLE.COM. He would type:: - - shell% kinit david@EXAMPLE.COM - Password for david@EXAMPLE.COM: <-- [Type david's password here.] - shell% - -David would then have tickets which he could use to log onto his own -machine. Note that he typed his password locally on Jennifer's -machine, but it never went over the network. Kerberos on the local -host performed the authentication to the KDC in the other realm. - -If you want to be able to forward your tickets to another host, you -need to request forwardable tickets. You do this by specifying the -**-f** option:: - - shell% kinit -f - Password for jennifer@ATHENA.MIT.EDU: <-- [Type your password here.] - shell% - -Note that kinit does not tell you that it obtained forwardable -tickets; you can verify this using the :ref:`klist(1)` command (see -:ref:`view_tkt`). - -Normally, your tickets are good for your system's default ticket -lifetime, which is ten hours on many systems. You can specify a -different ticket lifetime with the **-l** option. Add the letter -**s** to the value for seconds, **m** for minutes, **h** for hours, or -**d** for days. For example, to obtain forwardable tickets for -``david@EXAMPLE.COM`` that would be good for three hours, you would -type:: - - shell% kinit -f -l 3h david@EXAMPLE.COM - Password for david@EXAMPLE.COM: <-- [Type david's password here.] - shell% - -.. note:: You cannot mix units; specifying a lifetime of 3h30m would - result in an error. Note also that most systems specify a - maximum ticket lifetime. If you request a longer ticket - lifetime, it will be automatically truncated to the maximum - lifetime. - - -.. _view_tkt: - -Viewing tickets with klist --------------------------- - -The :ref:`klist(1)` command shows your tickets. When you first obtain -tickets, you will have only the ticket-granting ticket. The listing -would look like this:: - - shell% klist - Ticket cache: /tmp/krb5cc_ttypa - Default principal: jennifer@ATHENA.MIT.EDU - - Valid starting Expires Service principal - 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU - shell% - -The ticket cache is the location of your ticket file. In the above -example, this file is named ``/tmp/krb5cc_ttypa``. The default -principal is your Kerberos principal. - -The "valid starting" and "expires" fields describe the period of time -during which the ticket is valid. The "service principal" describes -each ticket. The ticket-granting ticket has a first component -``krbtgt``, and a second component which is the realm name. - -Now, if ``jennifer`` connected to the machine ``daffodil.mit.edu``, -and then typed "klist" again, she would have gotten the following -result:: - - shell% klist - Ticket cache: /tmp/krb5cc_ttypa - Default principal: jennifer@ATHENA.MIT.EDU - - Valid starting Expires Service principal - 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU - 06/07/04 20:22:30 06/08/04 05:49:19 host/daffodil.mit.edu@ATHENA.MIT.EDU - shell% - -Here's what happened: when ``jennifer`` used ssh to connect to the -host ``daffodil.mit.edu``, the ssh program presented her -ticket-granting ticket to the KDC and requested a host ticket for the -host ``daffodil.mit.edu``. The KDC sent the host ticket, which ssh -then presented to the host ``daffodil.mit.edu``, and she was allowed -to log in without typing her password. - -Suppose your Kerberos tickets allow you to log into a host in another -domain, such as ``trillium.example.com``, which is also in another -Kerberos realm, ``EXAMPLE.COM``. If you ssh to this host, you will -receive a ticket-granting ticket for the realm ``EXAMPLE.COM``, plus -the new host ticket for ``trillium.example.com``. klist will now -show:: - - shell% klist - Ticket cache: /tmp/krb5cc_ttypa - Default principal: jennifer@ATHENA.MIT.EDU - - Valid starting Expires Service principal - 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU - 06/07/04 20:22:30 06/08/04 05:49:19 host/daffodil.mit.edu@ATHENA.MIT.EDU - 06/07/04 20:24:18 06/08/04 05:49:19 krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU - 06/07/04 20:24:18 06/08/04 05:49:19 host/trillium.example.com@EXAMPLE.COM - shell% - -Depending on your host's and realm's configuration, you may also see a -ticket with the service principal ``host/trillium.example.com@``. If -so, this means that your host did not know what realm -trillium.example.com is in, so it asked the ``ATHENA.MIT.EDU`` KDC for -a referral. The next time you connect to ``trillium.example.com``, -the odd-looking entry will be used to avoid needing to ask for a -referral again. - -You can use the **-f** option to view the flags that apply to your -tickets. The flags are: - -===== ========================= - F Forwardable - f forwarded - P Proxiable - p proxy - D postDateable - d postdated - R Renewable - I Initial - i invalid - H Hardware authenticated - A preAuthenticated - T Transit policy checked - O Okay as delegate - a anonymous -===== ========================= - -Here is a sample listing. In this example, the user *jennifer* -obtained her initial tickets (**I**), which are forwardable (**F**) -and postdated (**d**) but not yet validated (**i**):: - - shell% klist -f - Ticket cache: /tmp/krb5cc_320 - Default principal: jennifer@ATHENA.MIT.EDU - - Valid starting Expires Service principal - 31/07/05 19:06:25 31/07/05 19:16:25 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU - Flags: FdiI - shell% - -In the following example, the user *david*'s tickets were forwarded -(**f**) to this host from another host. The tickets are reforwardable -(**F**):: - - shell% klist -f - Ticket cache: /tmp/krb5cc_p11795 - Default principal: david@EXAMPLE.COM - - Valid starting Expires Service principal - 07/31/05 11:52:29 07/31/05 21:11:23 krbtgt/EXAMPLE.COM@EXAMPLE.COM - Flags: Ff - 07/31/05 12:03:48 07/31/05 21:11:23 host/trillium.example.com@EXAMPLE.COM - Flags: Ff - shell% - - -Destroying tickets with kdestroy --------------------------------- - -Your Kerberos tickets are proof that you are indeed yourself, and -tickets could be stolen if someone gains access to a computer where -they are stored. If this happens, the person who has them can -masquerade as you until they expire. For this reason, you should -destroy your Kerberos tickets when you are away from your computer. - -Destroying your tickets is easy. Simply type kdestroy:: - - shell% kdestroy - shell% - -If :ref:`kdestroy(1)` fails to destroy your tickets, it will beep and -give an error message. For example, if kdestroy can't find any -tickets to destroy, it will give the following message:: - - shell% kdestroy - kdestroy: No credentials cache file found while destroying cache - shell% diff --git a/doc/rst_source/krb_users/user_commands/index.rst b/doc/rst_source/krb_users/user_commands/index.rst deleted file mode 100644 index b43fad69c..000000000 --- a/doc/rst_source/krb_users/user_commands/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _user_commands: - -User commands -============= - -.. toctree:: - :maxdepth: 1 - - kdestroy.rst - kinit.rst - klist.rst - kpasswd.rst - ksu.rst - kswitch.rst - kvno.rst - sclient.rst diff --git a/doc/rst_source/krb_users/user_commands/kdestroy.rst b/doc/rst_source/krb_users/user_commands/kdestroy.rst deleted file mode 100644 index b8c67aba4..000000000 --- a/doc/rst_source/krb_users/user_commands/kdestroy.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. _kdestroy(1): - -kdestroy -======== - -SYNOPSIS --------- - -**kdestroy** -[**-A**] -[**-q**] -[**-c** *cache_name*] - - -DESCRIPTION ------------ - -The kdestroy utility destroys the user's active Kerberos authorization -tickets by overwriting and deleting the credentials cache that -contains them. If the credentials cache is not specified, the default -credentials cache is destroyed. - - -OPTIONS -------- - -**-A** - Destroys all caches in the collection, if a cache collection is - available. - -**-q** - Run quietly. Normally kdestroy beeps if it fails to destroy the - user's tickets. The **-q** flag suppresses this behavior. - -**-c** *cache_name* - Use *cache_name* as the credentials (ticket) cache name and - location; if this option is not used, the default cache name and - location are used. - - The default credentials cache may vary between systems. If the - **KRB5CCNAME** environment variable is set, its value is used to - name the default ticket cache. - - -NOTE ----- - -Most installations recommend that you place the kdestroy command in -your .logout file, so that your tickets are destroyed automatically -when you log out. - - -ENVIRONMENT ------------ - -kdestroy uses the following environment variable: - -**KRB5CCNAME** - Location of the default Kerberos 5 credentials (ticket) cache, in - the form *type*:*residual*. If no *type* prefix is present, the - **FILE** type is assumed. The type of the default cache may - determine the availability of a cache collection; for instance, a - default cache of type **DIR** causes caches within the directory - to be present in the collection. - - -FILES ------ - -|ccache| - Default location of Kerberos 5 credentials cache - - -SEE ALSO --------- - -:ref:`kinit(1)`, :ref:`klist(1)` diff --git a/doc/rst_source/krb_users/user_commands/kinit.rst b/doc/rst_source/krb_users/user_commands/kinit.rst deleted file mode 100644 index c28fd29b6..000000000 --- a/doc/rst_source/krb_users/user_commands/kinit.rst +++ /dev/null @@ -1,211 +0,0 @@ -.. _kinit(1): - -kinit -===== - -SYNOPSIS --------- - -**kinit** -[**-V**] -[**-l** *lifetime*] -[**-s** *start_time*] -[**-r** *renewable_life*] -[**-p** | -**P**] -[**-f** | -**F**] -[**-a**] -[**-A**] -[**-C**] -[**-E**] -[**-v**] -[**-R**] -[**-k** [-**t** *keytab_file*]] -[**-c** *cache_name*] -[**-n**] -[**-S** *service_name*] -[**-T** *armor_ccache*] -[**-X** *attribute*\ [=\ *value*]] -[*principal*] - - -DESCRIPTION ------------ - -kinit obtains and caches an initial ticket-granting ticket for -*principal*. - - -OPTIONS -------- - -**-V** - display verbose output. - -**-l** *lifetime* - (:ref:`duration` string.) Requests a ticket with the lifetime - *lifetime*. - - For example, ``kinit -l 5:30`` or ``kinit -l 5h30m``. - - If the **-l** option is not specified, the default ticket lifetime - (configured by each site) is used. Specifying a ticket lifetime - longer than the maximum ticket lifetime (configured by each site) - will not override the configured maximum ticket lifetime. - -**-s** *start_time* - (:ref:`duration` string.) Requests a postdated ticket. Postdated - tickets are issued with the **invalid** flag set, and need to be - resubmitted to the KDC for validation before use. - - *start_time* specifies the duration of the delay before the ticket - can become valid. - -**-r** *renewable_life* - (:ref:`duration` string.) Requests renewable tickets, with a total - lifetime of *renewable_life*. - -**-f** - requests forwardable tickets. - -**-F** - requests non-forwardable tickets. - -**-p** - requests proxiable tickets. - -**-P** - requests non-proxiable tickets. - -**-a** - requests tickets restricted to the host's local address[es]. - -**-A** - requests tickets not restricted by address. - -**-C** - requests canonicalization of the principal name, and allows the - KDC to reply with a different client principal from the one - requested. - -**-E** - treats the principal name as an enterprise name (implies the - **-C** option). - -**-v** - requests that the ticket-granting ticket in the cache (with the - **invalid** flag set) be passed to the KDC for validation. If the - ticket is within its requested time range, the cache is replaced - with the validated ticket. - -**-R** - requests renewal of the ticket-granting ticket. Note that an - expired ticket cannot be renewed, even if the ticket is still - within its renewable life. - -**-k** [**-i** | **-t** *keytab_file*] - requests a ticket, obtained from a key in the local host's keytab. - The location of the keytab may be specified with the **-t** - *keytab_file* option, or with the **-i** option to specify the use - of the default client keytab; otherwise the default keytab will be - used. By default, a host ticket for the local host is requested, - but any principal may be specified. On a KDC, the special keytab - location ``KDB:`` can be used to indicate that kinit should open - the KDC database and look up the key directly. This permits an - administrator to obtain tickets as any principal that supports - authentication based on the key. - -**-n** - Requests anonymous processing. Two types of anonymous principals - are supported. - - For fully anonymous Kerberos, configure pkinit on the KDC and - configure **pkinit_anchors** in the client's :ref:`krb5.conf(5)`. - Then use the **-n** option with a principal of the form ``@REALM`` - (an empty principal name followed by the at-sign and a realm - name). If permitted by the KDC, an anonymous ticket will be - returned. - - A second form of anonymous tickets is supported; these - realm-exposed tickets hide the identity of the client but not the - client's realm. For this mode, use ``kinit -n`` with a normal - principal name. If supported by the KDC, the principal (but not - realm) will be replaced by the anonymous principal. - - As of release 1.8, the MIT Kerberos KDC only supports fully - anonymous operation. - -**-T** *armor_ccache* - Specifies the name of a credentials cache that already contains a - ticket. If supported by the KDC, this cache will be used to armor - the request, preventing offline dictionary attacks and allowing - the use of additional preauthentication mechanisms. Armoring also - makes sure that the response from the KDC is not modified in - transit. - -**-c** *cache_name* - use *cache_name* as the Kerberos 5 credentials (ticket) cache - location. If this option is not used, the default cache location - is used. - - The default cache location may vary between systems. If the - **KRB5CCNAME** environment variable is set, its value is used to - locate the default cache. If a principal name is specified and - the type of the default cache supports a collection (such as the - DIR type), an existing cache containing credentials for the - principal is selected or a new one is created and becomes the new - primary cache. Otherwise, any existing contents of the default - cache are destroyed by kinit. - -**-S** *service_name* - specify an alternate service name to use when getting initial - tickets. - -**-X** *attribute*\ [=\ *value*] - specify a pre-authentication *attribute* and *value* to be - interpreted by pre-authentication modules. The acceptable - attribute and value values vary from module to module. This - option may be specified multiple times to specify multiple - attributes. If no value is specified, it is assumed to be "yes". - - The following attributes are recognized by the PKINIT - pre-authentication mechanism: - - **X509_user_identity**\ =\ *value* - specify where to find user's X509 identity information - - **X509_anchors**\ =\ *value* - specify where to find trusted X509 anchor information - - **flag_RSA_PROTOCOL**\ [**=yes**] - specify use of RSA, rather than the default Diffie-Hellman - protocol - - -ENVIRONMENT ------------ - -kinit uses the following environment variables: - -**KRB5CCNAME** - Location of the default Kerberos 5 credentials cache, in the form - *type*:*residual*. If no *type* prefix is present, the **FILE** - type is assumed. The type of the default cache may determine the - availability of a cache collection; for instance, a default cache - of type **DIR** causes caches within the directory to be present - in the collection. - - -FILES ------ - -|ccache| - default location of Kerberos 5 credentials cache - -|keytab| - default location for the local host's keytab. - - -SEE ALSO --------- - -:ref:`klist(1)`, :ref:`kdestroy(1)`, kerberos(1) diff --git a/doc/rst_source/krb_users/user_commands/klist.rst b/doc/rst_source/krb_users/user_commands/klist.rst deleted file mode 100644 index d303f34d8..000000000 --- a/doc/rst_source/krb_users/user_commands/klist.rst +++ /dev/null @@ -1,135 +0,0 @@ -.. _klist(1): - -klist -===== - -SYNOPSIS --------- - -**klist** -[**-e**] -[[**-c**] [**-l**] [**-A**] [**-f**] [**-s**] [**-a** [**-n**]]] -[**-C**] -[**-k** [**-t**] [**-K**]] -[**-V**] -[*cache_name*\|\ *keytab_name*] - - -DESCRIPTION ------------ - -klist lists the Kerberos principal and Kerberos tickets held in a -credentials cache, or the keys held in a keytab file. - - -OPTIONS -------- - -**-e** - Displays the encryption types of the session key and the ticket - for each credential in the credential cache, or each key in the - keytab file. - -**-l** - If a cache collection is available, displays a table summarizing - the caches present in the collection. - -**-A** - If a cache collection is available, displays the contents of all - of the caches in the collection. - -**-c** - List tickets held in a credentials cache. This is the default if - neither **-c** nor **-k** is specified. - -**-f** - Shows the flags present in the credentials, using the following - abbreviations: - - :: - - F Forwardable - f forwarded - P Proxiable - p proxy - D postDateable - d postdated - R Renewable - I Initial - i invalid - H Hardware authenticated - A preAuthenticated - T Transit policy checked - O Okay as delegate - a anonymous - -**-s** - Causes klist to run silently (produce no output), but to still set - the exit status according to whether it finds the credentials - cache. The exit status is '0' if klist finds a credentials cache, - and '1' if it does not or if the tickets are expired. - -**-a** - Display list of addresses in credentials. - -**-n** - Show numeric addresses instead of reverse-resolving addresses. - -**-C** - List configuration data that has been stored in the credentials - cache when klist encounters it. By default, configuration data - is not listed. - -**-k** - List keys held in a keytab file. - -**-i** - In combination with **-k**, defaults to using the default client - keytab instead of the default acceptor keytab, if no name is - given. - -**-t** - Display the time entry timestamps for each keytab entry in the - keytab file. - -**-K** - Display the value of the encryption key in each keytab entry in - the keytab file. - -**-V** - Display the Kerberos version number and exit. - -If *cache_name* or *keytab_name* is not specified, klist will display -the credentials in the default credentials cache or keytab file as -appropriate. If the **KRB5CCNAME** environment variable is set, its -value is used to locate the default ticket cache. - - -ENVIRONMENT ------------ - -klist uses the following environment variable: - -**KRB5CCNAME** - Location of the default Kerberos 5 credentials (ticket) cache, in - the form *type*:*residual*. If no *type* prefix is present, the - **FILE** type is assumed. The type of the default cache may - determine the availability of a cache collection; for instance, a - default cache of type **DIR** causes caches within the directory - to be present in the collection. - - -FILES ------ - -|ccache| - Default location of Kerberos 5 credentials cache - -|keytab| - Default location for the local host's keytab file. - - -SEE ALSO --------- - -:ref:`kinit(1)`, :ref:`kdestroy(1)` diff --git a/doc/rst_source/krb_users/user_commands/kpasswd.rst b/doc/rst_source/krb_users/user_commands/kpasswd.rst deleted file mode 100644 index 1b6463265..000000000 --- a/doc/rst_source/krb_users/user_commands/kpasswd.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. _kpasswd(1): - -kpasswd -======= - -SYNOPSIS --------- - -**kpasswd** [*principal*] - - -DESCRIPTION ------------ - -The kpasswd command is used to change a Kerberos principal's password. -kpasswd first prompts for the current Kerberos password, then prompts -the user twice for the new password, and the password is changed. - -If the principal is governed by a policy that specifies the length -and/or number of character classes required in the new password, the -new password must conform to the policy. (The five character classes -are lower case, upper case, numbers, punctuation, and all other -characters.) - - -OPTIONS -------- - -*principal* - Change the password for the Kerberos principal principal. - Otherwise, kpasswd uses the principal name from an existing ccache - if there is one; if not, the principal is derived from the - identity of the user invoking the kpasswd command. - - -SEE ALSO --------- - -:ref:`kadmin(1)`, :ref:`kadmind(8)` diff --git a/doc/rst_source/krb_users/user_commands/ksu.rst b/doc/rst_source/krb_users/user_commands/ksu.rst deleted file mode 100644 index aa22c18a3..000000000 --- a/doc/rst_source/krb_users/user_commands/ksu.rst +++ /dev/null @@ -1,397 +0,0 @@ -.. _ksu(1): - -ksu -=== - -SYNOPSIS --------- - -**ksu** -[ *target_user* ] -[ **-n** *target_principal_name* ] -[ **-c** *source_cache_name* ] -[ **-k** ] -[ **-D** ] -[ **-r** time ] -[ **-pf** ] -[ **-l** *lifetime* ] -[ **-z | Z** ] -[ **-q** ] -[ **-e** *command* [ args ... ] ] [ **-a** [ args ... ] ] - - -REQUIREMENTS ------------- - -Must have Kerberos version 5 installed to compile ksu. Must have a -Kerberos version 5 server running to use ksu. - - -DESCRIPTION ------------ - -ksu is a Kerberized version of the su program that has two missions: -one is to securely change the real and effective user ID to that of -the target user, and the other is to create a new security context. - -.. note:: For the sake of clarity, all references to and attributes of - the user invoking the program will start with "source" - (e.g., "source user", "source cache", etc.). - - Likewise, all references to and attributes of the target - account will start with "target". - -AUTHENTICATION --------------- - -To fulfill the first mission, ksu operates in two phases: -authentication and authorization. Resolving the target principal name -is the first step in authentication. The user can either specify his -principal name with the **-n** option (e.g., ``-n jqpublic@USC.EDU``) -or a default principal name will be assigned using a heuristic -described in the OPTIONS section (see **-n** option). The target user -name must be the first argument to ksu; if not specified root is the -default. If ``.`` is specified then the target user will be the -source user (e.g., ``ksu .``). If the source user is root or the -target user is the source user, no authentication or authorization -takes place. Otherwise, ksu looks for an appropriate Kerberos ticket -in the source cache. - -The ticket can either be for the end-server or a ticket granting -ticket (TGT) for the target principal's realm. If the ticket for the -end-server is already in the cache, it's decrypted and verified. If -it's not in the cache but the TGT is, the TGT is used to obtain the -ticket for the end-server. The end-server ticket is then verified. -If neither ticket is in the cache, but ksu is compiled with the -**GET_TGT_VIA_PASSWD** define, the user will be prompted for a -Kerberos password which will then be used to get a TGT. If the user -is logged in remotely and does not have a secure channel, the password -may be exposed. If neither ticket is in the cache and -**GET_TGT_VIA_PASSWD** is not defined, authentication fails. - - -AUTHORIZATION -------------- - -This section describes authorization of the source user when ksu is -invoked without the **-e** option. For a description of the **-e** -option, see the OPTIONS section. - -Upon successful authentication, ksu checks whether the target -principal is authorized to access the target account. In the target -user's home directory, ksu attempts to access two authorization files: -:ref:`.k5login(5)` and .k5users. In the .k5login file each line -contains the name of a principal that is authorized to access the -account. - -For example: - :: - - jqpublic@USC.EDU - jqpublic/secure@USC.EDU - jqpublic/admin@USC.EDU - -The format of .k5users is the same, except the principal name may be -followed by a list of commands that the principal is authorized to -execute (see the **-e** option in the OPTIONS section for details). - -Thus if the target principal name is found in the .k5login file the -source user is authorized to access the target account. Otherwise ksu -looks in the .k5users file. If the target principal name is found -without any trailing commands or followed only by ``*`` then the -source user is authorized. If either .k5login or .k5users exist but -an appropriate entry for the target principal does not exist then -access is denied. If neither file exists then the principal will be -granted access to the account according to the aname->lname mapping -rules. Otherwise, authorization fails. - - -EXECUTION OF THE TARGET SHELL ------------------------------ - -Upon successful authentication and authorization, ksu proceeds in a -similar fashion to su. The environment is unmodified with the -exception of USER, HOME and SHELL variables. If the target user is -not root, USER gets set to the target user name. Otherwise USER -remains unchanged. Both HOME and SHELL are set to the target login's -default values. In addition, the environment variable **KRB5CCNAME** -gets set to the name of the target cache. The real and effective user -ID are changed to that of the target user. The target user's shell is -then invoked (the shell name is specified in the password file). Upon -termination of the shell, ksu deletes the target cache (unless ksu is -invoked with the **-k** option). This is implemented by first doing a -fork and then an exec, instead of just exec, as done by su. - - -CREATING A NEW SECURITY CONTEXT -------------------------------- - -ksu can be used to create a new security context for the target -program (either the target shell, or command specified via the **-e** -option). The target program inherits a set of credentials from the -source user. By default, this set includes all of the credentials in -the source cache plus any additional credentials obtained during -authentication. The source user is able to limit the credentials in -this set by using **-z** or **-Z** option. **-z** restricts the copy -of tickets from the source cache to the target cache to only the -tickets where client == the target principal name. The **-Z** option -provides the target user with a fresh target cache (no creds in the -cache). Note that for security reasons, when the source user is root -and target user is non-root, **-z** option is the default mode of -operation. - -While no authentication takes place if the source user is root or is -the same as the target user, additional tickets can still be obtained -for the target cache. If **-n** is specified and no credentials can -be copied to the target cache, the source user is prompted for a -Kerberos password (unless **-Z** specified or **GET_TGT_VIA_PASSWD** -is undefined). If successful, a TGT is obtained from the Kerberos -server and stored in the target cache. Otherwise, if a password is -not provided (user hit return) ksu continues in a normal mode of -operation (the target cache will not contain the desired TGT). If the -wrong password is typed in, ksu fails. - -.. note:: During authentication, only the tickets that could be - obtained without providing a password are cached in in the - source cache. - - -OPTIONS -------- - -**-n** *target_principal_name* - Specify a Kerberos target principal name. Used in authentication - and authorization phases of ksu. - - If ksu is invoked without **-n**, a default principal name is - assigned via the following heuristic: - - * Case 1: source user is non-root. - - If the target user is the source user the default principal name - is set to the default principal of the source cache. If the - cache does not exist then the default principal name is set to - ``target_user@local_realm``. If the source and target users are - different and neither ``~target_user/.k5users`` nor - ``~target_user/.k5login`` exist then the default principal name - is ``target_user_login_name@local_realm``. Otherwise, starting - with the first principal listed below, ksu checks if the - principal is authorized to access the target account and whether - there is a legitimate ticket for that principal in the source - cache. If both conditions are met that principal becomes the - default target principal, otherwise go to the next principal. - - a) default principal of the source cache - b) target_user\@local_realm - c) source_user\@local_realm - - If a-c fails try any principal for which there is a ticket in - the source cache and that is authorized to access the target - account. If that fails select the first principal that is - authorized to access the target account from the above list. If - none are authorized and ksu is configured with - **PRINC_LOOK_AHEAD** turned on, select the default principal as - follows: - - For each candidate in the above list, select an authorized - principal that has the same realm name and first part of the - principal name equal to the prefix of the candidate. For - example if candidate a) is ``jqpublic@ISI.EDU`` and - ``jqpublic/secure@ISI.EDU`` is authorized to access the target - account then the default principal is set to - ``jqpublic/secure@ISI.EDU``. - - * Case 2: source user is root. - - If the target user is non-root then the default principal name - is ``target_user@local_realm``. Else, if the source cache - exists the default principal name is set to the default - principal of the source cache. If the source cache does not - exist, default principal name is set to ``root\@local_realm``. - -**-c** *source_cache_name* - - Specify source cache name (e.g., ``-c FILE:/tmp/my_cache``). If - **-c** option is not used then the name is obtained from - **KRB5CCNAME** environment variable. If **KRB5CCNAME** is not - defined the source cache name is set to ``krb5cc_``. - The target cache name is automatically set to ``krb5cc_.(gen_sym())``, where gen_sym generates a new number such that - the resulting cache does not already exist. For example: - - :: - - krb5cc_1984.2 - -**-k** - Do not delete the target cache upon termination of the target - shell or a command (**-e** command). Without **-k**, ksu deletes - the target cache. - -**-D** - Turn on debug mode. - -**-z** - Restrict the copy of tickets from the source cache to the target - cache to only the tickets where client == the target principal - name. Use the **-n** option if you want the tickets for other then - the default principal. Note that the **-z** option is mutually - exclusive with the **-Z** option. - -**-Z** - Don't copy any tickets from the source cache to the target cache. - Just create a fresh target cache, where the default principal name - of the cache is initialized to the target principal name. Note - that the **-Z** option is mutually exclusive with the **-z** - option. - -**-q** - Suppress the printing of status messages. - -Ticket granting ticket options: - -**-l** *lifetime* **-r** *time* **-pf** - The ticket granting ticket options only apply to the case where - there are no appropriate tickets in the cache to authenticate the - source user. In this case if ksu is configured to prompt users - for a Kerberos password (**GET_TGT_VIA_PASSWD** is defined), the - ticket granting ticket options that are specified will be used - when getting a ticket granting ticket from the Kerberos server. - -**-l** *lifetime* - (:ref:`duration` string.) Specifies the lifetime to be requested - for the ticket; if this option is not specified, the default ticket - lifetime (12 hours) is used instead. - -**-r** *time* - (:ref:`duration` string.) Specifies that the **renewable** option - should be requested for the ticket, and specifies the desired - total lifetime of the ticket. - -**-p** - specifies that the **proxiable** option should be requested for - the ticket. - -**-f** - option specifies that the **forwardable** option should be - requested for the ticket. - -**-e** *command* [*args* ...] - ksu proceeds exactly the same as if it was invoked without the - **-e** option, except instead of executing the target shell, ksu - executes the specified command. Example of usage: - - :: - - ksu bob -e ls -lag - - The authorization algorithm for **-e** is as follows: - - If the source user is root or source user == target user, no - authorization takes place and the command is executed. If source - user id != 0, and ``~target_user/.k5users`` file does not exist, - authorization fails. Otherwise, ``~target_user/.k5users`` file - must have an appropriate entry for target principal to get - authorized. - - The .k5users file format: - - A single principal entry on each line that may be followed by a - list of commands that the principal is authorized to execute. A - principal name followed by a ``*`` means that the user is - authorized to execute any command. Thus, in the following - example: - - :: - - jqpublic@USC.EDU ls mail /local/kerberos/klist - jqpublic/secure@USC.EDU * - jqpublic/admin@USC.EDU - - ``jqpublic@USC.EDU`` is only authorized to execute ``ls``, - ``mail`` and ``klist`` commands. ``jqpublic/secure@USC.EDU`` is - authorized to execute any command. ``jqpublic/admin@USC.EDU`` is - not authorized to execute any command. Note, that - ``jqpublic/admin@USC.EDU`` is authorized to execute the target - shell (regular ksu, without the **-e** option) but - ``jqpublic@USC.EDU`` is not. - - The commands listed after the principal name must be either a full - path names or just the program name. In the second case, - **CMD_PATH** specifying the location of authorized programs must - be defined at the compilation time of ksu. Which command gets - executed? - - If the source user is root or the target user is the source user - or the user is authorized to execute any command (``*`` entry) - then command can be either a full or a relative path leading to - the target program. Otherwise, the user must specify either a - full path or just the program name. - -**-a** *args* - Specify arguments to be passed to the target shell. Note that all - flags and parameters following -a will be passed to the shell, - thus all options intended for ksu must precede **-a**. - - The **-a** option can be used to simulate the **-e** option if - used as follows: - - :: - - -a -c [command [arguments]]. - - **-c** is interpreted by the c-shell to execute the command. - - -INSTALLATION INSTRUCTIONS -------------------------- - -ksu can be compiled with the following four flags: - -**GET_TGT_VIA_PASSWD** - In case no appropriate tickets are found in the source cache, the - user will be prompted for a Kerberos password. The password is - then used to get a ticket granting ticket from the Kerberos - server. The danger of configuring ksu with this macro is if the - source user is logged in remotely and does not have a secure - channel, the password may get exposed. - -**PRINC_LOOK_AHEAD** - During the resolution of the default principal name, - **PRINC_LOOK_AHEAD** enables ksu to find principal names in - the .k5users file as described in the OPTIONS section - (see **-n** option). - -**CMD_PATH** - Specifies a list of directories containing programs that users are - authorized to execute (via .k5users file). - -**HAVE_GETUSERSHELL** - If the source user is non-root, ksu insists that the target user's - shell to be invoked is a "legal shell". *getusershell(3)* is - called to obtain the names of "legal shells". Note that the - target user's shell is obtained from the passwd file. - -Sample configuration: - :: - - KSU_OPTS = -DGET_TGT_VIA_PASSWD -DPRINC_LOOK_AHEAD -DCMD_PATH='"/bin /usr/ucb /local/bin" - -ksu should be owned by root and have the set user id bit turned on. - -ksu attempts to get a ticket for the end server just as Kerberized -telnet and rlogin. Thus, there must be an entry for the server in the -Kerberos database (e.g., ``host/nii.isi.edu@ISI.EDU``). The keytab -file must be in an appropriate location. - - -SIDE EFFECTS ------------- - -ksu deletes all expired tickets from the source cache. - - -AUTHOR OF KSU -------------- - -GENNADY (ARI) MEDVINSKY diff --git a/doc/rst_source/krb_users/user_commands/kswitch.rst b/doc/rst_source/krb_users/user_commands/kswitch.rst deleted file mode 100644 index 261660dad..000000000 --- a/doc/rst_source/krb_users/user_commands/kswitch.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. _kswitch(1): - -kswitch -======= - -SYNOPSIS -~~~~~~~~ - -**kswitch** -{**-c** *cachename*\|\ **-p** *principal*} - - -DESCRIPTION ------------ - -kswitch makes the specified credential cache the primary cache for the -collection, if a cache collection is available. - - -OPTIONS -------- - -**-c** *cachename* - Directly specifies the credential cache to be made primary. - -**-p** *principal* - Causes the cache collection to be searched for a cache containing - credentials for *principal*. If one is found, that collection is - made primary. - - -ENVIRONMENT ------------ - -kswitch uses the following environment variables: - -**KRB5CCNAME** - Location of the default Kerberos 5 credentials (ticket) cache, in - the form *type*:*residual*. If no *type* prefix is present, the - **FILE** type is assumed. The type of the default cache may - determine the availability of a cache collection; for instance, a - default cache of type **DIR** causes caches within the directory - to be present in the collection. - - -FILES ------ - -|ccache| - Default location of Kerberos 5 credentials cache - - -SEE ALSO --------- - -:ref:`kinit(1)`, :ref:`kdestroy(1)`, :ref:`klist(1)`), kerberos(1) diff --git a/doc/rst_source/krb_users/user_commands/kvno.rst b/doc/rst_source/krb_users/user_commands/kvno.rst deleted file mode 100644 index 31ca24460..000000000 --- a/doc/rst_source/krb_users/user_commands/kvno.rst +++ /dev/null @@ -1,86 +0,0 @@ -.. _kvno(1): - -kvno -==== - -SYNOPSIS --------- - -**kvno** -[**-c** *ccache*] -[**-e** *etype*] -[**-q**] -[**-h**] -[**-P**] -[**-S** *sname*] -[**-U** *for_user*] -*service1 service2* ... - - -DESCRIPTION ------------ - -kvno acquires a service ticket for the specified Kerberos principals -and prints out the key version numbers of each. - - -OPTIONS -------- - -**-c** *ccache* - Specifies the name of a credentials cache to use (if not the - default) - -**-e** *etype* - Specifies the enctype which will be requested for the session key - of all the services named on the command line. This is useful in - certain backward compatibility situations. - -**-q** - Suppress printing output when successful. If a service ticket - cannot be obtained, an error message will still be printed and - kvno will exit with nonzero status. - -**-h** - Prints a usage statement and exits. - -**-P** - Specifies that the *service1 service2* ... arguments are to be - treated as services for which credentials should be acquired using - constrained delegation. This option is only valid when used in - conjunction with protocol transition. - -**-S** *sname* - Specifies that the *service1 service2* ... arguments are - interpreted as hostnames, and the service principals are to be - constructed from those hostnames and the service name *sname*. - The service hostnames will be canonicalized according to the usual - rules for constructing service principals. - -**-U** *for_user* - Specifies that protocol transition (S4U2Self) is to be used to - acquire a ticket on behalf of *for_user*. If constrained - delegation is not requested, the service name must match the - credentials cache client principal. - - -ENVIRONMENT ------------ - -kvno uses the following environment variable: - -**KRB5CCNAME** - Location of the credentials (ticket) cache. - - -FILES ------ - -|ccache| - Default location of the credentials cache - - -SEE ALSO --------- - -:ref:`kinit(1)`, :ref:`kdestroy(1)` diff --git a/doc/rst_source/krb_users/user_commands/sclient.rst b/doc/rst_source/krb_users/user_commands/sclient.rst deleted file mode 100644 index ebf797253..000000000 --- a/doc/rst_source/krb_users/user_commands/sclient.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. _sclient(1): - -sclient -======= - -SYNOPSIS --------- - -**sclient** *remotehost* - - -DESCRIPTION ------------ - -sclient is a sample application, primarily useful for testing -purposes. It contacts a sample server :ref:`sserver(8)` and -authenticates to it using Kerberos version 5 tickets, then displays -the server's response. - - -SEE ALSO --------- - -:ref:`kinit(1)`, :ref:`sserver(8)` diff --git a/doc/rst_source/krb_users/user_config/index.rst b/doc/rst_source/krb_users/user_config/index.rst deleted file mode 100644 index 6b3d4393b..000000000 --- a/doc/rst_source/krb_users/user_config/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -User config files -================= - -The following files in your home directory can be used to control the -behavior of Kerberos as it applies to your account (unless they have -been disabled by your host's configuration): - -.. toctree:: - :maxdepth: 1 - - k5login.rst - k5identity.rst diff --git a/doc/rst_source/krb_users/user_config/k5identity.rst b/doc/rst_source/krb_users/user_config/k5identity.rst deleted file mode 100644 index 21c340eab..000000000 --- a/doc/rst_source/krb_users/user_config/k5identity.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. _.k5identity(5): - -.k5identity -=========== - -DESCRIPTION ------------ - -The .k5identity file, which resides in a user's home directory, -contains a list of rules for selecting a client principals based on -the server being accessed. These rules are used to choose a -credential cache within the cache collection when possible. - -Blank lines and lines beginning with ``#`` are ignored. Each line has -the form: - - *principal* *field*\=\ *value* ... - -If the server principal meets all of the field constraints, then -principal is chosen as the client principal. The following fields are -recognized: - -**realm** - If the realm of the server principal is known, it is matched - against *value*, which may be a pattern using shell wildcards. - For host-based server principals, the realm will generally only be - known if there is a :ref:`domain_realm` section in - :ref:`krb5.conf(5)` with a mapping for the hostname. - -**service** - If the server principal is a host-based principal, its service - component is matched against *value*, which may be a pattern using - shell wildcards. - -**host** - If the server principal is a host-based principal, its hostname - component is converted to lower case and matched against *value*, - which may be a pattern using shell wildcards. - - If the server principal matches the constraints of multiple lines - in the .k5identity file, the principal from the first matching - line is used. If no line matches, credentials will be selected - some other way, such as the realm heuristic or the current primary - cache. - - -EXAMPLE -------- - -The following example .k5identity file selects the client principal -``alice@KRBTEST.COM`` if the server principal is within that realm, -the principal ``alice/root@EXAMPLE.COM`` if the server host is within -a servers subdomain, and the principal ``alice/mail@EXAMPLE.COM`` when -accessing the IMAP service on ``mail.example.com``: - - :: - - alice@KRBTEST.COM realm=KRBTEST.COM - alice/root@EXAMPLE.COM host=*.servers.example.com - alice/mail@EXAMPLE.COM host=mail.example.com service=imap - - -SEE ALSO --------- - -kerberos(1), :ref:`krb5.conf(5)` diff --git a/doc/rst_source/krb_users/user_config/k5login.rst b/doc/rst_source/krb_users/user_config/k5login.rst deleted file mode 100644 index 00f5a5a3a..000000000 --- a/doc/rst_source/krb_users/user_config/k5login.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. _.k5login(5): - -.k5login -======== - -DESCRIPTION ------------ - -The .k5login file, which resides in a user's home directory, contains -a list of the Kerberos principals. Anyone with valid tickets for a -principal in the file is allowed host access with the UID of the user -in whose home directory the file resides. One common use is to place -a .k5login file in root's home directory, thereby granting system -administrators remote root access to the host via Kerberos. - - -EXAMPLES --------- - -Suppose the user ``alice`` had a .k5login file in her home directory -containing the following line: - - :: - - bob@FOOBAR.ORG - -This would allow ``bob`` to use Kerberos network applications, such as -ssh(1), to access ``alice``'s account, using ``bob``'s Kerberos -tickets. - -Let us further suppose that ``alice`` is a system administrator. -Alice and the other system administrators would have their principals -in root's .k5login file on each host: - - :: - - alice@BLEEP.COM - - joeadmin/root@BLEEP.COM - -This would allow either system administrator to log in to these hosts -using their Kerberos tickets instead of having to type the root -password. Note that because ``bob`` retains the Kerberos tickets for -his own principal, ``bob@FOOBAR.ORG``, he would not have any of the -privileges that require ``alice``'s tickets, such as root access to -any of the site's hosts, or the ability to change ``alice``'s -password. - - -SEE ALSO --------- - -kerberos(1) diff --git a/doc/rst_source/mitK5defaults.rst b/doc/rst_source/mitK5defaults.rst deleted file mode 100644 index 84b9df881..000000000 --- a/doc/rst_source/mitK5defaults.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. _mitK5defaults: - -MIT Kerberos defaults -===================== - -General defaults ----------------- - -========================================== ============================= ==================== -Description Default Environment -========================================== ============================= ==================== -:ref:`keytab_definition` file |keytab| **KRB5_KTNAME** -Client :ref:`keytab_definition` file |ckeytab| **KRB5_CLIENT_KTNAME** -Kerberos config file :ref:`krb5.conf(5)` |krb5conf|\ ``:``\ **KRB5_CONFIG** - |sysconfdir|\ ``/krb5.conf`` -KDC config file :ref:`kdc.conf(5)` |kdcdir|\ ``/kdc.conf`` **KRB5_KDC_PROFILE** -KDC database path (DB2) |kdcdir|\ ``/principal`` -Master key :ref:`stash_definition` |kdcdir|\ ``/.k5.``\ *realm* -Admin server ACL file :ref:`kadm5.acl(5)` |kdcdir|\ ``/kadm5.acl`` -Plugin base directory |libdir|\ ``/krb5/plugins`` -:ref:`rcache_definition` directory ``/var/tmp`` **KRB5RCACHEDIR** -Master key default enctype |defmkey| -Supported :ref:`Encryption_and_salt_types` |defkeysalts| -Permitted enctypes |defetypes| -KDC default port 88 -Second KDC default port 750 -Admin server port 749 -Password change port 464 -========================================== ============================= ==================== - - -Slave KDC propagation defaults ------------------------------- - -This table shows defaults used by the :ref:`kprop(8)` and -:ref:`kpropd(8)` programs. - -========================== ============================== =========== -Description Default Environment -========================== ============================== =========== -kprop database dump file |kdcdir|\ ``/slave_datatrans`` -kpropd temporary dump file |kdcdir|\ ``/from_master`` -kdb5_util location |sbindir|\ ``/kdb5_util`` -kprop location |sbindir|\ ``/kprop`` -kpropd ACL file |kdcdir|\ ``/kpropd.acl`` -kprop port 754 KPROP_PORT -========================== ============================== =========== - - -.. _paths: - -Default paths for Unix-like systems ------------------------------------ - -On Unix-like systems, some paths used by MIT krb5 depend on parameters -chosen at build time. For a custom build, these paths default to -subdirectories of ``/usr/local``. When MIT krb5 is integrated into an -operating system, the paths are generally chosen to match the -operating system's filesystem layout. - -========================== ============= =========================== =========================== -Description Symbolic name Custom build path Typical OS path -========================== ============= =========================== =========================== -User programs BINDIR ``/usr/local/bin`` ``/usr/bin`` -Libraries and plugins LIBDIR ``/usr/local/lib`` ``/usr/lib`` -Parent of KDC state dir LOCALSTATEDIR ``/usr/local/var`` ``/var`` -Administrative programs SBINDIR ``/usr/local/sbin`` ``/usr/sbin`` -Alternate krb5.conf dir SYSCONFDIR ``/usr/local/etc`` ``/etc`` -Default ccache name DEFCCNAME ``FILE:/tmp/krb5cc_%{uid}`` ``FILE:/tmp/krb5cc_%{uid}`` -Default keytab name DEFKTNAME ``FILE:/etc/krb5.keytab`` ``FILE:/etc/krb5.keytab`` -========================== ============= =========================== =========================== - -The default client keytab name (DEFCKTNAME) typically defaults to -``FILE:/usr/local/var/krb5/user/%{euid}/client.keytab`` for a custom -build. A native build will typically use a path which will vary -according to the operating system's layout of ``/var``. diff --git a/doc/rst_source/mitK5features.rst b/doc/rst_source/mitK5features.rst deleted file mode 100644 index db79066bc..000000000 --- a/doc/rst_source/mitK5features.rst +++ /dev/null @@ -1,140 +0,0 @@ -.. highlight:: rst - -.. _mitK5features: - -MIT Kerberos Features -===================== - -http://web.mit.edu/kerberos - - -Quick facts ------------ - - ====================================================== ======================================= ============================================================================= - Latest stable version 1.10.3 http://web.mit.edu/kerberos/krb5-1.10/ - Supported versions 1.9.4, 1.10.3 http://web.mit.edu/kerberos/krb5-1.9/ - Release cycle 9 - 12 months - Supported platforms/OS distributions Solaris - - SPARC - - x86_64/x86 - GNU/Linux - - Debian x86_64/x86 - - Ubuntu x86_64/x86 - - RedHat x86_64/x86 - BSD - - NetBSD x86_64/x86 - Crypto backends - OpenSSL 1.0\+ - http://www.openssl.org - - builtin - MIT Kerberos native crypto library - - NSS 3.12.9\+ - Mozilla's Network Security Services. - http://www.mozilla.org/projects/security/pki/nss - Database backends - LDAP - - DB2 - krb4 support < 1.8 - DES support configurable http://k5wiki.kerberos.org/wiki/Projects/Disable_DES - GSS-API S4U extensions 1.8+ http://msdn.microsoft.com/en-us/library/cc246071 - - S4U2Self - - S4U2Proxy - GSS-API naming extensions 1.8+ http://tools.ietf.org/html/draft-ietf-kitten-gssapi-naming-exts-11 - - GSS-API extensions for storing delegated credentials 1.8+ :rfc:`5588` - - License :ref:`mitK5license` - ====================================================== ======================================= ============================================================================= - - -Interoperabiity ---------------- - -Microsoft -~~~~~~~~~ - -Starting from version 1.7: - -* Follow client principal referrals in the client library when - obtaining initial tickets. - -* KDC can issue realm referrals for service principals based on domain names. - -* Extensions supporting DCE RPC, including three-leg GSS context setup - and unencapsulated GSS tokens inside SPNEGO. - -* Microsoft GSS_WrapEX, implemented using the gss_iov API, which is - similar to the equivalent SSPI functionality. This is needed to - support some instances of DCE RPC. - -* NTLM recognition support in GSS-API, to facilitate dropping in an - NTLM implementation for improved compatibility with older releases - of Microsoft Windows. - -* KDC support for principal aliases, if the back end supports them. - Currently, only the LDAP back end supports aliases. - -* Support Microsoft set/change password (RFC 3244) protocol in - kadmind. - -* Implement client and KDC support for GSS_C_DELEG_POLICY_FLAG, which - allows a GSS application to request credential delegation only if - permitted by KDC policy. - - -Starting from version 1.8: - -* Microsoft Services for User (S4U) compatibility` - - -Heimdal -~~~~~~~ - -* Support for reading Heimdal database starting from version 1.8 - - -Feature list ------------- - - =============================================== =========== ============================================ - \ Available Additional information - =============================================== =========== ============================================ - Credentials delegation 1.7 :rfc:`5896` - Cross-realm authentication and referrals 1.7 http://tools.ietf.org/html/draft-ietf-krb-wg-kerberos-referrals-12 - Master key migration 1.7 http://k5wiki.kerberos.org/wiki/Projects/Master_Key_Migration - PKINIT 1.7 :rfc:`4556` - Anonymous PKINIT 1.8 :rfc:`6112` http://k5wiki.kerberos.org/wiki/Projects/Anonymous_pkinit - Constrained delegation 1.8 http://k5wiki.kerberos.org/wiki/Projects/ConstrainedDelegation - IAKERB 1.8 http://tools.ietf.org/html/draft-ietf-krb-wg-iakerb-02 - Heimdal bridge plugin for KDC backend 1.8 - Advance warning on password expiry 1.9 - Camellia encryption (CTS-CMAC mode) 1.9 experimental http://tools.ietf.org/html/draft-ietf-krb-wg-camellia-cts-00 - KDC support for SecurID preauthentication 1.9 http://k5wiki.kerberos.org/wiki/Projects/SecurID_SAM_support - kadmin over IPv6 1.9 - Trace logging 1.9 http://k5wiki.kerberos.org/wiki/Projects/Trace_logging - GSSAPI/KRB5 multi-realm support - Plugin to test password quality 1.9 http://k5wiki.kerberos.org/wiki/Projects/Password_quality_pluggable_interface - Plugin to synchronize password changes 1.9 - Parallel KDC 1.9 - GS2 1.9 :rfc:`5801` :rfc:`5587` http://k5wiki.kerberos.org/wiki/Projects/GS2 - Purging old keys 1.9 - Naming extensions for delegation chain 1.9 - Password expiration API 1.9 - Windows client support (build-only) 1.9 - pre-auth mechanisms: - - PW-SALT :rfc:`4120#section-5.2.7.3` - - ENC-TIMESTAMP :rfc:`4120#section-5.2.7.2` - - SAM-2 - - FAST negotiation framework 1.8 :rfc:`6113` - - PKINIT with FAST on client 1.10 :rfc:`6113` - - PKINIT :rfc:`4556` - - FX-COOKIE :rfc:`6113#section-5.2` - - S4U-X509-USER 1.8 http://msdn.microsoft.com/en-us/library/cc246091 - - PRNG - - modularity: 1.9 - - Yarrow PRNG < 1.10 - - Fortuna PRNG 1.9 http://www.schneier.com/book-practical.html - - OS PRNG 1.10 OS's native PRNG - Zero configuration - IPv6 support in iprop - Plugin interface for configuration 1.10 http://k5wiki.kerberos.org/wiki/Projects/Pluggable_configuration - Credentials for multiple identities 1.10 http://k5wiki.kerberos.org/wiki/Projects/Client_principal_selection - =============================================== =========== ============================================ - diff --git a/doc/rst_source/mitK5license.rst b/doc/rst_source/mitK5license.rst deleted file mode 100644 index 6b837b90f..000000000 --- a/doc/rst_source/mitK5license.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _mitK5license: - -MIT Kerberos License information -================================ - -.. include:: notice.rst diff --git a/doc/rst_source/notice.rst b/doc/rst_source/notice.rst deleted file mode 100644 index 9fe8f7957..000000000 --- a/doc/rst_source/notice.rst +++ /dev/null @@ -1,1124 +0,0 @@ -.. include:: - -Copyright |copy| 1985-2012 by the Massachusetts Institute of Technology. - -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - -1. Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. -2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -Downloading of this software may constitute an export of cryptographic -software from the United States of America that is subject to the -United States Export Administration Regulations (EAR), 15 CFR 730-774. -Additional laws or regulations may apply. It is the responsibility of -the person or entity contemplating export to comply with all -applicable export laws and regulations, including obtaining any -required license from the U.S. government. - -The U.S. government prohibits export of encryption source code to -certain countries and individuals, including, but not limited to, the -countries of Cuba, Iran, North Korea, Sudan, Syria, and residents and -nationals of those countries. - -Documentation components of this software distribution are licensed -under a Creative Commons Attribution-ShareAlike 3.0 Unported License. -(http://creativecommons.org/licenses/by-sa/3.0/) - -Individual source code files are copyright MIT, Cygnus Support, -Novell, OpenVision Technologies, Oracle, Red Hat, Sun Microsystems, -FundsXpress, and others. - -Project Athena, Athena, Athena MUSE, Discuss, Hesiod, Kerberos, Moira, -and Zephyr are trademarks of the Massachusetts Institute of Technology -(MIT). No commercial use of these trademarks may be made without -prior written permission of MIT. - -"Commercial use" means use of a name in a product or other for-profit -manner. It does NOT prevent a commercial firm from referring to the -MIT trademarks in order to convey information (although in doing so, -recognition of their trademark status should be given). - -------------------- - -The following copyright and permission notice applies to the -OpenVision Kerberos Administration system located in -``kadmin/create``, ``kadmin/dbutil``, ``kadmin/passwd``, -``kadmin/server``, ``lib/kadm5``, and portions of -``lib/rpc``: - - Copyright, OpenVision Technologies, Inc., 1993-1996, All Rights Reserved - - WARNING: Retrieving the OpenVision Kerberos Administration system source - code, as described below, indicates your acceptance of the following - terms. If you do not agree to the following terms, do not retrieve the - OpenVision Kerberos administration system. - - You may freely use and distribute the Source Code and Object Code - compiled from it, with or without modification, but this Source Code is - provided to you "AS IS" EXCLUSIVE OF ANY WARRANTY, INCLUDING, WITHOUT - LIMITATION, ANY WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A - PARTICULAR PURPOSE, OR ANY OTHER WARRANTY, WHETHER EXPRESS OR IMPLIED. - IN NO EVENT WILL OPENVISION HAVE ANY LIABILITY FOR ANY LOST PROFITS, - LOSS OF DATA OR COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR - FOR ANY SPECIAL, INDIRECT, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THIS - AGREEMENT, INCLUDING, WITHOUT LIMITATION, THOSE RESULTING FROM THE USE - OF THE SOURCE CODE, OR THE FAILURE OF THE SOURCE CODE TO PERFORM, OR FOR - ANY OTHER REASON. - - OpenVision retains all copyrights in the donated Source Code. OpenVision - also retains copyright to derivative works of the Source Code, whether - created by OpenVision or by a third party. The OpenVision copyright - notice must be preserved if derivative works are made based on the - donated Source Code. - - OpenVision Technologies, Inc. has donated this Kerberos Administration - system to MIT for inclusion in the standard Kerberos 5 distribution. - This donation underscores our commitment to continuing Kerberos - technology development and our gratitude for the valuable work which has - been performed by MIT and the Kerberos community. - -------------------- - - Portions contributed by Matt Crawford ``crawdad@fnal.gov`` were work - performed at Fermi National Accelerator Laboratory, which is operated - by Universities Research Association, Inc., under contract - DE-AC02-76CHO3000 with the U.S. Department of Energy. - -------------------- - -Portions of ``src/lib/crypto`` have the following copyright: - - Copyright |copy| 1998 by the FundsXpress, INC. - - All rights reserved. - - Export of this software from the United States of America may require - a specific license from the United States Government. It is the - responsibility of any person or organization contemplating export to - obtain such a license before exporting. - - WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - distribute this software and its documentation for any purpose and - without fee is hereby granted, provided that the above copyright - notice appear in all copies and that both that copyright notice and - this permission notice appear in supporting documentation, and that - the name of FundsXpress. not be used in advertising or publicity pertaining - to distribution of the software without specific, written prior - permission. FundsXpress makes no representations about the suitability of - this software for any purpose. It is provided "as is" without express - or implied warranty. - - THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED - WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. - -------------------- - -The implementation of the AES encryption algorithm in -``src/lib/crypto/builtin/aes`` has the following copyright: - - | Copyright |copy| 2001, Dr Brian Gladman ``brg@gladman.uk.net``, - Worcester, UK. - | All rights reserved. - - LICENSE TERMS - - The free distribution and use of this software in both source and binary - form is allowed (with or without changes) provided that: - - 1. distributions of this source code include the above copyright - notice, this list of conditions and the following disclaimer; - 2. distributions in binary form include the above copyright - notice, this list of conditions and the following disclaimer - in the documentation and/or other associated materials; - 3. the copyright holder's name is not used to endorse products - built using this software without specific written permission. - - DISCLAIMER - - This software is provided 'as is' with no explcit or implied warranties - in respect of any properties, including, but not limited to, correctness - and fitness for purpose. - -------------------- - -Portions contributed by Red Hat, including the pre-authentication -plug-in framework and the NSS crypto implementation, contain the -following copyright: - - | Copyright |copy| 2006 Red Hat, Inc. - | Portions copyright |copy| 2006 Massachusetts Institute of Technology - | All Rights Reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are - met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - 3. Neither the name of Red Hat, Inc., nor the names of its contributors - may be used to endorse or promote products derived from this software - without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS - IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED - TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A - PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER - OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, - EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, - PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR - PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING - NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -------------------- - -The bundled verto source code is subject to the following license: - - Copyright 2011 Red Hat, Inc. - - Permission is hereby granted, free of charge, to any person - obtaining a copy of this software and associated documentation files - (the "Software"), to deal in the Software without restriction, - including without limitation the rights to use, copy, modify, merge, - publish, distribute, sublicense, and/or sell copies of the Software, - and to permit persons to whom the Software is furnished to do so, - subject to the following conditions: - - The above copyright notice and this permission notice shall be - included in all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS - BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN - ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - SOFTWARE. - -------------------- - -The implementations of GSSAPI mechglue in GSSAPI-SPNEGO in -``src/lib/gssapi``, including the following files: - -.. parsed-literal:: - - lib/gssapi/generic/gssapi_err_generic.et - lib/gssapi/mechglue/g_accept_sec_context.c - lib/gssapi/mechglue/g_acquire_cred.c - lib/gssapi/mechglue/g_canon_name.c - lib/gssapi/mechglue/g_compare_name.c - lib/gssapi/mechglue/g_context_time.c - lib/gssapi/mechglue/g_delete_sec_context.c - lib/gssapi/mechglue/g_dsp_name.c - lib/gssapi/mechglue/g_dsp_status.c - lib/gssapi/mechglue/g_dup_name.c - lib/gssapi/mechglue/g_exp_sec_context.c - lib/gssapi/mechglue/g_export_name.c - lib/gssapi/mechglue/g_glue.c - lib/gssapi/mechglue/g_imp_name.c - lib/gssapi/mechglue/g_imp_sec_context.c - lib/gssapi/mechglue/g_init_sec_context.c - lib/gssapi/mechglue/g_initialize.c - lib/gssapi/mechglue/g_inquire_context.c - lib/gssapi/mechglue/g_inquire_cred.c - lib/gssapi/mechglue/g_inquire_names.c - lib/gssapi/mechglue/g_process_context.c - lib/gssapi/mechglue/g_rel_buffer.c - lib/gssapi/mechglue/g_rel_cred.c - lib/gssapi/mechglue/g_rel_name.c - lib/gssapi/mechglue/g_rel_oid_set.c - lib/gssapi/mechglue/g_seal.c - lib/gssapi/mechglue/g_sign.c - lib/gssapi/mechglue/g_store_cred.c - lib/gssapi/mechglue/g_unseal.c - lib/gssapi/mechglue/g_userok.c - lib/gssapi/mechglue/g_utils.c - lib/gssapi/mechglue/g_verify.c - lib/gssapi/mechglue/gssd_pname_to_uid.c - lib/gssapi/mechglue/mglueP.h - lib/gssapi/mechglue/oid_ops.c - lib/gssapi/spnego/gssapiP_spnego.h - lib/gssapi/spnego/spnego_mech.c - -and the initial implementation of incremental propagation, including -the following new or changed files: - -.. parsed-literal:: - - include/iprop_hdr.h - kadmin/server/ipropd_svc.c - lib/kdb/iprop.x - lib/kdb/kdb_convert.c - lib/kdb/kdb_log.c - lib/kdb/kdb_log.h - lib/krb5/error_tables/kdb5_err.et - slave/kpropd_rpc.c - slave/kproplog.c - -are subject to the following license: - - Copyright |copy| 2004 Sun Microsystems, Inc. - - Permission is hereby granted, free of charge, to any person obtaining a - copy of this software and associated documentation files (the - "Software"), to deal in the Software without restriction, including - without limitation the rights to use, copy, modify, merge, publish, - distribute, sublicense, and/or sell copies of the Software, and to - permit persons to whom the Software is furnished to do so, subject to - the following conditions: - - The above copyright notice and this permission notice shall be included - in all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS - OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. - IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY - CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, - TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE - SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -------------------- - -Kerberos V5 includes documentation and software developed at the -University of California at Berkeley, which includes this copyright -notice: - - | Copyright |copy| 1983 Regents of the University of California. - | All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are - met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - 3. Neither the name of the University nor the names of its contributors - may be used to endorse or promote products derived from this software - without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - -------------------- - -Portions contributed by Novell, Inc., including the LDAP database -backend, are subject to the following license: - - | Copyright |copy| 2004-2005, Novell, Inc. - | All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are met: - - 1. Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - 3. The copyright holder's name is not used to endorse or promote products - derived from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE - LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - -------------------- - -Portions funded by Sandia National Laboratory -and developed by the University of Michigan's -Center for Information Technology Integration, -including the PKINIT implementation, are subject -to the following license: - - | COPYRIGHT |copy| 2006-2007 - | THE REGENTS OF THE UNIVERSITY OF MICHIGAN - | ALL RIGHTS RESERVED - - Permission is granted to use, copy, create derivative works - and redistribute this software and such derivative works - for any purpose, so long as the name of The University of - Michigan is not used in any advertising or publicity - pertaining to the use of distribution of this software - without specific, written prior authorization. If the - above copyright notice or any other identification of the - University of Michigan is included in any copy of any - portion of this software, then the disclaimer below must - also be included. - - THIS SOFTWARE IS PROVIDED AS IS, WITHOUT REPRESENTATION - FROM THE UNIVERSITY OF MICHIGAN AS TO ITS FITNESS FOR ANY - PURPOSE, AND WITHOUT WARRANTY BY THE UNIVERSITY OF - MICHIGAN OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING - WITHOUT LIMITATION THE IMPLIED WARRANTIES OF - MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE - REGENTS OF THE UNIVERSITY OF MICHIGAN SHALL NOT BE LIABLE - FOR ANY DAMAGES, INCLUDING SPECIAL, INDIRECT, INCIDENTAL, OR - CONSEQUENTIAL DAMAGES, WITH RESPECT TO ANY CLAIM ARISING - OUT OF OR IN CONNECTION WITH THE USE OF THE SOFTWARE, EVEN - IF IT HAS BEEN OR IS HEREAFTER ADVISED OF THE POSSIBILITY OF - SUCH DAMAGES. - -------------------- - -The pkcs11.h file included in the PKINIT code has the -following license: - - | Copyright 2006 g10 Code GmbH - | Copyright 2006 Andreas Jellinghaus - - This file is free software; as a special exception the author gives - unlimited permission to copy and/or distribute it, with or without - modifications, as long as this notice is preserved. - - This file is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY, to the extent permitted by law; without even - the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR - PURPOSE. - -------------------- - -Portions contributed by Apple Inc. are subject to the following license: - - Copyright 2004-2008 Apple Inc. All Rights Reserved. - - Export of this software from the United States of America may require - a specific license from the United States Government. It is the - responsibility of any person or organization contemplating export to - obtain such a license before exporting. - - WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - distribute this software and its documentation for any purpose and - without fee is hereby granted, provided that the above copyright - notice appear in all copies and that both that copyright notice and - this permission notice appear in supporting documentation, and that - the name of Apple Inc. not be used in advertising or publicity pertaining - to distribution of the software without specific, written prior - permission. Apple Inc. makes no representations about the suitability of - this software for any purpose. It is provided "as is" without express - or implied warranty. - - THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED - WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. - -------------------- - -The implementations of UTF-8 string handling in src/util/support and -src/lib/krb5/unicode are subject to the following copyright and -permission notice: - - | The OpenLDAP Public License - | Version 2.8, 17 August 2003 - - Redistribution and use of this software and associated documentation - ("Software"), with or without modification, are permitted provided - that the following conditions are met: - - 1. Redistributions in source form must retain copyright statements - and notices, - 2. Redistributions in binary form must reproduce applicable copyright - statements and notices, this list of conditions, and the following - disclaimer in the documentation and/or other materials provided - with the distribution, and - 3. Redistributions must contain a verbatim copy of this document. - - The OpenLDAP Foundation may revise this license from time to time. - Each revision is distinguished by a version number. You may use - this Software under terms of this license revision or under the - terms of any subsequent revision of the license. - - THIS SOFTWARE IS PROVIDED BY THE OPENLDAP FOUNDATION AND ITS - CONTRIBUTORS "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, - INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY - AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT - SHALL THE OPENLDAP FOUNDATION, ITS CONTRIBUTORS, OR THE AUTHOR(S) - OR OWNER(S) OF THE SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, - INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, - BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER - CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN - ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - - The names of the authors and copyright holders must not be used in - advertising or otherwise to promote the sale, use or other dealing - in this Software without specific, written prior permission. Title - to copyright in this Software shall at all times remain with copyright - holders. - - OpenLDAP is a registered trademark of the OpenLDAP Foundation. - - Copyright 1999-2003 The OpenLDAP Foundation, Redwood City, - California, USA. All Rights Reserved. Permission to copy and - distribute verbatim copies of this document is granted. - -------------------- - -Marked test programs in src/lib/krb5/krb have the following copyright: - - | Copyright |copy| 2006 Kungliga Tekniska Högskola - | (Royal Institute of Technology, Stockholm, Sweden). - | All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - 3. Neither the name of KTH nor the names of its contributors may be - used to endorse or promote products derived from this software without - specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY KTH AND ITS CONTRIBUTORS "AS IS" AND ANY - EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR - PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL KTH OR ITS CONTRIBUTORS BE - LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, - WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR - OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF - ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -------------------- - -Portions of the RPC implementation in src/lib/rpc and src/include/gssrpc -have the following copyright and permission notice: - - Copyright |copy| 2010, Oracle America, Inc. - - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - 3. Neither the name of the "Oracle America, Inc." nor the names of - its contributors may be used to endorse or promote products - derived from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS - IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED - TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A - PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED - TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR - PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING - NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -------------------- - - Copyright |copy| 2006,2007,2009 - NTT (Nippon Telegraph and Telephone Corporation). All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer as - the first lines of this file unmodified. - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - - THIS SOFTWARE IS PROVIDED BY NTT "AS IS" AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. - IN NO EVENT SHALL NTT BE LIABLE FOR ANY DIRECT, INDIRECT, - INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF - THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -------------------- - - Copyright 2000 by Carnegie Mellon University - - All Rights Reserved - - Permission to use, copy, modify, and distribute this software and its - documentation for any purpose and without fee is hereby granted, - provided that the above copyright notice appear in all copies and that - both that copyright notice and this permission notice appear in - supporting documentation, and that the name of Carnegie Mellon - University not be used in advertising or publicity pertaining to - distribution of the software without specific, written prior - permission. - - CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO - THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND - FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE FOR - ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN - ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT - OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - -------------------- - - Copyright |copy| 2002 Naval Research Laboratory (NRL/CCS) - - Permission to use, copy, modify and distribute this software and its - documentation is hereby granted, provided that both the copyright - notice and this permission notice appear in all copies of the software, - derivative works or modified versions, and any portions thereof. - - NRL ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" CONDITION AND - DISCLAIMS ANY LIABILITY OF ANY KIND FOR ANY DAMAGES WHATSOEVER - RESULTING FROM THE USE OF THIS SOFTWARE. - -------------------- - -Portions extracted from Internet RFCs have the following copyright -notice: - - Copyright |copy| The Internet Society (2006). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, - INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE - INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED - WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -------------------- - - Copyright |copy| 1991, 1992, 1994 by Cygnus Support. - - Permission to use, copy, modify, and - distribute this software and its documentation for any purpose and - without fee is hereby granted, provided that the above copyright - notice appear in all copies and that both that copyright notice and - this permission notice appear in supporting documentation. - Cygnus Support makes no representations about the suitability of - this software for any purpose. It is provided "as is" without express - or implied warranty. - -------------------- - - Copyright |copy| 2006 Secure Endpoints Inc. - - Permission is hereby granted, free of charge, to any person - obtaining a copy of this software and associated documentation - files (the "Software"), to deal in the Software without - restriction, including without limitation the rights to use, copy, - modify, merge, publish, distribute, sublicense, and/or sell copies - of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be - included in all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS - BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN - ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - SOFTWARE. - -------------------- - -Portions of the implementation of the Fortuna-like PRNG are subject to -the following notice: - - | Copyright |copy| 2005 Marko Kreen - | All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - -.. - - Copyright |copy| 1994 by the University of Southern California - - EXPORT OF THIS SOFTWARE from the United States of America may - require a specific license from the United States Government. - It is the responsibility of any person or organization contemplating - export to obtain such a license before exporting. - - WITHIN THAT CONSTRAINT, permission to copy, modify, and distribute - this software and its documentation in source and binary forms is - hereby granted, provided that any documentation or other materials - related to such distribution or use acknowledge that the software - was developed by the University of Southern California. - - DISCLAIMER OF WARRANTY. THIS SOFTWARE IS PROVIDED "AS IS". The - University of Southern California MAKES NO REPRESENTATIONS OR - WARRANTIES, EXPRESS OR IMPLIED. By way of example, but not - limitation, the University of Southern California MAKES NO - REPRESENTATIONS OR WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY - PARTICULAR PURPOSE. The University of Southern - California shall not be held liable for any liability nor for any - direct, indirect, or consequential damages with respect to any - claim by the user or distributor of the ksu software. - -------------------- - - | Copyright |copy| 1995 - | The President and Fellows of Harvard University - - This code is derived from software contributed to Harvard by - Jeremy Rassen. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - 3. All advertising materials mentioning features or use of this software - must display the following acknowledgement: - - This product includes software developed by the University of - California, Berkeley and its contributors. - - 4. Neither the name of the University nor the names of its contributors - may be used to endorse or promote products derived from this software - without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - -------------------- - - | Copyright |copy| 2008 by the Massachusetts Institute of Technology. - | Copyright 1995 by Richard P. Basch. All Rights Reserved. - | Copyright 1995 by Lehman Brothers, Inc. All Rights Reserved. - - Export of this software from the United States of America may - require a specific license from the United States Government. - It is the responsibility of any person or organization contemplating - export to obtain such a license before exporting. - - WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - distribute this software and its documentation for any purpose and - without fee is hereby granted, provided that the above copyright - notice appear in all copies and that both that copyright notice and - this permission notice appear in supporting documentation, and that - the name of Richard P. Basch, Lehman Brothers and M.I.T. not be used - in advertising or publicity pertaining to distribution of the software - without specific, written prior permission. Richard P. Basch, - Lehman Brothers and M.I.T. make no representations about the suitability - of this software for any purpose. It is provided "as is" without - express or implied warranty. - -------------------- - -The following notice applies to ``src/lib/krb5/krb/strptime.c`` and -``src/include/k5-queue.h``. - - | Copyright |copy| 1997, 1998 The NetBSD Foundation, Inc. - | All rights reserved. - - This code was contributed to The NetBSD Foundation by Klaus Klein. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - 3. All advertising materials mentioning features or use of this software - must display the following acknowledgement: - - This product includes software developed by the NetBSD - Foundation, Inc. and its contributors. - - 4. Neither the name of The NetBSD Foundation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED - TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR - PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS - BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGE. - -------------------- - -The following notice applies to Unicode library files in -``src/lib/krb5/unicode``: - - | Copyright 1997, 1998, 1999 Computing Research Labs, - | New Mexico State University - - Permission is hereby granted, free of charge, to any person obtaining a - copy of this software and associated documentation files (the "Software"), - to deal in the Software without restriction, including without limitation - the rights to use, copy, modify, merge, publish, distribute, sublicense, - and/or sell copies of the Software, and to permit persons to whom the - Software is furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included in - all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL - THE COMPUTING RESEARCH LAB OR NEW MEXICO STATE UNIVERSITY BE LIABLE FOR ANY - CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT - OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR - THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -------------------- - -The following notice applies to ``src/util/support/strlcpy.c``: - - Copyright |copy| 1998 Todd C. Miller ``Todd.Miller@courtesan.com`` - - Permission to use, copy, modify, and distribute this software for any - purpose with or without fee is hereby granted, provided that the above - copyright notice and this permission notice appear in all copies. - - THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES - WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF - MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR - ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN - ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF - OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - -------------------- - -The following notice applies to ``src/util/profile/argv_parse.c`` and -``src/util/profile/argv_parse.h``: - - Copyright 1999 by Theodore Ts'o. - - Permission to use, copy, modify, and distribute this software for - any purpose with or without fee is hereby granted, provided that - the above copyright notice and this permission notice appear in all - copies. THE SOFTWARE IS PROVIDED "AS IS" AND THEODORE TS'O (THE - AUTHOR) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, - INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. - IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER - RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION - OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR - IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. (Isn't - it sick that the U.S. culture of lawsuit-happy lawyers requires - this kind of disclaimer?) - -------------------- - -The following notice applies to SWIG-generated code in -``src/util/profile/profile_tcl.c``: - - Copyright |copy| 1999-2000, The University of Chicago - - This file may be freely redistributed without license or fee provided - this copyright message remains intact. - -------------------- - -The following notice applies to portiions of ``src/lib/rpc`` and -``src/include/gssrpc``: - - Copyright |copy| 2000 The Regents of the University of Michigan. - All rights reserved. - - Copyright |copy| 2000 Dug Song ``dugsong@UMICH.EDU``. - All rights reserved, all wrongs reversed. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - 3. Neither the name of the University nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED - WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING - NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -------------------- - -Implementations of the MD4 algorithm are subject to the following -notice: - - Copyright |copy| 1990, RSA Data Security, Inc. All rights reserved. - - License to copy and use this software is granted provided that - it is identified as the "RSA Data Security, Inc. MD4 Message - Digest Algorithm" in all material mentioning or referencing this - software or this function. - - License is also granted to make and use derivative works - provided that such works are identified as "derived from the RSA - Data Security, Inc. MD4 Message Digest Algorithm" in all - material mentioning or referencing the derived work. - - RSA Data Security, Inc. makes no representations concerning - either the merchantability of this software or the suitability - of this software for any particular purpose. It is provided "as - is" without express or implied warranty of any kind. - - These notices must be retained in any copies of any part of this - documentation and/or software. - -------------------- - -Implementations of the MD5 algorithm are subject to the following -notice: - - Copyright |copy| 1990, RSA Data Security, Inc. All rights reserved. - - License to copy and use this software is granted provided that - it is identified as the "RSA Data Security, Inc. MD5 Message- - Digest Algorithm" in all material mentioning or referencing this - software or this function. - - License is also granted to make and use derivative works - provided that such works are identified as "derived from the RSA - Data Security, Inc. MD5 Message-Digest Algorithm" in all - material mentioning or referencing the derived work. - - RSA Data Security, Inc. makes no representations concerning - either the merchantability of this software or the suitability - of this software for any particular purpose. It is provided "as - is" without express or implied warranty of any kind. - - These notices must be retained in any copies of any part of this - documentation and/or software. - -------------------- - -The following notice applies to ``src/lib/crypto/crypto_tests/t_mddriver.c``: - - Copyright |copy| 1990-2, RSA Data Security, Inc. Created 1990. All - rights reserved. - - RSA Data Security, Inc. makes no representations concerning either - the merchantability of this software or the suitability of this - software for any particular purpose. It is provided "as is" - without express or implied warranty of any kind. - - These notices must be retained in any copies of any part of this - documentation and/or software. - -------------------- - -Portions of ``src/lib/krb5`` are subject to the following notice: - - | Copyright |copy| 1994 CyberSAFE Corporation. - | Copyright 1990,1991,2007,2008 by the Massachusetts - Institute of Technology. - | All Rights Reserved. - - Export of this software from the United States of America may - require a specific license from the United States Government. - It is the responsibility of any person or organization contemplating - export to obtain such a license before exporting. - - WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - distribute this software and its documentation for any purpose and - without fee is hereby granted, provided that the above copyright - notice appear in all copies and that both that copyright notice and - this permission notice appear in supporting documentation, and that - the name of M.I.T. not be used in advertising or publicity pertaining - to distribution of the software without specific, written prior - permission. Furthermore if you modify this software you must label - your software as modified software and not distribute it in such a - fashion that it might be confused with the original M.I.T. software. - Neither M.I.T., the Open Computing Security Group, nor - CyberSAFE Corporation make any representations about the suitability of - this software for any purpose. It is provided "as is" without express - or implied warranty. - -------------------- - -Portions contributed by PADL Software are subject to the following -license: - - Copyright (c) 2011, PADL Software Pty Ltd. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - - 3. Neither the name of PADL Software nor the names of its contributors - may be used to endorse or promote products derived from this software - without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY PADL SOFTWARE AND CONTRIBUTORS "AS IS" AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL PADL SOFTWARE OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - -------------------- - -The bundled libev source code is subject to the following license: - - All files in libev are Copyright (C)2007,2008,2009 Marc Alexander Lehmann. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are - met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - Alternatively, the contents of this package may be used under the terms - of the GNU General Public License ("GPL") version 2 or any later version, - in which case the provisions of the GPL are applicable instead of the - above. If you wish to allow the use of your version of this package only - under the terms of the GPL and not to allow others to use your version of - this file under the BSD license, indicate your decision by deleting the - provisions above and replace them with the notice and other provisions - required by the GPL in this and the other files of this package. If you do - not delete the provisions above, a recipient may use your version of this - file under either the BSD or the GPL. diff --git a/doc/rst_source/relay/build_this.rst b/doc/rst_source/relay/build_this.rst deleted file mode 100644 index f51d1047d..000000000 --- a/doc/rst_source/relay/build_this.rst +++ /dev/null @@ -1,81 +0,0 @@ -How to build this documentation from the source -=============================================== - -Pre-requisites for the simple build, or to update man pages: - -* Sphinx 1.0.4 or higher (See http://sphinx.pocoo.org) with “autodoc” - extension installed. - -Additional prerequisites to include the API reference based on Doxygen -markup: - -* python 2.5 with the Cheetah, lxml, and xml modules -* Doxygen - - -Simple build without API reference ----------------------------------- - -To test simple changes to the RST sources, you can build the -documentation without the Doxygen reference by running, from the doc -directory:: - - sphinx-build rst_source test_html - -You will see a number of warnings about missing files. This is -expected. - - -Updating man pages ------------------- - -Man pages are generated from the RST sources and checked into the -``src/man`` directory of the repository. This allows man pages to be -installed without requiring Sphinx when using a source checkout. To -regenerate these files, run ``make rstman`` from the man subdirectory -of a configured build tree. You can also do this from an unconfigured -source tree with:: - - cd src/man - make -f Makefile.in top_srcdir=.. srcdir=. rstman - make clean - -As with the simple build, it is normal to see warnings about missing -files when rebuilding the man pages. - - -Building for a release tarball or web site ------------------------------------------- - -To generate documentation in HTML format, run ``make rsthtml`` in the -``doc`` subdirectory of a configured build tree (the build directory -corresponding to ``src/doc``, not the top-level ``doc`` directory). -The output will be placed in the top-level ``doc/rst_html`` directory. -This build will include the API reference generated from Doxygen -markup in the source tree. - -Documentation generated this way will use symbolic names for paths -(like ``BINDIR`` for the directory containing user programs), with the -symbolic names being links to a table showing typical values for those -paths. - -You can also do this from an unconfigured source tree with:: - - cd src/doc - make -f Makefile.in top_srcdir=.. PYTHON=python rsthml - make -f Makefile.in clean - - -Building for an OS package or site documentation ------------------------------------------------- - -To generate documentation specific to a build of MIT krb5 as you have -configured it, run ``make substhtml`` in the ``doc`` subdirectory of a -configured build tree (the build directory corresponding to -``src/doc``, not the top-level ``doc`` directory). The output will be -placed in the ``rst_html_subst`` subdirectory of that build directory. -This build will include the API reference. - -Documentation generated this way will use concrete paths (like -``/usr/local/bin`` for the directory containing user programs, for a -default custom build). diff --git a/doc/rst_source/relay/index.rst b/doc/rst_source/relay/index.rst deleted file mode 100644 index 45e3e1f14..000000000 --- a/doc/rst_source/relay/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -About this project -================== - -.. toctree:: - :maxdepth: 1 - - philosophy.rst - build_this.rst - diff --git a/doc/rst_source/relay/philosophy.rst b/doc/rst_source/relay/philosophy.rst deleted file mode 100644 index 2771f84a8..000000000 --- a/doc/rst_source/relay/philosophy.rst +++ /dev/null @@ -1,28 +0,0 @@ -Kerberos Documentation Relay -============================ - -Philosophy ----------- - -- The documentation must be useful; - -- The documentation must be correct; - -- The documentation must be detailed, but optimized. No verbose mode; - -- The documentation should be built incrementally; - -- The documentation should be easy to maintain; - -- The documentation should be examined to identify the approaches - that do not work; - -Feedback and Comments ---------------------- - -At the moment the comments should be sent via email to -krb5-bugs@mit.edu. - -The html version of this documentation has a "FEEDBACK" link -(at the bottom of every page) to the krb5-bugs@mit.edu email address -with the pre-constructed subject line. diff --git a/doc/rst_source/resources.rst b/doc/rst_source/resources.rst deleted file mode 100644 index 74e93003b..000000000 --- a/doc/rst_source/resources.rst +++ /dev/null @@ -1,55 +0,0 @@ -Resources -========= - -Mailing lists -------------- - -* kerberos@mit.edu is a community resource for discussion and - questions about MIT krb5 and other Kerberos implementations. To - subscribe to the list, please follow the instructions at - http://mailman.mit.edu/mailman/listinfo/kerberos. -* krbdev@mit.edu is the primary list for developers of MIT Kerberos. - To subscribe to the list, please follow the instructions at - http://mailman.mit.edu/mailman/listinfo/krbdev. -* krb5-bugs@mit.edu is notified when a ticket is created or updated. - This list helps track bugs and feature requests. - In addition, this list is used to track documentation criticism - and recommendations for improvements. -* krbcore@mit.edu is a private list for the MIT krb5 core team. Send - mail to this list if you need to contact the core team. -* krbcore-security@mit.edu is the point of contact for security problems - with MIT Kerberos. Please use PGP-encrypted mail to report possible - vulnerabilities to this list. - - -IRC channels ------------- - -The main IRC channel for MIT Kerberos development is #krbdev on -irc.freenode.net. - -There is a separate channel, `#kerberos`, for general Kerberos -discussion and support. - -For more information about freenode, see http://freenode.net/. - -The `#krbdev` channel is logged at -http://colabti.org/irclogger/irclogger_logs/krbdev using the -colabti.org service, which generously offers IRC logging -to Free / Open Source projects. - -The `#krbdev` channel was previously logged by lopbot, courtesy -of Brandon Allbery. These logs are no longer readily available online. -Despite the possible existence of logging, please summarize important -conversations to more permanent places, such as an appropriate -mailing list or wiki page. - - -Archives --------- - -* The archive http://mailman.mit.edu/pipermail/kerberos/ contains past - posting from `kerberos@mit.edu` list. - -* The http://mailman.mit.edu/pipermail/krbdev/ contains past - posting from `krbdev@mit.edu` list. diff --git a/doc/rst_source/txt_conf.py b/doc/rst_source/txt_conf.py deleted file mode 100644 index f9f00e945..000000000 --- a/doc/rst_source/txt_conf.py +++ /dev/null @@ -1,88 +0,0 @@ -# -*- coding: utf-8 -*- -# -# MIT Kerberos documentation build configuration file, created by -# sphinx-quickstart on Wed Oct 13 09:14:03 2010. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -#extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.doxylink'] -extensions = ['sphinx.ext.autodoc'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'notice' - -# General information about the project. -project = u'MIT Kerberos' -copyright = u'2012, MIT' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '0.0.1' -# The full version, including alpha/beta/rc tags. -release = '0.0.1' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -today = ' ' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = [] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] diff --git a/doc/rst_tools/README b/doc/rst_tools/README deleted file mode 100644 index cca78d368..000000000 --- a/doc/rst_tools/README +++ /dev/null @@ -1,65 +0,0 @@ -How to deploy the Doxygen output in Sphinx project. -==================================================== - -The text below is meant to give the instructions on how to incorporate MIT Kerberos API reference documentation into Sphinx document hierarchy. The Sphinx API documentation can be constructed with (Part B) or without (Part A) the bridge to the original Doxygen HTML output. - -Pre-requisites: -- python 2.5+ with Cheetah, lxml and xml extension modules installed; -- For part B only: - - Sphinx “doxylink” extension; - - Doxygen HTML output - - -Part A: Transforming Doxygen XML output into reStructuredText (rst) without the bridge to Doxygen HTML output. - -1. Delete lines containing text "Doxygen reference" from the template files func_document.tmpl and type_document.tmpl; - -2. In the Doxygen configuration file set GENERATE_XML to YES. Generate Doxygen XML output; - -3. Suppose the Doxygen XML output is located in doxy_xml_dir and the desired output directory is rst_dir. - Run: - python doxy.py –i doxy_xml_dir –o rst_dir –t func - This will result in the storing of the API function documentation files in rst format in the rst_dir. The file names are constructed based on the function name. For example, the file for krb5_build_principal() will be krb5_build_principal.rst - - Run: - python doxy.py –i doxy_xml_dir –o rst_dir –t typedef - It is similar to the API function conversion, but for data types. The result will be stored under rst_dir/types directory - - Alternatively, running - python doxy.py –i doxy_xml_dir –o rst_dir - or - python doxy.py –i doxy_xml_dir –o rst_dir -t all - converts Doxygen XML output into reStructuredText format files both for API functions and data types; - -4. In krb_appldev/index.rst add the following section to point to the API references: - - .. toctree:: - :maxdepth: 1 - - refs/index.rst - -5. Copy the content of rst_dir into krb_appldev/refs/api/ directory and rst_dir/types into krb_appldev/refs/types directory; - -6. Rebuild Sphinx source: - sphinx-build source_dir build_dir - - - - -Part B: Bridge to Doxygen HTML output. - -1. Transform Doxygen XML output into reStructuredText. - In src/Doxygen configuration file request genetation of the tag file and XML output: - GENERATE_TAGFILE = krb5doxy.tag - GENERATE_XML = YES - -2. Modify Sphinx conf.py file to point to the “doxylink” extension and Doxygen tag file: - extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.doxylink'] - doxylink = { ' krb5doxy' : ('/tmp/krb5doxy.tag, ' doxy_html_dir ') } - - where doxy_html_dir is the location of the Doxygen HTML output - -3. Continue with steps 3 - 6 of Part A. - - - diff --git a/doc/rst_tools/define_document.tmpl b/doc/rst_tools/define_document.tmpl deleted file mode 100644 index 8bf2fd393..000000000 --- a/doc/rst_tools/define_document.tmpl +++ /dev/null @@ -1,27 +0,0 @@ -.. highlightlang:: c - -.. $composite.macro_reference($composite.name): - -#set $title = $composite.name -$title -#echo ''.join(['=']*len($title)) # - -.. -.. data:: $composite.name -.. - -#if $composite.short_description is not None and len($composite.short_description) -$composite.short_description -#end if - -$composite.long_description - -#if $composite.name_signature is not None and len($composite.name_signature) -#echo ''.join(['=']*len($composite.name_signature)) + '== ======================' # -$composite.name_signature $composite.initializer -#echo ''.join(['=']*len($composite.name_signature)) + '== ======================' # -#else -#echo ''.join(['=']*len($composite.name)) + '=== ======================' # -$composite.name $composite.initializer -#echo ''.join(['=']*len($composite.name)) + '=== ======================' # -#end if diff --git a/doc/rst_tools/docmodel.py b/doc/rst_tools/docmodel.py deleted file mode 100644 index ef4cd76c3..000000000 --- a/doc/rst_tools/docmodel.py +++ /dev/null @@ -1,252 +0,0 @@ -''' - Copyright 2011 by the Massachusetts - Institute of Technology. All Rights Reserved. - - Export of this software from the United States of America may - require a specific license from the United States Government. - It is the responsibility of any person or organization contemplating - export to obtain such a license before exporting. - - WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - distribute this software and its documentation for any purpose and - without fee is hereby granted, provided that the above copyright - notice appear in all copies and that both that copyright notice and - this permission notice appear in supporting documentation, and that - the name of M.I.T. not be used in advertising or publicity pertaining - to distribution of the software without specific, written prior - permission. Furthermore if you modify this software you must label - your software as modified software and not distribute it in such a - fashion that it might be confused with the original M.I.T. software. - M.I.T. makes no representations about the suitability of - this software for any purpose. It is provided "as is" without express - or implied warranty. -''' -import re - -from Cheetah.Template import Template - -class Attribute(object): - def __init__(self, **argkw): - self.definition = argkw.get('definition') - self.name = argkw.get('name') - self.type = argkw.get('type') - self.typeId = argkw.get('typeId') - self.short_description = argkw.get('short_description') - self.long_description = argkw.get('long_description') - self.version = argkw.get('version') - - def __repr__(self): - result = list() - for (attr,value) in self.__dict__.iteritems(): - result.append('%s=%s' % (attr,value)) - return 'Attribute: %s' % ','.join(result) - - -class CompositeType(): - def __init__(self, **argkw): - self.category = 'composite' - self.definition = argkw.get('definition') - self.name = argkw.get('name') - self.name_signature = argkw.get('name_signature') - self.Id = argkw.get('Id') - self.initializer = argkw.get('initializer') - self.active = argkw.get('active', False) - self.version = argkw.get('version') - self.return_type = argkw.get('return_type') - self.short_description = argkw.get('short_description') - self.long_description = argkw.get('long_description') - self.friends = argkw.get('friends') - self.type = argkw.get('type') - self.attributes = self._setAttributes(argkw.get('attributes')) - - def __repr__(self): - result = list() - for (attr,value) in self.__dict__.iteritems(): - if attr == 'attributes': - if value is not None: - attributes = ['%s' % a for a in value] - value = '\n %s' % '\n '.join(attributes) - - result.append('%s: %s' % (attr,value)) - result = '\n'.join(result) - - return result - - def _setAttributes(self, attributes): - result = None - if attributes is not None: - result = list() - for a in attributes: - result.append(Attribute(**a)) - - return result - - def struct_reference(self, name): - result = re.sub(r'_', '-', name) - result = '_%s-struct' % result - - return result - - def macro_reference(self, name): - result = re.sub(r'_', '-', name) - result = '_%s-data' % result - - return result - -class Parameter(object): - def __init__(self, **argkw): - self.seqno = argkw.get('seqno') - self.name = argkw.get('name') - self.direction = argkw.get('direction') - self.type = argkw.get('type') - self.typeId = argkw.get('typeId') - self.description = argkw.get('description') - self.version = argkw.get('version') - - def __repr__(self): - content = (self.name,self.direction,self.seqno,self.type,self.typeId,self.description) - return 'Parameter: name=%s,direction=%s,seqno=%s,type=%s,typeId=%s,descr=%s' % content - -class Function(object): - def __init__(self, **argkw): - self.category = 'function' - self.name = argkw.get('name') - self.Id = argkw.get('Id') - self.active = argkw.get('active', False) - self.version = argkw.get('version') - self.parameters = self._setParameters(argkw.get('parameters')) - self.return_type = argkw.get('return_type') - self.return_description = argkw.get('return_description') - self.retval_description = argkw.get('retval_description') - self.warn_description = argkw.get('warn_description') - self.sa_description = argkw.get('sa_description') - self.notes_description = argkw.get('notes_description') - self.version_num = argkw.get('version_num') - self.short_description = argkw.get('short_description') - self.long_description = argkw.get('long_description') - self.deprecated_description = argkw.get('deprecated_description') - self.friends = argkw.get('friends') - - def _setParameters(self, parameters): - result = None - if parameters is not None: - result = list() - for p in parameters: - result.append(Parameter(**p)) - - return result - - def getObjectRow(self): - result = [str(self.Id), - self.name, - self.category] - - return ','.join(result) - - def getObjectDescriptionRow(self): - result = [self.Id, - self.active, - self.version, - self.short_description, - self.long_description] - - return ','.join(result) - - def getParameterRows(self): - result = list() - for p in self.parameters: - p_row = [self.Id, - p.name, - p.seqno, - p.type, - p.typeId, - p.description, - p.version] - result.append(','.join(p_row)) - - return '\n'.join(result) - - def __repr__(self): - lines = list() - lines.append('Category: %s' % self.category) - lines.append('Function name: %s' % self.name) - lines.append('Function Id: %s' % self.Id) - parameters = [' %s' % p for p in self.parameters] - lines.append('Parameters:\n%s' % '\n'.join(parameters)) - lines.append('Function return type: %s' % self.return_type) - lines.append('Function return type description:\n%s' % self.return_description) - lines.append('Function retval description:\n%s' % self.retval_description) - lines.append('Function short description:\n%s' % self.short_description) - lines.append('Function long description:\n%s' % self.long_description) - lines.append('Warning description:\n%s' % self.warn_description) - lines.append('See also description:\n%s' % self.sa_description) - lines.append('NOTE description:\n%s' % self.notes_description) - lines.append('Version introduced:\n%s' % self.version_num) - lines.append('Deprecated description:\n%s' % self.deprecated_description) - result = '\n'.join(lines) - - return result - - -class DocModel(object): - def __init__(self, **argkw): - if len(argkw): - self.name = argkw['name'] - if argkw['category'] == 'function': - self.category = 'function' - self.function = Function(**argkw) - elif argkw['category'] == 'composite': - self.category = 'composite' - self.composite = CompositeType(**argkw) - - def __repr__(self): - obj = getattr(self,self.category) - print type(obj) - return str(obj) - - def signature(self): - param_list = list() - for p in self.function.parameters: - if p.type is "... " : - param_list.append('%s %s' % (p.type,' ')) - else: - param_list.append('%s %s' % (p.type, p.name)) - param_list = ', '.join(param_list) - result = '%s %s(%s)' % (self.function.return_type, - self.function.name, param_list) - - return result - - def save(self, path, template_path): - f = open(template_path, 'r') - t = Template(f.read(),self) - out = open(path, 'w') - out.write(str(t)) - out.close() - f.close() - - -class DocModelTest(DocModel): - def __init__(self): - doc_path = '../docutil/example.yml' - argkw = yaml.load(open(doc_path,'r')) - super(DocModelTest,self).__init__(**argkw) - - def run_tests(self): - self.test_save() - - def test_print(self): - print 'testing' - print self - - - def test_save(self): - template_path = '../docutil/function2edit.html' - - path = '/var/tsitkova/Sources/v10/trunk/documentation/test_doc.html' - - self.save(path, template_path) - -if __name__ == '__main__': - tester = DocModelTest() - tester.run_tests() diff --git a/doc/rst_tools/doxy.py b/doc/rst_tools/doxy.py deleted file mode 100644 index c8a4b9dad..000000000 --- a/doc/rst_tools/doxy.py +++ /dev/null @@ -1,64 +0,0 @@ -''' - Copyright 2011 by the Massachusetts - Institute of Technology. All Rights Reserved. - - Export of this software from the United States of America may - require a specific license from the United States Government. - It is the responsibility of any person or organization contemplating - export to obtain such a license before exporting. - - WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - distribute this software and its documentation for any purpose and - without fee is hereby granted, provided that the above copyright - notice appear in all copies and that both that copyright notice and - this permission notice appear in supporting documentation, and that - the name of M.I.T. not be used in advertising or publicity pertaining - to distribution of the software without specific, written prior - permission. Furthermore if you modify this software you must label - your software as modified software and not distribute it in such a - fashion that it might be confused with the original M.I.T. software. - M.I.T. makes no representations about the suitability of - this software for any purpose. It is provided "as is" without express - or implied warranty. -''' -import sys -import os -import re -from optparse import OptionParser - - -from doxybuilder_types import * -from doxybuilder_funcs import * - - -def processOptions(): - usage = "\n\t\t%prog -t type -i in_dir -o out_dir" - description = "Description:\n\tProcess doxygen output for c-types and/or functions" - parser = OptionParser(usage=usage, description=description) - - parser.add_option("-t", "--type", type="string", dest="action_type", help="process typedef and/or function. Possible choices: typedef, func, all. Default: all.", default="all") - parser.add_option("-i", "--in", type="string", dest="in_dir", help="input directory") - parser.add_option("-o", "--out", type="string", dest= "out_dir", help="output directory. Note: The subdirectory ./types will be created for typedef") - - (options, args) = parser.parse_args() - action = options.action_type - in_dir = options.in_dir - out_dir = options.out_dir - - - if in_dir is None or out_dir is None: - parser.error("Input and output directories are required") - - if action == "all" or action == "typedef": - tester = DoxyTypesTest(in_dir, out_dir) - tester.run_tests() - - if action == "all" or action == "func" or action == "function": - tester = DoxyFuncsTest(in_dir, out_dir) - tester.run_tests() - - -if __name__ == '__main__': - parser = processOptions() - - diff --git a/doc/rst_tools/doxybuilder_funcs.py b/doc/rst_tools/doxybuilder_funcs.py deleted file mode 100644 index 13331f8ba..000000000 --- a/doc/rst_tools/doxybuilder_funcs.py +++ /dev/null @@ -1,595 +0,0 @@ -''' - Copyright 2011 by the Massachusetts - Institute of Technology. All Rights Reserved. - - Export of this software from the United States of America may - require a specific license from the United States Government. - It is the responsibility of any person or organization contemplating - export to obtain such a license before exporting. - - WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - distribute this software and its documentation for any purpose and - without fee is hereby granted, provided that the above copyright - notice appear in all copies and that both that copyright notice and - this permission notice appear in supporting documentation, and that - the name of M.I.T. not be used in advertising or publicity pertaining - to distribution of the software without specific, written prior - permission. Furthermore if you modify this software you must label - your software as modified software and not distribute it in such a - fashion that it might be confused with the original M.I.T. software. - M.I.T. makes no representations about the suitability of - this software for any purpose. It is provided "as is" without express - or implied warranty. -''' -import sys -import re - -from collections import defaultdict -from xml.sax import make_parser -from xml.sax.handler import ContentHandler -from docmodel import * - -class DocNode(object): - """ - Represents the structure of xml node. - """ - def __init__(self, name): - """ - @param node: name - the name of a node. - @param attributes: a dictionary populated with attributes of a node - @param children: a dictionary with lists of children nodes. Nodes - in lists are ordered as they appear in a document. - @param content: a content of xml node represented as a list of - tuples [(type,value)] with type = ['char'|'element']. - If type is 'char' then the value is a character string otherwise - it is a reference to a child node. - """ - self.name = name - self.content = list() - self.attributes = dict() - self.children = defaultdict(list) - - def walk(self, decorators, sub_ws, stack=[]): - result = list() - decorator = decorators.get(self.name, decorators['default']) - stack.append(decorators['default']) - decorators['default'] = decorator - - for (obj_type,obj) in self.content: - if obj_type == 'char': - if obj != '': - result.append(obj) - else: - partial = obj.walk(decorators,1, stack) - if partial is not None: - result.append(' %s ' % partial) - decorators['default'] = stack.pop() - result = decorator(self, ''.join(result)) - if result is not None: - if sub_ws == 1: - result = re.sub(r'[ ]+', r' ', result) - else: - result = result.strip() - - return result - - def getContent(self): - decorators = {'default': lambda node,value: value} - result = self.walk(decorators, 1) - if len(result) == 0: - result = None - - return result - - def __repr__(self): - result = ['Content: %s' % self.content] - - for (key,value) in self.attributes.iteritems(): - result.append('Attr: %s = %s' % (key,value)) - for (key,value) in self.children.iteritems(): - result.append('Child: %s,%i' % (key,len(value))) - - return '\n'.join(result) - -class DoxyContenHandler(object, ContentHandler): - def __init__(self, builder): - self.builder = builder - self.counters = defaultdict(int) - self._nodes = None - self._current = None - - def startDocument(self): - pass - - def endDocument(self): - import sys - - def startElement(self, name, attrs): - if name == self.builder.toplevel: - self._nodes = [] - - if name == 'memberdef': - kind = attrs.get('kind') - if kind is None: - raise ValueError('Kind is not defined') - self.counters[kind] += 1 - - if self._nodes is None: - return - - node = DocNode(name) - for (key,value) in attrs.items(): - node.attributes[key] = value - if self._current is not None: - self._current.children[name].append(node) - self._nodes.append(self._current) - self._current = node - - def characters(self, content): - - if self._current is not None: - self._current.content.append(('char',content.strip())) - - def endElement(self, name): - if name == self.builder.toplevel: - assert(len(self._nodes) == 0) - self._nodes = None - self.builder.document.append(self._current) - self._current = None - else: - if self._nodes is not None: - node = self._current - self._current = self._nodes.pop() - self._current.content.append(('element',node)) - - -class XML2AST(object): - """ - Translates XML document into Abstract Syntax Tree like representation - The content of document is stored in self.document - """ - def __init__(self, xmlpath, toplevel='doxygen'): - self.document = list() - self.toplevel = toplevel - self.parser = make_parser() - handler = DoxyContenHandler(self) - self.parser.setContentHandler(handler) - filename = 'krb5_8hin.xml' - filepath = '%s/%s' % (xmlpath,filename) - self.parser.parse(open(filepath,'r')) - - -class DoxyFuncs(XML2AST): - def __init__(self, path): - super(DoxyFuncs, self).__init__(path,toplevel='memberdef') - self.objects = list() - - def run(self): - for node in self.document: - self.process(node) - print "\nnumber of functions processed ===> ",len(self.objects) - - def process(self, node): - node_type = node.attributes['kind'] - if node_type == 'function': - data = self._process_function_node(node) - else: - print 'not processing node: %s' % node_type - return - - self.objects.append(DocModel(**data)) - - def save(self, templates, target_dir): - for obj in self.objects: - template_path = templates[obj.category] - outpath = '%s/%s.rst' % (target_dir,obj.name) - obj.save(outpath, template_path) - - - def _process_function_node(self, node): - f_name = node.children['name'][0].getContent() - print f_name - f_Id = node.attributes['id'] - f_ret_type = self._process_type_node(node.children['type'][0]) - f_brief = node.children['briefdescription'][0].getContent() - f_detailed = node.children['detaileddescription'][0] - detailed_description = self._process_description_node(f_detailed) - return_value_description = self._process_return_value_description(f_detailed) - retval_description = self._process_retval_description(f_detailed) - warning_description = self._process_warning_description(f_detailed) - seealso_description = self._process_seealso_description(f_detailed) - notes_description = self._process_notes_description(f_detailed) - f_version = self._process_version_description(f_detailed) - deprecated_description = self._process_deprecated_description(f_detailed) - param_description_map = self.process_parameter_description(f_detailed) - f_definition = node.children['definition'][0].getContent() - f_argsstring = node.children['argsstring'][0].getContent() - - function_descr = {'category': 'function', - 'name': f_name, - 'Id': f_Id, - 'return_type': f_ret_type[1], - 'return_description': return_value_description, - 'retval_description': retval_description, - 'sa_description': seealso_description, - 'warn_description': warning_description, - 'notes_description': notes_description, - 'short_description': f_brief, - 'version_num': f_version, - 'long_description': detailed_description, - 'deprecated_description': deprecated_description, - 'parameters': list()} - - parameters = function_descr['parameters'] - for (i,p) in enumerate(node.children['param']): - type_node = p.children['type'][0] - p_type = self._process_type_node(type_node) - if p_type[1].find('...') > -1 : - p_name = '' - else: - p_name = None - p_name_node = p.children.get('declname') - if p_name_node is not None: - p_name = p_name_node[0].getContent() - (p_direction,p_descr) = param_description_map.get(p_name,(None,None)) - - param_descr = {'seqno': i, - 'name': p_name, - 'direction': p_direction, - 'type': p_type[1], - 'typeId': p_type[0], - 'description': p_descr} - parameters.append(param_descr) - result = Function(**function_descr) - print >> self.tmp, result - - return function_descr - - def _process_type_node(self, type_node): - """ - Type node has form - type_string - for build in types and - - - 'type_name' - - postfix (ex. *, **m, etc.) - - for user defined types. - """ - type_ref_node = type_node.children.get('ref') - if type_ref_node is not None: - p_type_id = type_ref_node[0].attributes['refid'] - else: - p_type_id = None - p_type = type_node.getContent() - # remove some macros - p_type = re.sub('KRB5_ATTR_DEPRECATED', '', p_type) - p_type = re.sub('KRB5_CALLCONV_C', '', p_type) - p_type = re.sub('KRB5_CALLCONV_WRONG', '', p_type) - p_type = re.sub('KRB5_CALLCONV', '', p_type) - p_type = p_type.strip() - - return (p_type_id, p_type) - - def _process_description_node(self, node): - """ - Description node is comprised of ... sections - """ - para = node.children.get('para') - result = list() - if para is not None: - decorators = {'default': self.paragraph_content_decorator} - for e in para: - result.append(str(e.walk(decorators, 1))) - result.append('\n') - result = '\n'.join(result) - - return result - - def return_value_description_decorator(self, node, value): - if node.name == 'simplesect': - if node.attributes['kind'] == 'return': - cont = set() - cont = node.getContent() - return value - else: - return None - - def paragraph_content_decorator(self, node, value): - if node.name == 'para': - return value + '\n' - elif node.name == 'simplesect': - if node.attributes['kind'] == 'return': - return None - elif node.name == 'ref': - if value.find('()') >= 0: - # functions - return ':c:func:' + '`' + value + '`' - else: - # macro's - return ':data:' + '`' + value + '`' - elif node.name == 'emphasis': - return '*' + value + '*' - elif node.name == 'itemizedlist': - return '\n' + value - elif node.name == 'listitem': - return '\n\t - ' + value + '\n' - elif node.name == 'computeroutput': - return '**' + value + '**' - else: - return None - - def parameter_name_decorator(self, node, value): - if node.name == 'parametername': - direction = node.attributes.get('direction') - if direction is not None: - value = '%s:%s' % (value,direction) - return value - - elif node.name == 'parameterdescription': - return None - else: - return value - - def parameter_description_decorator(self, node, value): - if node.name == 'parameterdescription': - return value - elif node.name == 'parametername': - return None - else: - return value - - def process_parameter_description(self, node): - """ - Parameter descriptions reside inside detailed description section. - """ - para = node.children.get('para') - result = dict() - if para is not None: - for e in para: - - param_list = e.children.get('parameterlist') - if param_list is None: - continue - param_items = param_list[0].children.get('parameteritem') - if param_items is None: - continue - for it in param_items: - decorators = {'default': self.parameter_name_decorator} - direction = None - name = it.walk(decorators,0).split(':') - if len(name) == 2: - direction = name[1] - - decorators = {'default': self.parameter_description_decorator, - 'para': self.paragraph_content_decorator} - description = it.walk(decorators, 0) - result[name[0]] = (direction,description) - return result - - - def _process_return_value_description(self, node): - result = None - ret = list() - - para = node.children.get('para') - if para is not None: - for p in para: - simplesect_list = p.children.get('simplesect') - if simplesect_list is None: - continue - for it in simplesect_list: - decorators = {'default': self.return_value_description_decorator, - 'para': self.parameter_name_decorator} - result = it.walk(decorators, 1) - if result is not None: - ret.append(result) - return ret - - - def _process_retval_description(self, node): - """ - retval descriptions reside inside detailed description section. - """ - para = node.children.get('para') - - result = None - ret = list() - if para is not None: - - for e in para: - param_list = e.children.get('parameterlist') - if param_list is None: - continue - for p in param_list: - kind = p.attributes['kind'] - if kind == 'retval': - - param_items = p.children.get('parameteritem') - if param_items is None: - continue - - - for it in param_items: - param_descr = it.children.get('parameterdescription') - if param_descr is not None: - val = param_descr[0].children.get('para') - - if val is not None: - val_descr = val[0].getContent() - - else: - val_descr ='' - - decorators = {'default': self.parameter_name_decorator} - - name = it.walk(decorators, 1).split(':') - - val = name[0] - result = " %s %s" % (val, val_descr) - ret.append (result) - return ret - - def return_warning_decorator(self, node, value): - if node.name == 'simplesect': - if node.attributes['kind'] == 'warning': - return value - else: - return None - - def _process_warning_description(self, node): - result = None - para = node.children.get('para') - if para is not None: - for p in para: - simplesect_list = p.children.get('simplesect') - if simplesect_list is None: - continue - for it in simplesect_list: - decorators = {'default': self.return_warning_decorator, - 'para': self.paragraph_content_decorator} - result = it.walk(decorators, 1) - # Assuming that only one Warning per function - if result is not None: - return result - return result - - def return_seealso_decorator(self, node, value): - if node.name == 'simplesect': - if node.attributes['kind'] == 'see': - return value - else: - return None - - def _process_seealso_description(self, node): - result = None - para = node.children.get('para') - if para is not None: - for p in para: - simplesect_list = p.children.get('simplesect') - if simplesect_list is None: - continue - for it in simplesect_list: - decorators = {'default': self.return_seealso_decorator, - 'para': self.paragraph_content_decorator} - result = it.walk(decorators, 1) - return result - - def return_version_decorator(self, node, value): - if node.name == 'simplesect': - if node.attributes['kind'] == 'version': - return value - else: - return None - - def _process_version_description(self, node): - result = None - para = node.children.get('para') - if para is not None: - for p in para: - simplesect_list = p.children.get('simplesect') - if simplesect_list is None: - continue - for it in simplesect_list: - decorators = {'default': self.return_version_decorator, - 'para': self.paragraph_content_decorator} - result = it.walk(decorators, 1) - if result is not None: - return result - return result - - def return_notes_decorator(self, node, value): - if node.name == 'simplesect': - if node.attributes['kind'] == 'note': - return value - else: - return None - - def _process_notes_description(self, node): - result = None - para = node.children.get('para') - if para is not None: - for p in para: - simplesect_list = p.children.get('simplesect') - if simplesect_list is None: - continue - for it in simplesect_list: - decorators = {'default': self.return_notes_decorator, - 'para': self.paragraph_content_decorator} - result = it.walk(decorators, 1) - if result is not None: - return result - return result - - def return_deprecated_decorator(self, node, value): - if node.name == 'xrefsect': - if node.attributes['id'].find('deprecated_') > -1: - xreftitle = node.children.get('xreftitle') - if xreftitle[0] is not None: - xrefdescr = node.children.get('xrefdescription') - deprecated_descr = "DEPRECATED %s" % xrefdescr[0].getContent() - return deprecated_descr - else: - return None - - def _process_deprecated_description(self, node): - result = None - para = node.children.get('para') - if para is not None: - for p in para: - xrefsect_list = p.children.get('xrefsect') - if xrefsect_list is None: - continue - for it in xrefsect_list: - decorators = {'default': self.return_deprecated_decorator, - 'para': self.paragraph_content_decorator} - result = it.walk(decorators, 1) - if result is not None: - return result - return result - - def break_into_lines(self, value, linelen=82): - breaks = range(0,len(value),linelen) + [len(value)] - result = list() - for (start,end) in zip(breaks[:-1],breaks[1:]): - result.append(value[start:end]) - result = '\n'.join(result) - - return result - - def _save(self, table, path = None): - if path is None: - f = sys.stdout - else: - f = open(path, 'w') - for l in table: - f.write('%s\n' % ','.join(l)) - if path is not None: - f.close() - - - -class DoxyFuncsTest(DoxyFuncs): - def __init__(self, xmlpath, rstpath): - super(DoxyFuncsTest,self).__init__(xmlpath) - self.target_dir = rstpath - outfile = '%s/%s' % (self.target_dir, 'out.txt') - self.tmp = open(outfile, 'w') - - def run_tests(self): - self.test_save() - - def test_run(self): - self.run() - - def test_save(self): - self.run() - templates = {'function': 'func_document.tmpl'} - self.save(templates, self.target_dir) - -if __name__ == '__main__': - tester = DoxyFuncsTest(xmlpath, rstpath) - tester.run_tests() - diff --git a/doc/rst_tools/doxybuilder_types.py b/doc/rst_tools/doxybuilder_types.py deleted file mode 100644 index c7a38f9d2..000000000 --- a/doc/rst_tools/doxybuilder_types.py +++ /dev/null @@ -1,370 +0,0 @@ -''' - Copyright 2011 by the Massachusetts - Institute of Technology. All Rights Reserved. - - Export of this software from the United States of America may - require a specific license from the United States Government. - It is the responsibility of any person or organization contemplating - export to obtain such a license before exporting. - - WITHIN THAT CONSTRAINT, permission to use, copy, modify, and - distribute this software and its documentation for any purpose and - without fee is hereby granted, provided that the above copyright - notice appear in all copies and that both that copyright notice and - this permission notice appear in supporting documentation, and that - the name of M.I.T. not be used in advertising or publicity pertaining - to distribution of the software without specific, written prior - permission. Furthermore if you modify this software you must label - your software as modified software and not distribute it in such a - fashion that it might be confused with the original M.I.T. software. - M.I.T. makes no representations about the suitability of - this software for any purpose. It is provided "as is" without express - or implied warranty. -''' - -import sys -import os -import re - -from lxml import etree - -from docmodel import * - - -class DoxyTypes(object): - def __init__(self, xmlpath): - self.xmlpath = xmlpath - - def run_compound(self, filename, include=None): - path = '%s/%s' % (self.xmlpath,filename) - tree = etree.parse(path) - root = tree.getroot() - - brief_node = root.xpath('./compounddef/briefdescription')[0] - brief_description = self._get_brief_description(brief_node) - details_node = root.xpath('./compounddef/detaileddescription')[0] - detailed_description = self._get_detailed_description(details_node) - - fields = list() - for node in root.iterfind(".//memberdef[@kind]"): - data = {} - kind = node.attrib['kind'] - if include is None or kind in include: - if kind == 'variable': - data = self._process_variable_node(node) - else: - pass - fields.append(data) - - result = {'brief_description': brief_description, - 'detailed_description': detailed_description, - 'attributes': fields} - - return result - - - - def run(self, filename, include=None): - """ - Parses xml file generated by doxygen. - - @param filename: doxygen xml file name - @param include: members sections to include, in None -- include all - """ - path = '%s/%s' % (self.xmlpath,filename) - tree = etree.parse(path) - root = tree.getroot() - result = list() - for node in root.iterfind(".//memberdef[@kind]"): - data = {} - kind = node.attrib['kind'] - if include is None or kind in include: - if kind == 'typedef': - data = self._process_typedef_node(node) - elif kind == 'variable': - data = self._process_variable_node(node) - elif kind == 'define': - data = self._process_define_node(node) - result.append(data) - print "\nnumber of types processed ==> " , len(result) - return result - - - def _process_typedef_node(self, node): - t_name = node.xpath('./name/text()')[0] - - print t_name - - t_Id = node.attrib['id'] - t_definition = node.xpath('./definition/text()')[0] - t_type = self._process_type_node(node.xpath("./type")[0]) - brief_node = node.xpath('./briefdescription')[0] - t_brief = self._get_brief_description(brief_node) - details_node = node.xpath('./detaileddescription')[0] - t_detailed = self._get_detailed_description(details_node) - # remove macros - t_definition = re.sub('KRB5_CALLCONV_C', '', t_definition) - t_definition = re.sub('KRB5_CALLCONV', '', t_definition) - t_definition = re.sub('\*', '\\*', t_definition) - # handle fp - if t_type[1].find('(') >= 0: - t_type = (t_type[0],None) - - typedef_descr = {'category': 'composite', - 'definition': t_definition, - 'name': t_name, - 'Id': t_Id, - 'initializer': '', - 'type': t_type[1], - 'short_description': t_brief, - 'long_description': t_detailed, - 'attributes': list() - } - if t_type[0] is not None : - filename = '%s.xml' % t_type[0] - path = '%s/%s' % (self.xmlpath,filename) - if not os.path.exists(path): - # nothing can be done - return typedef_descr - - compound_info = self.run_compound(filename) - if compound_info is not None: - brief_description = compound_info.get('brief_description') - if brief_description is not None and len(brief_description): - # override brief description - typedef_descr['short_description'] = brief_description - detailed_description = compound_info.get('detailed_description') - if detailed_description is not None and len(detailed_description): - # check if this is not a duplicate - if detailed_description.find(t_detailed) < 0: - typedef_descr['long_description'] = '%s\n%s' % \ - (detailed_description, - typedef_descr['long_description']) - typedef_descr['attributes'] = compound_info['attributes'] - return typedef_descr - - def _process_variable_node(self, node): - v_name = node.xpath('./name/text()')[0] - v_Id = node.attrib['id'] - v_definition = node.xpath('./definition/text()')[0] - v_type = self._process_type_node(node.xpath("./type")[0]) - brief_node = node.xpath('./briefdescription')[0] - v_brief = self._get_brief_description(brief_node) - details_node = node.xpath('./detaileddescription')[0] - detailed_description = self._get_detailed_description(details_node) - # remove macros - v_definition = re.sub('KRB5_CALLCONV_C', '', v_definition) - v_definition = re.sub('KRB5_CALLCONV', '', v_definition) - v_definition = re.sub('\*', '\\*', v_definition) - - variable_descr = {'category': 'variable', - 'definition': v_definition, - 'name': v_name, - 'Id': v_Id, - 'initializer': '', - 'type': v_type[1], - 'short_description': v_brief, - 'long_description': detailed_description, - 'attributes': list() - } - - return variable_descr - - def _process_define_node(self, node): - d_name = node.xpath('./name/text()')[0] - print d_name - d_initializer = '' - d_type = '' - d_signature = '' - - # Process param/defname node - if len(node.xpath('./param/defname')) > 0: - prm_str = '' - prm_list = list() - for p in node.xpath("./param"): - x = self._process_paragraph_content(p) - if x is not None and len(x): - prm_list.append(x) - if prm_list is not None: - prm_str = prm_str.join(prm_list) - d_signature = " %s (%s) " % (d_name , prm_str) - d_signature = re.sub(', \)', ')', d_signature) - - if len(node.xpath('./initializer')) > 0: - len_ref = len(node.xpath('./initializer/ref')) - if len(node.xpath('./initializer/ref')) > 0: - d_type = self._process_type_node(node.xpath("./initializer/ref")[0]) - if len(d_type) > 0: - len_text = len(node.xpath('./initializer/text()')) - if len_text == 0 and d_type[1]: - d_initializer = d_type[1] - if len_text > 0 and len(node.xpath('./initializer/text()')[0]) > 0: - d_initializer = node.xpath('./initializer/text()')[0] + d_type[1] - if len_text > 1: - if node.xpath('./initializer/text()')[1] is not None: - d_initializer = d_initializer + node.xpath('./initializer/text()')[1] - else: - d_initializer = node.xpath('./initializer/text()')[0] - d_Id = node.attrib['id'] - brief_node = node.xpath('./briefdescription')[0] - d_brief = self._get_brief_description(brief_node) - details_node = node.xpath('./detaileddescription')[0] - detailed_description = self._get_detailed_description(details_node) - - define_descr = {'category': 'composite', - 'definition': '', - 'name': d_name, - 'name_signature': d_signature, - 'Id': d_Id, - 'initializer': d_initializer, - 'type': '', - 'short_description': d_brief, - 'long_description': detailed_description, - 'attributes': list() - } - - return define_descr - - - def _get_brief_description(self, node): - result = list() - for p in node.xpath("./para"): - x = self._process_paragraph_content(p) - if x is not None and len(x): - result.append(x) - result = '\n'.join(result) - - return result - - - def _get_detailed_description(self, node): - """ - Description node is comprised of ... sections. - There are few types of these sections: - a) Content section - b) Return value section -- skip - c) Parameter list section -- skip - @param node: detailed description node - """ - result = list() - for p in node.xpath("./para"): - if len(p.xpath("./simplesect[@kind='return']")): - continue - elif len(p.xpath("./parameterlist[@kind='param']")): - continue - else: - x = self._process_paragraph_content(p) - result.append(x) - result = '\n'.join(result) - - return result - - def _process_paragraph_content(self, node): - - result = list() - content = node.xpath(".//text()") - for e in content: - if node is e.getparent(): - result.append(e.strip()) - elif e.getparent().tag == 'ref': - if e.is_tail: - result.append(e.strip()) - else: - result.append(':c:type:`%s`' % e.strip()) - elif e.getparent().tag == 'emphasis': - if e.is_tail: - result.append(e.strip()) - else: - result.append('*%s*' % e.strip()) - elif e.getparent().tag == 'computeroutput': - if e.is_tail: - result.append(e.strip()) - else: - result.append('*%s*' % e.strip()) - elif e.getparent().tag == 'defname': - result.append('%s, ' % e.strip()) - result = ' '.join(result) - - return result - - def _process_type_node(self, node): - """ - Type node has form - type_string - for build in types and - - - 'type_name' - - postfix (ex. *, **m, etc.) - - for user defined types. - """ - p_id = node.xpath("./ref/@refid") - if len(p_id) == 1: - p_id = p_id[0] - elif len(p_id) == 0: - p_id = None - p_type = ' '.join(node.xpath(".//text()")) - - # remove macros - p_type = re.sub('KRB5_CALLCONV_C', ' ', p_type) - p_type = re.sub('KRB5_CALLCONV', ' ', p_type) - - return (p_id,p_type) - - def save(self, obj, templates, target_dir): - template_path = templates[obj.category] - outpath = '%s/%s.rst' % (target_dir,obj.name) - obj.save(outpath, template_path) - - - -class DoxyTypesTest(DoxyTypes): - def __init__(self, xmlpath, rstpath): - self.templates = { 'composite': 'type_document.tmpl'} - self.target_dir = rstpath - - super(DoxyTypesTest,self).__init__(xmlpath) - - def run_tests(self): - print "Process typedef's" - self.test_process_typedef_node() - print "Process define's" - self.test_process_define_node() - - def test_run(self): - filename = 'krb5_8hin.xml' - self.run(filename) - - def test_process_variable_node(self): - filename = 'struct__krb5__octet__data.xml' - result = self.run(filename, include=['variable']) - - def test_process_typedef_node(self): - # run parser for typedefs - filename = 'krb5_8hin.xml' - result = self.run(filename, include=['typedef']) - target_dir = '%s/types' % (self.target_dir) - if not os.path.exists(target_dir): - os.makedirs(target_dir, 0755) - for t in result: - obj = DocModel(**t) - self.save(obj, self.templates, target_dir) - - def test_process_define_node(self): - # run parser for define's - filename = 'krb5_8hin.xml' - result = self.run(filename, include=['define']) - target_dir = '%s/macros' % (self.target_dir) - if not os.path.exists(target_dir): - os.makedirs(target_dir, 0755) - for t in result: - obj = DocModel(**t) - tmpl = {'composite': 'define_document.tmpl'} - self.save(obj, tmpl, target_dir) - -if __name__ == '__main__': - - tester = DoxyTypesTest( xml_inpath, rst_outpath) - tester.run_tests() diff --git a/doc/rst_tools/func_document.tmpl b/doc/rst_tools/func_document.tmpl deleted file mode 100644 index b9b63d115..000000000 --- a/doc/rst_tools/func_document.tmpl +++ /dev/null @@ -1,99 +0,0 @@ -#if $function.short_description is not None - #set $title = $function.name + ' - ' + $function.short_description -#else - #set $title = $function.name -#end if -$title -#echo ''.join(['=']*len($title)) # - -.. - -.. c:function:: $signature - -.. - - -:param: - -#for $param in $function.parameters: - #if $param.name is '' - #continue - #end if - #if $param.direction is not None - #set name_description = '**[%s]** **%s**' % ($param.direction, $param.name) - #else - #set name_description = '**%s**' % $param.name - #end if - #if $param.description is not None - #set $description= ' - ' + $param.description - #else - #set $description='' - #end if - $name_description$description - -#end for - -.. - -#if len($function.retval_description) > 0 - -:retval: -#for $retval in $function.retval_description: - - $retval -#end for -#end if - -#if len($function.return_description) > 0 - -:return: -#for $retval in $function.return_description: - - $retval -#end for -#end if - -.. - -#if $function.deprecated_description is not None - -$function.deprecated_description -#end if - - - - -#if $function.long_description is not None - - -$function.long_description - -#end if - - -.. - -#if $function.sa_description is not None -.. seealso:: - $function.sa_description -#end if - - -#if $function.warn_description is not None or $function.notes_description is not None - - -#if $function.warn_description is not None -.. warning:: - $function.warn_description -#end if - -#if $function.notes_description is not None -.. note:: - $function.notes_description -#end if - -#end if - -#if $function.version_num is not None -.. note:: - $function.version_num -#end if - diff --git a/doc/rst_tools/type_document.tmpl b/doc/rst_tools/type_document.tmpl deleted file mode 100644 index 5987fa762..000000000 --- a/doc/rst_tools/type_document.tmpl +++ /dev/null @@ -1,43 +0,0 @@ -.. highlightlang:: c - -.. $composite.struct_reference($composite.name): - -#set $title = $composite.name -$title -#echo ''.join(['=']*len($title)) # - -.. -.. c:type:: $composite.name -.. - -#if $composite.short_description is not None and len($composite.short_description) -$composite.short_description -#end if - -$composite.long_description - -Declaration ------------- - -$composite.definition - -#if $composite.Id is not None -#if len($composite.attributes) - -Members ---------- - -#end if - -#for $attr in $composite.attributes: -#if $attr.name is not None -.. c:member:: $attr.type $composite.name.$attr.name - - $attr.short_description -#if $attr.long_description is not None - $attr.long_description -#end if - -#end if -#end for -#end if diff --git a/doc/tools/README b/doc/tools/README new file mode 100644 index 000000000..cca78d368 --- /dev/null +++ b/doc/tools/README @@ -0,0 +1,65 @@ +How to deploy the Doxygen output in Sphinx project. +==================================================== + +The text below is meant to give the instructions on how to incorporate MIT Kerberos API reference documentation into Sphinx document hierarchy. The Sphinx API documentation can be constructed with (Part B) or without (Part A) the bridge to the original Doxygen HTML output. + +Pre-requisites: +- python 2.5+ with Cheetah, lxml and xml extension modules installed; +- For part B only: + - Sphinx “doxylink” extension; + - Doxygen HTML output + + +Part A: Transforming Doxygen XML output into reStructuredText (rst) without the bridge to Doxygen HTML output. + +1. Delete lines containing text "Doxygen reference" from the template files func_document.tmpl and type_document.tmpl; + +2. In the Doxygen configuration file set GENERATE_XML to YES. Generate Doxygen XML output; + +3. Suppose the Doxygen XML output is located in doxy_xml_dir and the desired output directory is rst_dir. + Run: + python doxy.py –i doxy_xml_dir –o rst_dir –t func + This will result in the storing of the API function documentation files in rst format in the rst_dir. The file names are constructed based on the function name. For example, the file for krb5_build_principal() will be krb5_build_principal.rst + + Run: + python doxy.py –i doxy_xml_dir –o rst_dir –t typedef + It is similar to the API function conversion, but for data types. The result will be stored under rst_dir/types directory + + Alternatively, running + python doxy.py –i doxy_xml_dir –o rst_dir + or + python doxy.py –i doxy_xml_dir –o rst_dir -t all + converts Doxygen XML output into reStructuredText format files both for API functions and data types; + +4. In krb_appldev/index.rst add the following section to point to the API references: + + .. toctree:: + :maxdepth: 1 + + refs/index.rst + +5. Copy the content of rst_dir into krb_appldev/refs/api/ directory and rst_dir/types into krb_appldev/refs/types directory; + +6. Rebuild Sphinx source: + sphinx-build source_dir build_dir + + + + +Part B: Bridge to Doxygen HTML output. + +1. Transform Doxygen XML output into reStructuredText. + In src/Doxygen configuration file request genetation of the tag file and XML output: + GENERATE_TAGFILE = krb5doxy.tag + GENERATE_XML = YES + +2. Modify Sphinx conf.py file to point to the “doxylink” extension and Doxygen tag file: + extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.doxylink'] + doxylink = { ' krb5doxy' : ('/tmp/krb5doxy.tag, ' doxy_html_dir ') } + + where doxy_html_dir is the location of the Doxygen HTML output + +3. Continue with steps 3 - 6 of Part A. + + + diff --git a/doc/tools/define_document.tmpl b/doc/tools/define_document.tmpl new file mode 100644 index 000000000..8bf2fd393 --- /dev/null +++ b/doc/tools/define_document.tmpl @@ -0,0 +1,27 @@ +.. highlightlang:: c + +.. $composite.macro_reference($composite.name): + +#set $title = $composite.name +$title +#echo ''.join(['=']*len($title)) # + +.. +.. data:: $composite.name +.. + +#if $composite.short_description is not None and len($composite.short_description) +$composite.short_description +#end if + +$composite.long_description + +#if $composite.name_signature is not None and len($composite.name_signature) +#echo ''.join(['=']*len($composite.name_signature)) + '== ======================' # +$composite.name_signature $composite.initializer +#echo ''.join(['=']*len($composite.name_signature)) + '== ======================' # +#else +#echo ''.join(['=']*len($composite.name)) + '=== ======================' # +$composite.name $composite.initializer +#echo ''.join(['=']*len($composite.name)) + '=== ======================' # +#end if diff --git a/doc/tools/docmodel.py b/doc/tools/docmodel.py new file mode 100644 index 000000000..ef4cd76c3 --- /dev/null +++ b/doc/tools/docmodel.py @@ -0,0 +1,252 @@ +''' + Copyright 2011 by the Massachusetts + Institute of Technology. All Rights Reserved. + + Export of this software from the United States of America may + require a specific license from the United States Government. + It is the responsibility of any person or organization contemplating + export to obtain such a license before exporting. + + WITHIN THAT CONSTRAINT, permission to use, copy, modify, and + distribute this software and its documentation for any purpose and + without fee is hereby granted, provided that the above copyright + notice appear in all copies and that both that copyright notice and + this permission notice appear in supporting documentation, and that + the name of M.I.T. not be used in advertising or publicity pertaining + to distribution of the software without specific, written prior + permission. Furthermore if you modify this software you must label + your software as modified software and not distribute it in such a + fashion that it might be confused with the original M.I.T. software. + M.I.T. makes no representations about the suitability of + this software for any purpose. It is provided "as is" without express + or implied warranty. +''' +import re + +from Cheetah.Template import Template + +class Attribute(object): + def __init__(self, **argkw): + self.definition = argkw.get('definition') + self.name = argkw.get('name') + self.type = argkw.get('type') + self.typeId = argkw.get('typeId') + self.short_description = argkw.get('short_description') + self.long_description = argkw.get('long_description') + self.version = argkw.get('version') + + def __repr__(self): + result = list() + for (attr,value) in self.__dict__.iteritems(): + result.append('%s=%s' % (attr,value)) + return 'Attribute: %s' % ','.join(result) + + +class CompositeType(): + def __init__(self, **argkw): + self.category = 'composite' + self.definition = argkw.get('definition') + self.name = argkw.get('name') + self.name_signature = argkw.get('name_signature') + self.Id = argkw.get('Id') + self.initializer = argkw.get('initializer') + self.active = argkw.get('active', False) + self.version = argkw.get('version') + self.return_type = argkw.get('return_type') + self.short_description = argkw.get('short_description') + self.long_description = argkw.get('long_description') + self.friends = argkw.get('friends') + self.type = argkw.get('type') + self.attributes = self._setAttributes(argkw.get('attributes')) + + def __repr__(self): + result = list() + for (attr,value) in self.__dict__.iteritems(): + if attr == 'attributes': + if value is not None: + attributes = ['%s' % a for a in value] + value = '\n %s' % '\n '.join(attributes) + + result.append('%s: %s' % (attr,value)) + result = '\n'.join(result) + + return result + + def _setAttributes(self, attributes): + result = None + if attributes is not None: + result = list() + for a in attributes: + result.append(Attribute(**a)) + + return result + + def struct_reference(self, name): + result = re.sub(r'_', '-', name) + result = '_%s-struct' % result + + return result + + def macro_reference(self, name): + result = re.sub(r'_', '-', name) + result = '_%s-data' % result + + return result + +class Parameter(object): + def __init__(self, **argkw): + self.seqno = argkw.get('seqno') + self.name = argkw.get('name') + self.direction = argkw.get('direction') + self.type = argkw.get('type') + self.typeId = argkw.get('typeId') + self.description = argkw.get('description') + self.version = argkw.get('version') + + def __repr__(self): + content = (self.name,self.direction,self.seqno,self.type,self.typeId,self.description) + return 'Parameter: name=%s,direction=%s,seqno=%s,type=%s,typeId=%s,descr=%s' % content + +class Function(object): + def __init__(self, **argkw): + self.category = 'function' + self.name = argkw.get('name') + self.Id = argkw.get('Id') + self.active = argkw.get('active', False) + self.version = argkw.get('version') + self.parameters = self._setParameters(argkw.get('parameters')) + self.return_type = argkw.get('return_type') + self.return_description = argkw.get('return_description') + self.retval_description = argkw.get('retval_description') + self.warn_description = argkw.get('warn_description') + self.sa_description = argkw.get('sa_description') + self.notes_description = argkw.get('notes_description') + self.version_num = argkw.get('version_num') + self.short_description = argkw.get('short_description') + self.long_description = argkw.get('long_description') + self.deprecated_description = argkw.get('deprecated_description') + self.friends = argkw.get('friends') + + def _setParameters(self, parameters): + result = None + if parameters is not None: + result = list() + for p in parameters: + result.append(Parameter(**p)) + + return result + + def getObjectRow(self): + result = [str(self.Id), + self.name, + self.category] + + return ','.join(result) + + def getObjectDescriptionRow(self): + result = [self.Id, + self.active, + self.version, + self.short_description, + self.long_description] + + return ','.join(result) + + def getParameterRows(self): + result = list() + for p in self.parameters: + p_row = [self.Id, + p.name, + p.seqno, + p.type, + p.typeId, + p.description, + p.version] + result.append(','.join(p_row)) + + return '\n'.join(result) + + def __repr__(self): + lines = list() + lines.append('Category: %s' % self.category) + lines.append('Function name: %s' % self.name) + lines.append('Function Id: %s' % self.Id) + parameters = [' %s' % p for p in self.parameters] + lines.append('Parameters:\n%s' % '\n'.join(parameters)) + lines.append('Function return type: %s' % self.return_type) + lines.append('Function return type description:\n%s' % self.return_description) + lines.append('Function retval description:\n%s' % self.retval_description) + lines.append('Function short description:\n%s' % self.short_description) + lines.append('Function long description:\n%s' % self.long_description) + lines.append('Warning description:\n%s' % self.warn_description) + lines.append('See also description:\n%s' % self.sa_description) + lines.append('NOTE description:\n%s' % self.notes_description) + lines.append('Version introduced:\n%s' % self.version_num) + lines.append('Deprecated description:\n%s' % self.deprecated_description) + result = '\n'.join(lines) + + return result + + +class DocModel(object): + def __init__(self, **argkw): + if len(argkw): + self.name = argkw['name'] + if argkw['category'] == 'function': + self.category = 'function' + self.function = Function(**argkw) + elif argkw['category'] == 'composite': + self.category = 'composite' + self.composite = CompositeType(**argkw) + + def __repr__(self): + obj = getattr(self,self.category) + print type(obj) + return str(obj) + + def signature(self): + param_list = list() + for p in self.function.parameters: + if p.type is "... " : + param_list.append('%s %s' % (p.type,' ')) + else: + param_list.append('%s %s' % (p.type, p.name)) + param_list = ', '.join(param_list) + result = '%s %s(%s)' % (self.function.return_type, + self.function.name, param_list) + + return result + + def save(self, path, template_path): + f = open(template_path, 'r') + t = Template(f.read(),self) + out = open(path, 'w') + out.write(str(t)) + out.close() + f.close() + + +class DocModelTest(DocModel): + def __init__(self): + doc_path = '../docutil/example.yml' + argkw = yaml.load(open(doc_path,'r')) + super(DocModelTest,self).__init__(**argkw) + + def run_tests(self): + self.test_save() + + def test_print(self): + print 'testing' + print self + + + def test_save(self): + template_path = '../docutil/function2edit.html' + + path = '/var/tsitkova/Sources/v10/trunk/documentation/test_doc.html' + + self.save(path, template_path) + +if __name__ == '__main__': + tester = DocModelTest() + tester.run_tests() diff --git a/doc/tools/doxy.py b/doc/tools/doxy.py new file mode 100644 index 000000000..c8a4b9dad --- /dev/null +++ b/doc/tools/doxy.py @@ -0,0 +1,64 @@ +''' + Copyright 2011 by the Massachusetts + Institute of Technology. All Rights Reserved. + + Export of this software from the United States of America may + require a specific license from the United States Government. + It is the responsibility of any person or organization contemplating + export to obtain such a license before exporting. + + WITHIN THAT CONSTRAINT, permission to use, copy, modify, and + distribute this software and its documentation for any purpose and + without fee is hereby granted, provided that the above copyright + notice appear in all copies and that both that copyright notice and + this permission notice appear in supporting documentation, and that + the name of M.I.T. not be used in advertising or publicity pertaining + to distribution of the software without specific, written prior + permission. Furthermore if you modify this software you must label + your software as modified software and not distribute it in such a + fashion that it might be confused with the original M.I.T. software. + M.I.T. makes no representations about the suitability of + this software for any purpose. It is provided "as is" without express + or implied warranty. +''' +import sys +import os +import re +from optparse import OptionParser + + +from doxybuilder_types import * +from doxybuilder_funcs import * + + +def processOptions(): + usage = "\n\t\t%prog -t type -i in_dir -o out_dir" + description = "Description:\n\tProcess doxygen output for c-types and/or functions" + parser = OptionParser(usage=usage, description=description) + + parser.add_option("-t", "--type", type="string", dest="action_type", help="process typedef and/or function. Possible choices: typedef, func, all. Default: all.", default="all") + parser.add_option("-i", "--in", type="string", dest="in_dir", help="input directory") + parser.add_option("-o", "--out", type="string", dest= "out_dir", help="output directory. Note: The subdirectory ./types will be created for typedef") + + (options, args) = parser.parse_args() + action = options.action_type + in_dir = options.in_dir + out_dir = options.out_dir + + + if in_dir is None or out_dir is None: + parser.error("Input and output directories are required") + + if action == "all" or action == "typedef": + tester = DoxyTypesTest(in_dir, out_dir) + tester.run_tests() + + if action == "all" or action == "func" or action == "function": + tester = DoxyFuncsTest(in_dir, out_dir) + tester.run_tests() + + +if __name__ == '__main__': + parser = processOptions() + + diff --git a/doc/tools/doxybuilder_funcs.py b/doc/tools/doxybuilder_funcs.py new file mode 100644 index 000000000..13331f8ba --- /dev/null +++ b/doc/tools/doxybuilder_funcs.py @@ -0,0 +1,595 @@ +''' + Copyright 2011 by the Massachusetts + Institute of Technology. All Rights Reserved. + + Export of this software from the United States of America may + require a specific license from the United States Government. + It is the responsibility of any person or organization contemplating + export to obtain such a license before exporting. + + WITHIN THAT CONSTRAINT, permission to use, copy, modify, and + distribute this software and its documentation for any purpose and + without fee is hereby granted, provided that the above copyright + notice appear in all copies and that both that copyright notice and + this permission notice appear in supporting documentation, and that + the name of M.I.T. not be used in advertising or publicity pertaining + to distribution of the software without specific, written prior + permission. Furthermore if you modify this software you must label + your software as modified software and not distribute it in such a + fashion that it might be confused with the original M.I.T. software. + M.I.T. makes no representations about the suitability of + this software for any purpose. It is provided "as is" without express + or implied warranty. +''' +import sys +import re + +from collections import defaultdict +from xml.sax import make_parser +from xml.sax.handler import ContentHandler +from docmodel import * + +class DocNode(object): + """ + Represents the structure of xml node. + """ + def __init__(self, name): + """ + @param node: name - the name of a node. + @param attributes: a dictionary populated with attributes of a node + @param children: a dictionary with lists of children nodes. Nodes + in lists are ordered as they appear in a document. + @param content: a content of xml node represented as a list of + tuples [(type,value)] with type = ['char'|'element']. + If type is 'char' then the value is a character string otherwise + it is a reference to a child node. + """ + self.name = name + self.content = list() + self.attributes = dict() + self.children = defaultdict(list) + + def walk(self, decorators, sub_ws, stack=[]): + result = list() + decorator = decorators.get(self.name, decorators['default']) + stack.append(decorators['default']) + decorators['default'] = decorator + + for (obj_type,obj) in self.content: + if obj_type == 'char': + if obj != '': + result.append(obj) + else: + partial = obj.walk(decorators,1, stack) + if partial is not None: + result.append(' %s ' % partial) + decorators['default'] = stack.pop() + result = decorator(self, ''.join(result)) + if result is not None: + if sub_ws == 1: + result = re.sub(r'[ ]+', r' ', result) + else: + result = result.strip() + + return result + + def getContent(self): + decorators = {'default': lambda node,value: value} + result = self.walk(decorators, 1) + if len(result) == 0: + result = None + + return result + + def __repr__(self): + result = ['Content: %s' % self.content] + + for (key,value) in self.attributes.iteritems(): + result.append('Attr: %s = %s' % (key,value)) + for (key,value) in self.children.iteritems(): + result.append('Child: %s,%i' % (key,len(value))) + + return '\n'.join(result) + +class DoxyContenHandler(object, ContentHandler): + def __init__(self, builder): + self.builder = builder + self.counters = defaultdict(int) + self._nodes = None + self._current = None + + def startDocument(self): + pass + + def endDocument(self): + import sys + + def startElement(self, name, attrs): + if name == self.builder.toplevel: + self._nodes = [] + + if name == 'memberdef': + kind = attrs.get('kind') + if kind is None: + raise ValueError('Kind is not defined') + self.counters[kind] += 1 + + if self._nodes is None: + return + + node = DocNode(name) + for (key,value) in attrs.items(): + node.attributes[key] = value + if self._current is not None: + self._current.children[name].append(node) + self._nodes.append(self._current) + self._current = node + + def characters(self, content): + + if self._current is not None: + self._current.content.append(('char',content.strip())) + + def endElement(self, name): + if name == self.builder.toplevel: + assert(len(self._nodes) == 0) + self._nodes = None + self.builder.document.append(self._current) + self._current = None + else: + if self._nodes is not None: + node = self._current + self._current = self._nodes.pop() + self._current.content.append(('element',node)) + + +class XML2AST(object): + """ + Translates XML document into Abstract Syntax Tree like representation + The content of document is stored in self.document + """ + def __init__(self, xmlpath, toplevel='doxygen'): + self.document = list() + self.toplevel = toplevel + self.parser = make_parser() + handler = DoxyContenHandler(self) + self.parser.setContentHandler(handler) + filename = 'krb5_8hin.xml' + filepath = '%s/%s' % (xmlpath,filename) + self.parser.parse(open(filepath,'r')) + + +class DoxyFuncs(XML2AST): + def __init__(self, path): + super(DoxyFuncs, self).__init__(path,toplevel='memberdef') + self.objects = list() + + def run(self): + for node in self.document: + self.process(node) + print "\nnumber of functions processed ===> ",len(self.objects) + + def process(self, node): + node_type = node.attributes['kind'] + if node_type == 'function': + data = self._process_function_node(node) + else: + print 'not processing node: %s' % node_type + return + + self.objects.append(DocModel(**data)) + + def save(self, templates, target_dir): + for obj in self.objects: + template_path = templates[obj.category] + outpath = '%s/%s.rst' % (target_dir,obj.name) + obj.save(outpath, template_path) + + + def _process_function_node(self, node): + f_name = node.children['name'][0].getContent() + print f_name + f_Id = node.attributes['id'] + f_ret_type = self._process_type_node(node.children['type'][0]) + f_brief = node.children['briefdescription'][0].getContent() + f_detailed = node.children['detaileddescription'][0] + detailed_description = self._process_description_node(f_detailed) + return_value_description = self._process_return_value_description(f_detailed) + retval_description = self._process_retval_description(f_detailed) + warning_description = self._process_warning_description(f_detailed) + seealso_description = self._process_seealso_description(f_detailed) + notes_description = self._process_notes_description(f_detailed) + f_version = self._process_version_description(f_detailed) + deprecated_description = self._process_deprecated_description(f_detailed) + param_description_map = self.process_parameter_description(f_detailed) + f_definition = node.children['definition'][0].getContent() + f_argsstring = node.children['argsstring'][0].getContent() + + function_descr = {'category': 'function', + 'name': f_name, + 'Id': f_Id, + 'return_type': f_ret_type[1], + 'return_description': return_value_description, + 'retval_description': retval_description, + 'sa_description': seealso_description, + 'warn_description': warning_description, + 'notes_description': notes_description, + 'short_description': f_brief, + 'version_num': f_version, + 'long_description': detailed_description, + 'deprecated_description': deprecated_description, + 'parameters': list()} + + parameters = function_descr['parameters'] + for (i,p) in enumerate(node.children['param']): + type_node = p.children['type'][0] + p_type = self._process_type_node(type_node) + if p_type[1].find('...') > -1 : + p_name = '' + else: + p_name = None + p_name_node = p.children.get('declname') + if p_name_node is not None: + p_name = p_name_node[0].getContent() + (p_direction,p_descr) = param_description_map.get(p_name,(None,None)) + + param_descr = {'seqno': i, + 'name': p_name, + 'direction': p_direction, + 'type': p_type[1], + 'typeId': p_type[0], + 'description': p_descr} + parameters.append(param_descr) + result = Function(**function_descr) + print >> self.tmp, result + + return function_descr + + def _process_type_node(self, type_node): + """ + Type node has form + type_string + for build in types and + + + 'type_name' + + postfix (ex. *, **m, etc.) + + for user defined types. + """ + type_ref_node = type_node.children.get('ref') + if type_ref_node is not None: + p_type_id = type_ref_node[0].attributes['refid'] + else: + p_type_id = None + p_type = type_node.getContent() + # remove some macros + p_type = re.sub('KRB5_ATTR_DEPRECATED', '', p_type) + p_type = re.sub('KRB5_CALLCONV_C', '', p_type) + p_type = re.sub('KRB5_CALLCONV_WRONG', '', p_type) + p_type = re.sub('KRB5_CALLCONV', '', p_type) + p_type = p_type.strip() + + return (p_type_id, p_type) + + def _process_description_node(self, node): + """ + Description node is comprised of ... sections + """ + para = node.children.get('para') + result = list() + if para is not None: + decorators = {'default': self.paragraph_content_decorator} + for e in para: + result.append(str(e.walk(decorators, 1))) + result.append('\n') + result = '\n'.join(result) + + return result + + def return_value_description_decorator(self, node, value): + if node.name == 'simplesect': + if node.attributes['kind'] == 'return': + cont = set() + cont = node.getContent() + return value + else: + return None + + def paragraph_content_decorator(self, node, value): + if node.name == 'para': + return value + '\n' + elif node.name == 'simplesect': + if node.attributes['kind'] == 'return': + return None + elif node.name == 'ref': + if value.find('()') >= 0: + # functions + return ':c:func:' + '`' + value + '`' + else: + # macro's + return ':data:' + '`' + value + '`' + elif node.name == 'emphasis': + return '*' + value + '*' + elif node.name == 'itemizedlist': + return '\n' + value + elif node.name == 'listitem': + return '\n\t - ' + value + '\n' + elif node.name == 'computeroutput': + return '**' + value + '**' + else: + return None + + def parameter_name_decorator(self, node, value): + if node.name == 'parametername': + direction = node.attributes.get('direction') + if direction is not None: + value = '%s:%s' % (value,direction) + return value + + elif node.name == 'parameterdescription': + return None + else: + return value + + def parameter_description_decorator(self, node, value): + if node.name == 'parameterdescription': + return value + elif node.name == 'parametername': + return None + else: + return value + + def process_parameter_description(self, node): + """ + Parameter descriptions reside inside detailed description section. + """ + para = node.children.get('para') + result = dict() + if para is not None: + for e in para: + + param_list = e.children.get('parameterlist') + if param_list is None: + continue + param_items = param_list[0].children.get('parameteritem') + if param_items is None: + continue + for it in param_items: + decorators = {'default': self.parameter_name_decorator} + direction = None + name = it.walk(decorators,0).split(':') + if len(name) == 2: + direction = name[1] + + decorators = {'default': self.parameter_description_decorator, + 'para': self.paragraph_content_decorator} + description = it.walk(decorators, 0) + result[name[0]] = (direction,description) + return result + + + def _process_return_value_description(self, node): + result = None + ret = list() + + para = node.children.get('para') + if para is not None: + for p in para: + simplesect_list = p.children.get('simplesect') + if simplesect_list is None: + continue + for it in simplesect_list: + decorators = {'default': self.return_value_description_decorator, + 'para': self.parameter_name_decorator} + result = it.walk(decorators, 1) + if result is not None: + ret.append(result) + return ret + + + def _process_retval_description(self, node): + """ + retval descriptions reside inside detailed description section. + """ + para = node.children.get('para') + + result = None + ret = list() + if para is not None: + + for e in para: + param_list = e.children.get('parameterlist') + if param_list is None: + continue + for p in param_list: + kind = p.attributes['kind'] + if kind == 'retval': + + param_items = p.children.get('parameteritem') + if param_items is None: + continue + + + for it in param_items: + param_descr = it.children.get('parameterdescription') + if param_descr is not None: + val = param_descr[0].children.get('para') + + if val is not None: + val_descr = val[0].getContent() + + else: + val_descr ='' + + decorators = {'default': self.parameter_name_decorator} + + name = it.walk(decorators, 1).split(':') + + val = name[0] + result = " %s %s" % (val, val_descr) + ret.append (result) + return ret + + def return_warning_decorator(self, node, value): + if node.name == 'simplesect': + if node.attributes['kind'] == 'warning': + return value + else: + return None + + def _process_warning_description(self, node): + result = None + para = node.children.get('para') + if para is not None: + for p in para: + simplesect_list = p.children.get('simplesect') + if simplesect_list is None: + continue + for it in simplesect_list: + decorators = {'default': self.return_warning_decorator, + 'para': self.paragraph_content_decorator} + result = it.walk(decorators, 1) + # Assuming that only one Warning per function + if result is not None: + return result + return result + + def return_seealso_decorator(self, node, value): + if node.name == 'simplesect': + if node.attributes['kind'] == 'see': + return value + else: + return None + + def _process_seealso_description(self, node): + result = None + para = node.children.get('para') + if para is not None: + for p in para: + simplesect_list = p.children.get('simplesect') + if simplesect_list is None: + continue + for it in simplesect_list: + decorators = {'default': self.return_seealso_decorator, + 'para': self.paragraph_content_decorator} + result = it.walk(decorators, 1) + return result + + def return_version_decorator(self, node, value): + if node.name == 'simplesect': + if node.attributes['kind'] == 'version': + return value + else: + return None + + def _process_version_description(self, node): + result = None + para = node.children.get('para') + if para is not None: + for p in para: + simplesect_list = p.children.get('simplesect') + if simplesect_list is None: + continue + for it in simplesect_list: + decorators = {'default': self.return_version_decorator, + 'para': self.paragraph_content_decorator} + result = it.walk(decorators, 1) + if result is not None: + return result + return result + + def return_notes_decorator(self, node, value): + if node.name == 'simplesect': + if node.attributes['kind'] == 'note': + return value + else: + return None + + def _process_notes_description(self, node): + result = None + para = node.children.get('para') + if para is not None: + for p in para: + simplesect_list = p.children.get('simplesect') + if simplesect_list is None: + continue + for it in simplesect_list: + decorators = {'default': self.return_notes_decorator, + 'para': self.paragraph_content_decorator} + result = it.walk(decorators, 1) + if result is not None: + return result + return result + + def return_deprecated_decorator(self, node, value): + if node.name == 'xrefsect': + if node.attributes['id'].find('deprecated_') > -1: + xreftitle = node.children.get('xreftitle') + if xreftitle[0] is not None: + xrefdescr = node.children.get('xrefdescription') + deprecated_descr = "DEPRECATED %s" % xrefdescr[0].getContent() + return deprecated_descr + else: + return None + + def _process_deprecated_description(self, node): + result = None + para = node.children.get('para') + if para is not None: + for p in para: + xrefsect_list = p.children.get('xrefsect') + if xrefsect_list is None: + continue + for it in xrefsect_list: + decorators = {'default': self.return_deprecated_decorator, + 'para': self.paragraph_content_decorator} + result = it.walk(decorators, 1) + if result is not None: + return result + return result + + def break_into_lines(self, value, linelen=82): + breaks = range(0,len(value),linelen) + [len(value)] + result = list() + for (start,end) in zip(breaks[:-1],breaks[1:]): + result.append(value[start:end]) + result = '\n'.join(result) + + return result + + def _save(self, table, path = None): + if path is None: + f = sys.stdout + else: + f = open(path, 'w') + for l in table: + f.write('%s\n' % ','.join(l)) + if path is not None: + f.close() + + + +class DoxyFuncsTest(DoxyFuncs): + def __init__(self, xmlpath, rstpath): + super(DoxyFuncsTest,self).__init__(xmlpath) + self.target_dir = rstpath + outfile = '%s/%s' % (self.target_dir, 'out.txt') + self.tmp = open(outfile, 'w') + + def run_tests(self): + self.test_save() + + def test_run(self): + self.run() + + def test_save(self): + self.run() + templates = {'function': 'func_document.tmpl'} + self.save(templates, self.target_dir) + +if __name__ == '__main__': + tester = DoxyFuncsTest(xmlpath, rstpath) + tester.run_tests() + diff --git a/doc/tools/doxybuilder_types.py b/doc/tools/doxybuilder_types.py new file mode 100644 index 000000000..c7a38f9d2 --- /dev/null +++ b/doc/tools/doxybuilder_types.py @@ -0,0 +1,370 @@ +''' + Copyright 2011 by the Massachusetts + Institute of Technology. All Rights Reserved. + + Export of this software from the United States of America may + require a specific license from the United States Government. + It is the responsibility of any person or organization contemplating + export to obtain such a license before exporting. + + WITHIN THAT CONSTRAINT, permission to use, copy, modify, and + distribute this software and its documentation for any purpose and + without fee is hereby granted, provided that the above copyright + notice appear in all copies and that both that copyright notice and + this permission notice appear in supporting documentation, and that + the name of M.I.T. not be used in advertising or publicity pertaining + to distribution of the software without specific, written prior + permission. Furthermore if you modify this software you must label + your software as modified software and not distribute it in such a + fashion that it might be confused with the original M.I.T. software. + M.I.T. makes no representations about the suitability of + this software for any purpose. It is provided "as is" without express + or implied warranty. +''' + +import sys +import os +import re + +from lxml import etree + +from docmodel import * + + +class DoxyTypes(object): + def __init__(self, xmlpath): + self.xmlpath = xmlpath + + def run_compound(self, filename, include=None): + path = '%s/%s' % (self.xmlpath,filename) + tree = etree.parse(path) + root = tree.getroot() + + brief_node = root.xpath('./compounddef/briefdescription')[0] + brief_description = self._get_brief_description(brief_node) + details_node = root.xpath('./compounddef/detaileddescription')[0] + detailed_description = self._get_detailed_description(details_node) + + fields = list() + for node in root.iterfind(".//memberdef[@kind]"): + data = {} + kind = node.attrib['kind'] + if include is None or kind in include: + if kind == 'variable': + data = self._process_variable_node(node) + else: + pass + fields.append(data) + + result = {'brief_description': brief_description, + 'detailed_description': detailed_description, + 'attributes': fields} + + return result + + + + def run(self, filename, include=None): + """ + Parses xml file generated by doxygen. + + @param filename: doxygen xml file name + @param include: members sections to include, in None -- include all + """ + path = '%s/%s' % (self.xmlpath,filename) + tree = etree.parse(path) + root = tree.getroot() + result = list() + for node in root.iterfind(".//memberdef[@kind]"): + data = {} + kind = node.attrib['kind'] + if include is None or kind in include: + if kind == 'typedef': + data = self._process_typedef_node(node) + elif kind == 'variable': + data = self._process_variable_node(node) + elif kind == 'define': + data = self._process_define_node(node) + result.append(data) + print "\nnumber of types processed ==> " , len(result) + return result + + + def _process_typedef_node(self, node): + t_name = node.xpath('./name/text()')[0] + + print t_name + + t_Id = node.attrib['id'] + t_definition = node.xpath('./definition/text()')[0] + t_type = self._process_type_node(node.xpath("./type")[0]) + brief_node = node.xpath('./briefdescription')[0] + t_brief = self._get_brief_description(brief_node) + details_node = node.xpath('./detaileddescription')[0] + t_detailed = self._get_detailed_description(details_node) + # remove macros + t_definition = re.sub('KRB5_CALLCONV_C', '', t_definition) + t_definition = re.sub('KRB5_CALLCONV', '', t_definition) + t_definition = re.sub('\*', '\\*', t_definition) + # handle fp + if t_type[1].find('(') >= 0: + t_type = (t_type[0],None) + + typedef_descr = {'category': 'composite', + 'definition': t_definition, + 'name': t_name, + 'Id': t_Id, + 'initializer': '', + 'type': t_type[1], + 'short_description': t_brief, + 'long_description': t_detailed, + 'attributes': list() + } + if t_type[0] is not None : + filename = '%s.xml' % t_type[0] + path = '%s/%s' % (self.xmlpath,filename) + if not os.path.exists(path): + # nothing can be done + return typedef_descr + + compound_info = self.run_compound(filename) + if compound_info is not None: + brief_description = compound_info.get('brief_description') + if brief_description is not None and len(brief_description): + # override brief description + typedef_descr['short_description'] = brief_description + detailed_description = compound_info.get('detailed_description') + if detailed_description is not None and len(detailed_description): + # check if this is not a duplicate + if detailed_description.find(t_detailed) < 0: + typedef_descr['long_description'] = '%s\n%s' % \ + (detailed_description, + typedef_descr['long_description']) + typedef_descr['attributes'] = compound_info['attributes'] + return typedef_descr + + def _process_variable_node(self, node): + v_name = node.xpath('./name/text()')[0] + v_Id = node.attrib['id'] + v_definition = node.xpath('./definition/text()')[0] + v_type = self._process_type_node(node.xpath("./type")[0]) + brief_node = node.xpath('./briefdescription')[0] + v_brief = self._get_brief_description(brief_node) + details_node = node.xpath('./detaileddescription')[0] + detailed_description = self._get_detailed_description(details_node) + # remove macros + v_definition = re.sub('KRB5_CALLCONV_C', '', v_definition) + v_definition = re.sub('KRB5_CALLCONV', '', v_definition) + v_definition = re.sub('\*', '\\*', v_definition) + + variable_descr = {'category': 'variable', + 'definition': v_definition, + 'name': v_name, + 'Id': v_Id, + 'initializer': '', + 'type': v_type[1], + 'short_description': v_brief, + 'long_description': detailed_description, + 'attributes': list() + } + + return variable_descr + + def _process_define_node(self, node): + d_name = node.xpath('./name/text()')[0] + print d_name + d_initializer = '' + d_type = '' + d_signature = '' + + # Process param/defname node + if len(node.xpath('./param/defname')) > 0: + prm_str = '' + prm_list = list() + for p in node.xpath("./param"): + x = self._process_paragraph_content(p) + if x is not None and len(x): + prm_list.append(x) + if prm_list is not None: + prm_str = prm_str.join(prm_list) + d_signature = " %s (%s) " % (d_name , prm_str) + d_signature = re.sub(', \)', ')', d_signature) + + if len(node.xpath('./initializer')) > 0: + len_ref = len(node.xpath('./initializer/ref')) + if len(node.xpath('./initializer/ref')) > 0: + d_type = self._process_type_node(node.xpath("./initializer/ref")[0]) + if len(d_type) > 0: + len_text = len(node.xpath('./initializer/text()')) + if len_text == 0 and d_type[1]: + d_initializer = d_type[1] + if len_text > 0 and len(node.xpath('./initializer/text()')[0]) > 0: + d_initializer = node.xpath('./initializer/text()')[0] + d_type[1] + if len_text > 1: + if node.xpath('./initializer/text()')[1] is not None: + d_initializer = d_initializer + node.xpath('./initializer/text()')[1] + else: + d_initializer = node.xpath('./initializer/text()')[0] + d_Id = node.attrib['id'] + brief_node = node.xpath('./briefdescription')[0] + d_brief = self._get_brief_description(brief_node) + details_node = node.xpath('./detaileddescription')[0] + detailed_description = self._get_detailed_description(details_node) + + define_descr = {'category': 'composite', + 'definition': '', + 'name': d_name, + 'name_signature': d_signature, + 'Id': d_Id, + 'initializer': d_initializer, + 'type': '', + 'short_description': d_brief, + 'long_description': detailed_description, + 'attributes': list() + } + + return define_descr + + + def _get_brief_description(self, node): + result = list() + for p in node.xpath("./para"): + x = self._process_paragraph_content(p) + if x is not None and len(x): + result.append(x) + result = '\n'.join(result) + + return result + + + def _get_detailed_description(self, node): + """ + Description node is comprised of ... sections. + There are few types of these sections: + a) Content section + b) Return value section -- skip + c) Parameter list section -- skip + @param node: detailed description node + """ + result = list() + for p in node.xpath("./para"): + if len(p.xpath("./simplesect[@kind='return']")): + continue + elif len(p.xpath("./parameterlist[@kind='param']")): + continue + else: + x = self._process_paragraph_content(p) + result.append(x) + result = '\n'.join(result) + + return result + + def _process_paragraph_content(self, node): + + result = list() + content = node.xpath(".//text()") + for e in content: + if node is e.getparent(): + result.append(e.strip()) + elif e.getparent().tag == 'ref': + if e.is_tail: + result.append(e.strip()) + else: + result.append(':c:type:`%s`' % e.strip()) + elif e.getparent().tag == 'emphasis': + if e.is_tail: + result.append(e.strip()) + else: + result.append('*%s*' % e.strip()) + elif e.getparent().tag == 'computeroutput': + if e.is_tail: + result.append(e.strip()) + else: + result.append('*%s*' % e.strip()) + elif e.getparent().tag == 'defname': + result.append('%s, ' % e.strip()) + result = ' '.join(result) + + return result + + def _process_type_node(self, node): + """ + Type node has form + type_string + for build in types and + + + 'type_name' + + postfix (ex. *, **m, etc.) + + for user defined types. + """ + p_id = node.xpath("./ref/@refid") + if len(p_id) == 1: + p_id = p_id[0] + elif len(p_id) == 0: + p_id = None + p_type = ' '.join(node.xpath(".//text()")) + + # remove macros + p_type = re.sub('KRB5_CALLCONV_C', ' ', p_type) + p_type = re.sub('KRB5_CALLCONV', ' ', p_type) + + return (p_id,p_type) + + def save(self, obj, templates, target_dir): + template_path = templates[obj.category] + outpath = '%s/%s.rst' % (target_dir,obj.name) + obj.save(outpath, template_path) + + + +class DoxyTypesTest(DoxyTypes): + def __init__(self, xmlpath, rstpath): + self.templates = { 'composite': 'type_document.tmpl'} + self.target_dir = rstpath + + super(DoxyTypesTest,self).__init__(xmlpath) + + def run_tests(self): + print "Process typedef's" + self.test_process_typedef_node() + print "Process define's" + self.test_process_define_node() + + def test_run(self): + filename = 'krb5_8hin.xml' + self.run(filename) + + def test_process_variable_node(self): + filename = 'struct__krb5__octet__data.xml' + result = self.run(filename, include=['variable']) + + def test_process_typedef_node(self): + # run parser for typedefs + filename = 'krb5_8hin.xml' + result = self.run(filename, include=['typedef']) + target_dir = '%s/types' % (self.target_dir) + if not os.path.exists(target_dir): + os.makedirs(target_dir, 0755) + for t in result: + obj = DocModel(**t) + self.save(obj, self.templates, target_dir) + + def test_process_define_node(self): + # run parser for define's + filename = 'krb5_8hin.xml' + result = self.run(filename, include=['define']) + target_dir = '%s/macros' % (self.target_dir) + if not os.path.exists(target_dir): + os.makedirs(target_dir, 0755) + for t in result: + obj = DocModel(**t) + tmpl = {'composite': 'define_document.tmpl'} + self.save(obj, tmpl, target_dir) + +if __name__ == '__main__': + + tester = DoxyTypesTest( xml_inpath, rst_outpath) + tester.run_tests() diff --git a/doc/tools/func_document.tmpl b/doc/tools/func_document.tmpl new file mode 100644 index 000000000..b9b63d115 --- /dev/null +++ b/doc/tools/func_document.tmpl @@ -0,0 +1,99 @@ +#if $function.short_description is not None + #set $title = $function.name + ' - ' + $function.short_description +#else + #set $title = $function.name +#end if +$title +#echo ''.join(['=']*len($title)) # + +.. + +.. c:function:: $signature + +.. + + +:param: + +#for $param in $function.parameters: + #if $param.name is '' + #continue + #end if + #if $param.direction is not None + #set name_description = '**[%s]** **%s**' % ($param.direction, $param.name) + #else + #set name_description = '**%s**' % $param.name + #end if + #if $param.description is not None + #set $description= ' - ' + $param.description + #else + #set $description='' + #end if + $name_description$description + +#end for + +.. + +#if len($function.retval_description) > 0 + +:retval: +#for $retval in $function.retval_description: + - $retval +#end for +#end if + +#if len($function.return_description) > 0 + +:return: +#for $retval in $function.return_description: + - $retval +#end for +#end if + +.. + +#if $function.deprecated_description is not None + +$function.deprecated_description +#end if + + + + +#if $function.long_description is not None + + +$function.long_description + +#end if + + +.. + +#if $function.sa_description is not None +.. seealso:: + $function.sa_description +#end if + + +#if $function.warn_description is not None or $function.notes_description is not None + + +#if $function.warn_description is not None +.. warning:: + $function.warn_description +#end if + +#if $function.notes_description is not None +.. note:: + $function.notes_description +#end if + +#end if + +#if $function.version_num is not None +.. note:: + $function.version_num +#end if + diff --git a/doc/tools/type_document.tmpl b/doc/tools/type_document.tmpl new file mode 100644 index 000000000..5987fa762 --- /dev/null +++ b/doc/tools/type_document.tmpl @@ -0,0 +1,43 @@ +.. highlightlang:: c + +.. $composite.struct_reference($composite.name): + +#set $title = $composite.name +$title +#echo ''.join(['=']*len($title)) # + +.. +.. c:type:: $composite.name +.. + +#if $composite.short_description is not None and len($composite.short_description) +$composite.short_description +#end if + +$composite.long_description + +Declaration +------------ + +$composite.definition + +#if $composite.Id is not None +#if len($composite.attributes) + +Members +--------- + +#end if + +#for $attr in $composite.attributes: +#if $attr.name is not None +.. c:member:: $attr.type $composite.name.$attr.name + + $attr.short_description +#if $attr.long_description is not None + $attr.long_description +#end if + +#end if +#end for +#end if diff --git a/doc/txt_conf.py b/doc/txt_conf.py new file mode 100644 index 000000000..f9f00e945 --- /dev/null +++ b/doc/txt_conf.py @@ -0,0 +1,88 @@ +# -*- coding: utf-8 -*- +# +# MIT Kerberos documentation build configuration file, created by +# sphinx-quickstart on Wed Oct 13 09:14:03 2010. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +#extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.doxylink'] +extensions = ['sphinx.ext.autodoc'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'notice' + +# General information about the project. +project = u'MIT Kerberos' +copyright = u'2012, MIT' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.0.1' +# The full version, including alpha/beta/rc tags. +release = '0.0.1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +today = ' ' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] diff --git a/doc/users/index.rst b/doc/users/index.rst new file mode 100644 index 000000000..233c3ef55 --- /dev/null +++ b/doc/users/index.rst @@ -0,0 +1,10 @@ +For users +========= + +.. toctree:: + :maxdepth: 2 + + pwd_mgmt.rst + tkt_mgmt.rst + user_config/index.rst + user_commands/index.rst diff --git a/doc/users/pwd_mgmt.rst b/doc/users/pwd_mgmt.rst new file mode 100644 index 000000000..ed7d459f0 --- /dev/null +++ b/doc/users/pwd_mgmt.rst @@ -0,0 +1,106 @@ +Password management +=================== + +Your password is the only way Kerberos has of verifying your identity. +If someone finds out your password, that person can masquerade as +you---send email that comes from you, read, edit, or delete your files, +or log into other hosts as you---and no one will be able to tell the +difference. For this reason, it is important that you choose a good +password, and keep it secret. If you need to give access to your +account to someone else, you can do so through Kerberos (see +:ref:`grant_access`). You should never tell your password to anyone, +including your system administrator, for any reason. You should +change your password frequently, particularly any time you think +someone may have found out what it is. + + +Changing your password +---------------------- + +To change your Kerberos password, use the :ref:`kpasswd(1)` command. +It will ask you for your old password (to prevent someone else from +walking up to your computer when you're not there and changing your +password), and then prompt you for the new one twice. (The reason you +have to type it twice is to make sure you have typed it correctly.) +For example, user ``david`` would do the following:: + + shell% kpasswd + Password for david: <- Type your old password. + Enter new password: <- Type your new password. + Enter it again: <- Type the new password again. + Password changed. + shell% + +If ``david`` typed the incorrect old password, he would get the +following message:: + + shell% kpasswd + Password for david: <- Type the incorrect old password. + kpasswd: Password incorrect while getting initial ticket + shell% + +If you make a mistake and don't type the new password the same way +twice, kpasswd will ask you to try again:: + + shell% kpasswd + Password for david: <- Type the old password. + Enter new password: <- Type the new password. + Enter it again: <- Type a different new password. + kpasswd: Password mismatch while reading password + shell% + +Once you change your password, it takes some time for the change to +propagate through the system. Depending on how your system is set up, +this might be anywhere from a few minutes to an hour or more. If you +need to get new Kerberos tickets shortly after changing your password, +try the new password. If the new password doesn't work, try again +using the old one. + + +.. _grant_access: + +Granting access to your account +------------------------------- + +If you need to give someone access to log into your account, you can +do so through Kerberos, without telling the person your password. +Simply create a file called :ref:`.k5login(5)` in your home directory. +This file should contain the Kerberos principal of each person to whom +you wish to give access. Each principal must be on a separate line. +Here is a sample .k5login file:: + + jennifer@ATHENA.MIT.EDU + david@EXAMPLE.COM + +This file would allow the users ``jennifer`` and ``david`` to use your +user ID, provided that they had Kerberos tickets in their respective +realms. If you will be logging into other hosts across a network, you +will want to include your own Kerberos principal in your .k5login file +on each of these hosts. + +Using a .k5login file is much safer than giving out your password, +because: + +* You can take access away any time simply by removing the principal + from your .k5login file. + +* Although the user has full access to your account on one particular + host (or set of hosts if your .k5login file is shared, e.g., over + NFS), that user does not inherit your network privileges. + +* Kerberos keeps a log of who obtains tickets, so a system + administrator could find out, if necessary, who was capable of using + your user ID at a particular time. + +One common application is to have a .k5login file in root's home +directory, giving root access to that machine to the Kerberos +principals listed. This allows system administrators to allow users +to become root locally, or to log in remotely as root, without their +having to give out the root password, and without anyone having to +type the root password over the network. + + +Password quality verification +----------------------------- + +TODO diff --git a/doc/users/tkt_mgmt.rst b/doc/users/tkt_mgmt.rst new file mode 100644 index 000000000..0ca95accd --- /dev/null +++ b/doc/users/tkt_mgmt.rst @@ -0,0 +1,312 @@ +Ticket management +================= + +On many systems, Kerberos is built into the login program, and you get +tickets automatically when you log in. Other programs, such as ssh, +can forward copies of your tickets to a remote host. Most of these +programs also automatically destroy your tickets when they exit. +However, MIT recommends that you explicitly destroy your Kerberos +tickets when you are through with them, just to be sure. One way to +help ensure that this happens is to add the :ref:`kdestroy(1)` command +to your .logout file. Additionally, if you are going to be away from +your machine and are concerned about an intruder using your +permissions, it is safest to either destroy all copies of your +tickets, or use a screensaver that locks the screen. + + +Kerberos ticket properties +-------------------------- + +There are various properties that Kerberos tickets can have: + +If a ticket is **forwardable**, then the KDC can issue a new ticket +(with a different network address, if necessary) based on the +forwardable ticket. This allows for authentication forwarding without +requiring a password to be typed in again. For example, if a user +with a forwardable TGT logs into a remote system, the KDC could issue +a new TGT for that user with the netword address of the remote system, +allowing authentication on that host to work as though the user were +logged in locally. + +When the KDC creates a new ticket based on a forwardable ticket, it +sets the **forwarded** flag on that new ticket. Any tickets that are +created based on a ticket with the forwarded flag set will also have +their forwarded flags set. + +A **proxiable** ticket is similar to a forwardable ticket in that it +allows a service to take on the identity of the client. Unlike a +forwardable ticket, however, a proxiable ticket is only issued for +specific services. In other words, a ticket-granting ticket cannot be +issued based on a ticket that is proxiable but not forwardable. + +A **proxy** ticket is one that was issued based on a proxiable ticket. + +A **postdated** ticket is issued with the invalid flag set. After the +starting time listed on the ticket, it can be presented to the KDC to +obtain valid tickets. + +Ticket-granting tickets with the **postdateable** flag set can be used +to obtain postdated service tickets. + +**Renewable** tickets can be used to obtain new session keys without +the user entering their password again. A renewable ticket has two +expiration times. The first is the time at which this particular +ticket expires. The second is the latest possible expiration time for +any ticket issued based on this renewable ticket. + +A ticket with the **initial flag** set was issued based on the +authentication protocol, and not on a ticket-granting ticket. +Application servers that wish to ensure that the user's key has been +recently presented for verification could specify that this flag must +be set to accept the ticket. + +An **invalid** ticket must be rejected by application servers. +Postdated tickets are usually issued with this flag set, and must be +validated by the KDC before they can be used. + +A **preauthenticated** ticket is one that was only issued after the +client requesting the ticket had authenticated itself to the KDC. + +The **hardware authentication** flag is set on a ticket which required +the use of hardware for authentication. The hardware is expected to +be possessed only by the client which requested the tickets. + +If a ticket has the **transit policy** checked flag set, then the KDC +that issued this ticket implements the transited-realm check policy +and checked the transited-realms list on the ticket. The +transited-realms list contains a list of all intermediate realms +between the realm of the KDC that issued the first ticket and that of +the one that issued the current ticket. If this flag is not set, then +the application server must check the transited realms itself or else +reject the ticket. + +The **okay as delegate** flag indicates that the server specified in +the ticket is suitable as a delegate as determined by the policy of +that realm. Some client applications may use this flag to decide +whether to forward tickets to a remote host, although many +applications do not honor it. + +An **anonymous** ticket is one in which the named principal is a +generic principal for that realm; it does not actually specify the +individual that will be using the ticket. This ticket is meant only +to securely distribute a session key. + + +.. _obtain_tkt: + +Obtaining tickets with kinit +---------------------------- + +If your site has integrated Kerberos V5 with the login system, you +will get Kerberos tickets automatically when you log in. Otherwise, +you may need to explicitly obtain your Kerberos tickets, using the +:ref:`kinit(1)` program. Similarly, if your Kerberos tickets expire, +use the kinit program to obtain new ones. + +To use the kinit program, simply type ``kinit`` and then type your +password at the prompt. For example, Jennifer (whose username is +``jennifer``) works for Bleep, Inc. (a fictitious company with the +domain name mit.edu and the Kerberos realm ATHENA.MIT.EDU). She would +type:: + + shell% kinit + Password for jennifer@ATHENA.MIT.EDU: <-- [Type jennifer's password here.] + shell% + +If you type your password incorrectly, kinit will give you the +following error message:: + + shell% kinit + Password for jennifer@ATHENA.MIT.EDU: <-- [Type the wrong password here.] + kinit: Password incorrect + shell% + +and you won't get Kerberos tickets. + +By default, kinit assumes you want tickets for your own username in +your default realm. Suppose Jennifer's friend David is visiting, and +he wants to borrow a window to check his mail. David needs to get +tickets for himself in his own realm, EXAMPLE.COM. He would type:: + + shell% kinit david@EXAMPLE.COM + Password for david@EXAMPLE.COM: <-- [Type david's password here.] + shell% + +David would then have tickets which he could use to log onto his own +machine. Note that he typed his password locally on Jennifer's +machine, but it never went over the network. Kerberos on the local +host performed the authentication to the KDC in the other realm. + +If you want to be able to forward your tickets to another host, you +need to request forwardable tickets. You do this by specifying the +**-f** option:: + + shell% kinit -f + Password for jennifer@ATHENA.MIT.EDU: <-- [Type your password here.] + shell% + +Note that kinit does not tell you that it obtained forwardable +tickets; you can verify this using the :ref:`klist(1)` command (see +:ref:`view_tkt`). + +Normally, your tickets are good for your system's default ticket +lifetime, which is ten hours on many systems. You can specify a +different ticket lifetime with the **-l** option. Add the letter +**s** to the value for seconds, **m** for minutes, **h** for hours, or +**d** for days. For example, to obtain forwardable tickets for +``david@EXAMPLE.COM`` that would be good for three hours, you would +type:: + + shell% kinit -f -l 3h david@EXAMPLE.COM + Password for david@EXAMPLE.COM: <-- [Type david's password here.] + shell% + +.. note:: You cannot mix units; specifying a lifetime of 3h30m would + result in an error. Note also that most systems specify a + maximum ticket lifetime. If you request a longer ticket + lifetime, it will be automatically truncated to the maximum + lifetime. + + +.. _view_tkt: + +Viewing tickets with klist +-------------------------- + +The :ref:`klist(1)` command shows your tickets. When you first obtain +tickets, you will have only the ticket-granting ticket. The listing +would look like this:: + + shell% klist + Ticket cache: /tmp/krb5cc_ttypa + Default principal: jennifer@ATHENA.MIT.EDU + + Valid starting Expires Service principal + 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU + shell% + +The ticket cache is the location of your ticket file. In the above +example, this file is named ``/tmp/krb5cc_ttypa``. The default +principal is your Kerberos principal. + +The "valid starting" and "expires" fields describe the period of time +during which the ticket is valid. The "service principal" describes +each ticket. The ticket-granting ticket has a first component +``krbtgt``, and a second component which is the realm name. + +Now, if ``jennifer`` connected to the machine ``daffodil.mit.edu``, +and then typed "klist" again, she would have gotten the following +result:: + + shell% klist + Ticket cache: /tmp/krb5cc_ttypa + Default principal: jennifer@ATHENA.MIT.EDU + + Valid starting Expires Service principal + 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU + 06/07/04 20:22:30 06/08/04 05:49:19 host/daffodil.mit.edu@ATHENA.MIT.EDU + shell% + +Here's what happened: when ``jennifer`` used ssh to connect to the +host ``daffodil.mit.edu``, the ssh program presented her +ticket-granting ticket to the KDC and requested a host ticket for the +host ``daffodil.mit.edu``. The KDC sent the host ticket, which ssh +then presented to the host ``daffodil.mit.edu``, and she was allowed +to log in without typing her password. + +Suppose your Kerberos tickets allow you to log into a host in another +domain, such as ``trillium.example.com``, which is also in another +Kerberos realm, ``EXAMPLE.COM``. If you ssh to this host, you will +receive a ticket-granting ticket for the realm ``EXAMPLE.COM``, plus +the new host ticket for ``trillium.example.com``. klist will now +show:: + + shell% klist + Ticket cache: /tmp/krb5cc_ttypa + Default principal: jennifer@ATHENA.MIT.EDU + + Valid starting Expires Service principal + 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU + 06/07/04 20:22:30 06/08/04 05:49:19 host/daffodil.mit.edu@ATHENA.MIT.EDU + 06/07/04 20:24:18 06/08/04 05:49:19 krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU + 06/07/04 20:24:18 06/08/04 05:49:19 host/trillium.example.com@EXAMPLE.COM + shell% + +Depending on your host's and realm's configuration, you may also see a +ticket with the service principal ``host/trillium.example.com@``. If +so, this means that your host did not know what realm +trillium.example.com is in, so it asked the ``ATHENA.MIT.EDU`` KDC for +a referral. The next time you connect to ``trillium.example.com``, +the odd-looking entry will be used to avoid needing to ask for a +referral again. + +You can use the **-f** option to view the flags that apply to your +tickets. The flags are: + +===== ========================= + F Forwardable + f forwarded + P Proxiable + p proxy + D postDateable + d postdated + R Renewable + I Initial + i invalid + H Hardware authenticated + A preAuthenticated + T Transit policy checked + O Okay as delegate + a anonymous +===== ========================= + +Here is a sample listing. In this example, the user *jennifer* +obtained her initial tickets (**I**), which are forwardable (**F**) +and postdated (**d**) but not yet validated (**i**):: + + shell% klist -f + Ticket cache: /tmp/krb5cc_320 + Default principal: jennifer@ATHENA.MIT.EDU + + Valid starting Expires Service principal + 31/07/05 19:06:25 31/07/05 19:16:25 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU + Flags: FdiI + shell% + +In the following example, the user *david*'s tickets were forwarded +(**f**) to this host from another host. The tickets are reforwardable +(**F**):: + + shell% klist -f + Ticket cache: /tmp/krb5cc_p11795 + Default principal: david@EXAMPLE.COM + + Valid starting Expires Service principal + 07/31/05 11:52:29 07/31/05 21:11:23 krbtgt/EXAMPLE.COM@EXAMPLE.COM + Flags: Ff + 07/31/05 12:03:48 07/31/05 21:11:23 host/trillium.example.com@EXAMPLE.COM + Flags: Ff + shell% + + +Destroying tickets with kdestroy +-------------------------------- + +Your Kerberos tickets are proof that you are indeed yourself, and +tickets could be stolen if someone gains access to a computer where +they are stored. If this happens, the person who has them can +masquerade as you until they expire. For this reason, you should +destroy your Kerberos tickets when you are away from your computer. + +Destroying your tickets is easy. Simply type kdestroy:: + + shell% kdestroy + shell% + +If :ref:`kdestroy(1)` fails to destroy your tickets, it will beep and +give an error message. For example, if kdestroy can't find any +tickets to destroy, it will give the following message:: + + shell% kdestroy + kdestroy: No credentials cache file found while destroying cache + shell% diff --git a/doc/users/user_commands/index.rst b/doc/users/user_commands/index.rst new file mode 100644 index 000000000..b43fad69c --- /dev/null +++ b/doc/users/user_commands/index.rst @@ -0,0 +1,16 @@ +.. _user_commands: + +User commands +============= + +.. toctree:: + :maxdepth: 1 + + kdestroy.rst + kinit.rst + klist.rst + kpasswd.rst + ksu.rst + kswitch.rst + kvno.rst + sclient.rst diff --git a/doc/users/user_commands/kdestroy.rst b/doc/users/user_commands/kdestroy.rst new file mode 100644 index 000000000..b8c67aba4 --- /dev/null +++ b/doc/users/user_commands/kdestroy.rst @@ -0,0 +1,77 @@ +.. _kdestroy(1): + +kdestroy +======== + +SYNOPSIS +-------- + +**kdestroy** +[**-A**] +[**-q**] +[**-c** *cache_name*] + + +DESCRIPTION +----------- + +The kdestroy utility destroys the user's active Kerberos authorization +tickets by overwriting and deleting the credentials cache that +contains them. If the credentials cache is not specified, the default +credentials cache is destroyed. + + +OPTIONS +------- + +**-A** + Destroys all caches in the collection, if a cache collection is + available. + +**-q** + Run quietly. Normally kdestroy beeps if it fails to destroy the + user's tickets. The **-q** flag suppresses this behavior. + +**-c** *cache_name* + Use *cache_name* as the credentials (ticket) cache name and + location; if this option is not used, the default cache name and + location are used. + + The default credentials cache may vary between systems. If the + **KRB5CCNAME** environment variable is set, its value is used to + name the default ticket cache. + + +NOTE +---- + +Most installations recommend that you place the kdestroy command in +your .logout file, so that your tickets are destroyed automatically +when you log out. + + +ENVIRONMENT +----------- + +kdestroy uses the following environment variable: + +**KRB5CCNAME** + Location of the default Kerberos 5 credentials (ticket) cache, in + the form *type*:*residual*. If no *type* prefix is present, the + **FILE** type is assumed. The type of the default cache may + determine the availability of a cache collection; for instance, a + default cache of type **DIR** causes caches within the directory + to be present in the collection. + + +FILES +----- + +|ccache| + Default location of Kerberos 5 credentials cache + + +SEE ALSO +-------- + +:ref:`kinit(1)`, :ref:`klist(1)` diff --git a/doc/users/user_commands/kinit.rst b/doc/users/user_commands/kinit.rst new file mode 100644 index 000000000..c28fd29b6 --- /dev/null +++ b/doc/users/user_commands/kinit.rst @@ -0,0 +1,211 @@ +.. _kinit(1): + +kinit +===== + +SYNOPSIS +-------- + +**kinit** +[**-V**] +[**-l** *lifetime*] +[**-s** *start_time*] +[**-r** *renewable_life*] +[**-p** | -**P**] +[**-f** | -**F**] +[**-a**] +[**-A**] +[**-C**] +[**-E**] +[**-v**] +[**-R**] +[**-k** [-**t** *keytab_file*]] +[**-c** *cache_name*] +[**-n**] +[**-S** *service_name*] +[**-T** *armor_ccache*] +[**-X** *attribute*\ [=\ *value*]] +[*principal*] + + +DESCRIPTION +----------- + +kinit obtains and caches an initial ticket-granting ticket for +*principal*. + + +OPTIONS +------- + +**-V** + display verbose output. + +**-l** *lifetime* + (:ref:`duration` string.) Requests a ticket with the lifetime + *lifetime*. + + For example, ``kinit -l 5:30`` or ``kinit -l 5h30m``. + + If the **-l** option is not specified, the default ticket lifetime + (configured by each site) is used. Specifying a ticket lifetime + longer than the maximum ticket lifetime (configured by each site) + will not override the configured maximum ticket lifetime. + +**-s** *start_time* + (:ref:`duration` string.) Requests a postdated ticket. Postdated + tickets are issued with the **invalid** flag set, and need to be + resubmitted to the KDC for validation before use. + + *start_time* specifies the duration of the delay before the ticket + can become valid. + +**-r** *renewable_life* + (:ref:`duration` string.) Requests renewable tickets, with a total + lifetime of *renewable_life*. + +**-f** + requests forwardable tickets. + +**-F** + requests non-forwardable tickets. + +**-p** + requests proxiable tickets. + +**-P** + requests non-proxiable tickets. + +**-a** + requests tickets restricted to the host's local address[es]. + +**-A** + requests tickets not restricted by address. + +**-C** + requests canonicalization of the principal name, and allows the + KDC to reply with a different client principal from the one + requested. + +**-E** + treats the principal name as an enterprise name (implies the + **-C** option). + +**-v** + requests that the ticket-granting ticket in the cache (with the + **invalid** flag set) be passed to the KDC for validation. If the + ticket is within its requested time range, the cache is replaced + with the validated ticket. + +**-R** + requests renewal of the ticket-granting ticket. Note that an + expired ticket cannot be renewed, even if the ticket is still + within its renewable life. + +**-k** [**-i** | **-t** *keytab_file*] + requests a ticket, obtained from a key in the local host's keytab. + The location of the keytab may be specified with the **-t** + *keytab_file* option, or with the **-i** option to specify the use + of the default client keytab; otherwise the default keytab will be + used. By default, a host ticket for the local host is requested, + but any principal may be specified. On a KDC, the special keytab + location ``KDB:`` can be used to indicate that kinit should open + the KDC database and look up the key directly. This permits an + administrator to obtain tickets as any principal that supports + authentication based on the key. + +**-n** + Requests anonymous processing. Two types of anonymous principals + are supported. + + For fully anonymous Kerberos, configure pkinit on the KDC and + configure **pkinit_anchors** in the client's :ref:`krb5.conf(5)`. + Then use the **-n** option with a principal of the form ``@REALM`` + (an empty principal name followed by the at-sign and a realm + name). If permitted by the KDC, an anonymous ticket will be + returned. + + A second form of anonymous tickets is supported; these + realm-exposed tickets hide the identity of the client but not the + client's realm. For this mode, use ``kinit -n`` with a normal + principal name. If supported by the KDC, the principal (but not + realm) will be replaced by the anonymous principal. + + As of release 1.8, the MIT Kerberos KDC only supports fully + anonymous operation. + +**-T** *armor_ccache* + Specifies the name of a credentials cache that already contains a + ticket. If supported by the KDC, this cache will be used to armor + the request, preventing offline dictionary attacks and allowing + the use of additional preauthentication mechanisms. Armoring also + makes sure that the response from the KDC is not modified in + transit. + +**-c** *cache_name* + use *cache_name* as the Kerberos 5 credentials (ticket) cache + location. If this option is not used, the default cache location + is used. + + The default cache location may vary between systems. If the + **KRB5CCNAME** environment variable is set, its value is used to + locate the default cache. If a principal name is specified and + the type of the default cache supports a collection (such as the + DIR type), an existing cache containing credentials for the + principal is selected or a new one is created and becomes the new + primary cache. Otherwise, any existing contents of the default + cache are destroyed by kinit. + +**-S** *service_name* + specify an alternate service name to use when getting initial + tickets. + +**-X** *attribute*\ [=\ *value*] + specify a pre-authentication *attribute* and *value* to be + interpreted by pre-authentication modules. The acceptable + attribute and value values vary from module to module. This + option may be specified multiple times to specify multiple + attributes. If no value is specified, it is assumed to be "yes". + + The following attributes are recognized by the PKINIT + pre-authentication mechanism: + + **X509_user_identity**\ =\ *value* + specify where to find user's X509 identity information + + **X509_anchors**\ =\ *value* + specify where to find trusted X509 anchor information + + **flag_RSA_PROTOCOL**\ [**=yes**] + specify use of RSA, rather than the default Diffie-Hellman + protocol + + +ENVIRONMENT +----------- + +kinit uses the following environment variables: + +**KRB5CCNAME** + Location of the default Kerberos 5 credentials cache, in the form + *type*:*residual*. If no *type* prefix is present, the **FILE** + type is assumed. The type of the default cache may determine the + availability of a cache collection; for instance, a default cache + of type **DIR** causes caches within the directory to be present + in the collection. + + +FILES +----- + +|ccache| + default location of Kerberos 5 credentials cache + +|keytab| + default location for the local host's keytab. + + +SEE ALSO +-------- + +:ref:`klist(1)`, :ref:`kdestroy(1)`, kerberos(1) diff --git a/doc/users/user_commands/klist.rst b/doc/users/user_commands/klist.rst new file mode 100644 index 000000000..d303f34d8 --- /dev/null +++ b/doc/users/user_commands/klist.rst @@ -0,0 +1,135 @@ +.. _klist(1): + +klist +===== + +SYNOPSIS +-------- + +**klist** +[**-e**] +[[**-c**] [**-l**] [**-A**] [**-f**] [**-s**] [**-a** [**-n**]]] +[**-C**] +[**-k** [**-t**] [**-K**]] +[**-V**] +[*cache_name*\|\ *keytab_name*] + + +DESCRIPTION +----------- + +klist lists the Kerberos principal and Kerberos tickets held in a +credentials cache, or the keys held in a keytab file. + + +OPTIONS +------- + +**-e** + Displays the encryption types of the session key and the ticket + for each credential in the credential cache, or each key in the + keytab file. + +**-l** + If a cache collection is available, displays a table summarizing + the caches present in the collection. + +**-A** + If a cache collection is available, displays the contents of all + of the caches in the collection. + +**-c** + List tickets held in a credentials cache. This is the default if + neither **-c** nor **-k** is specified. + +**-f** + Shows the flags present in the credentials, using the following + abbreviations: + + :: + + F Forwardable + f forwarded + P Proxiable + p proxy + D postDateable + d postdated + R Renewable + I Initial + i invalid + H Hardware authenticated + A preAuthenticated + T Transit policy checked + O Okay as delegate + a anonymous + +**-s** + Causes klist to run silently (produce no output), but to still set + the exit status according to whether it finds the credentials + cache. The exit status is '0' if klist finds a credentials cache, + and '1' if it does not or if the tickets are expired. + +**-a** + Display list of addresses in credentials. + +**-n** + Show numeric addresses instead of reverse-resolving addresses. + +**-C** + List configuration data that has been stored in the credentials + cache when klist encounters it. By default, configuration data + is not listed. + +**-k** + List keys held in a keytab file. + +**-i** + In combination with **-k**, defaults to using the default client + keytab instead of the default acceptor keytab, if no name is + given. + +**-t** + Display the time entry timestamps for each keytab entry in the + keytab file. + +**-K** + Display the value of the encryption key in each keytab entry in + the keytab file. + +**-V** + Display the Kerberos version number and exit. + +If *cache_name* or *keytab_name* is not specified, klist will display +the credentials in the default credentials cache or keytab file as +appropriate. If the **KRB5CCNAME** environment variable is set, its +value is used to locate the default ticket cache. + + +ENVIRONMENT +----------- + +klist uses the following environment variable: + +**KRB5CCNAME** + Location of the default Kerberos 5 credentials (ticket) cache, in + the form *type*:*residual*. If no *type* prefix is present, the + **FILE** type is assumed. The type of the default cache may + determine the availability of a cache collection; for instance, a + default cache of type **DIR** causes caches within the directory + to be present in the collection. + + +FILES +----- + +|ccache| + Default location of Kerberos 5 credentials cache + +|keytab| + Default location for the local host's keytab file. + + +SEE ALSO +-------- + +:ref:`kinit(1)`, :ref:`kdestroy(1)` diff --git a/doc/users/user_commands/kpasswd.rst b/doc/users/user_commands/kpasswd.rst new file mode 100644 index 000000000..1b6463265 --- /dev/null +++ b/doc/users/user_commands/kpasswd.rst @@ -0,0 +1,39 @@ +.. _kpasswd(1): + +kpasswd +======= + +SYNOPSIS +-------- + +**kpasswd** [*principal*] + + +DESCRIPTION +----------- + +The kpasswd command is used to change a Kerberos principal's password. +kpasswd first prompts for the current Kerberos password, then prompts +the user twice for the new password, and the password is changed. + +If the principal is governed by a policy that specifies the length +and/or number of character classes required in the new password, the +new password must conform to the policy. (The five character classes +are lower case, upper case, numbers, punctuation, and all other +characters.) + + +OPTIONS +------- + +*principal* + Change the password for the Kerberos principal principal. + Otherwise, kpasswd uses the principal name from an existing ccache + if there is one; if not, the principal is derived from the + identity of the user invoking the kpasswd command. + + +SEE ALSO +-------- + +:ref:`kadmin(1)`, :ref:`kadmind(8)` diff --git a/doc/users/user_commands/ksu.rst b/doc/users/user_commands/ksu.rst new file mode 100644 index 000000000..aa22c18a3 --- /dev/null +++ b/doc/users/user_commands/ksu.rst @@ -0,0 +1,397 @@ +.. _ksu(1): + +ksu +=== + +SYNOPSIS +-------- + +**ksu** +[ *target_user* ] +[ **-n** *target_principal_name* ] +[ **-c** *source_cache_name* ] +[ **-k** ] +[ **-D** ] +[ **-r** time ] +[ **-pf** ] +[ **-l** *lifetime* ] +[ **-z | Z** ] +[ **-q** ] +[ **-e** *command* [ args ... ] ] [ **-a** [ args ... ] ] + + +REQUIREMENTS +------------ + +Must have Kerberos version 5 installed to compile ksu. Must have a +Kerberos version 5 server running to use ksu. + + +DESCRIPTION +----------- + +ksu is a Kerberized version of the su program that has two missions: +one is to securely change the real and effective user ID to that of +the target user, and the other is to create a new security context. + +.. note:: For the sake of clarity, all references to and attributes of + the user invoking the program will start with "source" + (e.g., "source user", "source cache", etc.). + + Likewise, all references to and attributes of the target + account will start with "target". + +AUTHENTICATION +-------------- + +To fulfill the first mission, ksu operates in two phases: +authentication and authorization. Resolving the target principal name +is the first step in authentication. The user can either specify his +principal name with the **-n** option (e.g., ``-n jqpublic@USC.EDU``) +or a default principal name will be assigned using a heuristic +described in the OPTIONS section (see **-n** option). The target user +name must be the first argument to ksu; if not specified root is the +default. If ``.`` is specified then the target user will be the +source user (e.g., ``ksu .``). If the source user is root or the +target user is the source user, no authentication or authorization +takes place. Otherwise, ksu looks for an appropriate Kerberos ticket +in the source cache. + +The ticket can either be for the end-server or a ticket granting +ticket (TGT) for the target principal's realm. If the ticket for the +end-server is already in the cache, it's decrypted and verified. If +it's not in the cache but the TGT is, the TGT is used to obtain the +ticket for the end-server. The end-server ticket is then verified. +If neither ticket is in the cache, but ksu is compiled with the +**GET_TGT_VIA_PASSWD** define, the user will be prompted for a +Kerberos password which will then be used to get a TGT. If the user +is logged in remotely and does not have a secure channel, the password +may be exposed. If neither ticket is in the cache and +**GET_TGT_VIA_PASSWD** is not defined, authentication fails. + + +AUTHORIZATION +------------- + +This section describes authorization of the source user when ksu is +invoked without the **-e** option. For a description of the **-e** +option, see the OPTIONS section. + +Upon successful authentication, ksu checks whether the target +principal is authorized to access the target account. In the target +user's home directory, ksu attempts to access two authorization files: +:ref:`.k5login(5)` and .k5users. In the .k5login file each line +contains the name of a principal that is authorized to access the +account. + +For example: + :: + + jqpublic@USC.EDU + jqpublic/secure@USC.EDU + jqpublic/admin@USC.EDU + +The format of .k5users is the same, except the principal name may be +followed by a list of commands that the principal is authorized to +execute (see the **-e** option in the OPTIONS section for details). + +Thus if the target principal name is found in the .k5login file the +source user is authorized to access the target account. Otherwise ksu +looks in the .k5users file. If the target principal name is found +without any trailing commands or followed only by ``*`` then the +source user is authorized. If either .k5login or .k5users exist but +an appropriate entry for the target principal does not exist then +access is denied. If neither file exists then the principal will be +granted access to the account according to the aname->lname mapping +rules. Otherwise, authorization fails. + + +EXECUTION OF THE TARGET SHELL +----------------------------- + +Upon successful authentication and authorization, ksu proceeds in a +similar fashion to su. The environment is unmodified with the +exception of USER, HOME and SHELL variables. If the target user is +not root, USER gets set to the target user name. Otherwise USER +remains unchanged. Both HOME and SHELL are set to the target login's +default values. In addition, the environment variable **KRB5CCNAME** +gets set to the name of the target cache. The real and effective user +ID are changed to that of the target user. The target user's shell is +then invoked (the shell name is specified in the password file). Upon +termination of the shell, ksu deletes the target cache (unless ksu is +invoked with the **-k** option). This is implemented by first doing a +fork and then an exec, instead of just exec, as done by su. + + +CREATING A NEW SECURITY CONTEXT +------------------------------- + +ksu can be used to create a new security context for the target +program (either the target shell, or command specified via the **-e** +option). The target program inherits a set of credentials from the +source user. By default, this set includes all of the credentials in +the source cache plus any additional credentials obtained during +authentication. The source user is able to limit the credentials in +this set by using **-z** or **-Z** option. **-z** restricts the copy +of tickets from the source cache to the target cache to only the +tickets where client == the target principal name. The **-Z** option +provides the target user with a fresh target cache (no creds in the +cache). Note that for security reasons, when the source user is root +and target user is non-root, **-z** option is the default mode of +operation. + +While no authentication takes place if the source user is root or is +the same as the target user, additional tickets can still be obtained +for the target cache. If **-n** is specified and no credentials can +be copied to the target cache, the source user is prompted for a +Kerberos password (unless **-Z** specified or **GET_TGT_VIA_PASSWD** +is undefined). If successful, a TGT is obtained from the Kerberos +server and stored in the target cache. Otherwise, if a password is +not provided (user hit return) ksu continues in a normal mode of +operation (the target cache will not contain the desired TGT). If the +wrong password is typed in, ksu fails. + +.. note:: During authentication, only the tickets that could be + obtained without providing a password are cached in in the + source cache. + + +OPTIONS +------- + +**-n** *target_principal_name* + Specify a Kerberos target principal name. Used in authentication + and authorization phases of ksu. + + If ksu is invoked without **-n**, a default principal name is + assigned via the following heuristic: + + * Case 1: source user is non-root. + + If the target user is the source user the default principal name + is set to the default principal of the source cache. If the + cache does not exist then the default principal name is set to + ``target_user@local_realm``. If the source and target users are + different and neither ``~target_user/.k5users`` nor + ``~target_user/.k5login`` exist then the default principal name + is ``target_user_login_name@local_realm``. Otherwise, starting + with the first principal listed below, ksu checks if the + principal is authorized to access the target account and whether + there is a legitimate ticket for that principal in the source + cache. If both conditions are met that principal becomes the + default target principal, otherwise go to the next principal. + + a) default principal of the source cache + b) target_user\@local_realm + c) source_user\@local_realm + + If a-c fails try any principal for which there is a ticket in + the source cache and that is authorized to access the target + account. If that fails select the first principal that is + authorized to access the target account from the above list. If + none are authorized and ksu is configured with + **PRINC_LOOK_AHEAD** turned on, select the default principal as + follows: + + For each candidate in the above list, select an authorized + principal that has the same realm name and first part of the + principal name equal to the prefix of the candidate. For + example if candidate a) is ``jqpublic@ISI.EDU`` and + ``jqpublic/secure@ISI.EDU`` is authorized to access the target + account then the default principal is set to + ``jqpublic/secure@ISI.EDU``. + + * Case 2: source user is root. + + If the target user is non-root then the default principal name + is ``target_user@local_realm``. Else, if the source cache + exists the default principal name is set to the default + principal of the source cache. If the source cache does not + exist, default principal name is set to ``root\@local_realm``. + +**-c** *source_cache_name* + + Specify source cache name (e.g., ``-c FILE:/tmp/my_cache``). If + **-c** option is not used then the name is obtained from + **KRB5CCNAME** environment variable. If **KRB5CCNAME** is not + defined the source cache name is set to ``krb5cc_``. + The target cache name is automatically set to ``krb5cc_.(gen_sym())``, where gen_sym generates a new number such that + the resulting cache does not already exist. For example: + + :: + + krb5cc_1984.2 + +**-k** + Do not delete the target cache upon termination of the target + shell or a command (**-e** command). Without **-k**, ksu deletes + the target cache. + +**-D** + Turn on debug mode. + +**-z** + Restrict the copy of tickets from the source cache to the target + cache to only the tickets where client == the target principal + name. Use the **-n** option if you want the tickets for other then + the default principal. Note that the **-z** option is mutually + exclusive with the **-Z** option. + +**-Z** + Don't copy any tickets from the source cache to the target cache. + Just create a fresh target cache, where the default principal name + of the cache is initialized to the target principal name. Note + that the **-Z** option is mutually exclusive with the **-z** + option. + +**-q** + Suppress the printing of status messages. + +Ticket granting ticket options: + +**-l** *lifetime* **-r** *time* **-pf** + The ticket granting ticket options only apply to the case where + there are no appropriate tickets in the cache to authenticate the + source user. In this case if ksu is configured to prompt users + for a Kerberos password (**GET_TGT_VIA_PASSWD** is defined), the + ticket granting ticket options that are specified will be used + when getting a ticket granting ticket from the Kerberos server. + +**-l** *lifetime* + (:ref:`duration` string.) Specifies the lifetime to be requested + for the ticket; if this option is not specified, the default ticket + lifetime (12 hours) is used instead. + +**-r** *time* + (:ref:`duration` string.) Specifies that the **renewable** option + should be requested for the ticket, and specifies the desired + total lifetime of the ticket. + +**-p** + specifies that the **proxiable** option should be requested for + the ticket. + +**-f** + option specifies that the **forwardable** option should be + requested for the ticket. + +**-e** *command* [*args* ...] + ksu proceeds exactly the same as if it was invoked without the + **-e** option, except instead of executing the target shell, ksu + executes the specified command. Example of usage: + + :: + + ksu bob -e ls -lag + + The authorization algorithm for **-e** is as follows: + + If the source user is root or source user == target user, no + authorization takes place and the command is executed. If source + user id != 0, and ``~target_user/.k5users`` file does not exist, + authorization fails. Otherwise, ``~target_user/.k5users`` file + must have an appropriate entry for target principal to get + authorized. + + The .k5users file format: + + A single principal entry on each line that may be followed by a + list of commands that the principal is authorized to execute. A + principal name followed by a ``*`` means that the user is + authorized to execute any command. Thus, in the following + example: + + :: + + jqpublic@USC.EDU ls mail /local/kerberos/klist + jqpublic/secure@USC.EDU * + jqpublic/admin@USC.EDU + + ``jqpublic@USC.EDU`` is only authorized to execute ``ls``, + ``mail`` and ``klist`` commands. ``jqpublic/secure@USC.EDU`` is + authorized to execute any command. ``jqpublic/admin@USC.EDU`` is + not authorized to execute any command. Note, that + ``jqpublic/admin@USC.EDU`` is authorized to execute the target + shell (regular ksu, without the **-e** option) but + ``jqpublic@USC.EDU`` is not. + + The commands listed after the principal name must be either a full + path names or just the program name. In the second case, + **CMD_PATH** specifying the location of authorized programs must + be defined at the compilation time of ksu. Which command gets + executed? + + If the source user is root or the target user is the source user + or the user is authorized to execute any command (``*`` entry) + then command can be either a full or a relative path leading to + the target program. Otherwise, the user must specify either a + full path or just the program name. + +**-a** *args* + Specify arguments to be passed to the target shell. Note that all + flags and parameters following -a will be passed to the shell, + thus all options intended for ksu must precede **-a**. + + The **-a** option can be used to simulate the **-e** option if + used as follows: + + :: + + -a -c [command [arguments]]. + + **-c** is interpreted by the c-shell to execute the command. + + +INSTALLATION INSTRUCTIONS +------------------------- + +ksu can be compiled with the following four flags: + +**GET_TGT_VIA_PASSWD** + In case no appropriate tickets are found in the source cache, the + user will be prompted for a Kerberos password. The password is + then used to get a ticket granting ticket from the Kerberos + server. The danger of configuring ksu with this macro is if the + source user is logged in remotely and does not have a secure + channel, the password may get exposed. + +**PRINC_LOOK_AHEAD** + During the resolution of the default principal name, + **PRINC_LOOK_AHEAD** enables ksu to find principal names in + the .k5users file as described in the OPTIONS section + (see **-n** option). + +**CMD_PATH** + Specifies a list of directories containing programs that users are + authorized to execute (via .k5users file). + +**HAVE_GETUSERSHELL** + If the source user is non-root, ksu insists that the target user's + shell to be invoked is a "legal shell". *getusershell(3)* is + called to obtain the names of "legal shells". Note that the + target user's shell is obtained from the passwd file. + +Sample configuration: + :: + + KSU_OPTS = -DGET_TGT_VIA_PASSWD -DPRINC_LOOK_AHEAD -DCMD_PATH='"/bin /usr/ucb /local/bin" + +ksu should be owned by root and have the set user id bit turned on. + +ksu attempts to get a ticket for the end server just as Kerberized +telnet and rlogin. Thus, there must be an entry for the server in the +Kerberos database (e.g., ``host/nii.isi.edu@ISI.EDU``). The keytab +file must be in an appropriate location. + + +SIDE EFFECTS +------------ + +ksu deletes all expired tickets from the source cache. + + +AUTHOR OF KSU +------------- + +GENNADY (ARI) MEDVINSKY diff --git a/doc/users/user_commands/kswitch.rst b/doc/users/user_commands/kswitch.rst new file mode 100644 index 000000000..261660dad --- /dev/null +++ b/doc/users/user_commands/kswitch.rst @@ -0,0 +1,56 @@ +.. _kswitch(1): + +kswitch +======= + +SYNOPSIS +~~~~~~~~ + +**kswitch** +{**-c** *cachename*\|\ **-p** *principal*} + + +DESCRIPTION +----------- + +kswitch makes the specified credential cache the primary cache for the +collection, if a cache collection is available. + + +OPTIONS +------- + +**-c** *cachename* + Directly specifies the credential cache to be made primary. + +**-p** *principal* + Causes the cache collection to be searched for a cache containing + credentials for *principal*. If one is found, that collection is + made primary. + + +ENVIRONMENT +----------- + +kswitch uses the following environment variables: + +**KRB5CCNAME** + Location of the default Kerberos 5 credentials (ticket) cache, in + the form *type*:*residual*. If no *type* prefix is present, the + **FILE** type is assumed. The type of the default cache may + determine the availability of a cache collection; for instance, a + default cache of type **DIR** causes caches within the directory + to be present in the collection. + + +FILES +----- + +|ccache| + Default location of Kerberos 5 credentials cache + + +SEE ALSO +-------- + +:ref:`kinit(1)`, :ref:`kdestroy(1)`, :ref:`klist(1)`), kerberos(1) diff --git a/doc/users/user_commands/kvno.rst b/doc/users/user_commands/kvno.rst new file mode 100644 index 000000000..31ca24460 --- /dev/null +++ b/doc/users/user_commands/kvno.rst @@ -0,0 +1,86 @@ +.. _kvno(1): + +kvno +==== + +SYNOPSIS +-------- + +**kvno** +[**-c** *ccache*] +[**-e** *etype*] +[**-q**] +[**-h**] +[**-P**] +[**-S** *sname*] +[**-U** *for_user*] +*service1 service2* ... + + +DESCRIPTION +----------- + +kvno acquires a service ticket for the specified Kerberos principals +and prints out the key version numbers of each. + + +OPTIONS +------- + +**-c** *ccache* + Specifies the name of a credentials cache to use (if not the + default) + +**-e** *etype* + Specifies the enctype which will be requested for the session key + of all the services named on the command line. This is useful in + certain backward compatibility situations. + +**-q** + Suppress printing output when successful. If a service ticket + cannot be obtained, an error message will still be printed and + kvno will exit with nonzero status. + +**-h** + Prints a usage statement and exits. + +**-P** + Specifies that the *service1 service2* ... arguments are to be + treated as services for which credentials should be acquired using + constrained delegation. This option is only valid when used in + conjunction with protocol transition. + +**-S** *sname* + Specifies that the *service1 service2* ... arguments are + interpreted as hostnames, and the service principals are to be + constructed from those hostnames and the service name *sname*. + The service hostnames will be canonicalized according to the usual + rules for constructing service principals. + +**-U** *for_user* + Specifies that protocol transition (S4U2Self) is to be used to + acquire a ticket on behalf of *for_user*. If constrained + delegation is not requested, the service name must match the + credentials cache client principal. + + +ENVIRONMENT +----------- + +kvno uses the following environment variable: + +**KRB5CCNAME** + Location of the credentials (ticket) cache. + + +FILES +----- + +|ccache| + Default location of the credentials cache + + +SEE ALSO +-------- + +:ref:`kinit(1)`, :ref:`kdestroy(1)` diff --git a/doc/users/user_commands/sclient.rst b/doc/users/user_commands/sclient.rst new file mode 100644 index 000000000..ebf797253 --- /dev/null +++ b/doc/users/user_commands/sclient.rst @@ -0,0 +1,24 @@ +.. _sclient(1): + +sclient +======= + +SYNOPSIS +-------- + +**sclient** *remotehost* + + +DESCRIPTION +----------- + +sclient is a sample application, primarily useful for testing +purposes. It contacts a sample server :ref:`sserver(8)` and +authenticates to it using Kerberos version 5 tickets, then displays +the server's response. + + +SEE ALSO +-------- + +:ref:`kinit(1)`, :ref:`sserver(8)` diff --git a/doc/users/user_config/index.rst b/doc/users/user_config/index.rst new file mode 100644 index 000000000..6b3d4393b --- /dev/null +++ b/doc/users/user_config/index.rst @@ -0,0 +1,12 @@ +User config files +================= + +The following files in your home directory can be used to control the +behavior of Kerberos as it applies to your account (unless they have +been disabled by your host's configuration): + +.. toctree:: + :maxdepth: 1 + + k5login.rst + k5identity.rst diff --git a/doc/users/user_config/k5identity.rst b/doc/users/user_config/k5identity.rst new file mode 100644 index 000000000..21c340eab --- /dev/null +++ b/doc/users/user_config/k5identity.rst @@ -0,0 +1,66 @@ +.. _.k5identity(5): + +.k5identity +=========== + +DESCRIPTION +----------- + +The .k5identity file, which resides in a user's home directory, +contains a list of rules for selecting a client principals based on +the server being accessed. These rules are used to choose a +credential cache within the cache collection when possible. + +Blank lines and lines beginning with ``#`` are ignored. Each line has +the form: + + *principal* *field*\=\ *value* ... + +If the server principal meets all of the field constraints, then +principal is chosen as the client principal. The following fields are +recognized: + +**realm** + If the realm of the server principal is known, it is matched + against *value*, which may be a pattern using shell wildcards. + For host-based server principals, the realm will generally only be + known if there is a :ref:`domain_realm` section in + :ref:`krb5.conf(5)` with a mapping for the hostname. + +**service** + If the server principal is a host-based principal, its service + component is matched against *value*, which may be a pattern using + shell wildcards. + +**host** + If the server principal is a host-based principal, its hostname + component is converted to lower case and matched against *value*, + which may be a pattern using shell wildcards. + + If the server principal matches the constraints of multiple lines + in the .k5identity file, the principal from the first matching + line is used. If no line matches, credentials will be selected + some other way, such as the realm heuristic or the current primary + cache. + + +EXAMPLE +------- + +The following example .k5identity file selects the client principal +``alice@KRBTEST.COM`` if the server principal is within that realm, +the principal ``alice/root@EXAMPLE.COM`` if the server host is within +a servers subdomain, and the principal ``alice/mail@EXAMPLE.COM`` when +accessing the IMAP service on ``mail.example.com``: + + :: + + alice@KRBTEST.COM realm=KRBTEST.COM + alice/root@EXAMPLE.COM host=*.servers.example.com + alice/mail@EXAMPLE.COM host=mail.example.com service=imap + + +SEE ALSO +-------- + +kerberos(1), :ref:`krb5.conf(5)` diff --git a/doc/users/user_config/k5login.rst b/doc/users/user_config/k5login.rst new file mode 100644 index 000000000..00f5a5a3a --- /dev/null +++ b/doc/users/user_config/k5login.rst @@ -0,0 +1,53 @@ +.. _.k5login(5): + +.k5login +======== + +DESCRIPTION +----------- + +The .k5login file, which resides in a user's home directory, contains +a list of the Kerberos principals. Anyone with valid tickets for a +principal in the file is allowed host access with the UID of the user +in whose home directory the file resides. One common use is to place +a .k5login file in root's home directory, thereby granting system +administrators remote root access to the host via Kerberos. + + +EXAMPLES +-------- + +Suppose the user ``alice`` had a .k5login file in her home directory +containing the following line: + + :: + + bob@FOOBAR.ORG + +This would allow ``bob`` to use Kerberos network applications, such as +ssh(1), to access ``alice``'s account, using ``bob``'s Kerberos +tickets. + +Let us further suppose that ``alice`` is a system administrator. +Alice and the other system administrators would have their principals +in root's .k5login file on each host: + + :: + + alice@BLEEP.COM + + joeadmin/root@BLEEP.COM + +This would allow either system administrator to log in to these hosts +using their Kerberos tickets instead of having to type the root +password. Note that because ``bob`` retains the Kerberos tickets for +his own principal, ``bob@FOOBAR.ORG``, he would not have any of the +privileges that require ``alice``'s tickets, such as root access to +any of the site's hosts, or the ability to change ``alice``'s +password. + + +SEE ALSO +-------- + +kerberos(1) -- cgit