194 * maximum record that can be produced. Calls to {@link
195 * SSLSession#getPacketBufferSize()} and {@link
196 * SSLSession#getApplicationBufferSize()} should be used to determine
197 * the appropriate buffer sizes. The size of the outbound application
198 * data buffer generally does not matter. If buffer conditions do not
199 * allow for the proper consumption/production of data, the application
200 * must determine (via {@link SSLEngineResult}) and correct the
201 * problem, and then try the call again.
202 * <P>
203 * For example, <code>unwrap()</code> will return a {@link
204 * SSLEngineResult.Status#BUFFER_OVERFLOW} result if the engine
205 * determines that there is not enough destination buffer space available.
206 * Applications should call {@link SSLSession#getApplicationBufferSize()}
207 * and compare that value with the space available in the destination buffer,
208 * enlarging the buffer if necessary. Similarly, if <code>unwrap()</code>
209 * were to return a {@link SSLEngineResult.Status#BUFFER_UNDERFLOW}, the
210 * application should call {@link SSLSession#getPacketBufferSize()} to ensure
211 * that the source buffer has enough room to hold a record (enlarging if
212 * necessary), and then obtain more inbound data.
213 *
214 * <pre>
215 * SSLEngineResult r = engine.unwrap(src, dst);
216 * switch (r.getStatus()) {
217 * BUFFER_OVERFLOW:
218 * // Could attempt to drain the dst buffer of any already obtained
219 * // data, but we'll just increase it to the size needed.
220 * int appSize = engine.getSession().getApplicationBufferSize();
221 * ByteBuffer b = ByteBuffer.allocate(appSize + dst.position());
222 * dst.flip();
223 * b.put(dst);
224 * dst = b;
225 * // retry the operation.
226 * break;
227 * BUFFER_UNDERFLOW:
228 * int netSize = engine.getSession().getPacketBufferSize();
229 * // Resize buffer if needed.
230 * if (netSize > dst.capacity()) {
231 * ByteBuffer b = ByteBuffer.allocate(netSize);
232 * src.flip();
233 * b.put(src);
234 * src = b;
235 * }
236 * // Obtain more inbound network data for src,
237 * // then retry the operation.
238 * break;
239 * // other cases: CLOSED, OK.
240 * }
241 * </pre>
242 *
243 * <P>
244 * Unlike <code>SSLSocket</code>, all methods of SSLEngine are
245 * non-blocking. <code>SSLEngine</code> implementations may
246 * require the results of tasks that may take an extended period of
247 * time to complete, or may even block. For example, a TrustManager
248 * may need to connect to a remote certificate validation service,
249 * or a KeyManager might need to prompt a user to determine which
250 * certificate to use as part of client authentication. Additionally,
251 * creating cryptographic signatures and verifying them can be slow,
252 * seemingly blocking.
253 * <P>
254 * For any operation which may potentially block, the
255 * <code>SSLEngine</code> will create a {@link java.lang.Runnable}
256 * delegated task. When <code>SSLEngineResult</code> indicates that a
257 * delegated task result is needed, the application must call {@link
258 * #getDelegatedTask()} to obtain an outstanding delegated task and
259 * call its {@link java.lang.Runnable#run() run()} method (possibly using
260 * a different thread depending on the compute strategy). The
261 * application should continue obtaining delegated tasks until no more
425 * <P>
426 * Note that the value is not authenticated, and should not be
427 * relied upon.
428 *
429 * @return the port number of the peer, or -1 if nothing is
430 * available.
431 */
432 public int getPeerPort() {
433 return peerPort;
434 }
435
436 /**
437 * Attempts to encode a buffer of plaintext application data into
438 * SSL/TLS network data.
439 * <P>
440 * An invocation of this method behaves in exactly the same manner
441 * as the invocation:
442 * <blockquote><pre>
443 * {@link #wrap(ByteBuffer [], int, int, ByteBuffer)
444 * engine.wrap(new ByteBuffer [] { src }, 0, 1, dst);}
445 * </pre</blockquote>
446 *
447 * @param src
448 * a <code>ByteBuffer</code> containing outbound application data
449 * @param dst
450 * a <code>ByteBuffer</code> to hold outbound network data
451 * @return an <code>SSLEngineResult</code> describing the result
452 * of this operation.
453 * @throws SSLException
454 * A problem was encountered while processing the
455 * data that caused the <code>SSLEngine</code> to abort.
456 * See the class description for more information on
457 * engine closure.
458 * @throws ReadOnlyBufferException
459 * if the <code>dst</code> buffer is read-only.
460 * @throws IllegalArgumentException
461 * if either <code>src</code> or <code>dst</code>
462 * is null.
463 * @throws IllegalStateException if the client/server mode
464 * has not yet been set.
465 * @see #wrap(ByteBuffer [], int, int, ByteBuffer)
466 */
467 public SSLEngineResult wrap(ByteBuffer src,
468 ByteBuffer dst) throws SSLException {
469 return wrap(new ByteBuffer [] { src }, 0, 1, dst);
470 }
471
472 /**
473 * Attempts to encode plaintext bytes from a sequence of data
474 * buffers into SSL/TLS network data.
475 * <P>
476 * An invocation of this method behaves in exactly the same manner
477 * as the invocation:
478 * <blockquote><pre>
479 * {@link #wrap(ByteBuffer [], int, int, ByteBuffer)
480 * engine.wrap(srcs, 0, srcs.length, dst);}
481 * </pre</blockquote>
482 *
483 * @param srcs
484 * an array of <code>ByteBuffers</code> containing the
485 * outbound application data
486 * @param dst
487 * a <code>ByteBuffer</code> to hold outbound network data
488 * @return an <code>SSLEngineResult</code> describing the result
489 * of this operation.
490 * @throws SSLException
491 * A problem was encountered while processing the
492 * data that caused the <code>SSLEngine</code> to abort.
493 * See the class description for more information on
494 * engine closure.
495 * @throws ReadOnlyBufferException
496 * if the <code>dst</code> buffer is read-only.
497 * @throws IllegalArgumentException
498 * if either <code>srcs</code> or <code>dst</code>
499 * is null, or if any element in <code>srcs</code> is null.
500 * @throws IllegalStateException if the client/server mode
501 * has not yet been set.
580 * is null, or if any element in the <code>srcs</code>
581 * subsequence specified is null.
582 * @throws IllegalStateException if the client/server mode
583 * has not yet been set.
584 * @see java.nio.channels.GatheringByteChannel
585 * @see java.nio.channels.GatheringByteChannel#write(
586 * ByteBuffer[], int, int)
587 */
588 public abstract SSLEngineResult wrap(ByteBuffer [] srcs, int offset,
589 int length, ByteBuffer dst) throws SSLException;
590
591 /**
592 * Attempts to decode SSL/TLS network data into a plaintext
593 * application data buffer.
594 * <P>
595 * An invocation of this method behaves in exactly the same manner
596 * as the invocation:
597 * <blockquote><pre>
598 * {@link #unwrap(ByteBuffer, ByteBuffer [], int, int)
599 * engine.unwrap(src, new ByteBuffer [] { dst }, 0, 1);}
600 * </pre</blockquote>
601 *
602 * @param src
603 * a <code>ByteBuffer</code> containing inbound network data.
604 * @param dst
605 * a <code>ByteBuffer</code> to hold inbound application data.
606 * @return an <code>SSLEngineResult</code> describing the result
607 * of this operation.
608 * @throws SSLException
609 * A problem was encountered while processing the
610 * data that caused the <code>SSLEngine</code> to abort.
611 * See the class description for more information on
612 * engine closure.
613 * @throws ReadOnlyBufferException
614 * if the <code>dst</code> buffer is read-only.
615 * @throws IllegalArgumentException
616 * if either <code>src</code> or <code>dst</code>
617 * is null.
618 * @throws IllegalStateException if the client/server mode
619 * has not yet been set.
620 * @see #unwrap(ByteBuffer, ByteBuffer [], int, int)
621 */
622 public SSLEngineResult unwrap(ByteBuffer src,
623 ByteBuffer dst) throws SSLException {
624 return unwrap(src, new ByteBuffer [] { dst }, 0, 1);
625 }
626
627 /**
628 * Attempts to decode SSL/TLS network data into a sequence of plaintext
629 * application data buffers.
630 * <P>
631 * An invocation of this method behaves in exactly the same manner
632 * as the invocation:
633 * <blockquote><pre>
634 * {@link #unwrap(ByteBuffer, ByteBuffer [], int, int)
635 * engine.unwrap(src, dsts, 0, dsts.length);}
636 * </pre</blockquote>
637 *
638 * @param src
639 * a <code>ByteBuffer</code> containing inbound network data.
640 * @param dsts
641 * an array of <code>ByteBuffer</code>s to hold inbound
642 * application data.
643 * @return an <code>SSLEngineResult</code> describing the result
644 * of this operation.
645 * @throws SSLException
646 * A problem was encountered while processing the
647 * data that caused the <code>SSLEngine</code> to abort.
648 * See the class description for more information on
649 * engine closure.
650 * @throws ReadOnlyBufferException
651 * if any of the <code>dst</code> buffers are read-only.
652 * @throws IllegalArgumentException
653 * if either <code>src</code> or <code>dsts</code>
654 * is null, or if any element in <code>dsts</code> is null.
655 * @throws IllegalStateException if the client/server mode
656 * has not yet been set.
|
194 * maximum record that can be produced. Calls to {@link
195 * SSLSession#getPacketBufferSize()} and {@link
196 * SSLSession#getApplicationBufferSize()} should be used to determine
197 * the appropriate buffer sizes. The size of the outbound application
198 * data buffer generally does not matter. If buffer conditions do not
199 * allow for the proper consumption/production of data, the application
200 * must determine (via {@link SSLEngineResult}) and correct the
201 * problem, and then try the call again.
202 * <P>
203 * For example, <code>unwrap()</code> will return a {@link
204 * SSLEngineResult.Status#BUFFER_OVERFLOW} result if the engine
205 * determines that there is not enough destination buffer space available.
206 * Applications should call {@link SSLSession#getApplicationBufferSize()}
207 * and compare that value with the space available in the destination buffer,
208 * enlarging the buffer if necessary. Similarly, if <code>unwrap()</code>
209 * were to return a {@link SSLEngineResult.Status#BUFFER_UNDERFLOW}, the
210 * application should call {@link SSLSession#getPacketBufferSize()} to ensure
211 * that the source buffer has enough room to hold a record (enlarging if
212 * necessary), and then obtain more inbound data.
213 *
214 * <pre>{@code
215 * SSLEngineResult r = engine.unwrap(src, dst);
216 * switch (r.getStatus()) {
217 * BUFFER_OVERFLOW:
218 * // Could attempt to drain the dst buffer of any already obtained
219 * // data, but we'll just increase it to the size needed.
220 * int appSize = engine.getSession().getApplicationBufferSize();
221 * ByteBuffer b = ByteBuffer.allocate(appSize + dst.position());
222 * dst.flip();
223 * b.put(dst);
224 * dst = b;
225 * // retry the operation.
226 * break;
227 * BUFFER_UNDERFLOW:
228 * int netSize = engine.getSession().getPacketBufferSize();
229 * // Resize buffer if needed.
230 * if (netSize > dst.capacity()) {
231 * ByteBuffer b = ByteBuffer.allocate(netSize);
232 * src.flip();
233 * b.put(src);
234 * src = b;
235 * }
236 * // Obtain more inbound network data for src,
237 * // then retry the operation.
238 * break;
239 * // other cases: CLOSED, OK.
240 * }
241 * }</pre>
242 *
243 * <P>
244 * Unlike <code>SSLSocket</code>, all methods of SSLEngine are
245 * non-blocking. <code>SSLEngine</code> implementations may
246 * require the results of tasks that may take an extended period of
247 * time to complete, or may even block. For example, a TrustManager
248 * may need to connect to a remote certificate validation service,
249 * or a KeyManager might need to prompt a user to determine which
250 * certificate to use as part of client authentication. Additionally,
251 * creating cryptographic signatures and verifying them can be slow,
252 * seemingly blocking.
253 * <P>
254 * For any operation which may potentially block, the
255 * <code>SSLEngine</code> will create a {@link java.lang.Runnable}
256 * delegated task. When <code>SSLEngineResult</code> indicates that a
257 * delegated task result is needed, the application must call {@link
258 * #getDelegatedTask()} to obtain an outstanding delegated task and
259 * call its {@link java.lang.Runnable#run() run()} method (possibly using
260 * a different thread depending on the compute strategy). The
261 * application should continue obtaining delegated tasks until no more
425 * <P>
426 * Note that the value is not authenticated, and should not be
427 * relied upon.
428 *
429 * @return the port number of the peer, or -1 if nothing is
430 * available.
431 */
432 public int getPeerPort() {
433 return peerPort;
434 }
435
436 /**
437 * Attempts to encode a buffer of plaintext application data into
438 * SSL/TLS network data.
439 * <P>
440 * An invocation of this method behaves in exactly the same manner
441 * as the invocation:
442 * <blockquote><pre>
443 * {@link #wrap(ByteBuffer [], int, int, ByteBuffer)
444 * engine.wrap(new ByteBuffer [] { src }, 0, 1, dst);}
445 * </pre></blockquote>
446 *
447 * @param src
448 * a <code>ByteBuffer</code> containing outbound application data
449 * @param dst
450 * a <code>ByteBuffer</code> to hold outbound network data
451 * @return an <code>SSLEngineResult</code> describing the result
452 * of this operation.
453 * @throws SSLException
454 * A problem was encountered while processing the
455 * data that caused the <code>SSLEngine</code> to abort.
456 * See the class description for more information on
457 * engine closure.
458 * @throws ReadOnlyBufferException
459 * if the <code>dst</code> buffer is read-only.
460 * @throws IllegalArgumentException
461 * if either <code>src</code> or <code>dst</code>
462 * is null.
463 * @throws IllegalStateException if the client/server mode
464 * has not yet been set.
465 * @see #wrap(ByteBuffer [], int, int, ByteBuffer)
466 */
467 public SSLEngineResult wrap(ByteBuffer src,
468 ByteBuffer dst) throws SSLException {
469 return wrap(new ByteBuffer [] { src }, 0, 1, dst);
470 }
471
472 /**
473 * Attempts to encode plaintext bytes from a sequence of data
474 * buffers into SSL/TLS network data.
475 * <P>
476 * An invocation of this method behaves in exactly the same manner
477 * as the invocation:
478 * <blockquote><pre>
479 * {@link #wrap(ByteBuffer [], int, int, ByteBuffer)
480 * engine.wrap(srcs, 0, srcs.length, dst);}
481 * </pre></blockquote>
482 *
483 * @param srcs
484 * an array of <code>ByteBuffers</code> containing the
485 * outbound application data
486 * @param dst
487 * a <code>ByteBuffer</code> to hold outbound network data
488 * @return an <code>SSLEngineResult</code> describing the result
489 * of this operation.
490 * @throws SSLException
491 * A problem was encountered while processing the
492 * data that caused the <code>SSLEngine</code> to abort.
493 * See the class description for more information on
494 * engine closure.
495 * @throws ReadOnlyBufferException
496 * if the <code>dst</code> buffer is read-only.
497 * @throws IllegalArgumentException
498 * if either <code>srcs</code> or <code>dst</code>
499 * is null, or if any element in <code>srcs</code> is null.
500 * @throws IllegalStateException if the client/server mode
501 * has not yet been set.
580 * is null, or if any element in the <code>srcs</code>
581 * subsequence specified is null.
582 * @throws IllegalStateException if the client/server mode
583 * has not yet been set.
584 * @see java.nio.channels.GatheringByteChannel
585 * @see java.nio.channels.GatheringByteChannel#write(
586 * ByteBuffer[], int, int)
587 */
588 public abstract SSLEngineResult wrap(ByteBuffer [] srcs, int offset,
589 int length, ByteBuffer dst) throws SSLException;
590
591 /**
592 * Attempts to decode SSL/TLS network data into a plaintext
593 * application data buffer.
594 * <P>
595 * An invocation of this method behaves in exactly the same manner
596 * as the invocation:
597 * <blockquote><pre>
598 * {@link #unwrap(ByteBuffer, ByteBuffer [], int, int)
599 * engine.unwrap(src, new ByteBuffer [] { dst }, 0, 1);}
600 * </pre></blockquote>
601 *
602 * @param src
603 * a <code>ByteBuffer</code> containing inbound network data.
604 * @param dst
605 * a <code>ByteBuffer</code> to hold inbound application data.
606 * @return an <code>SSLEngineResult</code> describing the result
607 * of this operation.
608 * @throws SSLException
609 * A problem was encountered while processing the
610 * data that caused the <code>SSLEngine</code> to abort.
611 * See the class description for more information on
612 * engine closure.
613 * @throws ReadOnlyBufferException
614 * if the <code>dst</code> buffer is read-only.
615 * @throws IllegalArgumentException
616 * if either <code>src</code> or <code>dst</code>
617 * is null.
618 * @throws IllegalStateException if the client/server mode
619 * has not yet been set.
620 * @see #unwrap(ByteBuffer, ByteBuffer [], int, int)
621 */
622 public SSLEngineResult unwrap(ByteBuffer src,
623 ByteBuffer dst) throws SSLException {
624 return unwrap(src, new ByteBuffer [] { dst }, 0, 1);
625 }
626
627 /**
628 * Attempts to decode SSL/TLS network data into a sequence of plaintext
629 * application data buffers.
630 * <P>
631 * An invocation of this method behaves in exactly the same manner
632 * as the invocation:
633 * <blockquote><pre>
634 * {@link #unwrap(ByteBuffer, ByteBuffer [], int, int)
635 * engine.unwrap(src, dsts, 0, dsts.length);}
636 * </pre></blockquote>
637 *
638 * @param src
639 * a <code>ByteBuffer</code> containing inbound network data.
640 * @param dsts
641 * an array of <code>ByteBuffer</code>s to hold inbound
642 * application data.
643 * @return an <code>SSLEngineResult</code> describing the result
644 * of this operation.
645 * @throws SSLException
646 * A problem was encountered while processing the
647 * data that caused the <code>SSLEngine</code> to abort.
648 * See the class description for more information on
649 * engine closure.
650 * @throws ReadOnlyBufferException
651 * if any of the <code>dst</code> buffers are read-only.
652 * @throws IllegalArgumentException
653 * if either <code>src</code> or <code>dsts</code>
654 * is null, or if any element in <code>dsts</code> is null.
655 * @throws IllegalStateException if the client/server mode
656 * has not yet been set.
|