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