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 ¶ms); 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