home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / security / SignatureSpi.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  10.3 KB  |  296 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)SignatureSpi.java    1.8 98/05/02
  3.  *
  4.  * Copyright 1997, 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.   
  15. package java.security;
  16.  
  17. import java.security.spec.AlgorithmParameterSpec;
  18. import java.util.*;
  19. import java.io.*;
  20.  
  21. /**
  22.  * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>)
  23.  * for the <code>Signature</code> class, which is used to provide the
  24.  * functionality of a digital signature algorithm. Digital signatures are used
  25.  * for authentication and integrity assurance of digital data.
  26.  *.
  27.  * <p> All the abstract methods in this class must be implemented by each
  28.  * cryptographic service provider who wishes to supply the implementation
  29.  * of a particular signature algorithm.
  30.  *
  31.  * @author Benjamin Renaud 
  32.  *
  33.  * @version 1.8 99/03/26
  34.  *
  35.  * @see Signature
  36.  */
  37.  
  38. public abstract class SignatureSpi {
  39.  
  40.     /**
  41.      * Application-specified source of randomness. 
  42.      */
  43.     protected SecureRandom appRandom = null;
  44.  
  45.     /**
  46.      * Initializes this signature object with the specified
  47.      * public key for verification operations.
  48.      *
  49.      * @param publicKey the public key of the identity whose signature is
  50.      * going to be verified.
  51.      * 
  52.      * @exception InvalidKeyException if the key is improperly
  53.      * encoded, parameters are missing, and so on.  
  54.      */
  55.     protected abstract void engineInitVerify(PublicKey publicKey)
  56.     throws InvalidKeyException;
  57.  
  58.     /**
  59.      * Initializes this signature object with the specified
  60.      * private key for signing operations.
  61.      *
  62.      * @param privateKey the private key of the identity whose signature
  63.      * will be generated.
  64.      *
  65.      * @exception InvalidKeyException if the key is improperly
  66.      * encoded, parameters are missing, and so on. 
  67.      */
  68.     protected abstract void engineInitSign(PrivateKey privateKey)
  69.     throws InvalidKeyException;
  70.  
  71.     /**
  72.      * Initializes this signature object with the specified
  73.      * private key and source of randomness for signing operations.
  74.      *
  75.      * <p>This concrete method has been added to this previously-defined
  76.      * abstract class. (For backwards compatibility, it cannot be abstract.)
  77.      *
  78.      * @param privateKey the private key of the identity whose signature
  79.      * will be generated.
  80.      * @param random the source of randomness
  81.      *
  82.      * @exception InvalidKeyException if the key is improperly
  83.      * encoded, parameters are missing, and so on. 
  84.      */
  85.     protected void engineInitSign(PrivateKey privateKey,
  86.                   SecureRandom random)
  87.     throws InvalidKeyException {
  88.         this.appRandom = random;
  89.         engineInitSign(privateKey);
  90.     }
  91.  
  92.     /**
  93.      * Updates the data to be signed or verified
  94.      * using the specified byte.
  95.      *
  96.      * @param b the byte to use for the update.
  97.      *
  98.      * @exception SignatureException if the engine is not initialized
  99.      * properly.
  100.      */
  101.     protected abstract void engineUpdate(byte b) throws SignatureException;
  102.  
  103.     /**
  104.      * Updates the data to be signed or verified, using the 
  105.      * specified array of bytes, starting at the specified offset.
  106.      *
  107.      * @param data the array of bytes.  
  108.      * @param off the offset to start from in the array of bytes.  
  109.      * @param len the number of bytes to use, starting at offset.
  110.      *
  111.      * @exception SignatureException if the engine is not initialized 
  112.      * properly.
  113.      */
  114.     protected abstract void engineUpdate(byte[] b, int off, int len) 
  115.         throws SignatureException;
  116.  
  117.     /** 
  118.      * Returns the signature bytes of all the data
  119.      * updated so far.    
  120.      * The format of the signature depends on the underlying 
  121.      * signature scheme.
  122.      *
  123.      * @return the signature bytes of the signing operation's result.
  124.      *
  125.      * @exception SignatureException if the engine is not
  126.      * initialized properly.  
  127.      */
  128.     protected abstract byte[] engineSign() throws SignatureException;
  129.  
  130.     /**
  131.      * Finishes this signature operation and stores the resulting signature
  132.      * bytes in the provided buffer <code>outbuf</code>, starting at
  133.      * <code>offset</code>.
  134.      * The format of the signature depends on the underlying 
  135.      * signature scheme.
  136.      * 
  137.      * <p>The signature implementation is reset to its initial state
  138.      * (the state it was in after a call to one of the
  139.      * <code>engineInitSign</code> methods)
  140.      * and can be reused to generate further signatures with the same private
  141.      * key.
  142.      *
  143.      * This method should be abstract, but we leave it concrete for
  144.      * binary compatibility.  Knowledgeable providers should override this
  145.      * method.
  146.      *
  147.      * @param outbuf buffer for the signature result.
  148.      *
  149.      * @param offset offset into <code>outbuf</code> where the signature is
  150.      * stored.
  151.      *
  152.      * @param len number of bytes within <code>outbuf</code> allotted for the
  153.      * signature.
  154.      * Both this default implementation and the SUN provider do not
  155.      * return partial digests. If the value of this parameter is less
  156.      * than the actual signature length, this method will throw a
  157.      * SignatureException.
  158.      * This parameter is ignored if its value is greater than or equal to
  159.      * the actual signature length.
  160.      *
  161.      * @return the number of bytes placed into <code>outbuf</code>
  162.      * 
  163.      * @exception SignatureException if an error occurs or <code>len</code>
  164.      * is less than the actual signature length.
  165.      *
  166.      * @since JDK1.2
  167.      */
  168.     protected int engineSign(byte[] outbuf, int offset, int len)
  169.                     throws SignatureException {
  170.     byte[] sig = engineSign();
  171.     if (len < sig.length) {
  172.         throw new SignatureException
  173.             ("partial signatures not returned");
  174.     }
  175.     if (outbuf.length - offset < sig.length) {
  176.         throw new SignatureException
  177.             ("insufficient space in the output buffer to store the "
  178.              + "signature");
  179.     }
  180.     System.arraycopy(sig, 0, outbuf, offset, sig.length);
  181.     return sig.length;
  182.     }
  183.  
  184.     /** 
  185.      * Verifies the passed-in signature.   
  186.      * 
  187.      * @param sigBytes the signature bytes to be verified.
  188.      *
  189.      * @return true if the signature was verified, false if not. 
  190.      *
  191.      * @exception SignatureException if the engine is not initialized 
  192.      * properly, or the passed-in signature is improperly encoded or 
  193.      * of the wrong type, etc.  
  194.      */
  195.     protected abstract boolean engineVerify(byte[] sigBytes) 
  196.     throws SignatureException;
  197.  
  198.     /**
  199.      * Sets the specified algorithm parameter to the specified
  200.      * value. This method supplies a general-purpose mechanism through
  201.      * which it is possible to set the various parameters of this object. 
  202.      * A parameter may be any settable parameter for the algorithm, such as 
  203.      * a parameter size, or a source of random bits for signature generation 
  204.      * (if appropriate), or an indication of whether or not to perform
  205.      * a specific but optional computation. A uniform algorithm-specific 
  206.      * naming scheme for each parameter is desirable but left unspecified 
  207.      * at this time.
  208.      *
  209.      * @param param the string identifier of the parameter.
  210.      *
  211.      * @param value the parameter value.
  212.      *
  213.      * @exception InvalidParameterException if <code>param</code> is an
  214.      * invalid parameter for this signature algorithm engine,
  215.      * the parameter is already set
  216.      * and cannot be set again, a security exception occurs, and so on. 
  217.      *
  218.      * @deprecated Replaced by <a href =
  219.      * "#engineSetParameter(java.security.spec.AlgorithmParameterSpec)">
  220.      * engineSetParameter</a>.
  221.      */
  222.     protected abstract void engineSetParameter(String param, Object value) 
  223.     throws InvalidParameterException;
  224.  
  225.     /**
  226.      * Initializes this signature engine with the specified parameter set.
  227.      *
  228.      * This concrete method has been added to this previously-defined
  229.      * abstract class. (For backwards compatibility, it cannot be abstract.)
  230.      * It may be overridden by a provider to set the algorithm parameters
  231.      * using the specified <code>params</code>. Such an override
  232.      * is expected to throw an InvalidAlgorithmParameterException if
  233.      * a parameter is invalid.
  234.      * If this method is not overridden, it always throws an
  235.      * UnsupportedOperationException.
  236.      *
  237.      * @param params the parameters
  238.      *
  239.      * @exception InvalidAlgorithmParameterException if the given parameters
  240.      * are inappropriate for this signature engine
  241.      */
  242.     protected void engineSetParameter(AlgorithmParameterSpec params)
  243.     throws InvalidAlgorithmParameterException {
  244.         throw new UnsupportedOperationException();
  245.     }
  246.  
  247.     /**
  248.      * Gets the value of the specified algorithm parameter. 
  249.      * This method supplies a general-purpose mechanism through which it 
  250.      * is possible to get the various parameters of this object. A parameter
  251.      * may be any settable parameter for the algorithm, such as a parameter 
  252.      * size, or  a source of random bits for signature generation (if 
  253.      * appropriate), or an indication of whether or not to perform a 
  254.      * specific but optional computation. A uniform algorithm-specific 
  255.      * naming scheme for each parameter is desirable but left unspecified 
  256.      * at this time.
  257.      *
  258.      * @param param the string name of the parameter.
  259.      *
  260.      * @return the object that represents the parameter value, or null if
  261.      * there is none.
  262.      *
  263.      * @exception InvalidParameterException if <code>param</code> is an 
  264.      * invalid parameter for this engine, or another exception occurs while
  265.      * trying to get this parameter.
  266.      *
  267.      * @deprecated
  268.      */
  269.     protected abstract Object engineGetParameter(String param)
  270.     throws InvalidParameterException;
  271.  
  272.     /**
  273.      * Returns a clone if the implementation is cloneable.
  274.      * 
  275.      * @return a clone if the implementation is cloneable.
  276.      *
  277.      * @exception CloneNotSupportedException if this is called
  278.      * on an implementation that does not support <code>Cloneable</code>.
  279.      */
  280.     public Object clone() throws CloneNotSupportedException {
  281.     if (this instanceof Cloneable) {
  282.         return super.clone();
  283.     } else {
  284.         throw new CloneNotSupportedException();
  285.     }
  286.     }
  287. }
  288.     
  289.         
  290.  
  291.  
  292.  
  293.         
  294.         
  295.     
  296.