1  /*
  2   *  ccaudit_extensions.h
  3   *  securityd
  4   *
  5   *  Created by G H on 3/24/09.
  6   *  Copyright (c) 2009 Apple Inc. All Rights Reserved.
  7   *
  8   *  Extensions to utility classes in Security::CommonCriteria 
  9   *  (libsecurity_utilities).  Not clear that these are useful enough to be
 10   *  added there, so for now, they're here.  
 11   */
 12  
 13  #include <string>
 14  #include <stdint.h>
 15  #include <Security/Authorization.h>
 16  #include <bsm/audit_kevents.h>      // AUE_NULL
 17  #include <bsm/libbsm.h>
 18  
 19  //
 20  // Regarding message formats in comments, below: 
 21  //
 22  //     <> denotes a string with the indicated information
 23  //     '' denotes a literal string
 24  // 
 25  // Message info is in text tokens unless otherwise indicated.  
 26  //
 27  
 28  namespace Security
 29  {
 30  
 31  namespace CommonCriteria
 32  {
 33  
 34  namespace Securityd 
 35  {
 36  
 37  //
 38  // Pure virtual class from which audit log writers should be derived.  
 39  // The assumption about logging is that a "success" case logs certain
 40  // data about what succeeded, while a "failure" case logs that same data
 41  // plus some indication as to why the failure occurred.  
 42  //
 43  // Subclasses minimally need to provide a writeCommon() method.  They may
 44  // override logSuccess(); q.v.  
 45  //
 46  // An AuditLogger is intended to live no longer than the audit trailer of a
 47  // securityd IPC.  
 48  //
 49  // setClientInfo() must be called before logging, or at best, gibberish
 50  // will be logged.  
 51  //
 52  // Nomenclature: 
 53  //     "write" methods only au_write()
 54  //     "log" methods open, write, and close the log
 55  //
 56  class AuditLogger
 57  {
 58  public:
 59      AuditLogger() : mAuditFd(-1), mEvent(AUE_NULL), mClientInfoSet(false)  { }
 60      AuditLogger(const audit_token_t *srcToken, short auEvent = AUE_NULL);
 61      AuditLogger(const AuditToken &srcToken, short auEvent = AUE_NULL);
 62      virtual ~AuditLogger();
 63      
 64      bool open();    // false if auditing disabled; throws on real errors
 65      void close(bool writeLog = true);   // throws if writeLog true but au_close() failed
 66      
 67      void setClientInfo(const audit_token_t *srcToken);
 68      void setClientInfo(const AuditToken &srcToken);
 69      void setEvent(short auEvent)  { mEvent = auEvent; }
 70      short event() const  { return mEvent; }
 71          
 72      // common log-writing activities
 73      void writeToken(token_t *token, const char *name);
 74      void writeSubject();
 75      void writeReturn(char status, int reterr);
 76      virtual void writeCommon() = 0; // should not open or close log
 77      
 78      // logSuccess() assumes that all the ancillary information you need is
 79      // written by writeCommon().  If that's not true, you can either
 80      // override logSuccess() in your subclass, or use a different method
 81      // altogether.  Do not call AuditLogger::logSuccess() from the subclass
 82      // in eiher case.  
 83      virtual void logSuccess();
 84  
 85      virtual void logFailure(const char *errMsg = NULL, int errcode = errAuthorizationDenied);
 86      virtual void logFailure(string &errMsg, int errcode = errAuthorizationDenied)  { logFailure(errMsg.c_str(), errcode); }
 87      
 88      // @@@  Extra credit: let callers add arbitrary tokens.  Tokens added
 89      // before a log*() call would be appended to the end of writeCommon()'s
 90      // standard set.  
 91  
 92  protected:
 93      void logInternalError(const char *fmt, ...);
 94      
 95  private:
 96      int mAuditFd;
 97      short mEvent;
 98      bool mClientInfoSet;    // disallow resetting client info
 99      
100      uid_t mAuditId;
101      uid_t mEuid;
102      gid_t mEgid;
103      uid_t mRuid;
104      gid_t mRgid;
105      pid_t mPid;
106      au_asid_t mAuditSessionId;
107      au_tid_t mOldTerminalId;    // to cache audit_token_to_au32() result
108      au_tid_addr_t mTerminalId;  // @@@  AuditInfo still uses ai_tid_t
109  };
110  
111  //
112  // KeychainAuthLogger format:
113  //     'System keychain authorization'
114  //     <keychain name>
115  //     <keychain item name>
116  //     [optional] <more failure info>
117  // 
118  // For QueryKeychainAuth audit logging
119  //
120  class KeychainAuthLogger : public AuditLogger
121  {
122      static const char *sysKCAuthStr;
123      static const char *unknownKCStr;
124      static const char *unknownItemStr;
125      
126  public:
127      KeychainAuthLogger() : AuditLogger(), mDatabase(unknownKCStr), mItem(unknownItemStr)  { }
128      KeychainAuthLogger(const audit_token_t *srcToken, short auEvent);
129      KeychainAuthLogger(const audit_token_t *srcToken, short auEvent, const char *database, const char *item);
130      KeychainAuthLogger(const AuditToken &srcToken, short auEvent);
131      KeychainAuthLogger(const AuditToken &srcToken, short auEvent, const char *database, const char *item);
132      void setDbName(const char *database);
133      void setItemName(const char *item);
134      virtual void writeCommon();
135      
136  private:
137      string mDatabase;
138      string mItem;
139  };
140  
141  // 
142  // RightLogger provides basic common data and behavior for rights-based
143  // logging classes.  @@@  "RightLogger" is a lousy name
144  //
145  class RightLogger
146  {
147  protected:
148      static const char *unknownRightStr;
149  
150  public:
151      RightLogger() : mRight(unknownRightStr)  { }
152      virtual ~RightLogger()  { }
153      
154      void setRight(const string &rightName);
155      void setRight(const char *rightName);
156  
157  protected:
158      string mRight;
159  };
160  
161  //
162  // Basic (per-mechanism) AuthMechLogger format:
163  //     <right name>
164  //     [optional] 'mechanism' <mechanism name>
165  //     [optional] <more info>
166  //
167  // e.g.:
168  //     com.foo.bar
169  //     mechanism FooPlugin:SomeMechanism
170  //     unknown mechanism; ending rule evaluation
171  //
172  class AuthMechLogger : public AuditLogger, public RightLogger
173  {
174      static const char *unknownMechStr;
175      static const char *mechStr;
176      
177  public:
178      AuthMechLogger() : AuditLogger(), RightLogger(), mEvaluatingMechanism(false), mCurrentMechanism(unknownMechStr)  { }
179      AuthMechLogger(const AuditToken &srcToken, short auEvent);
180      AuthMechLogger(const audit_token_t *srcToken, short auEvent);
181      
182      void setCurrentMechanism(const char *mech);    // pass NULL if not running mechs.  
183      void setCurrentMechanism(const string &mech)  { setCurrentMechanism(mech.c_str()); }
184      virtual void writeCommon();
185      
186      // Authorization mechanism-evaluation interrupts need to be logged since
187      // they cause evaluation to restart, possibly at a different point in the 
188      // mechanism chain.  
189      void logInterrupt(const char *msg);     // NULL msg okay
190      void logInterrupt(string &msg)  { logInterrupt(msg.c_str()); }
191      
192  private:
193      bool mEvaluatingMechanism;
194      string mCurrentMechanism;
195  };
196  
197  //
198  // Basic RightAuthenticationLogger formats:
199  //
200  // Per-credential (newly granted during an evaluation):
201  //     <right name>
202  //     UID of user performing the authentication [arg32 token]
203  //     UID and username of the successfully authenticated user [arg32 token]
204  // or:
205  //     <right name>
206  //     UID of user performing the authentication [arg32 token]
207  //     Name of the user as whom the first UID was attempting to authenticate
208  //
209  // Final (i.e., after all mechanisms) right-granting decision format:
210  //     <right name>
211  //     name of process requesting authorization
212  //     name of process that created the Authorization handle
213  //
214  // Least-privilege credential-generating event format:
215  //     <right name>
216  //     'least-privilege'
217  //
218  // @@@  each format should be its own class
219  // 
220  class RightAuthenticationLogger : public AuditLogger, public RightLogger
221  {
222      static const char *unknownUserStr;
223      static const char *unknownClientStr;
224      static const char *unknownAuthCreatorStr;
225      static const char *authenticatorStr;
226      static const char *clientStr;
227      static const char *authCreatorStr;
228      static const char *authenticatedAsStr;
229      static const char *leastPrivStr;
230  
231  public:
232      RightAuthenticationLogger() : AuditLogger(), RightLogger()  { }
233      RightAuthenticationLogger(const AuditToken &srcToken, short auEvent);
234      RightAuthenticationLogger(const audit_token_t *srcToken, short auEvent);
235      virtual ~RightAuthenticationLogger()  { }
236      
237      virtual void writeCommon();
238      
239      virtual void logSuccess()  { }  // throw?  in any case, don't allow the usual logSuccess() to work
240      // @@@  clean up, consolidate Success and AuthorizationResult
241      void logSuccess(uid_t authenticator, uid_t target, const char *targetName);
242      void logAuthorizationResult(const char *client, const char *authCreator, int errcode);
243      void logLeastPrivilege(uid_t userId, bool isAuthorizingUser);
244      virtual void logFailure(const char *errMsg, int errcode)  { AuditLogger::logFailure(errMsg, errcode); }
245      void logAuthenticatorFailure(uid_t authenticator, const char *targetName);
246  };
247  
248  
249  }   // namespace Securityd
250  
251  }   // namespace CommonCriteria
252      
253  }   // namespace Security