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      private FtpsFileSystemConfigBuilder()
43      {
44          super("ftps.");
45      }
46  
47      /**
48       * Gets the singleton builder.
49       *
50       * @return the singleton builder.
51       */
52      public static FtpsFileSystemConfigBuilder getInstance()
53      {
54          return BUILDER;
55      }
56  
57      /**
58       * Set FTPS mode, either "implicit" or "explicit".
59       *
60       * <p>Note, that implicit mode is not standardized and considered as deprecated. Some unit tests for VFS fail with
61       * implicit mode and it is not yet clear if its a problem with Commons VFS/Commons Net or our test server Apache
62       * FTP/SSHD.</p>
63       *
64       * @param opts The FileSystemOptions.
65       * @param ftpsMode The mode to establish a FTPS connection.
66       * @see <a href="http://en.wikipedia.org/wiki/FTPS#Implicit">Wikipedia: FTPS/Implicit</a>
67       * @since 2.1
68       */
69      public void setFtpsMode(final FileSystemOptions opts, final FtpsMode ftpsMode)
70      {
71          setParam(opts, FTPS_MODE, ftpsMode);
72      }
73  
74      /**
75       * Return the FTPS mode. Defaults to "explicit" if not defined.
76       *
77       * @param opts The FileSystemOptions.
78       * @return The file type.
79       * @see #setFtpsType
80       */
81      public FtpsMode getFtpsMode(final FileSystemOptions opts)
82      {
83          return getEnum(FtpsMode.class, opts, FTPS_MODE, FtpsMode.EXPLICIT);
84      }
85  
86      /**
87       * Set FTPS type, either "implicit" or "explicit".
88       * <p>
89       * Note, that implicit mode is not standardized and considered as deprecated. Some unit tests for VFS fail with
90       * implicit mode and it is not yet clear if its a problem with Commons VFS/Commons Net or our test server Apache
91       * FTP/SSHD.
92       * </p>
93       *
94       * @param opts The FileSystemOptions.
95       * @param ftpsType The file type.
96       * @see <a href="http://en.wikipedia.org/wiki/FTPS#Implicit">Wikipedia: FTPS/Implicit</a>
97       * @deprecated As of 2.1, use {@link #setFtpsMode(FileSystemOptions, FtpsMode)}
98       */
99      @Deprecated
100     public void setFtpsType(final FileSystemOptions opts, final String ftpsType)
101     {
102         final FtpsMode mode;
103         if (ftpsType != null)
104         {
105             mode = FtpsMode.valueOf(ftpsType.toUpperCase());
106             if (mode == null)
107             {
108                 throw new IllegalArgumentException("Not a proper FTPS mode: " + ftpsType);
109             }
110         }
111         else
112         {
113             mode = null;
114         }
115         setFtpsMode(opts, mode);
116     }
117 
118     /**
119      * Return the FTPS type. Defaults to "explicit" if not defined.
120      *
121      * @param opts The FileSystemOptions.
122      * @return The file type.
123      * @see #setFtpsType
124      * @deprecated As of 2.1, use {@link #getFtpsMode(FileSystemOptions)}
125      */
126     @Deprecated
127     public String getFtpsType(final FileSystemOptions opts)
128     {
129         return getFtpsMode(opts).name().toLowerCase();
130     }
131 
132     /**
133      * Gets the data channel protection level (PROT).
134      *
135      * @param opts The FileSystemOptions.
136      * @return The PROT value.
137      * @see org.apache.commons.net.ftp.FTPSClient#execPROT(String)
138      * @since 2.1
139      */
140     public FtpsDataChannelProtectionLevel getDataChannelProtectionLevel(final FileSystemOptions opts)
141     {
142         return getEnum(FtpsDataChannelProtectionLevel.class, opts, PROT);
143     }
144 
145     /**
146      * Sets the data channel protection level (PROT).
147      *
148      * @param opts The FileSystemOptions.
149      * @param prot The PROT value, {@code null} has no effect.
150      * @see org.apache.commons.net.ftp.FTPSClient#execPROT(String)
151      * @since 2.1
152      */
153     public void setDataChannelProtectionLevel(final FileSystemOptions opts, final FtpsDataChannelProtectionLevel prot)
154     {
155         setParam(opts, PROT, prot);
156     }
157 
158     /**
159      * Gets the KeyManager used to provide a client-side certificate if the FTPS server requests it.
160      *
161      * @param opts The FileSystemOptions.
162      * @return the key manager instance or {@code null}
163      * @see org.apache.commons.net.ftp.FTPSClient#setKeyManager(KeyManager)
164      * @since 2.1
165      */
166     public KeyManager getKeyManager(final FileSystemOptions opts)
167     {
168         return (KeyManager) getParam(opts, KEY_MANAGER);
169     }
170 
171     /**
172      * Sets the KeyManager used to provide a client-side certificate if the FTPS server requests it.
173      *
174      * @param opts The FileSystemOptions.
175      * @param keyManager The key manager instance.
176      * @see org.apache.commons.net.ftp.FTPSClient#setKeyManager(KeyManager)
177      * @since 2.1
178      */
179     public void setKeyManager(final FileSystemOptions opts, final KeyManager keyManager)
180     {
181         setParam(opts, KEY_MANAGER, keyManager);
182     }
183 
184     /**
185      * Gets the TrustManager that validates the FTPS server's certificate.
186      * <p>
187      * If the params do not contain the key for the trust manager, it will return a trust manger that simply checks this
188      * certificate for validity.
189      * </p>
190      *
191      * @param opts The FileSystemOptions.
192      * @return the trust manager instance or {@code null}
193      * @see org.apache.commons.net.ftp.FTPSClient#setTrustManager(TrustManager)
194      * @since 2.1
195      */
196     public TrustManager getTrustManager(final FileSystemOptions opts)
197     {
198         final TrustManager trustManager;
199         if (hasParam(opts, TRUST_MANAGER))
200         {
201             trustManager = (TrustManager) getParam(opts, TRUST_MANAGER);
202         }
203         else
204         {
205             trustManager = TrustManagerUtils.getValidateServerCertificateTrustManager();
206         }
207         return trustManager;
208     }
209 
210     /**
211      * Sets the TrustManager that validates the FTPS server's certificate.
212      *
213      * @param opts The FileSystemOptions.
214      * @param trustManager The trust manager instance.
215      * @see org.apache.commons.net.ftp.FTPSClient#setTrustManager(TrustManager)
216      * @since 2.1
217      */
218     public void setTrustManager(final FileSystemOptions opts, final TrustManager trustManager)
219     {
220         setParam(opts, TRUST_MANAGER, trustManager);
221     }
222 }