View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.vfs2.provider.ftps;
18  
19  import javax.net.ssl.KeyManager;
20  import javax.net.ssl.TrustManager;
21  
22  import org.apache.commons.net.util.TrustManagerUtils;
23  import org.apache.commons.vfs2.FileSystemOptions;
24  import org.apache.commons.vfs2.provider.ftp.FtpFileSystemConfigBuilder;
25  
26  /**
27   * The configuration builder for various FTPS configuration options.
28   *
29   * @since 2.0
30   */
31  public final class FtpsFileSystemConfigBuilder extends FtpFileSystemConfigBuilder {
32  
33      private static final String PREFIX = FtpsFileSystemConfigBuilder.class.getName();
34  
35      private static final FtpsFileSystemConfigBuilder BUILDER = new FtpsFileSystemConfigBuilder();
36  
37      private static final String FTPS_MODE = PREFIX + ".FTPS_MODE";
38      private static final String PROT = PREFIX + ".PROT";
39      private static final String KEY_MANAGER = PREFIX + ".KEY_MANAGER";
40      private static final String TRUST_MANAGER = PREFIX + ".TRUST_MANAGER";
41  
42      /**
43       * Gets the singleton builder.
44       *
45       * @return the singleton builder.
46       */
47      public static FtpsFileSystemConfigBuilder getInstance() {
48          return BUILDER;
49      }
50  
51      private FtpsFileSystemConfigBuilder() {
52          super("ftps.");
53      }
54  
55      /**
56       * Gets the data channel protection level (PROT).
57       *
58       * @param opts The FileSystemOptions.
59       * @return The PROT value.
60       * @see org.apache.commons.net.ftp.FTPSClient#execPROT(String)
61       * @since 2.1
62       */
63      public FtpsDataChannelProtectionLevel getDataChannelProtectionLevel(final FileSystemOptions opts) {
64          return getEnum(FtpsDataChannelProtectionLevel.class, opts, PROT);
65      }
66  
67      /**
68       * Returns the FTPS mode. Defaults to "explicit" if not defined.
69       *
70       * @param opts The FileSystemOptions.
71       * @return The file type.
72       * @see #setFtpsType
73       */
74      public FtpsMode getFtpsMode(final FileSystemOptions opts) {
75          return getEnum(FtpsMode.class, opts, FTPS_MODE, FtpsMode.EXPLICIT);
76      }
77  
78      /**
79       * Returns the FTPS type. Defaults to "explicit" if not defined.
80       *
81       * @param opts The FileSystemOptions.
82       * @return The file type.
83       * @see #setFtpsType
84       * @deprecated As of 2.1, use {@link #getFtpsMode(FileSystemOptions)}
85       */
86      @Deprecated
87      public String getFtpsType(final FileSystemOptions opts) {
88          return getFtpsMode(opts).name().toLowerCase();
89      }
90  
91      /**
92       * Gets the KeyManager used to provide a client-side certificate if the FTPS server requests it.
93       *
94       * @param opts The FileSystemOptions.
95       * @return the key manager instance or {@code null}
96       * @see org.apache.commons.net.ftp.FTPSClient#setKeyManager(KeyManager)
97       * @since 2.1
98       */
99      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 }