1 /* 2 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.net.ssl; 27 28 /** 29 * An encapsulation of the result state produced by 30 * <code>SSLEngine</code> I/O calls. 31 * 32 * <p> A <code>SSLEngine</code> provides a means for establishing 33 * secure communication sessions between two peers. <code>SSLEngine</code> 34 * operations typically consume bytes from an input buffer and produce 35 * bytes in an output buffer. This class provides operational result 36 * values describing the state of the <code>SSLEngine</code>, including 37 * indications of what operations are needed to finish an 38 * ongoing handshake. Lastly, it reports the number of bytes consumed 39 * and produced as a result of this operation. 40 * 41 * @see SSLEngine 42 * @see SSLEngine#wrap(ByteBuffer, ByteBuffer) 43 * @see SSLEngine#unwrap(ByteBuffer, ByteBuffer) 44 * 45 * @author Brad R. Wetmore 46 * @since 1.5 47 */ 48 49 public class SSLEngineResult { 50 51 /** 52 * An <code>SSLEngineResult</code> enum describing the overall result 53 * of the <code>SSLEngine</code> operation. 54 * 55 * The <code>Status</code> value does not reflect the 56 * state of a <code>SSLEngine</code> handshake currently 57 * in progress. The <code>SSLEngineResult's HandshakeStatus</code> 58 * should be consulted for that information. 59 * 60 * @author Brad R. Wetmore 61 * @since 1.5 62 */ 63 public static enum Status { 64 65 /** 66 * The <code>SSLEngine</code> was not able to unwrap the 67 * incoming data because there were not enough source bytes 68 * available to make a complete packet. 69 * 70 * <P> 71 * Repeat the call once more bytes are available. 72 */ 73 BUFFER_UNDERFLOW, 74 75 /** 76 * The <code>SSLEngine</code> was not able to process the 77 * operation because there are not enough bytes available in the 78 * destination buffer to hold the result. 79 * <P> 80 * Repeat the call once more bytes are available. 81 * 82 * @see SSLSession#getPacketBufferSize() 83 * @see SSLSession#getApplicationBufferSize() 84 */ 85 BUFFER_OVERFLOW, 86 87 /** 88 * The <code>SSLEngine</code> completed the operation, and 89 * is available to process similar calls. 90 */ 91 OK, 92 93 /** 94 * The operation just closed this side of the 95 * <code>SSLEngine</code>, or the operation 96 * could not be completed because it was already closed. 97 */ 98 CLOSED; 99 } 100 101 /** 102 * An <code>SSLEngineResult</code> enum describing the current 103 * handshaking state of this <code>SSLEngine</code>. 104 * 105 * @author Brad R. Wetmore 106 * @since 1.5 107 */ 108 public static enum HandshakeStatus { 109 110 /** 111 * The <code>SSLEngine</code> is not currently handshaking. 112 */ 113 NOT_HANDSHAKING, 114 115 /** 116 * The <code>SSLEngine</code> has just finished handshaking. 117 * <P> 118 * This value is only generated by a call to 119 * <code>SSLEngine.wrap()/unwrap()</code> when that call 120 * finishes a handshake. It is never generated by 121 * <code>SSLEngine.getHandshakeStatus()</code>. 122 * 123 * @see SSLEngine#wrap(ByteBuffer, ByteBuffer) 124 * @see SSLEngine#unwrap(ByteBuffer, ByteBuffer) 125 * @see SSLEngine#getHandshakeStatus() 126 */ 127 FINISHED, 128 129 /** 130 * The <code>SSLEngine</code> needs the results of one (or more) 131 * delegated tasks before handshaking can continue. 132 * 133 * @see SSLEngine#getDelegatedTask() 134 */ 135 NEED_TASK, 136 137 /** 138 * The <code>SSLEngine</code> must send data to the remote side 139 * before handshaking can continue, so <code>SSLEngine.wrap()</code> 140 * should be called. 141 * 142 * @see SSLEngine#wrap(ByteBuffer, ByteBuffer) 143 */ 144 NEED_WRAP, 145 146 /** 147 * The <code>SSLEngine</code> needs to receive data from the 148 * remote side before handshaking can continue. 149 */ 150 NEED_UNWRAP; 151 } 152 153 154 private final Status status; 155 private final HandshakeStatus handshakeStatus; 156 private final int bytesConsumed; 157 private final int bytesProduced; 158 159 /** 160 * Initializes a new instance of this class. 161 * 162 * @param status 163 * the return value of the operation. 164 * 165 * @param handshakeStatus 166 * the current handshaking status. 167 * 168 * @param bytesConsumed 169 * the number of bytes consumed from the source ByteBuffer 170 * 171 * @param bytesProduced 172 * the number of bytes placed into the destination ByteBuffer 173 * 174 * @throws IllegalArgumentException 175 * if the <code>status</code> or <code>handshakeStatus</code> 176 * arguments are null, or if <code>bytesConsumed</code> or 177 * <code>bytesProduced</code> is negative. 178 */ 179 public SSLEngineResult(Status status, HandshakeStatus handshakeStatus, 180 int bytesConsumed, int bytesProduced) { 181 182 if ((status == null) || (handshakeStatus == null) || 183 (bytesConsumed < 0) || (bytesProduced < 0)) { 184 throw new IllegalArgumentException("Invalid Parameter(s)"); 185 } 186 187 this.status = status; 188 this.handshakeStatus = handshakeStatus; 189 this.bytesConsumed = bytesConsumed; 190 this.bytesProduced = bytesProduced; 191 } 192 193 /** 194 * Gets the return value of this <code>SSLEngine</code> operation. 195 * 196 * @return the return value 197 */ 198 final public Status getStatus() { 199 return status; 200 } 201 202 /** 203 * Gets the handshake status of this <code>SSLEngine</code> 204 * operation. 205 * 206 * @return the handshake status 207 */ 208 final public HandshakeStatus getHandshakeStatus() { 209 return handshakeStatus; 210 } 211 212 /** 213 * Returns the number of bytes consumed from the input buffer. 214 * 215 * @return the number of bytes consumed. 216 */ 217 final public int bytesConsumed() { 218 return bytesConsumed; 219 } 220 221 /** 222 * Returns the number of bytes written to the output buffer. 223 * 224 * @return the number of bytes produced 225 */ 226 final public int bytesProduced() { 227 return bytesProduced; 228 } 229 230 /** 231 * Returns a String representation of this object. 232 */ 233 @Override 234 public String toString() { 235 return ("Status = " + status + 236 " HandshakeStatus = " + handshakeStatus + 237 "\nbytesConsumed = " + bytesConsumed + 238 " bytesProduced = " + bytesProduced); 239 } 240 } 241
