Greg Hudson [Tue, 8 Jan 2013 20:20:45 +0000 (15:20 -0500)]
Allow principals to refer to nonexistent policies
Stop using and maintaining the policy_refcnt field, and do not try to
prevent deletion of a policy which is still referenced by principals.
Instead, allow principals to refer to policy names which do not exist
as policy objects; treat those principals as having no associated
policy.
In the kadmin client, warn if addprinc or modprinc tries to reference
a policy which doesn't exist, since the server will no longer error
out in this case.
Greg Hudson [Mon, 7 Jan 2013 20:22:26 +0000 (15:22 -0500)]
Stop loading policy for pw_expiration in LDAP
populate_krb5_db_entry() performs a subsidiary LDAP search to load the
password policy, which it uses to update the pw_expiration field.
This has some minimal value (it causes pw_expiration values in
principals to auto-update whenever the pw_max_life field of a policy
changes), but it's complicated, expensive, and inconsistent with the
DB2 back end. Get rid of it.
Zhanna Tsitkov [Wed, 9 Jan 2013 15:36:12 +0000 (10:36 -0500)]
Update release numbers, refs in feature list doc
At the moment the latest release number is 1.11 and the supported releases
are 1.10 and 1.9.
Also, update some references to the documents and fix typos.
Greg Hudson [Wed, 9 Jan 2013 15:21:00 +0000 (10:21 -0500)]
Error on void pointer arithmetic with gcc
Add -Werror=pointer-arith to the gcc warning flags. The equivalent
was added to the Solaris compiler flags in 2dc1ef4078acd7ca463a8eee2ef20de54e672f37 (r21886).
Greg Hudson [Wed, 9 Jan 2013 15:07:27 +0000 (10:07 -0500)]
Fix void pointer arithmetic in oid_ops.c
When asserting that out has advanced the expected number of bytes in
generic_gss_str_to_oid, avoid adding to oid->elements, which is a void
pointer. Instead subtract from out and compare.
Greg Hudson [Thu, 3 Jan 2013 18:47:01 +0000 (13:47 -0500)]
Install pkg-config data files
Add seven data files for pkg-config, corresponding to the five modules
supported by krb5-config. For krb5 and krb5-gssapi, we also provide
mit- versions for callers desiring to distinguish between our
implementation and Heimdal's.
Based on a patch from Stef Walter <stefw@gnome.org>.
Greg Hudson [Thu, 3 Jan 2013 16:07:15 +0000 (11:07 -0500)]
Move krb5-config to new src/build-tools directory
In preparation for adding a bunch of pkg-config data files, move
krb5-config into a new source tree subdirectory containing tools we
provide as outputs to other build systems.
Greg Hudson [Tue, 1 Jan 2013 05:23:43 +0000 (00:23 -0500)]
Fix gss_str_to_oid and gss_oid_to_str edge cases
Neither function correctly handled OIDs whose second arc exceeds 47
(theoretically possible if the first arc is 2). gss_str_to_oid had
additional problems: it used scanf, it didn't consistently protect
against read overrun if the input buffer wasn't null-terminated, and
it could get confused by + or - characters in the first two arcs. Fix
gss_oid_to_str and rewrite gss_str_to_oid.
Greg Hudson [Mon, 31 Dec 2012 22:21:46 +0000 (17:21 -0500)]
Fix a small memory leak in util_errmap
Calls to gssint_mecherrmap_map_errcode would result in calling
mecherror_copy with a zero-length mech OID, which would result in an
OID with 0 for length and malloc(0) for elements. On platforms which
return non-null from malloc(0), gssint_mecherrmap_destroy() wouldn't
free the elements pointer.
Avoid calling malloc(0) and don't use the length field to decide
whether to free an elements pointer.
Tom Yu [Fri, 21 Dec 2012 21:07:28 +0000 (16:07 -0500)]
Delete timestamp_to_sfstring sprintf fallback
The final fallback for krb5_timestamp_to_sfstring() is an explicit
European date-order format string passed to sprintf(). This can be
confused with a conventional US date format. Because we attempt to
build a strftime() replacement anyway, and we try passing some
unambiguous ISO 8601 date and time formats to strftime(), remove this
final fallback.
Tom Yu [Fri, 21 Dec 2012 20:45:53 +0000 (15:45 -0500)]
Add more formats to krb5_timestamp_to_sfstring
krb5_timestamp_to_string() can produce ambiguous dates. The final
fallback, "%d/%m/%Y %R", contains a European order date format that
can be confused with a US date format. Add some additional strftime()
format strings, including locale-dependent formats and some ISO 8601
formats. Remove the hardcoded strftime() format that had an ambiguous
date order.
Greg Hudson [Fri, 21 Dec 2012 17:20:43 +0000 (12:20 -0500)]
Use krb5_init_creds_context as clpreauth rock
The clpreauth rock had become a collection of alias pointers into the
init_creds context structure. Get rid of it and just pass the context
(suitably casted) to clpreauth modules. Simplify the signatures of
k5_preauth(), k5_preauth_tryagain(), process_pa_data(), and
fill_response_items() by referencing fields from the init_creds
context.
Since we can't use the non-nullity of rock->selected_preauth_type to
determine whether to record the selected preauth type, k5_preauth now
reports it in an output parameter, and get_in_tkt.c decides whether or
not to record it.
Greg Hudson [Fri, 21 Dec 2012 21:18:34 +0000 (16:18 -0500)]
Initialize ret in process_pa_data
If the for loop never consults any preauth modules and must_preauth is
false, we might never set ret, so we need to initialize it. The bug
was introduced in 5c23bce0e8d3328bb36bc85ee10cfac486b8ae9b and is
detected by some versions of gcc with -O2.
Greg Hudson [Thu, 20 Dec 2012 19:20:37 +0000 (14:20 -0500)]
Fix signed overflow check in k5_ucs2s_to_utf8s
Signed overflow must be checked before it happens, since modern
versions of gcc will optimize out checks of the result. Reported by
Nickolai Zeldovich <nickolai@csail.mit.edu>.
Greg Hudson [Thu, 20 Dec 2012 19:19:16 +0000 (14:19 -0500)]
Remove inoperative null checks in KDC code
In prepare_error_tgs, kdc_free_rstate, and kdc_fast_handle_error,
remove unnecessary null checks. The callers avoid passing null
states, and in each case we've already dereferenced the pointer
earlier. Reported by Nickolai Zeldovich <nickolai@csail.mit.edu>.
Greg Hudson [Thu, 20 Dec 2012 19:17:45 +0000 (14:17 -0500)]
Avoid null dereference in BDB dbtree error case
An error case in __bt_first would deference a null pointer. This is
an old upstream BDB bug. Use a separate variable to hold the result
of mpool_get() until it has been checked. Reported by Nickolai
Zeldovich <nickolai@csail.mit.edu>.
Greg Hudson [Thu, 20 Dec 2012 19:00:37 +0000 (14:00 -0500)]
Fix clntraw_create initialization
clntraw_create has been broken since inception; on the first call, it
would compute invalid values of xdrs and client and dereference them.
Fix that. (This is pretty strong evidence that no one has ever used
it.) Reported by Nickolai Zeldovich <nickolai@csail.mit.edu>.
Greg Hudson [Sun, 16 Dec 2012 21:55:29 +0000 (16:55 -0500)]
Simplify k5test.py environments
The initial k5test.py design, copied from the dejagnu suite, is to
create config files and environments for four expected roles: client,
server, master, and slave. This approach exaggerates the complexity
of the common case, where the configurations don't need to vary, and
limits us to having just one slave for kprop/iprop tests.
Instead, create just one configuration by default, and add a
special_env() method which sets up a differently configured
environment for the few test cases which need one. The run_as_*()
methods are collapsed into just run(), which accepts an optional
argument for the environment returned by special_env().
Greg Hudson [Sun, 18 Nov 2012 20:48:08 +0000 (15:48 -0500)]
Remove LDAP realm krbTicketPolicyReference code
ldap_realm.c had some code intended to handle a
krbTicketPolicyReference from a krbRealmContainer object, but there
wasn't enough of it to ever do anything. Remove it.
Greg Hudson [Sun, 18 Nov 2012 18:59:48 +0000 (13:59 -0500)]
Simplify LDAP KDB module container DN handling
Outside of krb5_ldap_read_krbcontainer_params and
krb5_ldap_create_krbcontainer, no fields of
krb5_ldap_krbcontainer_params were used except for the DN. There was
code to create a krbTicketPolicyReference attribute (which would fail
because the schema doesn't allow that attribute, and was never
exercised because kdb5_ldap_util would never set the parameter) and to
read fields like max ticket life from the referenced ticket policy,
but those fields were never used.
Eliminate the structure and just store the container DN in
krb5_ldap_context. Continue creating the container object when
creating a realm (by calling krb5_ldap_create_krbcontainer
unconditionally; it now exits successfully if the container already
exists), but don't ever read it.
Greg Hudson [Sun, 18 Nov 2012 01:24:11 +0000 (20:24 -0500)]
Remove unneeded code in krb5_ldap_put_principal
krb5_ldap_put_principal contained some conditionals for the case where
entry->princ is NULL, but only after entry->princ was dereferenced
unconditionally. It's not necessary to handle this case, so don't.
Greg Hudson [Thu, 20 Dec 2012 16:27:49 +0000 (11:27 -0500)]
Don't output trailing whitespace in depfix.pl
All of our deps files have a trailing space in the first line,
originating from depfix.pl. This space triggers the whitespace
checker when generating a new deps file. Get rid of the trailing
whitespace in the script; the change will be reflected in the deps
files the next time they are regenerated.
Greg Hudson [Sun, 28 Oct 2012 15:31:37 +0000 (11:31 -0400)]
Pass through module errors when preauthenticating
If we are responding to a KDC_ERR_PREAUTH_REQUIRED and cannot
preauthenticate, report the error from the first real preauth type we
tried.
k5_preauth() now accepts a boolean input indicating that it must
succeed on a real preauth type, instead of returning a boolean saying
whether or not it did.
Greg Hudson [Sat, 27 Oct 2012 19:29:48 +0000 (15:29 -0400)]
Rename internal preauth functions
The preauth functions are internal to libkrb5, so use the k5_ prefix,
don't use KRB5_CALLCONV, and prototype them in int-proto.h. Also
remove krb5_do_preauth from the Unix libkrb5 export list.
Reorder the k5_preauth() and k5_preauth_tryagain() arguments for more
consistency with the clpreauth interface, and put the output padata
arguments at the end.
Rename any remaining uses of "kcontext" to "context" in preauth2.c.
Greg Hudson [Sat, 27 Oct 2012 15:55:36 +0000 (11:55 -0400)]
Make clpreauth flags function optional
With one exception (KRB5_PADATA_PKINIT_KX), every padata type
processed by a clpreauth module is now a real preauthentication type.
Reduce the amount of boilerplate required for a clpreauth module by
making the flags method optional if all of the preauth types
advertised by the module are real.
Greg Hudson [Tue, 23 Oct 2012 17:02:12 +0000 (13:02 -0400)]
Use a proper consumer interface for clpreauth
In preauth2.c, use wrapper functions for calls to clpreauth functions.
Get rid of the expanded-out module table, instead using a helper
function to find the handle for a preauth type. Replace use counts
with a list of previously processed pa types. Check for pa type
conflicts when loading clpreauth modules.
Greg Hudson [Sun, 21 Oct 2012 23:37:14 +0000 (19:37 -0400)]
Separate clpreauth and kdcpreauth interfaces
Since there is no overlap between the clpreauth and kdcpreauth
interface declarations, there's no particular reason to combine them
into one header. For backward compatibility and convenience, leave
behind a preauth_plugin.h which includes both.
Greg Hudson [Sun, 21 Oct 2012 20:14:59 +0000 (16:14 -0400)]
Save extended messages across fallback to master
In krb5_get_init_creds_password and krb5_get_init_creds_keytab, save
the extended error before retrying against the master KDC, and restore
that state if returning the error from the original request.
Greg Hudson [Sun, 21 Oct 2012 00:16:19 +0000 (20:16 -0400)]
Simplify error message retrieval
Eliminate the scratch_buf field of struct error_info and just return a
non-localized constant error message if we can't allocate a copy of
the real one. Also rely on a conformant strerror().
Greg Hudson [Sat, 20 Oct 2012 20:52:29 +0000 (16:52 -0400)]
Style cleanup for internal error handling
Fix style issues in kerrs.c and errors.c. Rename error handling
functions to use shorter k5_ prefix. Eliminate an inoperable
krb5int_set_error() call in gic_opte_alloc and convert the other
call to use krb5_set_error_message().
Ben Kaduk [Thu, 13 Dec 2012 20:26:38 +0000 (15:26 -0500)]
Update retiring-des with real-world experience
We took notes when upgrading the ZONE.MIT.EDU realm to reduce
its usage of single-DES. Use these to give examples for the upgrade
procedure, and flesh out some parts of it that were missing or
under-specified.
Tom Yu [Mon, 17 Dec 2012 20:44:27 +0000 (15:44 -0500)]
Add copyright footer to HTML docs
The technique we use for inserting the feedback link in the footer
overrides the Sphinx basic/layout.html and agogo/layout.html footers
in a way that prevents us from getting the copyright link footer.
Copy the relevant part of the Sphinx basic/layout.html for now.
Add a copyright.rst that links to mitK5license.rst.
Nalin Dahyabhai [Thu, 13 Dec 2012 19:26:07 +0000 (14:26 -0500)]
PKINIT (draft9) null ptr deref [CVE-2012-1016]
Don't check for an agility KDF identifier in the non-draft9 reply
structure when we're building a draft9 reply, because it'll be NULL.
The KDC plugin for PKINIT can dereference a null pointer when handling
a draft9 request, leading to a crash of the KDC process. An attacker
would need to have a valid PKINIT certificate, or an unauthenticated
attacker could execute the attack if anonymous PKINIT is enabled.
Tom Yu [Thu, 13 Dec 2012 23:07:51 +0000 (18:07 -0500)]
Conditionally include MITKC logo in HTML doc
Conditionally include the MITKC logo in the HTML output from Sphinx if
the environment variable HTML_LOGO is set. During official builds for
the web site, that environment variable will point to an appropriately
scaled copy of the MITKC logo.
Ben Kaduk [Wed, 12 Dec 2012 18:23:03 +0000 (13:23 -0500)]
Better names for doxygen-Sphinx bridge functions
It is confusing when the codepath for the production doc build
involves calling functions with names like "test". Rename things
which are in active use so that routines which are actually only
used for testing are more discernable as such.
Ben Kaduk [Wed, 12 Dec 2012 15:36:18 +0000 (10:36 -0500)]
Make the doc build quieter
Don't print out every node processed (or not processed) in the
doxygen-Sphinx bridge, nor print out a summary of how many types
or functions were processed.
While here, tell doxygen to be quiet in its output as well, and
not print out each file that is generated. It still outputs
warnings, though.
Greg Hudson [Thu, 13 Dec 2012 19:53:58 +0000 (14:53 -0500)]
Use an empty challenge for the password question
If a question's challenge is NULL, it is unnecessarily difficult for a
responder callback to detect whether it was asked. So it's better to
use an empty challenge when there is no challenge data to communicate.
Do this for the "password" question.
Greg Hudson [Tue, 11 Dec 2012 19:36:06 +0000 (14:36 -0500)]
Don't finalize libraries in static build
In a build with static libraries, functions tagged with
__attribute__((destructor)) may be executed in any order, not in a
topologically sorted order as they are in shared libraries. This
could result in libcom_err functions being invoked (from another
library's finalizer) after libcom_err has been finalized, which would
(at minimum) result in using a mutex after it is destroyed. To
prevent this kind of problem, disable finalizers in the static build
regardless of whether we have compiler or linker support for them.
Reported by Mihai Serban <mihai.serban@gmail.com>.
Ben Kaduk [Tue, 11 Dec 2012 22:19:44 +0000 (17:19 -0500)]
Regenerate checked-in man pages
Pick up changes to kadmin.rst and krb5_conf.rst adding cross-references
for account lockout and detailing parameter expansion for keytab
and credentials cache names in krb5.conf
Ben Kaduk [Mon, 3 Dec 2012 20:41:04 +0000 (15:41 -0500)]
Update manpage version on master
Now that version.py is in place to update Sphinx's idea of the
version number in accordance reality, update the version in the
man pages that we check in; the master branch is currently a 1.12 prerelease.
Ben Kaduk [Tue, 27 Nov 2012 23:45:59 +0000 (18:45 -0500)]
Make sphinx warnings fatal for doc build
We currently do not have any warnings. Let us keep it that way by
making warnings fatal in maintainer-mode (and configurable on the
buildslaves). Using sphinx-build -W also causes errors to be reported
in the exit status and picked up by make, which is quite useful.
In order to allow the build bot to use -W but end-users to not use it,
SPHINX_ARGS must be passed on the command line; it cannot be set by
the convenience target 'htmlsrc'. Document this.
Ben Kaduk [Mon, 10 Dec 2012 20:02:14 +0000 (15:02 -0500)]
Do not document unused symbols
The macro KRB5_KEYUSAGE_PA_REFERRAL was defined in an early revision
of draft-ietf-krb-wg-kerberos-referrals but did not make it into
RFC 6806. We retain the definition so as to not break code implementing
the early draft, but need not document it.
Likewise, the krb5_octet_data structure and krb5_free_octet_data routine
are marked as having been originally introduced for PKINIT and "Do not
use this." They are in fact unused, and should not be documented, but
the actual definitions must remain for compatibility.
Greg Hudson [Mon, 10 Dec 2012 19:18:30 +0000 (14:18 -0500)]
Fix various integer issues
In kdc_util.c and spnego_mech.c, error returns from ASN.1 length
functions could be ignored because they were assigned to unsigned
values. In spnego_mech.c, two buffer size checks could be rewritten
to reduce the likelihood of pointer overflow. In dump.c and
kdc_preauth.c, calloc() could be used to simplify the code and avoid
multiplication overflow. In pkinit_clnt.c, the wrong value was
checked for a null result from malloc(), and the code could be
simplified.
Reported by Nickolai Zeldovich <nickolai@csail.mit.edu>.
Ben Kaduk [Thu, 29 Nov 2012 00:06:44 +0000 (19:06 -0500)]
Note notice.txt's dependency on version.py
This dependency has been in effect since the notice build was changed
to use the main conf.py, due to its unconditional execfile('version.py').
Adding another conditional in conf.py seems to add needless complication,
it is easier to just note the dependency in the Makefile and carry on.
ticket: 7470 (new)
title: NOTICE build has unnoted dependency on version.py
tags: pullup
target_version: 1.11
Ben Kaduk [Tue, 27 Nov 2012 18:31:34 +0000 (13:31 -0500)]
Do not generate unused parts of toctree
Our css only displays up to depth 3 of the toctree, partially
because the API reference content explodes at depth 4 and that would
not be pretty to see in the sidebar. However, we would previously
always generate HTML for the full toctree and hide parts with CSS.
For the apiref, this proved to be about 65k per html file, and we
have one html file per function/type/macro.
Limit the depth of the toctree that gets generated to save on space
in the release tarball.
Unfortunately, there seems to be a Sphinx bug wherein the toctree
will only be generated to depth 1 for a document at a depth greater
than the maxdepth of the toctree, so the sidebar table of contents
on individual apiref pages will just be the toplevel toctree.
This issue is being tracked at
https://bitbucket.org/birkenfeld/sphinx/issue/1046/
Ben Kaduk [Wed, 28 Nov 2012 19:19:43 +0000 (14:19 -0500)]
Reformat RST to avoid sphinx warnings
Old versions of docutils will see inline markup (e.g., :ref:`foo`)
at the beginning of a line in the content of a directive block
and attempt to interpret that markup as options or arguments
to the directive. RST intended as inline markup (as opposed to
modifying the behavior of the directive) will not be interpretable
in this context, and causes Sphinx to emit a warning.
Work around this behavior by always leaving a blank line before
the content of a directive block, forcing it to be interpreted
as content and not options or arguments.
The buggy behavior was only encountered in note environments, but
for consistency of style, also reformat warning and error blocks.
Tom Yu [Thu, 6 Dec 2012 23:35:59 +0000 (18:35 -0500)]
Make resources.rst more useful to non-devs
Reorder the IRC channel listing so #kerberos is first. (Developers
form a smaller part of our audience for this documentation set.)
Remove some details that are available on the wiki and not of interest
to non-developers.
Greg Hudson [Fri, 7 Dec 2012 02:40:05 +0000 (21:40 -0500)]
Don't return a host referral to the service realm
A host referral to the same realm we just looked up the principal in
is useless at best and confusing to the client at worst. Don't
respond with one in the KDC.
Ben Kaduk [Mon, 3 Dec 2012 19:21:55 +0000 (14:21 -0500)]
Access keys for the KfW ribbon interface
Improve accessibility by actually enabling access keys for ribbon
elements (tap alt and follow the onscreen hints for keys to press),
instead of just underlining a letter in the name of each element.
Supply an underlined letter in the text of each element, corresponding
to this access key, even if there is not a shortcut key bound to that
element. While here, fix conflicting assignment to 'R' on the 'options'
tab (between "Renewable Until" and "Automatic Ticket Renewal") by
making "Automatic Ticket Renewal" use 'T'. Microsoft's UI recommendations
seem to say that access keys should be easy to locate when searching
through the menu, and thus using the first letter of the first or
second word is advisable.
The Ribbon XML Reference seems to indicate that these elements should
be "keytip" elements, but MSVS creates "keys" elements, which seem
to work, whereas "keytip" does not. Apparently 'F' is standard for
the application button menu (which contains exit). Access keys work
somewhat poorly for us in this menu, as they appear on top of the text
of the menu items, since we have no icons here.
Ben Kaduk [Mon, 3 Dec 2012 17:25:07 +0000 (12:25 -0500)]
Leave 'OK' button visible in Leash AboutBox
The AboutBox dialog as specified in the resource file is larger than
the one we display; the dialog init routine marks several things as
non-visible, moves the 'OK' button up to where the now-invisible items
were, and shrinks the dialog's bounding rectangle.
However, the edit boxes containing copyright and version information
seem to always present as being on top of the 'OK' button, and their
background causes the button to appear almost invisible with the current
repositioning.
To keep the 'OK' button visible, reduce the amount that it is moved
(and the amount the dialog is shrunk) so that the button does not overlap
with the edit box.
Greg Hudson [Wed, 5 Dec 2012 16:42:55 +0000 (11:42 -0500)]
Cross-reference account lockout documentation
Link to the database.rst description of policy objects when talking
about them. Briefly mention the "default" policy. Link to the
kadmin_local.rst description of policy fields when referencing them.
Describe policy fields more briefly, and expand the kadmin_local.rst
descriptions where appropriate.
Zhanna Tsitkov [Fri, 30 Nov 2012 21:54:42 +0000 (16:54 -0500)]
Document key usage assigned number conflict
Document the fact that the key usage type 26 is used by both
KBKRB5_KEYUSAGE_PA_S4U_X509_USER_REQUEST and
KRB5_KEYUSAGE_PA_S4U_X509_USER_REQUEST, while 27 - by
KRB5_KEYUSAGE_PA_S4U_X509_USER_REPLY and KRB5_KEYUSAGE_PA_SAM_RESPONSE.
Also, since KRB5_KEYUSAGE_PA_REFERRAL is not actually used in MIT Kerberos
code and is not defined in the latest referrals draft
(http://tools.ietf.org/html/draft-ietf-krb-wg-kerberos-referrals-15)
mark it as "unused".
Zhanna Tsitkov [Thu, 29 Nov 2012 19:01:00 +0000 (14:01 -0500)]
Document param expansion for keytab/ccache names
The DEFCCNAME, DEFCKTNAME and DEFKTNAME configuration options are
subjects to parameter expansion. Also note that this feature
was first introduced in release 1.11.
Greg Hudson [Thu, 29 Nov 2012 01:19:37 +0000 (20:19 -0500)]
Avoid redundant socket cleanup in sendto_kdc.c
Since r25120, kill_conn() has been responsible for closing and
invalidating conn->fd. In the unlikely event that the KDC sends a TCP
response to us before we send a TCP request, we were cleaning up the
socket again, which is useless (though also harmless). Get rid of
that code.
Greg Hudson [Thu, 29 Nov 2012 06:58:13 +0000 (01:58 -0500)]
Fix spin-loop bug in k5_sendto_kdc
In the second part of the first pass over the server list, we passed
the wrong list pointer to service_fds, causing it to see only a subset
of the server entries corresponding to sel_state. This could cause
service_fds to spin if an event is reported on an fd not in the
subset.
Ben Kaduk [Tue, 20 Nov 2012 23:06:22 +0000 (18:06 -0500)]
Remove last "document not in toctree" warnings
There were two of them, for notice.rst and mitK5license.rst.
The former is included in the latter, which is linked to from
the mitK5features document but not listed in a table of contents
otherwise. Includes are processed unconditionally, so we can
add notice.rst to the exclude_patterns array (formerly unused_docs)
and its content will still be included.
If we attempt to do the same for mitK5license.rst, it is not processed
at all, and the attempt to link to it will fail. Instead, put a dummy
table of contents in the mitK5features document (which links to the
license document), with the "hidden" attribute. This satisfies the
Sphinx need to know where all the input documents are without changing
the displayed table of contents.
Ben Kaduk [Sat, 17 Nov 2012 00:48:55 +0000 (19:48 -0500)]
Render macros as literals
Some convenience macros are referring to and dereferencing pointers,
and Sphinx will get a bit confused trying to interpret this as markup.
There should never be any markup intended to be interpreted in the
value of a macro definition, so we can silence this class of
warnings by treating them as literals. (In some sense, they actually
are literals, too.)
This will cause a warning for macros that only cause a
symbol to be defined, that is, a literal "#define MACRO" with no
initializer, due to the lack of body in the inline-literal markup.
Such macros should probably be added to the exclude list for conversion
to reStructuredText in the Doxygen-Sphinx bridge, as was already
done for KRB5_OLD_CRYPTO. Support code to programmatically omit
macros of this sort is deliberately *not* included, so that explicit
action must be taken when a new macro is to be undocumented.
Also, strip leading and trailing whitespace from the macro name,
since this causes problems with the markup.
Ben Kaduk [Wed, 21 Nov 2012 16:31:06 +0000 (11:31 -0500)]
Exclude lists for doxygen API docs
Doxygen will pick up every function, macro, and typedef defined
in krb5.h; some of these may not actually be part of the public
API for one reason or another. Provide hardcoded exclude lists
for macro/function/type names for which we do not want to emit
reStructuredText documentation, and check these lists when processing
the Doxygen XML output.
Seed these lists with the macros TRUE, FALSE, KRB5_OLD_CRYPTO,
KRB5_GENERAL__, KRB5_CALLCONV, KRB5_CALLCONV_C, KRB5_CALLCONV_WRONG,
KRB5INT_BEGIN_DECLS, KRB5INT_END_DECLS, and KRB5_ATTR_DEPRECATED,
and typedefs krb5_cc_ops and krb5_responder_context. The booleans
are compatibility cruft that we do not want to advertise, and the other
macros are for internal use for signalling and platform compatibility.
The typedefs are functioning just as forward declarations.
For consistency, remove KRB5_OLD_CRYPTO.rst from the macros index; it
had no content even when we did generate it.
Ben Kaduk [Thu, 15 Nov 2012 21:27:57 +0000 (16:27 -0500)]
Handle adjacent notes from doxygen more correctly
The Doxygen documentation seems to claim that adjacent @note entries
will be collapsed into a single "note" element, as separate paragraphs.
This seems to be reflected in the XML output: multiple <para> entries
in a single <simplesec kind="note"> with a <simplesecsep/> element
between them.
Our XML-to-RST converter gets the entire contents of the simplesec
element, parsed into a unicode string with a single newline between
paragraphs. Paragraphs seem to always start with two spaces, though
I have not tracked down the origin of this behavior. Prior to this
commit, we would just output this entire unicode string directly.
Since our template puts a tab character before the note string, this
means that the first paragraph is indented by a tab and two spaces,
and the second paragraph by just two spaces. Sphinx warns about this,
as "block did not end with blank line; unexpected whitespace", and
the paragraphs are indented differently within the note.
Fix the warning by checking for newlines in the interior of the
parsed unicode string, and introducing the appropriate whitespace
for the Sphinx parser.
Ben Kaduk [Wed, 14 Nov 2012 18:44:08 +0000 (13:44 -0500)]
Fix overflowing cell in HTML table
sphinx-build defaults to the 'tabulary' environment for tables,
but uses regular 'tabular' for those involving literal blocks,
since tabulary does not handle them properly. It seems that this
deficiency of tabulary also applies to inline literals, which
are rendered as \code{} sections by the latex builder.
Fortunately, sphinx provides a workaround to force a particular
column specification for the table.
The requirement for a table:: statement after the tabularcolumns::
statement is very poorly documented.
Ben Kaduk [Tue, 20 Nov 2012 18:13:12 +0000 (13:13 -0500)]
Update doxygen markup in krb5.hin
A few places were using the standard C /* comment */ form, but
this is rendered poorly by doxygen through to our Sphinx bridge.
Use the special /**< comment */ form to get doxygen-specific behavior.
If the standard C comment form is used, the full comment (including
start and end markers) is included in the value of the macro, and
Sphinx then tries to treat the end of the comment as the start of
inline markup with no corresponding end-string, which is a warning.
Using the doxygen form of the comment, the contents of the comment
are put in a separate paragraph block, which is inserted in the
body of the generated RST document.
The markup for krb5_rd_priv() had a line that ended with an @c
markup statement without a symbol following it. This confused
doxygen into not parsing any more of the comment. The beginning
of the next line is a macro identifier with markup to auto-linkify it.
In RST, it is not possible to have a link and a terminal font on the
same text, so removing the @c is the appropriate fix.
There are also eleven deprecated functions which are replaced by
the krb5_c_* family of functions. However, referring to this class
of functions as the "krb5_c_" class of functions results in Sphinx
attempting to interpret this statement as a link to a label elsewhere
in the document, and no such label exists. To avoid this warning, use
"krb5_c_*" to refer to the class of functions, which is arguably
more correct anyways.
Ben Kaduk [Mon, 19 Nov 2012 21:36:56 +0000 (16:36 -0500)]
Make krb5_trace_info a typedef
Our doxygen-to-sphinx documentation bridge only processes typedefs
and not structure definitions, since we almost universally use
typedefs for our data structures. krb5_trace_info is the sole
exception, so bring it into the fold.
Zhanna Tsitkov [Mon, 26 Nov 2012 21:45:08 +0000 (16:45 -0500)]
Move Release tag into footer for Sphinx HTML
The current position of the Release tag is in the body of the main page
of the Sphinx html. Move it to the footer. This way the release number
can be viewed from every page.
projects / thirdparty / krb5.git / log
