gsscontext.java

gcc的组建

   * indicates that the token needs to be sent to the peer, but the local
   * end of the context is now fully established.</p>
   *
   * <p>The GSS-API authentication tokens contain a definitive start and end.
   * This method will attempt to read one of these tokens per invocation,
   * and may block on the stream if only part of the token is available.</p>
   *
   * <p>Upon completion of the context establishment, the available context
   * options may be queried through the get methods.</p>
   *
   * @param inStream  Contains the token generated by the peer.
   * @param outStream Output stream where the output token will be written.
   *                  During the final stage of context establishment, there
   *                  may be no bytes written.
   * @return The number of bytes written, or 0 if no token is written.
   * @throws GSSException If this operation fails.
   */
  void acceptSecContext(InputStream inStream, OutputStream outStream)
    throws GSSException;

  /**
   * Used during context establishment to determine the state of the
   * context. Returns <code>true</code> if this is a fully established
   * context on the caller's side and no more tokens are needed from the
   * peer. Should be called after a call to {@link
   * #initSecContext(byte[],int,int)} or {@link
   * #acceptSecContext(byte[],int,int)} when no {@link GSSException}
   * is thrown.
   *
   * @return True of this context is fully established on this side.
   */
  boolean isEstablished();

  /**
   * Releases any system resources and cryptographic information stored in
   * the context object. This will invalidate the context.
   *
   * @throws GSSException If this operation fails.
   */
  void dispose() throws GSSException;

  /**
   * <p>Returns the maximum message size that, if presented to the
   * {@link #wrap(byte[],int,int,org.ietf.jgss.MessageProp)} method with
   * the same <i>confReq</i> and <i>qop</i> parameters, will result in an
   * output token containing no more than the <i>maxTokenSize</i> bytes.</p>
   *
   * <p>This call is intended for use by applications that communicate over
   * protocols that impose a maximum message size.  It enables the
   * application to fragment messages prior to applying protection.</p>
   *
   * <p>GSS-API implementations are recommended but not required to detect
   * invalid QOP values when getWrapSizeLimit is called.  This routine
   * guarantees only a maximum message size, not the availability of
   * specific QOP values for message protection.</p>
   *
   * <p>Successful completion of this call does not guarantee that wrap will
   * be able to protect a message of the computed length, since this
   * ability may depend on the availability of system resources at the
   * time that wrap is called.  However, if the implementation itself
   * imposes an upper limit on the length of messages that may be
   * processed by wrap, the implementation should not return a value that
   * is greater than this length.</p>
   *
   * @param qop          Indicates the level of protection wrap will be asked
   *                     to provide.
   * @param confReq      Indicates if wrap will be asked to provide privacy
   *                     service.
   * @param maxTokenSize The desired maximum size of the token emitted
   *                     by {@link #wrap(byte[],int,int,org.ietf.jgss.MessageProp)}.
   * @return The maximum wrapped output size.
   * @throws GSSException If this operation fails.
   */
  int getWrapSizeLimit(int qop, boolean confReq, int maxTokenSize)
    throws GSSException;

  /**
   * <p>Applies per-message security services over the established security
   * context.  The method will return a token with a cryptographic MIC and
   * may optionally encrypt the specified <i>inBuf</i>. This method is
   * equivalent in functionality to its stream counterpart. The returned
   * byte array will contain both the MIC and the message.</p>
   *
   * <p>The {@link MessageProp} object is instantiated by the application
   * and used to specify a QOP value which selects cryptographic algorithms,
   * and a privacy service to optionally encrypt the message. The underlying
   * mechanism that is used in the call may not be able to provide the
   * privacy service.  It sets the actual privacy service that it does
   * provide in this {@link MessageProp} object which the caller should then
   * query upon return. If the mechanism is not able to provide the
   * requested QOP, it throws a {@link GSSException} with the {@link
   * GSSException#BAD_QOP} code.</p>
   *
   * <p>Since some application-level protocols may wish to use tokens emitted
   * by wrap to provide "secure framing", implementations should support
   * the wrapping of zero-length messages.</p>
   *
   * <p>The application will be responsible for sending the token to the
   * peer.</p>
   *
   * @param inBuf   Application data to be protected.
   * @param offset  The offset within the inBuf where the data begins.
   * @param len     The length of the data within the inBuf (starting at
   *                the offset).
   * @param msgProp Instance of {@link MessageProp} that is used by the
   *                application to set the desired QOP and privacy state.
   *                Set the desired QOP to 0 to request the default QOP.
   *                Upon return from this method, this object will contain
   *                the the actual privacy state that was applied to the
   *                message by the underlying mechanism.
   * @return The wrapped data.
   * @throws GSSException If this operation fails.
   */
  byte[] wrap(byte[] inBuf, int offset, int len, MessageProp msgProp)
    throws GSSException;

  /**
   * <p>Allows to apply per-message security services over the established
   * security context.  The method will produce a token with a
   * cryptographic MIC and may optionally encrypt the message in inStream.
   * The outStream will contain both the MIC and the message.</p>
   *
   * <p>The {@link MessageProp} object is instantiated by the application and
   * used to specify a QOP value which selects cryptographic algorithms, and
   * a privacy service to optionally encrypt the message.  The underlying
   * mechanism that is used in the call may not be able to provide the
   * privacy service.  It sets the actual privacy service that it does
   * provide in this MessageProp object which the caller should then query
   * upon return.  If the mechanism is not able to provide the requested
   * QOP, it throws a {@link GSSException} with the {@link
   * GSSException#BAD_QOP} code.</p>
   *
   * <p>Since some application-level protocols may wish to use tokens emitted
   * by wrap to provide "secure framing", implementations should support
   * the wrapping of zero-length messages.</p>
   *
   * <p>The application will be responsible for sending the token to the
   * peer.</p>
   *
   * @param inStream  Input stream containing the application data to be
   *                  protected.
   * @param outStream The output stream to write the protected message to.
   *                  The application is responsible for sending this to the
   *                  other peer for processing in its unwrap method.
   * @param msgProp   Instance of {@link MessageProp} that is used by the
   *                  application to set the desired QOP and privacy state.
   *                  Set the desired QOP to 0 to request the default QOP.
   *                  Upon return from this method, this object will contain
   *                  the the actual privacy state that was applied to the
   *                  message by the underlying mechanism.
   * @throws GSSException If this operation fails.
   */
  void wrap(InputStream inStream, OutputStream outStream, MessageProp msgProp)
    throws GSSException;

  /**
   * <p>Used by the peer application to process tokens generated with the
   * wrap call. This call is equal in functionality to its stream
   * counterpart. The method will return the message supplied in the peer
   * application to the wrap call, verifying the embedded MIC.</p>
   *
   * <p>The {@link MessageProp} object is instantiated by the application and
   * is used by the underlying mechanism to return information to the caller
   * such as the QOP, whether confidentiality was applied to the message, and
   * other supplementary message state information.</p>
   *
   * <p>Since some application-level protocols may wish to use tokens emitted
   * by wrap to provide "secure framing", implementations should support
   * the wrapping and unwrapping of zero-length messages.</p>
   *
   * @param inBuf   GSS-API wrap token received from peer.
   * @param offset  The offset within the inBuf where the token begins.
   * @param len     The length of the token within the inBuf (starting at
   *                the offset).
   * @param msgProp Upon return from the method, this object will contain
   *                the applied QOP, the privacy state of the message, and
   *                supplementary information stating whether the token was
   *                a duplicate, old, out of sequence or arriving after a gap.
   * @return The unwrapped token.
   * @throws GSSException If this operation fails.
   */
  byte[] unwrap(byte[] inBuf, int offset, int len, MessageProp msgProp)
    throws GSSException;

  /**
   * <p>Used by the peer application to process tokens generated with the
   * wrap call.  This call is equal in functionality to its byte array
   * counterpart.  It will produce the message supplied in the peer
   * application to the wrap call, verifying the embedded MIC.</p>
   *
   * <p>The {@link MessageProp} object is instantiated by the application
   * and is used by the underlying mechanism to return information to the
   * caller such as the QOP, whether confidentiality was applied to the
   * message, and other supplementary message state information.</p>
   *
   * <p>Since some application-level protocols may wish to use tokens emitted
   * by wrap to provide "secure framing", implementations should support
   * the wrapping and unwrapping of zero-length messages.</p>
   *
   * @param inStream  Input stream containing the GSS-API wrap token
   *                  received from the peer.
   * @param outStream The output stream to write the application message to.
   * @param msgProp   Upon return from the method, this object will contain
   *                  the applied QOP, the privacy state of the message, and
   *                  supplementary information stating whether the token was
   *                  a duplicate, old, out of sequence or arriving after a gap.
   * @throws GSSException If this operation fails.
   */
  void unwrap(InputStream inStream, OutputStream outStream, MessageProp msgProp)
    throws GSSException;

  /**
   * <p>Returns a token containing a cryptographic MIC for the supplied
   * message, for transfer to the peer application.  Unlike wrap, which
   * encapsulates the user message in the returned token, only the message
   * MIC is returned in the output token.  This method is identical in
   * functionality to its stream counterpart.</p>
   *
   * <p>Note that privacy can only be applied through the wrap call.</p>
   *
   * <p>Since some application-level protocols may wish to use tokens emitted
   * by getMIC to provide "secure framing", implementations should support
   * derivation of MICs from zero-length messages.</p>
   *
   * @param inMsg   Message to generate MIC over.
   * @param offset  The offset within the inMsg where the token begins.
   * @param len     The length of the token within the inMsg (starting at
   *                the offset).
   * @param msgProp Instance of MessageProp that is used by the
   *                application to set the desired QOP.  Set the desired
   *                QOP to 0 in msgProp to request the default QOP.
   *                Alternatively pass in <code>null</code> for msgProp to
   *                request default QOP.
   * @return The MIC.
   * @throws GSSException If this operation fails.
   */
  byte[] getMIC(byte[] inMsg, int offset, int len, MessageProp msgProp)
    throws GSSException;

  /**
   * <p>Produces a token containing a cryptographic MIC for the supplied
   * message, for transfer to the peer application.  Unlike wrap, which
   * encapsulates the user message in the returned token, only the message
   * MIC is produced in the output token.  This method is identical in
   * functionality to its byte array counterpart.</p>
   *
   * <p>Note that privacy can only be applied through the wrap call.</p>
   *
   * <p>Since some application-level protocols may wish to use tokens emitted
   * by getMIC to provide "secure framing", implementations should support
   * derivation of MICs from zero-length messages.</p>
   *
   * @param inStream  Input stream containing the message to generate
   *                  the MIC over.
   * @param outStream Output stream to write the GSS-API output token to.
   * @param msgProp   Instance of MessageProp that is used by the
   *                  application to set the desired QOP.  Set the desired
   *                  QOP to 0 in msgProp to request the default QOP.
   *                  Alternatively pass in <code>null</code> for msgProp
   *                  to request default QOP.
   * @throws GSSException If this operation fails.
   */
  void getMIC(InputStream inStream, OutputStream outStream, MessageProp mgProp)
    throws GSSException;

  /**
   * <p>Verifies the cryptographic MIC, contained in the token parameter,
   * over the supplied message.  This method is equivalent in
   * functionality to its stream counterpart.</p>
   *
   * <p>The MessageProp object is instantiated by the application and is used
   * by the underlying mechanism to return information to the caller such
   * as the QOP indicating the strength of protection that was applied to
   * the message and other supplementary message state information.</p>
   *
   * <p>Since some application-level protocols may wish to use tokens emitted
   * by getMIC to provide "secure framing", implementations should support
   * the calculation and verification of MICs over zero-length messages.</p>
   *
   * @param inTok     Token generated by peer's getMIC method.
   * @param tokOffset The offset within the inTok where the token begins.
   * @param tokLen    The length of the token within the inTok (starting at
   *                  the offset).
   * @param inMsg     Application message to verify the cryptographic MIC
   *                  over.
   * @param msgOffset The offset within the inMsg where the message begins.
   * @param msgLen    The length of the message within the inMsg (starting
   *                  at the offset).
   * @param msgProp   Upon return from the method, this object will contain
   *                  the applied QOP and supplementary information
   *                  stating whether the token was a duplicate, old, out
   *                  of sequence or arriving after a gap.  The
   *                  confidentiality state will be set to <code>false</code>.
   * @throws GSSException If this operation fails.
   */
  void verifyMIC(byte[] inTok, int tokOffset, int tokLen, byte[] inMsg,
                 int msgOffset, int msgLen, MessageProp msgProp)
    throws GSSException;

  /**
   * <p>Verifies the cryptographic MIC, contained in the token parameter,
   * over the supplied message.  This method is equivalent in
   * functionality to its byte array counterpart.</p>
   *
   * <p>The MessageProp object is instantiated by the application and is used
   * by the underlying mechanism to return information to the caller such
   * as the QOP indicating the strength of protection that was applied to
   * the message and other supplementary message state information.</p>
   *