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