path: root/gnome-initial-setup/pages/account/org.freedesktop.realmd.xml

<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node name="/">

	<!--
	  org.freedesktop.realmd.Provider:
	  @short_description: a realm provider

	  Various realm providers represent different software implementations
	  that provide access to realms or domains.

	  This interface is implemented by individual providers, but is
	  aggregated globally at the system bus name
	  <literal>org.freedesktop.realmd</literal>
	  with the object path <literal>/org/freedesktop/realmd</literal>
	-->
	<interface name="org.freedesktop.realmd.Provider">

		<!--
		  Name: the name of the provider

		  The name of the provider. This is not normally displayed
		  to the user, but may be useful for diagnostics or debugging.
		-->
		<property name="Name" type="s" access="read"/>

		<!--
		  Version: the version of the provider

		  The version of the provider. This is not normally used in
		  logic, but may be useful for diagnostics or debugging.
		-->
		<property name="Version" type="s" access="read"/>

		<!--
		  Realms: a list of realms

		  A list of known, enrolled or discovered realms. All realms
		  that this provider knows about are listed here. As realms
		  are discovered they are added to this list.

		  Each realm is represented by the DBus object path of the
		  realm object.
		-->
		<property name="Realms" type="ao" access="read"/>

		<!--
		  Discover:
		  @string: an input string to discover realms for
		  @options: options for the discovery operation
		  @relevance: the relevance of the returned results
		  @realm: a list of realms discovered

		  Discover realms for the given string. The input @string is
		  usually a domain or realm name, perhaps typed by a user. If
		  an empty string is provided the realm provider should try to
		  discover a default realm if possible (eg: from DHCP).

		  @options can contain, but is not limited to, the following values:
		  <itemizedlist>
		    <listitem><para><literal>operation</literal>: a string
		      identifier chosen by the client, which can then later be
		      passed to org.freedesktop.realmd.Service.Cancel() in order
		      to cancel the operation</para></listitem>
		  </itemizedlist>

		  The @relevance returned can be used to rank results from
		  different discover calls to different providers. Implementors
		  should return a positive number if the provider highly
		  recommends that the realms be handled by this provider,
		  or a zero if it can possibly handle the realms. Negative
		  should be returned if no realms are found.

		  This method does not return an error when no realms are
		  discovered. It simply returns an @realm list.

		  To see diagnostic information about the discovery process
		  connect to the org.freedesktop.realmd.Service::Diagnostics
		  signal.

		  This method requires authorization for the PolicyKit action
		  called <literal>org.freedesktop.realmd.discover-realm</literal>.

		  In addition to common DBus error results, this method may
		  return:
		  <itemizedlist>
		    <listitem><para><literal>org.freedesktop.realmd.Error.Failed</literal>:
		      may be returned if the discovery could not be run for some reason.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.Cancelled</literal>:
		      returned if the operation was cancelled.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.NotAuthorized</literal>:
		      returned if the calling client is not permitted to perform a discovery
		      operation.</para></listitem>
		  </itemizedlist>
		-->
		<method name="Discover">
			<arg name="string" type="s" direction="in"/>
			<arg name="options" type="a{sv}" direction="in"/>
			<arg name="relevance" type="i" direction="out"/>
			<arg name="realm" type="ao" direction="out"/>
		</method>

	</interface>

	<!--
	  org.freedesktop.realmd.Service:
	  @short_description: the realmd service

	  Global calls for managing the realmd service. Usually you'll want
	  to use #org.freedesktop.realmd.Provider instead.

	  This interface is implemented by the realmd service, and is always
	  available at the object path <literal>/org/freedesktop/realmd</literal>

	  The service also implements the
	  <literal>org.freedesktop.DBus.ObjectManager</literal> interface which
	  makes it easy to retrieve all realmd objects and properties in one go.
	-->
	<interface name="org.freedesktop.realmd.Service">

		<!--
		  Cancel:
		  @operation: the operation to cancel

		  Cancel a realmd operation. To be able to cancel an operation
		  pass a uniquely chosen <literal>operation</literal> string
		  identifier as an option in the methods <literal>options</literal>
		  argument.

		  These operation string identifiers should be unique per client
		  calling the realmd service.

		  It is not guaranteed that the service can or will cancel the
		  operation. For example the operation may have already completed
		  by the time this method is handled. The caller of the operation
		  method will receive a
		  <literal>org.freedesktop.realmd.Error.Cancelled</literal>
		  if the operation was cancelled.
		-->
		<method name="Cancel">
			<arg name="operation" type="s" direction="in"/>
		</method>

		<!--
		  SetLocale:
		  @locale: the locale for the client

		  Set the language @locale for the client. This locale is used
		  for error messages. The locale is used until the next time
		  this method is called, the client disconnects, or the client
		  calls #org.freedesktop.realmd.Service.Release().
		-->
		<method name="SetLocale">
			<arg name="locale" type="s" direction="in"/>
		</method>

		<!--
		  Diagnostics:
		  @data: diagnostic data
		  @operation: the operation this data resulted from

		  This signal is fired when diagnostics result from an operation
		  in the provider or one of its realms.

		  It is not guaranteed that this signal is emitted once per line.
		  More than one line may be contained in @data, or a partial
		  line. New line characters are embedded in @data.

		  This signal is sent explicitly to the client which invoked
		  operation method. In order to tell which operation this
		  diagnostic data results from, pass a unique
		  <literal>operation</literal> string identifier in the
		  <literal>options</literal> argument of the operation method.
		  That same identifier will be passed back via the @operation
		  argument of this signal.
		-->
		<signal name="Diagnostics">
			<arg name="data" type="s"/>
			<arg name="operation" type="s"/>
		</signal>

		<!--
		  Release:

		  Normally realmd waits until all clients have disconnected
		  before exiting itself, sometime later. For long lived clients
		  they can call this method to allow the realmd service to quit.
		  This is an optimization. The daemon will not exit immediately.
		  It is safe to call this multiple times.
		-->
		<method name="Release">
			<!-- no arguments -->
		</method>

	</interface>

	<!--
	  org.freedesktop.realmd.Realm:
	  @short_description: a realm

	  Represents one realm.

	  Contains generic information about a realm, and useful properties for
	  introspecting what kind of realm this is and how to work with
	  the realm.

	  Use #org.freedesktop.realmd.Provider:Realms or
	  #org.freedesktop.realmd.Provider.Discover() to get access to some
	  kerberos realm objects.

	  Realms will always implement additional interfaces, such as
	  #org.freedesktop.realmd.Kerberos.  Do not assume that all realms
	  implement that kerberos interface. Use the
	  #org.freedesktop.realmd.Realm:SupportedInterfaces property to see
	  which interfaces are set.

	  Different realms support various ways to configure them on the
	  system. Use the #org.freedesktop.realmd.Realm:Configured property
	  to determine if a realm is configured. If it is configured the
	  property will be set to the interface of the mechanism that was
	  used to configure it.

	  To configure a realm, look in the
	  #org.freedesktop.realmd.Realm:SupportedInterfaces property for a
	  recognized purpose specific interface that can be used for
	  configuration, such as the
	  #org.freedesktop.realmd.KerberosMembership interface and its
	  #org.freedesktop.realmd.KerberosMembership.Join() method.

	  To deconfigure a realm from the current system, you can use the
	  #org.freedesktop.realmd.Realm.Deconfigure() method. In additon some
	  of the configuration specific interfaces provide methods to
	  deconfigure a realm in a specific way, such as
	  #org.freedesktop.realmd.KerberosMembership.Leave() method.

	  The various properties are guaranteed to have been updated before
	  the operation methods return, if they change state.
	-->
	<interface name="org.freedesktop.realmd.Realm">

		<!--
		  Name: the realm name

		  This is the name of the realm, appropriate for display to
		  end users where necessary.
		-->
		<property name="Name" type="s" access="read"/>

		<!--
		  Configured: whether this domain is configured and how

		  If this property is an empty string, then the realm is not
		  configured. Otherwise the realm is configured, and contains
		  a string which is the interface that represents how it was
		  configured, for example #org.freedesktop.realmd.KerberosMembership.
		-->
		<property name="Configured" type="s" access="read"/>

		<!--
		  Deconfigure: deconfigure this realm

		  Deconfigure this realm from the local machine with standard
		  default behavior.

		  The behavior of this method depends on the which configuration
		  interface is present in the
		  #org.freedesktop.realmd.Realm.Configured property. It does not
		  always delete membership accounts in the realm, but just
		  reconfigures the local machine so it no longer is configured
		  for the given realm. In some cases the implementation may try
		  to update membership accounts, but this is not guaranteed.

		  Various configuration interfaces may support more specific ways
		  to deconfigure a realm in a specific way, such as the
		  #org.freedesktop.realmd.KerberosMembership.Leave() method.

		  @options can contain, but is not limited to, the following values:
		  <itemizedlist>
		    <listitem><para><literal>operation</literal>: a string
		      identifier chosen by the client, which can then later be
		      passed to org.freedesktop.realmd.Service.Cancel() in order
		      to cancel the operation</para></listitem>
		  </itemizedlist>

		  This method requires authorization for the PolicyKit action
		  called <literal>org.freedesktop.realmd.deconfigure-realm</literal>.

		  In addition to common DBus error results, this method may return:
		  <itemizedlist>
		    <listitem><para><literal>org.freedesktop.realmd.Error.Failed</literal>:
		      may be returned if the deconfigure failed for a generic reason.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.Cancelled</literal>:
		      returned if the operation was cancelled.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.NotAuthorized</literal>:
		      returned if the calling client is not permitted to deconfigure a
		      realm.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.NotConfigured</literal>:
		      returned if this realm is not configured on the machine.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.Busy</literal>:
		      returned if the service is currently performing another operation like
		      join or leave.</para></listitem>
		  </itemizedlist>
		-->
		<method name="Deconfigure">
			<arg name="options" type="a{sv}" direction="in"/>
		</method>

		<!--
		  SupportedInterfaces:

		  Additional supported interfaces of this realm. This includes
		  interfaces that contain more information about the realm,
		  such as #org.freedesktop.realmd.Kerberos and interfaces
		  which contain methods for configuring a realm, such as
		  #org.freedesktop.realmd.KerberosMembership.
		-->
		<property name="SupportedInterfaces" type="as" access="read"/>

		<!--
		  Details: informational details about the realm

		  Informational details about the realm. The following values
		  should be present:
		  <itemizedlist>
		    <listitem><para><literal>server-software</literal>:
		      identifier of the software running on the server (eg:
		      <literal>active-directory</literal>).</para></listitem>
		    <listitem><para><literal>client-software</literal>:
		      identifier of the software running on the client (eg:
		      <literal>sssd</literal>).</para></listitem>
		  </itemizedlist>
		-->
		<property name="Details" type="a(ss)" access="read"/>

		<!--
		  LoginFormats: supported formats for login names

		  Supported formats for login to this realm. This is only
		  relevant once the realm has been enrolled. The formats
		  will contain a <literal>%U</literal> in the string, which
		  indicate where the user name should be placed. The formats
		  may contain a <literal>%D</literal> in the string which
		  indicate where a domain name should be placed.

		  The first format in the list is the preferred format for
		  login names.
		-->
		<property name="LoginFormats" type="as" access="read"/>

		<!--
		  LoginPolicy: the policy for logins using this realm

		  The policy for logging into this computer using this realm.

		  The policy can be changed using the
		  #org.freedesktop.realmd.Realm.ChangeLoginPolicy() method.

		  The following policies are predefined. Not all providers
		  support all these policies and there may be provider specific
		  policies or multiple policies represented in the string:
		  <itemizedlist>
		    <listitem><para><literal>allow-any-login</literal>: allow
		      login by any authenticated user present in this
		      realm.</para></listitem>
		    <listitem><para><literal>allow-permitted-logins</literal>:
		      only allow the logins permitted in the
		      #org.freedesktop.realmd.Realm:PermittedLogins
		      property.</para></listitem>
		    <listitem><para><literal>deny-any-login</literal>:
		      don't allow any logins via authenticated users of this
		      realm.</para></listitem>
		  </itemizedlist>
		-->
		<property name="LoginPolicy" type="s" access="read"/>

		<!--
		  PermittedLogins: the permitted login names

		  The list of permitted authenticated users allowed to login
		  into this computer. This is only relevant if the
		  #org.freedesktop.realmd.Realm:LoginPolicy property
		  contains the <literal>allow-permitted-logins</literal>
		  string.
		-->
		<property name="PermittedLogins" type="as" access="read"/>

		<!--
		  ChangeLoginPolicy:
		  @login_policy: the new login policy, or an empty string
		  @permitted_add: a list of logins to permit
		  @permitted_remove: a list of logins to not permit
		  @options: options for this operation

		  Change the login policy and/or permitted logins for this realm.

		  Not all realms support the all the various login policies. An
		  error will be returned if the new login policy is not supported.
		  You may specify an empty string for the @login_policy argument
		  which will cause no change in the policy itself. If the policy
		  is changed, it will be reflected in the
		  #org.freedesktop.realmd.Realm:LoginPolicy property.

		  The @permitted_add and @permitted_remove arguments represent
		  lists of login names that should be added and removed from
		  the #org.freedesktop.realmd.Kerberos:PermittedLogins property.

		  @options can contain, but is not limited to, the following values:
		  <itemizedlist>
		    <listitem><para><literal>operation</literal>: a string
		      identifier chosen by the client, which can then later be
		      passed to org.freedesktop.realmd.Service.Cancel() in order
		      to cancel the operation</para></listitem>
		  </itemizedlist>

		  This method requires authorization for the PolicyKit action
		  called <literal>org.freedesktop.realmd.login-policy</literal>.

		  In addition to common DBus error results, this method may return:
		  <itemizedlist>
		    <listitem><para><literal>org.freedesktop.realmd.Error.Failed</literal>:
		      may be returned if the policy change failed for a generic reason.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.Cancelled</literal>:
		      returned if the operation was cancelled.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.NotAuthorized</literal>:
		      returned if the calling client is not permitted to change login policy
		      operation.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.NotConfigured</literal>:
		      returned if the realm is not configured.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.Busy</literal>:
		      returned if the service is currently performing another operation like
		      join or leave.</para></listitem>
		  </itemizedlist>
		-->
		<method name="ChangeLoginPolicy">
			<arg name="login_policy" type="s" direction="in"/>
			<arg name="permitted_add" type="as" direction="in"/>
			<arg name="permitted_remove" type="as" direction="in"/>
			<arg name="options" type="a{sv}" direction="in"/>
		</method>

	</interface>

	<!--
	  org.freedesktop.realmd.Kerberos:
	  @short_description: a kerberos realm

	  An interface that describes a kerberos realm in more detail. This
	  is always implemented on an DBus object path that also implements
	  the #org.freedesktop.realmd.Realm interface.
	-->
	<interface name="org.freedesktop.realmd.Kerberos">

		<!--
		  RealmName: the kerberos realm name

		  The kerberos name for this realm. This is usually in upper
		  case.
		-->
		<property name="RealmName" type="s" access="read"/>

		<!--
		  DomainName: the DNS domain name

		  The DNS domain name for this realm.
		-->
		<property name="DomainName" type="s" access="read"/>

	</interface>

	<!--
	  org.freedesktop.realmd.KerberosMembership:

	  An interface used to configure this machine by joining a realm.

	  It sets up a computer/host account in the realm for this machine
	  and a keytab to track the credentials for that account.

	  The various properties are guaranteed to have been updated before
	  the operation methods return, if they change state.
	-->
	<interface name="org.freedesktop.realmd.KerberosMembership">

		<!--
		  SuggestedAdministrator: common administrator name

		  The common administrator name for this type of realm. This
		  can be used by clients as a hint when prompting the user for
		  administrative authentication.
		-->
		<property name="SuggestedAdministrator" type="s" access="read"/>

		<!--
		  SupportedJoinCredentials: credentials supported for joining

		  Various kinds of credentials that are supported when calling the
		  #org.freedesktop.realmd.Kerberos.Join() method.

		  Each credential is represented by a type, and an owner. The type
		  denotes which kind of credential is passed to the method. The
		  owner indicates to the client how to prompt the user or obtain
		  the credential, and to the service how to use the credential.

		  The various types are:
		  <itemizedlist>
		    <listitem><para><literal>ccache</literal>:
		      the credentials should contain an array of bytes as a
		      <literal>ay</literal> containing the data from a kerberos
		      credential cache file.</para></listitem>
		    <listitem><para><literal>password</literal>:
		      the credentials should contain a pair of strings as a
		      <literal>(ss)</literal> representing a name and
		      password. The name may contain a realm in the standard
		      kerberos format. If missing, it will default to this
		      realm. The name may be empty for a computer or one time
		      password.</para></listitem>
		    <listitem><para><literal>automatic</literal>:
		      the credentials should contain an empty string as a
		      <literal>s</literal>. Using <literal>automatic</literal>
		      indicates that default or system credentials are to be
		      used.</para></listitem>
		  </itemizedlist>

		  The various owners are:
		  <itemizedlist>
		    <listitem><para><literal>administrator</literal>:
		      the credentials belong to a kerberos user principal.
		      The caller may use this as a hint to prompt the user
		      for administrative credentials.</para></listitem>
		    <listitem><para><literal>user</literal>:
		      the credentials belong to a kerberos user principal.
		      The caller may use this as a hint to prompt the user
		      for his (possibly non-administrative)
		      credentials.</para></listitem>
		    <listitem><para><literal>computer</literal>:
		      the credentials belong to the computer realmd is
		      being run on.</para></listitem>
		    <listitem><para><literal>secret</literal>:
		      the credentials are a one time password or other secret
		      used to join or leave the computer.</para></listitem>
		  </itemizedlist>
		-->
		<property name="SupportedJoinCredentials" type="a(ss)" access="read"/>

		<!--
		  SupportedLeaveCredentials: credentials supported for leaving

		  Various kinds of credentials that are supported when calling the
		  #org.freedesktop.realmd.Kerberos.Leave() method.

		  See #org.freedesktop.realmd.Kerberos:SupportedJoinCredentials for
		  a discussion of what the values represent.
		-->
		<property name="SupportedLeaveCredentials" type="a(ss)" access="read"/>

		<!--
		  Join:

		  Join this machine to the realm and enroll the machine.

		  If this method returns successfully then the machine will be
		  joined to the realm. It is not necessary to restart services or the
		  machine afterward. Relevant properties on the realm will be updated
		  before the method returns.

		  The @credentials should be set according to one of the
		  supported credentials returned by
		  #org.freedesktop.realmd.Kerberos:SupportedJoinCredentials.
		  The first string in the tuple is the type, the second string
		  is the owner, and the variant contains the credential contents
		  See the discussion at
		  #org.freedesktop.realmd.Kerberos:SupportedJoinCredentials
		  for more information.

		  @options can contain, but is not limited to, the following values:
		  <itemizedlist>
		    <listitem><para><literal>operation</literal>: a string
		      identifier chosen by the client, which can then later be
		      passed to org.freedesktop.realmd.Service.Cancel() in order
		      to cancel the operation</para></listitem>
		  </itemizedlist>

		  This method requires authorization for the PolicyKit action
		  called <literal>org.freedesktop.realmd.configure-realm</literal>.

		  In addition to common DBus error results, this method may return:
		  <itemizedlist>
		    <listitem><para><literal>org.freedesktop.realmd.Error.Failed</literal>:
		      may be returned if the join failed for a generic reason.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.Cancelled</literal>:
		      returned if the operation was cancelled.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.NotAuthorized</literal>:
		      returned if the calling client is not permitted to perform an join
		      operation.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.AuthenicationFailed</literal>:
		      returned if the credentials passed did not authenticate against the realm
		      correctly. It is appropriate to prompt the user again.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.AlreadyEnrolled</literal>:
		      returned if already enrolled in this realm, or another realm and enrolling
		      in multiple realms is not supported.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.Busy</literal>:
		      returned if the service is currently performing another operation like
		      join or leave.</para></listitem>
		  </itemizedlist>
		-->
		<method name="Join">
			<arg name="credentials" type="(ssv)" direction="in"/>
			<arg name="options" type="a{sv}" direction="in"/>
		</method>

		<!--
		  Leave:

		  Leave the realm and unenroll the machine.

		  If this method returns successfully then the machine will have
		  left the domain and been unenrolled. It is not necessary to restart
		  services or the machine afterward. Relevant properties on the realm
		  will be updated before the method returns.

		  The @credentials should be set according to one of the
		  supported credentials returned by
		  #org.freedesktop.realmd.Kerberos:SupportedUnenrollCredentials.
		  The first string in the tuple is the type, the second string
		  is the owner, and the variant contains the credential contents
		  See the discussion at
		  #org.freedesktop.realmd.Kerberos:SupportedEnrollCredentials
		  for more information.

		  @options can contain, but is not limited to, the following values:
		  <itemizedlist>
		    <listitem><para><literal>operation</literal>: a string
		      identifier chosen by the client, which can then later be
		      passed to org.freedesktop.realmd.Service.Cancel() in order
		      to cancel the operation</para></listitem>
		  </itemizedlist>

		  This method requires authorization for the PolicyKit action
		  called <literal>org.freedesktop.realmd.deconfigure-realm</literal>.

		  In addition to common DBus error results, this method may return:
		  <itemizedlist>
		    <listitem><para><literal>org.freedesktop.realmd.Error.Failed</literal>:
		      may be returned if the unenroll failed for a generic reason.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.Cancelled</literal>:
		      returned if the operation was cancelled.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.NotAuthorized</literal>:
		      returned if the calling client is not permitted to perform an unenroll
		      operation.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.AuthenicationFailed</literal>:
		      returned if the credentials passed did not authenticate against the realm
		      correctly. It is appropriate to prompt the user again.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.NotEnrolled</literal>:
		      returned if not enrolled in this realm.</para></listitem>
		    <listitem><para><literal>org.freedesktop.realmd.Error.Busy</literal>:
		      returned if the service is currently performing another operation like
		      enroll or unenroll.</para></listitem>
		  </itemizedlist>
		-->
		<method name="Leave">
			<arg name="credentials" type="(ssv)" direction="in"/>
			<arg name="options" type="a{sv}" direction="in"/>
		</method>

	</interface>

</node>