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    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 prompting for anything	it needs.  It will never  sub-
	      sequently	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 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 to specify which key and protocol to
       use  for	an authentication.  Like a key tuple, a	key template 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	speci-
       fied 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 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

   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

       The RPC protocol	is normally embodied by	one of the routines in We  de-
       scribe 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
		     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

       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	valid roles are	client
       and server.  The	client protocol	requires a proto=vnc key  with	attri-
       bute  !password.	 Conventionally, client	keys also have user and	server
       attributes.  The	server protocol	requires  a  p9sk1  key	 as  described
       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 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 Conventionally, rsa	 keys  also  have  service  attributes
       specifying  the	context	in which the key is used: ssh (SSH version 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 dur-
       ing key negotiation.  The  protocol  for	 encryption  (decryption)  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  en-
       crypt  and verify operations are	included as a convenience; factotum 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 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 negotia-
       tion.   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
       /src/cmd/auth/factotum

SEE ALSO
								   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.2-RELEASE+and+Ports>

home | help