.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" 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" '' . ds C` . ds C' '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 >0, 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. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" 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 "WebAuth::Keyring 3pm" .TH WebAuth::Keyring 3pm "2020-12-21" "perl v5.32.0" "User Contributed Perl Documentation" .\" 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" WebAuth::Keyring \- WebAuth keyring to hold encryption and decryption keys .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& use WebAuth qw(WA_KEY_AES WA_AES_128); \& use WebAuth::Key; \& use WebAuth::Keyring; \& \& my $wa = WebAuth\->new; \& eval { \& $key = WebAuth::Key\->new ($wa, WA_KEY_AES, WA_AES_128); \& $ring = WebAuth::Keyring\->new ($wa, $key); \& ... \& }; \& if ($@) { \& # handle exception \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This Perl class represents a keyring, which is a set of WebAuth keys with associated creation times and times after which they become valid. These keyrings can be read from and stored to files on disk and are used by WebAuth Application Servers and WebKDCs to store their encryption keys. .PP A WebAuth::Keyring object will be destroyed when the WebAuth context used to create it is destroyed, and subsequent accesses to it may cause memory access errors or other serious bugs. Be careful not to retain a copy of a WebAuth::Keyring object after the WebAuth object that created it has been destroyed. .SH "CLASS METHODS" .IX Header "CLASS METHODS" As with WebAuth module functions, failures are signaled by throwing WebAuth::Exception rather than by return status. .IP "new (\s-1WEBAUTH, KEY\s0)" 4 .IX Item "new (WEBAUTH, KEY)" .PD 0 .IP "new (\s-1WEBAUTH, SIZE\s0)" 4 .IX Item "new (WEBAUTH, SIZE)" .PD Create a new keyring attached to the WebAuth context \s-1WEBAUTH.\s0 .Sp The second argument to this method may be either a WebAuth::Key object or a numeric size. If a WebAuth::Key object is provided, a new keyring containing only that key will be created and returned. If a size is provided, a new, empty keyring with space preallocated to hold that many keys is created and returned. (Regardless of the allocated size of a keyring, keyrings will always dynamically expand to hold any new keys that are added to them.) .Sp This is a convenience wrapper around the WebAuth \fBkeyring_new()\fR method. .IP "decode (\s-1WEBAUTH, FILE\s0)" 4 .IX Item "decode (WEBAUTH, FILE)" Create a new WebAuth::Keyring object by decoding its contents from the provided serialized keyring data. .Sp This is a convenience wrapper around the WebAuth \fBkeyring_read()\fR method. .IP "read (\s-1WEBAUTH, FILE\s0)" 4 .IX Item "read (WEBAUTH, FILE)" Create a new WebAuth::Keyring object by reading its contents from the provided file. The created keyring object will have no association with the file after being created; it won't automatically be saved, or updated when the file changes. .Sp This is a convenience wrapper around the WebAuth \fBkeyring_read()\fR method. .SH "INSTANCE METHODS" .IX Header "INSTANCE METHODS" As with WebAuth module functions, failures are signaled by throwing WebAuth::Exception rather than by return status. .IP "add (\s-1CREATION, VALID_AFTER, KEY\s0)" 4 .IX Item "add (CREATION, VALID_AFTER, KEY)" Add a new \s-1KEY\s0 to the keyring with \s-1CREATION\s0 as the creation time and \&\s-1VALID_AFTER\s0 as the valid-after time. Both of the times should be in seconds since epoch. The key must be a WebAuth::Key object. .Sp Keys will not used for encryption until after their valid-after time, which provides an opportunity to synchronize the keyring between multiple systems before the keys are used. .IP "best_key (\s-1USAGE, HINT\s0)" 4 .IX Item "best_key (USAGE, HINT)" Returns the best key available in the keyring for a particular purpose and time. \s-1USAGE\s0 should be either WebAuth::WA_KEY_DECRYPT or WebAuth::WA_KEY_ENCRYPT and indicates whether the key will be used for decryption or encryption. For decryption keys, \s-1HINT\s0 is the timestamp of the data that will be decrypted. .Sp If \s-1USAGE\s0 is WebAuth::WA_KEY_ENCRYPT, this method will return the valid key in the keyring that was created most recently, since this is the best key to use for encryption going forward. If \s-1USAGE\s0 is WebAuth::WA_KEY_DECRYPT is false, this method will return the key most likely to have been used to encrypt something at the time \s-1HINT,\s0 where \s-1HINT\s0 is given in seconds since epoch. .IP "encode ()" 4 .IX Item "encode ()" Encode the keyring in the same serialization format that is used when writing it to a file, readable by \fBdecode()\fR or \fBread()\fR, and return the encoded form. .IP "entries ()" 4 .IX Item "entries ()" In a scalar context, returns the number of entries in the keyring. In an array context, returns a list of keyring entries as WebAuth::KeyringEntry objects. .IP "remove (\s-1INDEX\s0)" 4 .IX Item "remove (INDEX)" Removes the \s-1INDEX\s0 entry in the keyring, where \s-1INDEX\s0 is a numeric key number starting from 0. The keyring will then be compacted, so all subsequent entries in the keyring will have their index decreased by one. If you are removing multiple entries from a keyring, you should therefore remove them from the end of the keyring (the highest \s-1INDEX\s0 number) first. .IP "write (\s-1FILE\s0)" 4 .IX Item "write (FILE)" Writes the keyring out to \s-1FILE\s0 in the format suitable for later reading by \&\fBread()\fR. .SH "AUTHOR" .IX Header "AUTHOR" Russ Allbery .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBWebAuth\fR\|(3), \fBWebAuth::Key\fR\|(3), \fBWebAuth::KeyringEntry\fR\|(3) .PP This module is part of WebAuth. The current version is available from .