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: */
017:
018: package org.apache.tomcat.jni;
019:
020: /** SSL Context
021: *
022: * @author Mladen Turk
023: * @version $Revision: 467222 $, $Date: 2006-10-24 05:17:11 +0200 (mar., 24 oct. 2006) $
024: */
025:
026: public final class SSLContext {
027:
028: /**
029: * Initialize new SSL context
030: * @param pool The pool to use.
031: * @param protocol The SSL protocol to use. It can be one of:
032: * <PRE>
033: * SSL_PROTOCOL_SSLV2
034: * SSL_PROTOCOL_SSLV3
035: * SSL_PROTOCOL_SSLV2 | SSL_PROTOCOL_SSLV3
036: * SSL_PROTOCOL_TLSV1
037: * SSL_PROTOCOL_ALL
038: * </PRE>
039: * @param mode SSL mode to use
040: * <PRE>
041: * SSL_MODE_CLIENT
042: * SSL_MODE_SERVER
043: * SSL_MODE_COMBINED
044: * </PRE>
045: */
046: public static native long make(long pool, int protocol, int mode)
047: throws Exception;
048:
049: /**
050: * Free the resources used by the Context
051: * @param ctx Server or Client context to free.
052: * @return APR Status code.
053: */
054: public static native int free(long ctx);
055:
056: /**
057: * Set Session context id. Usually host:port combination.
058: * @param ctx Context to use.
059: * @param id String that uniquely identifies this context.
060: */
061: public static native void setContextId(long ctx, String id);
062:
063: /**
064: * Asssociate BIOCallback for input or output data capture.
065: * <br />
066: * First word in the output string will contain error
067: * level in the form:
068: * <PRE>
069: * [ERROR] -- Critical error messages
070: * [WARN] -- Varning messages
071: * [INFO] -- Informational messages
072: * [DEBUG] -- Debugging messaged
073: * </PRE>
074: * Callback can use that word to determine application logging level
075: * by intercepting <b>write</b> call.
076: * If the <b>bio</b> is set to 0 no error messages will be displayed.
077: * Default is to use the stderr output stream.
078: * @param ctx Server or Client context to use.
079: * @param bio BIO handle to use, created with SSL.newBIO
080: * @param dir BIO direction (1 for input 0 for output).
081: */
082: public static native void setBIO(long ctx, long bio, int dir);
083:
084: /**
085: * Set OpenSSL Option.
086: * @param ctx Server or Client context to use.
087: * @param options See SSL.SSL_OP_* for option flags.
088: */
089: public static native void setOptions(long ctx, int options);
090:
091: /**
092: * Sets the "quiet shutdown" flag for <b>ctx</b> to be
093: * <b>mode</b>. SSL objects created from <b>ctx</b> inherit the
094: * <b>mode</b> valid at the time and may be 0 or 1.
095: * <br />
096: * Normally when a SSL connection is finished, the parties must send out
097: * "close notify" alert messages using L<SSL_shutdown(3)|SSL_shutdown(3)>
098: * for a clean shutdown.
099: * <br />
100: * When setting the "quiet shutdown" flag to 1, <b>SSL.shutdown</b>
101: * will set the internal flags to SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN.
102: * (<b>SSL_shutdown</b> then behaves like called with
103: * SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN.)
104: * The session is thus considered to be shutdown, but no "close notify" alert
105: * is sent to the peer. This behaviour violates the TLS standard.
106: * The default is normal shutdown behaviour as described by the TLS standard.
107: * @param ctx Server or Client context to use.
108: * @param mode True to set the quiet shutdown.
109: */
110: public static native void setQuietShutdown(long ctx, boolean mode);
111:
112: /**
113: * Cipher Suite available for negotiation in SSL handshake.
114: * <br />
115: * This complex directive uses a colon-separated cipher-spec string consisting
116: * of OpenSSL cipher specifications to configure the Cipher Suite the client
117: * is permitted to negotiate in the SSL handshake phase. Notice that this
118: * directive can be used both in per-server and per-directory context.
119: * In per-server context it applies to the standard SSL handshake when a
120: * connection is established. In per-directory context it forces a SSL
121: * renegotation with the reconfigured Cipher Suite after the HTTP request
122: * was read but before the HTTP response is sent.
123: * @param ctx Server or Client context to use.
124: * @param ciphers An SSL cipher specification.
125: */
126: public static native boolean setCipherSuite(long ctx, String ciphers)
127: throws Exception;
128:
129: /**
130: * Set File of concatenated PEM-encoded CA CRLs or
131: * directory of PEM-encoded CA Certificates for Client Auth
132: * <br />
133: * This directive sets the all-in-one file where you can assemble the
134: * Certificate Revocation Lists (CRL) of Certification Authorities (CA)
135: * whose clients you deal with. These are used for Client Authentication.
136: * Such a file is simply the concatenation of the various PEM-encoded CRL
137: * files, in order of preference.
138: * <br />
139: * The files in this directory have to be PEM-encoded and are accessed through
140: * hash filenames. So usually you can't just place the Certificate files there:
141: * you also have to create symbolic links named hash-value.N. And you should
142: * always make sure this directory contains the appropriate symbolic links.
143: * Use the Makefile which comes with mod_ssl to accomplish this task.
144: * @param ctx Server or Client context to use.
145: * @param file File of concatenated PEM-encoded CA CRLs for Client Auth.
146: * @param path Directory of PEM-encoded CA Certificates for Client Auth.
147: */
148: public static native boolean setCARevocation(long ctx, String file,
149: String path) throws Exception;
150:
151: /**
152: * Set File of PEM-encoded Server CA Certificates
153: * <br />
154: * This directive sets the optional all-in-one file where you can assemble the
155: * certificates of Certification Authorities (CA) which form the certificate
156: * chain of the server certificate. This starts with the issuing CA certificate
157: * of of the server certificate and can range up to the root CA certificate.
158: * Such a file is simply the concatenation of the various PEM-encoded CA
159: * Certificate files, usually in certificate chain order.
160: * <br />
161: * But be careful: Providing the certificate chain works only if you are using
162: * a single (either RSA or DSA) based server certificate. If you are using a
163: * coupled RSA+DSA certificate pair, this will work only if actually both
164: * certificates use the same certificate chain. Else the browsers will be
165: * confused in this situation.
166: * @param ctx Server or Client context to use.
167: * @param file File of PEM-encoded Server CA Certificates.
168: * @param skipfirst Skip first certificate if chain file is inside
169: * certificate file.
170: */
171: public static native boolean setCertificateChainFile(long ctx,
172: String file, boolean skipfirst);
173:
174: /**
175: * Set Certificate
176: * <br />
177: * Point setCertificateFile at a PEM encoded certificate. If
178: * the certificate is encrypted, then you will be prompted for a
179: * pass phrase. Note that a kill -HUP will prompt again. A test
180: * certificate can be generated with `make certificate' under
181: * built time. Keep in mind that if you've both a RSA and a DSA
182: * certificate you can configure both in parallel (to also allow
183: * the use of DSA ciphers, etc.)
184: * <br />
185: * If the key is not combined with the certificate, use key param
186: * to point at the key file. Keep in mind that if
187: * you've both a RSA and a DSA private key you can configure
188: * both in parallel (to also allow the use of DSA ciphers, etc.)
189: * @param ctx Server or Client context to use.
190: * @param cert Certificate file.
191: * @param key Private Key file to use if not in cert.
192: * @param password Certificate password. If null and certificate
193: * is encrypted, password prompt will be dispayed.
194: * @param idx Certificate index SSL_AIDX_RSA or SSL_AIDX_DSA.
195: */
196: public static native boolean setCertificate(long ctx, String cert,
197: String key, String password, int idx) throws Exception;
198:
199: /**
200: * Set File and Directory of concatenated PEM-encoded CA Certificates
201: * for Client Auth
202: * <br />
203: * This directive sets the all-in-one file where you can assemble the
204: * Certificates of Certification Authorities (CA) whose clients you deal with.
205: * These are used for Client Authentication. Such a file is simply the
206: * concatenation of the various PEM-encoded Certificate files, in order of
207: * preference. This can be used alternatively and/or additionally to
208: * path.
209: * <br />
210: * The files in this directory have to be PEM-encoded and are accessed through
211: * hash filenames. So usually you can't just place the Certificate files there:
212: * you also have to create symbolic links named hash-value.N. And you should
213: * always make sure this directory contains the appropriate symbolic links.
214: * Use the Makefile which comes with mod_ssl to accomplish this task.
215: * @param ctx Server or Client context to use.
216: * @param file File of concatenated PEM-encoded CA Certificates for
217: * Client Auth.
218: * @param path Directory of PEM-encoded CA Certificates for Client Auth.
219: */
220: public static native boolean setCACertificate(long ctx,
221: String file, String path) throws Exception;
222:
223: /**
224: * Set SSL connection shutdown type
225: * <br />
226: * The following levels are available for level:
227: * <PRE>
228: * SSL_SHUTDOWN_TYPE_STANDARD
229: * SSL_SHUTDOWN_TYPE_UNCLEAN
230: * SSL_SHUTDOWN_TYPE_ACCURATE
231: * </PRE>
232: * @param ctx Server or Client context to use.
233: * @param type Shutdown type to use.
234: */
235: public static native void setShutdowType(long ctx, int type);
236:
237: /**
238: * Set Type of Client Certificate verification and Maximum depth of CA Certificates
239: * in Client Certificate verification.
240: * <br />
241: * This directive sets the Certificate verification level for the Client
242: * Authentication. Notice that this directive can be used both in per-server
243: * and per-directory context. In per-server context it applies to the client
244: * authentication process used in the standard SSL handshake when a connection
245: * is established. In per-directory context it forces a SSL renegotation with
246: * the reconfigured client verification level after the HTTP request was read
247: * but before the HTTP response is sent.
248: * <br />
249: * The following levels are available for level:
250: * <PRE>
251: * SSL_CVERIFY_NONE - No client Certificate is required at all
252: * SSL_CVERIFY_OPTIONAL - The client may present a valid Certificate
253: * SSL_CVERIFY_REQUIRE - The client has to present a valid Certificate
254: * SSL_CVERIFY_OPTIONAL_NO_CA - The client may present a valid Certificate
255: * but it need not to be (successfully) verifiable
256: * </PRE>
257: * <br />
258: * The depth actually is the maximum number of intermediate certificate issuers,
259: * i.e. the number of CA certificates which are max allowed to be followed while
260: * verifying the client certificate. A depth of 0 means that self-signed client
261: * certificates are accepted only, the default depth of 1 means the client
262: * certificate can be self-signed or has to be signed by a CA which is directly
263: * known to the server (i.e. the CA's certificate is under
264: * <code>setCACertificatePath</code>), etc.
265: * @param ctx Server or Client context to use.
266: * @param level Type of Client Certificate verification.
267: * @param depth Maximum depth of CA Certificates in Client Certificate
268: * verification.
269: */
270: public static native void setVerify(long ctx, int level, int depth);
271:
272: }
|