/* * This file is part of the Polkit-tqt project * Copyright (C) 2009 Daniel Nicoletti * Copyright (C) 2009 Dario Freddi * Copyright (C) 2009 Jaroslav Reznik * Copyright (C) 2009 Radek Novacek * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library General Public * License as published by the Free Software Foundation; either * version 2 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public License * along with this library; see the file COPYING.LIB. If not, write to * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, * Boston, MA 02110-1301, USA. */ #ifndef POLKIT_TQT_AUTHORITY_H #define POLKIT_TQT_AUTHORITY_H #include "polkit-tqt-export.h" #include "polkit-tqt-identity.h" #include "polkit-tqt-subject.h" #include "polkit-tqt-temporaryauthorization.h" #include "polkit-tqt-actiondescription.h" #include "tqobject.h" typedef struct _PolkitAuthority PolkitAuthority; class TQString; /** * \namespace PolkitTQt PolkitTQt * * \brief Namespace wrapping Polkit-TQt classes * * This namespace wraps all Polkit-TQt classes. */ namespace PolkitTQt { /** * \class Authority polkit-tqt-authority.h Authority * \author Daniel Nicoletti * \author Dario Freddi * \author Jaroslav Reznik * * \brief Convenience class for TQt/TDE applications * * This class is a singleton that makes easy the usage * of PolKitAuthority. It emits configChanged() * whenever PolicyKit files change (e.g. the PolicyKit.conf * or .policy files) or when ConsoleKit reports activities changes. * * \note This class is a singleton, its constructor is private. * Call Authority::instance() to get an instance of the Authority object. * Do not delete Authority::instance(), cleanup will be done automatically. */ class POLKIT_TQT_EXPORT Authority : public TQObject { Q_OBJECT public: enum Result { /** Result unknown */ Unknown = 0x00, /** The subject is authorized for the specified action */ Yes = 0x01, /** The subject is not authorized for the specified action */ No = 0x02, /** The subject is authorized if more information is provided */ Challenge = 0x03 }; enum AuthorizationFlags { /** No flags set **/ None = 0x00, /** If the subject can obtain the authorization through authentication, * and an authentication agent is available, then attempt to do so. * * Note, this means that the method used for checking authorization is likely * to block for a long time. **/ AllowUserInteraction = 0x01 }; /** Error codes for the authority class */ enum ErrorCode { /** No error occurred **/ E_None = 0x00, /** Authority cannot be obtained **/ E_GetAuthority = 0x01, /** Authority check failed **/ E_CheckFailed = 0x02, /** Wrong or empty subject was given **/ E_WrongSubject = 0x03, /** Action returned unknown result **/ E_UnknownResult = 0x04, /** Enumerating actions failed **/ E_EnumFailed = 0x05, /** Registration of authentication agent failed **/ E_RegisterFailed = 0x06, /** Unregistration of authentication agent failed **/ E_UnregisterFailed = 0x07, /** Cookie or polkit-tqt-identity.handled to the action is empty **/ E_CookieOrIdentityEmpty = 0x08, /** Response of auth agent failed **/ E_AgentResponseFailed = 0x09, /** Revoke temporary authorizations failed **/ E_RevokeFailed = 0x0A }; /** * \brief Returns the instance of Authority * * Returns the current instance of Authority. Call this function whenever * you need to access the Authority class. * * \note Authority is a singleton. Memory is handled by polkit-tqt, so you just * need to call this function to get a working instance of Authority. * Don't delete the object after having used it. * * \param authority use this if you want to set an explicit PolkitAuthority. If you * don't know what this implies, simply ignore the parameter. In case * you want to use it, be sure of streaming it the first time you call * this function, otherwise it will have no effect. * * \return The current authority instance */ static Authority* instance(PolkitAuthority *authority = nullptr); ~Authority(); /** * You should always call this method after every action. No action will be allowed * if the object is in error state. Use clearError() to clear the error message. * * \see lastError * \see clearError * * \return \c true if an error occurred, \c false if the library is ready */ bool hasError() const; /** * \return the code of last error */ ErrorCode lastError() const; /** * Get detail information about error that occurred. * * \return detail message */ const TQString errorDetails() const; /** * Use this method to clear the error message. */ void clearError(); /** * Returns the current instance of PolkitAuthority. If you are handling * it through Polkit-tqt (which is quite likely, since you are calling * this function), DO NOT use any PolicyKit API's specific method that * modifies the instance on it, unless you're completely aware of what you're doing and * of the possible consequencies. Use this instance only to gather information. * * \return the current PolkitAuthority instance */ PolkitAuthority* polkitAuthority() const; /** * This function should be used by mechanisms (e.g.: helper applications). * It returns the action should be carried out, so if the caller was * actually authorized to perform it. The result is in form of a Result, so that * you can have more control over the whole process, and detect an eventual error. * Most of the times you simply want to check if the result is == to \c Result::Yes, * if you don't have specific needs. * * It is CRITICAL that you call this function * and check what it returns before doing anything in your helper, since otherwise * you could be actually performing an action from an unknown or unauthorized caller. * * When operation is finished, signal checkAuthorizationFinish is emitted * with result of authorization check in its parameter. * * \see checkAuthorizationSync Synchronous version of this method. * \see checkAuthorizationFinished Signal that is emitted when this method finishes. * \see checkAuthorizationCancel Use it to cancel execution of this method. * * \param actionId the Id of the action in question * \param subject subject that the action is authorized for (e.g. unix process) * \param flags flags that influences the authorization checking * * \return \c Result::Yes if the caller is authorized and the action should be performed * \c otherwise if the caller was not authorized and the action should not be performed, * or an error has occurred * */ void checkAuthorization(const TQString &actionId, const Subject &subject, AuthorizationFlags flags); /** * Synchronous version of the checkAuthorization method. * * \param actionId the Id of the action in question * \param subject subject that the action is authorized for (e.g. unix process) * \param flags flags that influences the authorization checking * * \see checkAuthorization Asynchronous version of this method. */ Result checkAuthorizationSync(const TQString &actionId, const Subject &subject, AuthorizationFlags flags); /** * This method can be used to cancel last authorization check. */ void checkAuthorizationCancel(); /** * Asynchronously retrieves all registered actions. * * When operation is finished, signal checkAuthorizationFinish is emitted * with result of authorization check in its parameter. * * \see enumerateActionsSync Synchronous version of this method. * \see enumerateActionsFinished Signal that is emitted when this method finishes. * \see enumerateActionsCancel Use it to cancel execution of this method. */ void enumerateActions(); /** * Synchronously retrieves all registered actions. * * \see enumerateActions Asynchronous version of this method. * * \return a list of Action IDs */ ActionDescription::List enumerateActionsSync(); /** * This method can be used to cancel enumeration of actions */ void enumerateActionsCancel(); /** * Registers an authentication agent. * * \see registerAuthenticationAgentSync Synchronous version of this method. * \see registerAuthenticationAgentFinished Signal that is emitted when this method finishes. * \see registerAuthenticationAgentCancel Use it to cancel execution of this method. * * \param subject caller subject * \param locale the locale of the authentication agent * \param objectPath the object path for the authentication agent */ void registerAuthenticationAgent(const Subject &subject, const TQString &locale, const TQString &objectPath); /** * Registers an authentication agent. * * \see registerAuthenticationAgent Asynchronous version of this method. * * \param subject caller subject * \param locale the locale of the authentication agent * \param objectPath the object path for the authentication agent * * \return \c true if the Authentication agent has been successfully registered * \c false if the Authentication agent registration failed */ bool registerAuthenticationAgentSync(const Subject &subject, const TQString &locale, const TQString &objectPath); /** * This method can be used to cancel the registration of the authentication agent. */ void registerAuthenticationAgentCancel(); /** * Unregisters an Authentication agent. * * \see unregisterAuthenticationAgentSync Synchronous version of this method. * \see unregisterAuthenticationAgentFinished Signal that is emitted when this method finishes. * \see unregisterAuthenticationAgentCancel Use it to cancel execution of this method. * * \param subject caller subject * \param objectPath the object path for the Authentication agent * * \return \c true if the Authentication agent has been successfully unregistered * \c false if the Authentication agent unregistration failed */ void unregisterAuthenticationAgent(const Subject &subject, const TQString &objectPath); /** * Unregisters an Authentication agent. * * \see unregisterAuthenticationAgent Asynchronous version of this method. * * \param subject caller subject * \param objectPath the object path for the Authentication agent * * \return \c true if the Authentication agent has been successfully unregistered * \c false if the Authentication agent unregistration failed */ bool unregisterAuthenticationAgentSync(const Subject &subject, const TQString &objectPath); /** * This method can be used to cancel the unregistration of the authentication agent. */ void unregisterAuthenticationAgentCancel(); /** * Provide response that \p identity successfully authenticated for the authentication * request identified by \p cookie. * * \see authenticationAgentResponseSync Synchronous version of this method. * \see authenticationAgentResponseFinished Signal that is emitted when this method finishes. * \see authenticationAgentResponseCancel Use it to cancel execution of this method. * * \param cookie The cookie passed to the authentication agent from the authority. * \param identity The identity that was authenticated. */ void authenticationAgentResponse(const TQString &cookie, const Identity &identity); /** * Provide response that \p identity successfully authenticated for the authentication * request identified by \p cookie. * * \see authenticationAgentResponse Asynchronous version of this method. * * \param cookie The cookie passed to the authentication agent from the authority. * \param identity The identity that was authenticated. * * \return \c true if authority acknowledged the call, \c false if error is set. * */ bool authenticationAgentResponseSync(const TQString &cookie, const Identity &identity); /** * This method can be used to cancel the authenticationAgentResponseAsync method. */ void authenticationAgentResponseCancel(); /** * Retrieves all temporary action that applies to \p subject. * * \see enumerateTemporaryAuthorizationsSync Synchronous version of this method. * \see enumerateTemporaryAuthorizationsFinished Signal that is emitted when this method finishes. * \see enumerateTemporaryAuthorizationsCancel Use it to cancel execution of this method. * * \param subject the subject to get temporary authorizations for * */ void enumerateTemporaryAuthorizations(const Subject &subject); /** * Retrieves all temporary action that applies to \p subject * * \see enumerateTemporaryAuthorizations Asynchronous version of this method. * * \param subject the subject to get temporary authorizations for * * \note Free all TemporaryAuthorization objects using \p delete operator. * * \return List of all temporary authorizations */ TemporaryAuthorization::List enumerateTemporaryAuthorizationsSync(const Subject &subject); /** * This method can be used to cancel the enumerateTemporaryAuthorizationsAsync method. */ void enumerateTemporaryAuthorizationsCancel(); /** * Revokes all temporary authorizations that applies to \p subject * * \see revokeTemporaryAuthorizationsSync Synchronous version of this method. * \see revokeTemporaryAuthorizationsFinished Signal that is emitted when this method finishes. * \see revokeTemporaryAuthorizationsCancel Use it to cancel execution of this method. * \param subject the subject to revoke temporary authorizations from */ void revokeTemporaryAuthorizations(const Subject &subject); /** * Revokes all temporary authorizations that applies to \p subject * * \see revokeTemporaryAuthorizations Asynchronous version of this method. * * \param subject the subject to revoke temporary authorizations from * * \return \c true if all temporary authorization were revoked * \c false if the revoking failed */ bool revokeTemporaryAuthorizationsSync(const Subject &subject); /** * This method can be used to cancel the method revokeTemporaryAuthorizationsAsync. */ void revokeTemporaryAuthorizationsCancel(); /** * Revokes temporary authorization by \p id * * \see revokeTemporaryAuthorizationSync Synchronous version of this method. * \see revokeTemporaryAuthorizationFinished Signal that is emitted when this method finishes. * \see revokeTemporaryAuthorizationCancel Use it to cancel execution of this method. * * \param id the identifier of the temporary authorization */ void revokeTemporaryAuthorization(const TQString &id); /** * Revokes temporary authorization by \p id * * \see revokeTemporaryAuthorization Asynchronous version of this method. * * \param id the identifier of the temporary authorization * * \return \c true if the temporary authorization was revoked * \c false if the revoking failed */ bool revokeTemporaryAuthorizationSync(const TQString &id); /** * This method can be used to cancel the method revokeTemporaryAuthorizationAsync. */ void revokeTemporaryAuthorizationCancel(); signals: /** * This signal will be emitted when a configuration * file gets changed (e.g. /etc/PolicyKit/PolicyKit.conf or .policy files). * Connect to this signal if you want to track down actions. */ void configChanged(); /** * This signal is emitted when asynchronous method checkAuthorization finishes. * * The argument is the result of authorization. */ void checkAuthorizationFinished(Result); /** * This signal is emitted when asynchronous method enumerateActions finishes. * * The argument is the list of all Action IDs. */ void enumerateActionsFinished(ActionDescription::List); /** * This signal is emitted when asynchronous method registerAuthenticationAgent finishes. * * The argument is \c true if the Authentication agent has been successfully registered * \c false if the Authentication agent registration failed */ void registerAuthenticationAgentFinished(bool); /** * This signal is emitted when asynchronous method unregisterAuthenticationAgent finishes. * * The argument is \c true if the Authentication agent has been successfully unregistered * \c false if the Authentication agent unregistration failed */ void unregisterAuthenticationAgentFinished(bool); /** * This signal is emitted when asynchronous method authenticationAgentResponse finishes. * * The argument is \c true if authority acknowledged the call, \c false if error is set. */ void authenticationAgentResponseFinished(bool); /** * This signal is emitted when asynchronous method enumerateTemporaryAuthorizations finishes. * * The argument is list of all temporary authorizations. * * \note Free all TemporaryAuthorization objects using \p delete operator. */ void enumerateTemporaryAuthorizationsFinished(TemporaryAuthorization::List); /** * This signal is emitted when asynchronous method revokeTemporaryAuthorizations finishes. * * The argument is \c true if all temporary authorizations were revoked * \c false if the revoking failed */ void revokeTemporaryAuthorizationsFinished(bool); /** * This signal is emitted when asynchronous method revokeTemporaryAuthorization finishes. * \return \c true if the temporary authorization was revoked * \c false if the revoking failed */ void revokeTemporaryAuthorizationFinished(bool); private: // Disable copy Authority(const Authority&); Authority& operator=(const Authority&); Authority(TQObject *parent = nullptr); static Authority *m_theAuthority; class Private; Private *const d; }; } #endif