Editing the documentation for consistency
[accounts-sso:vitalyrepins-signon.git] / lib / signond / SignOn / abstract-key-manager.h
1 /*
2  * This file is part of signon
3  *
4  * Copyright (C) 2010 Nokia Corporation.
5  *
6  * Contact: Alberto Mardegan <alberto.mardegan@nokia.com>
7  *
8  * This library is free software; you can redistribute it and/or
9  * modify it under the terms of the GNU Lesser General Public License
10  * version 2.1 as published by the Free Software Foundation.
11  *
12  * This library is distributed in the hope that it will be useful, but
13  * WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with this library; if not, write to the Free Software
19  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
20  * 02110-1301 USA
21  */
22 /*!
23  * @copyright Copyright (C) 2009-2011 Nokia Corporation.
24  * @license LGPL
25  */
26
27 #ifndef SIGNON_ABSTRACT_KEY_MANAGER_H
28 #define SIGNON_ABSTRACT_KEY_MANAGER_H
29
30 #include <SignOn/extension-interface.h>
31
32 #include <QObject>
33 #include <QString>
34
35 namespace SignOn {
36
37 typedef QByteArray Key;
38
39 /*!
40  * @class AbstractKeyManager
41  * @brief Base class for KeyManager implementations.
42  *
43  * The AbstractKeyManager is the base class for implementing signond key
44  * managers. A key manager is an object which signond uses to get the keys
45  * needed to access the encrypted storage. It emits signals whenever new keys
46  * exist, when keys are disabled or removed. For example, a simple password
47  * based key manager would:
48  * @li query the user for the password when queryKeys() is called.
49  * @li emit keyInserted() whenever the user enters the password.
50  * @li if the password automatically expires after some time, emit keyDisabled
51  * @li if the user changes the password, emit keyInserted() with the new
52  * passord, and keyRemoved() for the old one.
53  */
54 class AbstractKeyManager: public QObject
55 {
56     Q_OBJECT
57
58 public:
59     /*!
60      * Constructor
61      */
62     explicit AbstractKeyManager(QObject *parent = 0);
63         
64     /*!
65      * Destructor
66      */
67     virtual ~AbstractKeyManager();
68
69     /*!
70      * This method initializes the key manager. Implementations can start
71      * emitting signals during this method's execution.
72      */
73     virtual void setup() = 0;
74
75     /*!
76      * Signond calls this method if a key (typically a new key emitted with
77      * the keyInserted() signal) needs to be authorized. Authorizing a key
78      * means allowing the key to be used to mount the secure storage. The base
79      * implementation of this method just emits the keyAuthorized() signal
80      * denying the authorization, but specific implementations could delegate
81      * the authorization to the user.
82      * @param key The key that needs authorization
83      * @param message An optional message that might be shown to the user.
84      */
85     virtual void authorizeKey(const Key &key,
86                               const QString &message = QString::null);
87
88     /*!
89      * Signond calls this method when there are no active keys. This might
90      * happen when signond is just starting, or when all existing keys have
91      * been disabled (which would cause the secure storage to be unmounted).
92      * The key manager <em>must</em> emit keyInserted() in response to this
93      * call, either with a valid key or with an empty one.
94      */
95     virtual void queryKeys();
96
97     /*!
98      * Gets a description for the key.
99      * @param key The key whose name is to be returned
100      * @return A description or name that could be shown to the user to
101      * identify the key
102      */
103     virtual QString describeKey(const Key &key);
104
105 Q_SIGNALS:
106     /*!
107      * Emitted when a new key is available. If the key is not yet known to
108      * signond, signond will call authorizeKey on the key managers before
109      * accepting it.
110      * @param key The new key
111      */
112     void keyInserted(const SignOn::Key key);
113
114     /*!
115      * Emitted when a key is disabled. For instance, this signal can be
116      * emitted when a password expires or when a hardware key is removed.
117      * @param key The key which has been disabled
118      */
119     void keyDisabled(const SignOn::Key key);
120
121     /*!
122      * Emitted when a key is to be removed. This means that the key will never
123      * be used again to access the secure storage; if it will be inserted
124      * again, it will have to be re-authenticated.
125      * It is not necessary to emit keyDisabled() before keyRemoved(): the key
126      * will be disabled anyway when keyRemoved is emitted.
127      * @param key The key which has to be removed
128      */
129     void keyRemoved(const SignOn::Key key);
130
131     /*!
132      * The key manager emits this when it has decided whether to authorized
133      * the key. If more than one key manager is installed, signond will
134      * authorized the key as soon as the first key manager emits this signal
135      * with authorized set to true.
136      * @param key The key which underwent the authorization step
137      * @param authorized The result of the authorization
138      */
139     void keyAuthorized(const SignOn::Key key, bool authorized);
140 };
141
142 } // namespace
143
144 #endif // SIGNON_ABSTRACT_KEY_MANAGER_H
145