.\" Written and revised by Solar Designer <solar at openwall.com> in 2000-2011.

.\" Revised by Zack Weinberg <zackw at panix.com> in 2017.

.\"

.\" No copyright is claimed, and this man page is hereby placed in the public

.\" domain.  In case this attempt to disclaim copyright and place the man page

.\" in the public domain is deemed null and void, then the man page is

.\" Copyright 2000-2011 Solar Designer, 2017 Zack Weinberg, and it is

 \" hereby released to the general public under the following terms:

.\"

.\" Redistribution and use in source and binary forms, with or without

.\" modification, are permitted.

.\"

.\" There's ABSOLUTELY NO WARRANTY, express or implied.

.\"

.\" This manual page in its current form is intended for use on systems

.\" based on the GNU C Library with crypt_blowfish patched into libcrypt.

.\"

.TH CRYPT_RN 3 "October 11, 2017" "Openwall Project" "Library functions"

.ad l

.\" No macros in NAME to keep makewhatis happy.

.SH NAME

\fBcrypt\fR, \fBcrypt_r\fR, \fBcrypt_rn\fR, \fBcrypt_ra\fR

\- passphrase hashing

.SH SYNOPSIS

.B #include <crypt.h>

.sp

.in +8

.ti -8

.BI "char *crypt(const char *" phrase ", const char *" setting );

.ti -8

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

.ti -8

.BI "char *crypt_rn(const char *" phrase ", const char *" setting ", void *" data ", int " size );

.ti -8

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

.in -8

.sp

Link with

.IR -lcrypt .

.ad b

.SH DESCRIPTION

The

.BR crypt ", " crypt_r ", " crypt_rn ", and " crypt_ra

functions irreversibly \(lqhash\(rq

.I phrase

for storage in the system password database

.RB ( shadow (5))

using a cryptographic \(lqhashing method.\(rq

The result of this operation is called a \(lqhashed passphrase\(rq

or just a \(lqhash.\(rq

Hashing methods are described in

.BR crypt (5).

.PP

.I setting

controls which hashing method to use,

and also supplies various parameters to the chosen method,

most importantly a random \(lqsalt\(rq

which ensures that no two stored hashes are the same,

even if the

.I phrase

strings are the same.

The hashing methods are explained below.

.PP

The

.I crypt_data

structure passed to

.B crypt_r

has at least these fields:

.sp

.in +4n

.nf

struct crypt_data {

    char output[CRYPT_OUTPUT_SIZE];

    char setting[CRYPT_OUTPUT_SIZE];

    char phrase[CRYPT_MAX_PASSPHRASE_SIZE];

    char initialized;

};

.fi

.in

.PP

Upon a successful return from

.BR crypt_r ,

the hashed passphrase will be stored in

.IR output .

Applications are encouraged, but not required, to use the

.I setting

and

.I phrase

fields to store the strings that they will pass as

.I phrase

and

.I setting

to

.BR crypt_r .

This will make it easier to erase all sensitive data

after it is no longer needed.

.PP

The

.I initialized

field must be set to zero before the first time a

.I crypt_data

object is first used in a call to

.BR crypt_r .

We recommend zeroing the entire

.I crypt_data

object, not just

.I initialized

and not just the documented fields,

before the first use.

(Of course, do this before storing anything in

.I setting

and

.IR phrase .)

.PP

The

.I data

argument to

.B crypt_rn

should also point to a

.I crypt_data

object, and

.I size

should be the size of that object, cast to

.BR int .

When used with

.BR crypt_rn ,

the entire

.I crypt_data

object must be zeroed before its first use;

this is not just a recommendation, as it is for

.BR crypt_r .

.RI ( setting

and

.I phrase

are still allowed to be used.)

Otherwise, the fields of the object have the same uses that they do for

.BR crypt_r .

.PP

On the first call to

.BR crypt_ra ,

.I data

should be the address of a

.B void *

variable set to NULL, and

.I size

should be the address of an

.B int

variable set to zero.

.B crypt_ra

will allocate and initialize a

.I crypt_data

object, using

.BR malloc (3),

and write its address and size into

.RI * data

and

.RI * size .

These can be reused in subsequent calls.

After the application is done hashing passphrases,

it should deallocate

.RI * data

using

.BR free (3).

.SH RETURN VALUE

Upon successful completion,

.BR crypt ", " crypt_r ", " crypt_rn ", and " crypt_ra

return a pointer to a string which encodes both the hashed passphrase,

and the settings that were used to encode it.

This string is directly usable as

.I setting

with other calls to

.BR crypt ", " crypt_r ", " crypt_rn ", and " crypt_ra ,

and as

.I prefix

with calls to

.BR crypt_gensalt ", " crypt_gensalt_rn ", and " crypt_gensalt_ra .

It will be entirely printable ASCII,

and will not contain whitespace

or the characters \(oq\fB:\fR\(cq,

\(oq\fB;\fR\(cq,

\(oq\fB*\fR\(cq,

\(oq\fB!\fR\(cq, or

\(oq\fB\e\fR\(cq.

See

.BR crypt (5)

for more detail on the format of hashed passphrases.

.PP

.B crypt

places its result in a static storage area,

which will be overwritten by subsequent calls to

.BR crypt .

It is not safe to call

.B crypt

from multiple threads simultaneously.

.PP

.BR crypt_r ", " crypt_rn ", and " crypt_ra

place their result in the

.I output

field of the

.I crypt_data

object that they are supplied with; it is safe to call them from

multiple threads simultaneously, as long as a separate

.I crypt_data

object is used for each thread.

.PP

Upon error,

.BR crypt_r ", " crypt_rn ", and " crypt_ra

write an

.I invalid

hashed passphrase to the

.I output

field of their

.I crypt_data

object, and

.B crypt

writes an invalid hash to its static storage area.

This string will be shorter than 13 characters,

will begin with a \(oq\fB*\fR\(cq,

and will not compare equal to

.IR setting .

.PP

Upon error,

.BR crypt_rn " and " crypt_ra

return a null pointer.

.BR crypt_r " and " crypt

may also return a null pointer,

or they may return a pointer to the invalid hash,

depending on how

.I libcrypt

was configured.

(The option to return the invalid hash is for compatibility

with old applications that assume that

.B crypt

cannot return a null pointer.

See

.B "PORTABILITY NOTES"

below.)

.PP

All four functions set

.I errno

when they fail.

.SH ERRORS

.TP

.B EINVAL

.I setting

is invalid, or requests a hashing method that is not supported.

.TP

.B ERANGE

.B crypt_rn

only:

.I size

is too small for the hashing method requested by

.IR setting .

.TP

.B ENOMEM

Failed to allocate internal scratch memory.

.br

.BR crypt_ra

only: failed to allocate memory for

.RI * data .

.TP

.BR ENOSYS " or " EOPNOTSUPP

Hashing passphrases is not supported at all on this installation,

or the hashing method requested by

.I setting

is not supported.

These error codes are not used by this version of

.IR libcrypt ,

but may be encountered on other systems.

.SH PORTABILITY NOTES

.PP

.B crypt

is included in POSIX, but

.BR crypt_r ", " crypt_rn ", and " crypt_ra

are not part of any standard.

.PP

POSIX does not specify any hashing methods,

and does not 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 considerably from system to system.

.PP

The behavior of

.B crypt

on errors isn't well standardized.

Some implementations simply can't fail

(except by crashing the program),

others return a null pointer or a fixed string.

Most implementations don't set

.IR errno ,

but some do.

POSIX specifies returning a null pointer and setting

.IR errno ,

but it defines only one possible error,

.BR ENOSYS ,

in the case where

.B crypt

is not supported at all.

Many existing applications are not prepared to handle null pointers

returned by

.BR crypt .

The behavior described above for this implementation,

setting

.I errno

and returning an invalid hashed passphrase different from

.IR setting ,

is chosen to make these applications fail closed when an error occurs.

.PP

Due to historical restrictions

on the export of cryptographic software from the USA,

.B crypt

is an optional POSIX component.

Applications should therefore be prepared for

.B crypt

not to be available,

or to always fail (setting

.I errno

to

.BR ENOSYS )

at runtime.

.PP

POSIX specifies that

.B crypt

is declared in

.BR unistd.h ,

but only if the macro

.B _XOPEN_CRYPT

is defined and has a value greater than or equal to zero.  Since

.I libcrypt

does not provide

.BR unistd.h ,

it declares

.BR crypt ", " crypt_r ", " crypt_rn ", and " crypt_ra

in

.B crypt.h

instead.

.PP

On a minority of systems (notably recent versions of Solaris),

.B crypt

uses a thread-specific static storage buffer,

which makes it safe to call from multiple threads simultaneously,

but does not prevent each call within a thread

from overwriting the results of the previous one.

.SH BUGS

.PP

Some implementations of

.BR crypt ,

upon error,

return an invalid hash that is stored in a read-only location

or only initialized once,

which means that it is only safe to erase the buffer pointed to by the

.B crypt

return value if an error did not occur.

.PP

.I struct crypt_data

may be quite large (32kB in this implementation of

.IR libcrypt ;

over 128kB in some other implementations).

This is large enough that it may be unwise to allocate it on the stack.

.PP

Some recently designed hashing methods need even more scratch memory,

but the

.B crypt_r

interface makes it impossible to change the size of

.I crypt_data

without breaking binary compatibility.

The

.B crypt_rn

interface could accommodate larger allocations for specific hashing methods,

but the caller of

.B crypt_rn

has no way of knowing how much memory to allocate.

.B crypt_ra

does the allocation itself,

but can only make a single call to

.BR malloc (3).

.SH ATTRIBUTES

For an explanation of the terms used in this section, see

.BR attributes (7).

.ad l

.TS

allbox;

lb lb lb

l l l.

Interface	Attribute	Value

T{

.B crypt

T}	Thread safety	MT-Unsafe race:crypt

T{

.BR crypt_r ", " crypt_rn ", " crypt_ra

T}	Thread safety	MT-Safe

.TE

.ad b

.sp

.SH HISTORY

A rotor-based

.B crypt

function appeared in Version 6 AT&T UNIX.

The "traditional" DES-based

.B crypt

first appeared in Version 7 AT&T UNIX.

.PP

.B crypt_r

originates with the GNU C Library.

There's also a

.B crypt_r

function on HP-UX and MKS Toolkit, but the prototypes and semantics

differ.

.PP

.BR crypt_rn

and

.BR crypt_ra

originate with the Openwall project.

.SH SEE ALSO

.ad l

.BR crypt_gensalt (3),

.BR getpass (3),

.BR getpwent (3),

.BR shadow (3),

.BR login (1),

.BR passwd (1),

.BR crypt (5),

.BR passwd (5),

.BR shadow (5),

.BR pam (8)