path: root/mof/60_LMI_Realmd.mof

[ Description (
  "Access to the Realmd Service. "
  "Realmd is used to discover realms available for joining as well as "
  "providing a mechanism for joining and leaving a realm."),
  Provider("cmpi:cmpiLMI_Realmd") ]
class LMI_RealmdService : CIM_Service
{
    [Description (
        "The name of the provider. This is not normally displayed "
        "to the user, but may be useful for diagnostics or debugging.")]
  string RealmdName;

    [Description (
        "The version of the provider. This is not normally used in "
	"logic, but may be useful for diagnostics or debugging.")]
  string RealmdVersion;

    [Description (
        "The locale used for messages.")]
  // FIXME: we should support CIM_LocalizationCapabilities but there is no way query supported locales.
  string Locale;

    [Description (
        "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.")]
  string Realms[];

    [Description (

        "Discover realms for the given target. The input target is "
      	"usually a domain or realm name, perhaps typed by a user. If an "
      	"empty target string is provided the realm provider should try "
      	"to discover a default realm if possible (eg: from DHCP).\n "
        "\n"
        "The behavior of the method may be modified via optional "
        "<name,value> pairs called \"options\" passed an array of "
        "option names and option values. The <name,value> pair is "
        "formed by indexing into the name array and finding it's value "
        "at the same index in the value array.\n "
        "\n"
        "The currently defined options are:\n "
        "\n"
	"\"client-software\": a string containing the client software "
	"identifier that the returned realms should match.\n"
        "\n"
	"\"server-software\": a string containing the client software "
	"identifier that the returned realms should match.\n"
        )]

    uint32 Discover(
      [In, Description (
        "What realms to discover")]
      string Target,
      [In, ArrayType ( "Indexed" ), Description (
        "This array is correlated with the OptionValues array. "
        "Each entry is related to the entries in the other array "
        "located at the same index. In this way a (name,value) tuple "
        "can be constructed.")]
      string OptionNames[],
      [In, ArrayType ( "Indexed" ), Description (
        "This array is correlated with the OptionNames array. "
        "Each entry is related to the entries in the other array "
        "located at the same index. In this way a (name,value) tuple "
        "can be constructed.")]
       string OptionValues[],
      [In ( false ), Out, Description (
        "Array of references to discovered realms")]
      LMI_RealmdRealm REF DiscoveredRealms[]);

    // Proof of concept simplfied API starts here

    [Description (
        "The name of the domain that this computer is a member of "
	"or NULL if not a member of any domain.")]
    string Domain;

    [Description (
        "Join the computer to a domain.")]
   uint32 JoinDomain(
      [In, Description (
        "The name of the domain to join.")]
      string Domain,
      [In, Description (
        "The administrative user who is authorizing joining the domain. "
	"Or NULL for a one time password based join.")]
      string User,
      [In, Description (
        "Either NULL for an automatic join, a one time password, or the "
	"password for the administrative user in the User parameter.")]
      string Password,
      [In, ArrayType ( "Indexed" ), Description (
        "This array is correlated with the OptionValues array. "
        "Each entry is related to the entries in the other array "
        "located at the same index. In this way a (name,value) tuple "
        "can be constructed.")]
      string OptionNames[],
      [In, ArrayType ( "Indexed" ), Description (
        "This array is correlated with the OptionNames array. "
        "Each entry is related to the entries in the other array "
        "located at the same index. In this way a (name,value) tuple "
        "can be constructed.")]
       string OptionValues[]);

    [Description (
        "Make the computer leave its joined domain.")]
   uint32 LeaveDomain(
      [In, Description (
        "The name of the domain to join.")]
      string Domain,
      [In, Description (
        "The administrative user who is authorizing joining the domain. "
	"Or NULL for a one time password based join.")]
      string User,
      [In, Description (
        "Either NULL for an automatic join, a one time password, or the "
	"password for the administrative user in the User parameter.")]
      string Password,
      [In, ArrayType ( "Indexed" ), Description (
        "This array is correlated with the OptionValues array. "
        "Each entry is related to the entries in the other array "
        "located at the same index. In this way a (name,value) tuple "
        "can be constructed.")]
      string OptionNames[],
      [In, ArrayType ( "Indexed" ), Description (
        "This array is correlated with the OptionNames array. "
        "Each entry is related to the entries in the other array "
        "located at the same index. In this way a (name,value) tuple "
        "can be constructed.")]
       string OptionValues[]);
};

[ Description (
  "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 LMI_RealmdService.Discover() to get access to help populate the "
  "LMI_RealmdService.Realms property. "

  "Different realms support various ways to configure them on the "
  "system. LMI_RealmdRealm.Configured property to determine if a realm "
  "is configured. If it is configured the property will be set to class "
  "used to configure it. "

  "To configure a realm use the method on the LMIRealmdRealm subclass "
  "designed for that purpose, for example the "
  "LMI_RealmdKerberosRealm.Join() method. "

  "To deconfigure a realm from the current system, you can use the "
  "Deconfigure() method. "),
  Provider("cmpi:cmpiLMI_Realmd") ]
class LMI_RealmdRealm : CIM_LogicalElement
{

    [Key, Override ( "InstanceID" ),
       Description (
          "Within the scope of the instantiating Namespace, "
          "InstanceID opaquely and uniquely identifies an instance "
          "of this class. In order to ensure uniqueness within the "
          "NameSpace, the value of InstanceID shall be constructed "
          "using the following \'preferred\' algorithm: \n"
          "<OrgID>:<LocalID> \n"
          "<LocalID> will be DBus object path correlated to this instance.")]
   string InstanceID;

    [Key, Description ( "The scoping System\'s CCN." ),
     MaxLen ( 256 ),
     Propagated ( "CIM_System.CreationClassName" )]
  string SystemCreationClassName;

    [Key, Description ( "The scoping System\'s Name." ),
     MaxLen ( 256 ),
    Propagated ( "CIM_System.Name" )]
  string SystemName;

    [Description (
        "Name of the realm, "
        "appropriate for display to end users where necessary.")]
  string RealmName;

    [Description (
    	"If this property is NULL then the realm is not configured."
        "Otherwise the realm is configured and the property contains "
	"a string which is the interface that represents how it was "
        "configured, e.g. \"KerberosMembership\".")]
  string Configured;

    [Description (
	"Indicates the types of operations this realm is capable of."
        "Current possible values are: \"Kerberos\", \"KerberosMembership\".")]
  string SupportedInterfaces[];

    [Description (
      "Extra detail information expressed as (name,value) pairs. "
      "This array is correlated with the DetailValues array. "
      "Each entry is related to the entries in the other array "
      "located at the same index. In this way a (name,value) tuple "
      "can be constructed."),
     ArrayType ( "Indexed" )]
  string DetailNames[];
    [Description (
      "Extra detail information expressed as (name,value) pairs. "
      "This array is correlated with the DetailNames array. "
      "Each entry is related to the entries in the other array "
      "located at the same index. In this way a (name,value) tuple "
      "can be constructed."),
     ArrayType ( "Indexed" )]
  string DetailValues[];

    [Description (
	"Software packages that are required in order for a join to "
	"succeed. These are either simple strings like \"sssd\" "
	"or strings with an operator and version number like \"sssd >= 1.9.0\" "
        "These values are specific to the packaging system that is being run.")]
  string RequiredPackages[];

    [Description (
	"Supported formats for login to this realm. This is only "
	"relevant once the realm has been enrolled. The formats "
	"will contain a \"%U\" in the string, which indicates where the "
        "user name should be placed. The formats may contain a \"%D\" in "
        "the string which indicates where a domain name should be placed. "
        "The first format in the list is the preferred format for login names.")]
  string LoginFormats[];

    [Description (
	"The policy for logging into this computer using this realm. "
        "The policy can be changed using the 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: "
	"\"allow-any-login\": allow login by any authenticated user present in this realm. "
	"\"allow-permitted-logins\": only allow the logins permitted in the PermittedLogins property. "
	"\"deny-any-login\": don't allow any logins via authenticated users of this realm.")]
  string LoginPolicy;

    [Description (
	"The list of permitted authenticated users allowed to login "
	"into this computer. This is only relevant if the LoginPolicy property "
	"contains the \"allow-permitted-logins\" string.")]
  string PermittedLogins[];

    [Description (
	"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 a NULL value 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 LoginPolicy property. "
	"The permitted_add and permitted_remove arguments represent lists of "
        "login names that should be added and removed from the PermittedLogins property.")]
  uint32 ChangeLoginPolicy(
      [In, Description (
        "the new login policy or NULL")]
      string LoginPolicy,
      [In, Description (
        "a list of logins to permit")]
      string PermittedAdd[],
      [In, Description (
        "a list of logins to not permit")]
      string PermittedRemove[]);

    [Description (
	"Deconfigure: deconfigure this realm"
        "\n"
        "Deconfigure this realm from the local machine with standard "
        "default behavior. "
        "\n"
        "The behavior of this method depends on the which configuration "
        "interface is present in the 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."
        "\n"
	"Various configuration interfaces may support more specific ways "
	"to deconfigure a realm in a specific way, such as the "
        "KerberosMembership.Leave() method.")]
  uint32 Deconfigure();

};


[ Description (
     "Credentials supported for joining. "
     "\n"
     "Various kinds of credentials that are supported when calling the "
     "Join() method. "
     "\n"
     "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. "
     "\n"

     "The various types are: "
     "\"ccache\": "
     "The credentials should contain an array of octets containing"
     "the data from a kerberos credential cache file. "
     "The data must be passed in the Data parameter, the Name & Password parameters must be NULL. "
     "\n"
     "\"password\": "
     "The credentials should contain a pair of strings representing "
     "a name and password. The name may contain a realm in the "
     "standard kerberos format. If a realm is missing, it will "
     "default to this realm. "
     "The name must be passed in the Name parameter, the password must be passed "
     "in the Password parameter, the Data parameter must be NULL. "
     "\n"
     "\"secret\": "
     "The credentials should contain a string secret. This is "
     "usually used for one time passwords. "
     "The data must be passed in the Data parameter, the Name & Password parameters must be NULL. "
     "\n"
     "\"automatic\": "
     "The credentials should contain an empty string.  Using "
     "\"automatic\" indicates that default or system credentials are "
     "to be used. "
     "The Name, Password & Data parameters must be NULL. "
     "\n"
     "The various owners are: "
     "\n"
     "\"administrator\": "
     "The credentials belong to a kerberos user principal. "
     "The caller may use this as a hint to prompt the user "
     "for administrative credentials. "
     "\n"
     "\"user\": "
     "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. "
     "\n"
     "\"computer\": "
     "The credentials belong to a computer account. "
     "\n"
     "\"none\": "
     "The credentials have an unspecified owner, such as a one time "
     "secret."),
  Provider("cmpi:cmpiLMI_Realmd") ]
class LMI_RealmdKerberosRealm : LMI_RealmdRealm
{
    [Description (
	"The kerberos name for this realm. This is usually in upper "
        "case.")]
  string RealmName;

    [Description (
	"The DNS domain name for this realm.")]
  string DomainName;

    [Description (
	"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.")]
  string SuggestedAdministrator;

    [Description (
        "This array is correlated with the SupportedJoinCredentialOwners array. "

        "Each entry is related to the entries in the other array "
        "located at the same index. In this way a (type,owner) tuple "
        "can be constructed. The set of tuples formed by correlating "
        "the two arrays define the supported combinations for the Join "
        "method."),
   ValueMap { "1", "2", "3", "4"},
   Values { "ccache", "password", "secrect", "automatic" },
   ArrayType ( "Indexed" )]
   uint32 SupportedJoinCredentialTypes[];

    [Description (
        "This array is correlated with the SupportedJoinCredentialTypes array. "

        "Each entry is related to the entries in the other array "
        "located at the same index. In this way a (type,owner) tuple "
        "can be constructed. The set of tuples formed by correlating "
        "the two arrays define the supported combinations for the Join "
        "method."),
   ValueMap { "1", "2", "3", "4"},
   Values { "administrator", "user", "computer", "none" },
   ArrayType ( "Indexed" )]
   uint32 SupportedJoinCredentialOwners[];

    [Description (
        "This array is correlated with the SupportedLeaveCredentialOwners array. "

        "Each entry is related to the entries in the other array "
        "located at the same index. In this way a (type,owner) tuple "
        "can be constructed. The set of tuples formed by correlating "
        "the two arrays define the supported combinations for the Leave "
        "method."),
   ValueMap { "1", "2", "3", "4"},
   Values { "ccache", "password", "secrect", "automatic" },
   ArrayType ( "Indexed" )]
   uint32 SupportedLeaveCredentialTypes[];

    [Description (
        "This array is correlated with the SupportedLeaveCredentialTypes array. "

        "Each entry is related to the entries in the other array "
        "located at the same index. In this way a (type,owner) tuple "
        "can be constructed. The set of tuples formed by correlating "
        "the two arrays define the supported combinations for the Leave "
        "method."),
   ValueMap { "1", "2", "3", "4"},
   Values { "administrator", "user", "computer", "none" },
   ArrayType ( "Indexed" )]
   uint32 SupportedLeaveCredentialOwners[];

   // FIXME - The Data parameter should be uint8 array with the octetstring qualifier
   // but the octetstring qualier doesn't seem to do anything and you end up with
   // an array of CMPIValue's with one octet in each, this is highly inefficent and awkward.

    [Description (
        "")]
   uint32 Join(
      [In, Description (
        "Credential type, see LMI_RealmdKerberosRealm description"),
       ValueMap { "1", "2", "3", "4"},
       Values { "ccache", "password", "secrect", "automatic" }]
      uint32 Type,
      [In, Description (
        "Credential owner, see LMI_RealmdKerberosRealm description"),
       ValueMap { "1", "2", "3", "4"},
       Values { "administrator", "user", "computer", "none" }]
      uint32 Owner,
      [In, Description (
        "The name may contain a realm in the standard kerberos format. "
        "If a realm is missing, it will default to this realm. "
        "Used when the Type is password.")]
      string Name,
      [In, Description (
        "Authentication password. "
        "Used when the Type is password.")]
      string Password,
      [In, Description (
        "Binary data when the Type is ccache or secret"),
        OctetString]
      uint8 Data[],
      [In, ArrayType ( "Indexed" ), Description (
        "This array is correlated with the OptionValues array. "
        "Each entry is related to the entries in the other array "
        "located at the same index. In this way a (name,value) tuple "
        "can be constructed.")]
      string OptionNames[],
      [In, ArrayType ( "Indexed" ), Description (
        "This array is correlated with the OptionNames array. "
        "Each entry is related to the entries in the other array "
        "located at the same index. In this way a (name,value) tuple "
        "can be constructed.")]
       string OptionValues[]);

    [Description (
        "")]
   uint32 Leave(
      [In, Description (
        "Credential type, see LMI_RealmdKerberosRealm description"),
       ValueMap { "1", "2", "3", "4"},
       Values { "ccache", "password", "secrect", "automatic" }]
      uint32 Type,
      [In, Description (
        "Credential owner, see LMI_RealmdKerberosRealm description"),
       ValueMap { "1", "2", "3", "4"},
       Values { "administrator", "user", "computer", "none" }]
      uint32 Owner,
      [In, Description (
        "The name may contain a realm in the standard kerberos format. "
        "If a realm is missing, it will default to this realm. "
        "Used when the Type is password.")]
      string Name,
      [In, Description (
        "Authentication password. "
        "Used when the Type is password.")]
      string Password,
      [In, Description (
        "Binary data when the Type is ccache or secret"),
        OctetString]
      uint8 Data[],
      [In, ArrayType ( "Indexed" ), Description (
        "This array is correlated with the OptionValues array. "
        "Each entry is related to the entries in the other array "
        "located at the same index. In this way a (name,value) tuple "
        "can be constructed.")]
      string OptionNames[],
      [In, ArrayType ( "Indexed" ), Description (
        "This array is correlated with the OptionNames array. "
        "Each entry is related to the entries in the other array "
        "located at the same index. In this way a (name,value) tuple "
        "can be constructed.")]
       string OptionValues[]);
};

[ Association,
  Provider("cmpi:cmpiLMI_Realmd") ]
class LMI_HostedRealmdService: CIM_HostedService
{
  [ Override("Antecedent"),
    Description("The hosting System") ]
  CIM_ComputerSystem REF Antecedent;

  [ Override("Dependent"),
    Description("The Central Instance of realm management") ]
  LMI_RealmdService REF Dependent;
};

[ Association,
  Provider("cmpi:cmpiLMI_Realmd") ]
class LMI_ServiceAffectsRealmdRealm: CIM_ServiceAffectsElement
{
  [ Override("AffectingElement"),
    Description("The Central Instance of realm management") ]
  LMI_RealmdService REF AffectingElement;

  [ Override("AffectedElement"),
    Description("The managed Identity") ]
  LMI_RealmdRealm REF AffectedElement;
};