audisp/plugins/zos-remote/zos-remote-ldap.h

   1 /***************************************************************************
   2  *   Copyright (C) 2007 International Business Machines  Corp.             *
   3  *   All Rights Reserved.                                                  *
   4  *                                                                         *
   5  *   This program is free software; you can redistribute it and/or modify  *
   6  *   it under the terms of the GNU General Public License as published by  *
   7  *   the Free Software Foundation; either version 2 of the License, or     *
   8  *   (at your option) any later version.                                   *
   9  *                                                                         *
  10  *   This program is distributed in the hope that it will be useful,       *
  11  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  12  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  13  *   GNU General Public License for more details.                          *
  14  *                                                                         *
  15  *   You should have received a copy of the GNU General Public License     *
  16  *   along with this program; if not, write to the                         *
  17  *   Free Software Foundation, Inc.,                                       *
  18  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  19  *                                                                         *
  20  * Authors:                                                                *
  21  *   Klaus Heinrich Kiwi <klausk@br.ibm.com>                               *
  22  ***************************************************************************/
  23
  24 #ifndef _ZOS_REMOTE_LDAP_H
  25 #define _ZOS_REMOTE_LDAP_H
  26
  27 #include <lber.h>
  28 #include <ldap.h>
  29
  30
  31 /***************************************************************************
  32  *   LDAP Extended Op OID for ICTX Audit                                   *
  33  ***************************************************************************/
  34 /* ICTX EIM component AUDIT Request OID */
  35 #define ICTX_OIDAUDITREQUEST     "1.3.18.0.2.12.68"
  36
  37 /* The AUDIT Response OID */
  38 #define ICTX_OIDAUDITRESPONSE    "1.3.18.0.2.12.69"
  39
  40 /* This implementation version
  41    Request and response must match this */
  42 #define ICTX_REQUESTVER          0x1
  43
  44 /* Needed for BER-encoding */
  45 #define ASN1_IA5STRING_TAG       0x16
  46
  47 /***************************************************************************
  48  *   the ASN.1 struct for the remote audit request and response:           *
  49  *                                                                         *
  50  *   RequestValue ::= SEQUENCE  {                                          *
  51  *       RequestVersion    INTEGER,                                        *
  52  *       ItemList    SEQUENCE OF                                           *
  53  *           Item    SEQUENCE {                                            *
  54  *               ItemVersion    INTEGER,                                   *
  55  *               ItemTag        INTEGER,                                   *
  56  *               LinkValue    OCTET STRING SIZE(8),                        *
  57  *               Violation    BOOLEAN,                                     *
  58  *               Event        INTEGER,                                     *
  59  *               Qualifier    INTEGER,                                     *
  60  *               Class        IA5String,                                   *
  61  *               Resource    IA5String,                                    *
  62  *               LogString    IA5String,                                   *
  63  *               DatafieldList    SEQUENCE OF                              *
  64  *                   DataField    SEQUENCE {                               *
  65  *                       TYPE    INTEGER,                                  *
  66  *                       VALUE    IA5STRING                                *
  67  *                   }                                                     *
  68  *           }                                                             *
  69  *   }                                                                     *
  70  *                                                                         *
  71  *   Response ::= SEQUENCE {                                               *
  72  *       Version        INTEGER,                                           *
  73  *       ResponseCode    INTEGER,                                          *
  74  *       ItemList    SEQUENCE OF                                           *
  75  *           Item    SEQUENCE {                                            *
  76  *               ItemVersion    INTEGER,                                   *
  77  *               ItemTag        INTEGER,                                   *
  78  *               MajorCode    INTEGER,                                     *
  79  *               MinorCode1    INTEGER,                                    *
  80  *               MinorCode2    INTEGER,                                    *
  81  *               MinorCode3    INTEGER                                     *
  82  *           }                                                             *
  83  *   }                                                                     *
  84  ***************************************************************************/
  85
  86 /***************************************************************************
  87  *   z/OS Remote-services Audit Minor return codes meaning
  88
  89 Major Code    Meaning
  90 ----------    ---------------------------------------------------------
  91 0-14          - MinorCode1 is the SAF return code
  92               - MinorCode2 is the RACF return code
  93               - MinorCode3 is the RACF reason code
  94
  95 16-20         - MinorCode1 identifies the extended operation request
  96                 parameter number (see audit request ASN.1 definition):
  97                  0 - Item
  98                  1 - ItemVersion
  99                  2 - ItemTag
 100                  3 - LinkValue
 101                  4 - Violation
 102                  5 - Event
 103                  6 - Qualifier
 104                  7 - Class
 105                  8 - Resource
 106                  9 - LogString
 107                 10 - DataFieldList
 108                 11 - DataField *
 109                 12 - TYPE *
 110                 13 - VALUE *
 111               - MinorCode2 indicates one of the Following:
 112                 32 - incorrect length
 113                 36 - incorrect value
 114                 40 - encoding error
 115               - MinorCode3 has no defined meaning
 116
 117 24-100        - MinorCode1 has no defined meaning
 118               - MinorCode2 has no defined meaning
 119               - MinorCode3 has no defined meaning
 120
 121 * There can be multiple DataField, TYPEs and VALUEs in a request. If any of them is bad
 122   you get the same 11, 12 or 13 MinorCode1. There is no further breakdown of which one
 123   is bad.
 124
 125  ***************************************************************************/
 126
 127 /***************************************************************************
 128  *   Audit Request 'event' field meaning                                   *
 129  ***************************************************************************/
 130 #define ZOS_REMOTE_EVENT_AUTHENTICATION            0x1
 131 #define ZOS_REMOTE_EVENT_AUTHORIZATION             0x2
 132 #define ZOS_REMOTE_EVENT_AUTHORIZATION_MAPPING     0x3
 133 #define ZOS_REMOTE_EVENT_KEY_MGMT                  0x4
 134 #define ZOS_REMOTE_EVENT_POLICY_MGMT               0x5
 135 #define ZOS_REMOTE_EVENT_ADMIN_CONFIG              0x6
 136 #define ZOS_REMOTE_EVENT_ADMIN_ACTION              0x7
 137
 138 /***************************************************************************
 139  *   Audit Request 'qualifier' field meaning                               *
 140  ***************************************************************************/
 141 #define ZOS_REMOTE_QUALIF_SUCCESS                  0x0
 142 #define ZOS_REMOTE_QUALIF_INFO                     0x1
 143 #define ZOS_REMOTE_QUALIF_WARN                     0x2
 144 #define ZOS_REMOTE_QUALIF_FAIL                     0x3
 145
 146 /***************************************************************************
 147  *   Relocate types for Audit Request                                      *
 148  ***************************************************************************/
 149 /* SAF identifier for bind user */
 150 #define ZOS_REMOTE_RELOC_SAF_BIND_USER             100
 151
 152 /* Reguestor's bind user identifier */
 153 #define ZOS_REMOTE_RELOC_REQ_BIND_USER             101
 154
 155 /* Originating security domain */
 156 #define ZOS_REMOTE_RELOC_ORIG_SECURITY             102
 157
 158 /* Originating registry / realm */
 159 #define ZOS_REMOTE_RELOC_ORIG_REALM                103
 160
 161 /* Originating user name */
 162 #define ZOS_REMOTE_RELOC_ORIG_USER                 104
 163
 164 /* Mapped security domain */
 165 #define ZOS_REMOTE_RELOC_MAPPED_SECURITY           105
 166
 167 /* Mapped registry / realm */
 168 #define ZOS_REMOTE_RELOC_MAPPED_REALM              106
 169
 170 /* Mapped user name */
 171 #define ZOS_REMOTE_RELOC_MAPPED_USER               107
 172
 173 /* Operation performed */
 174 #define ZOS_REMOTE_RELOC_OPERATION                 108
 175
 176 /* Mechanism / object name */
 177 #define ZOS_REMOTE_RELOC_OBJECT                    109
 178
 179 /* Method  / function used */
 180 #define ZOS_REMOTE_RELOC_FUNCTION                  110
 181
 182 /* Key / certificate name */
 183 #define ZOS_REMOTE_RELOC_CERTIFICATE               111
 184
 185 /* Caller subject initiating security event  */
 186 #define ZOS_REMOTE_RELOC_INITIATING_EVENT          112
 187
 188 /* Date and time security event occurred  */
 189 #define ZOS_REMOTE_RELOC_TIMESTAMP                 113
 190
 191 /* Application specific data. (i.e. Other) */
 192 #define ZOS_REMOTE_RELOC_OTHER                     114
 193
 194 /***************************************************************************
 195  *   z/OS Remote-services Audit Major return codes                         *
 196  ***************************************************************************/
 197 #define ZOS_REMOTE_MAJOR_SUCCESS                   0
 198
 199 /* Event was logged, with warnings */
 200 #define ZOS_REMOTE_MAJOR_WARNINGMODE               2
 201
 202 /* No logging required
 203    No audit controls are set to require it */
 204 #define ZOS_REMOTE_MAJOR_NOTREQ                    3
 205
 206 /* Class not active/ractlisted,
 207    covering profile not found or
 208    RACF is not installed */
 209 #define ZOS_REMOTE_MAJOR_UNDETERMINED              4
 210
 211 /* The user does not have authority the R_auditx service.
 212     The userid associated with the LDAP server must have
 213     at least READ access to the FACILITY class profile IRR.RAUDITX. */
 214 #define ZOS_REMOTE_MAJOR_UNAUTHORIZED              8
 215
 216
 217 /* The R_auditx service returned an unexpected error.
 218    Compare the returned minor codes with the SAF RACF codes
 219    documented in Security Server Callable Services */
 220 #define ZOS_REMOTE_MAJOR_RACROUTE                  12
 221
 222 /* A value specified in the extended operation request is
 223    incorrect or unsupported. Check the returned minor codes
 224    to narrow the reason */
 225 #define ZOS_REMOTE_MAJOR_VAL_ERR                   16
 226
 227 /* A DER decoding error was encountered in an item.
 228    Processing Terminated. Partial results may be returned */
 229 #define ZOS_REMOTE_MAJOR_ENC_ERR                   20
 230
 231 /* The requestor does not have sufficient authority for the
 232    requested function. The userid associated with the LDAP bind
 233    user must have at least READ access to the FACILITY class
 234    profile IRR.LDAP.REMOTE.AUDIT. */
 235 #define ZOS_REMOTE_MAJOR_UNSUF_AUTH                24
 236
 237 /* No items are found within the ItemList sequence of the extended
 238    operation request, so no response items are returned */
 239 #define ZOS_REMOTE_MAJOR_EMPTY                     28
 240
 241 /* Invalid RequestVersion */
 242 #define ZOS_REMOTE_MAJOR_INVALID_VER               61
 243
 244 /* An internal error was encountered within the ICTX component */
 245 #define ZOS_REMOTE_MAJOR_INTERNAL_ERR              100
 246
 247 /***************************************************************************
 248  *   Some standard sizes for remote audit request items                    *
 249  ***************************************************************************/
 250 #define ZOS_REMOTE_LINK_VALUE_SIZE                 8
 251 #define ZOS_REMOTE_CLASS_SIZE                      8
 252 #define ZOS_REMOTE_RESOURCE_SIZE                   240
 253 #define ZOS_REMOTE_LOGSTRING_SIZE                  200
 254
 255
 256 /***************************************************************************
 257  *   Some standard Error defines                                           *
 258  ***************************************************************************/
 259 #define ICTX_SUCCESS                         0x00
 260
 261 /* maybe a temporary failure? */
 262 #define ICTX_E_TRYAGAIN                      0x01
 263
 264 /* permanent failure - abort event submission */
 265 #define ICTX_E_ABORT                         0x02
 266
 267 /* Fatal failure - abort program */
 268 #define ICTX_E_FATAL                         0x03
 269
 270 /* generic error */
 271 #define ICTX_E_ERROR                         0x10
 272
 273 /***************************************************************************
 274  *   structure representing an z/OS Remote-services session                *
 275  ***************************************************************************/
 276 typedef struct opaque
 277 {
 278     char *server;
 279     unsigned int port;
 280     char *user;
 281     char *password;
 282     unsigned int timeout;
 283     LDAP *ld;
 284     int connected;
 285 } ZOS_REMOTE;
 286
 287 /***************************************************************************
 288  *   LDAP XOP operations                                                   *
 289  ***************************************************************************/
 290 /*
 291  * Initializes z/OS Remote-services (LDAP to ITDS) connection,
 292  * binds to ITDS Server using configured RACF ID
 293  * Args are:
 294  * server, bind user, bind password, server port, timeout
 295  * Caller must call zos_remote_destroy() to free memory allocation
 296  */
 297 int zos_remote_init(ZOS_REMOTE *, const char *, int, const char *,
 298                         const char *, int);
 299
 300 /*
 301  * Uninitializes z/OS Remote-services (LDAP) connection
 302  */
 303 void zos_remote_destroy(ZOS_REMOTE *);
 304
 305 /*
 306  * sync submit request - possibly reconnect to server
 307  * if the connection if found to be dead
 308  */
 309 int submit_request_s(ZOS_REMOTE *, BerElement *);
 310
 311
 312 #endif                          /* _ZOS_REMOTE_LDAP_H */