001    /**
002     * Copyright (c) 2000-present Liferay, Inc. All rights reserved.
003     *
004     * This library is free software; you can redistribute it and/or modify it under
005     * the terms of the GNU Lesser General Public License as published by the Free
006     * Software Foundation; either version 2.1 of the License, or (at your option)
007     * any later version.
008     *
009     * This library is distributed in the hope that it will be useful, but WITHOUT
010     * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
011     * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
012     * details.
013     */
014    
015    package com.liferay.portal.kernel.sanitizer;
016    
017    import java.io.InputStream;
018    import java.io.OutputStream;
019    
020    import java.util.Map;
021    
022    /**
023     * Provides an interface and constants for sanitizer component implementations.
024     * Commonly, sanitizers are implemented for stripping offensive vocabulary from
025     * content or for removing malicious HTML content, such as cross-site scripting
026     * (CSS). Multiple implementations can be deployed in a hook plugin and
027     * specified in a comma separated list of values for the
028     * <code>sanitizer.impl</code> portal property (see <a
029     * href="http://docs.liferay.com/portal/6.2/propertiesdoc/portal.properties.html#Sanitizer">Sanitizer</a>).
030     * All installed sanitizers are chained.
031     *
032     * @author Zsolt Balogh
033     * @author Brian Wing Shun Chan
034     */
035    public interface Sanitizer {
036    
037            public static final String MODE_ALL = "ALL";
038    
039            public static final String MODE_BAD_WORDS = "BAD_WORDS";
040    
041            public static final String MODE_XSS = "XSS";
042    
043            /**
044             * Returns the sanitized content as a byte array. Implementations may modify
045             * the input byte array.
046             *
047             * @param  companyId the primary key of the portal instance
048             * @param  groupId the primary key of the site's group
049             * @param  userId the user who changed the content
050             * @param  className the class name of the content model implementation
051             * @param  classPK the primary key of the content to sanitize,
052             *         <code>0</code> if not available
053             * @param  contentType the content type. For more information, see {@link
054             *         com.liferay.portal.kernel.util.ContentTypes}.
055             * @param  modes ways in which to run the sanitizer, such as {@link
056             *         #MODE_ALL}, {@link #MODE_BAD_WORDS}, and/or {@link #MODE_XSS}
057             * @param  bytes the content to be sanitized
058             * @param  options a map of options for the sanitizer
059             * @return the sanitized content
060             * @throws SanitizerException if a sanitizer exception occurred
061             */
062            public byte[] sanitize(
063                            long companyId, long groupId, long userId, String className,
064                            long classPK, String contentType, String[] modes, byte[] bytes,
065                            Map<String, Object> options)
066                    throws SanitizerException;
067    
068            /**
069             * Sanitizes the input stream content, assigning the results to the output
070             * stream.
071             *
072             * @param  companyId the primary key of the portal instance
073             * @param  groupId the primary key of the site's group
074             * @param  userId the user who changed the content
075             * @param  className the class name of the content model implementation
076             * @param  classPK the primary key of the content to sanitize,
077             *         <code>0</code> if not available
078             * @param  contentType the content type. For more information, see {@link
079             *         com.liferay.portal.kernel.util.ContentTypes}.
080             * @param  modes ways in which to run the sanitizer, such as {@link
081             *         #MODE_ALL}, {@link #MODE_BAD_WORDS}, and/or {@link #MODE_XSS}
082             * @param  inputStream the content to be sanitized
083             * @param  outputStream the result of the sanitizing process
084             * @param  options a map of options for the sanitizer
085             * @throws SanitizerException if a sanitizer exception occurred
086             */
087            public void sanitize(
088                            long companyId, long groupId, long userId, String className,
089                            long classPK, String contentType, String[] modes,
090                            InputStream inputStream, OutputStream outputStream,
091                            Map<String, Object> options)
092                    throws SanitizerException;
093    
094            /**
095             * Returns the sanitized content as a string.
096             *
097             * @param  companyId the primary key of the portal instance
098             * @param  groupId the primary key of the site's group
099             * @param  userId the user who changed the content
100             * @param  className the class name of the content model implementation
101             * @param  classPK the primary key of the content to sanitize,
102             *         <code>0</code> if not available
103             * @param  contentType the content type. For more information, see {@link
104             *         com.liferay.portal.kernel.util.ContentTypes}.
105             * @param  modes ways in which to run the sanitizer, such as {@link
106             *         #MODE_ALL}, {@link #MODE_BAD_WORDS}, and/or {@link #MODE_XSS}
107             * @param  s the content to sanitize
108             * @param  options the options map
109             * @return the sanitized content
110             * @throws SanitizerException if a sanitizer exception occurred
111             */
112            public String sanitize(
113                            long companyId, long groupId, long userId, String className,
114                            long classPK, String contentType, String[] modes, String s,
115                            Map<String, Object> options)
116                    throws SanitizerException;
117    
118    }