shibsp/TransactionLog.h

   1 /**
   2  * Licensed to the University Corporation for Advanced Internet
   3  * Development, Inc. (UCAID) under one or more contributor license
   4  * agreements. See the NOTICE file distributed with this work for
   5  * additional information regarding copyright ownership.
   6  *
   7  * UCAID licenses this file to you under the Apache License,
   8  * Version 2.0 (the "License"); you may not use this file except
   9  * in compliance with the License. You may obtain a copy of the
  10  * License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing,
  15  * software distributed under the License is distributed on an
  16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
  17  * either express or implied. See the License for the specific
  18  * language governing permissions and limitations under the License.
  19  */
  20
  21 /**
  22  * @file shibsp/TransactionLog.h
  23  *
  24  * Formatted event record logging.
  25  */
  26
  27 #if !defined (__shibsp_txlog_h__) && !defined(SHIBSP_LITE)
  28 #define __shibsp_txlog_h__
  29
  30 #include <shibsp/base.h>
  31 #include <xmltooling/logging.h>
  32 #include <xmltooling/Lockable.h>
  33 #include <xmltooling/io/GenericRequest.h>
  34
  35 #include <map>
  36 #include <vector>
  37 #include <iostream>
  38 #include <boost/scoped_ptr.hpp>
  39
  40 namespace xmltooling {
  41     class XMLTOOL_API Mutex;
  42 };
  43
  44 namespace opensaml {
  45     namespace saml1 {
  46         class SAML_API AuthenticationStatement;
  47     };
  48
  49     namespace saml1p {
  50         class SAML_API Response;
  51     };
  52
  53     namespace saml2 {
  54         class SAML_API AuthnStatement;
  55         class SAML_API NameID;
  56     };
  57
  58     namespace saml2p {
  59         class SAML_API AuthnRequest;
  60         class SAML_API LogoutRequest;
  61         class SAML_API LogoutResponse;
  62         class SAML_API StatusResponseType;
  63     };
  64
  65     namespace saml2md {
  66         class SAML_API EntityDescriptor;
  67     };
  68 };
  69
  70 namespace shibsp {
  71     class SHIBSP_API Application;
  72     class SHIBSP_API Attribute;
  73     class SHIBSP_API Session;
  74
  75     /**
  76      * Interface to a synchronized event/audit logging object.
  77      *
  78      * <p>For backward compatibility, we expose a logging object directly, but
  79      * new applications should rely on the Event callback API.
  80      */
  81     class SHIBSP_API TransactionLog : public virtual xmltooling::Lockable
  82     {
  83         MAKE_NONCOPYABLE(TransactionLog);
  84     public:
  85         /**
  86          * Constructor.
  87          *
  88          * @param fmt       formatting string for events
  89          * @param absent    string to output when a field is empty
  90          */
  91         TransactionLog(const char* fmt=nullptr, const char* absent=nullptr);
  92
  93         virtual ~TransactionLog();
  94
  95         xmltooling::Lockable* lock();
  96         void unlock();
  97
  98         /** @deprecated Logging object. */
  99         xmltooling::logging::Category& log;
 100
 101         /**
 102          * Callback interface that outputs an event record to a stream using formatting tokens.
 103          */
 104         class SHIBSP_API Event {
 105             MAKE_NONCOPYABLE(Event);
 106         protected:
 107             /** Function that handles a formatting token. */
 108             typedef bool (*handler_fn)(const Event& e, std::ostream&);
 109
 110             /** Map of tokens to handlers. */
 111             std::map<std::string, handler_fn> m_handlers;
 112
 113             /**
 114              * Constructor.
 115              */
 116             Event();
 117
 118         public:
 119             virtual ~Event();
 120
 121             /**
 122              * Returns a type string to be used for the log category in the event log.
 123              *
 124              * @return  type or category for the event
 125              */
 126             virtual const char* getType() const=0;
 127
 128             /** Exception */
 129             const std::exception* m_exception;
 130
 131             /** Request object associated with event. */
 132             const xmltooling::GenericRequest* m_request;
 133
 134             /** Application object associated with event. */
 135             const Application* m_app;
 136
 137             /** Session identifier. */
 138             const char* m_sessionID;
 139
 140             /** Peer entity associated with event. */
 141             const opensaml::saml2md::EntityDescriptor* m_peer;
 142
 143             /** Protocol associated with event. */
 144             const char* m_protocol;
 145
 146             /** Protocol binding associated with event. */
 147             const char* m_binding;
 148
 149             /** SAML 2.0 NameID. */
 150             const opensaml::saml2::NameID* m_nameID;
 151
 152             /**
 153              * Outputs an event record to a stream based on the defined formatting string.
 154              *
 155              * @param out       stream to use
 156              * @param field     field to output
 157              * @param absent    string to output if the field is empty
 158              * @return  true iff the field was recognized and substituted
 159              */
 160             virtual bool write(std::ostream& out, const char* field, const char* absent) const;
 161         };
 162
 163         /**
 164          * Write a formatted event record to the log.
 165          * <p>This method is internally synchronized and the caller does <strong>NOT</strong>
 166          * need to explicitly lock and unlock the object.
 167          *
 168          * @param e event to log
 169          */
 170         virtual void write(const Event& e);
 171
 172     private:
 173         boost::scoped_ptr<xmltooling::Mutex> m_lock;
 174         std::string m_absent;
 175         std::vector<std::string> m_formatting;
 176     };
 177
 178     class SHIBSP_API LoginEvent : public TransactionLog::Event
 179     {
 180     public:
 181         /**
 182          * Constructor.
 183          */
 184         LoginEvent();
 185
 186         virtual ~LoginEvent();
 187
 188         const char* getType() const;
 189
 190         /** SAML 2.0 AuthnStatement. */
 191         const opensaml::saml2::AuthnStatement* m_saml2AuthnStatement;
 192
 193         /** SAML 2.0 Response. */
 194         const opensaml::saml2p::StatusResponseType* m_saml2Response;
 195
 196         /** SAML 1.x AuthnStatement. */
 197         const opensaml::saml1::AuthenticationStatement* m_saml1AuthnStatement;
 198
 199         /** SAML 1.x Response. */
 200         const opensaml::saml1p::Response* m_saml1Response;
 201
 202         /** Attributes associated with event. */
 203         const std::vector<Attribute*>* m_attributes;
 204     };
 205
 206     class SHIBSP_API LogoutEvent : public TransactionLog::Event
 207     {
 208     public:
 209         /**
 210          * Constructor.
 211          */
 212         LogoutEvent();
 213
 214         virtual ~LogoutEvent();
 215
 216         const char* getType() const;
 217
 218         /** Result of logout (local, global, partial). */
 219         enum logout_type_t {
 220             LOGOUT_EVENT_UNKNOWN,
 221             LOGOUT_EVENT_INVALID,
 222             LOGOUT_EVENT_LOCAL,
 223             LOGOUT_EVENT_GLOBAL,
 224             LOGOUT_EVENT_PARTIAL
 225         } m_logoutType;
 226
 227         /** SAML 2.0 Request. */
 228         const opensaml::saml2p::LogoutRequest* m_saml2Request;
 229
 230         /** SAML 2.0 Response. */
 231         const opensaml::saml2p::LogoutResponse* m_saml2Response;
 232
 233         /** Primary session associated with event. */
 234         const Session* m_session;
 235
 236         /** All sessions associated with event. */
 237         std::vector<std::string> m_sessions;
 238     };
 239
 240     class SHIBSP_API AuthnRequestEvent : public TransactionLog::Event
 241     {
 242     public:
 243         /**
 244          * Constructor.
 245          */
 246         AuthnRequestEvent();
 247
 248         virtual ~AuthnRequestEvent();
 249
 250         const char* getType() const;
 251
 252         /** SAML 2.0 Request. */
 253         const opensaml::saml2p::AuthnRequest* m_saml2Request;
 254     };
 255
 256     /**
 257      * Registers Event classes into the runtime.
 258      */
 259     void SHIBSP_API registerEvents();
 260
 261     /** Login event. */
 262     #define LOGIN_EVENT         "Login"
 263
 264     /** Logout event. */
 265     #define LOGOUT_EVENT        "Logout"
 266
 267     /** AuthnRequest event. */
 268     #define AUTHNREQUEST_EVENT  "AuthnRequest"
 269 };
 270
 271 #endif /* __shibsp_txlog_h__ */