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