CaseMetadata.java

Go to the documentation of this file.

/*
 * Autopsy Forensic Browser
 *
 * Copyright 2011-2019 Basis Technology Corp.
 * Contact: carrier <at> sleuthkit <dot> org
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.sleuthkit.autopsy.casemodule;

import java.io.BufferedWriter;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStreamWriter;
import java.io.StringWriter;
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.Locale;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.transform.OutputKeys;
import javax.xml.transform.Result;
import javax.xml.transform.Source;
import javax.xml.transform.Transformer;
import javax.xml.transform.TransformerException;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.dom.DOMSource;
import javax.xml.transform.stream.StreamResult;
import org.apache.commons.lang3.StringUtils;
import org.sleuthkit.autopsy.coreutils.Version;
import org.sleuthkit.autopsy.coreutils.XMLUtil;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.NodeList;
import org.xml.sax.SAXException;

public final class CaseMetadata {

    private static final String FILE_EXTENSION = ".aut";
    private static final String DATE_FORMAT_STRING = "yyyy/MM/dd HH:mm:ss (z)";
    private static final DateFormat DATE_FORMAT = new SimpleDateFormat(DATE_FORMAT_STRING, Locale.US);

    /*
     * Fields from schema version 1
     */
    private static final String SCHEMA_VERSION_ONE = "1.0";
    private final static String ROOT_ELEMENT_NAME = "AutopsyCase"; //NON-NLS
    private final static String SCHEMA_VERSION_ELEMENT_NAME = "SchemaVersion"; //NON-NLS
    private final static String CREATED_DATE_ELEMENT_NAME = "CreatedDate"; //NON-NLS
    private final static String AUTOPSY_VERSION_ELEMENT_NAME = "AutopsyCreatedVersion"; //NON-NLS
    private final static String CASE_ELEMENT_NAME = "Case"; //NON-NLS
    private final static String CASE_NAME_ELEMENT_NAME = "Name"; //NON-NLS
    private final static String CASE_NUMBER_ELEMENT_NAME = "Number"; //NON-NLS
    private final static String EXAMINER_ELEMENT_NAME = "Examiner"; //NON-NLS
    private final static String CASE_TYPE_ELEMENT_NAME = "CaseType"; //NON-NLS
    private final static String CASE_DATABASE_NAME_ELEMENT_NAME = "DatabaseName"; //NON-NLS
    private final static String TEXT_INDEX_NAME_ELEMENT = "TextIndexName"; //NON-NLS

    /*
     * Fields from schema version 2
     */
    private static final String SCHEMA_VERSION_TWO = "2.0";
    private final static String AUTOPSY_CREATED_BY_ELEMENT_NAME = "CreatedByAutopsyVersion"; //NON-NLS
    private final static String CASE_DB_ABSOLUTE_PATH_ELEMENT_NAME = "Database"; //NON-NLS
    private final static String TEXT_INDEX_ELEMENT = "TextIndex"; //NON-NLS

    /*
     * Fields from schema version 3
     */
    private static final String SCHEMA_VERSION_THREE = "3.0";
    private final static String CASE_DISPLAY_NAME_ELEMENT_NAME = "DisplayName"; //NON-NLS
    private final static String CASE_DB_NAME_RELATIVE_ELEMENT_NAME = "CaseDatabase"; //NON-NLS

    /*
     * Fields from schema version 4
     */
    private static final String SCHEMA_VERSION_FOUR = "4.0";
    private final static String EXAMINER_ELEMENT_PHONE = "ExaminerPhone"; //NON-NLS  
    private final static String EXAMINER_ELEMENT_EMAIL = "ExaminerEmail"; //NON-NLS
    private final static String CASE_ELEMENT_NOTES = "CaseNotes"; //NON-NLS

    /*
     * Fields from schema version 5
     */
    private static final String SCHEMA_VERSION_FIVE = "5.0";
    private final static String ORIGINAL_CASE_ELEMENT_NAME = "OriginalCase"; //NON-NLS  

    /*
     * Fields from schema version 6
     */
    private static final String SCHEMA_VERSION_SIX = "6.0";
    private final static String CONTENT_PROVIDER_ELEMENT_NAME = "ContentProvider";
    private final static String CONTENT_PROVIDER_NAME_ELEMENT_NAME = "Name";
    
    /*
     * Unread fields, regenerated on save.
     */
    private final static String MODIFIED_DATE_ELEMENT_NAME = "ModifiedDate"; //NON-NLS
    private final static String AUTOPSY_SAVED_BY_ELEMENT_NAME = "SavedByAutopsyVersion"; //NON-NLS

    private final static String CURRENT_SCHEMA_VERSION = SCHEMA_VERSION_SIX;

    private final Path metadataFilePath;
    private Case.CaseType caseType;
    private String caseName;
    private CaseDetails caseDetails;
    private String caseDatabaseName;
    private String caseDatabasePath;
    private String textIndexName; // Legacy
    private String createdDate;
    private String createdByVersion;
    private CaseMetadata originalMetadata = null; // For portable cases
    private String contentProviderName;

    public static String getFileExtension() {
        return FILE_EXTENSION;
    }

    public static DateFormat getDateFormat() {
        return new SimpleDateFormat(DATE_FORMAT_STRING, Locale.US);
    }

    CaseMetadata(Case.CaseType caseType, String caseDirectory, String caseName, CaseDetails caseDetails) {
        this(caseType, caseDirectory, caseName, caseDetails, null);
    }

    CaseMetadata(Case.CaseType caseType, String caseDirectory, String caseName, CaseDetails caseDetails, CaseMetadata originalMetadata) {
        metadataFilePath = Paths.get(caseDirectory, caseDetails.getCaseDisplayName() + FILE_EXTENSION);
        this.caseType = caseType;
        this.caseName = caseName;
        this.caseDetails = caseDetails;
        caseDatabaseName = "";
        caseDatabasePath = "";
        textIndexName = "";
        createdByVersion = Version.getVersion();
        createdDate = CaseMetadata.DATE_FORMAT.format(new Date());
        this.originalMetadata = originalMetadata;
        this.contentProviderName = originalMetadata == null ? null : originalMetadata.contentProviderName;
    }

    public CaseMetadata(Path metadataFilePath) throws CaseMetadataException {
        this.metadataFilePath = metadataFilePath;
        readFromFile();
    }

    public static Path getCaseMetadataFilePath(Path directoryPath) {
        final File[] files = directoryPath.toFile().listFiles();
        if (files != null) {
            for (File file : files) {
                final String fileName = file.getName().toLowerCase();
                if (fileName.endsWith(CaseMetadata.getFileExtension()) && file.isFile()) {
                    return file.toPath();
                }
            }
        }
        return null;
    }

    public String getContentProviderName() {
        return this.contentProviderName;
    }

    public Path getFilePath() {
        return metadataFilePath;
    }

    public String getCaseDirectory() {
        return StringUtils.isBlank(this.caseDatabasePath)
                ? metadataFilePath.getParent().toString()
                : Paths.get(this.caseDatabasePath).getParent().toString();
    }

    public Case.CaseType getCaseType() {
        return caseType;
    }

    public String getCaseName() {
        return caseName;
    }

    public CaseDetails getCaseDetails() {
        return caseDetails;
    }

    public String getCaseDisplayName() {
        return caseDetails.getCaseDisplayName();
    }

    void setCaseDetails(CaseDetails newCaseDetails) throws CaseMetadataException {
        CaseDetails oldCaseDetails = this.caseDetails;
        this.caseDetails = newCaseDetails;
        try {
            writeToFile();
        } catch (CaseMetadataException ex) {
            this.caseDetails = oldCaseDetails;
            throw ex;
        }
    }

    public String getCaseNumber() {
        return caseDetails.getCaseNumber();
    }

    public String getExaminer() {
        return caseDetails.getExaminerName();
    }

    public String getExaminerPhone() {
        return caseDetails.getExaminerPhone();
    }

    public String getExaminerEmail() {
        return caseDetails.getExaminerEmail();
    }

    public String getCaseNotes() {
        return caseDetails.getCaseNotes();
    }

    public String getCaseDatabaseName() {
        return caseDatabaseName;
    }

    void setCaseDatabaseName(String caseDatabaseName) throws CaseMetadataException {
        String oldCaseDatabaseName = this.caseDatabaseName;
        this.caseDatabaseName = caseDatabaseName;
        try {
            writeToFile();
        } catch (CaseMetadataException ex) {
            this.caseDatabaseName = oldCaseDatabaseName;
            throw ex;
        }
    }

    public String getTextIndexName() {
        return textIndexName;
    }

    public String getCreatedDate() {
        return createdDate;
    }

    void setCreatedDate(String createdDate) throws CaseMetadataException {
        String oldCreatedDate = createdDate;
        this.createdDate = createdDate;
        try {
            writeToFile();
        } catch (CaseMetadataException ex) {
            this.createdDate = oldCreatedDate;
            throw ex;
        }
    }

    String getCreatedByVersion() {
        return createdByVersion;
    }

    void setCreatedByVersion(String buildVersion) throws CaseMetadataException {
        String oldCreatedByVersion = this.createdByVersion;
        this.createdByVersion = buildVersion;
        try {
            writeToFile();
        } catch (CaseMetadataException ex) {
            this.createdByVersion = oldCreatedByVersion;
            throw ex;
        }
    }

    void writeToFile() throws CaseMetadataException {
        try {
            /*
             * Create the XML DOM.
             */
            Document doc = XMLUtil.createDocument();
            createXMLDOM(doc);
            doc.normalize();

            /*
             * Prepare the DOM for pretty printing to the metadata file.
             */
            Source source = new DOMSource(doc);
            StringWriter stringWriter = new StringWriter();
            Result streamResult = new StreamResult(stringWriter);
            Transformer transformer = TransformerFactory.newInstance().newTransformer();
            transformer.setOutputProperty(OutputKeys.INDENT, "yes"); //NON-NLS
            transformer.setOutputProperty("{http://xml.apache.org/xslt}indent-amount", "2"); //NON-NLS
            transformer.transform(source, streamResult);

            /*
             * Write the DOM to the metadata file.  Add UTF-8 Characterset so it writes to the file
             * correctly for non-latin characters
             */
            try (BufferedWriter fileWriter = new BufferedWriter(new OutputStreamWriter(new FileOutputStream(metadataFilePath.toFile()), StandardCharsets.UTF_8))) {
                fileWriter.write(stringWriter.toString());
                fileWriter.flush();
            }

        } catch (ParserConfigurationException | TransformerException | IOException ex) {
            throw new CaseMetadataException(String.format("Error writing to case metadata file %s", metadataFilePath), ex);
        }
    }

    /*
     * Creates an XML DOM from the case metadata.
     */
    private void createXMLDOM(Document doc) {
        /*
         * Create the root element and its children.
         */
        Element rootElement = doc.createElement(ROOT_ELEMENT_NAME);
        doc.appendChild(rootElement);
        createChildElement(doc, rootElement, SCHEMA_VERSION_ELEMENT_NAME, CURRENT_SCHEMA_VERSION);
        createChildElement(doc, rootElement, CREATED_DATE_ELEMENT_NAME, createdDate);
        createChildElement(doc, rootElement, MODIFIED_DATE_ELEMENT_NAME, DATE_FORMAT.format(new Date()));
        createChildElement(doc, rootElement, AUTOPSY_CREATED_BY_ELEMENT_NAME, createdByVersion);
        createChildElement(doc, rootElement, AUTOPSY_SAVED_BY_ELEMENT_NAME, Version.getVersion());
        Element caseElement = doc.createElement(CASE_ELEMENT_NAME);
        rootElement.appendChild(caseElement);

        Element contentProviderEl = doc.createElement(CONTENT_PROVIDER_ELEMENT_NAME);
        rootElement.appendChild(contentProviderEl);
        
        Element contentProviderNameEl = doc.createElement(CONTENT_PROVIDER_NAME_ELEMENT_NAME);
        if (this.contentProviderName != null) {
            contentProviderNameEl.setTextContent(this.contentProviderName);   
        }
        contentProviderEl.appendChild(contentProviderNameEl);
            
        /*
         * Create the children of the case element.
         */
        createCaseElements(doc, caseElement, this);

        /*
         * Add original case element
         */
        Element originalCaseElement = doc.createElement(ORIGINAL_CASE_ELEMENT_NAME);
        rootElement.appendChild(originalCaseElement);
        if (originalMetadata != null) {
            createChildElement(doc, originalCaseElement, CREATED_DATE_ELEMENT_NAME, originalMetadata.createdDate);
            Element originalCaseDetailsElement = doc.createElement(CASE_ELEMENT_NAME);
            originalCaseElement.appendChild(originalCaseDetailsElement);
            createCaseElements(doc, originalCaseDetailsElement, originalMetadata);
        }

    }

    private void createCaseElements(Document doc, Element caseElement, CaseMetadata metadataToWrite) {
        CaseDetails caseDetailsToWrite = metadataToWrite.caseDetails;
        createChildElement(doc, caseElement, CASE_NAME_ELEMENT_NAME, metadataToWrite.caseName);
        createChildElement(doc, caseElement, CASE_DISPLAY_NAME_ELEMENT_NAME, caseDetailsToWrite.getCaseDisplayName());
        createChildElement(doc, caseElement, CASE_NUMBER_ELEMENT_NAME, caseDetailsToWrite.getCaseNumber());
        createChildElement(doc, caseElement, EXAMINER_ELEMENT_NAME, caseDetailsToWrite.getExaminerName());
        createChildElement(doc, caseElement, EXAMINER_ELEMENT_PHONE, caseDetailsToWrite.getExaminerPhone());
        createChildElement(doc, caseElement, EXAMINER_ELEMENT_EMAIL, caseDetailsToWrite.getExaminerEmail());
        createChildElement(doc, caseElement, CASE_ELEMENT_NOTES, caseDetailsToWrite.getCaseNotes());
        createChildElement(doc, caseElement, CASE_TYPE_ELEMENT_NAME, metadataToWrite.caseType.toString());
        createChildElement(doc, caseElement, CASE_DB_ABSOLUTE_PATH_ELEMENT_NAME, metadataToWrite.caseDatabasePath);
        createChildElement(doc, caseElement, CASE_DB_NAME_RELATIVE_ELEMENT_NAME, metadataToWrite.caseDatabaseName);
        createChildElement(doc, caseElement, TEXT_INDEX_ELEMENT, metadataToWrite.textIndexName);
    }

    private void createChildElement(Document doc, Element parentElement, String elementName, String elementContent) {
        Element element = doc.createElement(elementName);
        element.appendChild(doc.createTextNode(elementContent));
        parentElement.appendChild(element);
    }

    private void readFromFile() throws CaseMetadataException {
        try {
            /*
             * Parse the file into an XML DOM and get the root element.
             */
            DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
            Document doc = builder.parse(this.getFilePath().toFile());
            doc.getDocumentElement().normalize();
            Element rootElement = doc.getDocumentElement();
            if (!rootElement.getNodeName().equals(ROOT_ELEMENT_NAME)) {
                throw new CaseMetadataException("Case metadata file corrupted");
            }

            /*
             * Get the content of the relevant children of the root element.
             */
            String schemaVersion = getElementTextContent(rootElement, SCHEMA_VERSION_ELEMENT_NAME, true);
            this.createdDate = getElementTextContent(rootElement, CREATED_DATE_ELEMENT_NAME, true);
            if (schemaVersion.equals(SCHEMA_VERSION_ONE)) {
                this.createdByVersion = getElementTextContent(rootElement, AUTOPSY_VERSION_ELEMENT_NAME, true);
            } else {
                this.createdByVersion = getElementTextContent(rootElement, AUTOPSY_CREATED_BY_ELEMENT_NAME, true);
            }
            
            Element contentProviderEl = getChildElOrNull(rootElement, CONTENT_PROVIDER_ELEMENT_NAME);
            if (contentProviderEl != null) {
                Element contentProviderNameEl = getChildElOrNull(contentProviderEl, CONTENT_PROVIDER_NAME_ELEMENT_NAME);
                this.contentProviderName = contentProviderNameEl != null ? contentProviderNameEl.getTextContent() : null;
            } else {
                this.contentProviderName = null;
            }
             
            /*
             * Get the content of the children of the case element.
             */
            NodeList caseElements = doc.getElementsByTagName(CASE_ELEMENT_NAME);
            if (caseElements.getLength() == 0) {
                throw new CaseMetadataException("Case metadata file corrupted");
            }
            Element caseElement = (Element) caseElements.item(0);
            this.caseName = getElementTextContent(caseElement, CASE_NAME_ELEMENT_NAME, true);
            String caseDisplayName;
            String caseNumber;
            if (schemaVersion.equals(SCHEMA_VERSION_ONE) || schemaVersion.equals(SCHEMA_VERSION_TWO)) {
                caseDisplayName = caseName;
            } else {
                caseDisplayName = getElementTextContent(caseElement, CASE_DISPLAY_NAME_ELEMENT_NAME, true);
            }
            caseNumber = getElementTextContent(caseElement, CASE_NUMBER_ELEMENT_NAME, false);
            String examinerName = getElementTextContent(caseElement, EXAMINER_ELEMENT_NAME, false);
            String examinerPhone;
            String examinerEmail;
            String caseNotes;
            if (schemaVersion.equals(SCHEMA_VERSION_ONE) || schemaVersion.equals(SCHEMA_VERSION_TWO) || schemaVersion.equals(SCHEMA_VERSION_THREE)) {
                examinerPhone = "";  //case had metadata file written before additional examiner details were included 
                examinerEmail = "";
                caseNotes = "";
            } else {
                examinerPhone = getElementTextContent(caseElement, EXAMINER_ELEMENT_PHONE, false);
                examinerEmail = getElementTextContent(caseElement, EXAMINER_ELEMENT_EMAIL, false);
                caseNotes = getElementTextContent(caseElement, CASE_ELEMENT_NOTES, false);
            }

            this.caseDetails = new CaseDetails(caseDisplayName, caseNumber, examinerName, examinerPhone, examinerEmail, caseNotes);
            this.caseType = Case.CaseType.fromString(getElementTextContent(caseElement, CASE_TYPE_ELEMENT_NAME, true));
            if (null == this.caseType) {
                throw new CaseMetadataException("Case metadata file corrupted");
            }
            switch (schemaVersion) {
                case SCHEMA_VERSION_ONE:
                    this.caseDatabaseName = getElementTextContent(caseElement, CASE_DATABASE_NAME_ELEMENT_NAME, true);
                    this.textIndexName = getElementTextContent(caseElement, TEXT_INDEX_NAME_ELEMENT, true);
                    break;
                case SCHEMA_VERSION_TWO:
                    this.caseDatabaseName = getElementTextContent(caseElement, CASE_DB_ABSOLUTE_PATH_ELEMENT_NAME, true);
                    this.textIndexName = getElementTextContent(caseElement, TEXT_INDEX_ELEMENT, false);
                    break;
                default:
                    this.caseDatabasePath = getElementTextContent(caseElement, CASE_DB_ABSOLUTE_PATH_ELEMENT_NAME, false);
                    this.caseDatabaseName = getElementTextContent(caseElement, CASE_DB_NAME_RELATIVE_ELEMENT_NAME, true);
                    this.textIndexName = getElementTextContent(caseElement, TEXT_INDEX_ELEMENT, false);
                    break;
            }

            /*
             * Fix up the case database name due to a bug that for a time caused
             * the absolute paths of single-user case databases to be stored.
             * Derive the missing (absolute/relative) value from the one
             * present.
             */
            Path possibleAbsoluteCaseDbPath = Paths.get(this.caseDatabaseName);
            Path caseDirectoryPath = Paths.get(getCaseDirectory());
            if (possibleAbsoluteCaseDbPath.toFile().isAbsolute()) {
                this.caseDatabasePath = this.caseDatabaseName;
                this.caseDatabaseName = caseDirectoryPath.relativize(possibleAbsoluteCaseDbPath).toString();
            }

        } catch (ParserConfigurationException | SAXException | IOException ex) {
            throw new CaseMetadataException(String.format("Error reading from case metadata file %s", metadataFilePath), ex);
        }
    }
    
    private Element getChildElOrNull(Element parent, String childTag) {
        NodeList nl = parent.getElementsByTagName(childTag);
        if (nl != null && nl.getLength() > 0 && nl.item(0) instanceof Element) {
            return (Element) nl.item(0);
        } else {
            return null;
        }
    }
    
    private String getElementTextContent(Element parentElement, String elementName, boolean contentIsRequired) throws CaseMetadataException {
        NodeList elementsList = parentElement.getElementsByTagName(elementName);
        if (elementsList.getLength() == 0) {
            throw new CaseMetadataException(String.format("Missing %s element from case metadata file %s", elementName, metadataFilePath));
        }
        String textContent = elementsList.item(0).getTextContent();
        if (textContent.isEmpty() && contentIsRequired) {
            throw new CaseMetadataException(String.format("Empty %s element in case metadata file %s", elementName, metadataFilePath));
        }
        return textContent;
    }

    public final static class CaseMetadataException extends Exception {

        private static final long serialVersionUID = 1L;

        private CaseMetadataException(String message) {
            super(message);
        }

        private CaseMetadataException(String message, Throwable cause) {
            super(message, cause);
        }
    }

    public String getCaseDatabasePath() throws UnsupportedOperationException {
        if (Case.CaseType.SINGLE_USER_CASE == caseType) {
            return StringUtils.isBlank(this.caseDatabasePath)
                    ? this.metadataFilePath.getParent().resolve(this.caseDatabaseName).toString()
                    : this.caseDatabasePath;
        } else {
            throw new UnsupportedOperationException();
        }
    }

}