Source code

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