REMCTL_SET_CCACHE(3)

💖 REMCTL_SET_CCACHE — bestie edition 💖

okay so this is a page from the remctl Library Reference (it's REMCTL_SET_CCACHE, third section, library calls, iykyk) and it's literally about telling remctl which credential cache to use. let's get into it 🫶

---

✨ NAME ✨

remctl_set_ccache — set the credential cache for remctl client connections

---

✨ SYNOPSIS ✨

#include <remctl.h>

int remctl_set_ccache(struct remctl *r, const char *ccache);

---

✨ DESCRIPTION ✨

so remctl_set_ccache() is the girl that tells the remctl client library "hey, use ccache as the credential cache for authenticating to a remctl server, mmkay?" 💅

it will affect any subsequent remctl_open() calls on that same struct remctl object. and lowkey it may have broader effects too — like, go read the WARNINGS section below, don't skip it bestie, it's important. 😭

ccache is normally a path to a file in the file system that holds Kerberos credentials. but ngl it might take other values depending on the underlying Kerberos implementation that GSS-API is using. so like, don't assume it's always a path.

calling this function will normally override any KRB5CCNAME environment setting. so if the caller wants to honor that setting instead, they should either just... not call this function, or check whether that environment variable is set first. that's the vibe check right there. 🎀

---

✨ RETURN VALUE ✨

remctl_set_ccache() returns true on success and false on failure. and on failure? the caller should call remctl_error() to grab the error message. go get your girl, she'll tell you what went wrong. 🫶

and this is the part that's giving 🚨: this function will always return failure if the underlying GSS-API implementation that the remctl client library was compiled against does not support setting the Kerberos credential cache. so the caller should be prepared for that. fr fr. falling back on setting the KRB5CCNAME environment variable is often a reasonable choice — very demure, very mindful. ✨

---

✨ EXAMPLES ✨

here's an example of attempting to use this function to set a ticket cache location, and falling back on setting KRB5CCNAME in the environment if this function isn't supported. iconique behavior honestly. 👑

struct remctl r;

r = remctl_new();
if (r != NULL)
    if (!remctl_set_ccache(r, "/tmp/krb5cc_example"))
        putenv("KRB5CCNAME=/tmp/krb5cc_example");

⚠️ this assumes that any failure is due to lack of support from the underlying library rather than some other cause. so like, just keep that in mind, bestie. 🙈

---

✨ COMPATIBILITY ✨

this interface was added in version 3.0, but that version would always change the ticket cache used by all GSS-API calls in the same process. like, the whole group chat. 😭

support for the gss_krb5_import_cred() method of isolating the changed ticket cache to only this remctl client object was added in version 3.5. so if you're on the old one... thoughts and prayers. 💀

---

✨ WARNINGS ✨

okay this is the serious part, no cap. 🚨

the effect of this function is only localized to this specific remctl client context if both:

• the remctl client library was built against a Kerberos as well as GSS-API library, and
• the GSS-API library supported gss_krb5_import_cred().

otherwise? it falls back to calling gss_krb5_ccache_name(), which sets the credential cache used by the underlying GSS-API library for every GSS-API operation in the current execution context (process or thread) — not just for this remctl object, and not even just for remctl operations. 😳

💀 so this function may change global execution state and may affect other GSS-API operations done elsewhere in the same process. it's giving main character energy in the worst possible way. be careful out there.

---

✨ AUTHOR ✨

Russ Allbery <eagle@eyrie.org> 🦋

---

✨ COPYRIGHT AND LICENSE ✨

Copyright 2011, 2013-2014 The Board of Trustees of the Leland Stanford Junior University

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.

SPDX-License-Identifier: FSFAP ⭐

---

✨ SEE ALSO ✨

• remctl_new(3)
• remctl_open(3)
• remctl_error(3)

The current version of the remctl library and complete details of the remctl protocol are available from its web page at <https://www.eyrie.org/~eagle/software/remctl/>. 🌈

---

okay that's the whole page bestie, you ate that. 💅 and for the record, this was version 3.18, dated 2022-05-09, page REMCTL_SET_CCACHE(3) — mwah, slay, periodt. 💖✨🎀