nsswitch/libwbclient/wbclient.h

   1 /*
   2    Unix SMB/CIFS implementation.
   3
   4    Winbind client API
   5
   6    Copyright (C) Gerald (Jerry) Carter 2007
   7    Copyright (C) Volker Lendecke 2009
   8
   9    This library is free software; you can redistribute it and/or
  10    modify it under the terms of the GNU Lesser General Public
  11    License as published by the Free Software Foundation; either
  12    version 3 of the License, or (at your option) any later version.
  13
  14    This library is distributed in the hope that it will be useful,
  15    but WITHOUT ANY WARRANTY; without even the implied warranty of
  16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17    Library General Public License for more details.
  18
  19    You should have received a copy of the GNU Lesser General Public License
  20    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  21 */
  22
  23 #ifndef _WBCLIENT_H
  24 #define _WBCLIENT_H
  25
  26 #include <pwd.h>
  27 #include <grp.h>
  28
  29 /* Define error types */
  30
  31 /**
  32  *  @brief Status codes returned from wbc functions
  33  **/
  34
  35 enum _wbcErrType {
  36         WBC_ERR_SUCCESS = 0,    /**< Successful completion **/
  37         WBC_ERR_NOT_IMPLEMENTED,/**< Function not implemented **/
  38         WBC_ERR_UNKNOWN_FAILURE,/**< General failure **/
  39         WBC_ERR_NO_MEMORY,      /**< Memory allocation error **/
  40         WBC_ERR_INVALID_SID,    /**< Invalid SID format **/
  41         WBC_ERR_INVALID_PARAM,  /**< An Invalid parameter was supplied **/
  42         WBC_ERR_WINBIND_NOT_AVAILABLE,   /**< Winbind daemon is not available **/
  43         WBC_ERR_DOMAIN_NOT_FOUND,        /**< Domain is not trusted or cannot be found **/
  44         WBC_ERR_INVALID_RESPONSE,        /**< Winbind returned an invalid response **/
  45         WBC_ERR_NSS_ERROR,            /**< NSS_STATUS error **/
  46         WBC_ERR_AUTH_ERROR,        /**< Authentication failed **/
  47         WBC_ERR_UNKNOWN_USER,      /**< User account cannot be found */
  48         WBC_ERR_UNKNOWN_GROUP,     /**< Group account cannot be found */
  49         WBC_ERR_PWD_CHANGE_FAILED  /**< Password Change has failed */
  50 };
  51
  52 typedef enum _wbcErrType wbcErr;
  53
  54 #define WBC_ERROR_IS_OK(x) ((x) == WBC_ERR_SUCCESS)
  55
  56 const char *wbcErrorString(wbcErr error);
  57
  58 /**
  59  *  @brief Some useful details about the wbclient library
  60  *
  61  *  0.1: Initial version
  62  *  0.2: Added wbcRemoveUidMapping()
  63  *       Added wbcRemoveGidMapping()
  64  *  0.3: Added wbcGetpwsid()
  65  *       Added wbcGetSidAliases()
  66  *  0.4: Added wbcSidTypeString()
  67  *  0.5: Added wbcChangeTrustCredentials()
  68  *  0.6: Made struct wbcInterfaceDetails char* members non-const
  69  *  0.7: Added wbcSidToStringBuf()
  70  **/
  71 #define WBCLIENT_MAJOR_VERSION 0
  72 #define WBCLIENT_MINOR_VERSION 7
  73 #define WBCLIENT_VENDOR_VERSION "Samba libwbclient"
  74 struct wbcLibraryDetails {
  75         uint16_t major_version;
  76         uint16_t minor_version;
  77         const char *vendor_version;
  78 };
  79
  80 /**
  81  *  @brief Some useful details about the running winbindd
  82  *
  83  **/
  84 struct wbcInterfaceDetails {
  85         uint32_t interface_version;
  86         char *winbind_version;
  87         char winbind_separator;
  88         char *netbios_name;
  89         char *netbios_domain;
  90         char *dns_domain;
  91 };
  92
  93 /*
  94  * Data types used by the Winbind Client API
  95  */
  96
  97 #ifndef WBC_MAXSUBAUTHS
  98 #define WBC_MAXSUBAUTHS 15 /* max sub authorities in a SID */
  99 #endif
 100
 101 /**
 102  *  @brief Windows Security Identifier
 103  *
 104  **/
 105
 106 struct wbcDomainSid {
 107         uint8_t   sid_rev_num;
 108         uint8_t   num_auths;
 109         uint8_t   id_auth[6];
 110         uint32_t  sub_auths[WBC_MAXSUBAUTHS];
 111 };
 112
 113 /**
 114  * @brief Security Identifier type
 115  **/
 116
 117 enum wbcSidType {
 118         WBC_SID_NAME_USE_NONE=0,
 119         WBC_SID_NAME_USER=1,
 120         WBC_SID_NAME_DOM_GRP=2,
 121         WBC_SID_NAME_DOMAIN=3,
 122         WBC_SID_NAME_ALIAS=4,
 123         WBC_SID_NAME_WKN_GRP=5,
 124         WBC_SID_NAME_DELETED=6,
 125         WBC_SID_NAME_INVALID=7,
 126         WBC_SID_NAME_UNKNOWN=8,
 127         WBC_SID_NAME_COMPUTER=9
 128 };
 129
 130 /**
 131  * @brief Security Identifier with attributes
 132  **/
 133
 134 struct wbcSidWithAttr {
 135         struct wbcDomainSid sid;
 136         uint32_t attributes;
 137 };
 138
 139 /* wbcSidWithAttr->attributes */
 140
 141 #define WBC_SID_ATTR_GROUP_MANDATORY            0x00000001
 142 #define WBC_SID_ATTR_GROUP_ENABLED_BY_DEFAULT   0x00000002
 143 #define WBC_SID_ATTR_GROUP_ENABLED              0x00000004
 144 #define WBC_SID_ATTR_GROUP_OWNER                0x00000008
 145 #define WBC_SID_ATTR_GROUP_USEFOR_DENY_ONLY     0x00000010
 146 #define WBC_SID_ATTR_GROUP_RESOURCE             0x20000000
 147 #define WBC_SID_ATTR_GROUP_LOGON_ID             0xC0000000
 148
 149 /**
 150  *  @brief Windows GUID
 151  *
 152  **/
 153
 154 struct wbcGuid {
 155         uint32_t time_low;
 156         uint16_t time_mid;
 157         uint16_t time_hi_and_version;
 158         uint8_t clock_seq[2];
 159         uint8_t node[6];
 160 };
 161
 162 /**
 163  * @brief Domain Information
 164  **/
 165
 166 struct wbcDomainInfo {
 167         char *short_name;
 168         char *dns_name;
 169         struct wbcDomainSid sid;
 170         uint32_t domain_flags;
 171         uint32_t trust_flags;
 172         uint32_t trust_type;
 173 };
 174
 175 /* wbcDomainInfo->domain_flags */
 176
 177 #define WBC_DOMINFO_DOMAIN_UNKNOWN    0x00000000
 178 #define WBC_DOMINFO_DOMAIN_NATIVE     0x00000001
 179 #define WBC_DOMINFO_DOMAIN_AD         0x00000002
 180 #define WBC_DOMINFO_DOMAIN_PRIMARY    0x00000004
 181 #define WBC_DOMINFO_DOMAIN_OFFLINE    0x00000008
 182
 183 /* wbcDomainInfo->trust_flags */
 184
 185 #define WBC_DOMINFO_TRUST_TRANSITIVE  0x00000001
 186 #define WBC_DOMINFO_TRUST_INCOMING    0x00000002
 187 #define WBC_DOMINFO_TRUST_OUTGOING    0x00000004
 188
 189 /* wbcDomainInfo->trust_type */
 190
 191 #define WBC_DOMINFO_TRUSTTYPE_NONE       0x00000000
 192 #define WBC_DOMINFO_TRUSTTYPE_FOREST     0x00000001
 193 #define WBC_DOMINFO_TRUSTTYPE_IN_FOREST  0x00000002
 194 #define WBC_DOMINFO_TRUSTTYPE_EXTERNAL   0x00000003
 195
 196 /**
 197  * @brief Auth User Parameters
 198  **/
 199
 200 struct wbcAuthUserParams {
 201         const char *account_name;
 202         const char *domain_name;
 203         const char *workstation_name;
 204
 205         uint32_t flags;
 206
 207         uint32_t parameter_control;
 208
 209         enum wbcAuthUserLevel {
 210                 WBC_AUTH_USER_LEVEL_PLAIN = 1,
 211                 WBC_AUTH_USER_LEVEL_HASH = 2,
 212                 WBC_AUTH_USER_LEVEL_RESPONSE = 3
 213         } level;
 214         union {
 215                 const char *plaintext;
 216                 struct {
 217                         uint8_t nt_hash[16];
 218                         uint8_t lm_hash[16];
 219                 } hash;
 220                 struct {
 221                         uint8_t challenge[8];
 222                         uint32_t nt_length;
 223                         uint8_t *nt_data;
 224                         uint32_t lm_length;
 225                         uint8_t *lm_data;
 226                 } response;
 227         } password;
 228 };
 229
 230 /**
 231  * @brief Generic Blob
 232  **/
 233
 234 struct wbcBlob {
 235         uint8_t *data;
 236         size_t length;
 237 };
 238
 239 /**
 240  * @brief Named Blob
 241  **/
 242
 243 struct wbcNamedBlob {
 244         const char *name;
 245         uint32_t flags;
 246         struct wbcBlob blob;
 247 };
 248
 249 /**
 250  * @brief Logon User Parameters
 251  **/
 252
 253 struct wbcLogonUserParams {
 254         const char *username;
 255         const char *password;
 256         size_t num_blobs;
 257         struct wbcNamedBlob *blobs;
 258 };
 259
 260 /**
 261  * @brief ChangePassword Parameters
 262  **/
 263
 264 struct wbcChangePasswordParams {
 265         const char *account_name;
 266         const char *domain_name;
 267
 268         uint32_t flags;
 269
 270         enum wbcChangePasswordLevel {
 271                 WBC_CHANGE_PASSWORD_LEVEL_PLAIN = 1,
 272                 WBC_CHANGE_PASSWORD_LEVEL_RESPONSE = 2
 273         } level;
 274
 275         union {
 276                 const char *plaintext;
 277                 struct {
 278                         uint32_t old_nt_hash_enc_length;
 279                         uint8_t *old_nt_hash_enc_data;
 280                         uint32_t old_lm_hash_enc_length;
 281                         uint8_t *old_lm_hash_enc_data;
 282                 } response;
 283         } old_password;
 284         union {
 285                 const char *plaintext;
 286                 struct {
 287                         uint32_t nt_length;
 288                         uint8_t *nt_data;
 289                         uint32_t lm_length;
 290                         uint8_t *lm_data;
 291                 } response;
 292         } new_password;
 293 };
 294
 295 /* wbcAuthUserParams->parameter_control */
 296
 297 #define WBC_MSV1_0_CLEARTEXT_PASSWORD_ALLOWED           0x00000002
 298 #define WBC_MSV1_0_UPDATE_LOGON_STATISTICS              0x00000004
 299 #define WBC_MSV1_0_RETURN_USER_PARAMETERS               0x00000008
 300 #define WBC_MSV1_0_ALLOW_SERVER_TRUST_ACCOUNT           0x00000020
 301 #define WBC_MSV1_0_RETURN_PROFILE_PATH                  0x00000200
 302 #define WBC_MSV1_0_ALLOW_WORKSTATION_TRUST_ACCOUNT      0x00000800
 303
 304 /* wbcAuthUserParams->flags */
 305
 306 #define WBC_AUTH_PARAM_FLAGS_INTERACTIVE_LOGON          0x00000001
 307
 308 /**
 309  * @brief Auth User Information
 310  *
 311  * Some of the strings are maybe NULL
 312  **/
 313
 314 struct wbcAuthUserInfo {
 315         uint32_t user_flags;
 316
 317         char *account_name;
 318         char *user_principal;
 319         char *full_name;
 320         char *domain_name;
 321         char *dns_domain_name;
 322
 323         uint32_t acct_flags;
 324         uint8_t user_session_key[16];
 325         uint8_t lm_session_key[8];
 326
 327         uint16_t logon_count;
 328         uint16_t bad_password_count;
 329
 330         uint64_t logon_time;
 331         uint64_t logoff_time;
 332         uint64_t kickoff_time;
 333         uint64_t pass_last_set_time;
 334         uint64_t pass_can_change_time;
 335         uint64_t pass_must_change_time;
 336
 337         char *logon_server;
 338         char *logon_script;
 339         char *profile_path;
 340         char *home_directory;
 341         char *home_drive;
 342
 343         /*
 344          * the 1st one is the account sid
 345          * the 2nd one is the primary_group sid
 346          * followed by the rest of the groups
 347          */
 348         uint32_t num_sids;
 349         struct wbcSidWithAttr *sids;
 350 };
 351
 352 /**
 353  * @brief Logon User Information
 354  *
 355  * Some of the strings are maybe NULL
 356  **/
 357
 358 struct wbcLogonUserInfo {
 359         struct wbcAuthUserInfo *info;
 360         size_t num_blobs;
 361         struct wbcNamedBlob *blobs;
 362 };
 363
 364 /* wbcAuthUserInfo->user_flags */
 365
 366 #define WBC_AUTH_USER_INFO_GUEST                        0x00000001
 367 #define WBC_AUTH_USER_INFO_NOENCRYPTION                 0x00000002
 368 #define WBC_AUTH_USER_INFO_CACHED_ACCOUNT               0x00000004
 369 #define WBC_AUTH_USER_INFO_USED_LM_PASSWORD             0x00000008
 370 #define WBC_AUTH_USER_INFO_EXTRA_SIDS                   0x00000020
 371 #define WBC_AUTH_USER_INFO_SUBAUTH_SESSION_KEY          0x00000040
 372 #define WBC_AUTH_USER_INFO_SERVER_TRUST_ACCOUNT         0x00000080
 373 #define WBC_AUTH_USER_INFO_NTLMV2_ENABLED               0x00000100
 374 #define WBC_AUTH_USER_INFO_RESOURCE_GROUPS              0x00000200
 375 #define WBC_AUTH_USER_INFO_PROFILE_PATH_RETURNED        0x00000400
 376 #define WBC_AUTH_USER_INFO_GRACE_LOGON                  0x01000000
 377
 378 /* wbcAuthUserInfo->acct_flags */
 379
 380 #define WBC_ACB_DISABLED                        0x00000001 /* 1 User account disabled */
 381 #define WBC_ACB_HOMDIRREQ                       0x00000002 /* 1 Home directory required */
 382 #define WBC_ACB_PWNOTREQ                        0x00000004 /* 1 User password not required */
 383 #define WBC_ACB_TEMPDUP                         0x00000008 /* 1 Temporary duplicate account */
 384 #define WBC_ACB_NORMAL                          0x00000010 /* 1 Normal user account */
 385 #define WBC_ACB_MNS                             0x00000020 /* 1 MNS logon user account */
 386 #define WBC_ACB_DOMTRUST                        0x00000040 /* 1 Interdomain trust account */
 387 #define WBC_ACB_WSTRUST                         0x00000080 /* 1 Workstation trust account */
 388 #define WBC_ACB_SVRTRUST                        0x00000100 /* 1 Server trust account */
 389 #define WBC_ACB_PWNOEXP                         0x00000200 /* 1 User password does not expire */
 390 #define WBC_ACB_AUTOLOCK                        0x00000400 /* 1 Account auto locked */
 391 #define WBC_ACB_ENC_TXT_PWD_ALLOWED             0x00000800 /* 1 Encryped text password is allowed */
 392 #define WBC_ACB_SMARTCARD_REQUIRED              0x00001000 /* 1 Smart Card required */
 393 #define WBC_ACB_TRUSTED_FOR_DELEGATION          0x00002000 /* 1 Trusted for Delegation */
 394 #define WBC_ACB_NOT_DELEGATED                   0x00004000 /* 1 Not delegated */
 395 #define WBC_ACB_USE_DES_KEY_ONLY                0x00008000 /* 1 Use DES key only */
 396 #define WBC_ACB_DONT_REQUIRE_PREAUTH            0x00010000 /* 1 Preauth not required */
 397 #define WBC_ACB_PW_EXPIRED                      0x00020000 /* 1 Password Expired */
 398 #define WBC_ACB_NO_AUTH_DATA_REQD               0x00080000   /* 1 = No authorization data required */
 399
 400 struct wbcAuthErrorInfo {
 401         uint32_t nt_status;
 402         char *nt_string;
 403         int32_t pam_error;
 404         char *display_string;
 405 };
 406
 407 /**
 408  * @brief User Password Policy Information
 409  **/
 410
 411 /* wbcUserPasswordPolicyInfo->password_properties */
 412
 413 #define WBC_DOMAIN_PASSWORD_COMPLEX             0x00000001
 414 #define WBC_DOMAIN_PASSWORD_NO_ANON_CHANGE      0x00000002
 415 #define WBC_DOMAIN_PASSWORD_NO_CLEAR_CHANGE     0x00000004
 416 #define WBC_DOMAIN_PASSWORD_LOCKOUT_ADMINS      0x00000008
 417 #define WBC_DOMAIN_PASSWORD_STORE_CLEARTEXT     0x00000010
 418 #define WBC_DOMAIN_REFUSE_PASSWORD_CHANGE       0x00000020
 419
 420 struct wbcUserPasswordPolicyInfo {
 421         uint32_t min_length_password;
 422         uint32_t password_history;
 423         uint32_t password_properties;
 424         uint64_t expire;
 425         uint64_t min_passwordage;
 426 };
 427
 428 /**
 429  * @brief Change Password Reject Reason
 430  **/
 431
 432 enum wbcPasswordChangeRejectReason {
 433         WBC_PWD_CHANGE_NO_ERROR=0,
 434         WBC_PWD_CHANGE_PASSWORD_TOO_SHORT=1,
 435         WBC_PWD_CHANGE_PWD_IN_HISTORY=2,
 436         WBC_PWD_CHANGE_USERNAME_IN_PASSWORD=3,
 437         WBC_PWD_CHANGE_FULLNAME_IN_PASSWORD=4,
 438         WBC_PWD_CHANGE_NOT_COMPLEX=5,
 439         WBC_PWD_CHANGE_MACHINE_NOT_DEFAULT=6,
 440         WBC_PWD_CHANGE_FAILED_BY_FILTER=7,
 441         WBC_PWD_CHANGE_PASSWORD_TOO_LONG=8
 442 };
 443
 444 /* Note: this defines exist for compatibility reasons with existing code */
 445 #define WBC_PWD_CHANGE_REJECT_OTHER      WBC_PWD_CHANGE_NO_ERROR
 446 #define WBC_PWD_CHANGE_REJECT_TOO_SHORT  WBC_PWD_CHANGE_PASSWORD_TOO_SHORT
 447 #define WBC_PWD_CHANGE_REJECT_IN_HISTORY WBC_PWD_CHANGE_PWD_IN_HISTORY
 448 #define WBC_PWD_CHANGE_REJECT_COMPLEXITY WBC_PWD_CHANGE_NOT_COMPLEX
 449
 450 /**
 451  * @brief Logoff User Parameters
 452  **/
 453
 454 struct wbcLogoffUserParams {
 455         const char *username;
 456         size_t num_blobs;
 457         struct wbcNamedBlob *blobs;
 458 };
 459
 460 /** @brief Credential cache log-on parameters
 461  *
 462  */
 463
 464 struct wbcCredentialCacheParams {
 465         const char *account_name;
 466         const char *domain_name;
 467         enum wbcCredentialCacheLevel {
 468                 WBC_CREDENTIAL_CACHE_LEVEL_NTLMSSP = 1
 469         } level;
 470         size_t num_blobs;
 471         struct wbcNamedBlob *blobs;
 472 };
 473
 474
 475 /** @brief Info returned by credential cache auth
 476  *
 477  */
 478
 479 struct wbcCredentialCacheInfo {
 480         size_t num_blobs;
 481         struct wbcNamedBlob *blobs;
 482 };
 483
 484 /*
 485  * DomainControllerInfo struct
 486  */
 487 struct wbcDomainControllerInfo {
 488         char *dc_name;
 489 };
 490
 491 /*
 492  * DomainControllerInfoEx struct
 493  */
 494 struct wbcDomainControllerInfoEx {
 495         const char *dc_unc;
 496         const char *dc_address;
 497         uint16_t dc_address_type;
 498         struct wbcGuid *domain_guid;
 499         const char *domain_name;
 500         const char *forest_name;
 501         uint32_t dc_flags;
 502         const char *dc_site_name;
 503         const char *client_site_name;
 504 };
 505
 506 /**********************************************************
 507  * Memory Management
 508  **********************************************************/
 509
 510 /**
 511  * @brief Free library allocated memory
 512  *
 513  * @param * Pointer to free
 514  *
 515  * @return void
 516  **/
 517 void wbcFreeMemory(void*);
 518
 519
 520 /*
 521  * Utility functions for dealing with SIDs
 522  */
 523
 524 /**
 525  * @brief Get a string representation of the SID type
 526  *
 527  * @param type          type of the SID
 528  *
 529  * @return string representation of the SID type
 530  */
 531 const char* wbcSidTypeString(enum wbcSidType type);
 532
 533 #define WBC_SID_STRING_BUFLEN (15*11+25)
 534
 535 /*
 536  * @brief Print a sid into a buffer
 537  *
 538  * @param sid           Binary Security Identifier
 539  * @param buf           Target buffer
 540  * @param buflen        Target buffer length
 541  *
 542  * @return Resulting string length.
 543  */
 544 int wbcSidToStringBuf(const struct wbcDomainSid *sid, char *buf, int buflen);
 545
 546 /**
 547  * @brief Convert a binary SID to a character string
 548  *
 549  * @param sid           Binary Security Identifier
 550  * @param **sid_string  Resulting character string
 551  *
 552  * @return #wbcErr
 553  **/
 554 wbcErr wbcSidToString(const struct wbcDomainSid *sid,
 555                       char **sid_string);
 556
 557 /**
 558  * @brief Convert a character string to a binary SID
 559  *
 560  * @param *sid_string   Character string in the form of S-...
 561  * @param sid           Resulting binary SID
 562  *
 563  * @return #wbcErr
 564  **/
 565 wbcErr wbcStringToSid(const char *sid_string,
 566                       struct wbcDomainSid *sid);
 567
 568 /*
 569  * Utility functions for dealing with GUIDs
 570  */
 571
 572 /**
 573  * @brief Convert a binary GUID to a character string
 574  *
 575  * @param guid           Binary Guid
 576  * @param **guid_string  Resulting character string
 577  *
 578  * @return #wbcErr
 579  **/
 580 wbcErr wbcGuidToString(const struct wbcGuid *guid,
 581                        char **guid_string);
 582
 583 /**
 584  * @brief Convert a character string to a binary GUID
 585  *
 586  * @param *guid_string  Character string
 587  * @param guid          Resulting binary GUID
 588  *
 589  * @return #wbcErr
 590  **/
 591 wbcErr wbcStringToGuid(const char *guid_string,
 592                        struct wbcGuid *guid);
 593
 594 /**
 595  * @brief Ping winbindd to see if the daemon is running
 596  *
 597  * @return #wbcErr
 598  **/
 599 wbcErr wbcPing(void);
 600
 601 wbcErr wbcLibraryDetails(struct wbcLibraryDetails **details);
 602
 603 wbcErr wbcInterfaceDetails(struct wbcInterfaceDetails **details);
 604
 605 /**********************************************************
 606  * Name/SID conversion
 607  **********************************************************/
 608
 609 /**
 610  * @brief Convert a domain and name to SID
 611  *
 612  * @param dom_name    Domain name (possibly "")
 613  * @param name        User or group name
 614  * @param *sid        Pointer to the resolved domain SID
 615  * @param *name_type  Pointer to the SID type
 616  *
 617  * @return #wbcErr
 618  **/
 619 wbcErr wbcLookupName(const char *dom_name,
 620                      const char *name,
 621                      struct wbcDomainSid *sid,
 622                      enum wbcSidType *name_type);
 623
 624 /**
 625  * @brief Convert a SID to a domain and name
 626  *
 627  * @param *sid        Pointer to the domain SID to be resolved
 628  * @param domain     Resolved Domain name (possibly "")
 629  * @param name       Resolved User or group name
 630  * @param *name_type Pointer to the resolved SID type
 631  *
 632  * @return #wbcErr
 633  **/
 634 wbcErr wbcLookupSid(const struct wbcDomainSid *sid,
 635                     char **domain,
 636                     char **name,
 637                     enum wbcSidType *name_type);
 638
 639 /**
 640  * @brief Translate a collection of RIDs within a domain to names
 641  */
 642 wbcErr wbcLookupRids(struct wbcDomainSid *dom_sid,
 643                      int num_rids,
 644                      uint32_t *rids,
 645                      const char **domain_name,
 646                      const char ***names,
 647                      enum wbcSidType **types);
 648
 649 /*
 650  * @brief Get the groups a user belongs to
 651  **/
 652 wbcErr wbcLookupUserSids(const struct wbcDomainSid *user_sid,
 653                          bool domain_groups_only,
 654                          uint32_t *num_sids,
 655                          struct wbcDomainSid **sids);
 656
 657 /*
 658  * @brief Get alias membership for sids
 659  **/
 660 wbcErr wbcGetSidAliases(const struct wbcDomainSid *dom_sid,
 661                         struct wbcDomainSid *sids,
 662                         uint32_t num_sids,
 663                         uint32_t **alias_rids,
 664                         uint32_t *num_alias_rids);
 665
 666 /**
 667  * @brief Lists Users
 668  **/
 669 wbcErr wbcListUsers(const char *domain_name,
 670                     uint32_t *num_users,
 671                     const char ***users);
 672
 673 /**
 674  * @brief Lists Groups
 675  **/
 676 wbcErr wbcListGroups(const char *domain_name,
 677                      uint32_t *num_groups,
 678                      const char ***groups);
 679
 680 wbcErr wbcGetDisplayName(const struct wbcDomainSid *sid,
 681                          char **pdomain,
 682                          char **pfullname,
 683                          enum wbcSidType *pname_type);
 684
 685 /**********************************************************
 686  * SID/uid/gid Mappings
 687  **********************************************************/
 688
 689 /**
 690  * @brief Convert a Windows SID to a Unix uid, allocating an uid if needed
 691  *
 692  * @param *sid        Pointer to the domain SID to be resolved
 693  * @param *puid       Pointer to the resolved uid_t value
 694  *
 695  * @return #wbcErr
 696  *
 697  **/
 698 wbcErr wbcSidToUid(const struct wbcDomainSid *sid,
 699                    uid_t *puid);
 700
 701 /**
 702  * @brief Convert a Windows SID to a Unix uid if there already is a mapping
 703  *
 704  * @param *sid        Pointer to the domain SID to be resolved
 705  * @param *puid       Pointer to the resolved uid_t value
 706  *
 707  * @return #wbcErr
 708  *
 709  **/
 710 wbcErr wbcQuerySidToUid(const struct wbcDomainSid *sid,
 711                         uid_t *puid);
 712
 713 /**
 714  * @brief Convert a Unix uid to a Windows SID, allocating a SID if needed
 715  *
 716  * @param uid         Unix uid to be resolved
 717  * @param *sid        Pointer to the resolved domain SID
 718  *
 719  * @return #wbcErr
 720  *
 721  **/
 722 wbcErr wbcUidToSid(uid_t uid,
 723                    struct wbcDomainSid *sid);
 724
 725 /**
 726  * @brief Convert a Unix uid to a Windows SID if there already is a mapping
 727  *
 728  * @param uid         Unix uid to be resolved
 729  * @param *sid        Pointer to the resolved domain SID
 730  *
 731  * @return #wbcErr
 732  *
 733  **/
 734 wbcErr wbcQueryUidToSid(uid_t uid,
 735                         struct wbcDomainSid *sid);
 736
 737 /**
 738  * @brief Convert a Windows SID to a Unix gid, allocating a gid if needed
 739  *
 740  * @param *sid        Pointer to the domain SID to be resolved
 741  * @param *pgid       Pointer to the resolved gid_t value
 742  *
 743  * @return #wbcErr
 744  *
 745  **/
 746 wbcErr wbcSidToGid(const struct wbcDomainSid *sid,
 747                    gid_t *pgid);
 748
 749 /**
 750  * @brief Convert a Windows SID to a Unix gid if there already is a mapping
 751  *
 752  * @param *sid        Pointer to the domain SID to be resolved
 753  * @param *pgid       Pointer to the resolved gid_t value
 754  *
 755  * @return #wbcErr
 756  *
 757  **/
 758 wbcErr wbcQuerySidToGid(const struct wbcDomainSid *sid,
 759                         gid_t *pgid);
 760
 761 /**
 762  * @brief Convert a Unix gid to a Windows SID, allocating a SID if needed
 763  *
 764  * @param gid         Unix gid to be resolved
 765  * @param *sid        Pointer to the resolved domain SID
 766  *
 767  * @return #wbcErr
 768  *
 769  **/
 770 wbcErr wbcGidToSid(gid_t gid,
 771                    struct wbcDomainSid *sid);
 772
 773 /**
 774  * @brief Convert a Unix gid to a Windows SID if there already is a mapping
 775  *
 776  * @param gid         Unix gid to be resolved
 777  * @param *sid        Pointer to the resolved domain SID
 778  *
 779  * @return #wbcErr
 780  *
 781  **/
 782 wbcErr wbcQueryGidToSid(gid_t gid,
 783                         struct wbcDomainSid *sid);
 784
 785 /**
 786  * @brief Obtain a new uid from Winbind
 787  *
 788  * @param *puid      *pointer to the allocated uid
 789  *
 790  * @return #wbcErr
 791  **/
 792 wbcErr wbcAllocateUid(uid_t *puid);
 793
 794 /**
 795  * @brief Obtain a new gid from Winbind
 796  *
 797  * @param *pgid      Pointer to the allocated gid
 798  *
 799  * @return #wbcErr
 800  **/
 801 wbcErr wbcAllocateGid(gid_t *pgid);
 802
 803 /**
 804  * @brief Set an user id mapping
 805  *
 806  * @param uid       Uid of the desired mapping.
 807  * @param *sid      Pointer to the sid of the diresired mapping.
 808  *
 809  * @return #wbcErr
 810  *
 811  * @deprecated      This method is not impemented any more and should
 812  *                  be removed in the next major version change.
 813  **/
 814 wbcErr wbcSetUidMapping(uid_t uid, const struct wbcDomainSid *sid);
 815
 816 /**
 817  * @brief Set a group id mapping
 818  *
 819  * @param gid       Gid of the desired mapping.
 820  * @param *sid      Pointer to the sid of the diresired mapping.
 821  *
 822  * @return #wbcErr
 823  *
 824  * @deprecated      This method is not impemented any more and should
 825  *                  be removed in the next major version change.
 826  **/
 827 wbcErr wbcSetGidMapping(gid_t gid, const struct wbcDomainSid *sid);
 828
 829 /**
 830  * @brief Remove a user id mapping
 831  *
 832  * @param uid       Uid of the mapping to remove.
 833  * @param *sid      Pointer to the sid of the mapping to remove.
 834  *
 835  * @return #wbcErr
 836  *
 837  * @deprecated      This method is not impemented any more and should
 838  *                  be removed in the next major version change.
 839  **/
 840 wbcErr wbcRemoveUidMapping(uid_t uid, const struct wbcDomainSid *sid);
 841
 842 /**
 843  * @brief Remove a group id mapping
 844  *
 845  * @param gid       Gid of the mapping to remove.
 846  * @param *sid      Pointer to the sid of the mapping to remove.
 847  *
 848  * @return #wbcErr
 849  *
 850  * @deprecated      This method is not impemented any more and should
 851  *                  be removed in the next major version change.
 852  **/
 853 wbcErr wbcRemoveGidMapping(gid_t gid, const struct wbcDomainSid *sid);
 854
 855 /**
 856  * @brief Set the highwater mark for allocated uids.
 857  *
 858  * @param uid_hwm      The new uid highwater mark value
 859  *
 860  * @return #wbcErr
 861  *
 862  * @deprecated      This method is not impemented any more and should
 863  *                  be removed in the next major version change.
 864  **/
 865 wbcErr wbcSetUidHwm(uid_t uid_hwm);
 866
 867 /**
 868  * @brief Set the highwater mark for allocated gids.
 869  *
 870  * @param gid_hwm      The new gid highwater mark value
 871  *
 872  * @return #wbcErr
 873  *
 874  * @deprecated      This method is not impemented any more and should
 875  *                  be removed in the next major version change.
 876  **/
 877 wbcErr wbcSetGidHwm(gid_t gid_hwm);
 878
 879 /**********************************************************
 880  * NSS Lookup User/Group details
 881  **********************************************************/
 882
 883 /**
 884  * @brief Fill in a struct passwd* for a domain user based
 885  *   on username
 886  *
 887  * @param *name     Username to lookup
 888  * @param **pwd     Pointer to resulting struct passwd* from the query.
 889  *
 890  * @return #wbcErr
 891  **/
 892 wbcErr wbcGetpwnam(const char *name, struct passwd **pwd);
 893
 894 /**
 895  * @brief Fill in a struct passwd* for a domain user based
 896  *   on uid
 897  *
 898  * @param uid       Uid to lookup
 899  * @param **pwd     Pointer to resulting struct passwd* from the query.
 900  *
 901  * @return #wbcErr
 902  **/
 903 wbcErr wbcGetpwuid(uid_t uid, struct passwd **pwd);
 904
 905 /**
 906  * @brief Fill in a struct passwd* for a domain user based
 907  *   on sid
 908  *
 909  * @param sid       Sid to lookup
 910  * @param **pwd     Pointer to resulting struct passwd* from the query.
 911  *
 912  * @return #wbcErr
 913  **/
 914 wbcErr wbcGetpwsid(struct wbcDomainSid * sid, struct passwd **pwd);
 915
 916 /**
 917  * @brief Fill in a struct passwd* for a domain user based
 918  *   on username
 919  *
 920  * @param *name     Username to lookup
 921  * @param **grp     Pointer to resulting struct group* from the query.
 922  *
 923  * @return #wbcErr
 924  **/
 925 wbcErr wbcGetgrnam(const char *name, struct group **grp);
 926
 927 /**
 928  * @brief Fill in a struct passwd* for a domain user based
 929  *   on uid
 930  *
 931  * @param gid       Uid to lookup
 932  * @param **grp     Pointer to resulting struct group* from the query.
 933  *
 934  * @return #wbcErr
 935  **/
 936 wbcErr wbcGetgrgid(gid_t gid, struct group **grp);
 937
 938 /**
 939  * @brief Reset the passwd iterator
 940  *
 941  * @return #wbcErr
 942  **/
 943 wbcErr wbcSetpwent(void);
 944
 945 /**
 946  * @brief Close the passwd iterator
 947  *
 948  * @return #wbcErr
 949  **/
 950 wbcErr wbcEndpwent(void);
 951
 952 /**
 953  * @brief Return the next struct passwd* entry from the pwent iterator
 954  *
 955  * @param **pwd       Pointer to resulting struct passwd* from the query.
 956  *
 957  * @return #wbcErr
 958  **/
 959 wbcErr wbcGetpwent(struct passwd **pwd);
 960
 961 /**
 962  * @brief Reset the group iterator
 963  *
 964  * @return #wbcErr
 965  **/
 966 wbcErr wbcSetgrent(void);
 967
 968 /**
 969  * @brief Close the group iterator
 970  *
 971  * @return #wbcErr
 972  **/
 973 wbcErr wbcEndgrent(void);
 974
 975 /**
 976  * @brief Return the next struct group* entry from the pwent iterator
 977  *
 978  * @param **grp       Pointer to resulting struct group* from the query.
 979  *
 980  * @return #wbcErr
 981  **/
 982 wbcErr wbcGetgrent(struct group **grp);
 983
 984 /**
 985  * @brief Return the next struct group* entry from the pwent iterator
 986  *
 987  * This is similar to #wbcGetgrent, just that the member list is empty
 988  *
 989  * @param **grp       Pointer to resulting struct group* from the query.
 990  *
 991  * @return #wbcErr
 992  **/
 993 wbcErr wbcGetgrlist(struct group **grp);
 994
 995 /**
 996  * @brief Return the unix group array belonging to the given user
 997  *
 998  * @param *account       The given user name
 999  * @param *num_groups    Number of elements returned in the groups array
1000  * @param **_groups      Pointer to resulting gid_t array.
1001  *
1002  * @return #wbcErr
1003  **/
1004 wbcErr wbcGetGroups(const char *account,
1005                     uint32_t *num_groups,
1006                     gid_t **_groups);
1007
1008
1009 /**********************************************************
1010  * Lookup Domain information
1011  **********************************************************/
1012
1013 /**
1014  * @brief Lookup the current status of a trusted domain
1015  *
1016  * @param domain        The domain to query
1017  *
1018  * @param dinfo          A pointer to store the returned domain_info struct.
1019  *
1020  * @return #wbcErr
1021  **/
1022 wbcErr wbcDomainInfo(const char *domain,
1023                      struct wbcDomainInfo **dinfo);
1024
1025 /**
1026  * @brief Lookup the currently contacted DCs
1027  *
1028  * @param domain        The domain to query
1029  *
1030  * @param num_dcs       Number of DCs currently known
1031  * @param dc_names      Names of the currently known DCs
1032  * @param dc_ips        IP addresses of the currently known DCs
1033  *
1034  * @return #wbcErr
1035  **/
1036 wbcErr wbcDcInfo(const char *domain, size_t *num_dcs,
1037                  const char ***dc_names, const char ***dc_ips);
1038
1039 /**
1040  * @brief Enumerate the domain trusts known by Winbind
1041  *
1042  * @param **domains     Pointer to the allocated domain list array
1043  * @param *num_domains  Pointer to number of domains returned
1044  *
1045  * @return #wbcErr
1046  **/
1047 wbcErr wbcListTrusts(struct wbcDomainInfo **domains,
1048                      size_t *num_domains);
1049
1050 /* Flags for wbcLookupDomainController */
1051
1052 #define WBC_LOOKUP_DC_FORCE_REDISCOVERY        0x00000001
1053 #define WBC_LOOKUP_DC_DS_REQUIRED              0x00000010
1054 #define WBC_LOOKUP_DC_DS_PREFERRED             0x00000020
1055 #define WBC_LOOKUP_DC_GC_SERVER_REQUIRED       0x00000040
1056 #define WBC_LOOKUP_DC_PDC_REQUIRED             0x00000080
1057 #define WBC_LOOKUP_DC_BACKGROUND_ONLY          0x00000100
1058 #define WBC_LOOKUP_DC_IP_REQUIRED              0x00000200
1059 #define WBC_LOOKUP_DC_KDC_REQUIRED             0x00000400
1060 #define WBC_LOOKUP_DC_TIMESERV_REQUIRED        0x00000800
1061 #define WBC_LOOKUP_DC_WRITABLE_REQUIRED        0x00001000
1062 #define WBC_LOOKUP_DC_GOOD_TIMESERV_PREFERRED  0x00002000
1063 #define WBC_LOOKUP_DC_AVOID_SELF               0x00004000
1064 #define WBC_LOOKUP_DC_ONLY_LDAP_NEEDED         0x00008000
1065 #define WBC_LOOKUP_DC_IS_FLAT_NAME             0x00010000
1066 #define WBC_LOOKUP_DC_IS_DNS_NAME              0x00020000
1067 #define WBC_LOOKUP_DC_TRY_NEXTCLOSEST_SITE     0x00040000
1068 #define WBC_LOOKUP_DC_DS_6_REQUIRED            0x00080000
1069 #define WBC_LOOKUP_DC_RETURN_DNS_NAME          0x40000000
1070 #define WBC_LOOKUP_DC_RETURN_FLAT_NAME         0x80000000
1071
1072 /**
1073  * @brief Enumerate the domain trusts known by Winbind
1074  *
1075  * @param domain        Name of the domain to query for a DC
1076  * @param flags         Bit flags used to control the domain location query
1077  * @param *dc_info      Pointer to the returned domain controller information
1078  *
1079  * @return #wbcErr
1080  **/
1081 wbcErr wbcLookupDomainController(const char *domain,
1082                                  uint32_t flags,
1083                                  struct wbcDomainControllerInfo **dc_info);
1084
1085 /**
1086  * @brief Get extended domain controller information
1087  *
1088  * @param domain        Name of the domain to query for a DC
1089  * @param guid          Guid of the domain to query for a DC
1090  * @param site          Site of the domain to query for a DC
1091  * @param flags         Bit flags used to control the domain location query
1092  * @param *dc_info      Pointer to the returned extended domain controller information
1093  *
1094  * @return #wbcErr
1095  **/
1096 wbcErr wbcLookupDomainControllerEx(const char *domain,
1097                                    struct wbcGuid *guid,
1098                                    const char *site,
1099                                    uint32_t flags,
1100                                    struct wbcDomainControllerInfoEx **dc_info);
1101
1102 /**********************************************************
1103  * Athenticate functions
1104  **********************************************************/
1105
1106 /**
1107  * @brief Authenticate a username/password pair
1108  *
1109  * @param username     Name of user to authenticate
1110  * @param password     Clear text password os user
1111  *
1112  * @return #wbcErr
1113  **/
1114 wbcErr wbcAuthenticateUser(const char *username,
1115                            const char *password);
1116
1117 /**
1118  * @brief Authenticate with more detailed information
1119  *
1120  * @param params       Input parameters, WBC_AUTH_USER_LEVEL_HASH
1121  *                     is not supported yet
1122  * @param info         Output details on WBC_ERR_SUCCESS
1123  * @param error        Output details on WBC_ERR_AUTH_ERROR
1124  *
1125  * @return #wbcErr
1126  **/
1127 wbcErr wbcAuthenticateUserEx(const struct wbcAuthUserParams *params,
1128                              struct wbcAuthUserInfo **info,
1129                              struct wbcAuthErrorInfo **error);
1130
1131 /**
1132  * @brief Logon a User
1133  *
1134  * @param[in]  params      Pointer to a wbcLogonUserParams structure
1135  * @param[out] info        Pointer to a pointer to a wbcLogonUserInfo structure
1136  * @param[out] error       Pointer to a pointer to a wbcAuthErrorInfo structure
1137  * @param[out] policy      Pointer to a pointer to a wbcUserPasswordPolicyInfo structure
1138  *
1139  * @return #wbcErr
1140  **/
1141 wbcErr wbcLogonUser(const struct wbcLogonUserParams *params,
1142                     struct wbcLogonUserInfo **info,
1143                     struct wbcAuthErrorInfo **error,
1144                     struct wbcUserPasswordPolicyInfo **policy);
1145
1146 /**
1147  * @brief Trigger a logoff notification to Winbind for a specific user
1148  *
1149  * @param username    Name of user to remove from Winbind's list of
1150  *                    logged on users.
1151  * @param uid         Uid assigned to the username
1152  * @param ccfilename  Absolute path to the Krb5 credentials cache to
1153  *                    be removed
1154  *
1155  * @return #wbcErr
1156  **/
1157 wbcErr wbcLogoffUser(const char *username,
1158                      uid_t uid,
1159                      const char *ccfilename);
1160
1161 /**
1162  * @brief Trigger an extended logoff notification to Winbind for a specific user
1163  *
1164  * @param params      A wbcLogoffUserParams structure
1165  * @param error       User output details on error
1166  *
1167  * @return #wbcErr
1168  **/
1169 wbcErr wbcLogoffUserEx(const struct wbcLogoffUserParams *params,
1170                        struct wbcAuthErrorInfo **error);
1171
1172 /**
1173  * @brief Change a password for a user
1174  *
1175  * @param username      Name of user to authenticate
1176  * @param old_password  Old clear text password of user
1177  * @param new_password  New clear text password of user
1178  *
1179  * @return #wbcErr
1180  **/
1181 wbcErr wbcChangeUserPassword(const char *username,
1182                              const char *old_password,
1183                              const char *new_password);
1184
1185 /**
1186  * @brief Change a password for a user with more detailed information upon
1187  *   failure
1188  *
1189  * @param params                Input parameters
1190  * @param error                 User output details on WBC_ERR_PWD_CHANGE_FAILED
1191  * @param reject_reason         New password reject reason on WBC_ERR_PWD_CHANGE_FAILED
1192  * @param policy                Password policy output details on WBC_ERR_PWD_CHANGE_FAILED
1193  *
1194  * @return #wbcErr
1195  **/
1196 wbcErr wbcChangeUserPasswordEx(const struct wbcChangePasswordParams *params,
1197                                struct wbcAuthErrorInfo **error,
1198                                enum wbcPasswordChangeRejectReason *reject_reason,
1199                                struct wbcUserPasswordPolicyInfo **policy);
1200
1201 /**
1202  * @brief Authenticate a user with cached credentials
1203  *
1204  * @param *params    Pointer to a wbcCredentialCacheParams structure
1205  * @param **info     Pointer to a pointer to a wbcCredentialCacheInfo structure
1206  * @param **error    Pointer to a pointer to a wbcAuthErrorInfo structure
1207  *
1208  * @return #wbcErr
1209  **/
1210 wbcErr wbcCredentialCache(struct wbcCredentialCacheParams *params,
1211                           struct wbcCredentialCacheInfo **info,
1212                           struct wbcAuthErrorInfo **error);
1213
1214 /**
1215  * @brief Save a password with winbind for doing wbcCredentialCache() later
1216  *
1217  * @param *user      Username
1218  * @param *password  Password
1219  *
1220  * @return #wbcErr
1221  **/
1222 wbcErr wbcCredentialSave(const char *user, const char *password);
1223
1224 /**********************************************************
1225  * Resolve functions
1226  **********************************************************/
1227
1228 /**
1229  * @brief Resolve a NetbiosName via WINS
1230  *
1231  * @param name         Name to resolve
1232  * @param *ip          Pointer to the ip address string
1233  *
1234  * @return #wbcErr
1235  **/
1236 wbcErr wbcResolveWinsByName(const char *name, char **ip);
1237
1238 /**
1239  * @brief Resolve an IP address via WINS into a NetbiosName
1240  *
1241  * @param ip          The ip address string
1242  * @param *name       Pointer to the name
1243  *
1244  * @return #wbcErr
1245  *
1246  **/
1247 wbcErr wbcResolveWinsByIP(const char *ip, char **name);
1248
1249 /**********************************************************
1250  * Trusted domain functions
1251  **********************************************************/
1252
1253 /**
1254  * @brief Trigger a verification of the trust credentials of a specific domain
1255  *
1256  * @param *domain      The name of the domain.
1257  * @param error        Output details on WBC_ERR_AUTH_ERROR
1258  *
1259  * @return #wbcErr
1260  **/
1261 wbcErr wbcCheckTrustCredentials(const char *domain,
1262                                 struct wbcAuthErrorInfo **error);
1263
1264 /**
1265  * @brief Trigger a change of the trust credentials for a specific domain
1266  *
1267  * @param *domain      The name of the domain.
1268  * @param error        Output details on WBC_ERR_AUTH_ERROR
1269  *
1270  * @return #wbcErr
1271  **/
1272 wbcErr wbcChangeTrustCredentials(const char *domain,
1273                                  struct wbcAuthErrorInfo **error);
1274
1275 /**
1276  * @brief Trigger a no-op call through the NETLOGON pipe. Low-cost
1277  *        version of wbcCheckTrustCredentials
1278  *
1279  * @param *domain      The name of the domain, only NULL for the default domain is
1280  *                     supported yet. Other values than NULL will result in
1281  *                     WBC_ERR_NOT_IMPLEMENTED.
1282  * @param error        Output details on WBC_ERR_AUTH_ERROR
1283  *
1284  * @return #wbcErr
1285  **/
1286 wbcErr wbcPingDc(const char *domain, struct wbcAuthErrorInfo **error);
1287
1288 /**********************************************************
1289  * Helper functions
1290  **********************************************************/
1291
1292 /**
1293  * @brief Initialize a named blob and add to list of blobs
1294  *
1295  * @param[in,out] num_blobs     Pointer to the number of blobs
1296  * @param[in,out] blobs         Pointer to an array of blobs
1297  * @param[in]     name          Name of the new named blob
1298  * @param[in]     flags         Flags of the new named blob
1299  * @param[in]     data          Blob data of new blob
1300  * @param[in]     length        Blob data length of new blob
1301  *
1302  * @return #wbcErr
1303  **/
1304 wbcErr wbcAddNamedBlob(size_t *num_blobs,
1305                        struct wbcNamedBlob **blobs,
1306                        const char *name,
1307                        uint32_t flags,
1308                        uint8_t *data,
1309                        size_t length);
1310
1311 #endif      /* _WBCLIENT_H */