kadmin

class kadmin.KAdm5Variant

kadm5 library variant

Represent a kadm5 library to use. This struct will determine which C library kadmin will link against. The list of currently supported options consist of the enum variants.

Depending on how kadmin was compiled, not all variants may be supported on your system. Refer to the package documentation on how to compile for all possible options.

MitClient

MIT krb5 client-side library

Type:

KAdm5Variant

MitServer

MIT krb5 server-side library

Type:

KAdm5Variant

HeimdalClient

Heimdal client-side library

Type:

KAdm5Variant

HeimdalServer

Heimdal server-side library

Type:

KAdm5Variant

class kadmin.KAdminApiVersion

kadm5 API version

MIT krb5 supports up to version 4. Heimdal supports up to version 2.

This changes which fields will be available in the Policy and Principal structs. If the version is too low, some fields may not be populated. We try our best to document those in the fields documentation themselves.

If no version is provided during the KAdmin initialization, it defaults to the most conservative one, currently version 2.

Version2

Version 2

Type:

KAdminApiVersion

Version3

Version 3

Type:

KAdminApiVersion

Version4

Version 4

Type:

KAdminApiVersion

class kadmin.KAdmin

Interface to kadm5

This class has no constructor. Instead, use the with_ methods

static with_password(variant, client_name, password, params=None, db_args=None, api_version=None, library_path=None)

Construct a KAdmin object using a password

Parameters:

  • variant (KAdm5Variant) – Which kadm5 variant to use

  • client_name (str) – client name, usually a principal name

  • password (str) – password to authenticate with

  • params (Params | None) – additional kadm5 config options

  • db_args (DbArgs | None) – additional database specific arguments

  • api_version (KAdminApiVersion | None) – kadm5 API version to use

  • library_path (str | None) – path to libkadm5.so to load

Returns:

an initialized KAdmin object

Return type:

KAdmin

kadm = KAdmin.with_password("user@EXAMPLE.ORG", "vErYsEcUrE")
static with_keytab(variant, client_name=None, keytab=None, params=None, db_args=None, library_path=None)

Construct a KAdmin object using a keytab

Parameters:

  • variant (KAdm5Variant) – Which kadm5 variant to use

  • client_name (str | None) – client name, usually a principal name. If not provided, host/hostname will be used

  • keytab (str | None) – path to the keytab to use. If not provided, the default keytab will be used

  • params (Params | None) – additional kadm5 config options

  • db_args (DbArgs | None) – additional database specific arguments

  • api_version (KAdminApiVersion | None) – kadm5 API version to use

  • library_path (str | None) – path to libkadm5.so to load

Returns:

an initialized KAdmin object

Return type:

KAdmin

static with_ccache(variant, client_name=None, ccache_name=None, params=None, db_args=None, library_path=None)

Construct a KAdmin object using a credentials cache

Parameters:

  • variant (KAdm5Variant) – Which kadm5 variant to use

  • client_name (str | None) – client name, usually a principal name. If not provided, the default principal from the credentials cache will be used

  • ccache_name (str | None) – credentials cache name. If not provided, the default credentials cache will be used

  • params (Params | None) – additional kadm5 config options

  • db_args (DbArgs | None) – additional database specific arguments

  • api_version (KAdminApiVersion | None) – kadm5 API version to use

  • library_path (str | None) – path to libkadm5.so to load

Returns:

an initialized KAdmin object

Return type:

KAdmin

static with_anonymous(variant, client_name, params=None, db_args=None, library_path=None)

Not implemented

static with_local(variant, params=None, db_args=None, api_version=None, library_path=None)

Construct a KAdmin object for local database manipulation.

Parameters:

  • variant (KAdm5Variant) – Which kadm5 variant to use

  • params (Params | None) – additional kadm5 config options

  • db_args (DbArgs | None) – additional database specific arguments

  • api_version (KAdminApiVersion | None) – kadm5 API version to use

  • library_path (str | None) – path to libkadm5.so to load

Returns:

an initialized KAdmin object

Return type:

KAdmin

add_principal(name, **kwargs)

Create a principal

Parameters:

  • name (str) – the name of the principal to create

  • kwargs – Extra args for the creation. The name of those arguments must match the attributes name of the Principal class that are not marked as read-only. Same goes for their types.

Returns:

the newly created Principal

Return type:

Principal

In addition, the following arguments are available

Parameters:

  • db_args (DbArgs) – database specific arguments

  • key (NewPrincipalKey) – how to set the principal key

  • keysalts (KeySalts) – Use the specified keysalt list for setting the keys of the principal

rename_principal(old_name, new_name)

Rename a principal

Parameters:

  • old_name (str) – the current name of the principal

  • new_name – the new name of the principal

delete_principal(name)

Delete a principal

Principal.delete() is also available

Parameters:

name (str) – name of the principal to delete

get_principal(name)

Retrieve a principal

Parameters:

name (str) – principal name to retrieve

Returns:

Principal if found, None otherwise

Return type:

Principal | None

principal_exists(name)

Check if a principal exists

Parameters:

name (str) – principal name to check for

Returns:

True if the principal exists, False otherwise

Return type:

bool

principal_change_password(name, password, keepold=None, keysalts=None)

Change the password of a principal

Principal.change_password() is also available

Parameters:

  • name (str) – name of the principal to change the password of

  • password (str) – the new password

  • keepold (bool | None) – Keeps the existing keys in the database. This flag is usually not necessary except perhaps for krbtgt principals. Defaults to false. With Heimdal client, this option is silently ignored

  • keysalts (KeySalts | None) – Uses the specified keysalt list for setting the keys of the principal. With Heimdal client, this option is silently ignored

principal_randkey(name, keepold=None, keysalts=None)

Sets the key of the principal to a random value

Principal.randkey() is also available

Parameters:

  • name (str) – name of the principal to randomize the key of

  • keepold (bool | None) – Keeps the existing keys in the database. This flag is usually not necessary except perhaps for krbtgt principals. Defaults to false. With Heimdal client, this option is silently ignored

  • keysalts (KeySalts | None) – Uses the specified keysalt list for setting the keys of the principal. With Heimdal client, this option is silently ignored

principal_get_strings(name)

Retrieve string attributes on this principal

Only available for MIT variants

Parameters:

name (str) – name of the principal to randomize the key of

Returns:

a dictionary containing the string attributes set on this principal

Return type:

dict[str, str]

principal_set_string(name, key, value)

Set string attribute on this principal

Only available for MIT variants

Parameters:

  • name (str) – name of the principal to randomize the key of

  • key (str) – The string key

  • value (str | None) – The string value. Set to None to remove the attribute

list_principals(query=None)

List principals

Parameters:

query (str, optional) – a shell-style glob expression that can contain the wild-card characters ?, *, and []. All principal names matching the expression are retuned. If the expression does not contain an @ character, an @ character followed by the local realm is appended to the expression. If no query is provided, all principals are returned.

Returns:

the list of principal names matching the query

Return type:

list[str]

add_policy(name, **kwargs)

Create a policy

Only available for MIT and Heimdal server-side libraries.

Parameters:

  • name (str) – the name of the policy to create

  • kwargs – Extra args for the creation. The name of those arguments must match the attributes name of the Policy class. Same goes for their types.

Returns:

the newly created Policy

Return type:

Policy

delete_policy(name)

Delete a policy

Only available for MIT and Heimdal server-side libraries.

Policy.delete() is also available

Parameters:

name (str) – name of the policy to delete

get_policy(name)

Retrieve a policy

Only available for MIT and Heimdal server-side libraries.

Parameters:

name (str) – policy name to retrieve

Returns:

Policy if found, None otherwise

Return type:

Policy | None

policy_exists(name)

Check if a policy exists

Only available for MIT and Heimdal server-side libraries.

Parameters:

name (str) – policy name to check for

Returns:

True if the policy exists, False otherwise

Return type:

bool

list_policies(query=None)

List policies

Only available for MIT and Heimdal server-side libraries.

Parameters:

query (str | None) – a shell-style glob expression that can contain the wild-card characters ?, *, and []. All policy names matching the expression are returned. If no query is provided, all existing policy names are returned.

Returns:

the list of policy names matching the query

Return type:

list[str]

get_privileges()

Get current privileges

Returns:

The current session privileges

Return type:

int

class kadmin.Principal
name

Principal name

Type:

str

expire_time

When the principal expires

Type:

datetime.datetime | None

last_password_change

When the password was last changed

Read-only

Type:

datetime.datetime | None

password_expiration

When the password expires

Type:

datetime.datetime | None

max_life

Maximum ticket life

Type:

datetime.timedelta | None

modified_by

Last principal to modify this principal

Read-only

Type:

str

modified_at

When the principal was last modified

Read-only

Type:

datetime.datetime | None

attributes

Principal attributes

Type:

int

kvno

Current key version number

Read-only, but can be set on principal creation

Type:

int

mkvno

Master key version number

Read-only

Type:

int

policy

Associated policy

Type:

str | None

aux_attributes

Extra attributes

Type:

int

max_renewable_life

Maximum renewable ticket life

Type:

datetime.timedelta | None

last_success

When the last successful authentication occurred

Read-only

Type:

datetime.datetime | None

last_failed

When the last failed authentication occurred

Read-only

Type:

datetime.datetime | None

fail_auth_count

Number of failed authentication attempts

Type:

int

tl_dats

TL-data

Type:

TlData

modify(kadmin, **kwargs)

Change this principal

Parameters:

  • kadmin (KAdmin) – A KAdmin instance

  • kwargs – Attributes to change. The name of those arguments must match the attributes name of the Principal class that are not marked as read-only. Same goes for their types

Returns:

a new Principal object with the modifications made to it. The old object is still available, but will not be up-to-date

Return type:

Principal

delete(kadmin)

Delete this principal

The object will still be available, but shouldn’t be used for modifying, as the policy may not exist anymore

Parameters:

kadmin (KAdmin) – A KAdmin instance

change_password(kadmin, password, keepold=None, keysalts=None)

Change the password of the principal

Note that principal data will have changed after this, so you may need to refresh it

Parameters:

  • kadmin (KAdmin) – A KAdmin instance

  • password (str) – the new password

  • keepold (bool | None) – Keeps the existing keys in the database. This flag is usually not necessary except perhaps for krbtgt principals. Defaults to false. With Heimdal client, this option is silently ignored

  • keysalts (KeySalts | None) – Uses the specified keysalt list for setting the keys of the principal. With Heimdal client, this option is silently ignored

randkey(kadmin, keepold=None, keysalts=None)

Sets the key of the principal to a random value

Note that principal data will have changed after this, so you may need to refresh it

Parameters:

  • kadmin (KAdmin) – A KAdmin instance

  • keepold (bool | None) – Keeps the existing keys in the database. This flag is usually not necessary except perhaps for krbtgt principals. Defaults to false. With Heimdal client, this option is silently ignored

  • keysalts (KeySalts | None) – Uses the specified keysalt list for setting the keys of the principal. With Heimdal client, this option is silently ignored

unlock(kadmin)

Unlocks a locked principal (one which has received too many failed authentication attempts without enough time between them according to its password policy) so that it can successfully authenticate

Note that principal data will have changed after this, so you may need to refresh it

Parameters:

kadmin (KAdmin) – A KAdmin instance

get_strings(kadmin)

Retrieve string attributes on this principal

Only available for MIT variants

Parameters:

kadmin (KAdmin) – A KAdmin instance

Returns:

a dictionary containing the string attributes set on this principal

Return type:

dict[str, str]

set_string(kadmin, key, value)

Set string attribute on this principal

Only available for MIT variants

Parameters:

  • kadmin (KAdmin) – A KAdmin instance

  • key (str) – The string key

  • value (str | None) – The string value. Set to None to remove the attribute

class kadmin.NewPrincipalKey

Method to use to set the principal key when creating it

Passing the class itself is not enough. An object should be created from those subclasses.

class Password(password)

Provide a password to use

class NoKey

No key should be set on the principal

class RandKey

A random key should be generated for the principal. Tries ServerRandKey and falls back to OldStyleRandKey

class ServerRandKey

A random key should be generated for the principal by the server

class OldStyleRandKey

Old-style random key. Creates the principal with KRB5_KDB_DISALLOW_ALL_TIX and a generated dummy key, then calls randkey on the principal and finally removes KRB5_KDB_DISALLOW_ALL_TIX

class kadmin.Policy

Only available for MIT and Heimdal server-side libraries.

name

The policy name

Type:

str

password_min_life

Minimum lifetime of a password

Type:

datetime.timedelta | None

password_max_life

Maximum lifetime of a password

Type:

datetime.timedelta | None

password_min_length

Minimum length of a password

Type:

int

password_min_classes

Minimum number of character classes required in a password. The five character classes are lower case, upper case, numbers, punctuation, and whitespace/unprintable characters

Type:

int

password_history_num

Number of past keys kept for a principal. May not be filled if used with other database modules such as the MIT krb5 LDAP KDC database module

Type:

int

policy_refcnt

How many principals use this policy. Not filled for at least MIT krb5

Type:

int

password_max_fail

Number of authentication failures before the principal is locked. Authentication failures are only tracked for principals which require preauthentication. The counter of failed attempts resets to 0 after a successful attempt to authenticate. A value of 0 disables lock‐out

Only available in version 3 and above

Type:

int

password_failcount_interval

Allowable time between authentication failures. If an authentication failure happens after this duration has elapsed since the previous failure, the number of authentication failures is reset to 1. A value of None means forever

Only available in MIT and version 3 and above

Type:

datetime.timedelta | None

password_lockout_duration

Duration for which the principal is locked from authenticating if too many authentication failures occur without the specified failure count interval elapsing. A duration of None means the principal remains locked out until it is administratively unlocked

Only available in MIT and version 3 and above

Type:

datetime.timedelta | None

attributes

Policy attributes

Only available in MIT and version 4 and above

Type:

int

max_life

Maximum ticket life

Only available in MIT and version 4 and above

Type:

datetime.timedelta | None

max_renewable_life

Maximum renewable ticket life

Only available in MIT and version 4 and above

Type:

datetime.timedelta | None

allowed_keysalts

Allowed keysalts

Only available in MIT and version 4 and above

Type:

KeySalts | None

tl_data

TL-data

Only available in MIT and version 4 and above

Type:

TlData

modify(kadmin, **kwargs)

Change this policy

Parameters:

  • kadmin (KAdmin) – A KAdmin instance

  • kwargs – Attributes to change. The name of those arguments must match the attributes name of the Policy class. Same goes for their types. The name attribute is ignored.

Returns:

a new Policy object with the modifications made to it. The old object is still available, but will not be up-to-date

Return type:

Policy

delete(kadmin)

Delete this policy

The object will still be available, but shouldn’t be used for modifying, as the policy may not exist anymore

Parameters:

kadmin (KAdmin) – A KAdmin instance

class kadmin.Params(realm=None, kadmind_port=None, kpasswd_port=None, admin_server=None, dbname=None, acl_file=None, dict_file=None, stash_file=None)

kadm5 config options

Parameters:

  • realm (str | None) – Default realm database

  • kadmind_port (int | None) – kadmind port to connect to

  • kpasswd_port (int | None) – kpasswd port to connect to. Only available on MIT variants.

  • admin_server (str | None) – Admin server which kadmin should contact

  • dbname (str | None) – Name of the KDC database

  • acl_file (str | None) – Location of the access control list file

  • dict_file (str | None) – Location of the dictionary file containing strings that are not allowed as passwords. Only available on MIT variants.

  • stash_file (str | None) – Location where the master key has been stored

params = Params(realm="EXAMPLE.ORG")
class kadmin.DbArgs(/, *args, **kwargs)

Database specific arguments

See man kadmin(1) for a list of supported arguments

Parameters:

  • *args (str) – Database arguments (without value)

  • **kwargs (str | None) – Database arguments (with or without value)

db_args = DbArgs(host="ldap.example.org")
class kadmin.EncryptionType(enctype)

Kerberos encryption type

Parameters:

enctype (int) – Encryption type.

class kadmin.SaltType(salttype)

Kerberos salt type

Parameters:

salttype (int | None) – Salt type.

class kadmin.KeySalt(enctype, salttype)

Kerberos keysalt

Parameters:
enctype

Encryption type

Type:

EncryptionType

salttype

Salt type

Type:

SaltType

class kadmin.KeySalts(keysalts)

Kerberos keysalt list

Parameters:

keysalts (set[KeySalt]) – Keysalt list

keysalts

Keysalt list

Type:

set[KeySalt]

class kadmin.TlDataEntry(data_type, contents)

A single TL-data entry

Parameters:

  • data_type (int) – Entry type

  • contents (list[int]) – Entry contents

data_type
Type:

int

contents
Type:

list[int]

class kadmin.TlData(entries)

TL-data entries

Parameters:

entries (list[TlDataEntry]) – TL-data entries

entries
Type:

list[TlDataEntry]