diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/2/INDEX | 17 | ||||
| -rw-r--r-- | man/2/factotum | 201 | ||||
| -rw-r--r-- | man/2/keyring-crypt | 21 |
3 files changed, 230 insertions, 9 deletions
diff --git a/man/2/INDEX b/man/2/INDEX index 8e1c43ca..c1c27311 100644 --- a/man/2/INDEX +++ b/man/2/INDEX @@ -94,10 +94,25 @@ encoding encoding env env ether ether exception exception +attrtext factotum +challenge factotum +copyattrs factotum +delattr factotum factotum factotum +factotum factotum factotum +findattr factotum +findattrval factotum +getuserpassd factotum mount factotum -proxy factotum +open factotum +parseattrs factotum +proxy +publicattrs factotum +respond factotum +response factotum rpc factotum +rpcattrs factotum +takeattrs factotum expand filepat filepat filepat match filepat diff --git a/man/2/factotum b/man/2/factotum index b13062aa..180ed100 100644 --- a/man/2/factotum +++ b/man/2/factotum @@ -1,6 +1,7 @@ .TH FACTOTUM 2 .SH NAME -Factotum: mount, proxy, rpc \- client interface to factotum +Factotum: attrtext, challenge, copyattrs, delattr, findattr, findattrval, getuserpassd, mount, open, parseattrs, proxy, +publicattrs, takeattrs, respond, response, rpc, rpcattrs \- client interface to factotum .SH SYNOPSIS .EX include "factotum.m"; @@ -18,11 +19,41 @@ AuthRpcMax: con \fR...\fP; init: fn(); mount: fn(fd: ref Sys->FD, mnt: string, flags: int, aname: string): (int, ref Authinfo); + getuserpasswd: fn(keyspec: string): (string, string); -rpc: fn(facfd: ref Sys->FD, verb: string, a: array of byte): - (string, array of byte); -proxy: fn(afd: ref Sys->FD, facfd: ref Sys->FD, arg: string): - ref Authinfo; + +Challenge: adt { + user: string; # user (some protocols) + chal: string; # challenge string +}; + +challenge: fn(keyspec: string): ref Challenge; +response: fn(c: ref Challenge, resp: string): ref Authinfo; +respond: fn(chal: string, keyspec: string): (string, string); + +open: fn(): ref Sys->FD; +rpc: fn(facfd: ref Sys->FD, verb: string, a: array of byte): + (string, array of byte); +proxy: fn(afd: ref Sys->FD, facfd: ref Sys->FD, arg: string): + ref Authinfo; +rpcattrs: fn(facfd: ref Sys->FD): list of ref Attr; + +Attr: adt { + tag: int; # Aattr, Aval, or Aquery + name: string; + val: string; + + text: fn(a: self ref Attr): string; +}; + +parseattrs: fn(s: string): list of ref Attr; +copyattrs: fn(l: list of ref Attr): list of ref Attr; +delattr: fn(l: list of ref Attr, n: string): list of ref Attr; +takeattrs: fn(l: list of ref Attr, names: list of string): list of ref Attr; +findattr: fn(l: list of ref Attr, n: string): ref Attr; +findattrval: fn(l: list of ref Attr, n: string): string; +publicattrs: fn(l: list of ref Attr): list of ref Attr; +attrtext: fn(l: list of ref Attr): string; .EE .SH DESCRIPTION .B Factotum @@ -34,6 +65,12 @@ It can also interact with Plan 9's if that is in the name space (as well as or instead of .IR factotum (4)). .PP +.B Factotum +supports both the basic RPC interface to +.I factotum +and various high-level operations built on that. +The high-level functions will be described first. +.PP .B Init must be called before any other function. .PP @@ -92,6 +129,151 @@ and matches the given .IR keyspec . The tuple values are nil if no entry matches or the caller lacks permission to see them. .PP +The pair of functions +.B challenge +and +.B response +give servers access to challenge/response protocols provided by +.IR factotum . +All such authentication protocols are embedded in an application-level protocol +such as FTP, IMAP, POP3 and so on, in a way specific to that protocol. +These functions calculate parameters for application-specific messages. +.PP +A server calls +.B challenge +to get a challenge value to present to the user who will answer the challenge. +The server verifies the user's response by calling +.BR response , +which returns an +.B Authinfo +value (as described above) if the response is correct. +The specific challenge/response protocol is selected by the +.B proto +attribute in the +.I keyspec +for +.BR challenge , +which opens a connection to +.IR factotum , +obtains a string representing a challenge value, +and returns a reference to a +.B Challenge +adt that gives the challenge and a user name. +Some protocols take the user name from a +.B user +attribute in the +.IR keyspec , +and others negotiate it within the authentication protocol. +In the latter case, the +.B user +field of the resulting +.B Challenge +gives the name negotiated. +.PP +In the other direction, a process uses +.B respond +to calculate the correct response to a given challenge. +.I Chal +is the challenge presented by a server, and +.I keyspec +gives the attributes of the relevant key in the local +.IR factotum . +.B Respond +interacts with +.I factotum +and returns a tuple +.RI ( response,\ user ) +that gives the +.I response +string to return to the server, and an optional +.I user +name, depending on the protocol. +On error, the +.I response +is nil, and the system error string contains a diagnostic. +.PP +.IR Factotum (4) +represents keys as attribute value pairs in textual form, with space-separated fields. +A field can be a value-less +.IR attribute , +an +.IB attribute = value +pair, or +.IB attribute ? +to mark a required attribute with unknown value. +An +.I attribute +name that begins with an exclamation mark +.RB ( ! ) +is to be considered hidden or secret. +Values containing white space or special characters can be quoted using the conventions of +.IR sh (1). +.PP +.B Parseattrs +parses a string +.I s +of that form into a list of +.B Attr +references. +Each +.B Attr +has a +.B tag +that identifies the value as +.B Aattr +(a value-less attribute), a +.B Aval +(an attribute-value pair), or +.B Aquery +(an attribute for which a value is needed). +Other operations include: +.TP 15n +.B copyattrs +Return a copy of attribute list +.IR l . +.TP +.B delattr +Return a copy of +.I l +removing all attributes with name +.IR n . +.TP +.B takeattrs +Return the subset of list +.I l +that contains only the attributes listed in +.IR names . +.TP +.B findattr +Return a reference to the first +.B Attr +in +.I l +with the name +.IR n . +.TP +.B findattrval +Return the value of the first attribute in +.I l +with name +.IR n ; +return nil if the attribute is not found or has no value. +.TP +.B publicattrs +Return a copy of +.I l +in which all secret attributes have been removed. +.TP +.B attrtext +Return the textual representation of attribute list +.IR l , +acceptable to +.BR parseattrs . +.PP +The low-level interfaces to +.I factotum +are as follows. +.PP .B Proxy links an authenticating server on .I afd @@ -101,16 +283,19 @@ agent on .IR facfd . Typically .I facfd -is the result of +is the result of calling +.BR Factotum->open , +which is equivalent to .IP .EX sys->open("/mnt/factotum/rpc", Sys->ORDWR) .EE .PP .I Afd -is typically the result of +is a file descriptor that represents a connection to the service that requires authentication. +It is typically the result of .IR sys-open (2), -.IR sys-dial (2), +.IR dial (2), or .IR sys-fauth (2). .I Params diff --git a/man/2/keyring-crypt b/man/2/keyring-crypt index a083e543..6a5be85e 100644 --- a/man/2/keyring-crypt +++ b/man/2/keyring-crypt @@ -15,6 +15,12 @@ aessetup: fn(key: array of byte, ivec: array of byte): ref AESstate; aescbc: fn(state: ref AESstate, buf: array of byte, n: int, direction: int); +BFbsize: con 8; + +blowfishsetup: fn(key: array of byte, ivec: array of byte): ref BFstate; +blowfishcbc: fn(state: ref BFstate, buf: array of byte, + n: int, direction: int); + DESbsize: con 8; dessetup: fn(key: array of byte, ivec: array of byte): ref DESstate; @@ -88,6 +94,21 @@ should be bytes of random data: random enough to be unlikely to be reused but not cryptographically strongly unpredictable. .TP +.B blowfish +Bruce Schneier's symmetric block cipher. +The +.I key +is any length from 4 to 56 bytes. +.I Ivec +if non-nil is +.B BFbsize +bytes of random data. +For +.BR blowfishcbc , +.I n +must be a multiple of +.BR BFbsize . +.TP .B des The older Data Encryption Standard, DES. .I Key |