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
044package org.apache.commons.httpclient.contrib.ssl;
045
046import org.apache.commons.ssl.HttpSecureProtocol;
047
048import java.io.IOException;
049import 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 */
067public 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}