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