OSX/libsecurity_cdsa_utilities/lib/aclsubject.h

   1 /*
   2  * Copyright (c) 2000-2004,2006,2011,2013-2014 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24
  25 //
  26 // aclsubject - abstract ACL subject implementation
  27 //
  28 #ifndef _ACLSUBJECT
  29 #define _ACLSUBJECT
  30
  31 #include <security_cdsa_utilities/cssmaclpod.h>
  32 #include <security_cdsa_utilities/cssmcred.h>
  33 #include <security_utilities/refcount.h>
  34 #include <security_utilities/globalizer.h>
  35 #include <security_utilities/memutils.h>
  36 #include <security_utilities/adornments.h>
  37 #include <map>
  38 #include <set>
  39 #include <string>
  40 #include <limits.h>
  41
  42
  43 namespace Security {
  44
  45 class ObjectAcl;
  46 class AclValidationContext;
  47 class AclSubject;
  48
  49
  50 //
  51 // An AclValidationEnvironment can be subclassed to add context access to ACL subject
  52 // validation. If you use ACL subject classes that need context beyond the credential
  53 // structure itself, add that context to (a virtual subclass of) AclValidationContext, pass that
  54 // to ObjectAcl::validate() along with the credentials, and have the Subject implementation
  55 // access validationContext.environment().
  56 //
  57 class AclValidationEnvironment {
  58         friend class AclValidationContext;
  59 public:
  60     virtual ~AclValidationEnvironment();        // ensure virtual methods (need dynamic_cast)
  61
  62         // provide an Adornable for a given subject to store data in, or throw if none available (default)
  63         virtual Adornable &store(const AclSubject *subject);
  64
  65         // special-purpose bypass (force validation to succeed)
  66         bool forceSuccess = false;
  67 };
  68
  69
  70 //
  71 // An AclValidationContext holds all context for an ACL evaluation in one
  72 // package. It's designed to provide a uniform representation of credentials, plus
  73 // any (trusted path and/or implicit) context information useful for ACL validation.
  74 //
  75 // Contexts are immutable (constant) for validators; they do not change at all
  76 // during a validation exercise. Anything that should be mutable must go into
  77 // the environment (which is indirect and modifyable).
  78 //
  79 class AclValidationContext {
  80         friend class ObjectAcl;
  81 public:
  82     AclValidationContext(const AccessCredentials *cred,
  83         AclAuthorization auth, AclValidationEnvironment *env = NULL)
  84     : mAcl((ObjectAcl*) 0xDEADDEADDEADDEAD), mSubject((AclSubject*) 0xDEADDEADDEADDEAD), mCred(cred),
  85         mAuth(auth), mEnv(env), mEntryTag(NULL) { }
  86     AclValidationContext(const AclValidationContext &ctx)
  87     : mAcl(ctx.mAcl), mSubject(ctx.mSubject), mCred(ctx.mCred),
  88           mAuth(ctx.mAuth), mEnv(ctx.mEnv), mEntryTag(NULL) { }
  89         virtual ~AclValidationContext();
  90
  91     // access to (suitably focused) sample set
  92     virtual uint32 count() const = 0;   // number of samples
  93         uint32 size() const { return count(); } // alias
  94     virtual const TypedList &sample(uint32 n) const = 0;        // retrieve one sample
  95     const TypedList &operator [] (uint32 n) const { return sample(n); }
  96
  97     // context access
  98     AclAuthorization authorization() const      { return mAuth; }
  99         const AccessCredentials *cred() const   { return mCred; }
 100         AclValidationEnvironment *environment() const { return mEnv; }
 101     template <class Env> Env *environment() const { return dynamic_cast<Env *>(mEnv); }
 102         AclSubject *subject() const                             { return mSubject; }
 103         ObjectAcl *acl() const                                  { return mAcl; }
 104
 105         // tag manipulation
 106         virtual const char *credTag() const;
 107         virtual const char *entryTag() const;
 108         std::string s_credTag() const;
 109         void entryTag(const char *tag);
 110         void entryTag(const std::string &tag);
 111
 112         // selective match support - not currently implemented
 113         virtual void matched(const TypedList *match) const = 0;
 114         void matched(const TypedList &match) const { return matched(&match); }
 115
 116 private:
 117         void init(ObjectAcl *acl, AclSubject *subject);
 118
 119 private:
 120         ObjectAcl *mAcl;                                        // underlying ObjectAcl
 121         AclSubject *mSubject;                           // subject being validated
 122     const AccessCredentials *mCred;             // original credentials
 123     AclAuthorization mAuth;                             // action requested
 124     AclValidationEnvironment *mEnv;             // environmental context (if any)
 125         const char *mEntryTag;                          // entry tag
 126 };
 127
 128
 129 //
 130 // An AclValidationContext that simply presents all top-level credentials
 131 // to all subjects.
 132 //
 133 class BaseValidationContext : public AclValidationContext {
 134 public:
 135         BaseValidationContext(const AccessCredentials *cred,
 136                                                   AclAuthorization auth, AclValidationEnvironment *env)
 137         : AclValidationContext(cred, auth, env) { }
 138
 139         uint32 count() const    { return cred() ? cred()->samples().length() : 0; }
 140         uint32 size() const             { return count(); }
 141         const TypedList &sample(uint32 n) const
 142         { assert(n < count()); return cred()->samples()[n]; }
 143
 144         void matched(const TypedList *) const { }               // ignore match info
 145 };
 146
 147
 148 //
 149 // The AclSubject class models an ACL "subject" object. If you have a new ACL
 150 // subject type or variant, you make a subclass of this (plus a suitable Maker).
 151 //
 152 // Note that AclSubjects can contain both configuration and state information.
 153 // Configuration is set during AclSubject creation (passwords to check against,
 154 // evaluation options, etc.) and are typically passed on in the externalized form;
 155 // it is persistent.
 156 // On the other hand, state is volatile and is lost when the AclSubject dies.
 157 // This is stuff that accumulates during a particular lifetime, such as results
 158 // of previous evaluations (for caching or more nefarious purposes).
 159 // Be clear what each of your subclass members are, and document accordingly.
 160 //
 161 class AclSubject : public RefCount {
 162 public:
 163     typedef LowLevelMemoryUtilities::Writer Writer;
 164     typedef LowLevelMemoryUtilities::Reader Reader;
 165
 166         typedef uint8 Version;          // binary version marker
 167         static const int versionShift = 24;     // highest-order byte of type is version
 168         static const uint32 versionMask = 0xff000000;
 169
 170 public:
 171         explicit AclSubject(uint32 type, Version v = 0);
 172     virtual ~AclSubject();
 173     CSSM_ACL_SUBJECT_TYPE type() const { return mType; }
 174
 175         // validation (evaluation) primitive
 176     virtual bool validates(const AclValidationContext &ctx) const = 0;
 177
 178     // export to CSSM interface
 179     virtual CssmList toList(Allocator &alloc) const = 0;
 180
 181     // export/import for save/restore interface
 182     virtual void exportBlob(Writer::Counter &pub, Writer::Counter &priv);
 183     virtual void exportBlob(Writer &pub, Writer &priv);
 184     virtual void importBlob(Reader &pub, Reader &priv);
 185
 186         // binary compatibility version management. The version defaults to zero
 187         Version version() const { return mVersion; }
 188
 189         // forget any validation-related state you have acquired
 190         virtual void reset();
 191
 192         // debug suupport (dummied out but present for -UDEBUGDUMP)
 193         virtual void debugDump() const;
 194         IFDUMP(void dump(const char *title) const);
 195
 196 protected:
 197         void version(Version v) { mVersion = v; }
 198
 199 private:
 200     CSSM_ACL_SUBJECT_TYPE mType;
 201         Version mVersion;
 202
 203 public:
 204     class Maker {
 205     public:
 206         Maker(CSSM_ACL_SUBJECT_TYPE type);
 207                 virtual ~Maker();
 208
 209         uint32 type() const { return mType; }
 210         virtual AclSubject *make(const TypedList &list) const = 0;
 211         virtual AclSubject *make(Version version, Reader &pub, Reader &priv) const = 0;
 212
 213     protected:
 214         // list parsing helpers
 215         static void crack(const CssmList &list, uint32 count,
 216             ListElement **array = NULL, ...);
 217         static CSSM_WORDID_TYPE getWord(const ListElement &list,
 218             int min = 0, int max = INT_MAX);
 219
 220     private:
 221         CSSM_ACL_SUBJECT_TYPE mType;
 222     };
 223 };
 224
 225
 226 //
 227 // A SimpleAclSubject validates a credential by scanning its samples
 228 // one at a time, without any interactions between them. Thus its validate()
 229 // can be a lot simpler.
 230 // Note that this layer assumes that subject and sample types have the same
 231 // value, as is typical when both are derived from a WORDID.
 232 //
 233 class SimpleAclSubject : public AclSubject {
 234 public:
 235     SimpleAclSubject(CSSM_ACL_SUBJECT_TYPE type) : AclSubject(type) { }
 236
 237     virtual bool validates(const AclValidationContext &ctx) const;
 238     virtual bool validates(const AclValidationContext &baseCtx,
 239         const TypedList &sample) const = 0;
 240 };
 241
 242
 243 } // end namespace Security
 244
 245
 246 #endif //_ACLSUBJECT