1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.shiro.lang.codec;
20
21
22 /**
23 * <a href="http://en.wikipedia.org/wiki/Hexadecimal">Hexadecimal</a> encoder and decoder.
24 * <p/>
25 * This class was borrowed from Apache Commons Codec SVN repository (rev. {@code 560660}) with modifications
26 * to enable Hex conversion without a full dependency on Commons Codec. We didn't want to reinvent the wheel of
27 * great work they've done, but also didn't want to force every Shiro user to depend on the commons-codec.jar
28 * <p/>
29 * As per the Apache 2.0 license, the original copyright notice and all author and copyright information have
30 * remained in tact.
31 *
32 * @see <a href="http://en.wikipedia.org/wiki/Hexadecimal">Wikipedia: Hexadecimal</a>
33 * @since 0.9
34 */
35 @SuppressWarnings("checkstyle:MagicNumber")
36 public final class Hex {
37
38 /**
39 * Used to build output as Hex
40 */
41 private static final char[] DIGITS = {
42 '0', '1', '2', '3', '4', '5', '6', '7',
43 '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'
44 };
45
46 private Hex() {
47
48 }
49
50 /**
51 * Encodes the specified byte array to a character array and then returns that character array
52 * as a String.
53 *
54 * @param bytes the byte array to Hex-encode.
55 * @return A String representation of the resultant hex-encoded char array.
56 */
57 public static String encodeToString(byte[] bytes) {
58 char[] encodedChars = encode(bytes);
59 return new String(encodedChars);
60 }
61
62 /**
63 * Converts an array of bytes into an array of characters representing the hexadecimal values of each byte in order.
64 * The returned array will be double the length of the passed array, as it takes two characters to represent any
65 * given byte.
66 *
67 * @param data byte[] to convert to Hex characters
68 * @return A char[] containing hexadecimal characters
69 */
70 public static char[] encode(byte[] data) {
71
72 int l = data.length;
73
74 char[] out = new char[l << 1];
75
76 // two characters form the hex value.
77 for (int i = 0, j = 0; i < l; i++) {
78 out[j++] = DIGITS[(0xF0 & data[i]) >>> 4];
79 out[j++] = DIGITS[0x0F & data[i]];
80 }
81
82 return out;
83 }
84
85 /**
86 * Converts an array of character bytes representing hexadecimal values into an
87 * array of bytes of those same values. The returned array will be half the
88 * length of the passed array, as it takes two characters to represent any
89 * given byte. An exception is thrown if the passed char array has an odd
90 * number of elements.
91 *
92 * @param array An array of character bytes containing hexadecimal digits
93 * @return A byte array containing binary data decoded from
94 * the supplied byte array (representing characters).
95 * @throws IllegalArgumentException Thrown if an odd number of characters is supplied
96 * to this function
97 * @see #decode(char[])
98 */
99 public static byte[] decode(byte[] array) throws IllegalArgumentException {
100 String s = CodecSupport.toString(array);
101 return decode(s);
102 }
103
104 /**
105 * Converts the specified Hex-encoded String into a raw byte array. This is a
106 * convenience method that merely delegates to {@link #decode(char[])} using the
107 * argument's hex.toCharArray() value.
108 *
109 * @param hex a Hex-encoded String.
110 * @return A byte array containing binary data decoded from the supplied String's char array.
111 */
112 public static byte[] decode(String hex) {
113 return decode(hex.toCharArray());
114 }
115
116 /**
117 * Converts an array of characters representing hexadecimal values into an
118 * array of bytes of those same values. The returned array will be half the
119 * length of the passed array, as it takes two characters to represent any
120 * given byte. An exception is thrown if the passed char array has an odd
121 * number of elements.
122 *
123 * @param data An array of characters containing hexadecimal digits
124 * @return A byte array containing binary data decoded from
125 * the supplied char array.
126 * @throws IllegalArgumentException if an odd number or illegal of characters
127 * is supplied
128 */
129 @SuppressWarnings("magicNumber")
130 public static byte[] decode(char[] data) throws IllegalArgumentException {
131
132 int len = data.length;
133
134 if ((len & 0x01) != 0) {
135 throw new IllegalArgumentException("Odd number of characters.");
136 }
137
138 byte[] out = new byte[len >> 1];
139
140 // two characters form the hex value.
141 for (int i = 0, j = 0; j < len; i++) {
142 int f = toDigit(data[j], j) << 4;
143 j++;
144 f = f | toDigit(data[j], j);
145 j++;
146 out[i] = (byte) (f & 0xFF);
147 }
148
149 return out;
150 }
151
152 /**
153 * Converts a hexadecimal character to an integer.
154 *
155 * @param ch A character to convert to an integer digit
156 * @param index The index of the character in the source
157 * @return An integer
158 * @throws IllegalArgumentException if ch is an illegal hex character
159 */
160 protected static int toDigit(char ch, int index) throws IllegalArgumentException {
161 int digit = Character.digit(ch, 2 << 3);
162 if (digit == -1) {
163 throw new IllegalArgumentException("Illegal hexadecimal character " + ch + " at index " + index);
164 }
165 return digit;
166 }
167
168
169 }