CRYPT(3)

💖 CRYPT(3) 💖 — Library Functions Manual

okay bestie, sit down, hydrate, because we're talking about crypt, crypt_r, crypt_rn, and crypt_ra — the passphrase hashing girlies from the Crypt Library (libcrypt, -lcrypt). this is the manual page, part one, and it's lowkey a lot but we're gonna get through it together. 🫶

---

✨ NAME ✨

crypt, crypt_r, crypt_rn, crypt_ra — passphrase hashing 💅

---

🌸 LIBRARY 🌸

Crypt Library — that's libcrypt, and you link it with -lcrypt. periodt.

---

🎀 SYNOPSIS 🎀

#include <crypt.h>

char *
crypt(const char *phrase, const char *setting);

char *
crypt_r(const char *phrase, const char *setting,
    struct crypt_data *data);

char *
crypt_rn(const char *phrase, const char *setting,
    struct crypt_data *data, int size);

char *
crypt_ra(const char *phrase, const char *setting, void **data,
    int *size);

---

🦋 DESCRIPTION 🦋

so. the way that crypt, crypt_r, crypt_rn, and crypt_ra work is: they irreversibly "hash" a phrase so you can store it in the system password database — that's shadow(5), iykyk — using a cryptographic "hashing method." the thing you get out of that is called a "hashed passphrase" or just a "hash" for short. all the hashing methods themselves live in crypt(5). go look, they're cute.

setting is the main character here — it picks which hashing method gets used, and it also hands over a bunch of parameters to whichever method you chose. most importantly it carries a random "salt", which is the whole reason no two stored hashes come out identical even when the phrase strings are literally the same. no cap. ✨

the data argument to crypt_r is a structure of type struct crypt_data. at minimum it has these fields:

struct crypt_data {
    char output[CRYPT_OUTPUT_SIZE];
    char setting[CRYPT_OUTPUT_SIZE];
    char input[CRYPT_MAX_PASSPHRASE_SIZE];
    char initialized;
};

once crypt_r returns successfully, the hashed passphrase is sitting pretty in output. apps are encouraged (but like, not required, it's not that deep) to use the input and setting fields to stash the strings they're gonna pass as phrase and setting to crypt_r. why? because then it's way easier to wipe all the sensitive data once you don't need it anymore. slay. 🔥

⚠️ the initialized field must be set to zero before the very first time a struct crypt_data object is used in a call to crypt_r(). we recommend zeroing the entire object — not just initialized, and not just the documented fields — before first use. (obviously do this before you store anything in setting and input, bestie.)

the data argument to crypt_rn should also point at a struct crypt_data object, and size should be the size of that object, cast to int. here's the thing though — when you're using crypt_rn, the entire data object (except for the input and setting fields) must be zeroed before its first use. that is not a recommendation like it is for crypt_r. it's the rules. otherwise, the fields do exactly the same jobs they do for crypt_r. 💀

on the first call to crypt_ra, data should be the address of a void * variable that's set to NULL, and size should be the address of an int variable set to zero. crypt_ra will then allocate and initialize a struct crypt_data object for you using malloc(3), and write its address and size into the variables that data and size point at. you can reuse those in later calls, iconic. once the app is done hashing passphrases, it should deallocate that struct crypt_data object with free(3). 🧚

---

⭐ RETURN VALUES ⭐

when everything goes right, crypt, crypt_r, crypt_rn, and crypt_ra return a pointer to a string that encodes both the hashed passphrase and the settings used to encode it. that string is directly usable as setting in other calls to crypt, crypt_r, crypt_rn, and crypt_ra, and as prefix in calls to crypt_gensalt, crypt_gensalt_rn, and crypt_gensalt_ra. it will be entirely printable ASCII, and it will not contain whitespace or the characters ':', ';', '*', '!', or '\'. head to crypt(5) for more detail on the format of hashed passphrases. 💜

crypt puts its result in a static storage area, which gets overwritten by subsequent calls to crypt. so it is not safe to call crypt from multiple threads at the same time. also, don't use the pointer it returned as an argument for another call to crypt — some implementations, including earlier releases of libxcrypt, may overwrite the underlying static output buffer before computing the hash. rude, honestly. 😭

crypt_r, crypt_rn, and crypt_ra put their result in the output field of their data argument. it is safe to call them from multiple threads simultaneously, as long as you use a separate data object for each thread. and same energy as before: don't use the returned pointer as an argument for another call to crypt_r, crypt_rn, and crypt_ra that reuses the same data object for subsequent calls, because some implementations, including earlier releases of libxcrypt, may overwrite the output field of the passed data argument before computing the hash. also, calling crypt_ra with the phrase and/or setting parameters located inside a passed data object that's smaller than the size of struct crypt_data? not recommended. some implementations, including earlier releases of libxcrypt, may not preserve the passed literals if the data object needs to be altered. 💅

when there's an error, crypt_r, crypt_rn, and crypt_ra write an invalid hash to the output field of their data argument, and crypt writes an invalid hash to its static storage area. that string will be shorter than 13 characters, will begin with a '*', and will not compare equal to setting.

on error, crypt_rn and crypt_ra return a null pointer. crypt_r and crypt may also return a null pointer, or they may return a pointer to that invalid hash — it depends on how libcrypt was configured. (the option to return the invalid hash exists for compatibility with old applications that assume crypt can't return a null pointer. see "PORTABILITY NOTES" below. 👀)

all four functions set errno when they fail. when they succeed, the value of errno is unspecified and you must not rely on it. periodt.

---

🌈 ERRORS 🌈

• EINVAL — setting is invalid, or it's requesting a hashing method that isn't supported. 🙈
• ERANGE — phrase is too long (more than CRYPT_MAX_PASSPHRASE_SIZE characters; some hashing methods may have lower limits).
  • crypt_rn only: size is too small for the hashing method requested by setting.
• ENOMEM — failed to allocate internal scratch memory.
  • crypt_ra only: failed to allocate memory for data.
• ENOSYS or EOPNOTSUPP — hashing passphrases is not supported at all on this installation, or the hashing method requested by setting is not supported. these error codes are not used by this version of libcrypt, but you may run into them on other systems. ⭐

---

💜 PORTABILITY NOTES 💜

crypt is included in POSIX, but crypt_r, crypt_rn, and crypt_ra are not part of any standard. sorry bestie, that's just how it is.

POSIX permits crypt to use a single storage area for all callers, even when threads are in the picture. this library uses per-thread storage areas, but portable code should still avoid calling crypt from multiple threads simultaneously. lowkey just be careful. 🌸

POSIX doesn't specify any hashing methods, and it doesn't require hashed passphrases to be portable between systems. in practice, hashed passphrases are portable as long as both systems support the hashing method that was used. however, the set of supported hashing methods varies a lot from system to system. 😭

the behavior of crypt on errors isn't well standardized. some implementations literally can't fail (except by crashing the program 💀), others return a null pointer or a fixed string. most implementations don't set errno, but some do. POSIX specifies returning a null pointer and setting errno, but it only defines one possible error — ENOSYS — for the case where crypt isn't supported at all. some older applications are not prepared to handle null pointers coming back from crypt. the behavior described above for this implementation — setting errno and returning an invalid hash that's different from setting — was chosen to make those applications fail closed when an error occurs. it's giving safety. 🔥

because of historical restrictions on exporting cryptographic software from the USA, crypt is an optional POSIX component. so applications should be prepared for crypt to not be available, or to always fail at runtime (with errno set to ENOSYS). 🙈

POSIX specifies that crypt is declared in <unistd.h>, but only if the macro _XOPEN_CRYPT is defined and has a value greater than or equal to zero. since libcrypt does not provide <unistd.h>, it declares crypt, crypt_r, crypt_rn, and crypt_ra in <crypt.h> instead. 💅

on a minority of systems (notably recent versions of Solaris), crypt uses a thread-specific static storage buffer, which makes it safe to call from multiple threads simultaneously — but it does not stop each call within a thread from overwriting the results of the previous one. if an application needs to call crypt from parallel threads independently, it is strongly advised to allocate thread-specific struct crypt_data objects from within that program itself, and to use those objects with one of the re-entrant interfaces provided through crypt_r, crypt_rn, or crypt_ra. do it, it's the move. 🧚

---

🍓 BUGS 🍓

some implementations of crypt, when they hit an error, return an invalid hash that's stored in a read-only location or only initialized once — which means it is only safe to erase the buffer pointed to by the crypt return value if an error did not occur. 💀

struct crypt_data can be quite large (32kB in this implementation of libcrypt; over 128kB in some other implementations). that is large enough that it may be unwise to allocate it on the stack. 😭

some recently designed hashing methods need even more scratch memory, but the crypt_r interface makes it impossible to change the size of struct crypt_data without breaking binary compatibility. the crypt_rn interface could accommodate larger allocations for specific hashing methods, but the caller of crypt_rn has no way of knowing how much memory to allocate. crypt_ra does the allocation itself, but it can only make a single call to malloc(3). 🙈

---

okay that's part one bestie, don't go anywhere — there's more coming 💖

✨ ATTRIBUTES ✨

ok so if you're wondering what all those words even mean, bestie, go peek at attributes(7) 💖

Here's the tea on thread safety, laid out flat since we're not doing tables in here:

• crypt — Thread safety: MT-Safe* 🫶
• crypt_r, crypt_rn, crypt_ra — Thread safety: MT-Safe 👑

* In this implementation. Do NOT rely on this to be portable behavior. Go read the “PORTABILITY NOTES” section, fr fr. 💀

---

🌸 HISTORY 🌸

storytime, gather round 🎀

A rotor-based crypt function showed up way back in Version 6 AT&T UNIX. iconic behavior, honestly.

Then the “traditional” DES-based crypt made its debut in Version 7 AT&T UNIX. a glow-up era ✨

crypt_r? That one originates with the GNU C Library. There's also a crypt_r function hanging around on HP-UX and MKS Toolkit, but heads up — the prototypes and semantics differ. so like, same name, different vibe, do not get it twisted 🙈

crypt_rn and crypt_ra originate with the Openwall project. slay 💅

---

👑 SEE ALSO 👑

go read these next, no cap:

• crypt_gensalt(3)
• getpass(3)
• getpwent(3)
• shadow(3)
• login(1)
• passwd(1)
• crypt(5)
• passwd(5)
• shadow(5)
• pam(8)

---

and that's the whole page, bestie!! 🦋 you made it to the end, which is honestly main character energy 🌈

this one comes to you from the Openwall Project, dated October 11, 2017, and yeah it's the CRYPT(3) page 💜 go forth and hash responsibly, mwah 💋