~certify-web-dev/twisted/certify-trunk

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: Authentication with Perspective Broker</title><link href="../howto/stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">Authentication with Perspective Broker</h1><div class="toc"><ol><li><a href="#auto0">Overview</a></li><li><a href="#auto1">Compartmentalizing Services</a></li><ul><li><a href="#auto2">Incorrect Arguments</a></li><li><a href="#auto3">Unforgeable References</a></li><li><a href="#auto4">Argument Typechecking</a></li><li><a href="#auto5">Objects as Capabilities</a></li></ul><li><a href="#auto6">Avatars and Perspectives</a></li><li><a href="#auto7">Perspective Examples</a></li><ul><li><a href="#auto8">One Client</a></li><li><a href="#auto9">Two Clients</a></li><li><a href="#auto10">How that example worked</a></li></ul><li><a href="#auto11">Using Avatars</a></li><ul><li><a href="#auto12">Avatar Interfaces</a></li><li><a href="#auto13">Logging Out</a></li><li><a href="#auto14">Making Avatars</a></li><li><a href="#auto15">Connecting and Disconnecting</a></li><li><a href="#auto16">Viewable</a></li><li><a href="#auto17">Chat Server with Avatars</a></li></ul></ol></div><div class="content"><h2>Overview<a name="auto0"></a></h2>The examples shown in <a href="pb-usage.html">Using Perspective

Broker</a> demonstrate how to do basic remote method calls, but provided no

facilities for authentication. In this context, authentication is about who

gets which remote references, and how to restrict access to the <q>right</q>

set of people or programs.As soon as you have a program which offers services to multiple users,

where those users should not be allowed to interfere with each other, you

need to think about authentication. Many services use the idea of an

<q>account</q>, and rely upon fact that each user has access to only one

account. Twisted uses a system called <a href="cred.html">cred</a> to

handle authentication issues, and Perspective Broker has code to make it

easy to implement the most common use cases.<h2>Compartmentalizing Services<a name="auto1"></a></h2>Imagine how you would write a chat server using PB. The first step might

be a <code>ChatServer</code> object which had a bunch of

<code>pb.RemoteReference</code>s that point at user clients. Pretend that

those clients offered a <code>remote_print</code> method which lets the

server print a message on the user's console. In that case, the server might

look something like this:<pre class="python">

class ChatServer(pb.Referenceable):

def __init__(self):

self.groups = {} # indexed by name

self.users = {} # indexed by name

def remote_joinGroup(self, username, groupname):

if not self.groups.has_key(groupname):

self.groups[groupname] = []

self.groups[groupname].append(self.users[username])

def remote_sendMessage(self, from_username, groupname, message):

group = self.groups[groupname]

if group:

# send the message to all members of the group

for user in group:

user.callRemote("print",

"<%s> says: %s" % (from_username,

message))

</pre>For now, assume that all clients have somehow acquired a

<code>pb.RemoteReference</code> to this <code>ChatServer</code> object,

perhaps using <code>pb.Root</code> and <code>getRootObject</code> as

described in the <a href="pb-usage.html">previous chapter</a>. In this

scheme, when a user sends a message to the group, their client runs

something like the following:<pre class="python">

remotegroup.callRemote("sendMessage", "alice", "Hi, my name is alice.")

</pre><h3>Incorrect Arguments<a name="auto2"></a></h3>You've probably seen the first problem: users can trivially spoof each

other. We depend upon the user to pass a correct value in their

<q>username</q> argument, and have no way to tell if they're lying or not.

There is nothing to prevent Alice from modifying her client to do:<pre class="python">

remotegroup.callRemote("sendMessage", "bob", "i like pork")

</pre>much to the horror of Bob's vegetarian friends.<a href="#footnote-1" title="Apparently Alice is one of those weirdos who has nothing better to do than to try and impersonate Bob. She will lie to her chat client, send incorrect objects to remote methods, even rewrite her local client code entirely to accomplish this juvenile prank. Given this adversarial relationship, one must wonder why she and Bob seem to spend so much time together: their adventures are clearly documented by the cryptographic literature."><super>1</super></a>(In general, learn to get suspicious if you see any argument of a

remotely-invokable method described as <q>must be X</q>)The best way to fix this is to keep track of the user's name locally,

rather than asking them to send it to the server with each message. The best

place to keep state is in an object, so this suggests we need a per-user

object. Rather than choosing an obvious name<a href="#footnote-2" title="the obvious name is clearly ServerSidePerUserObjectWhichNobodyElseHasAccessTo, but because python makes everything else so easy to read, it only seems fair to make your audience work for something"><super>2</super></a>, let's call this the

<code>User</code> class.

class User(pb.Referenceable):

def __init__(self, username, server, clientref):

self.name = username

self.server = server

self.remote = clientref

def remote_joinGroup(self, groupname):

self.server.joinGroup(groupname, self)

def remote_sendMessage(self, groupname, message):

self.server.sendMessage(self.name, groupname, message)

def send(self, message):

self.remote.callRemote("print", message)

class ChatServer:

def __init__(self):

self.groups = {} # indexed by name

def joinGroup(self, groupname, user):

self.groups[groupname] = []

def sendMessage(self, from_username, groupname, message):

group = self.groups[groupname]

if group:

# send the message to all members of the group

for user in group:

user.send("<%s> says: %s" % (from_username, message))

</pre>Again, assume that each remote client gets access to a single

<code>User</code> object, which is created with the proper username.Note how the <code>ChatServer</code> object has no remote access: it

isn't even <code>pb.Referenceable</code> anymore. This means that all access

to it must be mediated through other objects, with code that is under your

control.As long as Alice only has access to her own <code>User</code> object, she

can no longer spoof Bob. The only way for her to invoke

<code>ChatServer.sendMessage</code> is to call her <code>User</code>

object's <code>remote_sendMessage</code> method, and that method uses its

own state to provide the <code>from_username</code> argument. It doesn't

give her any way to change that state.This restriction is important. The <code>User</code> object is able to

maintain its own integrity because there is a wall between the object and

the client: the client cannot inspect or modify internal state, like the

<code>.name</code> attribute. The only way through this wall is via remote

method invocations, and the only control Alice has over those invocations is

when they get invoked and what arguments they are given.<div class="note">Note: No object can maintain its integrity against local threats: by design,

Python offers no mechanism for class instances to hide their attributes, and

once an intruder has a copy of <code>self.__dict__</code>, they can do

everything the original object was able to do.</div><h3>Unforgeable References<a name="auto3"></a></h3>Now suppose you wanted to implement group parameters, for example a mode

in which nobody was allowed to talk about mattresses because some users were

sensitive and calming them down after someone said <q>mattress</q> is a

hassle that were best avoided altogether. Again, per-group state implies a

100

per-group object. We'll go out on a limb and call this the

101

<code>Group</code> object:<pre class="python">

102

class User(pb.Referenceable):

103

104

self.name = username

105

self.server = server

106

self.remote = clientref

107

def remote_joinGroup(self, groupname, allowMattress=True):

108

return self.server.joinGroup(groupname, self)

109

def send(self, message):

110

111

112

class Group(pb.Referenceable):

113

def __init__(self, groupname, allowMattress):

114

self.name = groupname

115

self.allowMattress = allowMattress

116

self.users = []

117

def remote_send(self, from_user, message):

118

if not self.allowMattress and message.find("mattress") != -1:

119

raise ValueError, "Don't say that word"

120

for user in self.users:

121

user.send("<%s> says: %s" % (from_user.name, message))

122

def addUser(self, user):

123

self.users.append(user)

124

125

class ChatServer:

126

def __init__(self):

127

self.groups = {} # indexed by name

128

129

130

self.groups[groupname] = Group(groupname, allowMattress)

131

self.groups[groupname].addUser(user)

132

return self.groups[groupname]

133

</pre>This example takes advantage of the fact that

134

<code>pb.Referenceable</code> objects sent over a wire can be returned to

135

you, and they will be turned into references to the same object that you

136

originally sent. The client cannot modify the object in any way: all they

137

can do is point at it and invoke its <code>remote_*</code> methods. Thus,

138

you can be sure that the <code>.name</code> attribute remains the same as

139

you left it. In this case, the client code would look something like

140

this:<pre class="python">

141

class ClientThing(pb.Referenceable):

142

def remote_print(self, message):

143

print message

144

def join(self):

145

d = self.remoteUser.callRemote("joinGroup", "#twisted",

146

allowMattress=False)

147

d.addCallback(self.gotGroup)

148

def gotGroup(self, group):

149

group.callRemote("send", self.remoteUser, "hi everybody")

150

</pre>The <code>User</code> object is sent from the server side, and is turned

151

into a <code>pb.RemoteReference</code> when it arrives at the client. The

152

client sends it back to <code>Group.remote_send</code>, and PB turns it back

153

into a reference to the original <code>User</code> when it gets there.

154

<code>Group.remote_send</code> can then use its <code>.name</code> attribute

155

as the sender of the message.<div class="note">Note: Third party references (there aren't any)This technique also relies upon the fact that the

156

<code>pb.Referenceable</code> reference can only come from someone

157

who holds a corresponding <code>pb.RemoteReference</code>. The design of the

158

serialization mechanism (implemented in <code class="API">twisted.spread.jelly</code>: pb, jelly, spread.. get it? Also

159

look for <q>banana</q> and <q>marmalade</q>. What other networking framework

160

can claim API names based on sandwich ingredients?) makes it impossible for

161

a client to obtain a reference that they weren't explicitly given.

162

References passed over the wire are given id numbers and recorded in a

163

per-connection dictionary. If you didn't give them the reference, the id

164

number won't be in the dict, and no amount of guessing by a malicious client

165

will give them anything else. The dict goes away when the connection is

166

dropped, further limiting the scope of those references.Futhermore, it is not possible for Bob to send his<code>User</code> reference to Alice (perhaps over some other PB channel

167

just between the two of them). Outside the context of Bob's connection to

168

the server, that reference is just a meaningless number. To prevent

169

confusion, PB will tell you if you try to give it away: when you try to hand

170

a <code>pb.RemoteReference</code> to a third party, you'll get an exception

171

(implemented with an assert in pb.py:364 RemoteReference.jellyFor).This helps the security model somewhat: only the client you gave the

172

reference to can cause any damage with it. Of course, the client might be a

173

brainless zombie, simply doing anything some third party wants. When it's

174

not proxying <code>callRemote</code> invocations, it's probably terrorizing

175

the living and searching out human brains for sustenance. In short, if you

176

don't trust them, don't give them that reference.And remember that everything you've ever given them over that connection

177

can come back to you. If expect the client to invoke your method with some

178

object A that you sent to them earlier, and instead they send you object B

179

(that you also sent to them earlier), and you don't check it somehow, then

180

you've just opened up a security hole (we'll see an example of this

181

shortly). It may be better to keep such objects in a dictionary on the

182

server side, and have the client send you an index string instead. Doing it

183

that way makes it obvious that they can send you anything they want, and

184

improves the chances that you'll remember to implement the right checks.

185

(This is exactly what PB is doing underneath, with a per-connection

186

dictionary of <code>Referenceable</code> objects, indexed by a number).And, of course, you have to make sure you don't accidentally hand out a

187

reference to the wrong object.</div>But again, note the vulnerability. If Alice holds a

188

<code>RemoteReference</code> to any object on the server side that

189

has a <code>.name</code> attribute, she can use that name as a spoofed

190

<q>from</q> parameter. As a simple example, what if her client code looked

191

like:<pre class="python">

192

class ClientThing(pb.Referenceable):

193

def join(self):

194

195

d.addCallback(self.gotGroup)

196

def gotGroup(self, group):

197

group.callRemote("send", from_user=group, "hi everybody")

198

</pre>This would let her send a message that appeared to come from

199

<q>#twisted</q> rather than <q>Alice</q>. If she joined a group that

200

happened to be named <q>bob</q> (perhaps it is the <q>How To Be Bob</q>

201

channel, populated by Alice and countless others, a place where they can

202

share stories about their best impersonating-Bob moments), then she would be

203

able to emit a message that looked like <q><bob> says: hi there</q>,

204

and she has accomplished her lifelong goal.<h3>Argument Typechecking<a name="auto4"></a></h3>There are two techniques to close this hole. The first is to have your

205

remotely-invokable methods do type-checking on their arguments: if

206

<code>Group.remote_send</code> asserted <code>isinstance(from_user,

207

User)</code> then Alice couldn't use non-User objects to do her spoofing,

208

and hopefully the rest of the system is designed well enough to prevent her

209

from obtaining access to somebody else's User object.<h3>Objects as Capabilities<a name="auto5"></a></h3>The second technique is to avoid having the client send you the objects

210

altogether. If they don't send you anything, there is nothing to verify. In

211

this case, you would have to have a per-user-per-group object, in which the

212

<code>remote_send</code> method would only take a single

213

<code>message</code> argument. The <code>UserGroup</code> object is created

214

with references to the only <code>User</code> and <code>Group</code> objects

215

that it will ever use, so no lookups are needed:<pre class="python">

216

class UserGroup(pb.Referenceable):

217

def __init__(self, user, group):

218

self.user = user

219

self.group = group

220

def remote_send(self, message):

221

self.group.send(self.user.name, message)

222

223

class Group:

224

def __init__(self, groupname, allowMattress):

225

self.name = groupname

226

self.allowMattress = allowMattress

227

self.users = []

228

def send(self, from_user, message):

229

230

raise ValueError, "Don't say that word"

231

232

user.send("<%s> says: %s" % (from_user.name, message))

233

def addUser(self, user):

234

self.users.append(user)

235

</pre>The only message-sending method Alice has left is

236

<code>UserGroup.remote_send</code>, and it only accepts a message: there are

237

no remaining ways to influence the <q>from</q> name.In this model, each remotely-accessible object represents a very small

238

set of capabilities. Security is achieved by only granting a minimal set of

239

abilities to each remote user.PB provides a shortcut which makes this technique easier to use. The

240

<code>Viewable</code> class will be discussed <a href="#viewable">below</a>.<h2>Avatars and Perspectives<a name="auto6"></a></h2>In Twisted's <a href="cred.html">cred</a> system, an <q>Avatar</q> is

241

an object that lives on the <q>server</q> side (defined here as the side

242

farthest from the human who is trying to get something done) which lets the

243

remote user get something done. The avatar isn't really a particular class,

244

it's more like a description of a role that some object plays, as in <q>the

245

Foo object here is acting as the user's avatar for this particular

246

service</q>. Generally, the remote user has some way of getting their avatar

247

to run some code. The avatar object may enforce some security checks, and

248

provide additional data, then call other methods which get things done.The two pieces in the cred puzzle (for any protocol, not just PB) are:

249

<q>what serves as the Avatar?</q>, and <q>how does the user get access to

250

it?</q>.For PB, the first question is easy. The Avatar is a remotely-accessible

251

object which can run code: this is a perfect description of

252

<code>pb.Referenceable</code> and its subclasses. We shall defer the second

253

question until the next section.In the example above, you can think of the <code>ChatServer</code> and

254

<code>Group</code> objects as a service. The <code>User</code> object is the

255

user's server-side representative: everything the user is capable of doing

256

is done by running one of its methods. Anything that the server wants to do

257

to the user (change their group membership, change their name, delete their

258

pet cat, whatever) is done by manipulating the <code>User</code> object.There are multiple User objects living in peace and harmony around the

259

ChatServer. Each has a different point of view on the services provided by

260

the ChatServer and the Groups: each may belong to different groups, some

261

might have more permissions than others (like the ability to create groups).

262

These different points of view are called <q>Perspectives</q>. This is the

263

origin of the term <q>Perspective</q> in <q>Perspective Broker</q>: PB

264

provides and controls (i.e. <q>brokers</q>) access to Perspectives.Once upon a time, these local-representative objects were actually called

265

<code>pb.Perspective</code>. But this has changed with the advent of the

266

rewritten cred system, and now the more generic term for a local

267

representative object is an Avatar. But you will still see reference to

268

<q>Perspective</q> in the code, the docs, and the module names<a href="#footnote-3" title="We could just go ahead and rename Perspective Broker to be Avatar Broker, but 1) that would cause massive compatibility problems, and 2) AB doesn't fit into the whole sandwich-themed naming scheme nearly as well as PB does. If we changed it to AB, we'd probably have to change Banana to be CD (CoderDecoder), and Jelly to be EF (EncapsulatorFragmentor). twisted.spread would then have to be renamed twisted.alphabetsoup, and then the whole food-pun thing would start all over again."><super>3</super></a>. Just remember

269

that perspectives and avatars are basically the same thing. Despite all we've been <a href="cred.html">telling you</a> about how

270

Avatars are more of a concept than an actual class, the base class from

271

which you can create your server-side avatar-ish objects is, in fact, named

272

<code>pb.Avatar</code><a href="#footnote-4" title="The avatar-ish class is named pb.Avatar because pb.Perspective was already taken, by the (now obsolete) oldcred perspective-ish class. It is a pity, but it simply wasn't possible both replace pb.Perspective in-place and maintain a reasonable level of backwards-compatibility."><super>4</super></a>. These objects behave very much like

273

<code>pb.Referenceable</code>. The only difference is that instead of

274

offering <q>remote_FOO</q> methods, they offer <q>perspective_FOO</q>

275

methods.The other way in which <code>pb.Avatar</code> differs from

276

<code>pb.Referenceable</code> is that the avatar objects are designed to be

277

the first thing retrieved by a cred-using remote client. Just as

278

<code>PBClientFactory.getRootObject</code> gives the client access to a

279

<code>pb.Root</code> object (which can then provide access to all kinds of

280

other objects), <code>PBClientFactory.login</code> gives client access to a

281

<code>pb.Avatar</code> object (which can return other references). So, the first half of using cred in your PB application is to create an

282

Avatar object which implements <code>perspective_</code> methods and is

283

careful to do useful things for the remote user while remaining vigilant

284

against being tricked with unexpected argument values. It must also be

285

careful to never give access to objects that the user should not have access

286

to, whether by returning them directly, returning objects which contain

287

them, or returning objects which can be asked (remotely) to provide

288

them.The second half is how the user gets a <code>pb.RemoteReference</code> to

289

your Avatar. As explained <a href="cred.html">elsewhere</a>, Avatars are

290

obtained from a Realm. The Realm doesn't deal with authentication at all

291

(usernames, passwords, public keys, challenge-response systems, retinal

292

scanners, real-time DNA sequencers, etc). It simply takes an <q>avatarID</q>

293

(which is effectively a username) and returns an Avatar object. The Portal

294

and its Checkers deal with authenticating the user: by the time they are

295

done, the remote user has proved their right to access the avatarID that is

296

given to the Realm, so the Realm can return a remotely-controllable object

297

that has whatever powers you wish to grant to this particular user. For PB, the realm is expected to return a <code>pb.Avatar</code> (or

298

anything which implements <code>pb.IPerspective</code>, really, but there's

299

no reason to not return a <code>pb.Avatar</code> subclass). This object will

300

be given to the client just like a <code>pb.Root</code> would be without

301

cred, and the user can get access to other objects through it (if you let

302

them).The basic idea is that there is a separate IPerspective-implementing

303

object (i.e. the Avatar subclass) (i.e. the <q>perspective</q>) for each

304

user, and only the authorized user gets a remote reference to that

305

object. You can store whatever permissions or capabilities the user

306

possesses in that object, and then use them when the user invokes a remote

307

method. You give the user access to the perspective object instead of the

308

objects that do the real work.<h2>Perspective Examples<a name="auto7"></a></h2>Here is a brief example of using a pb.Avatar. Most of the support code

309

is magic for now: we'll explain it later.<h3>One Client<a name="auto8"></a></h3><div class="py-listing"><pre>

310

#! /usr/bin/python

311

312

from twisted.spread import pb

313

from twisted.cred import checkers, portal

314

from twisted.internet import reactor

315

316

class MyPerspective(pb.Avatar):

317

def __init__(self, name):

318

self.name = name

319

def perspective_foo(self, arg):

320

print "I am", self.name, "perspective_foo(",arg,") called on", self

321

322

class MyRealm:

323

__implements__ = portal.IRealm

324

def requestAvatar(self, avatarId, mind, *interfaces):

325

if pb.IPerspective not in interfaces:

326

raise NotImplementedError

327

return pb.IPerspective, MyPerspective(avatarId), lambda:None

328

329

p = portal.Portal(MyRealm())

330

p.registerChecker(checkers.InMemoryDatabaseDontUse(user1="pass1"))

331

reactor.listenTCP(8800, pb.PBServerFactory(p))

332

reactor.run()

333

</pre><div class="caption">Source listing - <a href="listings/pb/pb5server.py">listings/pb/pb5server.py</a></div></div><div class="py-listing"><pre>

334

#! /usr/bin/python

335

336

337

338

339

340

def main():

341

factory = pb.PBClientFactory()

342

reactor.connectTCP("localhost", 8800, factory)

343

def1 = factory.login(credentials.UsernamePassword("user1", "pass1"))

344

def1.addCallback(connected)

345

reactor.run()

346

347

def connected(perspective):

348

print "got perspective ref:", perspective

349

print "asking it to foo(12)"

350

perspective.callRemote("foo", 12)

351

352

main()

353

</pre><div class="caption">Source listing - <a href="listings/pb/pb5client.py">listings/pb/pb5client.py</a></div></div>Ok, so that wasn't really very exciting. It doesn't accomplish much more

354

than the first PB example, and used a lot more code to do it. Let's try it

355

again with two users this time.<div class="note">Note: When the client runs <code>login</code> to request the Perspective,

356

they can provide it with an optional <code>client</code> argument (which

357

must be a <code>pb.Referenceable</code> object). If they do, then a

358

reference to that object will be handed to the realm's

359

<code>requestAvatar</code> in the <code>mind</code> argument.The server-side Perspective can use it to invoke remote methods on

360

something in the client, so that the client doesn't always have to drive the

361

interaction. In a chat server, the client object would be the one to which

362

<q>display text</q> messages were sent. In a board game server, this would

363

provide a way to tell the clients that someone has made a move, so they can

364

update their game boards.</div><h3>Two Clients<a name="auto9"></a></h3><div class="py-listing"><pre>

365

#! /usr/bin/python

366

367

368

369

370

371

class MyPerspective(pb.Avatar):

372

def __init__(self, name):

373

self.name = name

374

def perspective_foo(self, arg):

375

376

377

class MyRealm:

378

__implements__ = portal.IRealm

379

380

381

raise NotImplementedError

382

383

384

p = portal.Portal(MyRealm())

385

c = checkers.InMemoryUsernamePasswordDatabaseDontUse(user1="pass1",

386

user2="pass2")

387

p.registerChecker(c)

388

389

reactor.run()

390

</pre><div class="caption">Source listing - <a href="listings/pb/pb6server.py">listings/pb/pb6server.py</a></div></div><div class="py-listing"><pre>

391

#! /usr/bin/python

392

393

394

395

396

397

def main():

398

factory = pb.PBClientFactory()

399

400

401

def1.addCallback(connected)

402

reactor.run()

403

404

def connected(perspective):

405

print "got perspective1 ref:", perspective

406

print "asking it to foo(13)"

407

perspective.callRemote("foo", 13)

408

409

main()

410

</pre><div class="caption">Source listing - <a href="listings/pb/pb6client1.py">listings/pb/pb6client1.py</a></div></div><div class="py-listing"><pre>

411

#! /usr/bin/python

412

413

414

415

416

417

418

419

420

def main():

421

factory = pb.PBClientFactory()

422

423

def1 = factory.login(credentials.UsernamePassword("user2", "pass2"))

424

def1.addCallback(connected)

425

reactor.run()

426

427

def connected(perspective):

428

print "got perspective2 ref:", perspective

429

print "asking it to foo(14)"

430

perspective.callRemote("foo", 14)

431

432

main()

433

</pre><div class="caption">Source listing - <a href="listings/pb/pb6client2.py">listings/pb/pb6client2.py</a></div></div>While pb6server.py is running, try starting pb6client1, then pb6client2.

434

Compare the argument passed by the <code>.callRemote()</code> in each

435

client. You can see how each client gets connected to a different

436

Perspective.<h3>How that example worked<a name="auto10"></a></h3><a name="smallexample"></a>Let's walk through the previous example and see what was going on.First, we created a subclass called <code>MyPerspective</code> which is

437

our server-side Avatar. It implements a <code>perspective_foo</code> method

438

that is exposed to the remote client.Second, we created a realm (an object which implements

439

<code>IRealm</code>, and therefore implements <code>requestAvatar</code>).

440

This realm manufactures <code>MyPerspective</code> objects. It makes as many

441

as we want, and names each one with the avatarID (a username) that comes out

442

of the checkers. This MyRealm object returns two other objects as well,

443

which we will describe later.Third, we created a portal to hold this realm. The portal's job is to

444

dispatch incoming clients to the credential checkers, and then to request

445

Avatars for any which survive the authentication process.Fourth, we made a simple checker (an object which implements

446

<code>IChecker</code>) to hold valid user/password pairs. The checker gets

447

registered with the portal, so it knows who to ask when new clients connect.

448

We use a checker named <code>InMemoryDatabaseDontUse</code>, which suggests

449

that 1: all the username/password pairs are kept in memory instead of being

450

saved to a database or something, and 2: you shouldn't use it. The

451

admonition against using it is because there are better schemes: keeping

452

everything in memory will not work when you have thousands or millions of

453

users to keep track of, the passwords will be stored in the .tap file when

454

the application shuts down (possibly a security risk), and finally it is a

455

nuisance to add or remove users after the checker is constructed.Fifth, we create a <code>pb.PBServerFactory</code> to listen on a TCP

456

port. This factory knows how to connect the remote client to the Portal, so

457

incoming connections will be handed to the authentication process. Other

458

protocols (non-PB) would do something similar: the factory that creates

459

Protocol objects will give those objects access to the Portal so

460

authentication can take place.On the client side, a <code>pb.PBClientFactory</code> is created (as <a href="pb-usage.html">before</a>) and attached to a TCP connection. When the

461

connection completes, the factory will be asked to produce a Protocol, and

462

it will create a PB object. Unlike the previous chapter, where we used

463

<code>.getRootObject</code>, here we use <code>factory.login</code> to

464

initiate the cred authentication process. We provide a

465

<code>credentials</code> object, which is the client-side agent for doing

466

our half of the authentication process. This process may involve several

467

messages: challenges, responses, encrypted passwords, secure hashes, etc. We

468

give our credentials object everything it will need to respond correctly (in

469

this case, a username and password, but you could write a credential that

470

used public-key encryption or even fancier techniques).<code>login</code> returns a Deferred which, when it fires, will return a

471

<code>pb.RemoteReference</code> to the remote avatar. We can then do

472

<code>callRemote</code> to invoke a <code>perspective_foo</code> method on

473

that Avatar.<h2>Using Avatars<a name="auto11"></a></h2><h3>Avatar Interfaces<a name="auto12"></a></h3>The first element of the 3-tuple returned by <code>requestAvatar</code>

474

indicates which Interface this Avatar implements. For PB avatars, it will

475

always be <code>pb.IPerspective</code>, because that's the only interface

476

these avatars implement.This element is present because <code>requestAvatar</code> is actually

477

presented with a list of possible Interfaces. The question being posed to

478

the Realm is: <q>do you have an avatar for (avatarID) that can implement one

479

of the following set of Interfaces?</q>. Some portals and checkers might

480

give a list of Interfaces and the Realm could pick; the PB code only knows

481

how to do one, so we cannot take advantage of this feature.<h3>Logging Out<a name="auto13"></a></h3>The third element of the 3-tuple is a zero-argument callable, which will

482

be invoked by the protocol when the connection has been lost. We can use

483

this to notify the Avatar when the client has lost its connection. This will

484

be described in more detail below.<h3>Making Avatars<a name="auto14"></a></h3>In the example above, we create Avatars upon request, during

485

<code>requestAvatar</code>. Depending upon the service, these Avatars might

486

already exist before the connection is received, and might outlive the

487

connection. The Avatars might also accept multiple connections.Another possibility is that the Avatars might exist ahead of time, but in

488

a different form (frozen in a pickle and/or saved in a database). In this

489

case, <code>requestAvatar</code> may need to perform a database lookup and

490

then do something with the result before it can provide an avatar. In this

491

case, it would probably return a Deferred so it could provide the real

492

Avatar later, once the lookup had completed.Here are some possible implementations of

493

<code>MyRealm.requestAvatar</code>:<pre class="python">

494

# pre-existing, static avatars

495

def requestAvatar(self, avatarID, mind, *interfaces):

496

assert pb.IPerspective in interfaces

497

avatar = self.avatars[avatarID]

498

499

500

# database lookup and unpickling

501

502

503

d = self.database.fetchAvatar(avatarID)

504

d.addCallback(self.doUnpickle)

505

506

def doUnpickle(self, pickled):

507

avatar = pickle.loads(pickled)

508

return avatar

509

510

# everybody shares the same Avatar

511

512

513

return pb.IPerspective, self.theOneAvatar, lambda:None

514

515

# anonymous users share one Avatar, named users each get their own

516

517

518

if avatarID == checkers.ANONYMOUS:

519

return pb.IPerspective, self.anonAvatar, lambda:None

520

else:

521

return pb.IPerspective, self.avatars[avatarID], lambda:None

522

523

# anonymous users get independent (but temporary) Avatars

524

# named users get their own persistent one

525

526

527

if avatarID == checkers.ANONYMOUS:

528

529

else:

530

return pb.IPerspective, self.avatars[avatarID], lambda:None

531

</pre>The last example, note that the new <code>MyAvatar</code> instance is not

532

saved anywhere: it will vanish when the connection is dropped. By contrast,

533

the avatars that live in the <code>self.avatars</code> dictionary will

534

probably get persisted into the .tap file along with the Realm, the Portal,

535

and anything else that is referenced by the top-level Application object.

536

This is an easy way to manage saved user profiles.<h3>Connecting and Disconnecting<a name="auto15"></a></h3>It may be useful for your Avatars to be told when remote clients gain

537

(and lose) access to them. For example, and Avatar might be updated by

538

something in the server, and if there are clients attached, it should update

539

them (through the <q>mind</q> argument which lets the Avatar do callRemote

540

on the client).One common idiom which accomplishes this is to have the Realm tell the

541

avatar that a remote client has just attached. The Realm can also ask the

542

protocol to let it know when the connection goes away, so it can then inform

543

the Avatar that the client has detached. The third member of the

544

<code>requestAvatar</code> return tuple is a callable which will be invoked

545

when the connection is lost.<pre class="python">

546

class MyPerspective(pb.Avatar):

547

def __init__(self):

548

self.clients = []

549

def attached(self, mind):

550

self.clients.append(mind)

551

print "attached to", mind

552

def detached(self, mind):

553

self.clients.remove(mind)

554

print "detached from", mind

555

def update(self, message):

556

for c in self.clients:

557

c.callRemote("update", message)

558

559

class MyRealm:

560

def requestAvatar(self, avatarID, mind, *interfaces):

561

562

avatar = self.avatars[avatarID]

563

avatar.attached(mind)

564

return pb.IPerspective, avatar, lambda a=avatar:a.detached(mind)

565

</pre><h3>Viewable<a name="auto16"></a></h3><a name="viewable"></a>Once you have <code>IPerspective</code> objects (i.e. the Avatar) to

566

represent users, the <code base="twisted.spread.flavors" class="API">Viewable</code> class can come into play. This

567

class behaves a lot like <code>Referenceable</code>: it turns into a

568

<code>RemoteReference</code> when sent over the wire, and certain methods

569

can be invoked by the holder of that reference. However, the methods that

570

can be called have names that start with <code>view_</code> instead of

571

<code>remote_</code>, and those methods are always called with an extra

572

<code>perspective</code> argument that points to the Avatar through which

573

the reference was sent:<pre class="python">

574

class Foo(pb.Viewable):

575

def view_doFoo(self, perspective, arg1, arg2):

576

pass

577

</pre>This is useful if you want to let multiple clients share a reference to

578

the same object. The <code>view_</code> methods can use the

579

<q>perspective</q> argument to figure out which client is calling them. This

580

gives them a way to do additional permission checks, do per-user accounting,

581

etc.This is the shortcut which makes per-user-per-group capability objects

582

much easier to use. Instead of creating such per-(user,group) objects, you

583

just have per-group objects which inherit from <code>pb.Viewable</code>, and

584

give the user references to them. The local <code>pb.Avatar</code> object

585

will automatically show up as the <q>perspective</q> argument in the

586

<code>view_*</code> method calls, give you a chance to involve the Avatar in

587

the process.<h3>Chat Server with Avatars<a name="auto17"></a></h3>Combining all the above techniques, here is an example chat server which

588

uses a fixed set of identities (say, for the three members of your bridge

589

club, who hang out in <q>#NeedAFourth</q> hoping that someone will discover

590

your server, guess somebody's password, break in, join the group, and also

591

be available for a game next saturday afternoon).<div class="py-listing"><pre>

592

#! /usr/bin/python

593

594

from twisted.cred import portal, checkers

595

596

597

598

class ChatServer:

599

def __init__(self):

600

self.groups = {} # indexed by name

601

602

603

604

605

self.groups[groupname].addUser(user)

606

return self.groups[groupname]

607

608

class ChatRealm:

609

__implements__ = portal.IRealm

610

def requestAvatar(self, avatarID, mind, *interfaces):

611

612

avatar = User(avatarID)

613

avatar.server = self.server

614

avatar.attached(mind)

615

return pb.IPerspective, avatar, lambda a=avatar:a.detached(mind)

616

617

class User(pb.Avatar):

618

def __init__(self, name):

619

self.name = name

620

def attached(self, mind):

621

self.remote = mind

622

def detached(self, mind):

623

self.remote = None

624

def perspective_joinGroup(self, groupname, allowMattress=True):

625

626

def send(self, message):

627

628

629

class Group(pb.Viewable):

630

def __init__(self, groupname, allowMattress):

631

self.name = groupname

632

self.allowMattress = allowMattress

633

self.users = []

634

def addUser(self, user):

635

self.users.append(user)

636

def view_send(self, from_user, message):

637

638

raise ValueError, "Don't say that word"

639

640

user.send("<%s> says: %s" % (from_user.name, message))

641

642

realm = ChatRealm()

643

realm.server = ChatServer()

644

checker = checkers.InMemoryUsernamePasswordDatabaseDontUse()

645

checker.addUser("alice", "1234")

646

checker.addUser("bob", "secret")

647

checker.addUser("carol", "fido")

648

p = portal.Portal(realm, [checker])

649

650

651

reactor.run()

652

</pre><div class="caption">Source listing - <a href="listings/pb/chatserver.py">listings/pb/chatserver.py</a></div></div>Notice that the client uses <code>perspective_joinGroup</code> to both

653

join a group and retrieve a <code>RemoteReference</code> to the

654

<code>Group</code> object. However, the reference they get is actually to a

655

special intermediate object called a <code>pb.ViewPoint</code>. When they do

656

<code>group.callRemote("send", "message")</code>, their avatar is inserted

657

into the argument list that <code>Group.view_send</code> actually sees. This

658

lets the group get their username out of the Avatar without giving the

659

client an opportunity to spoof someone else.The client side code that joins a group and sends a message would look

660

like this:<div class="py-listing"><pre>

661

#! /usr/bin/python

662

663

664

665

666

667

class Client(pb.Referenceable):

668

669

def remote_print(self, message):

670

print message

671

672

def connect(self):

673

factory = pb.PBClientFactory()

674

675

def1 = factory.login(credentials.UsernamePassword("alice", "1234"),

676

client=self)

677

def1.addCallback(self.connected)

678

reactor.run()

679

680

def connected(self, perspective):

681

print "connected, joining group #lookingForFourth"

682

# this perspective is a reference to our User object

683

d = perspective.callRemote("joinGroup", "#lookingForFourth")

684

d.addCallback(self.gotGroup)

685

686

def gotGroup(self, group):

687

print "joined group, now sending a message to all members"

688

# 'group' is a reference to the Group object (through a ViewPoint)

689

d = group.callRemote("send", "You can call me Al.")

690

d.addCallback(self.shutdown)

691

692

def shutdown(self, result):

693

reactor.stop()

694

695

696

Client().connect()

697

</pre><div class="caption">Source listing - <a href="listings/pb/chatclient.py">listings/pb/chatclient.py</a></div></div><h2>Footnotes</h2><ol><li><a name="footnote-1">Apparently Alice is one of those weirdos who has nothing

698

better to do than to try and impersonate Bob. She will lie to her chat

699

client, send incorrect objects to remote methods, even rewrite her local

700

client code entirely to accomplish this juvenile prank. Given this

701

adversarial relationship, one must wonder why she and Bob seem to spend so

702

much time together: their adventures are clearly documented by the

703

cryptographic literature.</a></li><li><a name="footnote-2">the

704

obvious name is clearly

705

<code>ServerSidePerUserObjectWhichNobodyElseHasAccessTo</code>, but because

706

python makes everything else so easy to read, it only seems fair to make

707

your audience work for something</a></li><li><a name="footnote-3">We could just go ahead and rename Perspective Broker to be

708

Avatar Broker, but 1) that would cause massive compatibility problems, and 2)

709

<q>AB</q> doesn't fit into the whole sandwich-themed naming scheme nearly as

710

well as <q>PB</q> does. If we changed it to AB, we'd probably have to change

711

Banana to be CD (CoderDecoder), and Jelly to be EF (EncapsulatorFragmentor).

712

twisted.spread would then have to be renamed twisted.alphabetsoup, and then

713

the whole food-pun thing would start all over again.</a></li><li><a name="footnote-4">The avatar-ish class is named

714

<code>pb.Avatar</code> because <code>pb.Perspective</code> was already

715

taken, by the (now obsolete) oldcred perspective-ish class. It is a pity,

716

but it simply wasn't possible both replace <code>pb.Perspective</code>

717

in-place and maintain a reasonable level of

718

backwards-compatibility.</a></li></ol></div><a href="../howto/index.html">Index</a>Version: 2.0.1</body></html>

b'\\ No newline at end of file'

Older »