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