Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FACTOTUM(4)		   Kernel Interfaces Manual		   FACTOTUM(4)

NAME
       factotum	- authentication agent

SYNOPSIS
       factotum	[ -DdkSun ] [ -a authaddr ] [ -s srvname ]

       factotum	-g attribute=value ...	attribute?  ...

DESCRIPTION
       Factotum	 is  a	user-level file	system that acts as the	authentication
       agent for a user.  It does so by	managing a set of keys.	 A  key	 is  a
       collection  of  information  used  to authenticate a particular action.
       Stored as a list	of attribute=value pairs, a key	typically  contains  a
       user, an	authentication domain, a protocol, and some secret data.

       Factotum	presents the following files:

       rpc    each open	represents a new private channel to factotum

       proto  when read	lists the protocols available

       confirm
	      for confiming the	use of key

       needkey
	      allows external programs to control the addition of new keys

       log    a	log of actions

       ctl    for maintaining keys; when read, it returns a list of keys.  For
	      secret attributes, only the attribute name follow	by  a  is  re-
	      turned.

       In  any	authentication,	 the caller typically acts as a	client and the
       callee as a server.  The	server determines the  authentication  domain,
       sometimes  after	 a negotiation with the	client.	 Authentication	always
       requires	the client to prove its	identity to the	 server.   Under  some
       protocols,  the	authentication is mutual.  Proof is accomplished using
       secret information kept by factotum in conjunction with a cryptographic
       protocol.

       Factotum	 can  act in the role of client	for any	process	possessing the
       same user id as it.  For	select protocols such as p9sk1 it can also act
       as  a client for	other processes	provided its user id may speak for the
       other process' user id (see Plan	9's authsrv(6)).  Factotum can act  in
       the role	of server for any process.

       Factotum's  structure  is  independent of any particular	authentication
       protocol.  Factotum supports the	following protocols:

       p9any  a	metaprotocol used to negotiate which actual protocol to	use.

       p9sk1  a	Plan 9 shared key protocol.

       p9sk2  a	variant	of p9sk1.

       p9cr   a	Plan 9 protocol	that can use either p9sk1 keys or SecureID to-
	      kens.

       apop   the challenge/response protocol used by POP3 mail	servers.

       cram   the challenge/response protocol also used	by POP3	mail servers.

       chap   the challenge/response protocols used by PPP and PPTP.

       dsa    DSA signatures, used by SSH

       mschap a	proprietary Microsoft protocol also used by PPP	and PPTP.

       rsa    RSA encryption and signatures, used by SSH and TLS.

       pass   passwords	in the clear.

       vnc    vnc(1)'s challenge/response.

       wep    WEP  passwords  for  wireless ethernet cards.  The ``Protocols''
	      section below describes these protocols in more detail.

       The options to factotum are:

       -a     supplies the address of the authentication server	to use.	 With-
	      out  this	 option,  it  will  attempt  to	find an	authentication
	      server by	querying the connection	server,	the  file  <mtpt>/ndb,
	      and finally the network database in /lib/ndb.

       -m     specifies	the mount point	to use,	by default /mnt.

       -s     specifies	 the service name to use.  Without this	option,	facto-
	      tum does not create a service file in /srv.

       -D     turns on 9P tracing, written to standard error.

       -d     turns on debugging, written to standard error.

       -g     causes the agent to prompt for the key,  write  it  to  the  ctl
	      file, and	exit.  The agent will prompt for values	for any	of the
	      attributes ending	with a question	mark (?)  and will append  all
	      the  supplied  attribute	= value	pairs.	See the	section	on key
	      templates	below.

       -n     don't look for a secstore.

       -S     indicates	that the agent is running on a cpu server.  On	start-
	      ing,  it	will attempt to	get a 9psk1 key	from NVRAM using read-
	      nvram (see authsrv(3)), prompting	for  anything  it  needs.   It
	      will  never  subsequently	prompt for a key that it doesn't have.
	      This option is typically used by the kernel at boot time.

       -k     causes the NVRAM to be written.  It is only valid	 with  the  -S
	      option.	This  option  is  typically used by the	kernel at boot
	      time.

       -u     causes the agent	to  prompt  for	 user  id  and	writes	it  to
	      /dev/hostowner.	It is mutually exclusive with -k and -S.  This
	      option is	typically used by the kernel at	boot time.

   Key Tuples
       A key tuple is a	space delimited	list of	attribute=value	pairs.	An at-
       tribute	whose  name begins with	an exclamation point (!)  does not ap-
       pear when reading the ctl file.	Here are some examples:
	   proto=p9sk1 dom=avayalabs.com user=presotto !password=lucent
	   proto=apop server=mit.edu user=rsc !password=nerdsRus
	   proto=pass user=tb service=ssh !password=does.it.matter
       The ``Protocols'' section below describes the  attributes  specific  to
       each supported protocol.

       All  keys  can have additional attibutes	that act either	as comments or
       as selectors to distinguish them	in the auth(3) library calls.

       The factotum owner can use any key stored by  factotum.	 Any  key  may
       have one	or more	owner attributes listing the users who can use the key
       as though they were the owner.  For example, the	TLS and	SSH host  keys
       on  a  server often have	an attribute owner=* to	allow any user (and in
       particular, to run the TLS or SSH server-side protocol.

       Any key may have	a role attribute for restricting how it	can  be	 used.
       If  this	attribute is missing, the key can be used in any role.	Common
       values are:

       client for authenticating outbound calls

       server for authenticating inbound calls

       speaksfor
	      for authenticating processes whose user id does not match	facto-
	      tum's.

       encrypt
	      for encrypting data

       decrypt
	      for decrypting data

       sign   for cryptographically signing data

       verify for verifying cryptographic signatures

       Whenever	 factotum  runs	as a server, it	must have a p9sk1 key in order
       to communicate with the authentication server for validating  passwords
       and challenge/responses of other	users.

   Key Templates
       Key  templates  are used	by routines that interface to factotum such as
       auth_proxy and auth_challenge (see auth(3)) to specify  which  key  and
       protocol	 to  use  for an authentication.  Like a key tuple, a key tem-
       plate is	also a list of attribute=value	pairs.	 It  must  specify  at
       least  the  protocol and	enough other attributes	to uniquely identify a
       key, or set of keys, to use.  The keys chosen are those that match  all
       the attributes specified	in the template.  The possible attribute/value
       formats are:

       attr=val	 The attribute attr must exist in the key and its  value  must
		 exactly match val

       attr?	 The  attribute	 attr  must  exist  in	the  key but its value
		 doesn't matter.

       attr	 The attribute attr must exist in the key with a null value

       Key templates are also used by factotum to request a key	either via  an
       RPC  error  or via the needkey interface.  The possible attribute/value
       formats are:

       attr=val	 This pair must	remain unchanged

       attr?	 This attribute	needs a	value

       attr	 The pair must remain unchanged

   Control and Key Management
       A number	of messages can	be written to the control file.	  The  mesages
       are:

       key attribute-value-list
	      add a new	key.  This will	replace	any old	key whose public, i.e.
	      non ! attributes,	match.

       delkey attribute-value-list
	      delete a key whose attributes match those	given.

       debug  toggle debugging on and off, i.e., the debugging also turned  on
	      by the -d	option.

       By  default  when factotum starts it looks for a	secstore(1) account on
       $auth for the user and, if one exists, prompts for a secstore  password
       in  order to fetch the file factotum, which should contain control file
       commands.  An example would be
	 key dom=x.com proto=p9sk1 user=boyd !hex=26E522ADE2BBB2A229
	 key proto=rsa service=ssh size=1024 ek=3B !dk=...
       where the first line sets a password for	challenge/response authentica-
       tion,  strong  against dictionary attack	by being a long	random string,
       and the second line sets	a public/private keypair for  ssh  authentica-
       tion, generated by ssh_genkey (see ssh(1)).

   Confirming key use
       The  confirm file provides a connection from factotum to	a confirmation
       server, normally	the program auth/fgui.	Whenever a key with  the  con-
       firm  attribute is used,	factotum requires confirmation of its use.  If
       no process has confirm opened, use of the key will be denied.  However,
       if  the file is opened a	request	can be read from it with the following
       format:

       confirm tag=tagno _key template_

       The reply, written back to confirm, consists of string:

       tag=tagno answer=xxx

       If xxx is the string yes	then the use is	confirmed and the  authentica-
       tion will proceed.  Otherwise, it fails.

       Confirm	is exclusive open and can only be opened by a process with the
       same user id as factotum.

   Prompting for keys
       The needkey file	provides a connection from factotum to a  key  server,
       normally	 the program auth/fgui.	 Whenever factotum needs a new key, it
       first checks to see if needkey is opened.  If it	isn't,	it  returns  a
       error  to its client.  If the file is opened a request can be read from
       it with the following format:

       needkey tag=tagno _key template_

       It is up	to the reader to then query the	user for any  missing  fields,
       write  the  key tuple into the ctl file,	and then reply by writing into
       the needkey file	the string:

       tag=tagno

       Needkey is exclusive open and can only be opened	by a process with  the
       same user id as factotum.

   The RPC Protocol
       Authentication is performed by

       1)     opening rpc

       2)     setting  up  the	protocol and key to be used (see the start RPC
	      below),

       3)     shuttling	messages back and forth	between	factotum and the other
	      party (see the read and write RPC's) until done

       4)     if  successful,  reading	back  an AuthInfo structure (see auth-
	      srv(3)).

       The RPC protocol	is  normally  embodied	by  one	 of  the  routines  in
       auth(3).	 We describe it	here should anyone want	to extend the library.

       An RPC consists of writing a request message to rpc followed by reading
       a reply message back.  RPC's are	strictly ordered; requests and replies
       of  different RPC's cannot be interleaved.  Messages consist of a verb,
       a single	space, and data.  The data format depends on  the  verb.   The
       request verbs are:

       start attribute-value-list
	      start  a new authentication.  Attribute-value-pair-list must in-
	      clude a proto attribute, a role attribute	with value  client  or
	      server, and enough other attibutes to uniquely identify a	key to
	      use.  A start RPC	is required before any others.	  The possible
	      replies are:

	      ok     start succeeded.

	      error string
		     where string is the reason.

       read   get data from factotum to	send to	the other party.  The possible
	      replies are:

	      ok     read succeeded, this is zero length message.

	      ok data
		     read succeeded, the data follows the space	and is	unfor-
		     matted.

	      done   authentication has	succeeded, no further RPC's are	neces-
		     sary

	      done haveai
		     authentication has	succeeded, an AuthInfo structure  (see
		     auth(3)) can be retrieved with an authinfo	RPC

	      phase string
		     its  not  your turn to read, get some data	from the other
		     party and return it with a	write RPC.

	      error string
		     authentication failed, string is the reason.

	      protocol not started
		     a start RPC needs to precede reads	and writes

	      needkey attribute-value-list
		     a key matching the	argument is needed.  This argument may
		     be	 passed	 as  an	 argument  to  factotum	-g in order to
		     prompt for	a key.	After  that,  the  authentication  may
		     proceed, i.e., the	read restarted.

       write data
	      send  data  from	the  other  party  to  factotum.  The possible
	      replies are:

	      ok     the write succeeded

	      needkey attribute-value-list
		     see above

	      toosmall n
		     the write is too short, get  more	data  from  the	 other
		     party and retry the write.	 n specifies the maximun total
		     number of bytes.

	      phase string
		     its not your turn to write, get some data	from  factotum
		     first.

	      done   see above

	      done haveai
		     see above

       readhex,	writehex
	      like  read  and write, except that an ok response	to readhex re-
	      turns the	data encoded as	a long hexadecimal string, and the ar-
	      gument  to writehex is expected to be a long hexadecimal string.
	      These are	useful for manually debugging of binary	protocols.

       authinfo
	      retrieve the AuthInfo structure.	The possible replies are:

	      ok data
		     data is a marshaled form of the AuthInfo structure.

	      error string
		     where string is the reason	for the	error.

       attr   retrieve the attributes used in the  start  RPC.	 The  possible
	      replies are:

	      ok attribute-value-list

	      error string
		     where string is the reason	for the	error.

   Protocols
       Factotum	 supports  many	 authentication	types, each with its own roles
       and required key	attributes.

       P9any, p9sk1, p9sk2, and	p9cr are used to authenticate to Plan  9  sys-
       tems;  valid roles are client and server.  All require proto=p9sk1 keys
       with user, dom (authentication domain), and !password attributes.

       P9sk1 and p9sk2 are the Plan  9	shared-key  authentication  protocols.
       P9sk2  is  a deprecated form of p9sk1 that neglects to authenticate the
       server.

       P9any is	a meta-protocol	that negotiates	a protocol  (p9sk1  or	p9sk2)
       and an authentication domain and	then invokes the given protocol	with a
       dom= attribute.

       P9any, p9sk1, and p9sk2 are intended to be proxied via auth_proxy  (see
       auth(3)).

       P9cr  is	 a  textual  challenge-response	protocol; roles	are client and
       server.	It uses	p9sk1 keys as described	above.	The protocol with fac-
       totum  is  textual:  client  writes a user name,	server responds	with a
       challenge, client writes	a response, server responds with  ok  or  bad.
       Typically  this	information is wrapped in other	protocols before being
       sent over the network.

       Vnc is the challenge-response protocol used by vnc(1); valid roles  are
       client  and  server.  The client	protocol requires a proto=vnc key with
       attribute !password.  Conventionally, client keys also  have  user  and
       server  attributes.   The  server  protocol requires a p9sk1 key	as de-
       scribed above.  The protocol with factotum is the same as p9cr,	except
       that the	challenge and response are not textual.

       Apop  and  cram	are challenge-response protocols typically used	to au-
       thenticate to mail servers.  The	client protocols require proto=apop or
       proto=cram  keys	 with  user and	!password attributes.  Conventionally,
       client keys also	have server attributes.	 The server protocol  requires
       a p9sk1 key as described	above.	The protocol with factotum is textual:
       server writes a challenge of the	form  random@domain,  client  responds
       with  user  name	and then a hexadecimal response	(two separate writes),
       and then	the server responds with ok or bad.

       Chap and	mschap are challenge-response protocols	used in	PPP  sessions;
       valid  roles  are  client  and  server.	 The  client protocols require
       proto=chap or proto=mschap keys with  user  and	!password  attributes.
       Conventionally,	client	keys  also have	server attributes.  The	server
       protocol	requires a p9sk1 key as	described above.   The	protocol  with
       factotum	 is: server writes an 8-byte binary challenge, client responds
       with user name and then a Chapreply or MSchapreply  structure  (defined
       in <auth.h> ).

       Pass is a client-only protocol that hands out passwords from proto=pass
       keys with user and !password attributes.	 The protocol is a single read
       that  returns a string: a space-separated quoted	user name and password
       that can	be parsed with tokenize	(see  getfields(3)).   Conventionally,
       client keys have	distinguishing attributes like service and server that
       can be specified	in the start message to	select a key.

       Wep is a	client-only pseudo-protocol that  initializes  the  encryption
       key  on a wireless ethernet device.  It uses proto=wep keys with	!key1,
       !key2, or !key3 attributes.  The	protocol with factotum is: the	client
       writes  a  device name that must	begin with In response,	factotum opens
       the device's control file, sets the wireless secret using the key,  and
       turns  on encryption.  If the key has an	essid attribute, factotum uses
       it to set the wireless station ID.

       Rsa is an implementation	of the RSA protocol.  Valid roles are decrypt,
       encrypt,	 sign,	and verify.  Rsa uses proto=rsa	keys with ek and n at-
       tributes, large integers	specifying the public half of the key.	 If  a
       key is to be used for decryption	or signing, then it must also have at-
       tributes	!p, !q,	!kp, !kq, !c2, and !dk specifying the private half  of
       the  key;  see  rsa(3).	Conventionally,	rsa keys also have service at-
       tributes	specifying the context in which	the key	is used: ssh (SSH ver-
       sion  1), ssh-rsa (SSH version 2), or tls (SSL and TLS).	 If an SSH key
       has a comment attribute,	 that  comment	is  presented  to  remote  SSH
       servers	during	key negotiation.  The protocol for encryption (decryp-
       tion) is: write the message, then read back the	encrypted  (decrypted)
       form.  The protocol for signing is: write a hash	of the actual message,
       then read back the signature.  The protocol for verifying  a  signature
       is:  write  the	message	hash, write the	purported signature, then read
       back ok or bad telling whether the signature could  be  verified.   The
       hash  defaults  to SHA1 but can be specified by a hash attribute	on the
       key.  Valid hash	functions are md5 and sha1.  The hash function must be
       known  to factotum because the signature	encodes	the type of hash used.
       The encrypt and verify operations are included as a convenience;	facto-
       tum is not using	any private information	to perform them.

       Dsa  is	an  implementation  of	the  NIST digital signature algorithm.
       Valid roles are sign and	verify.	 It uses proto=dsa keys	with p,	q, al-
       pha, and	key attributes.	 If the	key is to be used for signing, it must
       also have a !secret attribute; see dsa(3).   Conventionally,  dsa  keys
       also have service attributes specifying the context in which the	key is
       used: ssh-dss (SSH version 2) is	the only one.  If an  SSH  key	has  a
       comment	attribute, that	comment	is presented to	SSH servers during key
       negotiation.  The protocol for signing and verifying is the same	as the
       RSA protocol.  Unlike rsa, the dsa protocol ignores the hash attribute;
       it always uses SHA1.

       Httpdigest is a client-only MD5-based challenge-response	protocol  used
       in HTTP;	see RFC	2617.  It uses proto=httpdigest	keys with user,	realm,
       and !password attributes.  The protocol with factotum is	textual: write
       the challenge, read the response.  The challenge	is a string with three
       space-separated fields nonce, method, and uri, parseable	with tokenize.
       The response is a hexadecimal string of length 32.

SOURCE
       /usr/local/plan9/src/cmd/auth/factotum

SEE ALSO
       ssh-agent(1)

								   FACTOTUM(4)

NAME | SYNOPSIS | DESCRIPTION | SOURCE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=factotum&sektion=4&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help