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 kacl.h <KACL>
31 *
32 * The KACL class encapsulates a POSIX Access Control List. It follows the
33 * little standard that couldn't, 1003.1e/1003.2c, which died in draft status.
34 * @short a POSIX ACL encapsulation
35 * @author Till Adam <adam@kde.org>
36 */
37class KIOCORE_EXPORT KACL
38{
39public:
40 /**
41 * Creates a new KACL from @p aclString. If the string is a valid acl
42 * string, isValid() will afterwards return true.
43 */
44 KACL(const QString &aclString);
45
46 /** Copy ctor */
47 KACL(const KACL &rhs);
48
49 /**
50 * Creates a new KACL from the basic permissions passed in @p basicPermissions.
51 * isValid() will return true, afterwards.
52 */
53 KACL(mode_t basicPermissions);
54
55 /**
56 * Creates an empty KACL. Until a valid acl string is set via setACL,
57 * isValid() will return false.
58 */
59 KACL();
60
61 virtual ~KACL();
62
63 KACL &operator=(const KACL &rhs);
64
65 bool operator==(const KACL &rhs) const;
66
67 bool operator!=(const KACL &rhs) const;
68
69 /**
70 * Returns whether the KACL object represents a valid acl.
71 * @return 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 /** @return the owner's permissions entry */
80 unsigned short ownerPermissions() const;
81
82 /** Set the owner's permissions entry.
83 * @return success or failure */
84 bool setOwnerPermissions(unsigned short);
85
86 /** @return the owning group's permissions entry */
87 unsigned short owningGroupPermissions() const;
88
89 /** Set the owning group's permissions entry.
90 * @return success or failure */
91 bool setOwningGroupPermissions(unsigned short);
92
93 /** @return the permissions entry for others */
94 unsigned short othersPermissions() const;
95
96 /** Set the permissions entry for others.
97 * @return success or failure */
98 bool setOthersPermissions(unsigned short);
99
100 /** @return 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 * @return whether the ACL contains extended entries */
110 bool isExtended() const;
111
112 /**
113 * Return the entry for the permissions mask if there is one and sets
114 * @p exists to true. If there is no such entry, @p exists is set to false.
115 * @return 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 * @return 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 @p 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 * @return the permissions for a user entry with the name in @p name */
129 unsigned short namedUserPermissions(const QString &name, bool *exists) const;
130
131 /** Set the permissions for a user with the name @p name. Will fail
132 * if the user doesn't exist, in which case the ACL will be unchanged.
133 * @return 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 * @return the list of all group permission entries. */
140 ACLUserPermissionsList allUserPermissions() const;
141
142 /** Replace the list of all user permissions with @p 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 * @return 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 @p 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 * @return the permissions for a group with the name in @p name */
153 unsigned short namedGroupPermissions(const QString &name, bool *exists) const;
154
155 /** Set the permissions for a group with the name @p name. Will fail
156 * if the group doesn't exist, in which case the ACL be unchanged.
157 * @return 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 * @return the list of all group permission entries. */
164
165 ACLGroupPermissionsList allGroupPermissions() const;
166 /** Replace the list of all user permissions with @p 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 * @return success or failure */
170 bool setAllGroupPermissions(const ACLGroupPermissionsList &);
171
172 /** Sets the whole list from a string. If the string in @p aclStr represents
173 * a valid ACL, it will be set, otherwise the ACL remains unchanged.
174 * @return whether setting the ACL was successful. */
175 bool setACL(const QString &aclStr);
176
177 /** Return a string representation of the ACL.
178 * @return 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