nsswitch/libwbclient/wbclient.h

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