001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.shiro.crypto.hash.format;
020
021import org.apache.shiro.crypto.hash.Hash;
022import org.apache.shiro.crypto.hash.SimpleHash;
023import org.apache.shiro.crypto.hash.SimpleHashProvider;
024import org.apache.shiro.lang.codec.Base64;
025import org.apache.shiro.lang.util.ByteSource;
026import org.apache.shiro.lang.util.StringUtils;
027
028/**
029 * The {@code Shiro1CryptFormat} is a fully reversible
030 * <a href="http://packages.python.org/passlib/modular_crypt_format.html">Modular Crypt Format</a> (MCF).  Because it is
031 * fully reversible (i.e. Hash -&gt; String, String -&gt; Hash), it does NOT use the traditional MCF encoding alphabet
032 * (the traditional MCF encoding, aka H64, is bit-destructive and cannot be reversed).  Instead, it uses fully
033 * reversible Base64 encoding for the Hash digest and any salt value.
034 * <h2>Format</h2>
035 * <p>Hash instances formatted with this implementation will result in a String with the following dollar-sign ($)
036 * delimited format:</p>
037 * <pre>
038 * <b>$</b>mcfFormatId<b>$</b>algorithmName<b>$</b>iterationCount<b>$</b>base64EncodedSalt<b>$</b>base64EncodedDigest
039 * </pre>
040 * <p>Each token is defined as follows:</p>
041 * <table>
042 *     <tr>
043 *         <th>Position</th>
044 *         <th>Token</th>
045 *         <th>Description</th>
046 *         <th>Required?</th>
047 *     </tr>
048 *     <tr>
049 *         <td>1</td>
050 *         <td>{@code mcfFormatId}</td>
051 *         <td>The Modular Crypt Format identifier for this implementation, equal to <b>{@code shiro1}</b>.
052 *             ( This implies that all {@code shiro1} MCF-formatted strings will always begin with the prefix
053 *             {@code $shiro1$} ).</td>
054 *         <td>true</td>
055 *     </tr>
056 *     <tr>
057 *         <td>2</td>
058 *         <td>{@code algorithmName}</td>
059 *         <td>The name of the hash algorithm used to perform the hash.  This is an algorithm name understood by
060 *         {@code MessageDigest}.{@link java.security.MessageDigest#getInstance(String) getInstance}, for example
061 *         {@code MD5}, {@code SHA-256}, {@code SHA-256}, etc.</td>
062 *         <td>true</td>
063 *     </tr>
064 *     <tr>
065 *         <td>3</td>
066 *         <td>{@code iterationCount}</td>
067 *         <td>The number of hash iterations performed.</td>
068 *         <td>true (1 <= N <= Integer.MAX_VALUE)</td>
069 *     </tr>
070 *     <tr>
071 *         <td>4</td>
072 *         <td>{@code base64EncodedSalt}</td>
073 *         <td>The Base64-encoded salt byte array.  This token only exists if a salt was used to perform the hash.</td>
074 *         <td>false</td>
075 *     </tr>
076 *     <tr>
077 *         <td>5</td>
078 *         <td>{@code base64EncodedDigest}</td>
079 *         <td>The Base64-encoded digest byte array.  This is the actual hash result.</td>
080 *         <td>true</td>
081 *     </tr>
082 * </table>
083 *
084 * @see ModularCryptFormat
085 * @see ParsableHashFormat
086 * @since 1.2
087 */
088public class Shiro1CryptFormat implements ModularCryptFormat, ParsableHashFormat {
089
090    /**
091     * shiro1 crypt id.
092     */
093    public static final String ID = "shiro1";
094
095    /**
096     * shiro1 crypt format prefix
097     */
098    public static final String MCF_PREFIX = TOKEN_DELIMITER + ID + TOKEN_DELIMITER;
099
100    public Shiro1CryptFormat() {
101    }
102
103    @Override
104    public String getId() {
105        return ID;
106    }
107
108    @Override
109    public String format(final Hash hash) {
110        if (hash == null) {
111            return null;
112        }
113
114        String algorithmName = hash.getAlgorithmName();
115        ByteSource salt = hash.getSalt();
116        int iterations = hash.getIterations();
117        StringBuilder sb = new StringBuilder(MCF_PREFIX)
118                .append(algorithmName)
119                .append(TOKEN_DELIMITER)
120                .append(iterations)
121                .append(TOKEN_DELIMITER);
122
123        if (salt != null) {
124            sb.append(salt.toBase64());
125        }
126
127        sb.append(TOKEN_DELIMITER);
128        sb.append(hash.toBase64());
129
130        return sb.toString();
131    }
132
133    @Override
134    public Hash parse(final String formatted) {
135        if (formatted == null) {
136            return null;
137        }
138        if (!formatted.startsWith(MCF_PREFIX)) {
139            //TODO create a HashFormatException class
140            String msg = "The argument is not a valid '" + ID + "' formatted hash.";
141            throw new IllegalArgumentException(msg);
142        }
143
144        String suffix = formatted.substring(MCF_PREFIX.length());
145        String[] parts = suffix.split("\\$");
146
147        final String algorithmName = parts[0];
148        if (!new SimpleHashProvider().getImplementedAlgorithms().contains(algorithmName)) {
149            throw new UnsupportedOperationException("Algorithm " + algorithmName + " is not supported in shiro1 format.");
150        }
151
152        //last part is always the digest/checksum, Base64-encoded:
153        int i = parts.length - 1;
154        String digestBase64 = parts[i--];
155        //second-to-last part is always the salt, Base64-encoded:
156        String saltBase64 = parts[i--];
157        String iterationsString = parts[i--];
158
159        byte[] digest = Base64.decode(digestBase64);
160        ByteSource salt;
161
162        if (StringUtils.hasLength(saltBase64)) {
163            byte[] saltBytes = Base64.decode(saltBase64);
164            salt = ByteSource.Util.bytes(saltBytes);
165        } else {
166            salt = ByteSource.Util.bytes(new byte[0]);
167        }
168
169        int iterations;
170        try {
171            iterations = Integer.parseInt(iterationsString);
172        } catch (NumberFormatException e) {
173            String msg = "Unable to parse formatted hash string: " + formatted;
174            throw new IllegalArgumentException(msg, e);
175        }
176
177        SimpleHash hash = new SimpleHash(algorithmName);
178        hash.setBytes(digest);
179        hash.setSalt(salt);
180        hash.setIterations(iterations);
181
182        return hash;
183    }
184}