crypt2(3C)

NAME

crypt2(), crypt2_passwd_match(), crypt2_passwd_hash(), crypt2_passwd_salt() — enhanced password hash functions

SYNOPSIS

#include <prot.h> 

int crypt2_passwd_match(const char *key, const char *oldhash, const char *username);

char *crypt2_passwd_hash(const char *key, const char *oldhash, const char *username);

char *crypt2_passwd_salt(const char *oldhash, const char *username);

char *crypt2(const char *key, const char *salt);

DESCRIPTION

The four crypt2 functions are enhancements to the legacy crypt() (see crypt(3C)) function. They are backward compatible with crypt() and provide the option to use an alternative password hash algorithm, as configured by the attributes CRYPT_DEFAULT and CRYPT_ALGORITHMS_DEPRECATE described in security(4).

crypt2_passwd_match(key, oldhash, username):

The crypt2_passwd_match() function derives both the password hash algorithm and salt from oldhash. It then applies the algorithm to the salt and to the string key. If the resulting hash string matches oldhash, then the function returns 1, otherwise it returns 0.

crypt2_passwd_hash(key, oldhash, username):

The crypt2_passwd_hash() function computes a random salt suitable for username and compatible with the hash algorithm encoded in oldhash. The function then applies the algorithm to the newly constructed salt and to the string key. Upon success, the resulting hash string is returned. Upon failure, a pointer to "*" is returned.

crypt_2passwd_salt(oldhash, username):

The crypt2_passwd_salt() function computes a random salt suitable for username and compatible with the hash algorithm encoded in oldhash. If oldhash corresponds to a hash algorithm that is compliant with the current password hash policies, the function returns a new salt suitable for that algorithm. Otherwise, if the original algorithm is not acceptable, the function returns a salt that corresponds to the default hash algorithm. Setting oldhash to aa requests a DES-compatible salt. Setting oldhash to $6$ requests a SHA-512-compatible salt. If the name of the user is not available when an application calls crypt2_passwd_salt(), the username should be set to "". This prompts the function to bypass any checks for per-user policies and to apply only the system-wide security policies.

crypt2(key, saltstring):

The crypt2() function derives both the password algorithm and salt from saltstring. It then applies the algorithm to the salt and to the string key, and returns the resulting hash string. Unlike crypt2_passwd_hash(), the crypt2() function makes no checks to the appropriateness of the hash algorithm or salt. It is recommended that saltstring be the result of a prior call to crypt2_passwd_salt().

WARNINGS

The crypt2(), crypt2_passwd_salt(), and crypt2_passwd_hash() functions return a pointer allocated by the functions themselves. The caller is responsible for calling free() to deallocate this space.

Currently, all the password hash policies are only enforced at the system-wide level using CRYPT_DEFAULT and CRYPT_ALGORITHMS_DEPRECATE. Enforcement of user-specific policies is not implemented yet. Even though the username argument is ignored, it still must be provided in calls to crypt2_passwd_match(), crypt2_passwd_hash(), and crypt2_passwd_salt).

crypt2(3C)

Technical documentation

» Table of Contents

» Index