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/7.0/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             * @deprecated As of 7.0.0, replaced by {@link #sanitize(long, long, long, String, long, String, String[], String, Map)}
062             */
063            @Deprecated
064            public byte[] sanitize(
065                            long companyId, long groupId, long userId, String className,
066                            long classPK, String contentType, String[] modes, byte[] bytes,
067                            Map<String, Object> options)
068                    throws SanitizerException;
069    
070            /**
071             * Sanitizes the input stream content, assigning the results to the output
072             * stream.
073             *
074             * @param  companyId the primary key of the portal instance
075             * @param  groupId the primary key of the site's group
076             * @param  userId the user who changed the content
077             * @param  className the class name of the content model implementation
078             * @param  classPK the primary key of the content to sanitize,
079             *         <code>0</code> if not available
080             * @param  contentType the content type. For more information, see {@link
081             *         com.liferay.portal.kernel.util.ContentTypes}.
082             * @param  modes ways in which to run the sanitizer, such as {@link
083             *         #MODE_ALL}, {@link #MODE_BAD_WORDS}, and/or {@link #MODE_XSS}
084             * @param  inputStream the content to be sanitized
085             * @param  outputStream the result of the sanitizing process
086             * @param  options a map of options for the sanitizer
087             * @throws SanitizerException if a sanitizer exception occurred
088             * @deprecated As of 7.0.0, replaced by {@link #sanitize(long, long, long, String, long, String, String[], String, Map)}
089             */
090            @Deprecated
091            public void sanitize(
092                            long companyId, long groupId, long userId, String className,
093                            long classPK, String contentType, String[] modes,
094                            InputStream inputStream, OutputStream outputStream,
095                            Map<String, Object> options)
096                    throws SanitizerException;
097    
098            /**
099             * Returns the sanitized content as a string.
100             *
101             * @param  companyId the primary key of the portal instance
102             * @param  groupId the primary key of the site's group
103             * @param  userId the user who changed the content
104             * @param  className the class name of the content model implementation
105             * @param  classPK the primary key of the content to sanitize,
106             *         <code>0</code> if not available
107             * @param  contentType the content type. For more information, see {@link
108             *         com.liferay.portal.kernel.util.ContentTypes}.
109             * @param  modes ways in which to run the sanitizer, such as {@link
110             *         #MODE_ALL}, {@link #MODE_BAD_WORDS}, and/or {@link #MODE_XSS}
111             * @param  content the content to sanitize
112             * @param  options the options map
113             * @return the sanitized content
114             * @throws SanitizerException if a sanitizer exception occurred
115             */
116            public String sanitize(
117                            long companyId, long groupId, long userId, String className,
118                            long classPK, String contentType, String[] modes, String content,
119                            Map<String, Object> options)
120                    throws SanitizerException;
121    
122    }