001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package javax.microedition.io;
028:
029: import java.lang.String;
030: import java.lang.IllegalArgumentException;
031: import java.io.IOException;
032: import javax.microedition.pki.CertificateException;
033:
034: /**
035: * This interface defines the secure socket stream connection.
036: * A secure connection is established using
037: * <CODE>Connector.open</CODE> with the scheme "ssl" and the secure
038: * connection is established before <CODE>open</CODE> returns.
039: * If the secure connection cannot be established due to errors
040: * related to certificates a <CODE>CertificateException</CODE> is thrown.
041: *
042: * <P>
043: * A secure socket is accessed using a generic connection string
044: * with an explicit host and port number. The host may be specified
045: * as a fully qualified host name or
046: * IPv4 number.
047: * e.g. <code>ssl://host.com:79</code> defines a target socket on the
048: * <code>host.com</code> system at
049: * port <code>79</code>.
050: * <P>Note that
051: * RFC1900 recommends the use of names rather than IP numbers for best results
052: * in the event of IP number reassignment. </P>
053: * <P>
054: * A secure connection MUST be implemented by one or more
055: * of the following specifications:
056: * <UL>
057: * <LI>TLS Protocol Version 1.0 as specified in
058: * <A HREF="http://www.ietf.org/rfc/rfc2246.txt">RFC 2246</A>.
059: * </LI>
060: *
061: * <LI>SSL V3 as specified in
062: * <A HREF="http://home.netscape.com/eng/ssl3/draft302.txt">
063: * The SSL Protocol Version 3.0</A>
064: * </LI>
065: *
066: * <LI>WAP(TM) TLS Profile and Tunneling Specification as specified
067: * in <A HREF="http://www.wapforum.com/what/technical.htm">
068: * WAP-219-TLS-20010411-a</A>
069: * </LI>
070: * </UL>
071: *
072: * <H2>
073: * BNF Format for Connector.open() string
074: * </H2>
075: * <P>
076: * The URI must conform to the BNF syntax specified below. If the URI
077: * does not conform to this syntax, an <code>IllegalArgumentException</code>
078: * is thrown.
079: * </P>
080: * <TABLE BORDER="1">
081: * <TR>
082: * <TD><socket_connection_string> </TD>
083: * <TD>::= "<strong>ssl://</strong>"<hostport> </TD>
084: * </TR>
085: * <TR>
086: * <TD><hostport> </TD>
087: * <TD>::= <I>host</I> ":" <I>port </I> </TD>
088: * </TR>
089: * <TR>
090: * <TD><host> </TD>
091: * <TD>::= <I>host name or IP address </I>
092: * </TD>
093: * </TR>
094: * <TR>
095: * <TD><port> </TD>
096: * <TD>::= <I>numeric port number </I> </TD>
097: * </TR>
098: * </TABLE>
099: *
100: * <H2>
101: * Examples
102: * </H2>
103: * <P>
104: * The following examples show how a <code>SecureConnection</code>
105: * would be used to access a sample loopback program.
106: * </P>
107: * <PRE>
108: * SecureConnection sc = (SecureConnection)
109: * Connector.open("ssl://host.com:79");
110: * SecurityInfo info = sc.getSecurityInfo();
111: * boolean isTLS = (info.getProtocolName().equals("TLS"));
112: *
113: * sc.setSocketOption(SocketConnection.LINGER, 5);
114: *
115: * InputStream is = sc.openInputStream();
116: * OutputStream os = sc.openOutputStream();
117: *
118: * os.write("\r\n".getBytes());
119: * int ch = 0;
120: * while(ch != -1) {
121: * ch = is.read();
122: * }
123: *
124: * is.close();
125: * os.close();
126: * sc.close();
127: * </PRE>
128: *
129: */
130: public interface SecureConnection extends SocketConnection {
131: /**
132: * Return the security information associated with this connection
133: * when it was opened.
134: *
135: * @return the security information associated with this open connection.
136: * @exception IOException if an arbitrary connection failure occurs
137: */
138: public SecurityInfo getSecurityInfo() throws IOException;
139: }
|