OSX/libsecurity_cdsa_client/lib/aclclient.h

   1 /*
   2  * Copyright (c) 2000-2001,2007,2011 Apple Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18
  19 //
  20 // aclclient
  21 //
  22 #ifndef _H_CDSA_CLIENT_ACLCLIENT
  23 #define _H_CDSA_CLIENT_ACLCLIENT  1
  24
  25 #include <security_cdsa_utilities/cssmaclpod.h>
  26 #include <security_cdsa_utilities/cssmacl.h>
  27 #include <security_cdsa_utilities/cssmcred.h>
  28 #include <security_utilities/refcount.h>
  29 #include <security_utilities/globalizer.h>
  30
  31 namespace Security {
  32 namespace CssmClient {
  33
  34 class CSP;
  35 class Key;
  36
  37 //
  38 // Any client-side object that has CSSM-layer ACLs shall be
  39 // derived from AclBearer and implement its methods accordingly.
  40 // Note the (shared/virtual) RefCount - you should handle AclBearer
  41 // references via RefPointers.
  42 // All the non-pure methods are implemented (in AclBearer) in terms of
  43 // the pure virtual methods; they just restate the problem in various ways.
  44 //
  45 class AclBearer : public virtual RefCount {
  46 public:
  47         virtual ~AclBearer();
  48
  49         // Acl manipulation
  50         virtual void getAcl(AutoAclEntryInfoList &aclInfos,
  51                 const char *selectionTag = NULL) const = 0;
  52         virtual void changeAcl(const CSSM_ACL_EDIT &aclEdit,
  53                 const CSSM_ACCESS_CREDENTIALS *cred = NULL) = 0;
  54
  55         void addAcl(const AclEntryInput &input, const CSSM_ACCESS_CREDENTIALS *cred = NULL);
  56         void changeAcl(CSSM_ACL_HANDLE handle, const AclEntryInput &input,
  57                 const CSSM_ACCESS_CREDENTIALS *cred = NULL);
  58         void deleteAcl(CSSM_ACL_HANDLE handle, const CSSM_ACCESS_CREDENTIALS *cred = NULL);
  59         void deleteAcl(const char *tag = NULL, const CSSM_ACCESS_CREDENTIALS *cred = NULL);
  60
  61         // Acl owner manipulation
  62         virtual void getOwner(AutoAclOwnerPrototype &owner) const = 0;
  63         virtual void changeOwner(const CSSM_ACL_OWNER_PROTOTYPE &newOwner,
  64                 const CSSM_ACCESS_CREDENTIALS *cred = NULL) = 0;
  65 };
  66
  67
  68 //
  69 // An AclBearer applied to a raw CSSM key
  70 //
  71 class KeyAclBearer : public AclBearer {
  72 public:
  73         KeyAclBearer(CSSM_CSP_HANDLE cspH, CSSM_KEY &theKey, Allocator &alloc)
  74                 : csp(cspH), key(theKey), allocator(alloc) { }
  75
  76         const CSSM_CSP_HANDLE csp;
  77         CSSM_KEY &key;
  78         Allocator &allocator;
  79
  80 protected:
  81         void getAcl(AutoAclEntryInfoList &aclInfos,
  82                 const char *selectionTag = NULL) const;
  83         void changeAcl(const CSSM_ACL_EDIT &aclEdit,
  84                 const CSSM_ACCESS_CREDENTIALS *cred = NULL);
  85         void getOwner(AutoAclOwnerPrototype &owner) const;
  86         void changeOwner(const CSSM_ACL_OWNER_PROTOTYPE &newOwner,
  87                 const CSSM_ACCESS_CREDENTIALS *cred = NULL);
  88 };
  89
  90
  91 //
  92 // An AclFactory helps create and maintain CSSM-layer AccessCredentials
  93 // and matching samples. There is state in an AclFactory, though simple
  94 // uses may not care about it.
  95 //
  96 class AclFactory {
  97 public:
  98         AclFactory();
  99         virtual ~AclFactory();
 100
 101         // these values are owned by the AclFactory and persist
 102         // until it is destroyed. You don't own the memory.
 103         const AccessCredentials *nullCred() const;                      // conforming empty
 104         const AccessCredentials *promptCred() const;            // enable interactive prompting
 105         const AccessCredentials *unlockCred() const;
 106         const AccessCredentials *cancelCred() const;
 107         const AccessCredentials *promptedPINCred() const;
 108         const AccessCredentials *promptedPINItemCred() const;
 109
 110         const AclOwnerPrototype &anyOwner() const;                      // wide-open owner
 111         const AclEntryInfo &anyAcl() const;                                     // wide-open ACL entry (authorizes anything)
 112
 113 protected:
 114         class KeychainCredentials {
 115         public:
 116                 KeychainCredentials(Allocator &alloc)
 117                         : allocator(alloc), mCredentials(new AutoCredentials(alloc)) { }
 118                 virtual ~KeychainCredentials();
 119
 120                 Allocator &allocator;
 121
 122         operator const AccessCredentials* () const { return mCredentials; }
 123         AccessCredentials* getAccessCredentials() const { return mCredentials; }
 124
 125     protected:
 126                 AutoCredentials *mCredentials;
 127         };
 128
 129 public:
 130     // create a self-managed AccessCredentials to explicitly provide a keychain passphrase
 131     class PassphraseUnlockCredentials : public KeychainCredentials {
 132     public:
 133         PassphraseUnlockCredentials (const CssmData& password, Allocator& allocator);
 134     };
 135
 136         // create a self-managed AccessCredentials to change a keychain passphrase
 137     class PasswordChangeCredentials : public KeychainCredentials {
 138     public:
 139         PasswordChangeCredentials (const CssmData& password, Allocator& allocator);
 140     };
 141
 142     // create an AccessCredentials to explicitly provide a keychain master key
 143     class MasterKeyUnlockCredentials : public KeychainCredentials {
 144     public:
 145         MasterKeyUnlockCredentials (const Key& key, Allocator& allocator);
 146     };
 147
 148 public:
 149         class AnyResourceContext : public ResourceControlContext {
 150         public:
 151                 AnyResourceContext(const CSSM_ACCESS_CREDENTIALS *cred = NULL);
 152
 153         private:
 154                 ListElement mAny;
 155                 CSSM_ACL_AUTHORIZATION_TAG mTag;
 156         };
 157
 158 public:
 159         //
 160         // Subject makers. Contents are chunk-allocated with the Allocator given
 161         //
 162         struct Subject : public TypedList {
 163                 Subject(Allocator &alloc, CSSM_ACL_SUBJECT_TYPE type);
 164         };
 165
 166         // an ANY subject, allocated dynamically for you
 167         struct AnySubject : public Subject {
 168                 AnySubject(Allocator &alloc) : Subject(alloc, CSSM_ACL_SUBJECT_TYPE_ANY) { }
 169         };
 170
 171         // a "nobody" subject (something guaranteed never to match)
 172         struct NobodySubject : public Subject {
 173                 NobodySubject(Allocator &alloc) : Subject(alloc, CSSM_ACL_SUBJECT_TYPE_COMMENT) { }
 174         };
 175
 176         // password subjects
 177         struct PWSubject : public Subject {
 178                 PWSubject(Allocator &alloc);                                                    // no secret
 179                 PWSubject(Allocator &alloc, const CssmData &secret);    // this secret
 180         };
 181
 182         struct PromptPWSubject : public Subject {
 183                 PromptPWSubject(Allocator &alloc, const CssmData &prompt);
 184                 PromptPWSubject(Allocator &alloc, const CssmData &prompt, const CssmData &secret);
 185         };
 186
 187         struct ProtectedPWSubject : public Subject {
 188                 ProtectedPWSubject(Allocator &alloc);
 189         };
 190
 191         // PIN (pre-auth) reference, origin side
 192         struct PinSubject : public Subject {
 193                 PinSubject(Allocator &alloc, uint32 slot);
 194         };
 195
 196         // PIN (pre-auth) source site
 197         struct PinSourceSubject : public Subject {
 198                 PinSourceSubject(Allocator &alloc, const TypedList &form);
 199         };
 200 };
 201
 202
 203 } // end namespace CssmClient
 204 } // end namespace Security
 205
 206 #endif // _H_CDSA_CLIENT_ACLCLIENT