1 /*
2  * This file is part of signon
3  *
4  * Copyright (C) 2009-2010 Nokia Corporation.
5  * Copyright (C) 2012-2016 Canonical Ltd.
6  *
7  * Contact: Alberto Mardegan <alberto.mardegan@canonical.com>
8  *
9  * This library is free software; you can redistribute it and/or
10  * modify it under the terms of the GNU Lesser General Public License
11  * version 2.1 as published by the Free Software Foundation.
12  *
13  * This library is distributed in the hope that it will be useful, but
14  * WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16  * Lesser General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public
19  * License along with this library; if not, write to the Free Software
20  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
21  * 02110-1301 USA
22  */
23 /*!
24  * @copyright Copyright (C) 2009-2011 Nokia Corporation.
25  * @license LGPL
26  */
27 
28 #ifndef IDENTITY_H
29 #define IDENTITY_H
30 
31 #include <QObject>
32 #include <QByteArray>
33 #include <QMap>
34 #include <QString>
35 #include <QStringList>
36 #include <QVariant>
37 #include <QPointer>
38 
39 #include "libsignoncommon.h"
40 #include "authsession.h"
41 #include "identityinfo.h"
42 #include "signonerror.h"
43 
44 #define SSO_NEW_IDENTITY 0
45 
46 namespace SignOn {
47 
48 typedef QPointer<AuthSession> AuthSessionP;
49 
50 /*!
51  * @class Identity
52  * @headerfile identity.h SignOn/Identity
53  *
54  * Represents a database entry for a single identity.
55  * Identity is a client side presentation of a credential.
56  */
57 class SIGNON_EXPORT Identity: public QObject
58 {
59     Q_OBJECT
Q_DISABLE_COPY(Identity)60     Q_DISABLE_COPY(Identity)
61 
62     friend class IdentityImpl;
63 
64 public:
65     /*!
66      * @enum IdentityError
67      * Codes for errors that may be reported by Identity objects
68      * @deprecated This enum is deprecated. Replaced by Error::ErrorType.
69      */
70     enum IdentityError {
71         UnknownError = 1,               /**< Catch-all for errors not
72                                           distinguished by another code. */
73         InternalServerError = 2,        /**< Signon Daemon internal error. */
74         InternalCommunicationError = 3, /**< Communication with Signon Daemon
75                                           error . */
76         PermissionDeniedError = 4,      /**< The operation cannot be performed
77                                           due to insufficient client
78                                           permissions. */
79         IdentityErr = 200,              /* placeholder to rearrange
80                                           enumeration. */
81         MethodNotAvailableError,        /**< The requested mechanism is not
82                                           available. */
83         NotFoundError,                  /**< The identity matching this
84                                           Identity object was not found on the
85                                           service. */
86         StoreFailedError,               /**< Storing credentials failed. */
87         RemoveFailedError,              /**< Removing credentials failed. */
88         SignOutFailedError,             /**< SignOut failed. */
89         CanceledError,                  /**< Operation was canceled by user. */
90         CredentialsNotAvailableError    /**< Query fails*/
91     };
92 
93 protected:
94     /*!
95      * @internal
96      */
97     Identity(const quint32 id = SSO_NEW_IDENTITY,
98              QObject *parent = 0);
99 
100 public:
101     /*!
102      * Constructs a new identity object.
103      *
104      * Can return NULL if client is untrusted.
105      *
106      * @param info Identity information
107      * @param parent Parent object of the identity
108      * @return Pointer to new identity object or NULL if it fails to create.
109      */
110     static Identity *newIdentity(const IdentityInfo &info = IdentityInfo(),
111                                  QObject *parent = 0);
112 
113     /*!
114      * Constructs an identity object associated with an existing identity record.
115      *
116      * Can return NULL if client is untrusted.
117      *
118      * @param id Identity ID on the service
119      * @param parent Parent object of the identity
120      * @return Pointer to identity object or NULL if it fails to create.
121      */
122     static Identity *existingIdentity(const quint32 id, QObject *parent = 0);
123 
124     /*!
125      * Destructor
126      */
127     virtual ~Identity();
128 
129     /*!
130      * Unique id of given identity
131      *
132      * @return  Identity ID of the identity. For new identity which is not
133      * stored, NEW_IDENTITY is returned.
134      */
135     quint32 id() const;
136 
137     /*!
138      * Query list of available authentication methods for given identity.
139      * List is returned by emitting signal methodsAvailable().
140      * If the operation fails, a signal error() is emitted.
141      * @see Identity::error()
142      * If identity is not stored, Error::type() is
143      * Error::CredentialsNotAvailable, or
144      * Error::IdentityNotFound.
145      * @see methodsAvailable().
146      */
147     void queryAvailableMethods();
148 
149     /*!
150      * Creates a new session for authentication. This creates a connection
151      * to authentication plugin.
152      * The Identity object is parent and owner of all created authentication sessions.
153      *
154      * @param methodName Name of authentication method to use
155      * @return New authentication session or NULL if not able to create
156      */
157     AuthSessionP createSession(const QString &methodName);
158 
159     /*!
160      * Destroys an authentication session.
161      *
162      * @param session Session to be destroyed
163      */
164     void destroySession(const AuthSessionP &session);
165 
166     /*!
167      * Requests the user to give a new secret into database.
168      * Client can use requestCredentialsUpdate() to launch external
169      * dialog for asking new secret, that will be stored into database.
170      * On success, a signal credentialsStored() is emitted.
171      * If the operation fails, a signal error() is emitted.
172      * If storing changes fails, Error::type() is
173      * Error::StoreFailed,
174      * If user cancels dialog, Error::type() is
175      * Error::IdentityOperationCanceled.
176      *
177      * @see credentialsStored()
178      * @see Identity::error()
179      * @param message Message to be shown for the user
180      */
181     void requestCredentialsUpdate(const QString &message = QString());
182 
183     /*!
184      * Stores credential parameters for this authentication identity.
185      * IdentityInfo contains restrictions on methods and mechanisms
186      * for given Identity. @see IdentityInfo
187      * On success, a signal credentialsStored() is emitted.
188      * If the operation fails, a signal error() is emitted.
189      * If storing changes fails, Error::type() is
190      * Error::StoreFailed,
191      *
192      * Untrusted clients may be blocked from performing this operation,
193      * subject to the security framework restrictions.
194      *
195      * If default value is used for the parameter the Identity object
196      * stores the internally stored information, e.g. the IdentityInfo object
197      * used to create a new identity using Identity::newIdentity()
198      *
199      * @see credentialsStored()
200      * @see Identity::error()
201      * @param info Credentials to store
202      */
203     void storeCredentials(const IdentityInfo &info = IdentityInfo());
204 
205     /*!
206      * Removes this identity from database.
207      * On success, a signal removed() is emitted
208      * If the operation fails, a signal error() is emitted.
209      * If removing fails, Error::type() is
210      * Error::RemoveFailed,
211      *
212      * Untrusted clients may be blocked from performing this operation,
213      * subject to the security framework restrictions.
214      * @see removed()
215      * @see Identity::error()
216      */
217     void remove();
218 
219     /*!
220      * Adds the named reference to identity into the database.
221      * On success, a signal referenceAdded() is emitted
222      * If the operation fails, a signal error() is emitted.
223      * If referencing fails, Error::type() is
224      * Error::StoreFailed,
225      *
226      * Untrusted clients may be blocked from performing this operation,
227      * subject to the security framework restrictions.
228      * @see referenceAdded()
229      * @see Identity::error()
230      */
231     void addReference(const QString &reference = QString());
232 
233     /*!
234      * Removes a named reference to identity from the database.
235      * On success, a signal referenceRemoved() is emitted
236      * If the operation fails, a signal error() is emitted.
237      * If dereferencing fails, Error::type() is
238      * Error::ReferenceNotFound,
239      *
240      * Untrusted clients may be blocked from performing this operation,
241      * subject to the security framework restrictions.
242      * @see referenceRemoved()
243      * @see Identity::error()
244      */
245     void removeReference(const QString &reference = QString());
246 
247     /*!
248      * Query stored credential parameters for this authentication identity.
249      * On success, a signal info() is emitted with parameters
250      * in the service.
251      * If the operation fails, a signal error() is emitted.
252      * If query fails, Error::type() is
253      * Error::CredentialsNotAvailable,
254      *
255      * Untrusted clients may be blocked from performing this operation,
256      * subject to the security framework restrictions.
257      * @see info()
258      * @see Identity::error()
259      */
260     void queryInfo();
261 
262     /*!
263      * Gets a secret verification from the user and compares it to the stored
264      * secret.
265      * This launchs an external dialog for asking secret.
266      * When verification is completed, signal userVerified() is emitted.
267      * If the operation fails, a signal error() is emitted.
268      * If user selects "Forgot Password"-sequence, Error::type() is
269      * Error::ForgotPassword.
270      *
271      * @see userVerified()
272      * @see Identity::error()
273      * @param message Message to be shown for the user
274      */
275     void verifyUser(const QString &message = QString());
276 
277     /*!
278      * Gets a secret verification from the user and compares it to the stored
279      * secret.
280      * This launchs an external dialog for asking secret.
281      * When verification is completed, signal userVerified() is emitted.
282      * If the operation fails, a signal error() is emitted.
283      * If user selects "Forgot Password"-sequence, Error::type() is
284      * Error::ForgotPassword.
285      *
286      * @see userVerified()
287      * @see Identity::error()
288      * @param params Dialog customization parameters
289      */
290     void verifyUser(const QVariantMap &params);
291 
292     /*!
293      * Verifies if the given secret match the stored secret.
294      * When verification is completed, a signal secretVerified() is emitted.
295      * If the operation fails, a signal error() is emitted.
296      * If the credentials are not stored, Error::type() is
297      * Error::CredentialsNotAvailable.
298      *
299      * @see secretVerified()
300      * @see Identity::error()
301      * @param secret String to be verified
302      */
303     void verifySecret(const QString &secret);
304 
305      /*!
306      * Signs out Identity from all services. All authentication sessions using
307      * this Identity will be invalidated and all tokens cleared from cache.
308      * When sign out is completed, signal signedOut() is emitted.
309      * If the operation fails, a signal error() is emitted.
310      * If signout fails, Error::type() is
311      * Error::SignOutFailed.
312      *
313      * All clients using same identity will receive signedOut signal.
314      * @see signedOut()
315      * @see Identity::error()
316      */
317     void signOut();
318 
319 Q_SIGNALS:
320 
321     /*!
322      * Emitted when an error occurs while performing an operation.
323      * Typical error types are generic errors, where
324      * Error::type() < Error::AuthServiceErr and
325      * Identity specific, where
326      * Error::IdentityErr < Error::type() < Error::AuthServiceErr
327      * @see SignOn::Error.
328      * @see SignOn::Error::ErrorType
329      * @param err The error object.
330      */
331     void error(const SignOn::Error &err);
332 
333     /*!
334      * Emitted when the list of available mechanisms has been obtained
335      * for identity.
336      *
337      * @param methods List of available methods
338      */
339     void methodsAvailable(const QStringList &methods);
340 
341     /*!
342      * Emitted when credentials passed by storeCredentials() method
343      * have been successfully stored on the service.
344      * @param id Identifier of the credentials that has been stored
345      */
346     void credentialsStored(const quint32 id);
347 
348     /*!
349      * Emitted when references are added by addReference()
350      * method and change
351      * has been successfully stored on the service.
352      */
353     void referenceAdded();
354 
355     /*!
356      * Emitted when references are removed by removeReference()
357      * method and change
358      * has been successfully stored on the service.
359      */
360     void referenceRemoved();
361 
362     /*!
363      * Emitted when credentials passed by queryInfo() method
364      * @param info Credentials as have been stored on the service
365      */
366     void info(const SignOn::IdentityInfo &info);
367 
368     /*!
369      * Emitted when the user verification is completed.
370      * @param valid Is the given secret same as stored
371      */
372     void userVerified(const bool valid);
373 
374     /*!
375      * Emitted when secret verification is completed.
376      * @param valid Is the given secret same as stored
377      */
378     void secretVerified(const bool valid);
379 
380     /*!
381      * Emitted when the identity is signed out.
382      */
383     void signedOut();
384 
385     /*!
386      * Emitted when the identity is removed.
387      */
388     void removed();
389 
390 private:
391     class IdentityImpl *impl;
392 };
393 
394 }  // namespace SignOn
395 
396 #endif /* IDENTITY_H */
397