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