Maintaining WebAuth

This file contains procedures and information for WebAuth maintainers and for anyone else who is interested in modifying the WebAuth source.

Terminology

Please use the following terms consistently throughout the WebAuth source code and documentation:

attribute

A single key-value pair in the WebAuth token format, normally directly corresponding to a struct member in the webauth_token struct representation.

code

An error code from something other than WebAuth, usually either APR or Kerberos. Use code instead of status for these to distinguish from a WebAuth status code. If both Kerberos and APR are in use in the same function, use code for the Kerberos status code and acode for the APR status code.

raw token

An encrypted token that has not been base64-encoded. These are used in only a small number of places, primarily when one type of token with one encryption key is contained in another token with a different encryption key.

status

A WebAuth status code; specifically, one of the members of the webauth_status enum. Try to avoid using status for things other than WebAuth status codes, since mixing and matching codes from different subsystems gets confusing.

token

A WebAuth protocol token. This comes in three forms: a webauth_token struct (representing any token), one of the specific webauth_token_* structs for a particular token, or an encrypted and base64-encoded string.

Standard Namespace Prefixes

All macros, functions, struct names, union names, and enum names used in WebAuth code should have standard prefixes to maintain namespace separation from other C libraries and user code. The following prefixes are used for all types of public names except macros:

mwa_          Internal to mod_webauth
mwk_          Internal to mod_webkdc
mwl_          Internal to mod_webauthldap
wai_          Internal to libwebauth and not visible outside it
wat_          Internal to the WebAuth test suite
webauth_      Part of the public WebAuth API

For macros, use the following:

MWA_          Internal to mod_webauth
MWK_          Internal to mod_webkdc
WA_           Part of the public WebAuth API or internal to libwebauth

Standard Variable Names

Use the following variables by preference in all WebAuth code for consistency. It makes it much easier to read unfamiliar parts of the code.

ctx

The WebAuth context.

kc

The WebAuth Kerberos context (struct webauth_krb5 *).

s

The WebAuth status code. Used either for storing the results of running WebAuth functions that return a status code or for storing the status code that will be returned by this function (or frequently both).

Building Module Documentation

The files doc/mod_*.xml have the module documentation for the Apache modules that come with WebAuth, in the XML format that is used for the Apache reference manual. Pre-built copies of the HTML files suitable for dropping into a built Apache 2.x manual directory are also provided for convenience.

Whenever the module documentation is changed in the XML files, the HTML files need to be rebuilt. Basic instructions for doing so are at:

<http://httpd.apache.org/docs-project/docsformat.html>

The basic steps are as follows:

    svn co \
        http://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x/docs/ \
        apache-docs
    cd apache-docs/manual
    svn co http://svn.apache.org/repos/asf/httpd/docs-build/trunk build
    cd build
    JAVA_HOME=/usr/lib/jvm/default-java  # (whatever your java home is)
    export JAVA_HOME
    cp /path/to/webauth/doc/mod_*.xml* ../mod/
    ./build.sh

Following that procedure should generate:

    ../mod/mod_web{auth,authldap,kdc}.html.en

which can then be copied into the WebAuth tree.

Once this infrastructure is set up, regenerating the documentation is only a matter of copying in new *.xml files and ./build.sh will incrementally rebuild only those files.

After copying the files back, run docs/scripts/clean-apache-manual on each of the newly-generated HTML files. This script will clean up some problems with the HTML generated by the Apache build process, generally by removing parts that are specific to the internal Apache documentation.

Making a Release

Follow the following steps to make a new full release of WebAuth:

  1. Make sure that NEWS is up-to-date. Update the release date in NEWS to the current date. Update the revision number in configure.ac and in README to the new release. Commit that change with a comment of "Release <version>".

  2. Check whether the shared library revision needs to be increased. This is set in Makefile.am in the LDFLAGS setting for libwebauth.la. Follow the instructions in the "Updating version info" section of the Libtool manual.

    If backward-incompatible changes were made to the library ABI, also change the symbol versioning in lib/libwebauth.map by changing the numbers after WEBAUTH to match the new major release of the WebAuth package. (Any backward-incompatible changes should generally force an increase of the second version number of the WebAuth version.)

  3. Check out a copy of the WebAuth tree, run ./autogen (making sure to use appropriate versions of Autoconf, Automake, and Libtool), and run ./configure with whatever options are needed to get it to finish.

  4. Run make distcheck. This will generate .tar.gz and .tar.xz files containing the source distribution and run through the test suite.

  5. Going back to the checked-out tree that you used to generate the release, tag the release point with git tag -s release/<version> and a tag comment of "WebAuth release <version>".

  6. Prepare new Debian packages. Switch to the Debian branch and import the new upstream tarball with the command:

      $ gbp import-orig --upstream-vcs-tag release/<version> <path>

    where <path> is the path to the .tar.xz file. (If you have previously done this for the same version and are reimporting, delete the upstream/<version> tag first with git tag -d.) For older versions of git-buildpackage, use git-import-orig as the command instead. Then update the packaging as needed, including a new changelog entry, and build the package and ensure it passes its test suite.

  7. Optionally, install this release on one server and run through the full test suite. This may have already been done as part of the preparation for the release. If one needs to wait for a bit before releasing at this point, don't forget to go back and update the date in NEWS and re-run make dist to generate the final tarballs when the release is actually ready.

  8. Sign the .tar.gz and .tar.xz files with the WebAuth signing key:

      $ gpg --detach-sign --armor -u webauth-team@lists <dist>.tar.gz

    where <dist>.tar.gz is the distribution tarball.

  9. Copy the resulting .tar.gz, .tar.gz.asc, .tar.xz, and .tar.xz.asc files into the dist subdirectory of the WebAuth web site.

  10. Based on the NEWS file, write up a release announcement. Convert that announcement to thread and put it in the news subdirectory of the WebAuth web site. The naming convention for release announcements is <version>-announce.th where <version> is the version of the release without any periods. See the existing announcements for the structure and the correct sidebar links.

    Add a short news entry to the main page and also to the index.th file in the news directory.

  11. Update the MD5 checksum and the links in download.th to correspond to the current release.

  12. Post the release announcement to the appropriate mailing lists.

License

Copyright 2009, 2010, 2011, 2012, 2013, 2014

The Board of Trustees of the Leland Stanford Junior University

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.

Converted to XHTML by faq2html version 1.36