xrootd
XrdSecTLayer.hh
Go to the documentation of this file.
1 #ifndef XRDSECTLAYER_HH
2 #define XRDSECTLAYER_HH
3 /******************************************************************************/
4 /* */
5 /* X r d S e c T L a y e r . h h */
6 /* */
7 /* */
8 /* (c) 2008 by the Board of Trustees of the Leland Stanford, Jr., University */
9 /* All Rights Reserved */
10 /* Produced by Andrew Hanushevsky for Stanford University under contract */
11 /* DE-AC02-76-SFO0515 with the Department of Energy */
12 /* */
13 /* This file is part of the XRootD software suite. */
14 /* */
15 /* XRootD is free software: you can redistribute it and/or modify it under */
16 /* the terms of the GNU Lesser General Public License as published by the */
17 /* Free Software Foundation, either version 3 of the License, or (at your */
18 /* option) any later version. */
19 /* */
20 /* XRootD is distributed in the hope that it will be useful, but WITHOUT */
21 /* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or */
22 /* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public */
23 /* License for more details. */
24 /* */
25 /* You should have received a copy of the GNU Lesser General Public License */
26 /* along with XRootD in a file called COPYING.LESSER (LGPL license) and file */
27 /* COPYING (GPL license). If not, see <http://www.gnu.org/licenses/>. */
28 /* */
29 /* The copyright holder's institutional names and contributor's names may not */
30 /* be used to endorse or promote products derived from this software without */
31 /* specific prior written permission of the institution or contributor. */
32 /******************************************************************************/
33 
35 #include "XrdSys/XrdSysPthread.hh"
36 
37 /* The XrdSecTLayer class is meant to be used as a wrapper for security
38  protocols that require transport-layer interactions to complete the
39  authentication exchange (e.g., native ssl). This class virtualizes a
40  transport-layer socket and provides the proper framing to allow stream
41  socket level interactions to occur across an existing client/xrootd
42  connection. To that extent, there are certain limitations in this
43  virtualization:
44  1) Interactions must complete within a window whose upper bound is set to
45  CPU 10 seconds (i.e., Network RTT and artificial delays do not apply).
46  The window has no lower bound so that an interaction may complete as fast
47  as conditions allow. An interaction is whatever bytes produce a single
48  request/response. These bytes need not be produced all at once but the
49  last required byte of an interaction must be produced within 10 CPU
50  seconds of the 1st byte. There is no limit on the number of interactions.
51  2) The use of the supplied socket must use standard and common socket
52  operations (e.g., read(), write(), send(), recv(), close()).
53  3) The protocol must not be sensitive to the fact that the socket will
54  identify itself as a local socket with an IPV4 address of 127.0.0.1.
55 
56  For more information, see pure abstract methods secClient() and secServer()
57  which must be implemented by the derived class (in addition to delete()).
58  Finally, consider the parameters you may need to pass to the constructor of
59  this class.
60 */
61 
62 class XrdOucErrInfo;
63 
65 {
66 public:
67 
68 // The object inheriting this class should call the initializer indicating
69 // the true name of the protocol (no more that 7 characters). To optimize the
70 // start-up, indicate who is the initiator (i.e., first one to send data). Using
71 // the enum below, specify isClient (the default) or isServer. If the initiator
72 // is not known, use the default and the class will dynamically determine it.
73 //
75 
76  XrdSecTLayer(const char *pName, Initiator who1st=isClient);
77 
78 // This is a symmetric wrapper. At the start on each end, secClient() is
79 // called on the client-side and secServer() is called on the server side.
80 // The 1st parameter is the filedescriptor to be used for the security exchange.
81 // It is the responsibility of each routine to close the file descriptor prior
82 // to returning to the caller! No return value is expected as success or failure
83 // is communicated via the esecond paramter, the XrdOucErrInfo object.
84 
85 // Upon success, the error code must be set to zero (the initial value) and
86 // for secServer() the Entity object defined in the topmost
87 // XrdSecProtocol object must contain the client's identity.
88 
89 // Upon failure, the error code must be set to a positive error number (usually
90 // some errno value) as well as text explaining the problem.
91 
92 // Client: theFD - file descriptor to be used
93 // einfo - the error object where ending status must be returned
94 //
95 virtual void secClient(int theFD, XrdOucErrInfo *einfo)=0;
96 
97 // Server: theFD - file descriptor to be used
98 // einfo - the error object where ending status must be returned
99 //
100 virtual void secServer(int theFD, XrdOucErrInfo *einfo)=0;
101 
102 // You must implete the proper delete(). Normally, do a "delete this" and join
103 // the secTid thread: "if (secTid) {XrdSysThread::Join(secTid,NULL);secTid=0;}".
104 //
105 virtual void Delete()=0;
106 
107 // Classes that must be public are only internally used
108 //
109 
110 virtual int Authenticate (XrdSecCredentials *cred,
111  XrdSecParameters **parms,
112  XrdOucErrInfo *einfo=0);
113 
115  XrdOucErrInfo *einfo=0);
116 
117  void secXeq();
118 
119 protected:
120 pthread_t secTid;
121 
122 virtual ~XrdSecTLayer() {if (eText) {free(eText);eText=0;}
123  if (myFD>0) {close(myFD);myFD=-1;}
124  }
125 
126 private:
127 
128 int bootUp(Initiator Who);
129 int Read(int FD, char *Buff, int rdLen);
130 int secDone();
131 void secDrain();
132 const char *secErrno(int rc, char *buff);
133 void secError(const char *Msg, int rc, int iserrno=1);
134 
138 int myFD;
139 int urFD;
140 int Tmax; // Maximum timeslices per interaction
141 int Tcur; // Current timeslice
142 int eCode;
143 char *eText;
145 
146 struct TLayerRR
147 {
148  char protName[8]; // via Constructor
149  char protCode; // One of the below
150 static const char endData = 0x00;
151 static const char xfrData = 0x01;
152  char protRsvd[7]; // Reserved
153 } Hdr;
154 
155 static const int buffSz = 8192;
156 static const int hdrSz = sizeof(TLayerRR);
157 static const int dataSz = buffSz - hdrSz;
158 };
159 #endif
Definition: XrdSecTLayer.hh:146
struct XrdSecTLayer::TLayerRR Hdr
int Read(int FD, char *Buff, int rdLen)
static const int dataSz
Definition: XrdSecTLayer.hh:157
static const char xfrData
Definition: XrdSecTLayer.hh:151
char protRsvd[7]
Definition: XrdSecTLayer.hh:152
XrdSysSemaphore mySem
Definition: XrdSecTLayer.hh:135
Definition: XrdSecInterface.hh:130
Initiator Starter
Definition: XrdSecTLayer.hh:136
virtual XrdSecCredentials * getCredentials(XrdSecParameters *parm=0, XrdOucErrInfo *einfo=0)
static const int hdrSz
Definition: XrdSecTLayer.hh:156
Definition: XrdSecTLayer.hh:74
char * eText
Definition: XrdSecTLayer.hh:143
int urFD
Definition: XrdSecTLayer.hh:139
pthread_t secTid
Definition: XrdSecTLayer.hh:120
Definition: XrdOucErrInfo.hh:100
XrdSecTLayer(const char *pName, Initiator who1st=isClient)
Definition: XrdSysPthread.hh:405
static const int buffSz
Definition: XrdSecTLayer.hh:155
void secDrain()
int Tmax
Definition: XrdSecTLayer.hh:140
virtual int Authenticate(XrdSecCredentials *cred, XrdSecParameters **parms, XrdOucErrInfo *einfo=0)
virtual void secClient(int theFD, XrdOucErrInfo *einfo)=0
void secError(const char *Msg, int rc, int iserrno=1)
Definition: XrdSecTLayer.hh:64
Initiator Responder
Definition: XrdSecTLayer.hh:137
char protCode
Definition: XrdSecTLayer.hh:149
Definition: XrdSecTLayer.hh:74
#define close(a)
Definition: XrdPosix.hh:43
virtual void secServer(int theFD, XrdOucErrInfo *einfo)=0
virtual ~XrdSecTLayer()
Definition: XrdSecTLayer.hh:122
int myFD
Definition: XrdSecTLayer.hh:138
XrdOucErrInfo * eDest
Definition: XrdSecTLayer.hh:144
virtual void Delete()=0
Delete the protocol object. DO NOT use C++ delete() on this object.
const char * secErrno(int rc, char *buff)
char protName[8]
Definition: XrdSecTLayer.hh:148
Initiator
Definition: XrdSecTLayer.hh:74
Generic structure to pass security information back and forth.
Definition: XrdSecInterface.hh:50
static const char endData
Definition: XrdSecTLayer.hh:150
int bootUp(Initiator Who)
int eCode
Definition: XrdSecTLayer.hh:142
int Tcur
Definition: XrdSecTLayer.hh:141