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    Copyright (C) Matthew Newton 2015
   9
  10    This library is free software; you can redistribute it and/or
  11    modify it under the terms of the GNU Lesser General Public
  12    License as published by the Free Software Foundation; either
  13    version 3 of the License, or (at your option) any later version.
  14
  15    This library is distributed in the hope that it will be useful,
  16    but WITHOUT ANY WARRANTY; without even the implied warranty of
  17    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18    Library General Public License for more details.
  19
  20    You should have received a copy of the GNU Lesser General Public License
  21    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  22 */
  23
  24 #ifndef _WBCLIENT_H
  25 #define _WBCLIENT_H
  26
  27 #include <pwd.h>
  28 #include <grp.h>
  29
  30 /* Define error types */
  31
  32 /**
  33  *  @brief Status codes returned from wbc functions
  34  **/
  35
  36 enum _wbcErrType {
  37         WBC_ERR_SUCCESS = 0,    /**< Successful completion **/
  38         WBC_ERR_NOT_IMPLEMENTED,/**< Function not implemented **/
  39         WBC_ERR_UNKNOWN_FAILURE,/**< General failure **/
  40         WBC_ERR_NO_MEMORY,      /**< Memory allocation error **/
  41         WBC_ERR_INVALID_SID,    /**< Invalid SID format **/
  42         WBC_ERR_INVALID_PARAM,  /**< An Invalid parameter was supplied **/
  43         WBC_ERR_WINBIND_NOT_AVAILABLE,   /**< Winbind daemon is not available **/
  44         WBC_ERR_DOMAIN_NOT_FOUND,        /**< Domain is not trusted or cannot be found **/
  45         WBC_ERR_INVALID_RESPONSE,        /**< Winbind returned an invalid response **/
  46         WBC_ERR_NSS_ERROR,            /**< NSS_STATUS error **/
  47         WBC_ERR_AUTH_ERROR,        /**< Authentication failed **/
  48         WBC_ERR_UNKNOWN_USER,      /**< User account cannot be found */
  49         WBC_ERR_UNKNOWN_GROUP,     /**< Group account cannot be found */
  50         WBC_ERR_PWD_CHANGE_FAILED, /**< Password Change has failed */
  51         WBC_ERR_NOT_MAPPED         /**< Translation function failed on some element **/
  52 };
  53
  54 typedef enum _wbcErrType wbcErr;
  55
  56 #define WBC_ERROR_IS_OK(x) ((x) == WBC_ERR_SUCCESS)
  57
  58 const char *wbcErrorString(wbcErr error);
  59
  60 /**
  61  *  @brief Some useful details about the wbclient library
  62  *
  63  *  0.1: Initial version
  64  *  0.2: Added wbcRemoveUidMapping()
  65  *       Added wbcRemoveGidMapping()
  66  *  0.3: Added wbcGetpwsid()
  67  *       Added wbcGetSidAliases()
  68  *  0.4: Added wbcSidTypeString()
  69  *  0.5: Added wbcChangeTrustCredentials()
  70  *  0.6: Made struct wbcInterfaceDetails char* members non-const
  71  *  0.7: Added wbcSidToStringBuf()
  72  *  0.8: Added wbcSidsToUnixIds() and wbcLookupSids()
  73  *  0.9: Added support for WBC_ID_TYPE_BOTH
  74  *  0.10: Added wbcPingDc2()
  75  *  0.11: Extended wbcAuthenticateUserEx to provide PAC parsing
  76  *  0.12: Added wbcCtxCreate and friends
  77  *  0.13: Added wbcCtxUnixIdsToSids and wbcUnixIdsToSids
  78  *  0.14: Added "authoritative" to wbcAuthErrorInfo
  79  *        Added WBC_SID_NAME_LABEL
  80  *  0.15: Added wbcSetClientProcessName()
  81  *  0.16: Added wbcChangeTrustCredentialsAt()
  82  **/
  83 #define WBCLIENT_MAJOR_VERSION 0
  84 #define WBCLIENT_MINOR_VERSION 16
  85 #define WBCLIENT_VENDOR_VERSION "Samba libwbclient"
  86 struct wbcLibraryDetails {
  87         uint16_t major_version;
  88         uint16_t minor_version;
  89         const char *vendor_version;
  90 };
  91
  92 /**
  93  *  @brief Some useful details about the running winbindd
  94  *
  95  **/
  96 struct wbcInterfaceDetails {
  97         uint32_t interface_version;
  98         char *winbind_version;
  99         char winbind_separator;
 100         char *netbios_name;
 101         char *netbios_domain;
 102         char *dns_domain;
 103 };
 104
 105 /**
 106  *  @brief Library context data
 107  *
 108  **/
 109
 110 struct wbcContext;
 111
 112 /*
 113  * Data types used by the Winbind Client API
 114  */
 115
 116 #ifndef WBC_MAXSUBAUTHS
 117 #define WBC_MAXSUBAUTHS 15 /* max sub authorities in a SID */
 118 #endif
 119
 120 /**
 121  *  @brief Windows Security Identifier
 122  *
 123  **/
 124
 125 struct wbcDomainSid {
 126         uint8_t   sid_rev_num;
 127         uint8_t   num_auths;
 128         uint8_t   id_auth[6];
 129         uint32_t  sub_auths[WBC_MAXSUBAUTHS];
 130 };
 131
 132 /**
 133  * @brief Security Identifier type
 134  **/
 135
 136 enum wbcSidType {
 137         WBC_SID_NAME_USE_NONE=0,
 138         WBC_SID_NAME_USER=1,
 139         WBC_SID_NAME_DOM_GRP=2,
 140         WBC_SID_NAME_DOMAIN=3,
 141         WBC_SID_NAME_ALIAS=4,
 142         WBC_SID_NAME_WKN_GRP=5,
 143         WBC_SID_NAME_DELETED=6,
 144         WBC_SID_NAME_INVALID=7,
 145         WBC_SID_NAME_UNKNOWN=8,
 146         WBC_SID_NAME_COMPUTER=9,
 147         WBC_SID_NAME_LABEL=10
 148 };
 149
 150 /**
 151  * @brief Security Identifier with attributes
 152  **/
 153
 154 struct wbcSidWithAttr {
 155         struct wbcDomainSid sid;
 156         uint32_t attributes;
 157 };
 158
 159 /* wbcSidWithAttr->attributes */
 160
 161 #define WBC_SID_ATTR_GROUP_MANDATORY            0x00000001
 162 #define WBC_SID_ATTR_GROUP_ENABLED_BY_DEFAULT   0x00000002
 163 #define WBC_SID_ATTR_GROUP_ENABLED              0x00000004
 164 #define WBC_SID_ATTR_GROUP_OWNER                0x00000008
 165 #define WBC_SID_ATTR_GROUP_USEFOR_DENY_ONLY     0x00000010
 166 #define WBC_SID_ATTR_GROUP_RESOURCE             0x20000000
 167 #define WBC_SID_ATTR_GROUP_LOGON_ID             0xC0000000
 168
 169 /**
 170  *  @brief Windows GUID
 171  *
 172  **/
 173
 174 struct wbcGuid {
 175         uint32_t time_low;
 176         uint16_t time_mid;
 177         uint16_t time_hi_and_version;
 178         uint8_t clock_seq[2];
 179         uint8_t node[6];
 180 };
 181
 182 /**
 183  * @brief Domain Information
 184  **/
 185
 186 struct wbcDomainInfo {
 187         char *short_name;
 188         char *dns_name;
 189         struct wbcDomainSid sid;
 190         uint32_t domain_flags;
 191         uint32_t trust_flags;
 192         uint32_t trust_type;
 193         char *trust_routing;
 194 };
 195
 196 /* wbcDomainInfo->domain_flags */
 197
 198 #define WBC_DOMINFO_DOMAIN_UNKNOWN    0x00000000
 199 #define WBC_DOMINFO_DOMAIN_NATIVE     0x00000001
 200 #define WBC_DOMINFO_DOMAIN_AD         0x00000002
 201 #define WBC_DOMINFO_DOMAIN_PRIMARY    0x00000004
 202 #define WBC_DOMINFO_DOMAIN_OFFLINE    0x00000008
 203
 204 /* wbcDomainInfo->trust_flags */
 205
 206 #define WBC_DOMINFO_TRUST_TRANSITIVE  0x00000001
 207 #define WBC_DOMINFO_TRUST_INCOMING    0x00000002
 208 #define WBC_DOMINFO_TRUST_OUTGOING    0x00000004
 209
 210 /* wbcDomainInfo->trust_type */
 211
 212 #define WBC_DOMINFO_TRUSTTYPE_NONE       0x00000000
 213 #define WBC_DOMINFO_TRUSTTYPE_FOREST     0x00000001
 214 #define WBC_DOMINFO_TRUSTTYPE_IN_FOREST  0x00000002
 215 #define WBC_DOMINFO_TRUSTTYPE_EXTERNAL   0x00000003
 216 #define WBC_DOMINFO_TRUSTTYPE_LOCAL      0x00000004
 217 #define WBC_DOMINFO_TRUSTTYPE_WKSTA      0x00000005
 218 #define WBC_DOMINFO_TRUSTTYPE_RWDC       0x00000006
 219 #define WBC_DOMINFO_TRUSTTYPE_RODC       0x00000007
 220 #define WBC_DOMINFO_TRUSTTYPE_PDC        0x00000008
 221
 222
 223 /**
 224  * @brief Generic Blob
 225  **/
 226
 227 struct wbcBlob {
 228         uint8_t *data;
 229         size_t length;
 230 };
 231
 232 /**
 233  * @brief Named Blob
 234  **/
 235
 236 struct wbcNamedBlob {
 237         const char *name;
 238         uint32_t flags;
 239         struct wbcBlob blob;
 240 };
 241
 242 /**
 243  * @brief Auth User Parameters
 244  **/
 245
 246 struct wbcAuthUserParams {
 247         const char *account_name;
 248         const char *domain_name;
 249         const char *workstation_name;
 250
 251         uint32_t flags;
 252
 253         uint32_t parameter_control;
 254
 255         enum wbcAuthUserLevel {
 256                 WBC_AUTH_USER_LEVEL_PLAIN = 1,
 257                 WBC_AUTH_USER_LEVEL_HASH = 2,
 258                 WBC_AUTH_USER_LEVEL_RESPONSE = 3,
 259                 WBC_AUTH_USER_LEVEL_PAC = 4
 260         } level;
 261         union {
 262                 const char *plaintext;
 263                 struct {
 264                         uint8_t nt_hash[16];
 265                         uint8_t lm_hash[16];
 266                 } hash;
 267                 struct {
 268                         uint8_t challenge[8];
 269                         uint32_t nt_length;
 270                         uint8_t *nt_data;
 271                         uint32_t lm_length;
 272                         uint8_t *lm_data;
 273                 } response;
 274                 struct wbcBlob pac;
 275         } password;
 276 };
 277
 278 /**
 279  * @brief Logon User Parameters
 280  **/
 281
 282 struct wbcLogonUserParams {
 283         const char *username;
 284         const char *password;
 285         size_t num_blobs;
 286         struct wbcNamedBlob *blobs;
 287 };
 288
 289 /**
 290  * @brief ChangePassword Parameters
 291  **/
 292
 293 struct wbcChangePasswordParams {
 294         const char *account_name;
 295         const char *domain_name;
 296
 297         uint32_t flags;
 298
 299         enum wbcChangePasswordLevel {
 300                 WBC_CHANGE_PASSWORD_LEVEL_PLAIN = 1,
 301                 WBC_CHANGE_PASSWORD_LEVEL_RESPONSE = 2
 302         } level;
 303
 304         union {
 305                 const char *plaintext;
 306                 struct {
 307                         uint32_t old_nt_hash_enc_length;
 308                         uint8_t *old_nt_hash_enc_data;
 309                         uint32_t old_lm_hash_enc_length;
 310                         uint8_t *old_lm_hash_enc_data;
 311                 } response;
 312         } old_password;
 313         union {
 314                 const char *plaintext;
 315                 struct {
 316                         uint32_t nt_length;
 317                         uint8_t *nt_data;
 318                         uint32_t lm_length;
 319                         uint8_t *lm_data;
 320                 } response;
 321         } new_password;
 322 };
 323
 324 /* wbcAuthUserParams->parameter_control */
 325
 326 #define WBC_MSV1_0_CLEARTEXT_PASSWORD_ALLOWED           0x00000002
 327 #define WBC_MSV1_0_UPDATE_LOGON_STATISTICS              0x00000004
 328 #define WBC_MSV1_0_RETURN_USER_PARAMETERS               0x00000008
 329 #define WBC_MSV1_0_ALLOW_SERVER_TRUST_ACCOUNT           0x00000020
 330 #define WBC_MSV1_0_RETURN_PROFILE_PATH                  0x00000200
 331 #define WBC_MSV1_0_ALLOW_WORKSTATION_TRUST_ACCOUNT      0x00000800
 332 #define WBC_MSV1_0_ALLOW_MSVCHAPV2                      0x00010000
 333
 334 /* wbcAuthUserParams->flags */
 335
 336 #define WBC_AUTH_PARAM_FLAGS_INTERACTIVE_LOGON          0x00000001
 337
 338 /**
 339  * @brief Auth User Information
 340  *
 341  * Some of the strings are maybe NULL
 342  **/
 343
 344 struct wbcAuthUserInfo {
 345         uint32_t user_flags;
 346
 347         char *account_name;
 348         char *user_principal;
 349         char *full_name;
 350         char *domain_name;
 351         char *dns_domain_name;
 352
 353         uint32_t acct_flags;
 354         uint8_t user_session_key[16];
 355         uint8_t lm_session_key[8];
 356
 357         uint16_t logon_count;
 358         uint16_t bad_password_count;
 359
 360         uint64_t logon_time;
 361         uint64_t logoff_time;
 362         uint64_t kickoff_time;
 363         uint64_t pass_last_set_time;
 364         uint64_t pass_can_change_time;
 365         uint64_t pass_must_change_time;
 366
 367         char *logon_server;
 368         char *logon_script;
 369         char *profile_path;
 370         char *home_directory;
 371         char *home_drive;
 372
 373         /*
 374          * the 1st one is the account sid
 375          * the 2nd one is the primary_group sid
 376          * followed by the rest of the groups
 377          */
 378         uint32_t num_sids;
 379         struct wbcSidWithAttr *sids;
 380 };
 381
 382 /**
 383  * @brief Logon User Information
 384  *
 385  * Some of the strings are maybe NULL
 386  **/
 387
 388 struct wbcLogonUserInfo {
 389         struct wbcAuthUserInfo *info;
 390         size_t num_blobs;
 391         struct wbcNamedBlob *blobs;
 392 };
 393
 394 /* wbcAuthUserInfo->user_flags */
 395
 396 #define WBC_AUTH_USER_INFO_GUEST                        0x00000001
 397 #define WBC_AUTH_USER_INFO_NOENCRYPTION                 0x00000002
 398 #define WBC_AUTH_USER_INFO_CACHED_ACCOUNT               0x00000004
 399 #define WBC_AUTH_USER_INFO_USED_LM_PASSWORD             0x00000008
 400 #define WBC_AUTH_USER_INFO_EXTRA_SIDS                   0x00000020
 401 #define WBC_AUTH_USER_INFO_SUBAUTH_SESSION_KEY          0x00000040
 402 #define WBC_AUTH_USER_INFO_SERVER_TRUST_ACCOUNT         0x00000080
 403 #define WBC_AUTH_USER_INFO_NTLMV2_ENABLED               0x00000100
 404 #define WBC_AUTH_USER_INFO_RESOURCE_GROUPS              0x00000200
 405 #define WBC_AUTH_USER_INFO_PROFILE_PATH_RETURNED        0x00000400
 406 #define WBC_AUTH_USER_INFO_GRACE_LOGON                  0x01000000
 407
 408 /* wbcAuthUserInfo->acct_flags */
 409
 410 #define WBC_ACB_DISABLED                        0x00000001 /* 1 User account disabled */
 411 #define WBC_ACB_HOMDIRREQ                       0x00000002 /* 1 Home directory required */
 412 #define WBC_ACB_PWNOTREQ                        0x00000004 /* 1 User password not required */
 413 #define WBC_ACB_TEMPDUP                         0x00000008 /* 1 Temporary duplicate account */
 414 #define WBC_ACB_NORMAL                          0x00000010 /* 1 Normal user account */
 415 #define WBC_ACB_MNS                             0x00000020 /* 1 MNS logon user account */
 416 #define WBC_ACB_DOMTRUST                        0x00000040 /* 1 Interdomain trust account */
 417 #define WBC_ACB_WSTRUST                         0x00000080 /* 1 Workstation trust account */
 418 #define WBC_ACB_SVRTRUST                        0x00000100 /* 1 Server trust account */
 419 #define WBC_ACB_PWNOEXP                         0x00000200 /* 1 User password does not expire */
 420 #define WBC_ACB_AUTOLOCK                        0x00000400 /* 1 Account auto locked */
 421 #define WBC_ACB_ENC_TXT_PWD_ALLOWED             0x00000800 /* 1 Encrypted text password is allowed */
 422 #define WBC_ACB_SMARTCARD_REQUIRED              0x00001000 /* 1 Smart Card required */
 423 #define WBC_ACB_TRUSTED_FOR_DELEGATION          0x00002000 /* 1 Trusted for Delegation */
 424 #define WBC_ACB_NOT_DELEGATED                   0x00004000 /* 1 Not delegated */
 425 #define WBC_ACB_USE_DES_KEY_ONLY                0x00008000 /* 1 Use DES key only */
 426 #define WBC_ACB_DONT_REQUIRE_PREAUTH            0x00010000 /* 1 Preauth not required */
 427 #define WBC_ACB_PW_EXPIRED                      0x00020000 /* 1 Password Expired */
 428 #define WBC_ACB_NO_AUTH_DATA_REQD               0x00080000   /* 1 = No authorization data required */
 429
 430 struct wbcAuthErrorInfo {
 431         uint32_t nt_status;
 432         char *nt_string;
 433         int32_t pam_error;
 434         char *display_string;
 435         uint8_t authoritative;
 436 };
 437
 438 /**
 439  * @brief User Password Policy Information
 440  **/
 441
 442 /* wbcUserPasswordPolicyInfo->password_properties */
 443
 444 #define WBC_DOMAIN_PASSWORD_COMPLEX             0x00000001
 445 #define WBC_DOMAIN_PASSWORD_NO_ANON_CHANGE      0x00000002
 446 #define WBC_DOMAIN_PASSWORD_NO_CLEAR_CHANGE     0x00000004
 447 #define WBC_DOMAIN_PASSWORD_LOCKOUT_ADMINS      0x00000008
 448 #define WBC_DOMAIN_PASSWORD_STORE_CLEARTEXT     0x00000010
 449 #define WBC_DOMAIN_REFUSE_PASSWORD_CHANGE       0x00000020
 450
 451 struct wbcUserPasswordPolicyInfo {
 452         uint32_t min_length_password;
 453         uint32_t password_history;
 454         uint32_t password_properties;
 455         uint64_t expire;
 456         uint64_t min_passwordage;
 457 };
 458
 459 /**
 460  * @brief Change Password Reject Reason
 461  **/
 462
 463 enum wbcPasswordChangeRejectReason {
 464         WBC_PWD_CHANGE_NO_ERROR=0,
 465         WBC_PWD_CHANGE_PASSWORD_TOO_SHORT=1,
 466         WBC_PWD_CHANGE_PWD_IN_HISTORY=2,
 467         WBC_PWD_CHANGE_USERNAME_IN_PASSWORD=3,
 468         WBC_PWD_CHANGE_FULLNAME_IN_PASSWORD=4,
 469         WBC_PWD_CHANGE_NOT_COMPLEX=5,
 470         WBC_PWD_CHANGE_MACHINE_NOT_DEFAULT=6,
 471         WBC_PWD_CHANGE_FAILED_BY_FILTER=7,
 472         WBC_PWD_CHANGE_PASSWORD_TOO_LONG=8
 473 };
 474
 475 /* Note: this defines exist for compatibility reasons with existing code */
 476 #define WBC_PWD_CHANGE_REJECT_OTHER      WBC_PWD_CHANGE_NO_ERROR
 477 #define WBC_PWD_CHANGE_REJECT_TOO_SHORT  WBC_PWD_CHANGE_PASSWORD_TOO_SHORT
 478 #define WBC_PWD_CHANGE_REJECT_IN_HISTORY WBC_PWD_CHANGE_PWD_IN_HISTORY
 479 #define WBC_PWD_CHANGE_REJECT_COMPLEXITY WBC_PWD_CHANGE_NOT_COMPLEX
 480
 481 /**
 482  * @brief Logoff User Parameters
 483  **/
 484
 485 struct wbcLogoffUserParams {
 486         const char *username;
 487         size_t num_blobs;
 488         struct wbcNamedBlob *blobs;
 489 };
 490
 491 /** @brief Credential cache log-on parameters
 492  *
 493  */
 494
 495 struct wbcCredentialCacheParams {
 496         const char *account_name;
 497         const char *domain_name;
 498         enum wbcCredentialCacheLevel {
 499                 WBC_CREDENTIAL_CACHE_LEVEL_NTLMSSP = 1
 500         } level;
 501         size_t num_blobs;
 502         struct wbcNamedBlob *blobs;
 503 };
 504
 505
 506 /** @brief Info returned by credential cache auth
 507  *
 508  */
 509
 510 struct wbcCredentialCacheInfo {
 511         size_t num_blobs;
 512         struct wbcNamedBlob *blobs;
 513 };
 514
 515 /*
 516  * DomainControllerInfo struct
 517  */
 518 struct wbcDomainControllerInfo {
 519         char *dc_name;
 520 };
 521
 522 /*
 523  * DomainControllerInfoEx struct
 524  */
 525 struct wbcDomainControllerInfoEx {
 526         const char *dc_unc;
 527         const char *dc_address;
 528         uint16_t dc_address_type;
 529         struct wbcGuid *domain_guid;
 530         const char *domain_name;
 531         const char *forest_name;
 532         uint32_t dc_flags;
 533         const char *dc_site_name;
 534         const char *client_site_name;
 535 };
 536
 537 /**********************************************************
 538  * Memory Management
 539  **********************************************************/
 540
 541 /**
 542  * @brief Free library allocated memory
 543  *
 544  * @param * Pointer to free
 545  *
 546  * @return void
 547  **/
 548 void wbcFreeMemory(void*);
 549
 550
 551 /**********************************************************
 552  * Context Management
 553  **********************************************************/
 554
 555 /**
 556  * @brief Create a new wbcContext context
 557  *
 558  * @return wbcContext
 559  **/
 560 struct wbcContext *wbcCtxCreate(void);
 561
 562 /**
 563  * @brief Free a library context
 564  *
 565  * @param ctx           wbcContext to free
 566  *
 567  * @return void
 568  **/
 569 void wbcCtxFree(struct wbcContext *ctx);
 570
 571
 572
 573 /*
 574  * Utility functions for dealing with SIDs
 575  */
 576
 577 /**
 578  * @brief Get a string representation of the SID type
 579  *
 580  * @param type          type of the SID
 581  *
 582  * @return string representation of the SID type
 583  */
 584 const char* wbcSidTypeString(enum wbcSidType type);
 585
 586 #define WBC_SID_STRING_BUFLEN (15*11+25)
 587
 588 /*
 589  * @brief Print a sid into a buffer
 590  *
 591  * @param sid           Binary Security Identifier
 592  * @param buf           Target buffer
 593  * @param buflen        Target buffer length
 594  *
 595  * @return Resulting string length.
 596  */
 597 int wbcSidToStringBuf(const struct wbcDomainSid *sid, char *buf, int buflen);
 598
 599 /**
 600  * @brief Convert a binary SID to a character string
 601  *
 602  * @param sid           Binary Security Identifier
 603  * @param **sid_string  Resulting character string
 604  *
 605  * @return #wbcErr
 606  **/
 607 wbcErr wbcSidToString(const struct wbcDomainSid *sid,
 608                       char **sid_string);
 609
 610 /**
 611  * @brief Convert a character string to a binary SID
 612  *
 613  * @param *sid_string   Character string in the form of S-...
 614  * @param sid           Resulting binary SID
 615  *
 616  * @return #wbcErr
 617  **/
 618 wbcErr wbcStringToSid(const char *sid_string,
 619                       struct wbcDomainSid *sid);
 620
 621 /*
 622  * Utility functions for dealing with GUIDs
 623  */
 624
 625 /**
 626  * @brief Convert a binary GUID to a character string
 627  *
 628  * @param guid           Binary Guid
 629  * @param **guid_string  Resulting character string
 630  *
 631  * @return #wbcErr
 632  **/
 633 wbcErr wbcGuidToString(const struct wbcGuid *guid,
 634                        char **guid_string);
 635
 636 /**
 637  * @brief Convert a character string to a binary GUID
 638  *
 639  * @param *guid_string  Character string
 640  * @param guid          Resulting binary GUID
 641  *
 642  * @return #wbcErr
 643  **/
 644 wbcErr wbcStringToGuid(const char *guid_string,
 645                        struct wbcGuid *guid);
 646
 647 /**
 648  * @brief Ping winbindd to see if the daemon is running
 649  *
 650  * @param *ctx        wbclient Context
 651  *
 652  * @return #wbcErr
 653  **/
 654 wbcErr wbcCtxPing(struct wbcContext *ctx);
 655
 656 /**
 657  * @brief Ping winbindd to see if the daemon is running
 658  *
 659  * @return #wbcErr
 660  **/
 661 wbcErr wbcPing(void);
 662
 663 wbcErr wbcLibraryDetails(struct wbcLibraryDetails **details);
 664
 665 wbcErr wbcCtxInterfaceDetails(struct wbcContext *ctx,
 666                               struct wbcInterfaceDetails **details);
 667 wbcErr wbcInterfaceDetails(struct wbcInterfaceDetails **details);
 668
 669 /**********************************************************
 670  * Name/SID conversion
 671  **********************************************************/
 672
 673 /**
 674  * @brief Convert a domain and name to SID
 675  *
 676  * @param *ctx        wbclient Context
 677  * @param dom_name    Domain name (possibly "")
 678  * @param name        User or group name
 679  * @param *sid        Pointer to the resolved domain SID
 680  * @param *name_type  Pointer to the SID type
 681  *
 682  * @return #wbcErr
 683  **/
 684 wbcErr wbcCtxLookupName(struct wbcContext *ctx,
 685                         const char *dom_name,
 686                         const char *name,
 687                         struct wbcDomainSid *sid,
 688                         enum wbcSidType *name_type);
 689
 690 /**
 691  * @brief Convert a domain and name to SID
 692  *
 693  * @param dom_name    Domain name (possibly "")
 694  * @param name        User or group name
 695  * @param *sid        Pointer to the resolved domain SID
 696  * @param *name_type  Pointer to the SID type
 697  *
 698  * @return #wbcErr
 699  **/
 700 wbcErr wbcLookupName(const char *dom_name,
 701                      const char *name,
 702                      struct wbcDomainSid *sid,
 703                      enum wbcSidType *name_type);
 704
 705 /**
 706  * @brief Convert a SID to a domain and name
 707  *
 708  * @param *ctx       wbclient Context
 709  * @param *sid       Pointer to the domain SID to be resolved
 710  * @param domain     Resolved Domain name (possibly "")
 711  * @param name       Resolved User or group name
 712  * @param *name_type Pointer to the resolved SID type
 713  *
 714  * @return #wbcErr
 715  **/
 716 wbcErr wbcCtxLookupSid(struct wbcContext *ctx,
 717                        const struct wbcDomainSid *sid,
 718                        char **domain,
 719                        char **name,
 720                        enum wbcSidType *name_type);
 721
 722 /**
 723  * @brief Convert a SID to a domain and name
 724  *
 725  * @param *sid       Pointer to the domain SID to be resolved
 726  * @param domain     Resolved Domain name (possibly "")
 727  * @param name       Resolved User or group name
 728  * @param *name_type Pointer to the resolved SID type
 729  *
 730  * @return #wbcErr
 731  **/
 732 wbcErr wbcLookupSid(const struct wbcDomainSid *sid,
 733                     char **domain,
 734                     char **name,
 735                     enum wbcSidType *name_type);
 736
 737 struct wbcTranslatedName {
 738         enum wbcSidType type;
 739         char *name;
 740         int domain_index;
 741 };
 742
 743 wbcErr wbcCtxLookupSids(struct wbcContext *ctx,
 744                         const struct wbcDomainSid *sids, int num_sids,
 745                         struct wbcDomainInfo **domains, int *num_domains,
 746                         struct wbcTranslatedName **names);
 747
 748 wbcErr wbcLookupSids(const struct wbcDomainSid *sids, int num_sids,
 749                      struct wbcDomainInfo **domains, int *num_domains,
 750                      struct wbcTranslatedName **names);
 751
 752 /**
 753  * @brief Translate a collection of RIDs within a domain to names
 754  */
 755 wbcErr wbcCtxLookupRids(struct wbcContext *ctx,
 756                         struct wbcDomainSid *dom_sid,
 757                         int num_rids,
 758                         uint32_t *rids,
 759                         const char **domain_name,
 760                         const char ***names,
 761                         enum wbcSidType **types);
 762
 763 /**
 764  * @brief Translate a collection of RIDs within a domain to names
 765  */
 766 wbcErr wbcLookupRids(struct wbcDomainSid *dom_sid,
 767                      int num_rids,
 768                      uint32_t *rids,
 769                      const char **domain_name,
 770                      const char ***names,
 771                      enum wbcSidType **types);
 772
 773 /*
 774  * @brief Get the groups a user belongs to
 775  **/
 776 wbcErr wbcCtxLookupUserSids(struct wbcContext *ctx,
 777                             const struct wbcDomainSid *user_sid,
 778                             bool domain_groups_only,
 779                             uint32_t *num_sids,
 780                             struct wbcDomainSid **sids);
 781
 782 /*
 783  * @brief Get the groups a user belongs to
 784  **/
 785 wbcErr wbcLookupUserSids(const struct wbcDomainSid *user_sid,
 786                          bool domain_groups_only,
 787                          uint32_t *num_sids,
 788                          struct wbcDomainSid **sids);
 789
 790 /*
 791  * @brief Get alias membership for sids
 792  **/
 793 wbcErr wbcCtxGetSidAliases(struct wbcContext *ctx,
 794                            const struct wbcDomainSid *dom_sid,
 795                            struct wbcDomainSid *sids,
 796                            uint32_t num_sids,
 797                            uint32_t **alias_rids,
 798                            uint32_t *num_alias_rids);
 799
 800 /*
 801  * @brief Get alias membership for sids
 802  **/
 803 wbcErr wbcGetSidAliases(const struct wbcDomainSid *dom_sid,
 804                         struct wbcDomainSid *sids,
 805                         uint32_t num_sids,
 806                         uint32_t **alias_rids,
 807                         uint32_t *num_alias_rids);
 808
 809 /**
 810  * @brief Lists Users
 811  **/
 812 wbcErr wbcCtxListUsers(struct wbcContext *ctx,
 813                        const char *domain_name,
 814                        uint32_t *num_users,
 815                        const char ***users);
 816
 817 /**
 818  * @brief Lists Users
 819  **/
 820 wbcErr wbcListUsers(const char *domain_name,
 821                     uint32_t *num_users,
 822                     const char ***users);
 823
 824 /**
 825  * @brief Lists Groups
 826  **/
 827 wbcErr wbcCtxListGroups(struct wbcContext *ctx,
 828                         const char *domain_name,
 829                         uint32_t *num_groups,
 830                         const char ***groups);
 831
 832 /**
 833  * @brief Lists Groups
 834  **/
 835 wbcErr wbcListGroups(const char *domain_name,
 836                      uint32_t *num_groups,
 837                      const char ***groups);
 838
 839 wbcErr wbcCtxGetDisplayName(struct wbcContext *ctx,
 840                             const struct wbcDomainSid *sid,
 841                             char **pdomain,
 842                             char **pfullname,
 843                             enum wbcSidType *pname_type);
 844
 845 wbcErr wbcGetDisplayName(const struct wbcDomainSid *sid,
 846                          char **pdomain,
 847                          char **pfullname,
 848                          enum wbcSidType *pname_type);
 849
 850 /**********************************************************
 851  * SID/uid/gid Mappings
 852  **********************************************************/
 853
 854 /**
 855  * @brief Convert a Windows SID to a Unix uid, allocating an uid if needed
 856  *
 857  * @param *ctx        wbclient Context
 858  * @param *sid        Pointer to the domain SID to be resolved
 859  * @param *puid       Pointer to the resolved uid_t value
 860  *
 861  * @return #wbcErr
 862  *
 863  **/
 864 wbcErr wbcCtxSidToUid(struct wbcContext *ctx,
 865                       const struct wbcDomainSid *sid,
 866                       uid_t *puid);
 867
 868 /**
 869  * @brief Convert a Windows SID to a Unix uid, allocating an uid if needed
 870  *
 871  * @param *sid        Pointer to the domain SID to be resolved
 872  * @param *puid       Pointer to the resolved uid_t value
 873  *
 874  * @return #wbcErr
 875  *
 876  **/
 877 wbcErr wbcSidToUid(const struct wbcDomainSid *sid,
 878                    uid_t *puid);
 879
 880 /**
 881  * @brief Convert a Windows SID to a Unix uid if there already is a mapping
 882  *
 883  * @param *sid        Pointer to the domain SID to be resolved
 884  * @param *puid       Pointer to the resolved uid_t value
 885  *
 886  * @return #wbcErr
 887  *
 888  **/
 889 wbcErr wbcQuerySidToUid(const struct wbcDomainSid *sid,
 890                         uid_t *puid);
 891
 892 /**
 893  * @brief Convert a Unix uid to a Windows SID, allocating a SID if needed
 894  *
 895  * @param *ctx        wbclient Context
 896  * @param uid         Unix uid to be resolved
 897  * @param *sid        Pointer to the resolved domain SID
 898  *
 899  * @return #wbcErr
 900  *
 901  **/
 902 wbcErr wbcCtxUidToSid(struct wbcContext *ctx, uid_t uid,
 903                       struct wbcDomainSid *sid);
 904
 905 /**
 906  * @brief Convert a Unix uid to a Windows SID, allocating a SID if needed
 907  *
 908  * @param uid         Unix uid to be resolved
 909  * @param *sid        Pointer to the resolved domain SID
 910  *
 911  * @return #wbcErr
 912  *
 913  **/
 914 wbcErr wbcUidToSid(uid_t uid,
 915                    struct wbcDomainSid *sid);
 916
 917 /**
 918  * @brief Convert a Unix uid to a Windows SID if there already is a mapping
 919  *
 920  * @param uid         Unix uid to be resolved
 921  * @param *sid        Pointer to the resolved domain SID
 922  *
 923  * @return #wbcErr
 924  *
 925  **/
 926 wbcErr wbcQueryUidToSid(uid_t uid,
 927                         struct wbcDomainSid *sid);
 928
 929 /**
 930  * @brief Convert a Windows SID to a Unix gid, allocating a gid if needed
 931  *
 932  * @param *ctx        wbclient Context
 933  * @param *sid        Pointer to the domain SID to be resolved
 934  * @param *pgid       Pointer to the resolved gid_t value
 935  *
 936  * @return #wbcErr
 937  *
 938  **/
 939 wbcErr wbcCtxSidToGid(struct wbcContext *ctx,
 940                       const struct wbcDomainSid *sid,
 941                       gid_t *pgid);
 942
 943 /**
 944  * @brief Convert a Windows SID to a Unix gid, allocating a gid if needed
 945  *
 946  * @param *sid        Pointer to the domain SID to be resolved
 947  * @param *pgid       Pointer to the resolved gid_t value
 948  *
 949  * @return #wbcErr
 950  *
 951  **/
 952 wbcErr wbcSidToGid(const struct wbcDomainSid *sid,
 953                    gid_t *pgid);
 954
 955 /**
 956  * @brief Convert a Windows SID to a Unix gid if there already is a mapping
 957  *
 958  * @param *sid        Pointer to the domain SID to be resolved
 959  * @param *pgid       Pointer to the resolved gid_t value
 960  *
 961  * @return #wbcErr
 962  *
 963  **/
 964 wbcErr wbcQuerySidToGid(const struct wbcDomainSid *sid,
 965                         gid_t *pgid);
 966
 967 /**
 968  * @brief Convert a Unix gid to a Windows SID, allocating a SID if needed
 969  *
 970  * @param *ctx        wbclient Context
 971  * @param gid         Unix gid to be resolved
 972  * @param *sid        Pointer to the resolved domain SID
 973  *
 974  * @return #wbcErr
 975  *
 976  **/
 977 wbcErr wbcCtxGidToSid(struct wbcContext *ctx, gid_t gid,
 978                    struct wbcDomainSid *sid);
 979
 980 /**
 981  * @brief Convert a Unix gid to a Windows SID, allocating a SID if needed
 982  *
 983  * @param gid         Unix gid to be resolved
 984  * @param *sid        Pointer to the resolved domain SID
 985  *
 986  * @return #wbcErr
 987  *
 988  **/
 989 wbcErr wbcGidToSid(gid_t gid,
 990                    struct wbcDomainSid *sid);
 991
 992 /**
 993  * @brief Convert a Unix gid to a Windows SID if there already is a mapping
 994  *
 995  * @param gid         Unix gid to be resolved
 996  * @param *sid        Pointer to the resolved domain SID
 997  *
 998  * @return #wbcErr
 999  *
1000  **/
1001 wbcErr wbcQueryGidToSid(gid_t gid,
1002                         struct wbcDomainSid *sid);
1003
1004 enum wbcIdType {
1005         WBC_ID_TYPE_NOT_SPECIFIED,
1006         WBC_ID_TYPE_UID,
1007         WBC_ID_TYPE_GID,
1008         WBC_ID_TYPE_BOTH
1009 };
1010
1011 union wbcUnixIdContainer {
1012         uid_t uid;
1013         gid_t gid;
1014 };
1015
1016 struct wbcUnixId {
1017         enum wbcIdType type;
1018         union wbcUnixIdContainer id;
1019 };
1020
1021 /**
1022  * @brief Convert a list of sids to unix ids
1023  *
1024  * @param *ctx        wbclient Context
1025  * @param sids        Pointer to an array of SIDs to convert
1026  * @param num_sids    Number of SIDs
1027  * @param ids         Preallocated output array for translated IDs
1028  *
1029  * @return #wbcErr
1030  *
1031  **/
1032 wbcErr wbcCtxSidsToUnixIds(struct wbcContext *ctx,
1033                            const struct wbcDomainSid *sids, uint32_t num_sids,
1034                            struct wbcUnixId *ids);
1035
1036 /**
1037  * @brief Convert a list of sids to unix ids
1038  *
1039  * @param sids        Pointer to an array of SIDs to convert
1040  * @param num_sids    Number of SIDs
1041  * @param ids         Preallocated output array for translated IDs
1042  *
1043  * @return #wbcErr
1044  *
1045  **/
1046 wbcErr wbcSidsToUnixIds(const struct wbcDomainSid *sids, uint32_t num_sids,
1047                         struct wbcUnixId *ids);
1048
1049 wbcErr wbcCtxUnixIdsToSids(struct wbcContext *ctx,
1050                            const struct wbcUnixId *ids, uint32_t num_ids,
1051                            struct wbcDomainSid *sids);
1052 wbcErr wbcUnixIdsToSids(const struct wbcUnixId *ids, uint32_t num_ids,
1053                         struct wbcDomainSid *sids);
1054
1055 /**
1056  * @brief Obtain a new uid from Winbind
1057  *
1058  * @param *ctx        wbclient Context
1059  * @param *puid       Pointer to the allocated uid
1060  *
1061  * @return #wbcErr
1062  **/
1063 wbcErr wbcCtxAllocateUid(struct wbcContext *ctx, uid_t *puid);
1064
1065 /**
1066  * @brief Obtain a new uid from Winbind
1067  *
1068  * @param *puid       Pointer to the allocated uid
1069  *
1070  * @return #wbcErr
1071  **/
1072 wbcErr wbcAllocateUid(uid_t *puid);
1073
1074 /**
1075  * @brief Obtain a new gid from Winbind
1076  *
1077  * @param *ctx        wbclient Context
1078  * @param *pgid       Pointer to the allocated gid
1079  *
1080  * @return #wbcErr
1081  **/
1082 wbcErr wbcCtxAllocateGid(struct wbcContext *ctx, gid_t *pgid);
1083
1084 /**
1085  * @brief Obtain a new gid from Winbind
1086  *
1087  * @param *pgid       Pointer to the allocated gid
1088  *
1089  * @return #wbcErr
1090  **/
1091 wbcErr wbcAllocateGid(gid_t *pgid);
1092
1093 /**
1094  * @brief Set an user id mapping
1095  *
1096  * @param uid       Uid of the desired mapping.
1097  * @param *sid      Pointer to the sid of the desired mapping.
1098  *
1099  * @return #wbcErr
1100  *
1101  * @deprecated      This method is not implemented any more and should
1102  *                  be removed in the next major version change.
1103  **/
1104 wbcErr wbcSetUidMapping(uid_t uid, const struct wbcDomainSid *sid);
1105
1106 /**
1107  * @brief Set a group id mapping
1108  *
1109  * @param gid       Gid of the desired mapping.
1110  * @param *sid      Pointer to the sid of the desired mapping.
1111  *
1112  * @return #wbcErr
1113  *
1114  * @deprecated      This method is not implemented any more and should
1115  *                  be removed in the next major version change.
1116  **/
1117 wbcErr wbcSetGidMapping(gid_t gid, const struct wbcDomainSid *sid);
1118
1119 /**
1120  * @brief Remove a user id mapping
1121  *
1122  * @param uid       Uid of the mapping to remove.
1123  * @param *sid      Pointer to the sid of the mapping to remove.
1124  *
1125  * @return #wbcErr
1126  *
1127  * @deprecated      This method is not implemented any more and should
1128  *                  be removed in the next major version change.
1129  **/
1130 wbcErr wbcRemoveUidMapping(uid_t uid, const struct wbcDomainSid *sid);
1131
1132 /**
1133  * @brief Remove a group id mapping
1134  *
1135  * @param gid       Gid of the mapping to remove.
1136  * @param *sid      Pointer to the sid of the mapping to remove.
1137  *
1138  * @return #wbcErr
1139  *
1140  * @deprecated      This method is not implemented any more and should
1141  *                  be removed in the next major version change.
1142  **/
1143 wbcErr wbcRemoveGidMapping(gid_t gid, const struct wbcDomainSid *sid);
1144
1145 /**
1146  * @brief Set the highwater mark for allocated uids.
1147  *
1148  * @param uid_hwm      The new uid highwater mark value
1149  *
1150  * @return #wbcErr
1151  *
1152  * @deprecated      This method is not implemented any more and should
1153  *                  be removed in the next major version change.
1154  **/
1155 wbcErr wbcSetUidHwm(uid_t uid_hwm);
1156
1157 /**
1158  * @brief Set the highwater mark for allocated gids.
1159  *
1160  * @param gid_hwm      The new gid highwater mark value
1161  *
1162  * @return #wbcErr
1163  *
1164  * @deprecated      This method is not implemented any more and should
1165  *                  be removed in the next major version change.
1166  **/
1167 wbcErr wbcSetGidHwm(gid_t gid_hwm);
1168
1169 /**********************************************************
1170  * NSS Lookup User/Group details
1171  **********************************************************/
1172
1173 /**
1174  * @brief Fill in a struct passwd* for a domain user based
1175  *   on username
1176  *
1177  * @param *ctx      wbclient Context
1178  * @param *name     Username to lookup
1179  * @param **pwd     Pointer to resulting struct passwd* from the query.
1180  *
1181  * @return #wbcErr
1182  **/
1183 wbcErr wbcCtxGetpwnam(struct wbcContext *ctx,
1184                       const char *name, struct passwd **pwd);
1185
1186 /**
1187  * @brief Fill in a struct passwd* for a domain user based
1188  *   on username
1189  *
1190  * @param *name     Username to lookup
1191  * @param **pwd     Pointer to resulting struct passwd* from the query.
1192  *
1193  * @return #wbcErr
1194  **/
1195 wbcErr wbcGetpwnam(const char *name, struct passwd **pwd);
1196
1197 /**
1198  * @brief Fill in a struct passwd* for a domain user based
1199  *   on uid
1200  *
1201  * @param *ctx      wbclient Context
1202  * @param uid       Uid to lookup
1203  * @param **pwd     Pointer to resulting struct passwd* from the query.
1204  *
1205  * @return #wbcErr
1206  **/
1207 wbcErr wbcCtxGetpwuid(struct wbcContext *ctx,
1208                       uid_t uid, struct passwd **pwd);
1209
1210 /**
1211  * @brief Fill in a struct passwd* for a domain user based
1212  *   on uid
1213  *
1214  * @param uid       Uid to lookup
1215  * @param **pwd     Pointer to resulting struct passwd* from the query.
1216  *
1217  * @return #wbcErr
1218  **/
1219 wbcErr wbcGetpwuid(uid_t uid, struct passwd **pwd);
1220
1221 /**
1222  * @brief Fill in a struct passwd* for a domain user based
1223  *   on sid
1224  *
1225  * @param *ctx         wbclient Context
1226  * @param sid       Sid to lookup
1227  * @param **pwd     Pointer to resulting struct passwd* from the query.
1228  *
1229  * @return #wbcErr
1230  **/
1231 wbcErr wbcCtxGetpwsid(struct wbcContext *ctx,
1232                       struct wbcDomainSid * sid, struct passwd **pwd);
1233
1234 /**
1235  * @brief Fill in a struct passwd* for a domain user based
1236  *   on sid
1237  *
1238  * @param sid       Sid to lookup
1239  * @param **pwd     Pointer to resulting struct passwd* from the query.
1240  *
1241  * @return #wbcErr
1242  **/
1243 wbcErr wbcGetpwsid(struct wbcDomainSid * sid, struct passwd **pwd);
1244
1245 /**
1246  * @brief Fill in a struct passwd* for a domain user based
1247  *   on username
1248  *
1249  * @param *ctx      wbclient Context
1250  * @param *name     Username to lookup
1251  * @param **grp     Pointer to resulting struct group* from the query.
1252  *
1253  * @return #wbcErr
1254  **/
1255 wbcErr wbcCtxGetgrnam(struct wbcContext *ctx,
1256                       const char *name, struct group **grp);
1257
1258 /**
1259  * @brief Fill in a struct passwd* for a domain user based
1260  *   on username
1261  *
1262  * @param *name     Username to lookup
1263  * @param **grp     Pointer to resulting struct group* from the query.
1264  *
1265  * @return #wbcErr
1266  **/
1267 wbcErr wbcGetgrnam(const char *name, struct group **grp);
1268
1269 /**
1270  * @brief Fill in a struct passwd* for a domain user based
1271  *   on uid
1272  *
1273  * @param *ctx      wbclient Context
1274  * @param gid       Uid to lookup
1275  * @param **grp     Pointer to resulting struct group* from the query.
1276  *
1277  * @return #wbcErr
1278  **/
1279 wbcErr wbcCtxGetgrgid(struct wbcContext *ctx,
1280                       gid_t gid, struct group **grp);
1281
1282 /**
1283  * @brief Fill in a struct passwd* for a domain user based
1284  *   on uid
1285  *
1286  * @param gid       Uid to lookup
1287  * @param **grp     Pointer to resulting struct group* from the query.
1288  *
1289  * @return #wbcErr
1290  **/
1291 wbcErr wbcGetgrgid(gid_t gid, struct group **grp);
1292
1293 /**
1294  * @brief Reset the passwd iterator
1295  *
1296  * @param *ctx      wbclient Context
1297  *
1298  * @return #wbcErr
1299  **/
1300 wbcErr wbcCtxSetpwent(struct wbcContext *ctx);
1301
1302 /**
1303  * @brief Reset the passwd iterator
1304  *
1305  * @return #wbcErr
1306  **/
1307 wbcErr wbcSetpwent(void);
1308
1309 /**
1310  * @brief Close the passwd iterator
1311  *
1312  * @param *ctx      wbclient Context
1313  *
1314  * @return #wbcErr
1315  **/
1316 wbcErr wbcCtxEndpwent(struct wbcContext *ctx);
1317
1318 /**
1319  * @brief Close the passwd iterator
1320  *
1321  * @return #wbcErr
1322  **/
1323 wbcErr wbcEndpwent(void);
1324
1325 /**
1326  * @brief Return the next struct passwd* entry from the pwent iterator
1327  *
1328  * @param *ctx      wbclient Context
1329  * @param **pwd     Pointer to resulting struct passwd* from the query.
1330  *
1331  * @return #wbcErr
1332  **/
1333 wbcErr wbcCtxGetpwent(struct wbcContext *ctx, struct passwd **pwd);
1334
1335 /**
1336  * @brief Return the next struct passwd* entry from the pwent iterator
1337  *
1338  * @param **pwd     Pointer to resulting struct passwd* from the query.
1339  *
1340  * @return #wbcErr
1341  **/
1342 wbcErr wbcGetpwent(struct passwd **pwd);
1343
1344 /**
1345  * @brief Reset the group iterator
1346  *
1347  * @param *ctx      wbclient Context
1348  *
1349  * @return #wbcErr
1350  **/
1351 wbcErr wbcCtxSetgrent(struct wbcContext *ctx);
1352
1353 /**
1354  * @brief Reset the group iterator
1355  *
1356  * @return #wbcErr
1357  **/
1358 wbcErr wbcSetgrent(void);
1359
1360 /**
1361  * @brief Close the group iterator
1362  *
1363  * @param *ctx      wbclient Context
1364  *
1365  * @return #wbcErr
1366  **/
1367 wbcErr wbcCtxEndgrent(struct wbcContext *ctx);
1368
1369 /**
1370  * @brief Close the group iterator
1371  *
1372  * @return #wbcErr
1373  **/
1374 wbcErr wbcEndgrent(void);
1375
1376 /**
1377  * @brief Return the next struct group* entry from the pwent iterator
1378  *
1379  * @param *ctx      wbclient Context
1380  * @param **grp     Pointer to resulting struct group* from the query.
1381  *
1382  * @return #wbcErr
1383  **/
1384 wbcErr wbcCtxGetgrent(struct wbcContext *ctx, struct group **grp);
1385
1386 /**
1387  * @brief Return the next struct group* entry from the pwent iterator
1388  *
1389  * @param **grp     Pointer to resulting struct group* from the query.
1390  *
1391  * @return #wbcErr
1392  **/
1393 wbcErr wbcGetgrent(struct group **grp);
1394
1395 /**
1396  * @brief Return the next struct group* entry from the pwent iterator
1397  *
1398  * This is similar to #wbcGetgrent, just that the member list is empty
1399  *
1400  * @param *ctx      wbclient Context
1401  * @param **grp     Pointer to resulting struct group* from the query.
1402  *
1403  * @return #wbcErr
1404  **/
1405 wbcErr wbcCtxGetgrlist(struct wbcContext *ctx, struct group **grp);
1406
1407 /**
1408  * @brief Return the next struct group* entry from the pwent iterator
1409  *
1410  * This is similar to #wbcGetgrent, just that the member list is empty
1411  *
1412  * @param **grp     Pointer to resulting struct group* from the query.
1413  *
1414  * @return #wbcErr
1415  **/
1416 wbcErr wbcGetgrlist(struct group **grp);
1417
1418 /**
1419  * @brief Return the unix group array belonging to the given user
1420  *
1421  * @param *ctx           wbclient Context
1422  * @param *account       The given user name
1423  * @param *num_groups    Number of elements returned in the groups array
1424  * @param **_groups      Pointer to resulting gid_t array.
1425  *
1426  * @return #wbcErr
1427  **/
1428 wbcErr wbcCtxGetGroups(struct wbcContext *ctx,
1429                        const char *account,
1430                        uint32_t *num_groups,
1431                        gid_t **_groups);
1432
1433 /**
1434  * @brief Return the unix group array belonging to the given user
1435  *
1436  * @param *account       The given user name
1437  * @param *num_groups    Number of elements returned in the groups array
1438  * @param **_groups      Pointer to resulting gid_t array.
1439  *
1440  * @return #wbcErr
1441  **/
1442 wbcErr wbcGetGroups(const char *account,
1443                     uint32_t *num_groups,
1444                     gid_t **_groups);
1445
1446
1447 /**********************************************************
1448  * Lookup Domain information
1449  **********************************************************/
1450
1451 /**
1452  * @brief Lookup the current status of a trusted domain
1453  *
1454  * @param *ctx           wbclient Context
1455  * @param domain         The domain to query
1456  *
1457  * @param dinfo          A pointer to store the returned domain_info struct.
1458  *
1459  * @return #wbcErr
1460  **/
1461 wbcErr wbcCtxDomainInfo(struct wbcContext *ctx,
1462                         const char *domain,
1463                         struct wbcDomainInfo **dinfo);
1464
1465 /**
1466  * @brief Lookup the current status of a trusted domain
1467  *
1468  * @param domain         The domain to query
1469  *
1470  * @param dinfo          A pointer to store the returned domain_info struct.
1471  *
1472  * @return #wbcErr
1473  **/
1474 wbcErr wbcDomainInfo(const char *domain,
1475                      struct wbcDomainInfo **dinfo);
1476
1477 /**
1478  * @brief Lookup the currently contacted DCs
1479  *
1480  * @param *ctx          wbclient Context
1481  * @param domain        The domain to query
1482  *
1483  * @param num_dcs       Number of DCs currently known
1484  * @param dc_names      Names of the currently known DCs
1485  * @param dc_ips        IP addresses of the currently known DCs
1486  *
1487  * @return #wbcErr
1488  **/
1489 wbcErr wbcCtxDcInfo(struct wbcContext *ctx,
1490                     const char *domain, size_t *num_dcs,
1491                     const char ***dc_names, const char ***dc_ips);
1492
1493 /**
1494  * @brief Lookup the currently contacted DCs
1495  *
1496  * @param domain        The domain to query
1497  *
1498  * @param num_dcs       Number of DCs currently known
1499  * @param dc_names      Names of the currently known DCs
1500  * @param dc_ips        IP addresses of the currently known DCs
1501  *
1502  * @return #wbcErr
1503  **/
1504 wbcErr wbcDcInfo(const char *domain, size_t *num_dcs,
1505                  const char ***dc_names, const char ***dc_ips);
1506
1507 /**
1508  * @brief Enumerate the domain trusts known by Winbind
1509  *
1510  * @param *ctx          wbclient Context
1511  * @param **domains     Pointer to the allocated domain list array
1512  * @param *num_domains  Pointer to number of domains returned
1513  *
1514  * @return #wbcErr
1515  **/
1516 wbcErr wbcCtxListTrusts(struct wbcContext *ctx,
1517                         struct wbcDomainInfo **domains,
1518                         size_t *num_domains);
1519
1520 /**
1521  * @brief Enumerate the domain trusts known by Winbind
1522  *
1523  * @param **domains     Pointer to the allocated domain list array
1524  * @param *num_domains  Pointer to number of domains returned
1525  *
1526  * @return #wbcErr
1527  **/
1528 wbcErr wbcListTrusts(struct wbcDomainInfo **domains,
1529                      size_t *num_domains);
1530
1531 /* Flags for wbcLookupDomainController */
1532
1533 #define WBC_LOOKUP_DC_FORCE_REDISCOVERY        0x00000001
1534 #define WBC_LOOKUP_DC_DS_REQUIRED              0x00000010
1535 #define WBC_LOOKUP_DC_DS_PREFERRED             0x00000020
1536 #define WBC_LOOKUP_DC_GC_SERVER_REQUIRED       0x00000040
1537 #define WBC_LOOKUP_DC_PDC_REQUIRED             0x00000080
1538 #define WBC_LOOKUP_DC_BACKGROUND_ONLY          0x00000100
1539 #define WBC_LOOKUP_DC_IP_REQUIRED              0x00000200
1540 #define WBC_LOOKUP_DC_KDC_REQUIRED             0x00000400
1541 #define WBC_LOOKUP_DC_TIMESERV_REQUIRED        0x00000800
1542 #define WBC_LOOKUP_DC_WRITABLE_REQUIRED        0x00001000
1543 #define WBC_LOOKUP_DC_GOOD_TIMESERV_PREFERRED  0x00002000
1544 #define WBC_LOOKUP_DC_AVOID_SELF               0x00004000
1545 #define WBC_LOOKUP_DC_ONLY_LDAP_NEEDED         0x00008000
1546 #define WBC_LOOKUP_DC_IS_FLAT_NAME             0x00010000
1547 #define WBC_LOOKUP_DC_IS_DNS_NAME              0x00020000
1548 #define WBC_LOOKUP_DC_TRY_NEXTCLOSEST_SITE     0x00040000
1549 #define WBC_LOOKUP_DC_DS_6_REQUIRED            0x00080000
1550 #define WBC_LOOKUP_DC_RETURN_DNS_NAME          0x40000000
1551 #define WBC_LOOKUP_DC_RETURN_FLAT_NAME         0x80000000
1552
1553 /**
1554  * @brief Enumerate the domain trusts known by Winbind
1555  *
1556  * @param *ctx          wbclient Context
1557  * @param domain        Name of the domain to query for a DC
1558  * @param flags         Bit flags used to control the domain location query
1559  * @param *dc_info      Pointer to the returned domain controller information
1560  *
1561  * @return #wbcErr
1562  **/
1563 wbcErr wbcCtxLookupDomainController(struct wbcContext *ctx,
1564                                     const char *domain,
1565                                     uint32_t flags,
1566                                     struct wbcDomainControllerInfo **dc_info);
1567
1568 /**
1569  * @brief Enumerate the domain trusts known by Winbind
1570  *
1571  * @param domain        Name of the domain to query for a DC
1572  * @param flags         Bit flags used to control the domain location query
1573  * @param *dc_info      Pointer to the returned domain controller information
1574  *
1575  * @return #wbcErr
1576  **/
1577 wbcErr wbcLookupDomainController(const char *domain,
1578                                  uint32_t flags,
1579                                  struct wbcDomainControllerInfo **dc_info);
1580
1581 /**
1582  * @brief Get extended domain controller information
1583  *
1584  * @param *ctx          wbclient Context
1585  * @param domain        Name of the domain to query for a DC
1586  * @param guid          Guid of the domain to query for a DC
1587  * @param site          Site of the domain to query for a DC
1588  * @param flags         Bit flags used to control the domain location query
1589  * @param *dc_info      Pointer to the returned extended domain controller information
1590  *
1591  * @return #wbcErr
1592  **/
1593 wbcErr wbcCtxLookupDomainControllerEx(struct wbcContext *ctx,
1594                                       const char *domain,
1595                                       struct wbcGuid *guid,
1596                                       const char *site,
1597                                       uint32_t flags,
1598                                       struct wbcDomainControllerInfoEx **dc_info);
1599
1600 /**
1601  * @brief Get extended domain controller information
1602  *
1603  * @param domain        Name of the domain to query for a DC
1604  * @param guid          Guid of the domain to query for a DC
1605  * @param site          Site of the domain to query for a DC
1606  * @param flags         Bit flags used to control the domain location query
1607  * @param *dc_info      Pointer to the returned extended domain controller information
1608  *
1609  * @return #wbcErr
1610  **/
1611 wbcErr wbcLookupDomainControllerEx(const char *domain,
1612                                    struct wbcGuid *guid,
1613                                    const char *site,
1614                                    uint32_t flags,
1615                                    struct wbcDomainControllerInfoEx **dc_info);
1616
1617 /**********************************************************
1618  * Athenticate functions
1619  **********************************************************/
1620
1621 /**
1622  * @brief Authenticate a username/password pair
1623  *
1624  * @param *ctx         wbclient Context
1625  * @param username     Name of user to authenticate
1626  * @param password     Clear text password os user
1627  *
1628  * @return #wbcErr
1629  **/
1630 wbcErr wbcCtxAuthenticateUser(struct wbcContext *ctx,
1631                               const char *username,
1632                               const char *password);
1633
1634 /**
1635  * @brief Authenticate a username/password pair
1636  *
1637  * @param username     Name of user to authenticate
1638  * @param password     Clear text password os user
1639  *
1640  * @return #wbcErr
1641  **/
1642 wbcErr wbcAuthenticateUser(const char *username,
1643                            const char *password);
1644
1645 /**
1646  * @brief Authenticate with more detailed information
1647  *
1648  * @param *ctx         wbclient Context
1649  * @param params       Input parameters, WBC_AUTH_USER_LEVEL_HASH
1650  *                     is not supported yet
1651  * @param info         Output details on WBC_ERR_SUCCESS
1652  * @param error        Output details on WBC_ERR_AUTH_ERROR
1653  *
1654  * @return #wbcErr
1655  **/
1656 wbcErr wbcCtxAuthenticateUserEx(struct wbcContext *ctx,
1657                                 const struct wbcAuthUserParams *params,
1658                                 struct wbcAuthUserInfo **info,
1659                                 struct wbcAuthErrorInfo **error);
1660
1661 /**
1662  * @brief Authenticate with more detailed information
1663  *
1664  * @param params       Input parameters, WBC_AUTH_USER_LEVEL_HASH
1665  *                     is not supported yet
1666  * @param info         Output details on WBC_ERR_SUCCESS
1667  * @param error        Output details on WBC_ERR_AUTH_ERROR
1668  *
1669  * @return #wbcErr
1670  **/
1671 wbcErr wbcAuthenticateUserEx(const struct wbcAuthUserParams *params,
1672                              struct wbcAuthUserInfo **info,
1673                              struct wbcAuthErrorInfo **error);
1674
1675 /**
1676  * @brief Logon a User
1677  *
1678  * @param[in]  *ctx        wbclient Context
1679  * @param[in]  params      Pointer to a wbcLogonUserParams structure
1680  * @param[out] info        Pointer to a pointer to a wbcLogonUserInfo structure
1681  * @param[out] error       Pointer to a pointer to a wbcAuthErrorInfo structure
1682  * @param[out] policy      Pointer to a pointer to a wbcUserPasswordPolicyInfo structure
1683  *
1684  * @return #wbcErr
1685  **/
1686 wbcErr wbcCtxLogonUser(struct wbcContext *ctx,
1687                        const struct wbcLogonUserParams *params,
1688                        struct wbcLogonUserInfo **info,
1689                        struct wbcAuthErrorInfo **error,
1690                        struct wbcUserPasswordPolicyInfo **policy);
1691
1692 /**
1693  * @brief Logon a User
1694  *
1695  * @param[in]  params      Pointer to a wbcLogonUserParams structure
1696  * @param[out] info        Pointer to a pointer to a wbcLogonUserInfo structure
1697  * @param[out] error       Pointer to a pointer to a wbcAuthErrorInfo structure
1698  * @param[out] policy      Pointer to a pointer to a wbcUserPasswordPolicyInfo structure
1699  *
1700  * @return #wbcErr
1701  **/
1702 wbcErr wbcLogonUser(const struct wbcLogonUserParams *params,
1703                     struct wbcLogonUserInfo **info,
1704                     struct wbcAuthErrorInfo **error,
1705                     struct wbcUserPasswordPolicyInfo **policy);
1706
1707 /**
1708  * @brief Trigger a logoff notification to Winbind for a specific user
1709  *
1710  * @param *ctx        wbclient Context
1711  * @param username    Name of user to remove from Winbind's list of
1712  *                    logged on users.
1713  * @param uid         Uid assigned to the username
1714  * @param ccfilename  Absolute path to the Krb5 credentials cache to
1715  *                    be removed
1716  *
1717  * @return #wbcErr
1718  **/
1719 wbcErr wbcCtxLogoffUser(struct wbcContext *ctx,
1720                         const char *username, uid_t uid,
1721                         const char *ccfilename);
1722
1723 /**
1724  * @brief Trigger a logoff notification to Winbind for a specific user
1725  *
1726  * @param username    Name of user to remove from Winbind's list of
1727  *                    logged on users.
1728  * @param uid         Uid assigned to the username
1729  * @param ccfilename  Absolute path to the Krb5 credentials cache to
1730  *                    be removed
1731  *
1732  * @return #wbcErr
1733  **/
1734 wbcErr wbcLogoffUser(const char *username,
1735                      uid_t uid,
1736                      const char *ccfilename);
1737
1738 /**
1739  * @brief Trigger an extended logoff notification to Winbind for a specific user
1740  *
1741  * @param *ctx        wbclient Context
1742  * @param params      A wbcLogoffUserParams structure
1743  * @param error       User output details on error
1744  *
1745  * @return #wbcErr
1746  **/
1747 wbcErr wbcCtxLogoffUserEx(struct wbcContext *ctx,
1748                           const struct wbcLogoffUserParams *params,
1749                           struct wbcAuthErrorInfo **error);
1750
1751 /**
1752  * @brief Trigger an extended logoff notification to Winbind for a specific user
1753  *
1754  * @param params      A wbcLogoffUserParams structure
1755  * @param error       User output details on error
1756  *
1757  * @return #wbcErr
1758  **/
1759 wbcErr wbcLogoffUserEx(const struct wbcLogoffUserParams *params,
1760                        struct wbcAuthErrorInfo **error);
1761
1762 /**
1763  * @brief Change a password for a user
1764  *
1765  * @param *ctx          wbclient Context
1766  * @param username      Name of user to authenticate
1767  * @param old_password  Old clear text password of user
1768  * @param new_password  New clear text password of user
1769  *
1770  * @return #wbcErr
1771  **/
1772 wbcErr wbcCtxChangeUserPassword(struct wbcContext *ctx,
1773                                 const char *username,
1774                                 const char *old_password,
1775                                 const char *new_password);
1776
1777 /**
1778  * @brief Change a password for a user
1779  *
1780  * @param username      Name of user to authenticate
1781  * @param old_password  Old clear text password of user
1782  * @param new_password  New clear text password of user
1783  *
1784  * @return #wbcErr
1785  **/
1786 wbcErr wbcChangeUserPassword(const char *username,
1787                              const char *old_password,
1788                              const char *new_password);
1789
1790 /**
1791  * @brief Change a password for a user with more detailed information upon
1792  *   failure
1793  *
1794  * @param *ctx                  wbclient Context
1795  * @param params                Input parameters
1796  * @param error                 User output details on WBC_ERR_PWD_CHANGE_FAILED
1797  * @param reject_reason         New password reject reason on WBC_ERR_PWD_CHANGE_FAILED
1798  * @param policy                Password policy output details on WBC_ERR_PWD_CHANGE_FAILED
1799  *
1800  * @return #wbcErr
1801  **/
1802 wbcErr wbcCtxChangeUserPasswordEx(struct wbcContext *ctx,
1803                                   const struct wbcChangePasswordParams *params,
1804                                   struct wbcAuthErrorInfo **error,
1805                                   enum wbcPasswordChangeRejectReason *reject_reason,
1806                                   struct wbcUserPasswordPolicyInfo **policy);
1807
1808 /**
1809  * @brief Change a password for a user with more detailed information upon
1810  *   failure
1811  *
1812  * @param params                Input parameters
1813  * @param error                 User output details on WBC_ERR_PWD_CHANGE_FAILED
1814  * @param reject_reason         New password reject reason on WBC_ERR_PWD_CHANGE_FAILED
1815  * @param policy                Password policy output details on WBC_ERR_PWD_CHANGE_FAILED
1816  *
1817  * @return #wbcErr
1818  **/
1819 wbcErr wbcChangeUserPasswordEx(const struct wbcChangePasswordParams *params,
1820                                struct wbcAuthErrorInfo **error,
1821                                enum wbcPasswordChangeRejectReason *reject_reason,
1822                                struct wbcUserPasswordPolicyInfo **policy);
1823
1824 /**
1825  * @brief Authenticate a user with cached credentials
1826  *
1827  * @param *ctx       wbclient Context
1828  * @param *params    Pointer to a wbcCredentialCacheParams structure
1829  * @param **info     Pointer to a pointer to a wbcCredentialCacheInfo structure
1830  * @param **error    Pointer to a pointer to a wbcAuthErrorInfo structure
1831  *
1832  * @return #wbcErr
1833  **/
1834 wbcErr wbcCtxCredentialCache(struct wbcContext *ctx,
1835                              struct wbcCredentialCacheParams *params,
1836                              struct wbcCredentialCacheInfo **info,
1837                              struct wbcAuthErrorInfo **error);
1838
1839 /**
1840  * @brief Authenticate a user with cached credentials
1841  *
1842  * @param *params    Pointer to a wbcCredentialCacheParams structure
1843  * @param **info     Pointer to a pointer to a wbcCredentialCacheInfo structure
1844  * @param **error    Pointer to a pointer to a wbcAuthErrorInfo structure
1845  *
1846  * @return #wbcErr
1847  **/
1848 wbcErr wbcCredentialCache(struct wbcCredentialCacheParams *params,
1849                           struct wbcCredentialCacheInfo **info,
1850                           struct wbcAuthErrorInfo **error);
1851
1852 /**
1853  * @brief Save a password with winbind for doing wbcCredentialCache() later
1854  *
1855  * @param *ctx       wbclient Context
1856  * @param *user      Username
1857  * @param *password  Password
1858  *
1859  * @return #wbcErr
1860  **/
1861 wbcErr wbcCtxCredentialSave(struct wbcContext *ctx,
1862                             const char *user, const char *password);
1863
1864 /**
1865  * @brief Save a password with winbind for doing wbcCredentialCache() later
1866  *
1867  * @param *user      Username
1868  * @param *password  Password
1869  *
1870  * @return #wbcErr
1871  **/
1872 wbcErr wbcCredentialSave(const char *user, const char *password);
1873
1874 /**********************************************************
1875  * Resolve functions
1876  **********************************************************/
1877
1878 /**
1879  * @brief Resolve a NetbiosName via WINS
1880  *
1881  * @param *ctx         wbclient Context
1882  * @param name         Name to resolve
1883  * @param *ip          Pointer to the ip address string
1884  *
1885  * @return #wbcErr
1886  **/
1887 wbcErr wbcCtxResolveWinsByName(struct wbcContext *ctx,
1888                                const char *name, char **ip);
1889
1890 /**
1891  * @brief Resolve a NetbiosName via WINS
1892  *
1893  * @param name         Name to resolve
1894  * @param *ip          Pointer to the ip address string
1895  *
1896  * @return #wbcErr
1897  **/
1898 wbcErr wbcResolveWinsByName(const char *name, char **ip);
1899
1900 /**
1901  * @brief Resolve an IP address via WINS into a NetbiosName
1902  *
1903  * @param *ctx         wbclient Context
1904  * @param ip           The ip address string
1905  * @param *name        Pointer to the name
1906  *
1907  * @return #wbcErr
1908  *
1909  **/
1910 wbcErr wbcCtxResolveWinsByIP(struct wbcContext *ctx,
1911                              const char *ip, char **name);
1912
1913 /**
1914  * @brief Resolve an IP address via WINS into a NetbiosName
1915  *
1916  * @param ip           The ip address string
1917  * @param *name        Pointer to the name
1918  *
1919  * @return #wbcErr
1920  *
1921  **/
1922 wbcErr wbcResolveWinsByIP(const char *ip, char **name);
1923
1924 /**********************************************************
1925  * Trusted domain functions
1926  **********************************************************/
1927
1928 /**
1929  * @brief Trigger a verification of the trust credentials of a specific domain
1930  *
1931  * @param *ctx         wbclient Context
1932  * @param *domain      The name of the domain.
1933  * @param error        Output details on WBC_ERR_AUTH_ERROR
1934  *
1935  * @return #wbcErr
1936  **/
1937 wbcErr wbcCtxCheckTrustCredentials(struct wbcContext *ctx, const char *domain,
1938                                    struct wbcAuthErrorInfo **error);
1939
1940 /**
1941  * @brief Trigger a verification of the trust credentials of a specific domain
1942  *
1943  * @param *domain      The name of the domain.
1944  * @param error        Output details on WBC_ERR_AUTH_ERROR
1945  *
1946  * @return #wbcErr
1947  **/
1948 wbcErr wbcCheckTrustCredentials(const char *domain,
1949                                 struct wbcAuthErrorInfo **error);
1950
1951 /**
1952  * @brief Trigger a change of the trust credentials for a specific domain
1953  *
1954  * @param *ctx         wbclient Context
1955  * @param *domain      The name of the domain.
1956  * @param error        Output details on WBC_ERR_AUTH_ERROR
1957  *
1958  * @return #wbcErr
1959  **/
1960 wbcErr wbcCtxChangeTrustCredentials(struct wbcContext *ctx, const char *domain,
1961                                     struct wbcAuthErrorInfo **error);
1962
1963 /**
1964  * @brief Trigger a change of the trust credentials for a specific domain
1965  *
1966  * @param *domain      The name of the domain.
1967  * @param error        Output details on WBC_ERR_AUTH_ERROR
1968  *
1969  * @return #wbcErr
1970  **/
1971 wbcErr wbcChangeTrustCredentials(const char *domain,
1972                                  struct wbcAuthErrorInfo **error);
1973
1974 /**
1975  * @brief Trigger a change of the trust credentials for a specific domain
1976  *        on the optionally given domain controller
1977  *
1978  * @param *ctx         wbclient Context
1979  * @param *domain      The name of the domain.
1980  * @param *dcname      The host name of the domain controller.
1981  * @param error        Output details on WBC_ERR_AUTH_ERROR
1982  *
1983  * @return #wbcErr
1984  *
1985  * @see wbcCtxChangeTrustCredentials()
1986  **/
1987 wbcErr wbcCtxChangeTrustCredentialsAt(struct wbcContext *ctx,
1988                                       const char *domain,
1989                                       const char *dcname,
1990                                       struct wbcAuthErrorInfo **error);
1991
1992 /**
1993  * @brief Trigger a change of the trust credentials for a specific domain
1994  *        on the optionally given domain controller
1995  *
1996  * @param *domain      The name of the domain.
1997  * @param *dcname      The host name of the domain controller.
1998  * @param error        Output details on WBC_ERR_AUTH_ERROR
1999  *
2000  * @return #wbcErr
2001  *
2002  * @see wbcChangeTrustCredentials()
2003  **/
2004 wbcErr wbcChangeTrustCredentialsAt(const char *domain,
2005                                    const char *dcname,
2006                                    struct wbcAuthErrorInfo **error);
2007
2008 /**
2009  * @brief Trigger a no-op call through the NETLOGON pipe. Low-cost
2010  *        version of wbcCheckTrustCredentials
2011  *
2012  * @param *ctx         wbclient Context
2013  * @param *domain      The name of the domain, only NULL for the default domain is
2014  *                     supported yet. Other values than NULL will result in
2015  *                     WBC_ERR_NOT_IMPLEMENTED.
2016  * @param error        Output details on WBC_ERR_AUTH_ERROR
2017  *
2018  * @return #wbcErr
2019  **/
2020 wbcErr wbcCtxPingDc(struct wbcContext *ctx, const char *domain,
2021                     struct wbcAuthErrorInfo **error);
2022
2023 /**
2024  * @brief Trigger a no-op call through the NETLOGON pipe. Low-cost
2025  *        version of wbcCheckTrustCredentials
2026  *
2027  * @param *domain      The name of the domain, only NULL for the default domain is
2028  *                     supported yet. Other values than NULL will result in
2029  *                     WBC_ERR_NOT_IMPLEMENTED.
2030  * @param error        Output details on WBC_ERR_AUTH_ERROR
2031  *
2032  * @return #wbcErr
2033  **/
2034 wbcErr wbcPingDc(const char *domain, struct wbcAuthErrorInfo **error);
2035
2036 /**
2037  * @brief Trigger a no-op call through the NETLOGON pipe. Low-cost
2038  *        version of wbcCheckTrustCredentials
2039  *
2040  * @param *ctx         wbclient Context
2041  * @param *domain      The name of the domain, only NULL for the default domain is
2042  *                     supported yet. Other values than NULL will result in
2043  *                     WBC_ERR_NOT_IMPLEMENTED.
2044  * @param error        Output details on WBC_ERR_AUTH_ERROR
2045  * @param dcname       DC that was attempted to ping
2046  *
2047  * @return #wbcErr
2048  **/
2049 wbcErr wbcCtxPingDc2(struct wbcContext *ctx, const char *domain,
2050                      struct wbcAuthErrorInfo **error,
2051                      char **dcname);
2052
2053 /**
2054  * @brief Trigger a no-op call through the NETLOGON pipe. Low-cost
2055  *        version of wbcCheckTrustCredentials
2056  *
2057  * @param *domain      The name of the domain, only NULL for the default domain is
2058  *                     supported yet. Other values than NULL will result in
2059  *                     WBC_ERR_NOT_IMPLEMENTED.
2060  * @param error        Output details on WBC_ERR_AUTH_ERROR
2061  * @param dcname       DC that was attempted to ping
2062  *
2063  * @return #wbcErr
2064  **/
2065 wbcErr wbcPingDc2(const char *domain, struct wbcAuthErrorInfo **error,
2066                   char **dcname);
2067
2068 /**********************************************************
2069  * Helper functions
2070  **********************************************************/
2071
2072 /**
2073  * @brief Initialize a named blob and add to list of blobs
2074  *
2075  * @param[in,out] num_blobs     Pointer to the number of blobs
2076  * @param[in,out] blobs         Pointer to an array of blobs
2077  * @param[in]     name          Name of the new named blob
2078  * @param[in]     flags         Flags of the new named blob
2079  * @param[in]     data          Blob data of new blob
2080  * @param[in]     length        Blob data length of new blob
2081  *
2082  * @return #wbcErr
2083  **/
2084 wbcErr wbcAddNamedBlob(size_t *num_blobs,
2085                        struct wbcNamedBlob **blobs,
2086                        const char *name,
2087                        uint32_t flags,
2088                        uint8_t *data,
2089                        size_t length);
2090
2091 /**
2092  * @brief Set the name of the process which call wbclient.
2093  *
2094  * By default wbclient will figure out the process name. This should just be
2095  * used in special cases like pam modules or similar. Only alpha numeric
2096  * chars in ASCII are allowed.
2097  *
2098  * This function should only be called once!
2099  *
2100  * @param[in]  name             The process name to set.
2101  */
2102 void wbcSetClientProcessName(const char *name);
2103
2104 #endif      /* _WBCLIENT_H */