Source code

001/**
002 *
003 * Copyright 2003-2007 Jive Software, 2016-2020 Florian Schmaus.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.jivesoftware.smack.util;
019
020import java.io.IOException;
021import java.nio.CharBuffer;
022import java.nio.charset.StandardCharsets;
023import java.util.Arrays;
024import java.util.Collection;
025import java.util.Iterator;
026import java.util.List;
027import java.util.Random;
028import java.util.regex.Pattern;
029
030/**
031 * A collection of utility methods for String objects.
032 */
033public class StringUtils {
034
035    public static final String MD5 = "MD5";
036    public static final String SHA1 = "SHA-1";
037
038    /**
039     * Deprecated, do not use.
040     *
041     * @deprecated use StandardCharsets.UTF_8 instead.
042     */
043    // TODO: Remove in Smack 4.5.
044    @Deprecated
045    public static final String UTF8 = "UTF-8";
046
047    /**
048     * Deprecated, do not use.
049     *
050     * @deprecated use StandardCharsets.US_ASCII instead.
051     */
052    // TODO: Remove in Smack 4.5.
053    @Deprecated
054    public static final String USASCII = "US-ASCII";
055
056    public static final String QUOTE_ENCODE = "&quot;";
057    public static final String APOS_ENCODE = "&apos;";
058    public static final String AMP_ENCODE = "&amp;";
059    public static final String LT_ENCODE = "&lt;";
060    public static final String GT_ENCODE = "&gt;";
061
062    public static final char[] HEX_CHARS = "0123456789abcdef".toCharArray();
063
064    /**
065     * Escape <code>input</code> for XML.
066     *
067     * @param input the input to escape.
068     * @return the XML escaped variant of <code>input</code>.
069     */
070    public static CharSequence escapeForXml(CharSequence input) {
071        return escapeForXml(input, XmlEscapeMode.safe);
072    }
073
074    /**
075     * Escape <code>input</code> for XML.
076     *
077     * @param input the input to escape.
078     * @return the XML escaped variant of <code>input</code>.
079     * @since 4.2
080     */
081    public static CharSequence escapeForXmlAttribute(CharSequence input) {
082        return escapeForXml(input, XmlEscapeMode.forAttribute);
083    }
084
085    /**
086     * Escape <code>input</code> for XML.
087     * <p>
088     * This is an optimized variant of {@link #escapeForXmlAttribute(CharSequence)} for XML where the
089     * XML attribute is quoted using ''' (Apos).
090     * </p>
091     *
092     * @param input the input to escape.
093     * @return the XML escaped variant of <code>input</code>.
094     * @since 4.2
095     */
096    public static CharSequence escapeForXmlAttributeApos(CharSequence input) {
097        return escapeForXml(input, XmlEscapeMode.forAttributeApos);
098    }
099
100    /**
101     * Escape <code>input</code> for XML.
102     *
103     * @param input the input to escape.
104     * @return the XML escaped variant of <code>input</code>.
105     * @since 4.2
106     */
107    public static CharSequence escapeForXmlText(CharSequence input) {
108        return escapeForXml(input, XmlEscapeMode.forText);
109    }
110
111    private enum XmlEscapeMode {
112        safe,
113        forAttribute,
114        forAttributeApos,
115        forText,
116    }
117
118    /**
119     * Escapes all necessary characters in the CharSequence so that it can be used
120     * in an XML doc.
121     *
122     * @param input the CharSequence to escape.
123     * @return the string with appropriate characters escaped.
124     */
125    private static CharSequence escapeForXml(final CharSequence input, final XmlEscapeMode xmlEscapeMode) {
126        if (input == null) {
127            return null;
128        }
129        final int len = input.length();
130        final StringBuilder out = new StringBuilder((int) (len * 1.3));
131        CharSequence toAppend;
132        char ch;
133        int last = 0;
134        int i = 0;
135        while (i < len) {
136            toAppend = null;
137            ch = input.charAt(i);
138            switch (xmlEscapeMode) {
139            case safe:
140                switch (ch) {
141                case '<':
142                    toAppend = LT_ENCODE;
143                    break;
144                case '>':
145                    toAppend = GT_ENCODE;
146                    break;
147                case '&':
148                    toAppend = AMP_ENCODE;
149                    break;
150                case '"':
151                    toAppend = QUOTE_ENCODE;
152                    break;
153                case '\'':
154                    toAppend = APOS_ENCODE;
155                    break;
156                default:
157                    break;
158                }
159                break;
160            case forAttribute:
161                // No need to escape '>' for attributes.
162                switch (ch) {
163                case '<':
164                    toAppend = LT_ENCODE;
165                    break;
166                case '&':
167                    toAppend = AMP_ENCODE;
168                    break;
169                case '"':
170                    toAppend = QUOTE_ENCODE;
171                    break;
172                case '\'':
173                    toAppend = APOS_ENCODE;
174                    break;
175                default:
176                    break;
177                }
178                break;
179            case forAttributeApos:
180                // No need to escape '>' and '"' for attributes using '\'' as quote.
181                switch (ch) {
182                case '<':
183                    toAppend = LT_ENCODE;
184                    break;
185                case '&':
186                    toAppend = AMP_ENCODE;
187                    break;
188                case '\'':
189                    toAppend = APOS_ENCODE;
190                    break;
191                default:
192                    break;
193                }
194                break;
195            case forText:
196                // No need to escape '"', '\'', and '>' for text.
197                switch (ch) {
198                case '<':
199                    toAppend = LT_ENCODE;
200                    break;
201                case '&':
202                    toAppend = AMP_ENCODE;
203                    break;
204                default:
205                    break;
206                }
207                break;
208            }
209            if (toAppend != null) {
210                if (i > last) {
211                    out.append(input, last, i);
212                }
213                out.append(toAppend);
214                last = ++i;
215            } else {
216                i++;
217            }
218        }
219        if (last == 0) {
220            return input;
221        }
222        if (i > last) {
223            out.append(input, last, i);
224        }
225        return out;
226    }
227
228    /**
229     * Hashes a String using the SHA-1 algorithm and returns the result as a
230     * String of hexadecimal numbers. This method is synchronized to avoid
231     * excessive MessageDigest object creation. If calling this method becomes
232     * a bottleneck in your code, you may wish to maintain a pool of
233     * MessageDigest objects instead of using this method.
234     * <p>
235     * A hash is a one-way function -- that is, given an
236     * input, an output is easily computed. However, given the output, the
237     * input is almost impossible to compute. This is useful for passwords
238     * since we can store the hash and a hacker will then have a very hard time
239     * determining the original password.
240     *
241     * @param data the String to compute the hash of.
242     * @return a hashed version of the passed-in String
243     * @deprecated use {@link org.jivesoftware.smack.util.SHA1#hex(String)} instead.
244     */
245    @Deprecated
246    public static synchronized String hash(String data) {
247        return org.jivesoftware.smack.util.SHA1.hex(data);
248    }
249
250    /**
251     * Encodes an array of bytes as String representation of hexadecimal.
252     *
253     * @param bytes an array of bytes to convert to a hex string.
254     * @return generated hex string.
255     */
256    public static String encodeHex(byte[] bytes) {
257        char[] hexChars = new char[bytes.length * 2];
258        for (int j = 0; j < bytes.length; j++) {
259            int v = bytes[j] & 0xFF;
260            hexChars[j * 2] = HEX_CHARS[v >>> 4];
261            hexChars[j * 2 + 1] = HEX_CHARS[v & 0x0F];
262        }
263        return new String(hexChars);
264    }
265
266    public static byte[] toUtf8Bytes(String string) {
267        return string.getBytes(StandardCharsets.UTF_8);
268    }
269
270    /**
271     * 24 upper case characters from the latin alphabet and numbers without '0' and 'O'.
272     */
273    public static final String UNAMBIGUOUS_NUMBERS_AND_LETTERS_STRING = "123456789ABCDEFGHIJKLMNPQRSTUVWXYZ";
274
275    /**
276     * 24 upper case characters from the latin alphabet and numbers without '0' and 'O'.
277     */
278    private static final char[] UNAMBIGUOUS_NUMBERS_AND_LETTERS = UNAMBIGUOUS_NUMBERS_AND_LETTERS_STRING.toCharArray();
279
280    /**
281     * Returns a random String of numbers and letters (lower and upper case)
282     * of the specified length. The method uses the Random class that is
283     * built-in to Java which is suitable for low to medium grade security uses.
284     * This means that the output is only pseudo random, i.e., each number is
285     * mathematically generated so is not truly random.<p>
286     *
287     * The specified length must be at least one. If not, the method will return
288     * null.
289     *
290     * @param length the desired length of the random String to return.
291     * @return a random String of numbers and letters of the specified length.
292     */
293    public static String insecureRandomString(int length) {
294        return randomString(length, RandomUtil.RANDOM.get());
295    }
296
297    public static String secureOnlineAttackSafeRandomString() {
298        // 34^10 = 2.06e15 possible combinations. Which is enough to protect against online brute force attacks.
299        // See also https://www.grc.com/haystack.htm
300        final int REQUIRED_LENGTH = 10;
301
302        return randomString(RandomUtil.SECURE_RANDOM.get(), UNAMBIGUOUS_NUMBERS_AND_LETTERS, REQUIRED_LENGTH);
303    }
304
305    public static String secureUniqueRandomString() {
306        // 34^13 = 8.11e19 possible combinations, which is > 2^64.
307        final int REQUIRED_LENGTH = 13;
308
309        return randomString(RandomUtil.SECURE_RANDOM.get(), UNAMBIGUOUS_NUMBERS_AND_LETTERS, REQUIRED_LENGTH);
310    }
311
312    /**
313     * Generate a secure random string with is human readable. The resulting string consists of 24 upper case characters
314     * from the Latin alphabet and numbers without '0' and 'O', grouped into 4-characters chunks, e.g.
315     * "TWNK-KD5Y-MT3T-E1GS-DRDB-KVTW". The characters are randomly selected by a cryptographically secure pseudorandom
316     * number generator (CSPRNG).
317     * <p>
318     * The string can be used a backup "code" for secrets, and is in fact the same as the one backup code specified in
319     * XEP-0373 and the one used by the <a href="https://github.com/open-keychain/open-keychain/wiki/Backups">Backup
320     * Format v2 of OpenKeychain</a>.
321     * </p>
322     *
323     * @see <a href="https://xmpp.org/extensions/xep-0373.html#backup-encryption"> XEP-0373 §5.4 Encrypting the Secret
324     *      Key Backup</a>
325     * @return a human readable secure random string.
326     */
327    public static String secureOfflineAttackSafeRandomString() {
328        // 34^24 = 2^122.10 possible combinations. Which is enough to protect against offline brute force attacks.
329        // See also https://www.grc.com/haystack.htm
330        final int REQUIRED_LENGTH = 24;
331
332        return randomString(RandomUtil.SECURE_RANDOM.get(), UNAMBIGUOUS_NUMBERS_AND_LETTERS, REQUIRED_LENGTH);
333    }
334
335    private static final int RANDOM_STRING_CHUNK_SIZE = 4;
336
337    private static String randomString(Random random, char[] alphabet, int numRandomChars) {
338        // The buffer most hold the size of the requested number of random chars and the chunk separators ('-').
339        int bufferSize = numRandomChars + ((numRandomChars - 1) / RANDOM_STRING_CHUNK_SIZE);
340        CharBuffer charBuffer = CharBuffer.allocate(bufferSize);
341
342        try {
343            randomString(charBuffer, random, alphabet, numRandomChars);
344        } catch (IOException e) {
345            // This should never happen if we calcuate the buffer size correctly.
346            throw new AssertionError(e);
347        }
348
349        return charBuffer.flip().toString();
350    }
351
352    private static void randomString(Appendable appendable, Random random, char[] alphabet, int numRandomChars)
353                    throws IOException {
354        for (int randomCharNum = 1; randomCharNum <= numRandomChars; randomCharNum++) {
355            int randomIndex = random.nextInt(alphabet.length);
356            char randomChar = alphabet[randomIndex];
357            appendable.append(randomChar);
358
359            if (randomCharNum % RANDOM_STRING_CHUNK_SIZE == 0 && randomCharNum < numRandomChars) {
360                appendable.append('-');
361            }
362        }
363    }
364
365    public static String randomString(final int length) {
366        return randomString(length, RandomUtil.SECURE_RANDOM.get());
367    }
368
369    public static String randomString(final int length, Random random) {
370        if (length == 0) {
371            return "";
372        }
373
374        char[] randomChars = new char[length];
375        for (int i = 0; i < length; i++) {
376            int index = random.nextInt(UNAMBIGUOUS_NUMBERS_AND_LETTERS.length);
377            randomChars[i] = UNAMBIGUOUS_NUMBERS_AND_LETTERS[index];
378        }
379        return new String(randomChars);
380    }
381
382    /**
383     * Returns true if CharSequence is not null and is not empty, false otherwise.
384     * Examples:
385     *    isNotEmpty(null) - false
386     *    isNotEmpty("") - false
387     *    isNotEmpty(" ") - true
388     *    isNotEmpty("empty") - true
389     *
390     * @param cs checked CharSequence
391     * @return true if string is not null and is not empty, false otherwise
392     */
393    public static boolean isNotEmpty(CharSequence cs) {
394        return !isNullOrEmpty(cs);
395    }
396
397    /**
398     * Returns true if the given CharSequence is null or empty.
399     *
400     * @param cs TODO javadoc me please
401     * @return true if the given CharSequence is null or empty
402     */
403    public static boolean isNullOrEmpty(CharSequence cs) {
404        return cs == null || isEmpty(cs);
405    }
406
407    /**
408     * Returns true if all given CharSequences are not empty.
409     *
410     * @param css the CharSequences to test.
411     * @return true if all given CharSequences are not empty.
412     */
413    public static boolean isNotEmpty(CharSequence... css) {
414        for (CharSequence cs : css) {
415            if (StringUtils.isNullOrEmpty(cs)) {
416                return false;
417            }
418        }
419        return true;
420    }
421
422    /**
423     * Returns true if all given CharSequences are either null or empty.
424     *
425     * @param css the CharSequences to test.
426     * @return true if all given CharSequences are null or empty.
427     */
428    public static boolean isNullOrEmpty(CharSequence... css) {
429        for (CharSequence cs : css) {
430            if (StringUtils.isNotEmpty(cs)) {
431                return false;
432            }
433        }
434        return true;
435    }
436
437    public static boolean isNullOrNotEmpty(CharSequence cs) {
438        if (cs == null) {
439            return true;
440        }
441        return !cs.toString().isEmpty();
442    }
443
444    /**
445     * Returns true if the given CharSequence is empty.
446     *
447     * @param cs TODO javadoc me please
448     * @return true if the given CharSequence is empty
449     */
450    public static boolean isEmpty(CharSequence cs) {
451        return cs.length() == 0;
452    }
453
454    /**
455     * Transform a collection of objects to a whitespace delimited String.
456     *
457     * @param collection the collection to transform.
458     * @return a String with all the elements of the collection.
459     */
460    public static String collectionToString(Collection<? extends Object> collection) {
461        return toStringBuilder(collection, " ").toString();
462    }
463
464    /**
465     * Transform a collection of objects to a delimited String.
466     *
467     * @param collection the collection to transform.
468     * @param delimiter the delimiter used to delimit the Strings.
469     * @return a StringBuilder with all the elements of the collection.
470     */
471    public static StringBuilder toStringBuilder(Collection<? extends Object> collection, String delimiter) {
472        StringBuilder sb = new StringBuilder(collection.size() * 20);
473        appendTo(collection, delimiter, sb);
474        return sb;
475    }
476
477    public static void appendTo(Collection<? extends Object> collection, StringBuilder sb) {
478        appendTo(collection, ", ", sb);
479    }
480
481    public static <O extends Object> void appendTo(Collection<O> collection, StringBuilder sb,
482                    Consumer<O> appendFunction) {
483        appendTo(collection, ", ", sb, appendFunction);
484    }
485
486    public static void appendTo(Collection<? extends Object> collection, String delimiter, StringBuilder sb) {
487        appendTo(collection, delimiter, sb, o -> sb.append(o));
488    }
489
490    public static <O extends Object> void appendTo(Collection<O> collection, String delimiter, StringBuilder sb,
491                    Consumer<O> appendFunction) {
492        for (Iterator<O> it = collection.iterator(); it.hasNext();) {
493            O cs = it.next();
494            appendFunction.accept(cs);
495            if (it.hasNext()) {
496                sb.append(delimiter);
497            }
498        }
499    }
500
501    public static String returnIfNotEmptyTrimmed(String string) {
502        if (string == null)
503            return null;
504        String trimmedString = string.trim();
505        if (trimmedString.length() > 0) {
506            return trimmedString;
507        } else {
508            return null;
509        }
510    }
511
512    public static boolean nullSafeCharSequenceEquals(CharSequence csOne, CharSequence csTwo) {
513        return nullSafeCharSequenceComparator(csOne, csTwo) == 0;
514    }
515
516    public static int nullSafeCharSequenceComparator(CharSequence csOne, CharSequence csTwo) {
517        if (csOne == null ^ csTwo == null) {
518            return (csOne == null) ? -1 : 1;
519        }
520        if (csOne == null && csTwo == null) {
521            return 0;
522        }
523        return csOne.toString().compareTo(csTwo.toString());
524    }
525
526    /**
527     * Require a {@link CharSequence} to be neither null, nor empty.
528     *
529     * @deprecated use {@link #requireNotNullNorEmpty(CharSequence, String)} instead.
530     * @param cs CharSequence
531     * @param message error message
532     * @param <CS> CharSequence type
533     * @return cs TODO javadoc me please
534     */
535    @Deprecated
536    public static <CS extends CharSequence> CS requireNotNullOrEmpty(CS cs, String message) {
537        return requireNotNullNorEmpty(cs, message);
538    }
539
540    /**
541     * Require a {@link CharSequence} to be neither null, nor empty.
542     *
543     * @param cs CharSequence
544     * @param message error message
545     * @param <CS> CharSequence type
546     * @return cs TODO javadoc me please
547     */
548    public static <CS extends CharSequence> CS requireNotNullNorEmpty(CS cs, String message) {
549        if (isNullOrEmpty(cs)) {
550            throw new IllegalArgumentException(message);
551        }
552        return cs;
553    }
554
555    public static <CS extends CharSequence> CS requireNullOrNotEmpty(CS cs, String message) {
556        if (cs == null) {
557            return null;
558        }
559        if (isEmpty(cs)) {
560            throw new IllegalArgumentException(message);
561        }
562        return cs;
563    }
564
565    /**
566     * Return the String representation of the given char sequence if it is not null.
567     *
568     * @param cs the char sequence or null.
569     * @return the String representation of <code>cs</code> or null.
570     */
571    public static String maybeToString(CharSequence cs) {
572        if (cs == null) {
573            return null;
574        }
575        return cs.toString();
576    }
577
578    /**
579     * Defined by XML 1.0 § 2.3 as:
580     *  S      ::=      (#x20 | #x9 | #xD | #xA)+
581     *
582     * @see <a href="https://www.w3.org/TR/xml/#sec-white-space">XML 1.0 § 2.3</a>
583     */
584    private static final Pattern XML_WHITESPACE = Pattern.compile("[\t\n\r ]");
585
586    public static String deleteXmlWhitespace(String string) {
587        return XML_WHITESPACE.matcher(string).replaceAll("");
588    }
589
590    public static Appendable appendHeading(Appendable appendable, String heading) throws IOException {
591        return appendHeading(appendable, heading, '-');
592    }
593
594    public static Appendable appendHeading(Appendable appendable, String heading, char underlineChar) throws IOException {
595        appendable.append(heading).append('\n');
596        for (int i = 0; i < heading.length(); i++) {
597            appendable.append(underlineChar);
598        }
599        return appendable.append('\n');
600    }
601
602    public static final String PORTABLE_NEWLINE_REGEX = "\\r?\\n";
603
604    public static List<String> splitLinesPortable(String input) {
605        String[] lines = input.split(PORTABLE_NEWLINE_REGEX);
606        return Arrays.asList(lines);
607    }
608}