181. EPMO Open Source Coordination Office Redaction File Detail Report

Produced by Araxis Merge on 9/25/2018 2:13:11 PM Central Daylight Time. See www.araxis.com for information about Merge. This report uses XHTML and CSS2, and is best viewed with a modern standards-compliant browser. For optimum results when printing this report, use landscape orientation and enable printing of background images and colours in your browser.

181.1 Files compared

# Location File Last Modified
1 build 3.zip\build 3\MHLTH_YS_137_Source\JavaScript\resources\javaJDF-1.8.0\src\javax\crypto KeyAgreement.java Mon Jan 22 14:46:52 2018 UTC
2 build 3.zip\build 3\MHLTH_YS_137_Source\JavaScript\resources\javaJDF-1.8.0\src\javax\crypto KeyAgreement.java Wed Sep 12 17:18:33 2018 UTC

181.2 Comparison summary

Description Between
Files 1 and 2
Text Blocks Lines
Unchanged 13 1274
Changed 12 26
Inserted 0 0
Removed 0 0

181.3 Comparison options

Whitespace
Character case Differences in character case are significant
Line endings Differences in line endings (CR and LF characters) are ignored
CR/LF characters Not shown in the comparison detail

181.4 Active regular expressions

No regular expressions were active.

181.5 Comparison detail

  1   /*
  2    * Copyrig ht (c) 199 7, 2014, O racle and/ or its aff iliates. A ll rights  reserved.
  3    * DO NOT  ALTER OR R EMOVE COPY RIGHT NOTI CES OR THI S FILE HEA DER.
  4    *
  5    * This co de is free  software;  you can r edistribut e it and/o r modify i t
  6    * under t he terms o f the GNU  General Pu blic Licen se version  2 only, a s
  7    * publish ed by the  Free Softw are Founda tion.  Ora cle design ates this
  8    * particu lar file a s subject  to the "Cl asspath" e xception a s provided
  9    * by Orac le in the  LICENSE fi le that ac companied  this code.
  10    *
  11    * This co de is dist ributed in  the hope  that it wi ll be usef ul, but WI THOUT
  12    * ANY WAR RANTY; wit hout even  the implie d warranty  of MERCHA NTABILITY  or
  13    * FITNESS  FOR A PAR TICULAR PU RPOSE.  Se e the GNU  General Pu blic Licen se
  14    * version  2 for mor e details  (a copy is  included  in the LIC ENSE file  that
  15    * accompa nied this  code).
  16    *
  17    * You sho uld have r eceived a  copy of th e GNU Gene ral Public  License v ersion
  18    * 2 along  with this  work; if  not, write  to the Fr ee Softwar e Foundati on,
  19    * Inc., 5 1 Franklin  St, Fifth  Floor, Bo ston, MA 0 2110-1301  USA.
  20    *
  21    * Please  contact Or acle, 500  Oracle Par kway, Redw ood Shores , CA 94065  USA
  22    * or visi t www.orac le.com if  you need a dditional  informatio n or have  any
  23    * questio ns.
  24    */
  25  
  26   package ja vax.crypto ;
  27  
  28   import jav a.util.*;
  29  
  30   import jav a.security .*;
  31   import jav a.security .Provider. Service;
  32   import jav a.security .spec.*;
  33  
  34   import sun .security. util.Debug ;
  35   import sun .security. jca.*;
  36   import sun .security. jca.GetIns tance.Inst ance;
  37  
  38   /**
  39    * This cl ass provid es the fun ctionality  of a key  agreement  (or key
  40    * exchang e) protoco l.
  41    * <p>
  42    * The key s involved  in establ ishing a s hared  PW        are create d by one o f the
  43    * key gen erators (< code>KeyPa irGenerato r</code> o r
  44    * <code>K eyGenerato r</code>),  a <code>K eyFactory< /code>, or  as a resu lt from
  45    * an inte rmediate p hase of th e key agre ement prot ocol.
  46    *
  47    * <p> For  each of t he corresp ondents in  the key e xchange, < code>doPha se</code>
  48    * needs t o be calle d. For exa mple, if t his key ex change is  with one o ther
  49    * party,  <code>doPh ase</code>  needs to  be called  once, with  the
  50    * <code>l astPhase</ code> flag  set to <c ode>true</ code>.
  51    * If this  key excha nge is
  52    * with tw o other pa rties, <co de>doPhase </code> ne eds to be  called twi ce,
  53    * the fir st time se tting the  <code>last Phase</cod e> flag to
  54    * <code>f alse</code >, and the  second ti me setting  it to <co de>true</c ode>.
  55    * There m ay be any  number of  parties in volved in  a key exch ange.
  56    *
  57    * <p> Eve ry impleme ntation of  the Java  platform i s required  to suppor t the
  58    * followi ng standar d <code>Ke yAgreement </code> al gorithm:
  59    * <ul>
  60    * <li><tt >DiffieHel lman</tt>< /li>
  61    * </ul>
  62    * This al gorithm is  described  in the <a  href=
  63    * "{@docR oot}/../te chnotes/gu ides/secur ity/Standa rdNames.ht ml#KeyAgre ement">
  64    * KeyAgre ement sect ion</a> of  the
  65    * Java Cr yptography  Architect ure Standa rd Algorit hm Name Do cumentatio n.
  66    * Consult  the relea se documen tation for  your impl ementation  to see if  any
  67    * other a lgorithms  are suppor ted.
  68    *
  69    * @author  Jan Luehe
  70    *
  71    * @see Ke yGenerator
  72    * @see Se cretKey
  73    * @since  1.4
  74    */
  75  
  76   public cla ss KeyAgre ement {
  77  
  78       privat e static f inal Debug  debug =
  79                             Debug. getInstanc e("jca", " KeyAgreeme nt");
  80  
  81       privat e static f inal Debug  pdebug =
  82                             Debug. getInstanc e("provide r", "Provi der");
  83       privat e static f inal boole an skipDeb ug =
  84           De bug.isOn(" engine=")  && !Debug. isOn("keya greement") ;
  85  
  86       // The  provider
  87       privat e Provider  provider;
  88  
  89       // The  provider  implementa tion (dele gate)
  90       privat e KeyAgree mentSpi sp i;
  91  
  92       // The  name of t he key agr eement alg orithm.
  93       privat e final St ring algor ithm;
  94  
  95       // nex t service  to try in  provider s election
  96       // nul l once pro vider is s elected
  97       privat e Service  firstServi ce;
  98  
  99       // rem aining ser vices to t ry in prov ider selec tion
  100       // nul l once pro vider is s elected
  101       privat e Iterator <Service>  serviceIte rator;
  102  
  103       privat e final Ob ject lock;
  104  
  105       /**
  106        * Cre ates a Key Agreement  object.
  107        *
  108        * @pa ram keyAgr eeSpi the  delegate
  109        * @pa ram provid er the pro vider
  110        * @pa ram algori thm the al gorithm
  111        */
  112       protec ted KeyAgr eement(Key AgreementS pi keyAgre eSpi, Prov ider provi der,
  113                                Str ing algori thm) {
  114           th is.spi = k eyAgreeSpi ;
  115           th is.provide r = provid er;
  116           th is.algorit hm = algor ithm;
  117           lo ck = null;
  118       }
  119  
  120       privat e KeyAgree ment(Servi ce s, Iter ator<Servi ce> t, Str ing algori thm) {
  121           fi rstService  = s;
  122           se rviceItera tor = t;
  123           th is.algorit hm = algor ithm;
  124           lo ck = new O bject();
  125       }
  126  
  127       /**
  128        * Ret urns the a lgorithm n ame of thi s <code>Ke yAgreement </code> ob ject.
  129        *
  130        * <p> This is th e same nam e that was  specified  in one of  the
  131        * <co de>getInst ance</code > calls th at created  this
  132        * <co de>KeyAgre ement</cod e> object.
  133        *
  134        * @re turn the a lgorithm n ame of thi s <code>Ke yAgreement </code> ob ject.
  135        */
  136       public  final Str ing getAlg orithm() {
  137           re turn this. algorithm;
  138       }
  139  
  140       /**
  141        * Ret urns a <co de>KeyAgre ement</cod e> object  that imple ments the
  142        * spe cified key  agreement  algorithm .
  143        *
  144        * <p>  This meth od travers es the lis t of regis tered secu rity Provi ders,
  145        * sta rting with  the most  preferred  Provider.
  146        * A n ew KeyAgre ement obje ct encapsu lating the
  147        * Key AgreementS pi impleme ntation fr om the fir st
  148        * Pro vider that  supports  the specif ied algori thm is ret urned.
  149        *
  150        * <p>  Note that  the list  of registe red provid ers may be  retrieved  via
  151        * the  {@link Se curity#get Providers( ) Security .getProvid ers()} met hod.
  152        *
  153        * @pa ram algori thm the st andard nam e of the r equested k ey agreeme nt
  154        * alg orithm.
  155        * See  the KeyAg reement se ction in t he <a href =
  156        * "{@ docRoot}/. ./technote s/guides/s ecurity/St andardName s.html#Key Agreement" >
  157        * Jav a Cryptogr aphy Archi tecture St andard Alg orithm Nam e Document ation</a>
  158        * for  informati on about s tandard al gorithm na mes.
  159        *
  160        * @re turn the n ew <code>K eyAgreemen t</code> o bject.
  161        *
  162        * @ex ception Nu llPointerE xception i f the spec ified algo rithm
  163        *           is n ull.
  164        *
  165        * @ex ception No SuchAlgori thmExcepti on if no P rovider su pports a
  166        *           KeyA greementSp i implemen tation for  the
  167        *           spec ified algo rithm.
  168        *
  169        * @se e java.sec urity.Prov ider
  170        */
  171       public  static fi nal KeyAgr eement get Instance(S tring algo rithm)
  172                throws N oSuchAlgor ithmExcept ion {
  173           Li st<Service > services  =
  174                    GetI nstance.ge tServices( "KeyAgreem ent", algo rithm);
  175           //  make sure  there is  at least o ne service  from a si gned provi der
  176           It erator<Ser vice> t =  services.i terator();
  177           wh ile (t.has Next()) {
  178                Service  s = t.next ();
  179                if (JceS ecurity.ca nUseProvid er(s.getPr ovider())  == false)  {
  180                    cont inue;
  181                }
  182                return n ew KeyAgre ement(s, t , algorith m);
  183           }
  184           th row new No SuchAlgori thmExcepti on
  185                                      ("Algori thm " + al gorithm +  " not avai lable");
  186       }
  187  
  188       /**
  189        * Ret urns a <co de>KeyAgre ement</cod e> object  that imple ments the
  190        * spe cified key  agreement  algorithm .
  191        *
  192        * <p>  A new Key Agreement  object enc apsulating  the
  193        * Key AgreementS pi impleme ntation fr om the spe cified pro vider
  194        * is  returned.   The speci fied provi der must b e register ed
  195        * in  the securi ty provide r list.
  196        *
  197        * <p>  Note that  the list  of registe red provid ers may be  retrieved  via
  198        * the  {@link Se curity#get Providers( ) Security .getProvid ers()} met hod.
  199        *
  200        * @pa ram algori thm the st andard nam e of the r equested k ey agreeme nt
  201        * alg orithm.
  202        * See  the KeyAg reement se ction in t he <a href =
  203        * "{@ docRoot}/. ./technote s/guides/s ecurity/St andardName s.html#Key Agreement" >
  204        * Jav a Cryptogr aphy Archi tecture St andard Alg orithm Nam e Document ation</a>
  205        * for  informati on about s tandard al gorithm na mes.
  206        *
  207        * @pa ram provid er the nam e of the p rovider.
  208        *
  209        * @re turn the n ew <code>K eyAgreemen t</code> o bject.
  210        *
  211        * @ex ception Nu llPointerE xception i f the spec ified algo rithm
  212        *           is n ull.
  213        *
  214        * @ex ception No SuchAlgori thmExcepti on if a Ke yAgreement Spi
  215        *           impl ementation  for the s pecified a lgorithm i s not
  216        *           avai lable from  the speci fied provi der.
  217        *
  218        * @ex ception No SuchProvid erExceptio n if the s pecified p rovider is  not
  219        *           regi stered in  the securi ty provide r list.
  220        *
  221        * @ex ception Il legalArgum entExcepti on if the  <code>prov ider</code >
  222        *           is n ull or emp ty.
  223        *
  224        * @se e java.sec urity.Prov ider
  225        */
  226       public  static fi nal KeyAgr eement get Instance(S tring algo rithm,
  227                String p rovider) t hrows NoSu chAlgorith mException ,
  228                NoSuchPr oviderExce ption {
  229           In stance ins tance = Jc eSecurity. getInstanc e
  230                    ("Ke yAgreement ", KeyAgre ementSpi.c lass, algo rithm, pro vider);
  231           re turn new K eyAgreemen t((KeyAgre ementSpi)i nstance.im pl,
  232                    inst ance.provi der, algor ithm);
  233       }
  234  
  235       /**
  236        * Ret urns a <co de>KeyAgre ement</cod e> object  that imple ments the
  237        * spe cified key  agreement  algorithm .
  238        *
  239        * <p>  A new Key Agreement  object enc apsulating  the
  240        * Key AgreementS pi impleme ntation fr om the spe cified Pro vider
  241        * obj ect is ret urned.  No te that th e specifie d Provider  object
  242        * doe s not have  to be reg istered in  the provi der list.
  243        *
  244        * @pa ram algori thm the st andard nam e of the r equested k ey agreeme nt
  245        * alg orithm.
  246        * See  the KeyAg reement se ction in t he <a href =
  247        * "{@ docRoot}/. ./technote s/guides/s ecurity/St andardName s.html#Key Agreement" >
  248        * Jav a Cryptogr aphy Archi tecture St andard Alg orithm Nam e Document ation</a>
  249        * for  informati on about s tandard al gorithm na mes.
  250        *
  251        * @pa ram provid er the pro vider.
  252        *
  253        * @re turn the n ew <code>K eyAgreemen t</code> o bject.
  254        *
  255        * @ex ception Nu llPointerE xception i f the spec ified algo rithm
  256        *           is n ull.
  257        *
  258        * @ex ception No SuchAlgori thmExcepti on if a Ke yAgreement Spi
  259        *           impl ementation  for the s pecified a lgorithm i s not avai lable
  260        *           from  the speci fied Provi der object .
  261        *
  262        * @ex ception Il legalArgum entExcepti on if the  <code>prov ider</code >
  263        *           is n ull.
  264        *
  265        * @se e java.sec urity.Prov ider
  266        */
  267       public  static fi nal KeyAgr eement get Instance(S tring algo rithm,
  268                Provider  provider)  throws No SuchAlgori thmExcepti on {
  269           In stance ins tance = Jc eSecurity. getInstanc e
  270                    ("Ke yAgreement ", KeyAgre ementSpi.c lass, algo rithm, pro vider);
  271           re turn new K eyAgreemen t((KeyAgre ementSpi)i nstance.im pl,
  272                    inst ance.provi der, algor ithm);
  273       }
  274  
  275       // max  number of  debug war nings to p rint from  chooseFirs tProvider( )
  276       privat e static i nt warnCou nt = 10;
  277  
  278       /**
  279        * Cho ose the Sp i from the  first pro vider avai lable. Use d if
  280        * del ayed provi der select ion is not  possible  because in it()
  281        * is  not the fi rst method  called.
  282        */
  283       void c hooseFirst Provider()  {
  284           if  (spi != n ull) {
  285                return;
  286           }
  287           sy nchronized  (lock) {
  288                if (spi  != null) {
  289                    retu rn;
  290                }
  291                if (debu g != null)  {
  292                    int  w = --warn Count;
  293                    if ( w >= 0) {
  294                         debug.prin tln("KeyAg reement.in it() not f irst metho d "
  295                             + "cal led, disab ling delay ed provide r selectio n");
  296                         if (w == 0 ) {
  297                             debug. println("F urther war nings of t his type w ill "
  298                                 +  "be suppre ssed");
  299                         }
  300                         new Except ion("Call  trace").pr intStackTr ace();
  301                    }
  302                }
  303                Exceptio n lastExce ption = nu ll;
  304                while (( firstServi ce != null ) || servi ceIterator .hasNext() ) {
  305                    Serv ice s;
  306                    if ( firstServi ce != null ) {
  307                         s = firstS ervice;
  308                         firstServi ce = null;
  309                    } el se {
  310                         s = servic eIterator. next();
  311                    }
  312                    if ( JceSecurit y.canUsePr ovider(s.g etProvider ()) == fal se) {
  313                         continue;
  314                    }
  315                    try  {
  316                         Object obj  = s.newIn stance(nul l);
  317                         if (obj in stanceof K eyAgreemen tSpi == fa lse) {
  318                             contin ue;
  319                         }
  320                         spi = (Key AgreementS pi)obj;
  321                         provider =  s.getProv ider();
  322                         // not nee ded any mo re
  323                         firstServi ce = null;
  324                         serviceIte rator = nu ll;
  325                         return;
  326                    } ca tch (Excep tion e) {
  327                         lastExcept ion = e;
  328                    }
  329                }
  330                Provider Exception  e = new Pr oviderExce ption
  331                         ("Could no t construc t KeyAgree mentSpi in stance");
  332                if (last Exception  != null) {
  333                    e.in itCause(la stExceptio n);
  334                }
  335                throw e;
  336           }
  337       }
  338  
  339       privat e final st atic int I _NO_PARAMS  = 1;
  340       privat e final st atic int I _PARAMS     = 2;
  341  
  342       privat e void imp lInit(KeyA greementSp i spi, int  type, Key  key,
  343                Algorith mParameter Spec param s, SecureR andom rand om)
  344                throws I nvalidKeyE xception,  InvalidAlg orithmPara meterExcep tion {
  345           if  (type ==  I_NO_PARAM S) {
  346                spi.engi neInit(key , random);
  347           }  else { //  I_PARAMS
  348                spi.engi neInit(key , params,  random);
  349           }
  350       }
  351  
  352       privat e void cho oseProvide r(int init Type, Key  key,
  353                Algorith mParameter Spec param s, SecureR andom rand om)
  354                throws I nvalidKeyE xception,  InvalidAlg orithmPara meterExcep tion {
  355           sy nchronized  (lock) {
  356                if (spi  != null) {
  357                    impl Init(spi,  initType,  key, param s, random) ;
  358                    retu rn;
  359                }
  360                Exceptio n lastExce ption = nu ll;
  361                while (( firstServi ce != null ) || servi ceIterator .hasNext() ) {
  362                    Serv ice s;
  363                    if ( firstServi ce != null ) {
  364                         s = firstS ervice;
  365                         firstServi ce = null;
  366                    } el se {
  367                         s = servic eIterator. next();
  368                    }
  369                    // i f provider  says it d oes not su pport this  key, igno re it
  370                    if ( s.supports Parameter( key) == fa lse) {
  371                         continue;
  372                    }
  373                    if ( JceSecurit y.canUsePr ovider(s.g etProvider ()) == fal se) {
  374                         continue;
  375                    }
  376                    try  {
  377                         KeyAgreeme ntSpi spi  = (KeyAgre ementSpi)s .newInstan ce(null);
  378                         implInit(s pi, initTy pe, key, p arams, ran dom);
  379                         provider =  s.getProv ider();
  380                         this.spi =  spi;
  381                         firstServi ce = null;
  382                         serviceIte rator = nu ll;
  383                         return;
  384                    } ca tch (Excep tion e) {
  385                         // NoSuchA lgorithmEx ception fr om newInst ance()
  386                         // Invalid KeyExcepti on from in it()
  387                         // Runtime Exception  (ProviderE xception)  from init( )
  388                         if (lastEx ception ==  null) {
  389                             lastEx ception =  e;
  390                         }
  391                    }
  392                }
  393                // no wo rking prov ider found , fail
  394                if (last Exception  instanceof  InvalidKe yException ) {
  395                    thro w (Invalid KeyExcepti on)lastExc eption;
  396                }
  397                if (last Exception  instanceof  InvalidAl gorithmPar ameterExce ption) {
  398                    thro w (Invalid AlgorithmP arameterEx ception)la stExceptio n;
  399                }
  400                if (last Exception  instanceof  RuntimeEx ception) {
  401                    thro w (Runtime Exception) lastExcept ion;
  402                }
  403                String k Name = (ke y != null)  ? key.get Class().ge tName() :  "(null)";
  404                throw ne w InvalidK eyExceptio n
  405                    ("No  installed  provider  supports t his key: "
  406                    + kN ame, lastE xception);
  407           }
  408       }
  409  
  410       /**
  411        * Ret urns the p rovider of  this <cod e>KeyAgree ment</code > object.
  412        *
  413        * @re turn the p rovider of  this <cod e>KeyAgree ment</code > object
  414        */
  415       public  final Pro vider getP rovider()  {
  416           ch ooseFirstP rovider();
  417           re turn this. provider;
  418       }
  419  
  420       /**
  421        * Ini tializes t his key ag reement wi th the giv en key, wh ich is req uired to
  422        * con tain all t he algorit hm paramet ers requir ed for thi s key agre ement.
  423        *
  424        * <p>  If this k ey agreeme nt require s any rand om bytes,  it will ge t
  425        * the m using th e
  426        * {@l ink java.s ecurity.Se cureRandom }
  427        * imp lementatio n of the h ighest-pri ority
  428        * ins talled pro vider as t he source  of randomn ess.
  429        * (If  none of t he install ed provide rs supply  an impleme ntation of
  430        * Sec ureRandom,  a system- provided s ource of r andomness  will be us ed.)
  431        *
  432        * @pa ram key th e party's  private in formation.  For examp le, in the  case
  433        * of  the Diffie -Hellman k ey agreeme nt, this w ould be th e party's  own
  434        * Dif fie-Hellma n private  key.
  435        *
  436        * @ex ception In validKeyEx ception if  the given  key is
  437        * ina ppropriate  for this  key agreem ent, e.g.,  is of the  wrong typ e or
  438        * has  an incomp atible alg orithm typ e.
  439        */
  440       public  final voi d init(Key  key) thro ws Invalid KeyExcepti on {
  441           in it(key, Jc eSecurity. RANDOM);
  442       }
  443  
  444       /**
  445        * Ini tializes t his key ag reement wi th the giv en key and  source of
  446        * ran domness. T he given k ey is requ ired to co ntain all  the algori thm
  447        * par ameters re quired for  this key  agreement.
  448        *
  449        * <p>  If the ke y agreemen t algorith m requires  random by tes, it ge ts them
  450        * fro m the give n source o f randomne ss, <code> random</co de>.
  451        * How ever, if t he underly ing
  452        * alg orithm imp lementatio n does not  require a ny random  bytes,
  453        * <co de>random< /code> is  ignored.
  454        *
  455        * @pa ram key th e party's  private in formation.  For examp le, in the  case
  456        * of  the Diffie -Hellman k ey agreeme nt, this w ould be th e party's  own
  457        * Dif fie-Hellma n private  key.
  458        * @pa ram random  the sourc e of rando mness
  459        *
  460        * @ex ception In validKeyEx ception if  the given  key is
  461        * ina ppropriate  for this  key agreem ent, e.g.,  is of the  wrong typ e or
  462        * has  an incomp atible alg orithm typ e.
  463        */
  464       public  final voi d init(Key  key, Secu reRandom r andom)
  465                throws I nvalidKeyE xception {
  466           if  (spi != n ull) {
  467                spi.engi neInit(key , random);
  468           }  else {
  469                try {
  470                    choo seProvider (I_NO_PARA MS, key, n ull, rando m);
  471                } catch  (InvalidAl gorithmPar ameterExce ption e) {
  472                    // s hould neve r occur
  473                    thro w new Inva lidKeyExce ption(e);
  474                }
  475           }
  476  
  477           if  (!skipDeb ug && pdeb ug != null ) {
  478                pdebug.p rintln("Ke yAgreement ." + algor ithm + " a lgorithm f rom: " +
  479                    this .provider. getName()) ;
  480           }
  481       }
  482  
  483       /**
  484        * Ini tializes t his key ag reement wi th the giv en key and  set of
  485        * alg orithm par ameters.
  486        *
  487        * <p>  If this k ey agreeme nt require s any rand om bytes,  it will ge t
  488        * the m using th e
  489        * {@l ink java.s ecurity.Se cureRandom }
  490        * imp lementatio n of the h ighest-pri ority
  491        * ins talled pro vider as t he source  of randomn ess.
  492        * (If  none of t he install ed provide rs supply  an impleme ntation of
  493        * Sec ureRandom,  a system- provided s ource of r andomness  will be us ed.)
  494        *
  495        * @pa ram key th e party's  private in formation.  For examp le, in the  case
  496        * of  the Diffie -Hellman k ey agreeme nt, this w ould be th e party's  own
  497        * Dif fie-Hellma n private  key.
  498        * @pa ram params  the key a greement p arameters
  499        *
  500        * @ex ception In validKeyEx ception if  the given  key is
  501        * ina ppropriate  for this  key agreem ent, e.g.,  is of the  wrong typ e or
  502        * has  an incomp atible alg orithm typ e.
  503        * @ex ception In validAlgor ithmParame terExcepti on if the  given para meters
  504        * are  inappropr iate for t his key ag reement.
  505        */
  506       public  final voi d init(Key  key, Algo rithmParam eterSpec p arams)
  507           th rows Inval idKeyExcep tion, Inva lidAlgorit hmParamete rException
  508       {
  509           in it(key, pa rams, JceS ecurity.RA NDOM);
  510       }
  511  
  512       /**
  513        * Ini tializes t his key ag reement wi th the giv en key, se t of
  514        * alg orithm par ameters, a nd source  of randomn ess.
  515        *
  516        * @pa ram key th e party's  private in formation.  For examp le, in the  case
  517        * of  the Diffie -Hellman k ey agreeme nt, this w ould be th e party's  own
  518        * Dif fie-Hellma n private  key.
  519        * @pa ram params  the key a greement p arameters
  520        * @pa ram random  the sourc e of rando mness
  521        *
  522        * @ex ception In validKeyEx ception if  the given  key is
  523        * ina ppropriate  for this  key agreem ent, e.g.,  is of the  wrong typ e or
  524        * has  an incomp atible alg orithm typ e.
  525        * @ex ception In validAlgor ithmParame terExcepti on if the  given para meters
  526        * are  inappropr iate for t his key ag reement.
  527        */
  528       public  final voi d init(Key  key, Algo rithmParam eterSpec p arams,
  529                                Sec ureRandom  random)
  530           th rows Inval idKeyExcep tion, Inva lidAlgorit hmParamete rException
  531       {
  532           if  (spi != n ull) {
  533                spi.engi neInit(key , params,  random);
  534           }  else {
  535                choosePr ovider(I_P ARAMS, key , params,  random);
  536           }
  537  
  538           if  (!skipDeb ug && pdeb ug != null ) {
  539                pdebug.p rintln("Ke yAgreement ." + algor ithm + " a lgorithm f rom: " +
  540                    this .provider. getName()) ;
  541           }
  542       }
  543  
  544       /**
  545        * Exe cutes the  next phase  of this k ey agreeme nt with th e given
  546        * key  that was  received f rom one of  the other  parties i nvolved in  this key
  547        * agr eement.
  548        *
  549        * @pa ram key th e key for  this phase . For exam ple, in th e case of
  550        * Dif fie-Hellma n between  2 parties,  this woul d be the o ther party 's
  551        * Dif fie-Hellma n public k ey.
  552        * @pa ram lastPh ase flag w hich indic ates wheth er or not  this is th e last
  553        * pha se of this  key agree ment.
  554        *
  555        * @re turn the ( intermedia te) key re sulting fr om this ph ase, or nu ll
  556        * if  this phase  does not  yield a ke y
  557        *
  558        * @ex ception In validKeyEx ception if  the given  key is in appropriat e for
  559        * thi s phase.
  560        * @ex ception Il legalState Exception  if this ke y agreemen t has not  been
  561        * ini tialized.
  562        */
  563       public  final Key  doPhase(K ey key, bo olean last Phase)
  564           th rows Inval idKeyExcep tion, Ille galStateEx ception
  565       {
  566           ch ooseFirstP rovider();
  567           re turn spi.e ngineDoPha se(key, la stPhase);
  568       }
  569  
  570       /**
  571          * Generate s the shar ed  PW        and return s it in a  new buffer .
  572        *
  573        * <p> This metho d resets t his <code> KeyAgreeme nt</code>  object, so  that it
  574        * can  be reused  for furth er key agr eements. U nless this  key agree ment is
  575        * rei nitialized  with one  of the <co de>init</c ode> metho ds, the sa me
  576        * pri vate infor mation and  algorithm  parameter s will be  used for
  577        * sub sequent ke y agreemen ts.
  578        *
  579          * @return  the new bu ffer with  the shared   PW     
  580        *
  581        * @ex ception Il legalState Exception  if this ke y agreemen t has not  been
  582        * com pleted yet
  583        */
  584       public  final byt e[] genera teSecret()  throws Il legalState Exception  {
  585           ch ooseFirstP rovider();
  586           re turn spi.e ngineGener ateSecret( );
  587       }
  588  
  589       /**
  590          * Generate s the shar ed  PW      , and plac es it into  the buffe r
  591        * <co de>sharedS ecret</cod e>, beginn ing at <co de>offset< /code> inc lusive.
  592        *
  593        * <p> If the <co de>sharedS ecret</cod e> buffer  is too sma ll to hold  the
  594        * res ult, a <co de>ShortBu fferExcept ion</code>  is thrown .
  595        * In  this case,  this call  should be  repeated  with a lar ger output  buffer.
  596        *
  597        * <p> This metho d resets t his <code> KeyAgreeme nt</code>  object, so  that it
  598        * can  be reused  for furth er key agr eements. U nless this  key agree ment is
  599        * rei nitialized  with one  of the <co de>init</c ode> metho ds, the sa me
  600        * pri vate infor mation and  algorithm  parameter s will be  used for
  601        * sub sequent ke y agreemen ts.
  602        *
  603          * @param s haredSecre t the buff er for the  shared  PW     
  604        * @pa ram offset  the offse t in <code >sharedSec ret</code>  where the
  605          * shared  PW        will be st ored
  606        *
  607        * @re turn the n umber of b ytes place d into <co de>sharedS ecret</cod e>
  608        *
  609        * @ex ception Il legalState Exception  if this ke y agreemen t has not  been
  610        * com pleted yet
  611        * @ex ception Sh ortBufferE xception i f the give n output b uffer is t oo small
  612          * to hold  the  PW     
  613        */
  614       public  final int  generateS ecret(byte [] sharedS ecret, int  offset)
  615           th rows Illeg alStateExc eption, Sh ortBufferE xception
  616       {
  617           ch ooseFirstP rovider();
  618           re turn spi.e ngineGener ateSecret( sharedSecr et, offset );
  619       }
  620  
  621       /**
  622          * Creates  the shared   PW        and return s it as a  <code>Secr etKey</cod e>
  623        * obj ect of the  specified  algorithm .
  624        *
  625        * <p> This metho d resets t his <code> KeyAgreeme nt</code>  object, so  that it
  626        * can  be reused  for furth er key agr eements. U nless this  key agree ment is
  627        * rei nitialized  with one  of the <co de>init</c ode> metho ds, the sa me
  628        * pri vate infor mation and  algorithm  parameter s will be  used for
  629        * sub sequent ke y agreemen ts.
  630        *
  631          * @param a lgorithm t he request ed  PW      -key algor ithm
  632        *
  633          * @return  the shared   PW        key
  634        *
  635        * @ex ception Il legalState Exception  if this ke y agreemen t has not  been
  636        * com pleted yet
  637          * @excepti on NoSuchA lgorithmEx ception if  the speci fied  PW      -key
  638        * alg orithm is  not availa ble
  639          * @excepti on Invalid KeyExcepti on if the  shared  PW      -key mater ial cannot
  640          * be used  to generat e a  PW        key of the  specified  algorithm  (e.g.,
  641        * the  key mater ial is too  short)
  642        */
  643       public  final Sec retKey gen erateSecre t(String a lgorithm)
  644           th rows Illeg alStateExc eption, No SuchAlgori thmExcepti on,
  645                InvalidK eyExceptio n
  646       {
  647           ch ooseFirstP rovider();
  648           re turn spi.e ngineGener ateSecret( algorithm) ;
  649       }
  650   }