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