1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 2005-2007 Till Adam <adam@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KACL_H
9#define KACL_H
10
11#include "kiocore_export.h"
12#include <qplatformdefs.h>
13
14#include <QList>
15#include <QPair>
16
17#include <memory>
18
19typedef QPair<QString, unsigned short> ACLUserPermissions;
20typedef QList<ACLUserPermissions> ACLUserPermissionsList;
21typedef QList<ACLUserPermissions>::iterator ACLUserPermissionsIterator;
22typedef QList<ACLUserPermissions>::const_iterator ACLUserPermissionsConstIterator;
23
24typedef QPair<QString, unsigned short> ACLGroupPermissions;
25typedef QList<ACLGroupPermissions> ACLGroupPermissionsList;
26typedef QList<ACLGroupPermissions>::iterator ACLGroupPermissionsIterator;
27typedef QList<ACLGroupPermissions>::const_iterator ACLGroupPermissionsConstIterator;
28
29/*!
30 * \class KACL
31 * \inmodule KIOCore
32 *
33 * \brief a POSIX ACL encapsulation.
34 *
35 * The KACL class encapsulates a POSIX Access Control List. It follows the
36 * little standard that couldn't, 1003.1e/1003.2c, which died in draft status.
37 */
38class KIOCORE_EXPORT KACL
39{
40public:
41 /*!
42 * Creates a new KACL from \a aclString. If the string is a valid acl
43 * string, isValid() will afterwards return true.
44 */
45 KACL(const QString &aclString);
46
47 /*! Copy ctor */
48 KACL(const KACL &rhs);
49
50 /*!
51 * Creates a new KACL from the basic permissions passed in \a basicPermissions.
52 * isValid() will return true, afterwards.
53 */
54 KACL(mode_t basicPermissions);
55
56 /*!
57 * Creates an empty KACL. Until a valid acl string is set via setACL,
58 * isValid() will return false.
59 */
60 KACL();
61
62 virtual ~KACL();
63
64 KACL &operator=(const KACL &rhs);
65
66 bool operator==(const KACL &rhs) const;
67
68 bool operator!=(const KACL &rhs) const;
69
70 /*!
71 * Returns whether the KACL object represents a valid acl.
72 */
73 bool isValid() const;
74
75 /* The standard (non-extended) part of an ACL. These map directly to
76 * standard unix file permissions. Setting them will never make a valid
77 * ACL invalid. */
78
79 /*! Returns the owner's permissions entry */
80 unsigned short ownerPermissions() const;
81
82 /*! Set the owner's permissions entry.
83 * Returns success or failure */
84 bool setOwnerPermissions(unsigned short);
85
86 /*! Returns the owning group's permissions entry */
87 unsigned short owningGroupPermissions() const;
88
89 /*! Set the owning group's permissions entry.
90 * Returns success or failure */
91 bool setOwningGroupPermissions(unsigned short);
92
93 /*! Returns the permissions entry for others */
94 unsigned short othersPermissions() const;
95
96 /*! Set the permissions entry for others.
97 * Returns success or failure */
98 bool setOthersPermissions(unsigned short);
99
100 /*! Returns the basic (owner/group/others) part of the ACL as a mode_t */
101 mode_t basePermissions() const;
102
103 /* The interface to the extended ACL. This is a mask, permissions for
104 * n named users and permissions for m named groups. */
105
106 /*!
107 * Return whether the ACL contains extended entries or can be expressed
108 * using only basic file permissions.
109 */
110 bool isExtended() const;
111
112 /*!
113 * Return the entry for the permissions mask if there is one and sets
114 * \a exists to true. If there is no such entry, \a exists is set to false.
115 * Returns the permissions mask entry */
116 unsigned short maskPermissions(bool &exists) const;
117
118 /*! Set the permissions mask for the ACL. Permissions set for individual
119 * entries will be masked with this, such that their effective permissions
120 * are the result of the logical and of their entry and the mask.
121 * Returns success or failure */
122 bool setMaskPermissions(unsigned short);
123
124 /*!
125 * Access to the permissions entry for a named user, if such an entry
126 * exists. If \a exists is non-null, the boolean variable it points to
127 * is set to true if a matching entry exists and to false otherwise.
128 * Returns the permissions for a user entry with the name in \a name */
129 unsigned short namedUserPermissions(const QString &name, bool *exists) const;
130
131 /*! Set the permissions for a user with the name \a name. Will fail
132 * if the user doesn't exist, in which case the ACL will be unchanged.
133 * Returns success or failure. */
134 bool setNamedUserPermissions(const QString &name, unsigned short);
135
136 /*! Returns the list of all group permission entries. Each entry consists
137 * of a name/permissions pair. This is a QPair, therefore access is provided
138 * via the .first and .next members.
139 * Returns the list of all group permission entries. */
140 ACLUserPermissionsList allUserPermissions() const;
141
142 /*! Replace the list of all user permissions with \a list. If one
143 * of the entries in the list does not exists, or setting of the ACL
144 * entry fails for any reason, the ACL will be left unchanged.
145 * Returns success or failure */
146 bool setAllUserPermissions(const ACLUserPermissionsList &list);
147
148 /*!
149 * Access to the permissions entry for a named group, if such an entry
150 * exists. If \a exists is non-null, the boolean variable it points to is
151 * set to true if a matching entry exists and to false otherwise.
152 * Returns the permissions for a group with the name in \a name */
153 unsigned short namedGroupPermissions(const QString &name, bool *exists) const;
154
155 /*! Set the permissions for a group with the name \a name. Will fail
156 * if the group doesn't exist, in which case the ACL be unchanged.
157 * Returns success or failure. */
158 bool setNamedGroupPermissions(const QString &name, unsigned short);
159
160 /*! Returns the list of all group permission entries. Each entry consists
161 * of a name/permissions pair. This is a QPair, therefore access is provided
162 * via the .first and .next members.
163 * Returns the list of all group permission entries. */
164 ACLGroupPermissionsList allGroupPermissions() const;
165
166 /*! Replace the list of all user permissions with \a list. If one
167 * of the entries in the list does not exists, or setting of the ACL
168 * entry fails for any reason, the ACL will be left unchanged.
169 * Returns success or failure */
170 bool setAllGroupPermissions(const ACLGroupPermissionsList &list);
171
172 /*! Sets the whole list from a string. If the string in \a aclStr represents
173 * a valid ACL, it will be set, otherwise the ACL remains unchanged.
174 * Returns whether setting the ACL was successful. */
175 bool setACL(const QString &aclStr);
176
177 /*! Return a string representation of the ACL.
178 * Returns a string version of the ACL in the format compatible with libacl and
179 * POSIX 1003.1e. Implementations conforming to that standard should be able
180 * to take such strings as input. */
181 QString asString() const;
182
183protected:
184 virtual void virtual_hook(int id, void *data);
185
186private:
187 class KACLPrivate;
188 std::unique_ptr<KACLPrivate> const d;
189 KIOCORE_EXPORT friend QDataStream &operator<<(QDataStream &s, const KACL &a);
190 KIOCORE_EXPORT friend QDataStream &operator>>(QDataStream &s, KACL &a);
191};
192
193KIOCORE_EXPORT QDataStream &operator<<(QDataStream &s, const KACL &a);
194KIOCORE_EXPORT QDataStream &operator>>(QDataStream &s, KACL &a);
195
196#endif
197

source code of kio/src/core/kacl.h