.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "WA_KEYRING 1" .TH WA_KEYRING 1 "2012-04-25" "4.1.1" "WebAuth" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" wa_keyring \- WebAuth keyring manipulation tool .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBwa_keyring\fR [\-\fB\-hv\fR] \fB\-f\fR \fIfile\fR \fIcommand\fR [\fIarg\fR ...] .PP \&\fBwa_keyring\fR \fB\-f\fR \fIkeyring\fR add \fIvalid-after\fR .PP \&\fBwa_keyring\fR \fB\-f\fR \fIkeyring\fR gc \fIoldest-valid-after-to-keep\fR .PP \&\fBwa_keyring\fR \fB\-f\fR \fIkeyring\fR list .PP \&\fBwa_keyring\fR \fB\-f\fR \fIkeyring\fR remove \fIid\fR .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBwa_keyring\fR is a command line tool to manage WebAuth key ring files, which contain the private \s-1AES\s0 keys used by mod_webauth and mod_webkdc. It supports the following individual commands: .IP "add \fIvalid-after\fR" 4 .IX Item "add valid-after" Adds a new key to the key ring. \fIvalid-after\fR uses the format: .Sp .Vb 1 \& nnnn[s|m|h|d|w] .Ve .Sp to indicate a time relative to the current time. The units for the time are specified by appending a single letter. That letter can be any of s, m, h, d, or w, which correspond to seconds, minutes, hours, days, and weeks respectively. .Sp For example: 10d is 10 days from the current time, and \-60d is 60 days before the current time. .IP "gc \fIoldest-valid-after-to-keep\fR" 4 .IX Item "gc oldest-valid-after-to-keep" Garbage collects (removes) old keys on the key ring. Any keys with a \&\fIvalid-after\fR date older then the specified time will be removed from the key ring. .Sp The format for \fIoldest-valid-after-to-keep\fR is the same as \fIvalid-after\fR from the add command. Note that this means that times given to the gc command should generally be negative, to remove keys that have expired in the past. .IP "list" 4 .IX Item "list" Lists all the keys in the key ring. By default, a brief listing is used, but a verbose listing can be requested with the \fB\-v\fR option. .Sp The following fields are present in a short listing: .RS 4 .IP "\fBid\fR" 4 .IX Item "id" The index/position of the key in the key ring. .IP "\fBCreated\fR" 4 .IX Item "Created" The date the key was created. .IP "\fBValid after\fR" 4 .IX Item "Valid after" The date at which the key becomes valid (in other words, the point at which the WebAuth server will start using it to encrypt and decrypt new data). .IP "\fBFingerprint\fR" 4 .IX Item "Fingerprint" The \s-1MD5\s0 digest of the key data. Used to compare keys in two key rings. .RE .RS 4 .Sp The following fields are present in the long listing: .IP "\fBKey-Id\fR" 4 .IX Item "Key-Id" The index/position of the key in the key ring. .IP "\fBCreated\fR" 4 .IX Item "Created" The date the key was created. .IP "\fBValid-After\fR" 4 .IX Item "Valid-After" The date at which the key becomes valid (in other words, the point at which the WebAuth server will start using it to encrypt and decrypt new data). .IP "\fBKey-Type\fR" 4 .IX Item "Key-Type" The type of key. Currently, \s-1AES\s0 is the only supported key type. .IP "\fBKey-Size\fR" 4 .IX Item "Key-Size" Length in bytes of the key. .IP "\fBFingerprint\fR" 4 .IX Item "Fingerprint" The \s-1MD5\s0 digest of the key data. Used to compare keys in two key rings. .RE .RS 4 .RE .IP "remove \fIid\fR" 4 .IX Item "remove id" Remove the key with \s-1ID\s0 \fIid\fR from the key ring. .SH "EXAMPLES" .IX Header "EXAMPLES" Add a key to the keyring valid as of the current time: .PP .Vb 1 \& wa_keyring \-f keyring add 0d .Ve .PP Add a key to the keyring that will be valid three days from now: .PP .Vb 1 \& wa_keyring \-f keyring add 3d .Ve .PP Remove keys from the key ring that became invalid more than 90 days ago: .PP .Vb 1 \& wa_keyring \-f keyring gc \-90d .Ve .PP Remove the first key in the keyring. .PP .Vb 1 \& wa_keyring \-f keyring remove 0 .Ve .PP Display a verbose listing of all of the keys in the key ring: .PP .Vb 1 \& wa_keyring \-f keyring \-v list .Ve .PP Note that a WebAuth server will normally manage its keyring file by itself, and \fBwa_keyring\fR is normally only used for debugging purposes. However, if you are setting up a load-balanced pool of servers that need to all share the same keys, turn off automatic keyring handling by putting the line: .PP .Vb 1 \& WebAuthKeyringAutoUpdate off .Ve .PP to your Apache configuration, running a script periodically from cron on one server that does something like: .PP .Vb 2 \& wa_keyring \-f keyring gc \-90d \& wa_keyring \-f keyring add 2d .Ve .PP and then copying (in a secure manner!) the new keyring file to all of the other servers. .SH "AUTHOR" .IX Header "AUTHOR" Roland Schemers