kadmin
======
.. py:module:: kadmin
.. py:class:: 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.
.. py:attribute:: MitClient
MIT krb5 client-side library
:type: KAdm5Variant
.. py:attribute:: MitServer
MIT krb5 server-side library
:type: KAdm5Variant
.. py:attribute:: HeimdalClient
Heimdal client-side library
:type: KAdm5Variant
.. py:attribute:: HeimdalServer
Heimdal server-side library
:type: KAdm5Variant
.. py:class:: 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.
.. py:attribute:: Version2
Version 2
:type: KAdminApiVersion
.. py:attribute:: Version3
Version 3
:type: KAdminApiVersion
.. py:attribute:: Version4
Version 4
:type: KAdminApiVersion
.. py:class:: KAdmin
Interface to kadm5
This class has no constructor. Instead, use the `with_` methods
.. py:staticmethod:: with_password(variant, client_name, password, params=None, db_args=None, api_version=None, library_path=None)
Construct a KAdmin object using a password
:param variant: Which kadm5 variant to use
:type variant: KAdm5Variant
:param client_name: client name, usually a principal name
:type client_name: str
:param password: password to authenticate with
:type password: str
:param params: additional kadm5 config options
:type params: Params | None
:param db_args: additional database specific arguments
:type db_args: DbArgs | None
:param api_version: kadm5 API version to use
:type api_version: KAdminApiVersion | None
:param library_path: path to libkadm5.so to load
:type library_path: str | None
:return: an initialized :py:class:`KAdmin` object
:rtype: KAdmin
.. code-block:: python
kadm = KAdmin.with_password("user@EXAMPLE.ORG", "vErYsEcUrE")
.. py:staticmethod:: with_keytab(variant, client_name=None, keytab=None, params=None, db_args=None, library_path=None)
Construct a KAdmin object using a keytab
:param variant: Which kadm5 variant to use
:type variant: KAdm5Variant
:param client_name: client name, usually a principal name. If not provided,
`host/hostname` will be used
:type client_name: str | None
:param keytab: path to the keytab to use. If not provided, the default keytab will be
used
:type keytab: str | None
:param params: additional kadm5 config options
:type params: Params | None
:param db_args: additional database specific arguments
:type db_args: DbArgs | None
:param api_version: kadm5 API version to use
:type api_version: KAdminApiVersion | None
:param library_path: path to libkadm5.so to load
:type library_path: str | None
:return: an initialized :py:class:`KAdmin` object
:rtype: KAdmin
.. py:staticmethod:: 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
:param variant: Which kadm5 variant to use
:type variant: KAdm5Variant
:param client_name: client name, usually a principal name. If not provided, the default
principal from the credentials cache will be used
:type client_name: str | None
:param ccache_name: credentials cache name. If not provided, the default credentials
cache will be used
:type ccache_name: str | None
:param params: additional kadm5 config options
:type params: Params | None
:param db_args: additional database specific arguments
:type db_args: DbArgs | None
:param api_version: kadm5 API version to use
:type api_version: KAdminApiVersion | None
:param library_path: path to libkadm5.so to load
:type library_path: str | None
:return: an initialized :py:class:`KAdmin` object
:rtype: KAdmin
.. py:staticmethod:: with_anonymous(variant, client_name, params=None, db_args=None, library_path=None)
Not implemented
.. py:staticmethod:: with_local(variant, params=None, db_args=None, api_version=None, library_path=None)
Construct a :py:class:`KAdmin` object for local database manipulation.
:param variant: Which kadm5 variant to use
:type variant: KAdm5Variant
:param params: additional kadm5 config options
:type params: :py:class:`Params<kadmin.Params>` | None
:param db_args: additional database specific arguments
:type db_args: :py:class:`DbArgs<kadmin.DbArgs>` | None
:param api_version: kadm5 API version to use
:type api_version: :py:class:`KAdminApiVersion<kadmin.KAdminApiVersion>` | None
:param library_path: path to libkadm5.so to load
:type library_path: str | None
:return: an initialized :py:class:`KAdmin` object
:rtype: KAdmin
.. py:method:: add_principal(name, **kwargs)
Create a principal
:param name: the name of the principal to create
:type name: str
:param kwargs: Extra args for the creation. The name of those arguments must match the
attributes name of the :py:class:`Principal` class that are not marked as read-only.
Same goes for their types.
:return: the newly created :py:class:`Principal`
:rtype: Principal
In addition, the following arguments are available
:param db_args: database specific arguments
:type db_args: DbArgs
:param key: how to set the principal key
:type key: NewPrincipalKey
:param keysalts: Use the specified keysalt list for setting the keys of the principal
:type keysalts: KeySalts
.. py:method:: rename_principal(old_name, new_name)
Rename a principal
:param old_name: the current name of the principal
:type old_name: str
:param new_name: the new name of the principal
:type old_name: str
.. py:method:: delete_principal(name)
Delete a principal
:py:meth:`Principal.delete` is also available
:param name: name of the principal to delete
:type name: str
.. py:method:: get_principal(name)
Retrieve a principal
:param name: principal name to retrieve
:type name: str
:return: :py:class:`Principal` if found, None otherwise
:rtype: Principal | None
.. py:method:: principal_exists(name)
Check if a principal exists
:param name: principal name to check for
:type name: str
:return: `True` if the principal exists, `False` otherwise
:rtype: bool
.. py:method:: principal_change_password(name, password, keepold=None, keysalts=None)
Change the password of a principal
:py:meth:`Principal.change_password` is also available
:param name: name of the principal to change the password of
:type name: str
:param password: the new password
:type password: str
:param keepold: 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
:type keepold: bool | None
:param keysalts: Uses the specified keysalt list for setting the keys of the principal. With Heimdal
client, this option is silently ignored
:type keysalts: KeySalts | None
.. py:method:: principal_randkey(name, keepold=None, keysalts=None)
Sets the key of the principal to a random value
:py:meth:`Principal.randkey` is also available
:param name: name of the principal to randomize the key of
:type name: str
:param keepold: 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
:type keepold: bool | None
:param keysalts: Uses the specified keysalt list for setting the keys of the principal. With Heimdal
client, this option is silently ignored
:type keysalts: KeySalts | None
.. py:method:: principal_get_strings(name)
Retrieve string attributes on this principal
Only available for MIT variants
:param name: name of the principal to randomize the key of
:type name: str
:return: a dictionary containing the string attributes set on this principal
:rtype: dict[str, str]
.. py:method:: principal_set_string(name, key, value)
Set string attribute on this principal
Only available for MIT variants
:param name: name of the principal to randomize the key of
:type name: str
:param key: The string key
:type key: str
:param value: The string value. Set to None to remove the attribute
:type value: str | None
.. py:method:: list_principals(query=None)
List principals
:param query: 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.
:type query: str, optional
:return: the list of principal names matching the query
:rtype: list[str]
.. py:method:: add_policy(name, **kwargs)
Create a policy
Only available for MIT and Heimdal server-side libraries.
:param name: the name of the policy to create
:type name: str
:param kwargs: Extra args for the creation. The name of those arguments must match the
attributes name of the :py:class:`Policy` class. Same goes for their types.
:return: the newly created :py:class:`Policy`
:rtype: Policy
.. py:method:: delete_policy(name)
Delete a policy
Only available for MIT and Heimdal server-side libraries.
:py:meth:`Policy.delete` is also available
:param name: name of the policy to delete
:type name: str
.. py:method:: get_policy(name)
Retrieve a policy
Only available for MIT and Heimdal server-side libraries.
:param name: policy name to retrieve
:type name: str
:return: :py:class:`Policy` if found, None otherwise
:rtype: Policy | None
.. py:method:: policy_exists(name)
Check if a policy exists
Only available for MIT and Heimdal server-side libraries.
:param name: policy name to check for
:type name: str
:return: `True` if the policy exists, `False` otherwise
:rtype: bool
.. py:method:: list_policies(query=None)
List policies
Only available for MIT and Heimdal server-side libraries.
:param query: 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.
:type query: str | None
:return: the list of policy names matching the query
:rtype: list[str]
.. py:method:: get_privileges()
Get current privileges
:return: The current session privileges
:rtype: int
.. py:class:: Principal
.. py:attribute:: name
Principal name
:type: str
.. py:attribute:: expire_time
When the principal expires
:type: datetime.datetime | None
.. py:attribute:: last_password_change
When the password was last changed
Read-only
:type: datetime.datetime | None
.. py:attribute:: password_expiration
When the password expires
:type: datetime.datetime | None
.. py:attribute:: max_life
Maximum ticket life
:type: datetime.timedelta | None
.. py:attribute:: modified_by
Last principal to modify this principal
Read-only
:type: str
.. py:attribute:: modified_at
When the principal was last modified
Read-only
:type: datetime.datetime | None
.. py:attribute:: attributes
Principal attributes
:type: int
.. py:attribute:: kvno
Current key version number
Read-only, but can be set on principal creation
:type: int
.. py:attribute:: mkvno
Master key version number
Read-only
:type: int
.. py:attribute:: policy
Associated policy
:type: str | None
.. py:attribute:: aux_attributes
Extra attributes
:type: int
.. py:attribute:: max_renewable_life
Maximum renewable ticket life
:type: datetime.timedelta | None
.. py:attribute:: last_success
When the last successful authentication occurred
Read-only
:type: datetime.datetime | None
.. py:attribute:: last_failed
When the last failed authentication occurred
Read-only
:type: datetime.datetime | None
.. py:attribute:: fail_auth_count
Number of failed authentication attempts
:type: int
.. py:attribute:: tl_dats
TL-data
:type: TlData
.. py:method:: modify(kadmin, **kwargs)
Change this principal
:param kadmin: A :py:class:`KAdmin` instance
:type kadmin: KAdmin
:param kwargs: Attributes to change. The name of those arguments must match the
attributes name of the :py:class:`Principal` class that are not marked as read-only.
Same goes for their types
:return: a new :py:class:`Principal` object with the modifications made to it. The old
object is still available, but will not be up-to-date
:rtype: Principal
.. py:method:: 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
:param kadmin: A :py:class:`KAdmin` instance
:type kadmin: KAdmin
.. py:method:: 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
:param kadmin: A :py:class:`KAdmin` instance
:type kadmin: KAdmin
:param password: the new password
:type password: str
:param keepold: 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
:type keepold: bool | None
:param keysalts: Uses the specified keysalt list for setting the keys of the principal. With Heimdal
client, this option is silently ignored
:type keysalts: KeySalts | None
.. py:method:: 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
:param kadmin: A :py:class:`KAdmin` instance
:type kadmin: KAdmin
:param keepold: 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
:type keepold: bool | None
:param keysalts: Uses the specified keysalt list for setting the keys of the principal. With Heimdal
client, this option is silently ignored
:type keysalts: KeySalts | None
.. py:method:: 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
:param kadmin: A :py:class:`KAdmin` instance
:type kadmin: KAdmin
.. py:method:: get_strings(kadmin)
Retrieve string attributes on this principal
Only available for MIT variants
:param kadmin: A :py:class:`KAdmin` instance
:type kadmin: KAdmin
:return: a dictionary containing the string attributes set on this principal
:rtype: dict[str, str]
.. py:method:: set_string(kadmin, key, value)
Set string attribute on this principal
Only available for MIT variants
:param kadmin: A :py:class:`KAdmin` instance
:type kadmin: KAdmin
:param key: The string key
:type key: str
:param value: The string value. Set to None to remove the attribute
:type value: str | None
.. py:class:: 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.
.. py:class:: Password(password)
Provide a password to use
:type password: str
.. py:class:: NoKey()
No key should be set on the principal
.. py:class:: RandKey()
A random key should be generated for the principal. Tries `ServerRandKey` and falls back to `OldStyleRandKey`
.. py:class:: ServerRandKey()
A random key should be generated for the principal by the server
.. py: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
.. py:class:: Policy
Only available for MIT and Heimdal server-side libraries.
.. py:attribute:: name
The policy name
:type: str
.. py:attribute:: password_min_life
Minimum lifetime of a password
:type: datetime.timedelta | None
.. py:attribute:: password_max_life
Maximum lifetime of a password
:type: datetime.timedelta | None
.. py:attribute:: password_min_length
Minimum length of a password
:type: int
.. py:attribute:: 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
.. py:attribute:: 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
.. py:attribute:: policy_refcnt
How many principals use this policy. Not filled for at least MIT krb5
:type: int
.. py:attribute:: 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 :py:class:`version<KAdminApiVersion>` 3 and above
:type: int
.. py:attribute:: 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 :py:class:`version<KAdminApiVersion>` 3 and above
:type: datetime.timedelta | None
.. py:attribute:: 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 :py:class:`version<KAdminApiVersion>` 3 and above
:type: datetime.timedelta | None
.. py:attribute:: attributes
Policy attributes
Only available in MIT and :py:class:`version<KAdminApiVersion>` 4 and above
:type: int
.. py:attribute:: max_life
Maximum ticket life
Only available in MIT and :py:class:`version<KAdminApiVersion>` 4 and above
:type: datetime.timedelta | None
.. py:attribute:: max_renewable_life
Maximum renewable ticket life
Only available in MIT and :py:class:`version<KAdminApiVersion>` 4 and above
:type: datetime.timedelta | None
.. py:attribute:: allowed_keysalts
Allowed keysalts
Only available in MIT and :py:class:`version<KAdminApiVersion>` 4 and above
:type: KeySalts | None
.. py:attribute:: tl_data
TL-data
Only available in MIT and :py:class:`version<KAdminApiVersion>` 4 and above
:type: TlData
.. py:method:: modify(kadmin, **kwargs)
Change this policy
:param kadmin: A :py:class:`KAdmin` instance
:type kadmin: KAdmin
:param kwargs: Attributes to change. The name of those arguments must match the
attributes name of the :py:class:`Policy` class. Same goes for their types. The
`name` attribute is ignored.
:return: a new :py:class:`Policy` object with the modifications made to it. The old
object is still available, but will not be up-to-date
:rtype: Policy
.. py:method:: 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
:param kadmin: A :py:class:`KAdmin` instance
:type kadmin: KAdmin
.. py:class:: 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
:param realm: Default realm database
:type realm: str | None
:param kadmind_port: kadmind port to connect to
:type kadmind_port: int | None
:param kpasswd_port: kpasswd port to connect to. Only available on MIT variants.
:type kpasswd_port: int | None
:param admin_server: Admin server which kadmin should contact
:type admin_server: str | None
:param dbname: Name of the KDC database
:type dbname: str | None
:param acl_file: Location of the access control list file
:type acl_file: str | None
:param dict_file: Location of the dictionary file containing strings that are not allowed
as passwords. Only available on MIT variants.
:type dict_file: str | None
:param stash_file: Location where the master key has been stored
:type stash_file: str | None
.. code-block:: python
params = Params(realm="EXAMPLE.ORG")
.. py:class:: DbArgs(/, *args, **kwargs)
Database specific arguments
See `man kadmin(1)` for a list of supported arguments
:param \*args: Database arguments (without value)
:type \*args: str
:param \**kwargs: Database arguments (with or without value)
:type \**kwargs: str | None
.. code-block:: python
db_args = DbArgs(host="ldap.example.org")
.. py:class:: EncryptionType(enctype)
Kerberos encryption type
:param enctype: Encryption type.
:type enctype: int
.. py:class:: SaltType(salttype)
Kerberos salt type
:param salttype: Salt type.
:type salttype: int | None
.. py:class:: KeySalt(enctype, salttype)
Kerberos keysalt
:param enctype: Encryption type
:type enctype: EncryptionType
:param salttype: Salt type
:type salttype: SaltType
.. py:attribute:: enctype
Encryption type
:type: EncryptionType
.. py:attribute:: salttype
Salt type
:type: SaltType
.. py:class:: KeySalts(keysalts)
Kerberos keysalt list
:param keysalts: Keysalt list
:type keysalts: set[KeySalt]
.. py:attribute:: keysalts
Keysalt list
:type: set[KeySalt]
.. py:class:: TlDataEntry(data_type, contents)
A single TL-data entry
:param data_type: Entry type
:type data_type: int
:param contents: Entry contents
:type contents: list[int]
.. py:attribute:: data_type
:type: int
.. py:attribute:: contents
:type: list[int]
.. py:class:: TlData(entries)
TL-data entries
:param entries: TL-data entries
:type entries: list[TlDataEntry]
.. py:attribute:: entries
:type: list[TlDataEntry]