<!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/chromium/SessionManager"
      xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
<!--
  Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
  Use of this source code is governed by a BSD-style license that can be
  found in the LICENSE file.

-->

  <!-- ********************************************************************* -->

  <!--
      org.chromium.SessionManagerInterface:
      @short_description: User session manager.

      Interface for user session manager. Also handles persisting and
      retrieving device and per-user enterprise policy blobs and
      brokering certain privileged operations on the browser's behalf.
  -->
  <interface name="org.chromium.SessionManagerInterface">

    <!--
        EmitLoginPromptVisible:

        Emits the "login-prompt-visible" upstart signal and LoginPromptVisible
        DBus signal on the browser's behalf.
    -->
    <method name="EmitLoginPromptVisible">
      <annotation name="org.chromium.DBus.Method.Kind" value="simple" />
    </method>

    <!--
        LoginPromptVisible:

        Emitted when the browser indicates that the sign in screen is visible.
    -->
    <signal name="LoginPromptVisible" />

    <!--
        EmitAshInitialized

        Emits the "ash-initialized" upstart signal on the browser's behalf.
    -->
    <method name="EmitAshInitialized">
      <annotation name="org.chromium.DBus.Method.Kind" value="simple" />
    </method>

    <!--
        EnableChromeTesting:
        @force_relaunch: Restart the browser no matter what.
        @extra_arguments: Extra command line arguments to pass on restart.
        @extra_environment_variables: Extra environment variables to export.
        @filepath: The named pipe to be used for testing communication.

        Restarts the browser, leaving it open for testing automation.
        Adds an argument to the chrome child job command line that causes it,
        upon restart, to open a testing channel. Next, kills and restarts
        chrome. The name of the pipe to be used for testing is returned in
        @filepath.
        If @force_relaunch is true, Chrome will be restarted with each
        invocation. Otherwise, it will only be restarted if
        automation is not yet enabled.  @extra_arguments can
        include any additional arguments that need to be passed to
        Chrome on subsequent launches. The values in
        @extra_environment_variables should take the form "NAME=VAL".
    -->
    <method name="EnableChromeTesting">
      <arg type="b" name="force_relaunch" direction="in" />
      <arg type="as" name="extra_arguments" direction="in" />
      <arg type="as" name="extra_environment_variables" direction="in" />
      <arg type="s" name="filepath" direction="out" />
    </method>

    <!--
        SavePassword:
        @password_fd: File descriptor to a pipe containing the user's password.
            The password is prefixed by the size of the password written as a
            size_t value.

        Saves the primary user's login password at the start of the session. The
        password will be saved to the Linux kernel process keyring. This
        password is used by shill to authenticate the user to 802.1X networks
        that require authentication via a username/password combo. The password
        will only be saved and used for enterprise users.

        The password will be discarded when the session_manager process exits in
        response to the session ending.
    -->
    <method name="SaveLoginPassword">
      <arg type="h" name="password_fd" direction="in" />
    </method>

    <!--
        LoginScreenStorageStore:
        @key: Key to store a given value for.
        @metadata: Metadata specifying settings for a given key/value pair.
        @value_size: Size of the value in bytes.
        @value_fd: File descriptor pointing at a shared memory region containing
            value to store with a given key.

        Saves a given key/value pair to the session manager for later access
        either from the login screen or the user session using
        |LoginScreenRetrieve()|. This method can only be called when no user
        sessions are running.

        If |metadata.clear_on_session_exit| is set to 'true', the saved
        key/value pair is deleted on session exit.
    -->
    <method name="LoginScreenStorageStore">
      <arg type="s" name="key" direction="in" />
      <arg type="ay" name="metadata" direction="in" />
      <arg type="t" name="value_size" direction="in" />
      <arg type="h" name="value_fd" direction="in" />
    </method>

    <!--
        LoginScreenStorageRetrieve:
        @key: Key the requested value was stored for.
        @value_size: Size of the value in bytes.
        @value_fd: File decriptor pointing at a shared memory region containing
            the requested value.

        Retrieves a value previously stored with |LoginScreenStore()|.
    -->
    <method name="LoginScreenStorageRetrieve">
      <arg type="s" name="key" direction="in" />
      <arg type="t" name="value_size" direction="out" />
      <arg type="h" name="value_fd" direction="out" />
    </method>

    <!--
        LoginScreenStorageListKeys:
        @keys: All keys that are currently stored in the login screen storage.
    -->
    <method name="LoginScreenStorageListKeys">
      <arg type="as" name="keys" direction="out" />
    </method>

    <!--
        LoginScreenStorageDelete:
        @key: Key to delete.

        Deletes a key from the login screen storage.
    -->
    <method name="LoginScreenStorageDelete">
      <arg type="s" name="key" direction="in" />
      <annotation name="org.chromium.DBus.Method.Kind" value="simple" />
    </method>

    <!--
        StartSession:
        @account_id: Account ID of the user to start a session for.
        @unique_identifier: Unused.

        Updates bookkeeping to know about a session for @account_id. Also emits
        "start-user-session" upstart signal (asynchronously) and
        "SessionStateChanged:started" D-Bus signal.
    -->
    <method name="StartSession">
      <arg type="s" name="account_id" direction="in" />
      <arg type="s" name="unique_identifier" direction="in" />
    </method>

    <!--
        @deprecated Use StopSessionWithReason instead.

        StopSession:
        @unique_identifier: Unused.

        Terminates all active user sessions, announces this over upstart
        ("stop-user-session") and DBus (SessionStateChanges:stopped).
    -->
    <method name="StopSession">
      <arg type="s" name="unique_identifier" direction="in" />
      <annotation name="org.chromium.DBus.Method.Kind" value="simple" />
    </method>

    <!--
        StopSessionWithReason:
        @reason: The reason of stopping the session.

        Terminates all active user sessions, announces this over upstart
        ("stop-user-session") and DBus (SessionStateChanges:stopped).
    -->
    <method name="StopSessionWithReason">
      <arg type="u" name="reason" direction="in" />
      <annotation name="org.chromium.DBus.Method.Kind" value="simple" />
    </method>

    <!--
        SessionStateChanged:
        @state: State the device has changed to.

        Signal emitted to announce session state changes. Supported values for
        @state include <quote>started</quote>, <quote>stopping</quote>, and
        <quote>stopped</quote>.
    -->
    <signal name="SessionStateChanged">
      <arg type="s" name="state" />
    </signal>

    <!--
        StorePolicyEx:
        @descriptor_blob: Serialized PolicyDescriptor protobuf containing
            metadata about the policy (e.g. user policy, account id).
        @policy_blob: Serialized PolicyFetchResponse protobuf which wraps the
            actual policy data along with an SHA1-RSA signature over the policy
            data. The policy data is opaque to Session Manager, the exact
            definition is only relevant to client code in Chrome.

        Verifies the signature in @policy_blob and persists the blob to disk.

        Device policy is stored in a root-owned location outside of any user's
        cryptohome. It is verified with the device-wide policy key.

        User policy is stored in a root-owned location within the user's
        cryptohome (for privacy reasons). The first attempt to store policy also
        installs the signing key for user policy. This key is used later to
        verify policy updates pushed by Chrome.

        User policy for users without session is rejected by this method.

        Policy for device local accounts is stored in the root-owned
        /var/lib/device_local_accounts directory in the stateful partition.
        Signatures are checked against the owner key, key rotation is not
        allowed.

        Component policy is rejected by the implementation at this point since
        it is stored by Chrome directly.
    -->
    <method name="StorePolicyEx">
      <arg type="ay" name="descriptor_blob" direction="in" />
      <arg type="ay" name="policy_blob" direction="in" />
      <annotation name="org.chromium.DBus.Method.Kind" value="async" />
    </method>

    <!--
        StoreUnsignedPolicyEx:
        @descriptor_blob: Serialized PolicyDescriptor protobuf containing
            metadata about the policy (user, device or component policy).
        @policy_blob: Serialized PolicyFetchResponse protobuf containing user,
            device or component policy, but no signature. If empty and
            |descriptor_blob| specifies component policy, the policy is deleted.

        Similar to StorePolicyEx, but stores policy without signature
        verification for AD managed devices. Locked down through busconfig to be
        only callable by authpolicyd and exits with an error if install
        attributes are not locked to enterprise_ad device mode.
    -->
    <method name="StoreUnsignedPolicyEx">
      <arg type="ay" name="descriptor_blob" direction="in" />
      <arg type="ay" name="policy_blob" direction="in" />
      <annotation name="org.chromium.DBus.Method.Kind" value="async" />
    </method>

    <!--
        ListStoredComponentPolicies:
        @descriptor_blob: Serialized PolicyDescriptor protobuf specifying the
            account (e.g. user, device) and the policy domain for which stored
            policies should be listed. The domain must support component ids
            (e.g. extensions, but not not Chrome policy). The component id field
            must be empty.

        Lists stored component policies for a given account (e.g. user, device)
        and policy domain (e.g. extensions).
    -->
    <method name="ListStoredComponentPolicies">
      <arg type="ay" name="descriptor_blob" direction="in" />
      <arg type="as" name="component_ids" direction="out" />
    </method>

    <!--
        RetrievePolicyEx:
        @descriptor_blob: Serialized PolicyDescriptor protobuf containing
            metadata about the policy (user vs device policy).
        @policy_blob: Serialized PolicyFetchResponse protobuf containing the
            requested user or device policy and a signature over that policy.

        Retrieve policy stored by StorePolicyEx.

        Can retrieve user policy for users without a user session. This is
        useful if we need to access user policy before actually starting the
        session. The user home must have been mounted as hidden user home with
        cryptohome.
    -->
    <method name="RetrievePolicyEx">
      <arg type="ay" name="descriptor_blob" direction="in" />
      <arg type="ay" name="policy_blob" direction="out" />
    </method>

    <!--
        SetOwnerKeyComplete:
        Defined as login_manager::kOwnerKeySetSignal, broadcast when the request
        to persist the policy key was completed.
        @success: A string value with either "success" or "failure" indicating
                  whether the policy key was actually persisted.
    -->
    <signal name="SetOwnerKeyComplete">
      <arg type="s" name="success" />
    </signal>

    <!--
        PropertyChangeComplete:
        Broadcast when a request to persist the policy blob file on disk was
        completed.
        @success: A string value with either "success" or "failure" indicating
                  whether the policy blob was actually persisted.
    -->
    <signal name="PropertyChangeComplete">
      <arg type="s" name="success" />
    </signal>

    <!--
        RetrieveSessionState:
        @state: The current session state.

        Get information about the current session. Will be one of
        <quote>started</quote>, <quote>stopping</quote>, <quote>stopped</quote>.
    -->
    <method name="RetrieveSessionState">
      <arg type="s" name="state" direction="out" />
      <annotation name="org.chromium.DBus.Method.Kind" value="simple" />
    </method>

    <!--
        RetrieveActiveSessions:
        @sessions: A map describing the currently active user sessions.

        Enumerate active user sessions.
        @sessions is a dictionary mapping { username: sanitized_user_name }.
    -->
    <method name="RetrieveActiveSessions">
      <arg type="a{ss}" name="sessions" direction="out" />
      <annotation name="org.chromium.DBus.Method.Kind" value="simple" />
    </method>

    <!--
        RetrievePrimarySession:
        @username: username of the primary session.
        @sanitized_username: sanitized username of the primary session.

        Return primary user session, if existent; otherwise return two empty
        strings.
    -->
    <method name="RetrievePrimarySession">
      <arg type="s" name="username" direction="out" />
      <arg type="s" name="sanitized_username" direction="out" />
      <annotation name="org.chromium.DBus.Method.Kind" value="simple" />
    </method>

    <!--
        IsGuestSessionActive:
        @is_guest: Whether a guest session is active and running.

        Check whether a guest session is active.
    -->
    <method name="IsGuestSessionActive">
      <arg type="b" name="is_guest" direction="out" />
      <annotation name="org.chromium.DBus.Method.Kind" value="simple" />
    </method>

    <!--
	HandleSupervisedUserCreationStarting:

        Handle notification from Chrome that creation of a supervised user is
        underway. Browser crashes will trigger session termination until
        someone calls HandleSupervisedUserCreationFinished.
    -->
    <method name="HandleSupervisedUserCreationStarting">
      <annotation name="org.chromium.DBus.Method.Kind" value="simple" />
    </method>

    <!--
	HandleSupervisedUserCreationFinished:

        Handle notification from Chrome that creation of a supervised user is
        completed. Browser crashes will once again trigger a browser restart.
    -->
    <method name="HandleSupervisedUserCreationFinished">
      <annotation name="org.chromium.DBus.Method.Kind" value="simple" />
    </method>

    <!--
        LockScreen:

        Allows other processes to request screen locking.
        Emits LockScreen signal to Chromium Browser to tell it to lock the
        screen. The browser should call the HandleScreenLocked
        method when the screen is actually locked.
    -->
    <method name="LockScreen" />

    <!--
        HandleLockScreenShown:

        Handle notification from Chrome that the lock screen is visible.
        Emits ScreenIsLocked.
    -->
    <method name="HandleLockScreenShown">
      <annotation name="org.chromium.DBus.Method.Kind" value="simple" />
    </method>

    <!--
        HandleLockScreenDismissed:

        Handle notification from Chrome that the lock screen is hidden.
        Emits ScreenIsUnlocked.
    -->
    <method name="HandleLockScreenDismissed">
      <annotation name="org.chromium.DBus.Method.Kind" value="simple" />
    </method>

    <!--
        IsScreenLocked:

        Returns true through screen_locked if the screen is locked.
    -->
    <method name="IsScreenLocked">
      <arg type="b" name="screen_locked" direction="out" />
      <annotation name="org.chromium.DBus.Method.Kind" value="simple" />
    </method>

    <!--
        ScreenIsLocked:
        Broadcast that the browser locked the screen.
    -->
    <signal name="ScreenIsLocked" />

    <!--
        ScreenIsUnlocked:
        Broadcast that the browser unlocked the screen.
    -->
    <signal name="ScreenIsUnlocked" />

    <!--
        RestartJob:
        @cred_fd: File descriptor that provides PID to be restarted.
        @argv: Command line arguments to restart the job with.
        @mode: Mode to restart job without user session (for headless chromium)
               or with user session (for guest session only).

      Restarts job with pid returned when querying @cred_fd using
        SO_PEERCRED, replacing its command line arguments with those provided.
        Only works for the browser process managed by the SessionManager.
    -->
    <method name="RestartJob">
      <arg type="h" name="cred_fd" direction="in" />
      <arg type="as" name="argv" direction="in" />
      <arg type="u" name="mode" direction="in" />
    </method>

    <!--
        StartDeviceWipe:

        Sets the device up to "Powerwash" on reboot, and triggers a reboot.
    -->
    <method name="StartDeviceWipe" />

    <!--
        StartRemoteDeviceWipe:

        Same as StartDeviceWipe (sets the device up to "Powerwash" on reboot,
        and triggers a reboot), except it also verifies the remote command.
    -->
    <method name="StartRemoteDeviceWipe">
      <arg type="ay" name="signed_command" direction="in" />
    </method>

    <!--
        ClearForcedReEnrollmentVpd:

        Sets block_devmode=0 and check_enrollment=0 in RW_VPD.

        Currently, we also set block_devmode=0 in system properties
        here. This should be removed again once the system property
        check for dev mode blocking is removed.
    -->
    <method name="ClearForcedReEnrollmentVpd">
      <annotation name="org.chromium.DBus.Method.Kind" value="async" />
    </method>

    <!--
        StartTPMFirmwareUpdate:
        @update_mode: Indicates the requested firmware update mode.

        Requests a TPM firmware update to be installed. This will only
        work immediately after boot while there hasn't been a user
        session yet.

        The idea behind the fresh boot requirement is that we
        shouldn't expose the ability to trigger a firmware update to a
        compromised browser processes. Only allowing it after a
        (verified) reboot reduces chances that we're dealing with a
        compromised browser process significantly.

        Remotely managed devices rely on a remote device owner to take
        device management decisions. Since updating TPM firmware is an
        invasive process, we don't allow local users to trigger the
        update on their own, but rely on device policy to confirm the
        requested update_mode.
    -->
    <method name="StartTPMFirmwareUpdate">
      <arg type="s" name="update_mode" direction="in" />
    </method>

    <!--
        SetFlagsForUser:
        @account_id: Account ID of the user to set flags for.
        @flags: array of flags to be set for the user.

        Sets browser @flags to be applied on next in-session restart. @flags are
        added as switches to the browser command line.
    -->
    <method name="SetFlagsForUser">
      <arg type="s" name="account_id" direction="in" />
      <arg type="as" name="flags" direction="in" />
      <annotation name="org.chromium.DBus.Method.Kind" value="simple" />
    </method>

    <!--
        SetFeatureFlagsForUser:
        @account_id: Account ID of the user to set flags for.
        @flags: array of feature flags to be set for the user.

        Sets feature flags to pass on browser startup for in-session restarts.
    -->
    <method name="SetFeatureFlagsForUser">
      <arg type="s" name="account_id" direction="in" />
      <arg type="as" name="feature_flags" direction="in" />
      <annotation name="org.chromium.DBus.Method.Kind" value="simple" />
    </method>

    <!--
        GetServerBackedStateKeys:
        @state_keys: The array of currently valid state keys.

        Requests server-backed state keys to be computed and returned. A
        server-backed state key is an opaque client-determined identifier that's
        used to stage state in a server to be retrieved after device
        recovery. These are used to figure out device state such as previous
        enrollment domain and whether the device got marked as stolen by its
        owner. The keys are time-dependent, with each key being valid only for a
        window of time, and based on system time this call returns the currently
        valid state key plus a number of subsequent state keys (all sorted by
        time in ascending order) that span approximately a year of time in
        coverage. It is the responsibility of the caller to ensure that the
        system time is accurate before starting the request!
    -->
    <method name="GetServerBackedStateKeys">
      <arg type="aay" name="state_keys" direction="out" />
      <annotation name="org.chromium.DBus.Method.Kind" value="async" />
    </method>

    <!--
        InitMachineInfo:
        @data: A string containing newline-separated key=value pairs.

        Initializes supplemental machine information for use by session manager
        that has be asynchronously determined in the boot process after
        starting session_manager. This method gets invoked by the ui-init-late
        init job; nothing else should call this method.
    -->
    <method name="InitMachineInfo">
      <arg type="s" name="data" direction="in" />
    </method>

    <!--
        StartArcMiniContainer:
        @request: Serialized StartArcMiniContainerRequest proto message
                  containing ARC startup options.

        Starts an ARC mini-container that contains no user information. This
        mainly exists so that we can do some of the container initialization
        work at the login screen, improving perceived responsiveness. This
        method is only available if the board supports ARC.  This method gets
        invoked by Chrome.
    -->
    <method name="StartArcMiniContainer">
      <arg type="ay" name="request" direction="in" />
    </method>

    <!--
        UpgradeArcContainer:
        @request: Serialized UpgradeArcContainerRequest proto message
                  containing ARC upgrade options.

        Upgrades an existing ARC mini-container to a fully featured container.
        This method is only available if the board supports ARC.  This method
        gets invoked by Chrome.

        This reports an error if Upgrade is somehow failed. If ARC mini
        container is already running, the ArcInstanceStopped signal will be
        delivered with error info.
    -->
    <method name="UpgradeArcContainer">
      <arg type="ay" name="request" direction="in" />
    </method>

    <!--
        StopArcInstance:
        @account_id: Account ID of the user to stop ARC for.
        @should_backup_log: Flag to back up arc-bugreport before shutdown.

        Stops the currently running ARC instance. Used to manually stop the ARC
        instance. If the instance is not running, this will result in a no-op.
        If this method is not called, session_manager will still stop the
        instance when the user's session ends. This method is only available if
        the board supports ARC. This method gets invoked by Chrome.
    -->
    <method name="StopArcInstance">
      <arg name="account_id" type="s" direction="in" />
      <arg name="should_backup_log" type="b" direction="in" />
      <annotation name="org.chromium.DBus.Method.Kind" value="normal"/>
    </method>

    <!--
        ArcInstanceStopped:
        @reason: The value of ArcContainerStopReason.

        Sent when ARC instance is stopped. Maybe clean shutdown, upgrade
        failure, or crash.
    -->
    <signal name="ArcInstanceStopped">
      <arg type="u" name="reason" />
    </signal>

    <!--
        SetArcCpuRestriction:
        @restriction_state: State used to set the level of CPU allowed specified
        as foreground or background with the
        |login_manager::ContainerCpuRestrictionState| enum.

        Adjusts the amount of CPU the ARC instance is allowed to use by setting
        the cpu.shares value of ARC's cpu cgroup.  When restriction_state is
        CONTAINER_CPU_RESTRICTION_FOREGROUND the limit is adjusted so ARC can
        use all the system's CPU if needed.  When restriction_state is
        CONTAINER_CPU_RESTRICTION_BACKGROUND, cpu.shares is set back to a
        tightly restricted level.  The ARC container is started in a state that
        is more restricted than CONTAINER_CPU_RESTRICTION_BACKGROUND.  This
        startup state is to allow Chrome to restore during login and can't be
        re-entered after startup is complete.
        Calling the method while the instance is not running *is* okay as long
        as the cgroups exist.
    -->
    <method name="SetArcCpuRestriction">
      <arg type="u" name="restriction_state" direction="in" />
    </method>

    <!--
        EmitArcBooted:

        Emits the "arc-booted" upstart signal on the browser's behalf.
    -->
    <method name="EmitArcBooted">
      <arg type="s" name="account_id" direction="in" />
    </method>

    <!--
        GetArcStartTimeTicks:

        Returns the value of start time (base::TimeTicks::ToInternalValue()) of
        the ARC instance if exists, otherwise an error will be returned
        accordingly i.e. ARC is not available on the platform or ARC is not
        started.
    -->
    <method name="GetArcStartTimeTicks">
      <arg type="x" name="start_time" direction="out" />
    </method>

    <!--
        EnableAdbSideload:

        Attempts to enable adb sideloading capability in ARC. This requires the
        device to have no user logged in since the last reboot. Note that there
        is no method to disable this capability because it will require a
        powerwash.
    -->
    <method name="EnableAdbSideload">
      <annotation name="org.chromium.DBus.Method.Kind" value="async" />
      <arg type="b" name="reply" direction="out" />
    </method>

    <!--
        QueryAdbSideload:

        Returns true if adb sideloading capability has been enabled in ARC,
        otherwise returns false.
    -->
    <method name="QueryAdbSideload">
      <annotation name="org.chromium.DBus.Method.Kind" value="async" />
      <arg type="b" name="reply" direction="out" />
    </method>
  </interface>
  <!-- ********************************************************************* -->
</node>