s3: Implement wbcGetpwsid
[ira/wip.git] / 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  **/
65 #define WBCLIENT_MAJOR_VERSION 0
66 #define WBCLIENT_MINOR_VERSION 3
67 #define WBCLIENT_VENDOR_VERSION "Samba libwbclient"
68 struct wbcLibraryDetails {
69         uint16_t major_version;
70         uint16_t minor_version;
71         const char *vendor_version;
72 };
73
74 /**
75  *  @brief Some useful details about the running winbindd
76  *
77  **/
78 struct wbcInterfaceDetails {
79         uint32_t interface_version;
80         const char *winbind_version;
81         char winbind_separator;
82         const char *netbios_name;
83         const char *netbios_domain;
84         const char *dns_domain;
85 };
86
87 /*
88  * Data types used by the Winbind Client API
89  */
90
91 #ifndef WBC_MAXSUBAUTHS
92 #define WBC_MAXSUBAUTHS 15 /* max sub authorities in a SID */
93 #endif
94
95 /**
96  *  @brief Windows Security Identifier
97  *
98  **/
99
100 struct wbcDomainSid {
101         uint8_t   sid_rev_num;
102         uint8_t   num_auths;
103         uint8_t   id_auth[6];
104         uint32_t  sub_auths[WBC_MAXSUBAUTHS];
105 };
106
107 /**
108  * @brief Security Identifier type
109  **/
110
111 enum wbcSidType {
112         WBC_SID_NAME_USE_NONE=0,
113         WBC_SID_NAME_USER=1,
114         WBC_SID_NAME_DOM_GRP=2,
115         WBC_SID_NAME_DOMAIN=3,
116         WBC_SID_NAME_ALIAS=4,
117         WBC_SID_NAME_WKN_GRP=5,
118         WBC_SID_NAME_DELETED=6,
119         WBC_SID_NAME_INVALID=7,
120         WBC_SID_NAME_UNKNOWN=8,
121         WBC_SID_NAME_COMPUTER=9
122 };
123
124 /**
125  * @brief Security Identifier with attributes
126  **/
127
128 struct wbcSidWithAttr {
129         struct wbcDomainSid sid;
130         uint32_t attributes;
131 };
132
133 /* wbcSidWithAttr->attributes */
134
135 #define WBC_SID_ATTR_GROUP_MANDATORY            0x00000001
136 #define WBC_SID_ATTR_GROUP_ENABLED_BY_DEFAULT   0x00000002
137 #define WBC_SID_ATTR_GROUP_ENABLED              0x00000004
138 #define WBC_SID_ATTR_GROUP_OWNER                0x00000008
139 #define WBC_SID_ATTR_GROUP_USEFOR_DENY_ONLY     0x00000010
140 #define WBC_SID_ATTR_GROUP_RESOURCE             0x20000000
141 #define WBC_SID_ATTR_GROUP_LOGON_ID             0xC0000000
142
143 /**
144  *  @brief Windows GUID
145  *
146  **/
147
148 struct wbcGuid {
149         uint32_t time_low;
150         uint16_t time_mid;
151         uint16_t time_hi_and_version;
152         uint8_t clock_seq[2];
153         uint8_t node[6];
154 };
155
156 /**
157  * @brief Domain Information
158  **/
159
160 struct wbcDomainInfo {
161         char *short_name;
162         char *dns_name;
163         struct wbcDomainSid sid;
164         uint32_t domain_flags;
165         uint32_t trust_flags;
166         uint32_t trust_type;
167 };
168
169 /* wbcDomainInfo->domain_flags */
170
171 #define WBC_DOMINFO_DOMAIN_UNKNOWN    0x00000000
172 #define WBC_DOMINFO_DOMAIN_NATIVE     0x00000001
173 #define WBC_DOMINFO_DOMAIN_AD         0x00000002
174 #define WBC_DOMINFO_DOMAIN_PRIMARY    0x00000004
175 #define WBC_DOMINFO_DOMAIN_OFFLINE    0x00000008
176
177 /* wbcDomainInfo->trust_flags */
178
179 #define WBC_DOMINFO_TRUST_TRANSITIVE  0x00000001
180 #define WBC_DOMINFO_TRUST_INCOMING    0x00000002
181 #define WBC_DOMINFO_TRUST_OUTGOING    0x00000004
182
183 /* wbcDomainInfo->trust_type */
184
185 #define WBC_DOMINFO_TRUSTTYPE_NONE       0x00000000
186 #define WBC_DOMINFO_TRUSTTYPE_FOREST     0x00000001
187 #define WBC_DOMINFO_TRUSTTYPE_IN_FOREST  0x00000002
188 #define WBC_DOMINFO_TRUSTTYPE_EXTERNAL   0x00000003
189
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 *p 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 *str          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 *str          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 domain      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 pdomain     Resolved Domain name (possibly "")
591  * @param pname       Resolved User or group name
592  * @param *pname_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 Lists Users
621  **/
622 wbcErr wbcListUsers(const char *domain_name,
623                     uint32_t *num_users,
624                     const char ***users);
625
626 /**
627  * @brief Lists Groups
628  **/
629 wbcErr wbcListGroups(const char *domain_name,
630                      uint32_t *num_groups,
631                      const char ***groups);
632
633 wbcErr wbcGetDisplayName(const struct wbcDomainSid *sid,
634                          char **pdomain,
635                          char **pfullname,
636                          enum wbcSidType *pname_type);
637
638 /**********************************************************
639  * SID/uid/gid Mappings
640  **********************************************************/
641
642 /**
643  * @brief Convert a Windows SID to a Unix uid, allocating an uid if needed
644  *
645  * @param *sid        Pointer to the domain SID to be resolved
646  * @param *puid       Pointer to the resolved uid_t value
647  *
648  * @return #wbcErr
649  *
650  **/
651 wbcErr wbcSidToUid(const struct wbcDomainSid *sid,
652                    uid_t *puid);
653
654 /**
655  * @brief Convert a Windows SID to a Unix uid if there already is a mapping
656  *
657  * @param *sid        Pointer to the domain SID to be resolved
658  * @param *puid       Pointer to the resolved uid_t value
659  *
660  * @return #wbcErr
661  *
662  **/
663 wbcErr wbcQuerySidToUid(const struct wbcDomainSid *sid,
664                         uid_t *puid);
665
666 /**
667  * @brief Convert a Unix uid to a Windows SID, allocating a SID if needed
668  *
669  * @param uid         Unix uid to be resolved
670  * @param *sid        Pointer to the resolved domain SID
671  *
672  * @return #wbcErr
673  *
674  **/
675 wbcErr wbcUidToSid(uid_t uid,
676                    struct wbcDomainSid *sid);
677
678 /**
679  * @brief Convert a Unix uid to a Windows SID if there already is a mapping
680  *
681  * @param uid         Unix uid to be resolved
682  * @param *sid        Pointer to the resolved domain SID
683  *
684  * @return #wbcErr
685  *
686  **/
687 wbcErr wbcQueryUidToSid(uid_t uid,
688                         struct wbcDomainSid *sid);
689
690 /**
691  * @brief Convert a Windows SID to a Unix gid, allocating a gid if needed
692  *
693  * @param *sid        Pointer to the domain SID to be resolved
694  * @param *pgid       Pointer to the resolved gid_t value
695  *
696  * @return #wbcErr
697  *
698  **/
699 wbcErr wbcSidToGid(const struct wbcDomainSid *sid,
700                    gid_t *pgid);
701
702 /**
703  * @brief Convert a Windows SID to a Unix gid if there already is a mapping
704  *
705  * @param *sid        Pointer to the domain SID to be resolved
706  * @param *pgid       Pointer to the resolved gid_t value
707  *
708  * @return #wbcErr
709  *
710  **/
711 wbcErr wbcQuerySidToGid(const struct wbcDomainSid *sid,
712                         gid_t *pgid);
713
714 /**
715  * @brief Convert a Unix gid to a Windows SID, allocating a SID if needed
716  *
717  * @param gid         Unix gid to be resolved
718  * @param *sid        Pointer to the resolved domain SID
719  *
720  * @return #wbcErr
721  *
722  **/
723 wbcErr wbcGidToSid(gid_t gid,
724                    struct wbcDomainSid *sid);
725
726 /**
727  * @brief Convert a Unix gid to a Windows SID if there already is a mapping
728  *
729  * @param gid         Unix gid to be resolved
730  * @param *sid        Pointer to the resolved domain SID
731  *
732  * @return #wbcErr
733  *
734  **/
735 wbcErr wbcQueryGidToSid(gid_t gid,
736                         struct wbcDomainSid *sid);
737
738 /**
739  * @brief Obtain a new uid from Winbind
740  *
741  * @param *puid      *pointer to the allocated uid
742  *
743  * @return #wbcErr
744  **/
745 wbcErr wbcAllocateUid(uid_t *puid);
746
747 /**
748  * @brief Obtain a new gid from Winbind
749  *
750  * @param *pgid      Pointer to the allocated gid
751  *
752  * @return #wbcErr
753  **/
754 wbcErr wbcAllocateGid(gid_t *pgid);
755
756 /**
757  * @brief Set an user id mapping
758  *
759  * @param uid       Uid of the desired mapping.
760  * @param *sid      Pointer to the sid of the diresired mapping.
761  *
762  * @return #wbcErr
763  **/
764 wbcErr wbcSetUidMapping(uid_t uid, const struct wbcDomainSid *sid);
765
766 /**
767  * @brief Set a group id mapping
768  *
769  * @param gid       Gid of the desired mapping.
770  * @param *sid      Pointer to the sid of the diresired mapping.
771  *
772  * @return #wbcErr
773  **/
774 wbcErr wbcSetGidMapping(gid_t gid, const struct wbcDomainSid *sid);
775
776 /**
777  * @brief Remove a user id mapping
778  *
779  * @param uid       Uid of the mapping to remove.
780  * @param *sid      Pointer to the sid of the mapping to remove.
781  *
782  * @return #wbcErr
783  **/
784 wbcErr wbcRemoveUidMapping(uid_t uid, const struct wbcDomainSid *sid);
785
786 /**
787  * @brief Remove a group id mapping
788  *
789  * @param gid       Gid of the mapping to remove.
790  * @param *sid      Pointer to the sid of the mapping to remove.
791  *
792  * @return #wbcErr
793  **/
794 wbcErr wbcRemoveGidMapping(gid_t gid, const struct wbcDomainSid *sid);
795
796 /**
797  * @brief Set the highwater mark for allocated uids.
798  *
799  * @param uid_hwm      The new uid highwater mark value
800  *
801  * @return #wbcErr
802  **/
803 wbcErr wbcSetUidHwm(uid_t uid_hwm);
804
805 /**
806  * @brief Set the highwater mark for allocated gids.
807  *
808  * @param gid_hwm      The new gid highwater mark value
809  *
810  * @return #wbcErr
811  **/
812 wbcErr wbcSetGidHwm(gid_t gid_hwm);
813
814 /**********************************************************
815  * NSS Lookup User/Group details
816  **********************************************************/
817
818 /**
819  * @brief Fill in a struct passwd* for a domain user based
820  *   on username
821  *
822  * @param *name     Username to lookup
823  * @param **pwd     Pointer to resulting struct passwd* from the query.
824  *
825  * @return #wbcErr
826  **/
827 wbcErr wbcGetpwnam(const char *name, struct passwd **pwd);
828
829 /**
830  * @brief Fill in a struct passwd* for a domain user based
831  *   on uid
832  *
833  * @param uid       Uid to lookup
834  * @param **pwd     Pointer to resulting struct passwd* from the query.
835  *
836  * @return #wbcErr
837  **/
838 wbcErr wbcGetpwuid(uid_t uid, struct passwd **pwd);
839
840 /**
841  * @brief Fill in a struct passwd* for a domain user based
842  *   on sid
843  *
844  * @param sid       Sid to lookup
845  * @param **pwd     Pointer to resulting struct passwd* from the query.
846  *
847  * @return #wbcErr
848  **/
849 wbcErr wbcGetpwsid(struct wbcDomainSid * sid, struct passwd **pwd);
850
851 /**
852  * @brief Fill in a struct passwd* for a domain user based
853  *   on username
854  *
855  * @param *name     Username to lookup
856  * @param **grp     Pointer to resulting struct group* from the query.
857  *
858  * @return #wbcErr
859  **/
860 wbcErr wbcGetgrnam(const char *name, struct group **grp);
861
862 /**
863  * @brief Fill in a struct passwd* for a domain user based
864  *   on uid
865  *
866  * @param gid       Uid to lookup
867  * @param **grp     Pointer to resulting struct group* from the query.
868  *
869  * @return #wbcErr
870  **/
871 wbcErr wbcGetgrgid(gid_t gid, struct group **grp);
872
873 /**
874  * @brief Reset the passwd iterator
875  *
876  * @return #wbcErr
877  **/
878 wbcErr wbcSetpwent(void);
879
880 /**
881  * @brief Close the passwd iterator
882  *
883  * @return #wbcErr
884  **/
885 wbcErr wbcEndpwent(void);
886
887 /**
888  * @brief Return the next struct passwd* entry from the pwent iterator
889  *
890  * @param **pwd       Pointer to resulting struct passwd* from the query.
891  *
892  * @return #wbcErr
893  **/
894 wbcErr wbcGetpwent(struct passwd **pwd);
895
896 /**
897  * @brief Reset the group iterator
898  *
899  * @return #wbcErr
900  **/
901 wbcErr wbcSetgrent(void);
902
903 /**
904  * @brief Close the group iterator
905  *
906  * @return #wbcErr
907  **/
908 wbcErr wbcEndgrent(void);
909
910 /**
911  * @brief Return the next struct group* entry from the pwent iterator
912  *
913  * @param **grp       Pointer to resulting struct group* from the query.
914  *
915  * @return #wbcErr
916  **/
917 wbcErr wbcGetgrent(struct group **grp);
918
919 /**
920  * @brief Return the next struct group* entry from the pwent iterator
921  *
922  * This is similar to #wbcGetgrent, just that the member list is empty
923  *
924  * @param **grp       Pointer to resulting struct group* from the query.
925  *
926  * @return #wbcErr
927  **/
928 wbcErr wbcGetgrlist(struct group **grp);
929
930 /**
931  * @brief Return the unix group array belonging to the given user
932  *
933  * @param *account       The given user name
934  * @param *num_groups    Number of elements returned in the groups array
935  * @param **_groups      Pointer to resulting gid_t array.
936  *
937  * @return #wbcErr
938  **/
939 wbcErr wbcGetGroups(const char *account,
940                     uint32_t *num_groups,
941                     gid_t **_groups);
942
943
944 /**********************************************************
945  * Lookup Domain information
946  **********************************************************/
947
948 /**
949  * @brief Lookup the current status of a trusted domain
950  *
951  * @param domain      Domain to query
952  * @param *dinfo       Pointer to returned domain_info struct
953  *
954  * @return #wbcErr
955  **/
956 wbcErr wbcDomainInfo(const char *domain,
957                      struct wbcDomainInfo **info);
958
959 /**
960  * @brief Enumerate the domain trusts known by Winbind
961  *
962  * @param **domains     Pointer to the allocated domain list array
963  * @param *num_domains  Pointer to number of domains returned
964  *
965  * @return #wbcErr
966  **/
967 wbcErr wbcListTrusts(struct wbcDomainInfo **domains,
968                      size_t *num_domains);
969
970 /* Flags for wbcLookupDomainController */
971
972 #define WBC_LOOKUP_DC_FORCE_REDISCOVERY        0x00000001
973 #define WBC_LOOKUP_DC_DS_REQUIRED              0x00000010
974 #define WBC_LOOKUP_DC_DS_PREFERRED             0x00000020
975 #define WBC_LOOKUP_DC_GC_SERVER_REQUIRED       0x00000040
976 #define WBC_LOOKUP_DC_PDC_REQUIRED             0x00000080
977 #define WBC_LOOKUP_DC_BACKGROUND_ONLY          0x00000100
978 #define WBC_LOOKUP_DC_IP_REQUIRED              0x00000200
979 #define WBC_LOOKUP_DC_KDC_REQUIRED             0x00000400
980 #define WBC_LOOKUP_DC_TIMESERV_REQUIRED        0x00000800
981 #define WBC_LOOKUP_DC_WRITABLE_REQUIRED        0x00001000
982 #define WBC_LOOKUP_DC_GOOD_TIMESERV_PREFERRED  0x00002000
983 #define WBC_LOOKUP_DC_AVOID_SELF               0x00004000
984 #define WBC_LOOKUP_DC_ONLY_LDAP_NEEDED         0x00008000
985 #define WBC_LOOKUP_DC_IS_FLAT_NAME             0x00010000
986 #define WBC_LOOKUP_DC_IS_DNS_NAME              0x00020000
987 #define WBC_LOOKUP_DC_TRY_NEXTCLOSEST_SITE     0x00040000
988 #define WBC_LOOKUP_DC_DS_6_REQUIRED            0x00080000
989 #define WBC_LOOKUP_DC_RETURN_DNS_NAME          0x40000000
990 #define WBC_LOOKUP_DC_RETURN_FLAT_NAME         0x80000000
991
992 /**
993  * @brief Enumerate the domain trusts known by Winbind
994  *
995  * @param domain        Name of the domain to query for a DC
996  * @param flags         Bit flags used to control the domain location query
997  * @param *dc_info      Pointer to the returned domain controller information
998  *
999  * @return #wbcErr
1000  **/
1001 wbcErr wbcLookupDomainController(const char *domain,
1002                                  uint32_t flags,
1003                                  struct wbcDomainControllerInfo **dc_info);
1004
1005 /**
1006  * @brief Get extended domain controller information
1007  *
1008  * @param domain        Name of the domain to query for a DC
1009  * @param guid          Guid of the domain to query for a DC
1010  * @param site          Site of the domain to query for a DC
1011  * @param flags         Bit flags used to control the domain location query
1012  * @param *dc_info      Pointer to the returned extended domain controller information
1013  *
1014  * @return #wbcErr
1015  **/
1016 wbcErr wbcLookupDomainControllerEx(const char *domain,
1017                                    struct wbcGuid *guid,
1018                                    const char *site,
1019                                    uint32_t flags,
1020                                    struct wbcDomainControllerInfoEx **dc_info);
1021
1022 /**********************************************************
1023  * Athenticate functions
1024  **********************************************************/
1025
1026 /**
1027  * @brief Authenticate a username/password pair
1028  *
1029  * @param username     Name of user to authenticate
1030  * @param password     Clear text password os user
1031  *
1032  * @return #wbcErr
1033  **/
1034 wbcErr wbcAuthenticateUser(const char *username,
1035                            const char *password);
1036
1037 /**
1038  * @brief Authenticate with more detailed information
1039  *
1040  * @param params       Input parameters, WBC_AUTH_USER_LEVEL_HASH
1041  *                     is not supported yet
1042  * @param info         Output details on WBC_ERR_SUCCESS
1043  * @param error        Output details on WBC_ERR_AUTH_ERROR
1044  *
1045  * @return #wbcErr
1046  **/
1047 wbcErr wbcAuthenticateUserEx(const struct wbcAuthUserParams *params,
1048                              struct wbcAuthUserInfo **info,
1049                              struct wbcAuthErrorInfo **error);
1050
1051 /**
1052  * @brief Logon a User
1053  *
1054  * @param[in]  params      Pointer to a wbcLogonUserParams structure
1055  * @param[out] info        Pointer to a pointer to a wbcLogonUserInfo structure
1056  * @param[out] error       Pointer to a pointer to a wbcAuthErrorInfo structure
1057  * @param[out] policy      Pointer to a pointer to a wbcUserPasswordPolicyInfo structure
1058  *
1059  * @return #wbcErr
1060  **/
1061 wbcErr wbcLogonUser(const struct wbcLogonUserParams *params,
1062                     struct wbcLogonUserInfo **info,
1063                     struct wbcAuthErrorInfo **error,
1064                     struct wbcUserPasswordPolicyInfo **policy);
1065
1066 /**
1067  * @brief Trigger a logoff notification to Winbind for a specific user
1068  *
1069  * @param username    Name of user to remove from Winbind's list of
1070  *                    logged on users.
1071  * @param uid         Uid assigned to the username
1072  * @param ccfilename  Absolute path to the Krb5 credentials cache to
1073  *                    be removed
1074  *
1075  * @return #wbcErr
1076  **/
1077 wbcErr wbcLogoffUser(const char *username,
1078                      uid_t uid,
1079                      const char *ccfilename);
1080
1081 /**
1082  * @brief Trigger an extended logoff notification to Winbind for a specific user
1083  *
1084  * @param params      A wbcLogoffUserParams structure
1085  * @param error       User output details on error
1086  *
1087  * @return #wbcErr
1088  **/
1089 wbcErr wbcLogoffUserEx(const struct wbcLogoffUserParams *params,
1090                        struct wbcAuthErrorInfo **error);
1091
1092 /**
1093  * @brief Change a password for a user
1094  *
1095  * @param username      Name of user to authenticate
1096  * @param old_password  Old clear text password of user
1097  * @param new_password  New clear text password of user
1098  *
1099  * @return #wbcErr
1100  **/
1101 wbcErr wbcChangeUserPassword(const char *username,
1102                              const char *old_password,
1103                              const char *new_password);
1104
1105 /**
1106  * @brief Change a password for a user with more detailed information upon
1107  *   failure
1108  *
1109  * @param params                Input parameters
1110  * @param error                 User output details on WBC_ERR_PWD_CHANGE_FAILED
1111  * @param reject_reason         New password reject reason on WBC_ERR_PWD_CHANGE_FAILED
1112  * @param policy                Password policy output details on WBC_ERR_PWD_CHANGE_FAILED
1113  *
1114  * @return #wbcErr
1115  **/
1116 wbcErr wbcChangeUserPasswordEx(const struct wbcChangePasswordParams *params,
1117                                struct wbcAuthErrorInfo **error,
1118                                enum wbcPasswordChangeRejectReason *reject_reason,
1119                                struct wbcUserPasswordPolicyInfo **policy);
1120
1121 /**
1122  * @brief Authenticate a user with cached credentials
1123  *
1124  * @param *params    Pointer to a wbcCredentialCacheParams structure
1125  * @param **info     Pointer to a pointer to a wbcCredentialCacheInfo structure
1126  * @param **error    Pointer to a pointer to a wbcAuthErrorInfo structure
1127  *
1128  * @return #wbcErr
1129  **/
1130 wbcErr wbcCredentialCache(struct wbcCredentialCacheParams *params,
1131                           struct wbcCredentialCacheInfo **info,
1132                           struct wbcAuthErrorInfo **error);
1133
1134 /**********************************************************
1135  * Resolve functions
1136  **********************************************************/
1137
1138 /**
1139  * @brief Resolve a NetbiosName via WINS
1140  *
1141  * @param name         Name to resolve
1142  * @param *ip          Pointer to the ip address string
1143  *
1144  * @return #wbcErr
1145  **/
1146 wbcErr wbcResolveWinsByName(const char *name, char **ip);
1147
1148 /**
1149  * @brief Resolve an IP address via WINS into a NetbiosName
1150  *
1151  * @param ip          The ip address string
1152  * @param *name       Pointer to the name
1153  *
1154  * @return #wbcErr
1155  *
1156  **/
1157 wbcErr wbcResolveWinsByIP(const char *ip, char **name);
1158
1159 /**********************************************************
1160  * Trusted domain functions
1161  **********************************************************/
1162
1163 /**
1164  * @brief Trigger a verification of the trust credentials of a specific domain
1165  *
1166  * @param *domain      The name of the domain, only NULL for the default domain is
1167  *                     supported yet. Other values than NULL will result in
1168  *                     WBC_ERR_NOT_IMPLEMENTED.
1169  * @param error        Output details on WBC_ERR_AUTH_ERROR
1170  *
1171  * @return #wbcErr
1172  **/
1173 wbcErr wbcCheckTrustCredentials(const char *domain,
1174                                 struct wbcAuthErrorInfo **error);
1175
1176 /**********************************************************
1177  * Helper functions
1178  **********************************************************/
1179
1180 /**
1181  * @brief Initialize a named blob and add to list of blobs
1182  *
1183  * @param[in,out] num_blobs     Pointer to the number of blobs
1184  * @param[in,out] blobs         Pointer to an array of blobs
1185  * @param[in]     name          Name of the new named blob
1186  * @param[in]     flags         Flags of the new named blob
1187  * @param[in]     data          Blob data of new blob
1188  * @param[in]     length        Blob data length of new blob
1189  *
1190  * @return #wbcErr
1191  **/
1192 wbcErr wbcAddNamedBlob(size_t *num_blobs,
1193                        struct wbcNamedBlob **blobs,
1194                        const char *name,
1195                        uint32_t flags,
1196                        uint8_t *data,
1197                        size_t length);
1198
1199 #endif      /* _WBCLIENT_H */