Save This Page
Home » openjdk-7 » javax » crypto » [javadoc | source]
    1   /*
    2    * Copyright (c) 1997, 2007, 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.crypto;
   27   
   28   import java.io;
   29   
   30   /**
   31    * A CipherOutputStream is composed of an OutputStream and a Cipher so
   32    * that write() methods first process the data before writing them out
   33    * to the underlying OutputStream.  The cipher must be fully
   34    * initialized before being used by a CipherOutputStream.
   35    *
   36    * <p> For example, if the cipher is initialized for encryption, the
   37    * CipherOutputStream will attempt to encrypt data before writing out the
   38    * encrypted data.
   39    *
   40    * <p> This class adheres strictly to the semantics, especially the
   41    * failure semantics, of its ancestor classes
   42    * java.io.OutputStream and java.io.FilterOutputStream.  This class
   43    * has exactly those methods specified in its ancestor classes, and
   44    * overrides them all.  Moreover, this class catches all exceptions
   45    * that are not thrown by its ancestor classes.
   46    *
   47    * <p> It is crucial for a programmer using this class not to use
   48    * methods that are not defined or overriden in this class (such as a
   49    * new method or constructor that is later added to one of the super
   50    * classes), because the design and implementation of those methods
   51    * are unlikely to have considered security impact with regard to
   52    * CipherOutputStream.
   53    *
   54    * @author  Li Gong
   55    * @see     java.io.OutputStream
   56    * @see     java.io.FilterOutputStream
   57    * @see     javax.crypto.Cipher
   58    * @see     javax.crypto.CipherInputStream
   59    *
   60    * @since 1.4
   61    */
   62   
   63   public class CipherOutputStream extends FilterOutputStream {
   64   
   65       // the cipher engine to use to process stream data
   66       private Cipher cipher;
   67   
   68       // the underlying output stream
   69       private OutputStream output;
   70   
   71       /* the buffer holding one byte of incoming data */
   72       private byte[] ibuffer = new byte[1];
   73   
   74       // the buffer holding data ready to be written out
   75       private byte[] obuffer;
   76   
   77       /**
   78        *
   79        * Constructs a CipherOutputStream from an OutputStream and a
   80        * Cipher.
   81        * <br>Note: if the specified output stream or cipher is
   82        * null, a NullPointerException may be thrown later when
   83        * they are used.
   84        *
   85        * @param os  the OutputStream object
   86        * @param c   an initialized Cipher object
   87        */
   88       public CipherOutputStream(OutputStream os, Cipher c) {
   89           super(os);
   90           output = os;
   91           cipher = c;
   92       };
   93   
   94       /**
   95        * Constructs a CipherOutputStream from an OutputStream without
   96        * specifying a Cipher. This has the effect of constructing a
   97        * CipherOutputStream using a NullCipher.
   98        * <br>Note: if the specified output stream is null, a
   99        * NullPointerException may be thrown later when it is used.
  100        *
  101        * @param os  the OutputStream object
  102        */
  103       protected CipherOutputStream(OutputStream os) {
  104           super(os);
  105           output = os;
  106           cipher = new NullCipher();
  107       }
  108   
  109       /**
  110        * Writes the specified byte to this output stream.
  111        *
  112        * @param      b   the <code>byte</code>.
  113        * @exception  IOException  if an I/O error occurs.
  114        * @since      JCE1.2
  115        */
  116       public void write(int b) throws IOException {
  117           ibuffer[0] = (byte) b;
  118           obuffer = cipher.update(ibuffer, 0, 1);
  119           if (obuffer != null) {
  120               output.write(obuffer);
  121               obuffer = null;
  122           }
  123       };
  124   
  125       /**
  126        * Writes <code>b.length</code> bytes from the specified byte array
  127        * to this output stream.
  128        * <p>
  129        * The <code>write</code> method of
  130        * <code>CipherOutputStream</code> calls the <code>write</code>
  131        * method of three arguments with the three arguments
  132        * <code>b</code>, <code>0</code>, and <code>b.length</code>.
  133        *
  134        * @param      b   the data.
  135        * @exception  NullPointerException if <code>b</code> is null.
  136        * @exception  IOException  if an I/O error occurs.
  137        * @see        javax.crypto.CipherOutputStream#write(byte[], int, int)
  138        * @since JCE1.2
  139        */
  140       public void write(byte b[]) throws IOException {
  141           write(b, 0, b.length);
  142       }
  143   
  144       /**
  145        * Writes <code>len</code> bytes from the specified byte array
  146        * starting at offset <code>off</code> to this output stream.
  147        *
  148        * @param      b     the data.
  149        * @param      off   the start offset in the data.
  150        * @param      len   the number of bytes to write.
  151        * @exception  IOException  if an I/O error occurs.
  152        * @since      JCE1.2
  153        */
  154       public void write(byte b[], int off, int len) throws IOException {
  155           obuffer = cipher.update(b, off, len);
  156           if (obuffer != null) {
  157               output.write(obuffer);
  158               obuffer = null;
  159           }
  160       }
  161   
  162       /**
  163        * Flushes this output stream by forcing any buffered output bytes
  164        * that have already been processed by the encapsulated cipher object
  165        * to be written out.
  166        *
  167        * <p>Any bytes buffered by the encapsulated cipher
  168        * and waiting to be processed by it will not be written out. For example,
  169        * if the encapsulated cipher is a block cipher, and the total number of
  170        * bytes written using one of the <code>write</code> methods is less than
  171        * the cipher's block size, no bytes will be written out.
  172        *
  173        * @exception  IOException  if an I/O error occurs.
  174        * @since      JCE1.2
  175        */
  176       public void flush() throws IOException {
  177           if (obuffer != null) {
  178               output.write(obuffer);
  179               obuffer = null;
  180           }
  181           output.flush();
  182       }
  183   
  184       /**
  185        * Closes this output stream and releases any system resources
  186        * associated with this stream.
  187        * <p>
  188        * This method invokes the <code>doFinal</code> method of the encapsulated
  189        * cipher object, which causes any bytes buffered by the encapsulated
  190        * cipher to be processed. The result is written out by calling the
  191        * <code>flush</code> method of this output stream.
  192        * <p>
  193        * This method resets the encapsulated cipher object to its initial state
  194        * and calls the <code>close</code> method of the underlying output
  195        * stream.
  196        *
  197        * @exception  IOException  if an I/O error occurs.
  198        * @since      JCE1.2
  199        */
  200       public void close() throws IOException {
  201           try {
  202               obuffer = cipher.doFinal();
  203           } catch (IllegalBlockSizeException e) {
  204               obuffer = null;
  205           } catch (BadPaddingException e) {
  206               obuffer = null;
  207           }
  208           try {
  209               flush();
  210           } catch (IOException ignored) {}
  211           out.close();
  212       }
  213   }

Save This Page
Home » openjdk-7 » javax » crypto » [javadoc | source]