'\" te
.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved.
.TH crypt_gensalt 3C "10 Jun 2002" "SunOS 5.11" "Standard C Library Functions"
.SH NAME
crypt_gensalt \- generate salt string for string encoding
.SH SYNOPSIS
.LP
.nf
#include <crypt.h>

\fBchar *\fR\fBcrypt_gensalt\fR(\fBconst char *\fR\fIoldsalt\fR, \fBconst struct passwd *\fR\fIuserinfo\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBcrypt_gensalt()\fR function generates the salt string required by \fBcrypt\fR(3C).
.sp
.LP
If \fIoldsalt\fR is \fINULL\fR, \fBcrypt_gensalt()\fR uses the algorithm defined by \fBCRYPT_DEFAULT\fR in \fB/etc/security/policy.conf\fR. See \fBpolicy.conf\fR(4).
.sp
.LP
If \fIoldsalt\fR is non-null, \fBcrypt_gensalt()\fR determines if the algorithm specified by \fIoldsalt\fR is allowable by checking the \fBCRYPT_ALGORITHMS_ALLOW\fR and \fBCRYPT_ALGORITHMS_DEPRECATE\fR variables in \fB/etc/security/policy.conf\fR. If the algorithm is allowed, \fBcrypt_gensalt()\fR loads the appropriate shared library and calls \fBcrypt_gensalt_impl\fR(3C). If the algorithm is not allowed or there is no entry for it in \fBcrypt.conf\fR, \fBcrypt_gensalt()\fR uses the default algorithm.
.sp
.LP
The mechanism just described provides a means to migrate users to new password hashing algorithms when the password is changed.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBcrypt_gensalt()\fR returns a pointer to the new salt. Otherwise a null pointer is returned and \fBerrno\fR is set to indicate the error.
.SH ERRORS
.sp
.LP
The \fBcrypt_gensalt()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 11n
.rt  
The configuration file \fBcrypt.conf\fR contains an invalid entry.
.RE

.sp
.ne 2
.mk
.na
\fB\fBELIBACC\fR\fR
.ad
.RS 11n
.rt  
The required shared library was not found.
.RE

.sp
.ne 2
.mk
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 11n
.rt  
There is insufficient memory to perform hashing.
.RE

.SH USAGE
.sp
.LP
The value returned by \fBcrypt_gensalt()\fR points to a null-terminated string. The caller of \fBcrypt_gensalt()\fR is responsible for calling \fBfree\fR(3C).
.sp
.LP
Applications dealing with user authentication and password changing should not call \fBcrypt_gensalt()\fR directly but should instead call the appropriate \fBpam\fR(3PAM) functions.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBpasswd\fR(1), \fBcrypt\fR(3C), \fBcrypt_genhash_impl\fR(3C), \fBcrypt_gensalt_impl\fR(3C), \fBgetpassphrase\fR(3C), \fBmalloc\fR(3C), \fBpam\fR(3PAM), \fBcrypt.conf\fR(4), \fBpasswd\fR(4), \fBpolicy.conf\fR(4), \fBattributes\fR(5)