remctl_set_ccache(3)

1REMCTL_SET_CCACHE(3)       remctl Library Reference       REMCTL_SET_CCACHE(3)
2
3
4

NAME

6       remctl_set_ccache - Set credential cache for remctl client connections
7

SYNOPSIS

9       #include <remctl.h>
10
11       int remctl_set_ccache(struct remctl *r, const char *ccache);
12

DESCRIPTION

14       remctl_set_ccache() tells the the remctl client library to use ccache
15       as the credential cache for authentication to a remctl server.  It will
16       affect any subsequent remctl_open() calls on the same struct remctl
17       object (and may have broader effects; see WARNINGS below).  ccache is
18       normally a path to a file in the file system that holds Kerberos
19       credentials, but may take other values depending on the underlying
20       Kerberos implementation used by GSS-API.
21
22       Calling this function will normally override any KRB5CCNAME environment
23       setting.  If the caller wishes to honor that setting, it should either
24       not call this function or check whether that environment variable is
25       set first.
26

RETURN VALUE

28       remctl_set_ccache() returns true on success and false on failure.  On
29       failure, the caller should call remctl_error() to retrieve the error
30       message.
31
32       This function will always return failure if the underlying GSS-API
33       implementation against which the remctl client library was compiled
34       does not support setting the Kerberos credential cache.  The caller
35       should be prepared for that.  Falling back on setting the KRB5CCNAME
36       environment variable is often a reasonable choice.
37

EXAMPLES

39       Here's an example of attempting to use this function to set a ticket
40       cache location and falling back on setting KRB5CCNAME in the
41       environment if this function is not supported.
42
43           struct remctl r;
44
45           r = remctl_new();
46           if (r != NULL)
47               if (!remctl_set_ccache(r, "/tmp/krb5cc_example"))
48                   putenv("KRB5CCNAME=/tmp/krb5cc_example");
49
50       This assumes that any failure is due to lack of support from the
51       underlying library rather than some other cause.
52

COMPATIBILITY

54       This interface was added in version 3.0, but that version would always
55       change the ticket cache used by all GSS-API calls in the same process.
56       Support for the gss_krb5_import_cred() method of isolating the changed
57       ticket cache to only this remctl client object was added in version
58       3.5.
59

WARNINGS

61       The effect of this function is only localized to this specific remctl
62       client context if the remctl client library was built against a
63       Kerberos as well as GSS-API library and the GSS-API library supported
64       gss_krb5_import_cred().  Otherwise, it falls back to calling
65       gss_krb5_ccache_name(), which sets the credential cache used by the
66       underlying GSS-API library for every GSS-API operation in the current
67       execution context (process or thread), not just for this remctl object
68       or even just for remctl operations.  This function may therefore change
69       global execution state and may affect other GSS-API operations done
70       elsewhere in the same process.
71

AUTHOR

73       Russ Allbery <eagle@eyrie.org>
74

COPYRIGHT AND LICENSE

76       Copyright 2011, 2013-2014 The Board of Trustees of the Leland Stanford
77       Junior University
78
79       Copying and distribution of this file, with or without modification,
80       are permitted in any medium without royalty provided the copyright
81       notice and this notice are preserved.  This file is offered as-is,
82       without any warranty.
83
84       SPDX-License-Identifier: FSFAP
85