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