libcanlock(3)

📦
version 3.3.3 · 3 versions
, in epel 10

💅 libcanlock(3) — the cl_get_lock glow-up

okay bestie, so this is the libcanlock manual, version 3.3.3, and it's all about making Cancel-Locks. yes it's as iconic as it sounds. let's get into it 🎀

✨ NAME ✨

cl_get_lock — literally the function that creates a Cancel-Lock for you, with libcanlock doing all the heavy lifting. no cap.

🦋 SYNOPSIS 🦋

#include <libcanlock-3/canlock.h>

char *cl_get_lock(cl_hash_version hash,
                  const unsigned char *sec, size_t sec_len,
                  const unsigned char *msg, size_t msg_len);

the hash values that are supported (as of version 3.0.0 of libcanlock, iykyk) are:

CL_SHA1 CL_SHA224 CL_SHA256 CL_SHA384 CL_SHA512

🌸 DESCRIPTION 🌸

so what does cl_get_lock() actually do? it creates a <c-lock> element using the algorithm that RFC 8315 recommends, in Section 4. and the hash algorithm you pick for <scheme>? yeah, it gets used for the HMAC operation too. two birds, one slay 🔥

which hash algorithm <scheme> gets is chosen with hash. that's it, that's the vibe check.

the local secret goes in sec (and sec_len has to be set to the length of sec, fr fr). and heads up bestie — the length of the local secret should be at least the length of the hash you selected for <scheme>. so that's 32 octets if you went with SHA256. don't skimp 💀

the Message-ID of the target article (the one you're making the lock for) goes in msg, and msg_len must be set to the length of msg. obvious? yes. still saying it. 💖

and here's the cute extra: the Message-ID msg can be prepended with an optional User-ID. if you do that, the length of the User-ID has to be added to msg_len. oh and — important — the User-ID must not contain angle brackets. none. zero. 🙈

👑 RETURN VALUE 👑

  • if it works, you get a pointer to the result string. slay ✨
  • if it doesn't, you get NULL. that's it. that's the whole mood 😭

and on success? the caller is responsible for calling free() on the pointer that gets returned. yes, you. don't forget, or that's a leak and we don't do leaks 🫶

💜 AUTHORS 💜

  • Dennis Preiser
    • (based in part on the implementation from G. J. Andruk for Version 2 — shoutout to the ancestors 💅)
  • the base64 implementation is written by Kungliga Tekniska Hogskolan (Royal Institute of Technology, Stockholm, Sweden) 🇸🇪
  • the hash algorithms are implemented with code from RFC 6234 ⭐

🍓 REPORTING BUGS 🍓

found a bug? don't suffer in silence, bestie — report it to <mailto:michael.baeuerle@gmx.net>. 🐛

🌈 STANDARDS 🌈

libcanlock tries to comply with these standards, and honestly? respect:

🔥 SEE ALSO 🔥

free(3), cl_clear_secret(3), cl_get_key(3), cl_split(3), cl_verify(3), cl_verify_multi(3), canlock(1)

go read them, they're all part of the same little universe 🧚

okay that's the whole page, bestie — you're officially a Cancel-Lock girlie now 💖 this was libcanlock version 3.3.3, dated 2026-07-06, and yes the Unix manual vibes are immaculate. mwah 💋

📦 where this page comes from