JezK
Edit File: Authen::Passphrase::BlowfishCrypt.3pm
.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Authen::Passphrase::BlowfishCrypt 3" .TH Authen::Passphrase::BlowfishCrypt 3 "2020-01-27" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Authen::Passphrase::BlowfishCrypt \- passphrases using the Blowfish\-based Unix crypt() .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Authen::Passphrase::BlowfishCrypt; \& \& $ppr = Authen::Passphrase::BlowfishCrypt\->new( \& cost => 8, \& salt => "sodium_\|_chloride", \& hash_base64 => "BPZijhMHLvPeNMHd6XwZyNamOXVBTPi"); \& \& $ppr = Authen::Passphrase::BlowfishCrypt\->new( \& cost => 8, salt_random => 1, \& passphrase => "passphrase"); \& \& $ppr = Authen::Passphrase::BlowfishCrypt\->from_crypt( \& \*(Aq$2a$08$a07iYVTrVz7hYEvtakjiXOB\*(Aq. \& \*(AqPZijhMHLvPeNMHd6XwZyNamOXVBTPi\*(Aq); \& \& $ppr = Authen::Passphrase::BlowfishCrypt\->from_rfc2307( \& \*(Aq{CRYPT}$2a$08$a07iYVTrVz7hYEvtakjiXOB\*(Aq. \& \*(AqPZijhMHLvPeNMHd6XwZyNamOXVBTPi\*(Aq); \& \& $key_nul = $ppr\->key_nul; \& $cost = $ppr\->cost; \& $cost = $ppr\->keying_nrounds_log2; \& $salt = $ppr\->salt; \& $salt_base64 = $ppr\->salt_base64; \& $hash = $ppr\->hash; \& $hash_base64 = $ppr\->hash_base64; \& \& if($ppr\->match($passphrase)) { ... \& \& $passwd = $ppr\->as_crypt; \& $userPassword = $ppr\->as_rfc2307; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" An object of this class encapsulates a passphrase hashed using the Blowfish-based Unix \fBcrypt()\fR hash function, known as \*(L"bcrypt\*(R". This is a subclass of Authen::Passphrase, and this document assumes that the reader is familiar with the documentation for that class. .PP The \fBcrypt()\fR function in a modern Unix actually supports several different passphrase schemes. This class is concerned only with one particular scheme, a Blowfish-based algorithm designed by Niels Provos and David Mazieres for OpenBSD. To handle the whole range of passphrase schemes supported by the modern \fBcrypt()\fR, see the from_crypt constructor and the as_crypt method in Authen::Passphrase. .PP The Blowfish-based \fBcrypt()\fR scheme uses a variant of Blowfish called \&\*(L"Eksblowfish\*(R", for \*(L"expensive key schedule Blowfish\*(R". It has the cryptographic strength of Blowfish, and a very slow key setup phase to resist brute-force attacks. There is a \*(L"cost\*(R" parameter to the scheme: the length of key setup is proportional to 2^cost. There is a 128\-bit salt. Up to 72 characters of the passphrase will be used; any more will be ignored. .PP The cost, salt, and passphrase are all used to (very slowly) key Eksblowfish. Once key setup is done, the string \&\*(L"OrpheanBeholderScryDoubt\*(R" (three Blowfish blocks long) is encrypted 64 times in \s-1ECB\s0 mode. The final byte of the ciphertext is then dropped, yielding a 23\-byte hash. .PP In the \fBcrypt()\fR function the salt and hash are represented in \s-1ASCII\s0 using a base 64 encoding. The base 64 digits are "\fB.\fR\*(L", \*(R"\fB/\fR\*(L", \&\*(R"\fBA\fR\*(L" to \*(R"\fBZ\fR\*(L", \*(R"\fBa\fR\*(L" to \*(R"\fBz\fR\*(L", \*(R"\fB0\fR\*(L" to \*(R"\fB9\fR" (in that order). The 16\-byte salt is represented as 22 base 64 digits, and the 23\-byte hash as 31 base 64 digits. .PP This algorithm is intended for situations where the efficiency of a brute force attack is a concern. It is suitable for use in new applications where this requirement exists. If that is not a concern, and it suffices to merely make brute force the most efficient attack, see Authen::Passphrase::SaltedDigest for more efficient hash algorithms. .PP Choice of the cost parameter is critical, due to the need to trade off expense of brute-force attack against speed of legitimate passphrase verification. A traditional target is that verification should take about one second on widely-available hardware. (Algorithms that are concerned about brute force speed but lack a cost parameter have often aimed for this, with respect to hardware available at the time of the algorithm's introduction.) As of 2011, this is achieved with a cost parameter around 14. .SH "CONSTRUCTORS" .IX Header "CONSTRUCTORS" .IP "Authen::Passphrase::BlowfishCrypt\->new(\s-1ATTR\s0 => \s-1VALUE, ...\s0)" 4 .IX Item "Authen::Passphrase::BlowfishCrypt->new(ATTR => VALUE, ...)" Generates a new passphrase recogniser object using the Blowfish-based \&\fBcrypt()\fR algorithm. The following attributes may be given: .RS 4 .IP "\fBkey_nul\fR" 4 .IX Item "key_nul" Truth value indicating whether to append a \s-1NUL\s0 to the passphrase before using it as a key. The algorithm as originally devised does not do this, but it was later modified to do it. The version that does append \s-1NUL\s0 is to be preferred. Default true. .IP "\fBcost\fR" 4 .IX Item "cost" Base-two logarithm of the number of keying rounds to perform. .IP "\fBkeying_nrounds_log2\fR" 4 .IX Item "keying_nrounds_log2" Synonym for \fBcost\fR. .IP "\fBsalt\fR" 4 .IX Item "salt" The salt, as a 16\-byte string. .IP "\fBsalt_base64\fR" 4 .IX Item "salt_base64" The salt, as a string of 22 base 64 digits. .IP "\fBsalt_random\fR" 4 .IX Item "salt_random" Causes salt to be generated randomly. The value given for this attribute is ignored. The source of randomness may be controlled by the facility described in Data::Entropy. .IP "\fBhash\fR" 4 .IX Item "hash" The hash, as a 23\-byte string. .IP "\fBhash_base64\fR" 4 .IX Item "hash_base64" The hash, as a string of 31 base 64 digits. .IP "\fBpassphrase\fR" 4 .IX Item "passphrase" A passphrase that will be accepted. .RE .RS 4 .Sp The cost and salt must be given, and either the hash or the passphrase. .RE .IP "Authen::Passphrase::BlowfishCrypt\->from_crypt(\s-1PASSWD\s0)" 4 .IX Item "Authen::Passphrase::BlowfishCrypt->from_crypt(PASSWD)" Generates a new passphrase recogniser object using the Blowfish-based \&\fBcrypt()\fR algorithm, from a crypt string. The crypt string must start with "\fB\f(CB$2\fB$\fR\*(L" for the version that does not append \s-1NUL\s0 to the key, or \*(R"\fB\f(CB$2a\fB$\fR\*(L" for the version that does. The next two characters must be decimal digits giving the cost parameter. This must be followed by \*(R"\fB$\fR", 22 base 64 digits giving the salt, and finally 31 base 64 digits giving the hash. .IP "Authen::Passphrase::BlowfishCrypt\->from_rfc2307(\s-1USERPASSWORD\s0)" 4 .IX Item "Authen::Passphrase::BlowfishCrypt->from_rfc2307(USERPASSWORD)" Generates a new passphrase recogniser object using the Blowfish-based \&\fBcrypt()\fR algorithm, from an \s-1RFC 2307\s0 string. The string must consist of "\fB{\s-1CRYPT\s0}\fR" (case insensitive) followed by an acceptable crypt string. .SH "METHODS" .IX Header "METHODS" .ie n .IP "$ppr\->key_nul" 4 .el .IP "\f(CW$ppr\fR\->key_nul" 4 .IX Item "$ppr->key_nul" Returns a truth value indicating whether a \s-1NUL\s0 will be appended to the passphrase before using it as a key. .ie n .IP "$ppr\->cost" 4 .el .IP "\f(CW$ppr\fR\->cost" 4 .IX Item "$ppr->cost" Returns the base-two logarithm of the number of keying rounds that will be performed. .ie n .IP "$ppr\->keying_nrounds_log2" 4 .el .IP "\f(CW$ppr\fR\->keying_nrounds_log2" 4 .IX Item "$ppr->keying_nrounds_log2" Synonym for \*(L"cost\*(R". .ie n .IP "$ppr\->salt" 4 .el .IP "\f(CW$ppr\fR\->salt" 4 .IX Item "$ppr->salt" Returns the salt, as a string of sixteen bytes. .ie n .IP "$ppr\->salt_base64" 4 .el .IP "\f(CW$ppr\fR\->salt_base64" 4 .IX Item "$ppr->salt_base64" Returns the salt, as a string of 22 base 64 digits. .ie n .IP "$ppr\->hash" 4 .el .IP "\f(CW$ppr\fR\->hash" 4 .IX Item "$ppr->hash" Returns the hash value, as a string of 23 bytes. .ie n .IP "$ppr\->hash_base64" 4 .el .IP "\f(CW$ppr\fR\->hash_base64" 4 .IX Item "$ppr->hash_base64" Returns the hash value, as a string of 31 base 64 digits. .ie n .IP "$ppr\->match(\s-1PASSPHRASE\s0)" 4 .el .IP "\f(CW$ppr\fR\->match(\s-1PASSPHRASE\s0)" 4 .IX Item "$ppr->match(PASSPHRASE)" .PD 0 .ie n .IP "$ppr\->as_crypt" 4 .el .IP "\f(CW$ppr\fR\->as_crypt" 4 .IX Item "$ppr->as_crypt" .ie n .IP "$ppr\->as_rfc2307" 4 .el .IP "\f(CW$ppr\fR\->as_rfc2307" 4 .IX Item "$ppr->as_rfc2307" .PD These methods are part of the standard Authen::Passphrase interface. .SH "SEE ALSO" .IX Header "SEE ALSO" Authen::Passphrase, Crypt::Eksblowfish::Bcrypt .SH "AUTHOR" .IX Header "AUTHOR" Andrew Main (Zefram) <zefram@fysh.org> .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2006, 2007, 2009, 2010, 2012 Andrew Main (Zefram) <zefram@fysh.org> .SH "LICENSE" .IX Header "LICENSE" This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.