SecurityServer/SecurityAgentClient.h

   1 /*
   2  * Copyright (c) 2000-2001 Apple Computer, 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 // SecurityAgentClient - client interface to SecurityAgent
  21 //
  22 #ifndef _H_SECURITYAGENTCLIENT
  23 #define _H_SECURITYAGENTCLIENT
  24
  25 #if defined(__cplusplus)
  26 #include <string>
  27 #include <Security/mach++.h>
  28 #include <Security/osxsigning.h>
  29 #include <Security/cssmacl.h>
  30 #include <Security/cssm.h>
  31 #include <Security/Authorization.h>
  32 #include <Security/AuthorizationPlugin.h>
  33 #include <Security/AuthorizationWalkers.h>
  34
  35 namespace Security {
  36
  37 using MachPlusPlus::Port;
  38     using MachPlusPlus::Bootstrap;
  39 using CodeSigning::OSXCode;
  40
  41
  42 namespace SecurityAgent {
  43
  44 #endif //C++ only
  45
  46 // Note: Following section also available to C code for inclusion
  47
  48 static const unsigned int maxPassphraseLength = 1024;
  49 static const unsigned int maxUsernameLength = 80;
  50
  51 //
  52 // Unified reason codes transmitted to SecurityAgent (and internationalized there)
  53 //
  54 enum Reason {
  55         noReason = 0,                   // no reason (not used, used as a NULL)
  56         unknownReason,                  // something else (catch-all internal error)
  57
  58         // reasons for asking for a new passphrase
  59         newDatabase = 11,               // need passphrase for a new database
  60         changePassphrase,               // changing passphrase for existing database
  61
  62         // reasons for retrying an unlock query
  63         invalidPassphrase = 21, // passphrase was wrong
  64
  65         // reasons for retrying a new passphrase query
  66         passphraseIsNull = 31,  // empty passphrase
  67         passphraseTooSimple,    // passphrase is not complex enough
  68         passphraseRepeated,             // passphrase was used before (must use new one)
  69         passphraseUnacceptable, // passphrase unacceptable for some other reason
  70
  71         // reasons for retrying an authorization query
  72         userNotInGroup = 41,    // authenticated user not in needed group
  73         unacceptableUser,               // authenticated user unacceptable for some other reason
  74
  75         // reasons for canceling a staged query
  76         tooManyTries = 61,              // too many failed attempts to get it right
  77         noLongerNeeded,                 // the queried item is no longer needed
  78         keychainAddFailed,              // the requested itemed couldn't be added to the keychain
  79         generalErrorCancel              // something went wrong so we have to give up now
  80 };
  81
  82 #if defined(__cplusplus)
  83
  84
  85 //
  86 // The client interface to the SecurityAgent.
  87 //
  88 class Client {
  89 public:
  90         Client();
  91     Client(uid_t clientUID, Bootstrap clientBootstrap);
  92         virtual ~Client();
  93
  94         virtual void activate(const char *bootstrapName = NULL);
  95         virtual void terminate();
  96         bool isActive() const { return mActive; }
  97
  98         bool keepAlive() const          { return mKeepAlive; }
  99         void keepAlive(bool ka)         { mKeepAlive = ka; }
 100
 101         // common stage termination calls
 102         void finishStagedQuery();
 103         void cancelStagedQuery(Reason reason);
 104
 105 public:
 106     struct KeychainBox {
 107         bool show;                              // show the "save in keychain" checkbox (in)
 108         bool setting;                   // value of the checkbox (in/out)
 109     };
 110
 111 public:
 112         // ask to unlock an existing database. Staged protocol
 113         void queryUnlockDatabase(const OSXCode *requestor, pid_t requestPid,
 114         const char *database, char passphrase[maxPassphraseLength]);
 115         void retryUnlockDatabase(Reason reason, char passphrase[maxPassphraseLength]);
 116
 117         // ask for a new passphrase for a database. Not yet staged
 118         void queryNewPassphrase(const OSXCode *requestor, pid_t requestPid,
 119         const char *database, Reason reason, char passphrase[maxPassphraseLength]);
 120         void retryNewPassphrase(Reason reason, char passphrase[maxPassphraseLength]);
 121
 122         // ask permission to use an item in a database
 123     struct KeychainChoice {
 124         bool allowAccess;                                               // user said "yes"
 125         bool continueGrantingToCaller;                  // user wants calling App added to ACL
 126                 char passphrase[maxPassphraseLength];   // only if requested
 127     };
 128     void queryKeychainAccess(const OSXCode *requestor, pid_t requestPid,
 129         const char *database, const char *itemName, AclAuthorization action,
 130                 bool needPassphrase, KeychainChoice &choice);
 131
 132     // generic old passphrase query
 133     void queryOldGenericPassphrase(const OSXCode *requestor, pid_t requestPid,
 134         const char *prompt,
 135         KeychainBox &addToKeychain, char passphrase[maxPassphraseLength]);
 136     void retryOldGenericPassphrase(Reason reason,
 137         bool &addToKeychain, char passphrase[maxPassphraseLength]);
 138
 139     // generic new passphrase query
 140     void queryNewGenericPassphrase(const OSXCode *requestor, pid_t requestPid,
 141         const char *prompt, Reason reason,
 142         KeychainBox &addToKeychain, char passphrase[maxPassphraseLength]);
 143     void retryNewGenericPassphrase(Reason reason,
 144         bool &addToKeychain, char passphrase[maxPassphraseLength]);
 145
 146         // authenticate a user for the purpose of authorization
 147         bool authorizationAuthenticate(const OSXCode *requestor, pid_t requestPid,
 148                 const char *neededGroup, const char *candidateUser,
 149                 char username[maxUsernameLength], char passphrase[maxPassphraseLength]);
 150         bool retryAuthorizationAuthenticate(Reason reason,
 151                 char username[maxUsernameLength], char passphrase[maxPassphraseLength]);
 152
 153     bool invokeMechanism(const string &inPluginId, const string &inMechanismId, const AuthorizationValueVector *inArguments, const AuthorizationItemSet *inHints, const AuthorizationItemSet *inContext, AuthorizationResult *outResult, AuthorizationItemSet *&outHintsPtr, AuthorizationItemSet *&outContextPtr);
 154
 155     void terminateAgent();
 156
 157         // Cancel a pending client call in another thread by sending a cancel message.
 158         // This call (only) may be made from another thread.
 159         void cancel();
 160
 161 private:
 162         // used by client call wrappers to receive IPC return-status
 163         OSStatus status;
 164
 165 private:
 166     Port mServerPort;
 167     Port mClientPort;
 168         bool mActive;
 169     uid_t desktopUid;
 170     gid_t desktopGid;
 171     bool mUsePBS;
 172     Bootstrap mClientBootstrap;
 173     mach_port_t pbsBootstrap;
 174         bool mKeepAlive;
 175
 176         enum Stage {
 177                 mainStage,                              // in between requests
 178                 unlockStage,                    // in unlock sub-protocol
 179                 newPassphraseStage,             // in get-new-passphrase sub-protocol
 180         newGenericPassphraseStage, // in get-new-generic-passphrase sub-protocol
 181         oldGenericPassphraseStage, // in get-old-generic-passphrase sub-protocol
 182                 authorizeStage,                 // in authorize-by-group-membership sub-protocol
 183        invokeMechanismStage   // in invoke mechanism sub-protocol
 184         } stage;
 185         Port mStagePort;
 186
 187         void setClientGroupID(const char *grpName = NULL);
 188         void locateDesktop();
 189     void establishServer(const char *name);
 190         void check(kern_return_t error);
 191         void unstage();
 192
 193 private:
 194         static const int cancelMessagePseudoID = 1200;
 195 };
 196
 197 }; // end namespace SecurityAgent
 198
 199 } // end namespace Security
 200
 201 #endif //C++ only
 202
 203 #endif //_H_SECURITYAGENTCLIENT