001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.vfs2.provider.ftps;
018
019import javax.net.ssl.KeyManager;
020import javax.net.ssl.TrustManager;
021
022import org.apache.commons.net.util.TrustManagerUtils;
023import org.apache.commons.vfs2.FileSystemOptions;
024import org.apache.commons.vfs2.provider.ftp.FtpFileSystemConfigBuilder;
025
026/**
027 * The configuration builder for various FTPS configuration options.
028 *
029 * @since 2.0
030 */
031public final class FtpsFileSystemConfigBuilder extends FtpFileSystemConfigBuilder {
032
033    private static final String PREFIX = FtpsFileSystemConfigBuilder.class.getName();
034
035    private static final FtpsFileSystemConfigBuilder BUILDER = new FtpsFileSystemConfigBuilder();
036
037    private static final String FTPS_MODE = PREFIX + ".FTPS_MODE";
038    private static final String PROT = PREFIX + ".PROT";
039    private static final String KEY_MANAGER = PREFIX + ".KEY_MANAGER";
040    private static final String TRUST_MANAGER = PREFIX + ".TRUST_MANAGER";
041
042    /**
043     * Gets the singleton builder.
044     *
045     * @return the singleton builder.
046     */
047    public static FtpsFileSystemConfigBuilder getInstance() {
048        return BUILDER;
049    }
050
051    private FtpsFileSystemConfigBuilder() {
052        super("ftps.");
053    }
054
055    /**
056     * Gets the data channel protection level (PROT).
057     *
058     * @param opts The FileSystemOptions.
059     * @return The PROT value.
060     * @see org.apache.commons.net.ftp.FTPSClient#execPROT(String)
061     * @since 2.1
062     */
063    public FtpsDataChannelProtectionLevel getDataChannelProtectionLevel(final FileSystemOptions opts) {
064        return getEnum(FtpsDataChannelProtectionLevel.class, opts, PROT);
065    }
066
067    /**
068     * Returns the FTPS mode. Defaults to "explicit" if not defined.
069     *
070     * @param opts The FileSystemOptions.
071     * @return The file type.
072     * @see #setFtpsType
073     */
074    public FtpsMode getFtpsMode(final FileSystemOptions opts) {
075        return getEnum(FtpsMode.class, opts, FTPS_MODE, FtpsMode.EXPLICIT);
076    }
077
078    /**
079     * Returns the FTPS type. Defaults to "explicit" if not defined.
080     *
081     * @param opts The FileSystemOptions.
082     * @return The file type.
083     * @see #setFtpsType
084     * @deprecated As of 2.1, use {@link #getFtpsMode(FileSystemOptions)}
085     */
086    @Deprecated
087    public String getFtpsType(final FileSystemOptions opts) {
088        return getFtpsMode(opts).name().toLowerCase();
089    }
090
091    /**
092     * Gets the KeyManager used to provide a client-side certificate if the FTPS server requests it.
093     *
094     * @param opts The FileSystemOptions.
095     * @return the key manager instance or {@code null}
096     * @see org.apache.commons.net.ftp.FTPSClient#setKeyManager(KeyManager)
097     * @since 2.1
098     */
099    public KeyManager getKeyManager(final FileSystemOptions opts) {
100        return getParam(opts, KEY_MANAGER);
101    }
102
103    /**
104     * Gets the TrustManager that validates the FTPS server's certificate.
105     * <p>
106     * If the params do not contain the key for the trust manager, it will return a trust manger that simply checks this
107     * certificate for validity.
108     * </p>
109     *
110     * @param opts The FileSystemOptions.
111     * @return the trust manager instance or {@code null}
112     * @see org.apache.commons.net.ftp.FTPSClient#setTrustManager(TrustManager)
113     * @since 2.1
114     */
115    public TrustManager getTrustManager(final FileSystemOptions opts) {
116        final TrustManager trustManager;
117        if (hasParam(opts, TRUST_MANAGER)) {
118            trustManager = getParam(opts, TRUST_MANAGER);
119        } else {
120            trustManager = TrustManagerUtils.getValidateServerCertificateTrustManager();
121        }
122        return trustManager;
123    }
124
125    /**
126     * Sets the data channel protection level (PROT).
127     *
128     * @param opts The FileSystemOptions.
129     * @param prot The PROT value, {@code null} has no effect.
130     * @see org.apache.commons.net.ftp.FTPSClient#execPROT(String)
131     * @since 2.1
132     */
133    public void setDataChannelProtectionLevel(final FileSystemOptions opts, final FtpsDataChannelProtectionLevel prot) {
134        setParam(opts, PROT, prot);
135    }
136
137    /**
138     * Sets FTPS mode, either "implicit" or "explicit".
139     *
140     * <p>
141     * Note, that implicit mode is not standardized and considered as deprecated. Some unit tests for VFS fail with
142     * implicit mode and it is not yet clear if its a problem with Commons VFS/Commons Net or our test server Apache
143     * FTP/SSHD.
144     * </p>
145     *
146     * @param opts The FileSystemOptions.
147     * @param ftpsMode The mode to establish a FTPS connection.
148     * @see <a href="https://en.wikipedia.org/wiki/FTPS#Implicit">Wikipedia: FTPS/Implicit</a>
149     * @since 2.1
150     */
151    public void setFtpsMode(final FileSystemOptions opts, final FtpsMode ftpsMode) {
152        setParam(opts, FTPS_MODE, ftpsMode);
153    }
154
155    /**
156     * Sets FTPS type, either "implicit" or "explicit".
157     * <p>
158     * Note, that implicit mode is not standardized and considered as deprecated. Some unit tests for VFS fail with
159     * implicit mode and it is not yet clear if its a problem with Commons VFS/Commons Net or our test server Apache
160     * FTP/SSHD.
161     * </p>
162     *
163     * @param opts The FileSystemOptions.
164     * @param ftpsType The file type.
165     * @see <a href="https://en.wikipedia.org/wiki/FTPS#Implicit">Wikipedia: FTPS/Implicit</a>
166     * @deprecated As of 2.1, use {@link #setFtpsMode(FileSystemOptions, FtpsMode)}
167     */
168    @Deprecated
169    public void setFtpsType(final FileSystemOptions opts, final String ftpsType) {
170        final FtpsMode mode;
171        if (ftpsType != null) {
172            mode = FtpsMode.valueOf(ftpsType.toUpperCase());
173        } else {
174            mode = null;
175        }
176        setFtpsMode(opts, mode);
177    }
178
179    /**
180     * Sets the KeyManager used to provide a client-side certificate if the FTPS server requests it.
181     *
182     * @param opts The FileSystemOptions.
183     * @param keyManager The key manager instance.
184     * @see org.apache.commons.net.ftp.FTPSClient#setKeyManager(KeyManager)
185     * @since 2.1
186     */
187    public void setKeyManager(final FileSystemOptions opts, final KeyManager keyManager) {
188        setParam(opts, KEY_MANAGER, keyManager);
189    }
190
191    /**
192     * Sets the TrustManager that validates the FTPS server's certificate.
193     *
194     * @param opts The FileSystemOptions.
195     * @param trustManager The trust manager instance.
196     * @see org.apache.commons.net.ftp.FTPSClient#setTrustManager(TrustManager)
197     * @since 2.1
198     */
199    public void setTrustManager(final FileSystemOptions opts, final TrustManager trustManager) {
200        setParam(opts, TRUST_MANAGER, trustManager);
201    }
202}