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

FreeBSD Manual Pages

  
 
  

home | help
Kadm5(3)	      User Contributed Perl Documentation	      Kadm5(3)

NAME
       Heimdal::Kadm5 -	Perl extension for adminstration of Heimdal Kerberos
       servers (kadmin)

SYNOPSIS
       use Heimdal::Kadm5;

       $client = Heimdal::Kadm5::Client->new('Client'=>'you/admin@YOUR.REALM',
				'Password'=>'eatmyshorts'); foreach my $name
       ($client->getPrincipals('*/admin'))
	 {
	    my $principal = $client->getPrincipal($name);
	    $principal->dump;
	 }

DESCRIPTION
       Heimdal::Kadm5 is a basic XSUB perl glue	to the Heimdal
       (http://www.pdc.kth.se/src/heimdal) kadm5clnt library. Heimdal is a
       free, slightly less export challenged implementation of Kerberos5 by
       Assar Westerlund	and Johan Danielsson. Heimdal::Kadm5 allows you	to
       perform more administration of your kdc than you	can usually pull off
       with the	included kadmin	program. Heimdal::Kadm5	should be considered
       alpha-code and may consequently crash and burn but should not muck up
       your kdc	any more than kadmin itself does.

OBJECTS
       "Heimdal::Kadm5::Client"	represents a client connection (the truly
       perverse	may conspire to	write a	kadmin servlet in perl and put that in
       "Heimdal::Kadm5::Server") to a kadmin server. The main object handled
       by a kadmin server is a "kadm5_principal_ent_t" (kadm5/admin.h).	This
       type corresponds	to the perl class "Heimdal::Kadm5::Principal". This
       object is returned by the "getPrincipal"	method of
       "Heimdal::Kadm5::Client"	and can	be created (when adding	principals to
       the kdc)	using the "makePrincipal" method of "Heimdal::Kadm5::Client".
       Note: Do	not create Principals directly through
       "Heimdal::Kadm5::Principal".  Principals	in the traditional sense of
       the word	(i.e things of type "krb5_principal") are passed around	as
       strings ('name/instance@REALM' or 'name@REALM');

METHODS
       In what follows $principal denotes an instance of
       Heimdal::Kadm5::Principal, $name	denotes	a principal name, $bitmask
       denotes an (you guessed it!) integer representing a bitmask, $seconds
       an integer representing seconds since the epoch (time_t value), $client
       a Heimdal::Kadm5::Client	instance. Other	variables should be even more
       obvious or are explained	in the text.

   Heimdal::Kadm5::Client
       Minimal use:

       my $client =
	  Heimdal::Kadm5::Client->new(Client=>'you');

       This would connect using	a password for 'you@DEFREALM'. The password is
       prompted	on the active tty.

       A more complex example:

       my $client =
	  Heimdal::Kadm5::Client->new(
			   RaiseErrors => 1,
			   Server => 'adm.somewhere.net',
			   Port	  => '8899',
			   # Required:
			   Client => 'you/admin',
			   Realm  => 'OTHER.REALM',
			   # --- Either	---
			   Password => 'very secret',
			   # --- Or ---
			   Keytab => '$HOME/mysecret.keytab'
			  );

       Be very careful when using the Password parameter: it implies storing
       the password in the script or reading it	from commmand line arguments
       or through some other means. Only use this on secured hosts, never from
       NFS mounted filesystems,	and never using	principals allowed to perform
       all operations on the kdc. In this case using a keytable	(see ktutil(8)
       for information on how to create	keytabs) is a better way to go.

       Normally	both the Server, Port and Realm	parameters are determined from
       the kerberos context (configuration files, DNS etc etc) but you may
       need to override	them. If you leave out the password or set it to undef
       the client library will prompt you for a	password. You must include the
       Client parameter	which is usually your admin or root -instance
       depending on your local system of belief. If for	some reason the	client
       connection cannot be initialized	undef is returned and errors are sent
       to warn unless the RaiseError parameter is set in which case all	errors
       are propagated by die.

       my @names = $client->getPrincipals($pattern);

       The getPrincipals method	returns	a list of principals matching $pattern
       which is	not a regular expression but rather a glob-like	animal.	For
       instance	'*/admin@REALM'	is an ok pattern. The elements of the list are
       principal names which can be used to obtain Heimdal::Kadm5::Principal
       object using

       my $principal = $client->getPrincipal($name);

       which returns a Heimdal::Kadm5::Principal object	(see the next section
       for details).

       my $principal = $client->makePrincipal($name);

       The makePrincipal method	takes a	principal name and creates an empty
       Heimdal::Kadm5::Principal object. This is intended for adding
       principals to the kdc. After creating the principal using makePrincipal
       use the accessor	methods	in Heimdal::Kadm5::Principal to	set values
       before adding the principal using

       $client->createPrincipal($principal,$password,$mask);

       If $mask	is set this value is used to determine which elements of the
       principal to include in the creation. Normally this value is
       automatically determined	by tracking the	uses of	the accessor methods
       in the Heimdal::Kadm5::Principal	class.

       Modifications to	an existing principal is done using this method:

       $client->createPrincipal($principal,$mask);

       The $mask value works in	the same way as	described above	for
       createPrincipal.	It is sometimes	useful to disable (lock) a principal,
       for instance when several operations must be performed.	The following
       methods can be used:

       $client->disablePrincipal($name);

       $client->enablePrincipal($name);

       Other methods which modify the kdc are and the use of which should be
       obvious:

       $client->changePassword($name, $password);

       $client->deletePrincipal($name);

       $client->renamePrincipal($name, $newname);

       $client->randKeyPrincipal($name);

       This method creates a random set	of keys	for the	principal named	$name.
       This is typically done for service principals. When creating a new
       service principal it is probably	a good idea to create the principal
       with some initial password, disable the principal, apply	the
       randKeyPrincipal	method and then	enable the principal.

       $client->handle->c_flush();

       This method flushes all modifications to	the datastore. It is called
       automatically when the client handle is DESTROYed if any	modifications
       (password change, create, rename	or delete has been performed);

       $client->extractKeytab($principal,$keytab);

       This method extracts the	keys belonging to the principal	object to the
       keytab (optionally) specified by	the second argument. If	the second
       argument	is missing it defaults to the standard default keytab,
       typically /etc/krb5.keytab.

   Heimdal::Kadm5::Principal
       $principal->dump($io);

       Dumps a representation of $principal on the $io handle (which defaults
       to \*STDOUT).  This is mostly usable for	debugging or simple scripts.

       my $name	= $principal->getPrincipal(); $principal->setPrincipal($name);

       Gets and	sets the principal name.

       my $seconds = $principal->getPrincExpireTime();
       $principal->setPrincExpireTime($seconds);

       Gets and	sets the time this principal expires.

       my $seconds = $principal->getLastPwdChange();

       Returns the last	time this principal's password was changed.

       my $kvno	= $principal->getKvno();

       Returns the key version number of this principal's password.

       my $mkvno = $principal->getMKvno();

       Returns this principal's	MKvno.

       my $seconds = $principal->getPwExpiration();
       $principal->setPwExpiration($seconds);

       Gets and	sets the password expriation time.

       my $seconds = $principal->getMaxLife();
       $principal->setMaxLife($seconds);

       Gets and	sets the maximum lifetime of a ticket.

       my $seconds = $principal->getMaxRenewableLife();
       $principal->setMaxRenewableLife($seconds);

       Gets and	sets the maximum renewable ticket lifetime.

       my $name	= $principal->getModName();

       Returns the principal name of the last modifier of the entry. Not
       currently (as of	heimdal	0.1g) supported	by heimdal and contains	undef.

       my $seconds = $principal->getModDate();

       Returns the date	of last	modification of	the entry.

       my $policyname =	$principal->getPolicy();

       getPolicy returns undef if no policy is set. Policies are not currently
       supported (as of	heimdal	0.1g) and always returns undef.

       my $seconds = $principal->getLastSuccess();

       Last time a successful authentication was done against this principal.

       my $seconds= $principal->getLastFailed();

       Last time a failed authentication was done against this principal.

       my $nfailed = $principal->getFailAuthCounts();

       How many	failed login attempts was done against this principal.

       my $bitmask = $principal->getAttributes();

       The bitmask of attributes for this principal.

       my @names = $principal->getAttributeNames();

       The list	of attribute names for this principal, expanded	from the
       bitmask.

       my $arrayref = $principal->getKeyTypes();

       getKeyTypes returns an array reference consisting of a list of array
       references with two elements each: [keytype,salt]. The keytype and salt
       are strings which describe a key	associated with	the principal.	Note
       that this data may not be present depending on how the principal	was
       obtained.

       my $password = $principal->getPassword();

       getPassword returns the password	if its saved in	the Kerberos database.
       Not the that principal object need to fetched with the bit
       KADM5_TL_DATA set in the	mask.

Exported constants
	 KADM5_ADMIN_SERVICE
	 KADM5_API_VERSION_1
	 KADM5_API_VERSION_2
	 KADM5_ATTRIBUTES
	 KADM5_AUX_ATTRIBUTES
	 KADM5_CHANGEPW_SERVICE
	 KADM5_CONFIG_ACL_FILE
	 KADM5_CONFIG_ADBNAME
	 KADM5_CONFIG_ADB_LOCKFILE
	 KADM5_CONFIG_ADMIN_KEYTAB
	 KADM5_CONFIG_ADMIN_SERVER
	 KADM5_CONFIG_DBNAME
	 KADM5_CONFIG_DICT_FILE
	 KADM5_CONFIG_ENCTYPE
	 KADM5_CONFIG_ENCTYPES
	 KADM5_CONFIG_EXPIRATION
	 KADM5_CONFIG_FLAGS
	 KADM5_CONFIG_KADMIND_PORT
	 KADM5_CONFIG_MAX_LIFE
	 KADM5_CONFIG_MAX_RLIFE
	 KADM5_CONFIG_MKEY_FROM_KEYBOARD
	 KADM5_CONFIG_MKEY_NAME
	 KADM5_CONFIG_PROFILE
	 KADM5_CONFIG_REALM
	 KADM5_CONFIG_STASH_FILE
	 KADM5_FAIL_AUTH_COUNT
	 KADM5_HIST_PRINCIPAL
	 KADM5_KEY_DATA
	 KADM5_KVNO
	 KADM5_LAST_FAILED
	 KADM5_LAST_PWD_CHANGE
	 KADM5_LAST_SUCCESS
	 KADM5_MAX_LIFE
	 KADM5_MAX_RLIFE
	 KADM5_MKVNO
	 KADM5_MOD_NAME
	 KADM5_MOD_TIME
	 KADM5_POLICY
	 KADM5_POLICY_CLR
	 KADM5_POLICY_NORMAL_MASK
	 KADM5_PRINCIPAL
	 KADM5_PRINCIPAL_NORMAL_MASK
	 KADM5_PRINC_EXPIRE_TIME
	 KADM5_PRIV_ADD
	 KADM5_PRIV_ALL
	 KADM5_PRIV_CPW
	 KADM5_PRIV_DELETE
	 KADM5_PRIV_GET
	 KADM5_PRIV_LIST
	 KADM5_PRIV_MODIFY
	 KADM5_PW_EXPIRATION
	 KADM5_PW_HISTORY_NUM
	 KADM5_PW_MAX_LIFE
	 KADM5_PW_MIN_CLASSES
	 KADM5_PW_MIN_LENGTH
	 KADM5_PW_MIN_LIFE
	 KADM5_REF_COUNT
	 KADM5_STRUCT_VERSION
	 KADM5_TL_DATA
	 KRB5_KDB_DISALLOW_ALL_TIX
	 KRB5_KDB_DISALLOW_DUP_SKEY
	 KRB5_KDB_DISALLOW_FORWARDABLE
	 KRB5_KDB_DISALLOW_POSTDATED
	 KRB5_KDB_DISALLOW_PROXIABLE
	 KRB5_KDB_DISALLOW_RENEWABLE
	 KRB5_KDB_DISALLOW_SVR
	 KRB5_KDB_DISALLOW_TGT_BASED
	 KRB5_KDB_NEW_PRINC
	 KRB5_KDB_PWCHANGE_SERVICE
	 KRB5_KDB_REQUIRES_HW_AUTH
	 KRB5_KDB_REQUIRES_PRE_AUTH
	 KRB5_KDB_REQUIRES_PWCHANGE
	 KRB5_KDB_SUPPORT_DESMD5
	 USE_KADM5_API_VERSION

AUTHOR
       Leif Johansson, leifj@it.su.se

SEE ALSO
       perl(1).

perl v5.32.0			  2010-02-11			      Kadm5(3)

NAME | SYNOPSIS | DESCRIPTION | OBJECTS | METHODS | Exported constants | AUTHOR | SEE ALSO

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

home | help