001    /*
002     * $Header$
003     * $Revision: 129 $
004     * $Date: 2007-11-14 19:21:33 -0800 (Wed, 14 Nov 2007) $
005     *
006     * ====================================================================
007     *
008     *  Copyright 1999-2004 The Apache Software Foundation
009     *
010     *  Licensed under the Apache License, Version 2.0 (the "License");
011     *  you may not use this file except in compliance with the License.
012     *  You may obtain a copy of the License at
013     *
014     *      http://www.apache.org/licenses/LICENSE-2.0
015     *
016     *  Unless required by applicable law or agreed to in writing, software
017     *  distributed under the License is distributed on an "AS IS" BASIS,
018     *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
019     *  See the License for the specific language governing permissions and
020     *  limitations under the License.
021     * ====================================================================
022     *
023     * This software consists of voluntary contributions made by many
024     * individuals on behalf of the Apache Software Foundation.  For more
025     * information on the Apache Software Foundation, please see
026     * <http://www.apache.org/>.
027     *
028     * [Additional notices, if required by prior licensing conditions]
029     *
030     * Alternatively, the contents of this file may be used under the
031     * terms of the GNU Lesser General Public License Version 2 or later
032     * (the "LGPL"), in which case the provisions of the LGPL are 
033     * applicable instead of those above.  See terms of LGPL at
034     * <http://www.gnu.org/copyleft/lesser.txt>.
035     * If you wish to allow use of your version of this file only under 
036     * the terms of the LGPL and not to allow others to use your version
037     * of this file under the Apache Software License, indicate your 
038     * decision by deleting the provisions above and replace them with 
039     * the notice and other provisions required by the LGPL.  If you do 
040     * not delete the provisions above, a recipient may use your version 
041     * of this file under either the Apache Software License or the LGPL.
042     */
043    
044    package org.apache.commons.httpclient.contrib.ssl;
045    
046    import org.apache.commons.ssl.HttpSecureProtocol;
047    
048    import java.io.IOException;
049    import java.security.GeneralSecurityException;
050    
051    /**
052     * A <code>SecureProtocolSocketFactory</code> that uses JSSE to create
053     * SSL sockets.  It will also support host name verification to help preventing
054     * man-in-the-middle attacks.  Host name verification is turned <b>on</b> by
055     * default but one will be able to turn it off, which might be a useful feature
056     * during development.  Host name verification will make sure the SSL sessions
057     * server host name matches with the the host name returned in the
058     * server certificates "Common Name" field of the "SubjectDN" entry.
059     *
060     * @author <a href="mailto:hauer@psicode.com">Sebastian Hauer</a>
061     *         <p/>
062     *         DISCLAIMER: HttpClient developers DO NOT actively support this component.
063     *         The component is provided as a reference material, which may be inappropriate
064     *         for use without additional customization.
065     *         </p>
066     */
067    public class StrictSSLProtocolSocketFactory extends HttpSecureProtocol {
068    
069        /**
070         * Constructor for StrictSSLProtocolSocketFactory.
071         *
072         * @param verifyHostname The host name verification flag. If set to
073         *                       <code>true</code> the SSL sessions server host name will be compared
074         *                       to the host name returned in the server certificates "Common Name"
075         *                       field of the "SubjectDN" entry.  If these names do not match a
076         *                       Exception is thrown to indicate this.  Enabling host name verification
077         *                       will help to prevent from man-in-the-middle attacks.  If set to
078         *                       <code>false</code> host name verification is turned off.
079         *                       <p/>
080         *                       Code sample:
081         *                       <p/>
082         *                       <blockquote>
083         *                       Protocol stricthttps = new Protocol(
084         *                       "https", new StrictSSLProtocolSocketFactory(true), 443);
085         *                       <p/>
086         *                       HttpClient client = new HttpClient();
087         *                       client.getHostConfiguration().setHost("localhost", 443, stricthttps);
088         *                       </blockquote>
089         */
090        public StrictSSLProtocolSocketFactory(boolean verifyHostname)
091            throws GeneralSecurityException, IOException {
092            super();
093            super.setCheckHostname(verifyHostname);
094        }
095    
096        /**
097         * Constructor for StrictSSLProtocolSocketFactory.
098         * Host name verification will be enabled by default.
099         */
100        public StrictSSLProtocolSocketFactory()
101            throws GeneralSecurityException, IOException {
102            this(true);
103        }
104    
105        /**
106         * Set the host name verification flag.
107         *
108         * @param verifyHostname The host name verification flag. If set to
109         *                       <code>true</code> the SSL sessions server host name will be compared
110         *                       to the host name returned in the server certificates "Common Name"
111         *                       field of the "SubjectDN" entry.  If these names do not match a
112         *                       Exception is thrown to indicate this.  Enabling host name verification
113         *                       will help to prevent from man-in-the-middle attacks.  If set to
114         *                       <code>false</code> host name verification is turned off.
115         */
116        public void setHostnameVerification(boolean verifyHostname) {
117            super.setCheckHostname(verifyHostname);
118        }
119    
120        /**
121         * Gets the status of the host name verification flag.
122         *
123         * @return Host name verification flag.  Either <code>true</code> if host
124         *         name verification is turned on, or <code>false</code> if host name
125         *         verification is turned off.
126         */
127        public boolean getHostnameVerification() {
128            return super.getCheckHostname();
129        }
130    
131    }