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