1# Perl representation of a WebAuth id token.
2#
3# Written by Russ Allbery <eagle@eyrie.org>
4# Copyright 2012, 2013
5#     The Board of Trustees of the Leland Stanford Junior University
6#
7# Permission is hereby granted, free of charge, to any person obtaining a copy
8# of this software and associated documentation files (the "Software"), to
9# deal in the Software without restriction, including without limitation the
10# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
11# sell copies of the Software, and to permit persons to whom the Software is
12# furnished to do so, subject to the following conditions:
13#
14# The above copyright notice and this permission notice shall be included in
15# all copies or substantial portions of the Software.
16#
17# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
20# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
22# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
23# IN THE SOFTWARE.
24
25package WebAuth::Token::Id;
26
27require 5.006;
28use strict;
29use warnings;
30
31use base qw(WebAuth::Token);
32
33our $VERSION;
34
35# This version matches the version of WebAuth with which this module was
36# released, but with two digits for the minor and patch versions.
37BEGIN {
38    $VERSION = '4.0700';
39}
40
41# Accessor methods.
42sub subject         { my $t = shift; $t->_attr ('subject',         @_) }
43sub authz_subject   { my $t = shift; $t->_attr ('authz_subject',   @_) }
44sub auth            { my $t = shift; $t->_attr ('auth',            @_) }
45sub auth_data       { my $t = shift; $t->_attr ('auth_data',       @_) }
46sub initial_factors { my $t = shift; $t->_attr ('initial_factors', @_) }
47sub session_factors { my $t = shift; $t->_attr ('session_factors', @_) }
48sub loa             { my $t = shift; $t->_attr ('loa',             @_) }
49sub creation        { my $t = shift; $t->_attr ('creation',        @_) }
50sub expiration      { my $t = shift; $t->_attr ('expiration',      @_) }
51
521;
53
54__END__
55
56=for stopwords
57WebAuth WebKDC KEYRING authenticator auth loa timestamp Allbery
58
59=head1 NAME
60
61WebAuth::Token::Id - WebAuth id tokens
62
63=head1 SYNOPSIS
64
65    my $token = WebAuth::Token::Id->new;
66    $token->subject ('user');
67    $token->auth ('webkdc');
68    $token->creation (time);
69    $token->expiration (time + 3600);
70    print $token->encode ($keyring), "\n";
71
72=head1 DESCRIPTION
73
74A WebAuth id token, which identifies a user to a WebAuth Authentication
75Server.  This token is sent from the WebKDC to the WAS following a user
76authentication to communicate the authentication information.
77
78=head1 CLASS METHODS
79
80=over 4
81
82=item new ()
83
84Create a new, empty WebAuth::Token::Id.  At least some attributes will
85have to be set using the accessor methods described below before the token
86can be used.
87
88=back
89
90=head1 INSTANCE METHODS
91
92As with WebAuth module functions, failures are signaled by throwing
93WebAuth::Exception rather than by return status.
94
95=head1 General Methods
96
97=over 4
98
99=item encode (KEYRING)
100
101Generate the encoded and encrypted form of this token using the provided
102KEYRING.  The encryption key used will be the one returned by the
103best_key() method of WebAuth::Keyring on that KEYRING.
104
105=back
106
107=head1 Accessor Methods
108
109=over 4
110
111=item subject ([SUBJECT])
112
113Get or set the subject, which holds the authenticated identity of the user
114holding this token.  This is set for tokens of authenticator type
115C<webkdc>, but not for tokens of authenticator type C<krb5>.
116
117=item authz_subject ([SUBJECT])
118
119Get or set the authorization subject, which holds the asserted
120authorization identity of the user holding this token.  The authorization
121identity may not match the authenticated identity.  It represents a
122request to use the authorization identity instead of the authentication
123subject when applying ACLs or determining identity in the application.
124
125=item auth ([TYPE])
126
127Get or set the authentication type, which describes what type of
128authenticator is included in this token.  Currently will be one of the
129values C<webkdc>, indicating a bearer token, and C<krb5>, indicating
130that the token contains a Kerberos authenticator.
131
132=item auth_data ([DATA])
133
134Get or set the authentication data.  If the authenticator type is C<krb5>,
135this will hold a Kerberos authenticator such as is created by the
136make_auth() function of the WebAuth::Krb5 module.  It is raw binary data.
137
138=item initial_factors ([FACTORS])
139
140Get or set a comma-separated list of authentication factors used by the
141user during initial authentication (the single sign-on transaction).  For
142a list of possible factors and their meaning, see the WebAuth protocol
143specification.
144
145=item session_factors ([FACTORS])
146
147Get or set a comma-separated list of authentication factors used by the
148user to authenticate this session (this particular visit to this WebAuth
149Application Server).  For a list of possible factors and their meaning,
150see the WebAuth protocol specification.
151
152=item loa ([LOA])
153
154Get or set the level of assurance established for this user
155authentication.  This is a number whose values are site-defined but for
156which increasing numbers represent increasing assurance for the
157authentication.
158
159=item creation ([TIMESTAMP])
160
161Get or set the creation timestamp for this token in seconds since epoch.
162If not set, the encoded token will have a creation time set to the time
163of encoding.
164
165=item expiration ([TIMESTAMP])
166
167Get or set the expiration timestamp for this token in seconds since epoch.
168
169=back
170
171=head1 AUTHOR
172
173Russ Allbery <eagle@eyrie.org>
174
175=head1 SEE ALSO
176
177WebAuth(3), WebAuth::Keyring(3), WebAuth::Krb5(3), WebAuth::Token(3)
178
179This module is part of WebAuth.  The current version is available from
180L<http://webauth.stanford.edu/>.
181
182=cut
183