<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<manualpage metafile="password_encryptions.xml.meta">
  <parentdocument href="./">Miscellaneous Documentation</parentdocument>

  <title>Password Formats</title>

  <summary>
    <p>Notes about the password encryption formats generated and understood by
    Apache.</p>
  </summary>

  <section id="basic"><title>Basic Authentication</title>

    <p>There are five formats that Apache recognizes for basic-authentication
    passwords. Note that not all formats work on every platform:</p>

    <dl>
       <dt>bcrypt</dt>
       <dd>"$2y$" + the result of the crypt_blowfish algorithm.
       See the APR source file
       <a href="http://svn.apache.org/viewvc/apr/apr/trunk/crypto/crypt_blowfish.c?view=markup">crypt_blowfish.c</a>
       for the details of the algorithm.</dd>

       <dt>MD5</dt>
       <dd>"$apr1$" + the result of an Apache-specific algorithm using an
       iterated (1,000 times) MD5 digest of various combinations of a
       random 32-bit salt and the password. See the APR source file
       <a href="http://svn.apache.org/viewvc/apr/apr/trunk/crypto/apr_md5.c?view=markup">apr_md5.c</a>
       for the details of the algorithm.</dd>

       <dt>SHA1</dt>
       <dd>"{SHA}" + Base64-encoded SHA-1 digest of the password. Insecure.</dd>

       <dt>CRYPT</dt>
       <dd>Unix only. Uses the traditional Unix <code>crypt(3)</code> function
       with a randomly-generated 32-bit salt (only 12 bits used) and the first 8
       characters of the password. Insecure.</dd>

       <dt>PLAIN TEXT (i.e. <em>unencrypted</em>)</dt>
       <dd>Windows &amp; Netware only. Insecure.</dd>
    </dl>

    <section><title>Generating values with htpasswd</title>

      <example><title>bcrypt</title>
      $ htpasswd -nbB myName myPassword<br />
      myName:$2y$05$c4WoMPo3SXsafkva.HHa6uXQZWr7oboPiC2bT/r7q1BB8I2s0BRqC
      </example>

      <example><title>MD5</title>
      $ htpasswd -nbm myName myPassword<br />
      myName:$apr1$r31.....$HqJZimcKQFAMYayBlzkrA/
      </example>

      <example><title>SHA1</title>
      $ htpasswd -nbs myName myPassword<br />
      myName:{SHA}VBPuJHI7uixaa6LQGWx4s+5GKNE=
      </example>

      <example><title>CRYPT</title>
      $ htpasswd -nbd myName myPassword<br />
      myName:rqXexS6ZhobKA
      </example>

    </section>

    <section>
      <title>Generating CRYPT and MD5 values with the OpenSSL
             command-line program</title>

      <p>OpenSSL knows the Apache-specific MD5 algorithm.</p>

      <example><title>MD5</title>
      $ openssl passwd -apr1 myPassword<br />
      $apr1$qHDFfhPC$nITSVHgYbDAK1Y0acGRnY0
      </example>

      <example><title>CRYPT</title>
      openssl passwd -crypt myPassword<br />
      qQ5vTYO3c8dsU
      </example>
    </section>

    <section>
      <title>Validating CRYPT or MD5 passwords with the OpenSSL command
             line program</title>
      <p>The salt for a CRYPT password is the first two characters (converted to
      a binary value). To validate <code>myPassword</code> against
      <code>rqXexS6ZhobKA</code></p>

      <example><title>CRYPT</title>
      $ openssl passwd -crypt -salt rq myPassword<br />
      Warning: truncating password to 8 characters<br />
      rqXexS6ZhobKA
      </example>

      <p>Note that using <code>myPasswo</code> instead of
      <code>myPassword</code> will produce the same result because only the
      first 8 characters of CRYPT passwords are considered.</p>

      <p>The salt for an MD5 password is between <code>$apr1$</code> and the
      following <code>$</code> (as a Base64-encoded binary value - max 8 chars).
      To validate <code>myPassword</code> against
      <code>$apr1$r31.....$HqJZimcKQFAMYayBlzkrA/</code></p>

      <example><title>MD5</title>
      $ openssl passwd -apr1 -salt r31..... myPassword<br />
      $apr1$r31.....$HqJZimcKQFAMYayBlzkrA/
      </example>
    </section>

    <section><title>Database password fields for mod_dbd</title>
      <p>The SHA1 variant is probably the most useful format for DBD
      authentication. Since the SHA1 and Base64 functions are commonly
      available, other software can populate a database with encrypted passwords
      that are usable by Apache basic authentication.</p>

      <p>To create Apache SHA1-variant basic-authentication passwords in various
      languages:</p>

      <example><title>PHP</title>
      '{SHA}' . base64_encode(sha1($password, TRUE))
      </example>

      <example><title>Java</title>
      "{SHA}" + new sun.misc.BASE64Encoder().encode(java.security.MessageDigest.getInstance("SHA1").digest(password.getBytes()))
      </example>

      <example><title>ColdFusion</title>
      "{SHA}" &amp; ToBase64(BinaryDecode(Hash(password, "SHA1"), "Hex"))
      </example>

      <example><title>Ruby</title>
      require 'digest/sha1'<br />
      require 'base64'<br />
      '{SHA}' + Base64.encode64(Digest::SHA1.digest(password))
      </example>

      <example><title>C or C++</title>
      Use the APR function: apr_sha1_base64
      </example>

      <example>
        <title>PostgreSQL (with the contrib/pgcrypto functions
               installed)</title>
        '{SHA}'||encode(digest(password,'sha1'),'base64')
      </example>
    </section>

  </section>

  <section id="digest"><title>Digest Authentication</title>
    <p>Apache recognizes one format for
    digest-authentication passwords - the MD5 hash of the string
    <code>user:realm:password</code> as a 32-character string of hexadecimal
    digits. <code>realm</code> is the Authorization Realm argument to the
    <directive module="mod_authn_core">AuthName</directive> directive in
    httpd.conf.</p>

    <section><title>Database password fields for mod_dbd</title>

      <p>Since the MD5 function is commonly available, other software can
      populate a database with encrypted passwords that are usable by Apache
      digest authentication.</p>

      <p>To create Apache digest-authentication passwords in various
      languages:</p>

      <example><title>PHP</title>
      md5($user . ':' . $realm . ':' .$password)
      </example>

      <example><title>Java</title>
      byte b[] = java.security.MessageDigest.getInstance("MD5").digest( (user + ":" + realm + ":" + password ).getBytes());<br />
      java.math.BigInteger bi = new java.math.BigInteger(1, b);<br />
      String s = bi.toString(16);<br />
      while (s.length() &lt; 32)<br />
      <indent>
        s = "0" + s;
      </indent>
      // String s is the encrypted password
      </example>

      <example><title>ColdFusion</title>
      LCase(Hash( (user &amp; ":" &amp; realm &amp; ":" &amp; password) , "MD5"))
      </example>

      <example><title>Ruby</title>
      require 'digest/md5'<br />
      Digest::MD5.hexdigest(user + ':' + realm + ':' + password)
      </example>

      <example>
        <title>PostgreSQL (with the contrib/pgcrypto functions installed)</title>
        encode(digest( user || ':' || realm || ':' || password , 'md5'), 'hex')
      </example>

    </section>
  </section>

</manualpage>
