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
180
181
|
Wallet Server API
Introduction
Here is the specification for the API that components of the wallet
server will implement. This is the document you should read if you're
planning on extending the wallet system. There are two pluggable
components in the wallet server: the implementation of a particular
object type (which amounts mostly to storage and retrieval), and the
ACL implementation.
See the documentation for Wallet::Object::Base and Wallet::ACL::Base,
which contain additional information about creating new object and
ACL verifier implementations and the documentation for all generic
methods. Wallet::Object::Base also provides some utility methods that
are useful for subclasses.
Object API
All object implementations should inherit from Wallet::Object::Base
and most of the methods of that module can be used without change.
Below are summaries of the methods that a typical object
implementation will need to override. Methods other than create()
should set the error with error() and return undef on failure unless
otherwise noted.
attr(ATTRIBUTE [, VALUES, PRINCIPAL, HOSTNAME [, DATETIME]])
Sets or retrieves a given object attribute. Attributes are used to
store backend-specific information for a particular object type. The
default implementation rejects all ATTRIBUTEs as unknown, so if your
backend has custom attributes, you will need to override this method.
If no other arguments besides ATTRIBUTE are given, returns the values
of that attribute, if any, as a list. To distinguish between the
empty attribute list and an error, be sure to undefine $self->{error}
at the start of the method and only set the error on failure so that
the caller can call error() to determine if there was a a failure.
If other arguments are given, sets the given ATTRIBUTE values to
VALUES, which must be a reference to an array (even if only one value
is being set). Pass a reference to an empty array to clear the
attribute values. Returns true on success and false on failure.
If you override this method, be sure to check the locked flag first
and abort if the object is locked, and be sure to call log_set() (with
a "type_data <attribute>" argument) as part of storing the attribute
in the database to update the history information.
attr_show()
Returns formatted attribution information for inclusion in show().
Object implementations should not have to override show() (and
generally should not). Instead, if there is any type-specific data,
they should implement this method and return that metadata, formatted
as key:value pairs with the keys right-aligned in the first 15
characters, followed by a space, a colon, and the value. Each line
should end in a newline. If any error occurs reading the data, return
undef set the internal reror and show() will abort with an error.
The default implementation of this method returns the empty string.
create(NAME, TYPE, DBH, PRINCIPAL, HOSTNAME [, DATETIME])
Creates a new object of a particular type. The parent method will
take care of all of the database manipulation. A new object
implementation should override this method if it needs to create
something in an external system when an object is created. For
example, the keytab backend overrides create() to create the principal
in the Kerberos KDC and then calls the parent method to do the
database setup.
This method should throw an exception on error.
destroy(PRINCIPAL, HOSTNAME [, DATETIME])
Destroys the given object. Backend implementations should override
this method if they need to destroy the object in an external system
or if they have any object-specific attributes to remove. Overriding
methods should then call the parent method to do the database cleanup.
For example, the keytab backend overrides this method to destroy the
principal in the Kerberos KDC and remove the enctypes and sync
attribute data from auxiliary tables. Be careful not to require that
the object exist in a remote system for destroy() to work, since an
administrator will want to destroy an orphaned wallet database entry
after something happened to the remote system entry.
If you override this method and perform actions before calling the
parent method, be sure to check the locked flag first and abort if the
object is locked.
flag_clear(FLAG, PRINCIPAL, HOSTNAME [, DATETIME])
Normally, objects won't have to override this method, but if the
object implementation has to take special action when the unchanging
flag is cleared, this is the place to do it. Take whatever action is
needed and then call the parent method to do the database work.
flag_set(FLAG, PRINCIPAL, HOSTNAME [, DATETIME])
As with flag_set(), normally object implementations won't need to
override this method but may want to if they have to take special
actions when the unchanging flag is set. Take whatever action is
needed and then call the parent method to do the database work.
get(PRINCIPAL, HOSTNAME [, DATETIME])
This is the one method that all object implementations must override.
Wallet::Object::Base just throws an exception if its get() method is
called. Retrieves the object data from wherever that backend stores
it, or generates new object data, and should return it as a string.
Don't forget to call log_action() after successfully retrieving the
data to update the history and trace information.
Be sure to check the locked flag first and abort if the object is
locked before returning any data.
store(DATA, PRINCIPAL, HOSTNAME [, DATETIME])
Store user-supplied data into the given object. This may not be
supported by all backends (for instance, backends that automatically
generate the data will not support this). Backends that don't support
storing data can just not implement this method and the default
store() method will return an appropriate error. Don't forget to call
log_action() after successfully storing the data to update the history
and trace information.
Be sure to check the locked flag first and abort if the object is
locked without storing any data.
If this method is implemented, don't forget to call log_action() after
successfully storing the data to update the history and trace
information.
ACL Verifier API
New ACL verifiers should inherit from Wallet::ACL::Base. There are
only two methods that a new ACL verifier needs to override, and new()
is only needed if the ACL verifier has some setup that needs to be
done before starting to check ACLs.
new()
Creates a persistant ACL verifier for the given ACL type. The default
does nothing except create a blessed object. Override if the verifier
needs persistant data, like a persistant LDAP connection. On failure,
throw an exception.
check(PRINCIPAL, ACL)
This method must be overridden by any new ACL verifier implemenetation
since the default declines all access. Checks whether the given
PRINCIPAL should be allowed access given ACL. Returns 1 if access is
granted, 0 if access is declined, and undef on error. On error, the
method should pass the error to error() to store it in the object for
retrieval by the caller.
Registering New Implementations
If you have developed a new object or ACL verifier implementation, you
must register that implementation in the database before objects of
that type or ACL lines of that scheme can be created. To do this, use
the wallet-admin command-line client:
wallet-admin register object <type> <class>
wallet-admin register verifier <scheme> <class>
where <type> or <scheme> is the object type or ACL scheme and <class>
is the Perl class which implements that object type or ACL verifier.
License
Copyright 2006-2008, 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.
SPDX-License-Identifier: FSFAP
|
