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.commons.compress.archivers.tar; 020 021import static org.apache.commons.compress.archivers.tar.TarConstants.CHKSUMLEN; 022import static org.apache.commons.compress.archivers.tar.TarConstants.CHKSUM_OFFSET; 023 024import java.io.IOException; 025import java.math.BigInteger; 026import java.nio.ByteBuffer; 027import org.apache.commons.compress.archivers.zip.ZipEncoding; 028import org.apache.commons.compress.archivers.zip.ZipEncodingHelper; 029 030/** 031 * This class provides static utility methods to work with byte streams. 032 * 033 * @Immutable 034 */ 035// CheckStyle:HideUtilityClassConstructorCheck OFF (bc) 036public class TarUtils { 037 038 private static final int BYTE_MASK = 255; 039 040 static final ZipEncoding DEFAULT_ENCODING = 041 ZipEncodingHelper.getZipEncoding(null); 042 043 /** 044 * Encapsulates the algorithms used up to Commons Compress 1.3 as 045 * ZipEncoding. 046 */ 047 static final ZipEncoding FALLBACK_ENCODING = new ZipEncoding() { 048 @Override 049 public boolean canEncode(final String name) { return true; } 050 051 @Override 052 public ByteBuffer encode(final String name) { 053 final int length = name.length(); 054 final byte[] buf = new byte[length]; 055 056 // copy until end of input or output is reached. 057 for (int i = 0; i < length; ++i) { 058 buf[i] = (byte) name.charAt(i); 059 } 060 return ByteBuffer.wrap(buf); 061 } 062 063 @Override 064 public String decode(final byte[] buffer) { 065 final int length = buffer.length; 066 final StringBuilder result = new StringBuilder(length); 067 068 for (final byte b : buffer) { 069 if (b == 0) { // Trailing null 070 break; 071 } 072 result.append((char) (b & 0xFF)); // Allow for sign-extension 073 } 074 075 return result.toString(); 076 } 077 }; 078 079 /** Private constructor to prevent instantiation of this utility class. */ 080 private TarUtils(){ 081 } 082 083 /** 084 * Parse an octal string from a buffer. 085 * 086 * <p>Leading spaces are ignored. 087 * The buffer must contain a trailing space or NUL, 088 * and may contain an additional trailing space or NUL.</p> 089 * 090 * <p>The input buffer is allowed to contain all NULs, 091 * in which case the method returns 0L 092 * (this allows for missing fields).</p> 093 * 094 * <p>To work-around some tar implementations that insert a 095 * leading NUL this method returns 0 if it detects a leading NUL 096 * since Commons Compress 1.4.</p> 097 * 098 * @param buffer The buffer from which to parse. 099 * @param offset The offset into the buffer from which to parse. 100 * @param length The maximum number of bytes to parse - must be at least 2 bytes. 101 * @return The long value of the octal string. 102 * @throws IllegalArgumentException if the trailing space/NUL is missing or if a invalid byte is detected. 103 */ 104 public static long parseOctal(final byte[] buffer, final int offset, final int length) { 105 long result = 0; 106 int end = offset + length; 107 int start = offset; 108 109 if (length < 2){ 110 throw new IllegalArgumentException("Length "+length+" must be at least 2"); 111 } 112 113 if (buffer[start] == 0) { 114 return 0L; 115 } 116 117 // Skip leading spaces 118 while (start < end){ 119 if (buffer[start] == ' '){ 120 start++; 121 } else { 122 break; 123 } 124 } 125 126 // Trim all trailing NULs and spaces. 127 // The ustar and POSIX tar specs require a trailing NUL or 128 // space but some implementations use the extra digit for big 129 // sizes/uids/gids ... 130 byte trailer = buffer[end - 1]; 131 while (start < end && (trailer == 0 || trailer == ' ')) { 132 end--; 133 trailer = buffer[end - 1]; 134 } 135 136 for ( ;start < end; start++) { 137 final byte currentByte = buffer[start]; 138 // CheckStyle:MagicNumber OFF 139 if (currentByte < '0' || currentByte > '7'){ 140 throw new IllegalArgumentException( 141 exceptionMessage(buffer, offset, length, start, currentByte)); 142 } 143 result = (result << 3) + (currentByte - '0'); // convert from ASCII 144 // CheckStyle:MagicNumber ON 145 } 146 147 return result; 148 } 149 150 /** 151 * Compute the value contained in a byte buffer. If the most 152 * significant bit of the first byte in the buffer is set, this 153 * bit is ignored and the rest of the buffer is interpreted as a 154 * binary number. Otherwise, the buffer is interpreted as an 155 * octal number as per the parseOctal function above. 156 * 157 * @param buffer The buffer from which to parse. 158 * @param offset The offset into the buffer from which to parse. 159 * @param length The maximum number of bytes to parse. 160 * @return The long value of the octal or binary string. 161 * @throws IllegalArgumentException if the trailing space/NUL is 162 * missing or an invalid byte is detected in an octal number, or 163 * if a binary number would exceed the size of a signed long 164 * 64-bit integer. 165 * @since 1.4 166 */ 167 public static long parseOctalOrBinary(final byte[] buffer, final int offset, 168 final int length) { 169 170 if ((buffer[offset] & 0x80) == 0) { 171 return parseOctal(buffer, offset, length); 172 } 173 final boolean negative = buffer[offset] == (byte) 0xff; 174 if (length < 9) { 175 return parseBinaryLong(buffer, offset, length, negative); 176 } 177 return parseBinaryBigInteger(buffer, offset, length, negative); 178 } 179 180 private static long parseBinaryLong(final byte[] buffer, final int offset, 181 final int length, 182 final boolean negative) { 183 if (length >= 9) { 184 throw new IllegalArgumentException("At offset " + offset + ", " 185 + length + " byte binary number" 186 + " exceeds maximum signed long" 187 + " value"); 188 } 189 long val = 0; 190 for (int i = 1; i < length; i++) { 191 val = (val << 8) + (buffer[offset + i] & 0xff); 192 } 193 if (negative) { 194 // 2's complement 195 val--; 196 val ^= (long) Math.pow(2.0, (length - 1) * 8.0) - 1; 197 } 198 return negative ? -val : val; 199 } 200 201 private static long parseBinaryBigInteger(final byte[] buffer, 202 final int offset, 203 final int length, 204 final boolean negative) { 205 final byte[] remainder = new byte[length - 1]; 206 System.arraycopy(buffer, offset + 1, remainder, 0, length - 1); 207 BigInteger val = new BigInteger(remainder); 208 if (negative) { 209 // 2's complement 210 val = val.add(BigInteger.valueOf(-1)).not(); 211 } 212 if (val.bitLength() > 63) { 213 throw new IllegalArgumentException("At offset " + offset + ", " 214 + length + " byte binary number" 215 + " exceeds maximum signed long" 216 + " value"); 217 } 218 return negative ? -val.longValue() : val.longValue(); 219 } 220 221 /** 222 * Parse a boolean byte from a buffer. 223 * Leading spaces and NUL are ignored. 224 * The buffer may contain trailing spaces or NULs. 225 * 226 * @param buffer The buffer from which to parse. 227 * @param offset The offset into the buffer from which to parse. 228 * @return The boolean value of the bytes. 229 * @throws IllegalArgumentException if an invalid byte is detected. 230 */ 231 public static boolean parseBoolean(final byte[] buffer, final int offset) { 232 return buffer[offset] == 1; 233 } 234 235 // Helper method to generate the exception message 236 private static String exceptionMessage(final byte[] buffer, final int offset, 237 final int length, final int current, final byte currentByte) { 238 // default charset is good enough for an exception message, 239 // 240 // the alternative was to modify parseOctal and 241 // parseOctalOrBinary to receive the ZipEncoding of the 242 // archive (deprecating the existing public methods, of 243 // course) and dealing with the fact that ZipEncoding#decode 244 // can throw an IOException which parseOctal* doesn't declare 245 String string = new String(buffer, offset, length); 246 247 string=string.replaceAll("\0", "{NUL}"); // Replace NULs to allow string to be printed 248 final String s = "Invalid byte "+currentByte+" at offset "+(current-offset)+" in '"+string+"' len="+length; 249 return s; 250 } 251 252 /** 253 * Parse an entry name from a buffer. 254 * Parsing stops when a NUL is found 255 * or the buffer length is reached. 256 * 257 * @param buffer The buffer from which to parse. 258 * @param offset The offset into the buffer from which to parse. 259 * @param length The maximum number of bytes to parse. 260 * @return The entry name. 261 */ 262 public static String parseName(final byte[] buffer, final int offset, final int length) { 263 try { 264 return parseName(buffer, offset, length, DEFAULT_ENCODING); 265 } catch (final IOException ex) { 266 try { 267 return parseName(buffer, offset, length, FALLBACK_ENCODING); 268 } catch (final IOException ex2) { 269 // impossible 270 throw new RuntimeException(ex2); //NOSONAR 271 } 272 } 273 } 274 275 /** 276 * Parse an entry name from a buffer. 277 * Parsing stops when a NUL is found 278 * or the buffer length is reached. 279 * 280 * @param buffer The buffer from which to parse. 281 * @param offset The offset into the buffer from which to parse. 282 * @param length The maximum number of bytes to parse. 283 * @param encoding name of the encoding to use for file names 284 * @since 1.4 285 * @return The entry name. 286 * @throws IOException on error 287 */ 288 public static String parseName(final byte[] buffer, final int offset, 289 final int length, 290 final ZipEncoding encoding) 291 throws IOException { 292 293 int len = 0; 294 for (int i = offset; len < length && buffer[i] != 0; i++, len++); 295 if (len > 0) { 296 final byte[] b = new byte[len]; 297 System.arraycopy(buffer, offset, b, 0, len); 298 return encoding.decode(b); 299 } 300 return ""; 301 } 302 303 /** 304 * Copy a name into a buffer. 305 * Copies characters from the name into the buffer 306 * starting at the specified offset. 307 * If the buffer is longer than the name, the buffer 308 * is filled with trailing NULs. 309 * If the name is longer than the buffer, 310 * the output is truncated. 311 * 312 * @param name The header name from which to copy the characters. 313 * @param buf The buffer where the name is to be stored. 314 * @param offset The starting offset into the buffer 315 * @param length The maximum number of header bytes to copy. 316 * @return The updated offset, i.e. offset + length 317 */ 318 public static int formatNameBytes(final String name, final byte[] buf, final int offset, final int length) { 319 try { 320 return formatNameBytes(name, buf, offset, length, DEFAULT_ENCODING); 321 } catch (final IOException ex) { 322 try { 323 return formatNameBytes(name, buf, offset, length, 324 FALLBACK_ENCODING); 325 } catch (final IOException ex2) { 326 // impossible 327 throw new RuntimeException(ex2); //NOSONAR 328 } 329 } 330 } 331 332 /** 333 * Copy a name into a buffer. 334 * Copies characters from the name into the buffer 335 * starting at the specified offset. 336 * If the buffer is longer than the name, the buffer 337 * is filled with trailing NULs. 338 * If the name is longer than the buffer, 339 * the output is truncated. 340 * 341 * @param name The header name from which to copy the characters. 342 * @param buf The buffer where the name is to be stored. 343 * @param offset The starting offset into the buffer 344 * @param length The maximum number of header bytes to copy. 345 * @param encoding name of the encoding to use for file names 346 * @since 1.4 347 * @return The updated offset, i.e. offset + length 348 * @throws IOException on error 349 */ 350 public static int formatNameBytes(final String name, final byte[] buf, final int offset, 351 final int length, 352 final ZipEncoding encoding) 353 throws IOException { 354 int len = name.length(); 355 ByteBuffer b = encoding.encode(name); 356 while (b.limit() > length && len > 0) { 357 b = encoding.encode(name.substring(0, --len)); 358 } 359 final int limit = b.limit() - b.position(); 360 System.arraycopy(b.array(), b.arrayOffset(), buf, offset, limit); 361 362 // Pad any remaining output bytes with NUL 363 for (int i = limit; i < length; ++i) { 364 buf[offset + i] = 0; 365 } 366 367 return offset + length; 368 } 369 370 /** 371 * Fill buffer with unsigned octal number, padded with leading zeroes. 372 * 373 * @param value number to convert to octal - treated as unsigned 374 * @param buffer destination buffer 375 * @param offset starting offset in buffer 376 * @param length length of buffer to fill 377 * @throws IllegalArgumentException if the value will not fit in the buffer 378 */ 379 public static void formatUnsignedOctalString(final long value, final byte[] buffer, 380 final int offset, final int length) { 381 int remaining = length; 382 remaining--; 383 if (value == 0) { 384 buffer[offset + remaining--] = (byte) '0'; 385 } else { 386 long val = value; 387 for (; remaining >= 0 && val != 0; --remaining) { 388 // CheckStyle:MagicNumber OFF 389 buffer[offset + remaining] = (byte) ((byte) '0' + (byte) (val & 7)); 390 val = val >>> 3; 391 // CheckStyle:MagicNumber ON 392 } 393 if (val != 0){ 394 throw new IllegalArgumentException 395 (value+"="+Long.toOctalString(value)+ " will not fit in octal number buffer of length "+length); 396 } 397 } 398 399 for (; remaining >= 0; --remaining) { // leading zeros 400 buffer[offset + remaining] = (byte) '0'; 401 } 402 } 403 404 /** 405 * Write an octal integer into a buffer. 406 * 407 * Uses {@link #formatUnsignedOctalString} to format 408 * the value as an octal string with leading zeros. 409 * The converted number is followed by space and NUL 410 * 411 * @param value The value to write 412 * @param buf The buffer to receive the output 413 * @param offset The starting offset into the buffer 414 * @param length The size of the output buffer 415 * @return The updated offset, i.e offset+length 416 * @throws IllegalArgumentException if the value (and trailer) will not fit in the buffer 417 */ 418 public static int formatOctalBytes(final long value, final byte[] buf, final int offset, final int length) { 419 420 int idx=length-2; // For space and trailing null 421 formatUnsignedOctalString(value, buf, offset, idx); 422 423 buf[offset + idx++] = (byte) ' '; // Trailing space 424 buf[offset + idx] = 0; // Trailing null 425 426 return offset + length; 427 } 428 429 /** 430 * Write an octal long integer into a buffer. 431 * 432 * Uses {@link #formatUnsignedOctalString} to format 433 * the value as an octal string with leading zeros. 434 * The converted number is followed by a space. 435 * 436 * @param value The value to write as octal 437 * @param buf The destinationbuffer. 438 * @param offset The starting offset into the buffer. 439 * @param length The length of the buffer 440 * @return The updated offset 441 * @throws IllegalArgumentException if the value (and trailer) will not fit in the buffer 442 */ 443 public static int formatLongOctalBytes(final long value, final byte[] buf, final int offset, final int length) { 444 445 final int idx=length-1; // For space 446 447 formatUnsignedOctalString(value, buf, offset, idx); 448 buf[offset + idx] = (byte) ' '; // Trailing space 449 450 return offset + length; 451 } 452 453 /** 454 * Write an long integer into a buffer as an octal string if this 455 * will fit, or as a binary number otherwise. 456 * 457 * Uses {@link #formatUnsignedOctalString} to format 458 * the value as an octal string with leading zeros. 459 * The converted number is followed by a space. 460 * 461 * @param value The value to write into the buffer. 462 * @param buf The destination buffer. 463 * @param offset The starting offset into the buffer. 464 * @param length The length of the buffer. 465 * @return The updated offset. 466 * @throws IllegalArgumentException if the value (and trailer) 467 * will not fit in the buffer. 468 * @since 1.4 469 */ 470 public static int formatLongOctalOrBinaryBytes( 471 final long value, final byte[] buf, final int offset, final int length) { 472 473 // Check whether we are dealing with UID/GID or SIZE field 474 final long maxAsOctalChar = length == TarConstants.UIDLEN ? TarConstants.MAXID : TarConstants.MAXSIZE; 475 476 final boolean negative = value < 0; 477 if (!negative && value <= maxAsOctalChar) { // OK to store as octal chars 478 return formatLongOctalBytes(value, buf, offset, length); 479 } 480 481 if (length < 9) { 482 formatLongBinary(value, buf, offset, length, negative); 483 } else { 484 formatBigIntegerBinary(value, buf, offset, length, negative); 485 } 486 487 buf[offset] = (byte) (negative ? 0xff : 0x80); 488 return offset + length; 489 } 490 491 private static void formatLongBinary(final long value, final byte[] buf, 492 final int offset, final int length, 493 final boolean negative) { 494 final int bits = (length - 1) * 8; 495 final long max = 1l << bits; 496 long val = Math.abs(value); // Long.MIN_VALUE stays Long.MIN_VALUE 497 if (val < 0 || val >= max) { 498 throw new IllegalArgumentException("Value " + value + 499 " is too large for " + length + " byte field."); 500 } 501 if (negative) { 502 val ^= max - 1; 503 val++; 504 val |= 0xffl << bits; 505 } 506 for (int i = offset + length - 1; i >= offset; i--) { 507 buf[i] = (byte) val; 508 val >>= 8; 509 } 510 } 511 512 private static void formatBigIntegerBinary(final long value, final byte[] buf, 513 final int offset, 514 final int length, 515 final boolean negative) { 516 final BigInteger val = BigInteger.valueOf(value); 517 final byte[] b = val.toByteArray(); 518 final int len = b.length; 519 if (len > length - 1) { 520 throw new IllegalArgumentException("Value " + value + 521 " is too large for " + length + " byte field."); 522 } 523 final int off = offset + length - len; 524 System.arraycopy(b, 0, buf, off, len); 525 final byte fill = (byte) (negative ? 0xff : 0); 526 for (int i = offset + 1; i < off; i++) { 527 buf[i] = fill; 528 } 529 } 530 531 /** 532 * Writes an octal value into a buffer. 533 * 534 * Uses {@link #formatUnsignedOctalString} to format 535 * the value as an octal string with leading zeros. 536 * The converted number is followed by NUL and then space. 537 * 538 * @param value The value to convert 539 * @param buf The destination buffer 540 * @param offset The starting offset into the buffer. 541 * @param length The size of the buffer. 542 * @return The updated value of offset, i.e. offset+length 543 * @throws IllegalArgumentException if the value (and trailer) will not fit in the buffer 544 */ 545 public static int formatCheckSumOctalBytes(final long value, final byte[] buf, final int offset, final int length) { 546 547 int idx=length-2; // for NUL and space 548 formatUnsignedOctalString(value, buf, offset, idx); 549 550 buf[offset + idx++] = 0; // Trailing null 551 buf[offset + idx] = (byte) ' '; // Trailing space 552 553 return offset + length; 554 } 555 556 /** 557 * Compute the checksum of a tar entry header. 558 * 559 * @param buf The tar entry's header buffer. 560 * @return The computed checksum. 561 */ 562 public static long computeCheckSum(final byte[] buf) { 563 long sum = 0; 564 565 for (final byte element : buf) { 566 sum += BYTE_MASK & element; 567 } 568 569 return sum; 570 } 571 572 /** 573 * Wikipedia <a href="http://en.wikipedia.org/wiki/Tar_(file_format)#File_header">says</a>: 574 * <blockquote> 575 * The checksum is calculated by taking the sum of the unsigned byte values 576 * of the header block with the eight checksum bytes taken to be ascii 577 * spaces (decimal value 32). It is stored as a six digit octal number with 578 * leading zeroes followed by a NUL and then a space. Various 579 * implementations do not adhere to this format. For better compatibility, 580 * ignore leading and trailing whitespace, and get the first six digits. In 581 * addition, some historic tar implementations treated bytes as signed. 582 * Implementations typically calculate the checksum both ways, and treat it 583 * as good if either the signed or unsigned sum matches the included 584 * checksum. 585 * </blockquote> 586 * <p> 587 * The return value of this method should be treated as a best-effort 588 * heuristic rather than an absolute and final truth. The checksum 589 * verification logic may well evolve over time as more special cases 590 * are encountered. 591 * 592 * @param header tar header 593 * @return whether the checksum is reasonably good 594 * @see <a href="https://issues.apache.org/jira/browse/COMPRESS-191">COMPRESS-191</a> 595 * @since 1.5 596 */ 597 public static boolean verifyCheckSum(final byte[] header) { 598 final long storedSum = parseOctal(header, CHKSUM_OFFSET, CHKSUMLEN); 599 long unsignedSum = 0; 600 long signedSum = 0; 601 602 for (int i = 0; i < header.length; i++) { 603 byte b = header[i]; 604 if (CHKSUM_OFFSET <= i && i < CHKSUM_OFFSET + CHKSUMLEN) { 605 b = ' '; 606 } 607 unsignedSum += 0xff & b; 608 signedSum += b; 609 } 610 return storedSum == unsignedSum || storedSum == signedSum; 611 } 612 613}