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