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
  39 namespace xmltooling {
  40     class XMLTOOL_API Mutex;
  41 };
  42
  43 namespace opensaml {
  44     namespace saml1 {
  45         class SAML_API AuthenticationStatement;
  46     };
  47
  48     namespace saml1p {
  49         class SAML_API Response;
  50     };
  51
  52     namespace saml2 {
  53         class SAML_API AuthnStatement;
  54         class SAML_API NameID;
  55     };
  56
  57     namespace saml2p {
  58         class SAML_API AuthnRequest;
  59         class SAML_API LogoutRequest;
  60         class SAML_API LogoutResponse;
  61         class SAML_API StatusResponseType;
  62     };
  63
  64     namespace saml2md {
  65         class SAML_API EntityDescriptor;
  66     };
  67 };
  68
  69 namespace shibsp {
  70     class SHIBSP_API Application;
  71     class SHIBSP_API Attribute;
  72     class SHIBSP_API Session;
  73
  74     /**
  75      * Interface to a synchronized event/audit logging object.
  76      *
  77      * <p>For backward compatibility, we expose a logging object directly, but
  78      * new applications should rely on the Event callback API.
  79      */
  80     class SHIBSP_API TransactionLog : public virtual xmltooling::Lockable
  81     {
  82         MAKE_NONCOPYABLE(TransactionLog);
  83     public:
  84         /**
  85          * Constructor.
  86          *
  87          * @param fmt       formatting string for events
  88          * @param absent    string to output when a field is empty
  89          */
  90         TransactionLog(const char* fmt=nullptr, const char* absent=nullptr);
  91
  92         virtual ~TransactionLog();
  93
  94         xmltooling::Lockable* lock();
  95         void unlock();
  96
  97         /** @deprecated Logging object. */
  98         xmltooling::logging::Category& log;
  99
 100         /**
 101          * Callback interface that outputs an event record to a stream using formatting tokens.
 102          */
 103         class SHIBSP_API Event {
 104             MAKE_NONCOPYABLE(Event);
 105         protected:
 106             /** Function that handles a formatting token. */
 107             typedef bool (*handler_fn)(const Event& e, std::ostream&);
 108
 109             /** Map of tokens to handlers. */
 110             std::map<std::string, handler_fn> m_handlers;
 111
 112             /**
 113              * Constructor.
 114              */
 115             Event();
 116
 117         public:
 118             virtual ~Event();
 119
 120             /**
 121              * Returns a type string to be used for the log category in the event log.
 122              *
 123              * @return  type or category for the event
 124              */
 125             virtual const char* getType() const=0;
 126
 127             /** Exception */
 128             const std::exception* m_exception;
 129
 130             /** Request object associated with event. */
 131             const xmltooling::GenericRequest* m_request;
 132
 133             /** Application object associated with event. */
 134             const Application* m_app;
 135
 136             /** Session identifier. */
 137             const char* m_sessionID;
 138
 139             /** Peer entity associated with event. */
 140             const opensaml::saml2md::EntityDescriptor* m_peer;
 141
 142             /** Protocol associated with event. */
 143             const char* m_protocol;
 144
 145             /** Protocol binding associated with event. */
 146             const char* m_binding;
 147
 148             /** SAML 2.0 NameID. */
 149             const opensaml::saml2::NameID* m_nameID;
 150
 151             /**
 152              * Outputs an event record to a stream based on the defined formatting string.
 153              *
 154              * @param out       stream to use
 155              * @param field     field to output
 156              * @param absent    string to output if the field is empty
 157              * @return  true iff the field was recognized and substituted
 158              */
 159             virtual bool write(std::ostream& out, const char* field, const char* absent) const;
 160         };
 161
 162         /**
 163          * Write a formatted event record to the log.
 164          * <p>This method is internally synchronized and the caller does <strong>NOT</strong>
 165          * need to explicitly lock and unlock the object.
 166          *
 167          * @param e event to log
 168          */
 169         virtual void write(const Event& e);
 170
 171     private:
 172         xmltooling::Mutex* m_lock;
 173         std::string m_absent;
 174         std::vector<std::string> m_formatting;
 175     };
 176
 177     class SHIBSP_API LoginEvent : public TransactionLog::Event
 178     {
 179     public:
 180         /**
 181          * Constructor.
 182          */
 183         LoginEvent();
 184
 185         virtual ~LoginEvent();
 186
 187         const char* getType() const;
 188
 189         /** SAML 2.0 AuthnStatement. */
 190         const opensaml::saml2::AuthnStatement* m_saml2AuthnStatement;
 191
 192         /** SAML 2.0 Response. */
 193         const opensaml::saml2p::StatusResponseType* m_saml2Response;
 194
 195         /** SAML 1.x AuthnStatement. */
 196         const opensaml::saml1::AuthenticationStatement* m_saml1AuthnStatement;
 197
 198         /** SAML 1.x Response. */
 199         const opensaml::saml1p::Response* m_saml1Response;
 200
 201         /** Attributes associated with event. */
 202         const std::vector<Attribute*>* m_attributes;
 203     };
 204
 205     class SHIBSP_API LogoutEvent : public TransactionLog::Event
 206     {
 207     public:
 208         /**
 209          * Constructor.
 210          */
 211         LogoutEvent();
 212
 213         virtual ~LogoutEvent();
 214
 215         const char* getType() const;
 216
 217         /** Result of logout (local, global, partial). */
 218         enum logout_type_t {
 219             LOGOUT_EVENT_UNKNOWN,
 220             LOGOUT_EVENT_INVALID,
 221             LOGOUT_EVENT_LOCAL,
 222             LOGOUT_EVENT_GLOBAL,
 223             LOGOUT_EVENT_PARTIAL
 224         } m_logoutType;
 225
 226         /** SAML 2.0 Request. */
 227         const opensaml::saml2p::LogoutRequest* m_saml2Request;
 228
 229         /** SAML 2.0 Response. */
 230         const opensaml::saml2p::LogoutResponse* m_saml2Response;
 231
 232         /** Primary session associated with event. */
 233         const Session* m_session;
 234
 235         /** All sessions associated with event. */
 236         std::vector<std::string> m_sessions;
 237     };
 238
 239     class SHIBSP_API AuthnRequestEvent : public TransactionLog::Event
 240     {
 241     public:
 242         /**
 243          * Constructor.
 244          */
 245         AuthnRequestEvent();
 246
 247         virtual ~AuthnRequestEvent();
 248
 249         const char* getType() const;
 250
 251         /** SAML 2.0 Request. */
 252         const opensaml::saml2p::AuthnRequest* m_saml2Request;
 253     };
 254
 255     /**
 256      * Registers Event classes into the runtime.
 257      */
 258     void SHIBSP_API registerEvents();
 259
 260     /** Login event. */
 261     #define LOGIN_EVENT         "Login"
 262
 263     /** Logout event. */
 264     #define LOGOUT_EVENT        "Logout"
 265
 266     /** AuthnRequest event. */
 267     #define AUTHNREQUEST_EVENT  "AuthnRequest"
 268 };
 269
 270 #endif /* __shibsp_txlog_h__ */