1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
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:
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 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.
3. Run make distcheck. This will generate a .tar.gz file containing
the source distribution and run through the test suite.
4. 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.
5. Sign the .tar.gz file with the WebAuth signing key:
$ gpg --detach-sign --armor -u webauth-team@lists <dist>.tar.gz
where <dist>.tar.gz is the distribution tarball. Contact Russ about
the signing key if you need to do this part and don't already have
it.
6. Copy the resulting .tar.gz and .tar.gz.asc files into the dist
subdirectory of the WebAuth web site.
7. 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.
8. Update the MD5 checksum and the links in download.th to correspond
to the current release.
9. Post the release announcement to the appropriate newsgroups and
mailing lists.
10. 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 "Release <version>".
License
Copyright 2009, 2010, 2011, 2012, 2013
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.
|
