source/nsswitch/libwbclient/wbclient.h

   1 /*
   2    Unix SMB/CIFS implementation.
   3
   4    Winbind client API
   5
   6    Copyright (C) Gerald (Jerry) Carter 2007
   7
   8    This library is free software; you can redistribute it and/or
   9    modify it under the terms of the GNU Lesser General Public
  10    License as published by the Free Software Foundation; either
  11    version 3 of the License, or (at your option) any later version.
  12
  13    This library is distributed in the hope that it will be useful,
  14    but WITHOUT ANY WARRANTY; without even the implied warranty of
  15    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16    Library General Public License for more details.
  17
  18    You should have received a copy of the GNU Lesser General Public License
  19    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  20 */
  21
  22 #ifndef _WBCLIENT_H
  23 #define _WBCLIENT_H
  24
  25 #include <pwd.h>
  26 #include <grp.h>
  27
  28 /* Define error types */
  29
  30 /**
  31  *  @brief Status codes returned from wbc functions
  32  **/
  33
  34 enum _wbcErrType {
  35         WBC_ERR_SUCCESS = 0,    /**< Successful completion **/
  36         WBC_ERR_NOT_IMPLEMENTED,/**< Function not implemented **/
  37         WBC_ERR_UNKNOWN_FAILURE,/**< General failure **/
  38         WBC_ERR_NO_MEMORY,      /**< Memory allocation error **/
  39         WBC_ERR_INVALID_SID,    /**< Invalid SID format **/
  40         WBC_ERR_INVALID_PARAM,  /**< An Invalid parameter was supplied **/
  41         WBC_ERR_WINBIND_NOT_AVAILABLE,   /**< Winbind daemon is not available **/
  42         WBC_ERR_DOMAIN_NOT_FOUND,        /**< Domain is not trusted or cannot be found **/
  43         WBC_ERR_INVALID_RESPONSE,        /**< Winbind returned an invalid response **/
  44         WBC_ERR_NSS_ERROR,            /**< NSS_STATUS error **/
  45         WBC_ERR_AUTH_ERROR,        /**< Authentication failed **/
  46         WBC_ERR_UNKNOWN_USER,      /**< User account cannot be found */
  47         WBC_ERR_UNKNOWN_GROUP      /**< Group account cannot be found */
  48 };
  49
  50 typedef enum _wbcErrType wbcErr;
  51
  52 #define WBC_ERROR_IS_OK(x) ((x) == WBC_ERR_SUCCESS)
  53
  54 const char *wbcErrorString(wbcErr error);
  55
  56 /**
  57  *  @brief Some useful details about the running winbindd
  58  *
  59  **/
  60 struct wbcInterfaceDetails {
  61         uint32_t interface_version;
  62         const char *winbind_version;
  63         char winbind_separator;
  64         const char *netbios_name;
  65         const char *netbios_domain;
  66         const char *dns_domain;
  67 };
  68
  69 /*
  70  * Data types used by the Winbind Client API
  71  */
  72
  73 #ifndef WBC_MAXSUBAUTHS
  74 #define WBC_MAXSUBAUTHS 15 /* max sub authorities in a SID */
  75 #endif
  76
  77 /**
  78  *  @brief Windows Security Identifier
  79  *
  80  **/
  81
  82 struct wbcDomainSid {
  83         uint8_t   sid_rev_num;
  84         uint8_t   num_auths;
  85         uint8_t   id_auth[6];
  86         uint32_t  sub_auths[WBC_MAXSUBAUTHS];
  87 };
  88
  89 /**
  90  * @brief Security Identifier type
  91  **/
  92
  93 enum wbcSidType {
  94         WBC_SID_NAME_USE_NONE=0,
  95         WBC_SID_NAME_USER=1,
  96         WBC_SID_NAME_DOM_GRP=2,
  97         WBC_SID_NAME_DOMAIN=3,
  98         WBC_SID_NAME_ALIAS=4,
  99         WBC_SID_NAME_WKN_GRP=5,
 100         WBC_SID_NAME_DELETED=6,
 101         WBC_SID_NAME_INVALID=7,
 102         WBC_SID_NAME_UNKNOWN=8,
 103         WBC_SID_NAME_COMPUTER=9
 104 };
 105
 106 /**
 107  * @brief Security Identifier with attributes
 108  **/
 109
 110 struct wbcSidWithAttr {
 111         struct wbcDomainSid sid;
 112         uint32_t attributes;
 113 };
 114
 115 /* wbcSidWithAttr->attributes */
 116
 117 #define WBC_SID_ATTR_GROUP_MANDATORY            0x00000001
 118 #define WBC_SID_ATTR_GROUP_ENABLED_BY_DEFAULT   0x00000002
 119 #define WBC_SID_ATTR_GROUP_ENABLED              0x00000004
 120 #define WBC_SID_ATTR_GROUP_OWNER                0x00000008
 121 #define WBC_SID_ATTR_GROUP_USEFOR_DENY_ONLY     0x00000010
 122 #define WBC_SID_ATTR_GROUP_RESOURCE             0x20000000
 123 #define WBC_SID_ATTR_GROUP_LOGON_ID             0xC0000000
 124
 125 /**
 126  * @brief Domain Information
 127  **/
 128
 129 struct wbcDomainInfo {
 130         char *short_name;
 131         char *dns_name;
 132         struct wbcDomainSid sid;
 133         uint32_t domain_flags;
 134         uint32_t trust_flags;
 135         uint32_t trust_type;
 136 };
 137
 138 /* wbcDomainInfo->domain_flags */
 139
 140 #define WBC_DOMINFO_DOMAIN_UNKNOWN    0x00000000
 141 #define WBC_DOMINFO_DOMAIN_NATIVE     0x00000001
 142 #define WBC_DOMINFO_DOMAIN_AD         0x00000002
 143 #define WBC_DOMINFO_DOMAIN_PRIMARY    0x00000004
 144 #define WBC_DOMINFO_DOMAIN_OFFLINE    0x00000008
 145
 146 /* wbcDomainInfo->trust_flags */
 147
 148 #define WBC_DOMINFO_TRUST_TRANSITIVE  0x00000001
 149 #define WBC_DOMINFO_TRUST_INCOMING    0x00000002
 150 #define WBC_DOMINFO_TRUST_OUTGOING    0x00000004
 151
 152 /* wbcDomainInfo->trust_type */
 153
 154 #define WBC_DOMINFO_TRUSTTYPE_NONE       0x00000000
 155 #define WBC_DOMINFO_TRUSTTYPE_FOREST     0x00000001
 156 #define WBC_DOMINFO_TRUSTTYPE_IN_FOREST  0x00000002
 157 #define WBC_DOMINFO_TRUSTTYPE_EXTERNAL   0x00000003
 158
 159
 160 /**
 161  * @brief Auth User Parameters
 162  **/
 163
 164 struct wbcAuthUserParams {
 165         const char *account_name;
 166         const char *domain_name;
 167         const char *workstation_name;
 168
 169         uint32_t flags;
 170
 171         uint32_t parameter_control;
 172
 173         enum wbcAuthUserLevel {
 174                 WBC_AUTH_USER_LEVEL_PLAIN = 1,
 175                 WBC_AUTH_USER_LEVEL_HASH = 2,
 176                 WBC_AUTH_USER_LEVEL_RESPONSE = 3
 177         } level;
 178         union {
 179                 const char *plaintext;
 180                 struct {
 181                         uint8_t nt_hash[16];
 182                         uint8_t lm_hash[16];
 183                 } hash;
 184                 struct {
 185                         uint8_t challenge[8];
 186                         uint32_t nt_length;
 187                         uint8_t *nt_data;
 188                         uint32_t lm_length;
 189                         uint8_t *lm_data;
 190                 } response;
 191         } password;
 192 };
 193
 194 /* wbcAuthUserParams->parameter_control */
 195
 196 #define WBC_MSV1_0_CLEARTEXT_PASSWORD_ALLOWED           0x00000002
 197 #define WBC_MSV1_0_UPDATE_LOGON_STATISTICS              0x00000004
 198 #define WBC_MSV1_0_RETURN_USER_PARAMETERS               0x00000008
 199 #define WBC_MSV1_0_ALLOW_SERVER_TRUST_ACCOUNT           0x00000020
 200 #define WBC_MSV1_0_RETURN_PROFILE_PATH                  0x00000200
 201 #define WBC_MSV1_0_ALLOW_WORKSTATION_TRUST_ACCOUNT      0x00000800
 202
 203 /* wbcAuthUserParams->flags */
 204
 205 #define WBC_AUTH_PARAM_FLAGS_INTERACTIVE_LOGON          0x00000001
 206
 207 /**
 208  * @brief Auth User Information
 209  *
 210  * Some of the strings are maybe NULL
 211  **/
 212
 213 struct wbcAuthUserInfo {
 214         uint32_t user_flags;
 215
 216         char *account_name;
 217         char *user_principal;
 218         char *full_name;
 219         char *domain_name;
 220         char *dns_domain_name;
 221
 222         uint32_t acct_flags;
 223         uint8_t user_session_key[16];
 224         uint8_t lm_session_key[8];
 225
 226         uint16_t logon_count;
 227         uint16_t bad_password_count;
 228
 229         uint64_t logon_time;
 230         uint64_t logoff_time;
 231         uint64_t kickoff_time;
 232         uint64_t pass_last_set_time;
 233         uint64_t pass_can_change_time;
 234         uint64_t pass_must_change_time;
 235
 236         char *logon_server;
 237         char *logon_script;
 238         char *profile_path;
 239         char *home_directory;
 240         char *home_drive;
 241
 242         /*
 243          * the 1st one is the account sid
 244          * the 2nd one is the primary_group sid
 245          * followed by the rest of the groups
 246          */
 247         uint32_t num_sids;
 248         struct wbcSidWithAttr *sids;
 249 };
 250
 251 /* wbcAuthUserInfo->user_flags */
 252
 253 #define WBC_AUTH_USER_INFO_GUEST                        0x00000001
 254 #define WBC_AUTH_USER_INFO_NOENCRYPTION                 0x00000002
 255 #define WBC_AUTH_USER_INFO_CACHED_ACCOUNT               0x00000004
 256 #define WBC_AUTH_USER_INFO_USED_LM_PASSWORD             0x00000008
 257 #define WBC_AUTH_USER_INFO_EXTRA_SIDS                   0x00000020
 258 #define WBC_AUTH_USER_INFO_SUBAUTH_SESSION_KEY          0x00000040
 259 #define WBC_AUTH_USER_INFO_SERVER_TRUST_ACCOUNT         0x00000080
 260 #define WBC_AUTH_USER_INFO_NTLMV2_ENABLED               0x00000100
 261 #define WBC_AUTH_USER_INFO_RESOURCE_GROUPS              0x00000200
 262 #define WBC_AUTH_USER_INFO_PROFILE_PATH_RETURNED        0x00000400
 263 #define WBC_AUTH_USER_INFO_GRACE_LOGON                  0x01000000
 264
 265 /* wbcAuthUserInfo->acct_flags */
 266
 267 #define WBC_ACB_DISABLED                        0x00000001 /* 1 User account disabled */
 268 #define WBC_ACB_HOMDIRREQ                       0x00000002 /* 1 Home directory required */
 269 #define WBC_ACB_PWNOTREQ                        0x00000004 /* 1 User password not required */
 270 #define WBC_ACB_TEMPDUP                         0x00000008 /* 1 Temporary duplicate account */
 271 #define WBC_ACB_NORMAL                          0x00000010 /* 1 Normal user account */
 272 #define WBC_ACB_MNS                             0x00000020 /* 1 MNS logon user account */
 273 #define WBC_ACB_DOMTRUST                        0x00000040 /* 1 Interdomain trust account */
 274 #define WBC_ACB_WSTRUST                         0x00000080 /* 1 Workstation trust account */
 275 #define WBC_ACB_SVRTRUST                        0x00000100 /* 1 Server trust account */
 276 #define WBC_ACB_PWNOEXP                         0x00000200 /* 1 User password does not expire */
 277 #define WBC_ACB_AUTOLOCK                        0x00000400 /* 1 Account auto locked */
 278 #define WBC_ACB_ENC_TXT_PWD_ALLOWED             0x00000800 /* 1 Encryped text password is allowed */
 279 #define WBC_ACB_SMARTCARD_REQUIRED              0x00001000 /* 1 Smart Card required */
 280 #define WBC_ACB_TRUSTED_FOR_DELEGATION          0x00002000 /* 1 Trusted for Delegation */
 281 #define WBC_ACB_NOT_DELEGATED                   0x00004000 /* 1 Not delegated */
 282 #define WBC_ACB_USE_DES_KEY_ONLY                0x00008000 /* 1 Use DES key only */
 283 #define WBC_ACB_DONT_REQUIRE_PREAUTH            0x00010000 /* 1 Preauth not required */
 284 #define WBC_ACB_PW_EXPIRED                      0x00020000 /* 1 Password Expired */
 285 #define WBC_ACB_NO_AUTH_DATA_REQD               0x00080000   /* 1 = No authorization data required */
 286
 287 struct wbcAuthErrorInfo {
 288         uint32_t nt_status;
 289         char *nt_string;
 290         int32_t pam_error;
 291         char *display_string;
 292 };
 293
 294 /*
 295  * DomainControllerInfo struct
 296  */
 297 struct wbcDomainControllerInfo {
 298         char *dc_name;
 299 };
 300
 301
 302
 303 /*
 304  * Memory Management
 305  */
 306
 307 void wbcFreeMemory(void*);
 308
 309
 310 /*
 311  * Utility functions for dealing with SIDs
 312  */
 313
 314 wbcErr wbcSidToString(const struct wbcDomainSid *sid,
 315                       char **sid_string);
 316
 317 wbcErr wbcStringToSid(const char *sid_string,
 318                       struct wbcDomainSid *sid);
 319
 320 wbcErr wbcPing(void);
 321
 322 wbcErr wbcInterfaceDetails(struct wbcInterfaceDetails **details);
 323
 324 /*
 325  * Name/SID conversion
 326  */
 327
 328 wbcErr wbcLookupName(const char *dom_name,
 329                      const char *name,
 330                      struct wbcDomainSid *sid,
 331                      enum wbcSidType *name_type);
 332
 333 wbcErr wbcLookupSid(const struct wbcDomainSid *sid,
 334                     char **domain,
 335                     char **name,
 336                     enum wbcSidType *name_type);
 337
 338 wbcErr wbcLookupRids(struct wbcDomainSid *dom_sid,
 339                      int num_rids,
 340                      uint32_t *rids,
 341                      const char **domain_name,
 342                      const char ***names,
 343                      enum wbcSidType **types);
 344
 345 wbcErr wbcLookupUserSids(const struct wbcDomainSid *user_sid,
 346                          bool domain_groups_only,
 347                          uint32_t *num_sids,
 348                          struct wbcDomainSid **sids);
 349
 350 wbcErr wbcListUsers(const char *domain_name,
 351                     uint32_t *num_users,
 352                     const char ***users);
 353
 354 wbcErr wbcListGroups(const char *domain_name,
 355                      uint32_t *num_groups,
 356                      const char ***groups);
 357
 358 /*
 359  * SID/uid/gid Mappings
 360  */
 361
 362 wbcErr wbcSidToUid(const struct wbcDomainSid *sid,
 363                    uid_t *puid);
 364
 365 wbcErr wbcUidToSid(uid_t uid,
 366                    struct wbcDomainSid *sid);
 367
 368 wbcErr wbcSidToGid(const struct wbcDomainSid *sid,
 369                    gid_t *pgid);
 370
 371 wbcErr wbcGidToSid(gid_t gid,
 372                    struct wbcDomainSid *sid);
 373
 374 wbcErr wbcAllocateUid(uid_t *puid);
 375
 376 wbcErr wbcAllocateGid(gid_t *pgid);
 377
 378 wbcErr wbcSetUidMapping(uid_t uid, const struct wbcDomainSid *sid);
 379
 380 wbcErr wbcSetGidMapping(gid_t gid, const struct wbcDomainSid *sid);
 381
 382 wbcErr wbcSetUidHwm(uid_t uid_hwm);
 383
 384 wbcErr wbcSetGidHwm(gid_t gid_hwm);
 385
 386 /*
 387  * NSS Lookup User/Group details
 388  */
 389
 390 wbcErr wbcGetpwnam(const char *name, struct passwd **pwd);
 391
 392 wbcErr wbcGetpwuid(uid_t uid, struct passwd **pwd);
 393
 394 wbcErr wbcGetgrnam(const char *name, struct group **grp);
 395
 396 wbcErr wbcGetgrgid(gid_t gid, struct group **grp);
 397
 398 wbcErr wbcSetpwent(void);
 399
 400 wbcErr wbcEndpwent(void);
 401
 402 wbcErr wbcGetpwent(struct passwd **pwd);
 403
 404 wbcErr wbcSetgrent(void);
 405
 406 wbcErr wbcEndgrent(void);
 407
 408 wbcErr wbcGetgrent(struct group **grp);
 409
 410 wbcErr wbcGetGroups(const char *account,
 411                     uint32_t *num_groups,
 412                     gid_t **_groups);
 413
 414
 415 /*
 416  * Lookup Domain information
 417  */
 418
 419 wbcErr wbcDomainInfo(const char *domain,
 420                      struct wbcDomainInfo **info);
 421
 422 wbcErr wbcListTrusts(struct wbcDomainInfo **domains,
 423                      size_t *num_domains);
 424
 425 /* Flags for wbcLookupDomainController */
 426
 427 #define WBC_LOOKUP_DC_FORCE_REDISCOVERY        0x00000001
 428 #define WBC_LOOKUP_DC_DS_REQUIRED              0x00000010
 429 #define WBC_LOOKUP_DC_DS_PREFERRED             0x00000020
 430 #define WBC_LOOKUP_DC_GC_SERVER_REQUIRED       0x00000040
 431 #define WBC_LOOKUP_DC_PDC_REQUIRED             0x00000080
 432 #define WBC_LOOKUP_DC_BACKGROUND_ONLY          0x00000100
 433 #define WBC_LOOKUP_DC_IP_REQUIRED              0x00000200
 434 #define WBC_LOOKUP_DC_KDC_REQUIRED             0x00000400
 435 #define WBC_LOOKUP_DC_TIMESERV_REQUIRED        0x00000800
 436 #define WBC_LOOKUP_DC_WRITABLE_REQUIRED        0x00001000
 437 #define WBC_LOOKUP_DC_GOOD_TIMESERV_PREFERRED  0x00002000
 438 #define WBC_LOOKUP_DC_AVOID_SELF               0x00004000
 439 #define WBC_LOOKUP_DC_ONLY_LDAP_NEEDED         0x00008000
 440 #define WBC_LOOKUP_DC_IS_FLAT_NAME             0x00010000
 441 #define WBC_LOOKUP_DC_IS_DNS_NAME              0x00020000
 442 #define WBC_LOOKUP_DC_TRY_NEXTCLOSEST_SITE     0x00040000
 443 #define WBC_LOOKUP_DC_DS_6_REQUIRED            0x00080000
 444 #define WBC_LOOKUP_DC_RETURN_DNS_NAME          0x40000000
 445 #define WBC_LOOKUP_DC_RETURN_FLAT_NAME         0x80000000
 446
 447 wbcErr wbcLookupDomainController(const char *domain,
 448                                  uint32_t flags,
 449                                  struct wbcDomainControllerInfo **dc_info);
 450
 451 /*
 452  * Athenticate functions
 453  */
 454
 455 wbcErr wbcAuthenticateUser(const char *username,
 456                            const char *password);
 457
 458 wbcErr wbcAuthenticateUserEx(const struct wbcAuthUserParams *params,
 459                              struct wbcAuthUserInfo **info,
 460                              struct wbcAuthErrorInfo **error);
 461
 462 wbcErr wbcLogoffUser(const char *username,
 463                      uid_t uid,
 464                      const char *ccfilename);
 465
 466
 467 /*
 468  * Resolve functions
 469  */
 470 wbcErr wbcResolveWinsByName(const char *name, char **ip);
 471 wbcErr wbcResolveWinsByIP(const char *ip, char **name);
 472
 473 /*
 474  * Trusted domain functions
 475  */
 476 wbcErr wbcCheckTrustCredentials(const char *domain,
 477                                 struct wbcAuthErrorInfo **error);
 478
 479
 480 #endif      /* _WBCLIENT_H */