xrootd/XrdSec/XrdSecEntityPin.hh

0001 #ifndef __SEC_ENTITYPIN_H__
0002 #define __SEC_ENTITYPIN_H__
0003 /******************************************************************************/
0004 /*                                                                            */
0005 /*                    X r d S e c E n t i t y P i n . h h                     */
0006 /*                                                                            */
0007 /* (c) 2020 by the Board of Trustees of the Leland Stanford, Jr., University  */
0008 /*   Produced by Andrew Hanushevsky for Stanford University under contract    */
0009 /*              DE-AC02-76-SFO0515 with the Department of Energy              */
0010 /*                                                                            */
0011 /* This file is part of the XRootD software suite.                            */
0012 /*                                                                            */
0013 /* XRootD is free software: you can redistribute it and/or modify it under    */
0014 /* the terms of the GNU Lesser General Public License as published by the     */
0015 /* Free Software Foundation, either version 3 of the License, or (at your     */
0016 /* option) any later version.                                                 */
0017 /*                                                                            */
0018 /* XRootD is distributed in the hope that it will be useful, but WITHOUT      */
0019 /* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or      */
0020 /* FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public       */
0021 /* License for more details.                                                  */
0022 /*                                                                            */
0023 /* You should have received a copy of the GNU Lesser General Public License   */
0024 /* along with XRootD in a file called COPYING.LESSER (LGPL license) and file  */
0025 /* COPYING (GPL license).  If not, see <http://www.gnu.org/licenses/>.        */
0026 /*                                                                            */
0027 /* The copyright holder's institutional names and contributor's names may not */
0028 /* be used to endorse or promote products derived from this software without  */
0029 /* specific prior written permission of the institution or contributor.       */
0030 /******************************************************************************/
0031
0032 /*! This class defines the XrdSecEntity object post processing plugin. When
0033     authentication succeeds, the plugin is called to inspect and possible
0034     decorate (e.g. add attributes) the entity object. The plugin also has the
0035     capability of returning failure due to some problem. When failure ooccurs,
0036     the security framework moves on to another authentication protocol, if one
0037     is avalable. Entity post processing plugins may be stacked. You always
0038     return the results of the stacked plugin whether or not you wish to handle
0039     the entity object, if a stacked plugin exists; unless you return false.
0040 */
0041
0042 class XrdOucErrInfo;
0043 class XrdSecEntity;
0044
0045 class XrdSecEntityPin
0046 {
0047 public:
0048
0049 //------------------------------------------------------------------------------
0050 //! Post process an authenticated entity object.
0051 //!
0052 //! @param  entity Reference to the entity object.
0053 //! @param  einfo  Reference to errinfo object where a message that should be
0054 //!                returned to the client on why post processing failed.
0055 //!
0056 //! @return true upon success and false upon failure with einfo containing
0057 //!         the reason for the failure.
0058 //------------------------------------------------------------------------------
0059
0060 virtual bool Process(XrdSecEntity &entity, XrdOucErrInfo &einfo) = 0;
0061
0062              XrdSecEntityPin() {}
0063 virtual     ~XrdSecEntityPin() {}
0064 };
0065
0066 /*! An instance of the plugin is obtained by the plugin manager using the
0067     XrdOucPinObject class. The most straightforward way to implement this
0068     is to inherit the XrdOucPinObject class by a class of your choosing
0069     that defines a file level object named SecEntityPin, as follows:
0070
0071     class myPinObject : public XrdOucPinObject<XrdSecEntityPin>
0072     {public:
0073
0074      XrdSecEntityPin *getInstance(...) {provide concrete implementation}
0075
0076     } SecEntityPin;
0077
0078     see XrdOucPinObject.hh for additional details. There are many other
0079     ways to accomplish this including inheriting this class along with the
0080     XrdSecEntityPin class by the post processing implementation class.
0081
0082     You should also specify the compilation version. That is, the XRootD
0083     version you used to compile your plug-in. Decalre it as:
0084
0085     #include "XrdVersion.hh"
0086     XrdVERSIONINFO(SecEntityPin,<name>);
0087
0088     where <name> is a 1- to 15-character unquoted name identifying your plugin.
0089 */
0090 #endif