173. EPMO Open Source Coordination Office Redaction File Detail Report

Produced by Araxis Merge on 9/25/2018 2:13:10 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.

173.1 Files compared

# Location File Last Modified
1 build 3.zip\build 3\MHLTH_YS_137_Source\JavaScript\resources\javaJDF-1.8.0\src\java\security KeyStore.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\java\security KeyStore.java Wed Sep 12 17:12:17 2018 UTC

173.2 Comparison summary

Description Between
Files 1 and 2
Text Blocks Lines
Unchanged 14 3974
Changed 13 28
Inserted 0 0
Removed 0 0

173.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

173.4 Active regular expressions

No regular expressions were active.

173.5 Comparison detail

  1   /*
  2    * Copyrig ht (c) 199 7, 2013, 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 va.securit y;
  27  
  28   import jav a.io.*;
  29   import jav a.net.URI;
  30   import jav a.security .cert.Cert ificate;
  31   import jav a.security .cert.X509 Certificat e;
  32   import jav a.security .cert.Cert ificateExc eption;
  33   import jav a.security .spec.Algo rithmParam eterSpec;
  34   import jav a.util.*;
  35   import jav ax.crypto. SecretKey;
  36  
  37   import jav ax.securit y.auth.Des troyFailed Exception;
  38   import jav ax.securit y.auth.cal lback.*;
  39  
  40   import sun .security. util.Debug ;
  41  
  42   /**
  43    * This cl ass repres ents a sto rage facil ity for cr yptographi c
  44    * keys an d certific ates.
  45    *
  46    * <p> A { @code KeyS tore} mana ges differ ent types  of entries .
  47    * Each ty pe of entr y implemen ts the {@c ode KeySto re.Entry}  interface.
  48    * Three b asic {@cod e KeyStore .Entry} im plementati ons are pr ovided:
  49    *
  50    * <ul>
  51    * <li><b> KeyStore.P rivateKeyE ntry</b>
  52    * <p> Thi s type of  entry hold s a crypto graphic {@ code Priva teKey},
  53    * which i s optional ly stored  in a prote cted forma t to preve nt
  54    * unautho rized acce ss.  It is  also acco mpanied by  a certifi cate chain
  55    * for the  correspon ding publi c key.
  56    *
  57    * <p> Pri vate keys  and certif icate chai ns are use d by a giv en entity  for
  58    * self-au thenticati on. Applic ations for  this auth entication  include s oftware
  59    * distrib ution orga nizations  which sign  JAR files  as part o f releasin g
  60    * and/or  licensing  software.
  61    *
  62    * <li><b> KeyStore.S ecretKeyEn try</b>
  63    * <p> Thi s type of  entry hold s a crypto graphic {@ code Secre tKey},
  64    * which i s optional ly stored  in a prote cted forma t to preve nt
  65    * unautho rized acce ss.
  66    *
  67    * <li><b> KeyStore.T rustedCert ificateEnt ry</b>
  68    * <p> Thi s type of  entry cont ains a sin gle public  key {@cod e Certific ate}
  69    * belongi ng to anot her party.  It is cal led a <i>t rusted cer tificate</ i>
  70    * because  the keyst ore owner  trusts tha t the publ ic key in  the certif icate
  71    * indeed  belongs to  the ident ity identi fied by th e <i>subje ct</i> (ow ner)
  72    * of the  certificat e.
  73    *
  74    * <p>This  type of e ntry can b e used to  authentica te other p arties.
  75    * </ul>
  76    *
  77    * <p> Eac h entry in  a keystor e is ident ified by a n "alias"  string. In  the
  78    * case of  private k eys and th eir associ ated certi ficate cha ins, these  strings
  79    * disting uish among  the diffe rent ways  in which t he entity  may authen ticate
  80    * itself.  For examp le, the en tity may a uthenticat e itself u sing diffe rent
  81    * certifi cate autho rities, or  using dif ferent pub lic key al gorithms.
  82    *
  83    * <p> Whe ther alias es are cas e sensitiv e is imple mentation  dependent.  In order
  84    * to avoi d problems , it is re commended  not to use  aliases i n a KeySto re that
  85    * only di ffer in ca se.
  86    *
  87    * <p> Whe ther keyst ores are p ersistent,  and the m echanisms  used by th e
  88    * keystor e if it is  persisten t, are not  specified  here. Thi s allows
  89    * use of  a variety  of techniq ues for pr otecting s ensitive ( e.g., priv ate or
  90    *  PW      ) keys. Sm art cards  or other i ntegrated  cryptograp hic engine s
  91    * (SafeKe yper) are  one option , and simp ler mechan isms such  as files m ay also
  92    * be used  (in a var iety of fo rmats).
  93    *
  94    * <p> Typ ical ways  to request  a KeyStor e object i nclude
  95    * relying  on the de fault type  and provi ding a spe cific keys tore type.
  96    *
  97    * <ul>
  98    * <li>To  rely on th e default  type:
  99    * <pre>
  100    *    KeyS tore ks =  KeyStore.g etInstance (KeyStore. getDefault Type());
  101    * </pre>
  102    * The sys tem will r eturn a ke ystore imp lementatio n for the  default ty pe.
  103    *
  104    * <li>To  provide a  specific k eystore ty pe:
  105    * <pre>
  106    *      Ke yStore ks  = KeyStore .getInstan ce("JKS");
  107    * </pre>
  108    * The sys tem will r eturn the  most prefe rred imple mentation  of the
  109    * specifi ed keystor e type ava ilable in  the enviro nment. <p>
  110    * </ul>
  111    *
  112    * <p> Bef ore a keys tore can b e accessed , it must  be
  113    * {@link  #load(java .io.InputS tream, cha r[]) loade d}.
  114    * <pre>
  115    *    KeyS tore ks =  KeyStore.g etInstance (KeyStore. getDefault Type());
  116    *
  117    *    // g et user pa ssword and  file inpu t stream
  118    *    char [] passwor d = getPas sword();
  119    *
  120    *    try  (FileInput Stream fis  = new Fil eInputStre am("keySto reName"))  {
  121    *         ks.load(fi s, passwor d);
  122    *    }
  123    * </pre>
  124    *
  125    * To crea te an empt y keystore  using the  above {@c ode load}  method,
  126    * pass {@ code null}  as the {@ code Input Stream} ar gument.
  127    *
  128    * <p> Onc e the keys tore has b een loaded , it is po ssible
  129    * to read  existing  entries fr om the key store, or  to write n ew entries
  130    * into th e keystore :
  131    * <pre>
  132    *    KeyS tore.Prote ctionParam eter protP aram =
  133    *         new KeySto re.Passwor dProtectio n(password );
  134    *
  135    *    // g et my priv ate key
  136    *    KeyS tore.Priva teKeyEntry  pkEntry =  (KeyStore .PrivateKe yEntry)
  137    *         ks.getEntr y("private KeyAlias",  protParam );
  138    *    Priv ateKey myP rivateKey  = pkEntry. getPrivate Key();
  139    *
  140    *      // save my   PW        key
  141    *    java x.crypto.S ecretKey m ySecretKey ;
  142    *    KeyS tore.Secre tKeyEntry  skEntry =
  143    *         new KeySto re.SecretK eyEntry(my SecretKey) ;
  144    *      ks.setEntr y(" PW      KeyAlias",  skEntry,  protParam) ;
  145    *
  146    *    // s tore away  the keysto re
  147    *    try  (FileOutpu tStream fo s = new Fi leOutputSt ream("newK eyStoreNam e")) {
  148    *         ks.store(f os, passwo rd);
  149    *    }
  150    * </pre>
  151    *
  152    * Note th at althoug h the same  password  may be use d to
  153    * load th e keystore , to prote ct the pri vate key e ntry,
  154    * to prot ect the  PW        key entry,  and to st ore the ke ystore
  155    * (as is  shown in t he sample  code above ),
  156    * differe nt passwor ds or othe r protecti on paramet ers
  157    * may als o be used.
  158    *
  159    * <p> Eve ry impleme ntation of  the Java  platform i s required  to suppor t
  160    * the fol lowing sta ndard {@co de KeyStor e} type:
  161    * <ul>
  162    * <li>{@c ode PKCS12 }</li>
  163    * </ul>
  164    * This ty pe is desc ribed in t he <a href =
  165    * "{@docR oot}/../te chnotes/gu ides/secur ity/Standa rdNames.ht ml#KeyStor e">
  166    * KeyStor e section< /a> of the
  167    * Java Cr yptography  Architect ure Standa rd Algorit hm Name Do cumentatio n.
  168    * Consult  the relea se documen tation for  your impl ementation  to see if  any
  169    * other t ypes are s upported.
  170    *
  171    * @author  Jan Luehe
  172    *
  173    * @see ja va.securit y.PrivateK ey
  174    * @see ja vax.crypto .SecretKey
  175    * @see ja va.securit y.cert.Cer tificate
  176    *
  177    * @since  1.2
  178    */
  179  
  180   public cla ss KeyStor e {
  181  
  182       privat e static f inal Debug  pdebug =
  183                             Debug. getInstanc e("provide r", "Provi der");
  184       privat e static f inal boole an skipDeb ug =
  185           De bug.isOn(" engine=")  && !Debug. isOn("keys tore");
  186  
  187       /*
  188        * Con stant to l ookup in t he Securit y properti es file to  determine
  189        * the  default k eystore ty pe.
  190        * In  the Securi ty propert ies file,  the defaul t keystore  type is g iven as:
  191        * <pr e>
  192        * key store.type =jks
  193        * </p re>
  194        */
  195       privat e static f inal Strin g KEYSTORE _TYPE = "k eystore.ty pe";
  196  
  197       // The  keystore  type
  198       privat e String t ype;
  199  
  200       // The  provider
  201       privat e Provider  provider;
  202  
  203       // The  provider  implementa tion
  204       privat e KeyStore Spi keySto reSpi;
  205  
  206       // Has  this keys tore been  initialize d (loaded) ?
  207       privat e boolean  initialize d = false;
  208  
  209       /**
  210        * A m arker inte rface for  {@code Key Store}
  211        * {@l ink #load( KeyStore.L oadStorePa rameter) l oad}
  212        * and
  213        * {@l ink #store (KeyStore. LoadStoreP arameter)  store}
  214        * par ameters.
  215        *
  216        * @si nce 1.5
  217        */
  218       public  static in terface Lo adStorePar ameter {
  219           /* *
  220            *  Gets the  parameter  used to pr otect keys tore data.
  221            *
  222            *  @return t he paramet er used to  protect k eystore da ta, or nul l
  223            * /
  224           pu blic Prote ctionParam eter getPr otectionPa rameter();
  225       }
  226  
  227       /**
  228        * A m arker inte rface for  keystore p rotection  parameters .
  229        *
  230        * <p>  The infor mation sto red in a { @code Prot ectionPara meter}
  231        * obj ect protec ts the con tents of a  keystore.
  232        * For  example,  protection  parameter s may be u sed to che ck
  233        * the  integrity  of keysto re data, o r to prote ct the
  234        * con fidentiali ty of sens itive keys tore data
  235        * (su ch as a {@ code Priva teKey}).
  236        *
  237        * @si nce 1.5
  238        */
  239       public  static in terface Pr otectionPa rameter {  }
  240  
  241       /**
  242        * A p assword-ba sed implem entation o f {@code P rotectionP arameter}.
  243        *
  244        * @si nce 1.5
  245        */
  246       public  static cl ass Passwo rdProtecti on impleme nts
  247                    Prot ectionPara meter, jav ax.securit y.auth.Des troyable {
  248  
  249           pr ivate fina l char[] p assword;
  250           pr ivate fina l String p rotectionA lgorithm;
  251           pr ivate fina l Algorith mParameter Spec prote ctionParam eters;
  252           pr ivate vola tile boole an destroy ed = false ;
  253  
  254           /* *
  255            *  Creates a  password  parameter.
  256            *
  257            *  <p> The s pecified { @code pass word} is c loned befo re it is s tored
  258            *  in the ne w {@code P asswordPro tection} o bject.
  259            *
  260            *  @param pa ssword the  password,  which may  be {@code  null}
  261            * /
  262           pu blic Passw ordProtect ion(char[]  password)  {
  263                this.pas sword = (p assword ==  null) ? n ull : pass word.clone ();
  264                this.pro tectionAlg orithm = n ull;
  265                this.pro tectionPar ameters =  null;
  266           }
  267  
  268           /* *
  269            *  Creates a  password  parameter  and specif ies the pr otection a lgorithm
  270            *  and assoc iated para meters to  use when e ncrypting  a keystore  entry.
  271            *  <p>
  272            *  The speci fied {@cod e password } is clone d before i t is store d in the
  273            *  new {@cod e Password Protection } object.
  274            *
  275            *  @param pa ssword the  password,  which may  be {@code  null}
  276            *  @param pr otectionAl gorithm th e encrypti on algorit hm name, f or
  277            *      examp le, {@code  PBEWithHm acSHA256An dAES_256}.
  278            *      See t he Cipher  section in  the <a hr ef=
  279            *  "{@docRoo t}/../tech notes/guid es/securit y/Standard Names.html #Cipher">
  280            *  Java Cryp tography A rchitectur e Standard  Algorithm  Name
  281            *  Documenta tion</a>
  282            *      for i nformation  about sta ndard encr yption alg orithm nam es.
  283            *  @param pr otectionPa rameters t he encrypt ion algori thm parame ter
  284            *      speci fication,  which may  be {@code  null}
  285            *  @exceptio n NullPoin terExcepti on if {@co de protect ionAlgorit hm} is
  286            *      {@cod e null}
  287            *
  288            *  @since 1. 8
  289            * /
  290           pu blic Passw ordProtect ion(char[]  password,  String pr otectionAl gorithm,
  291                Algorith mParameter Spec prote ctionParam eters) {
  292                if (prot ectionAlgo rithm == n ull) {
  293                    thro w new Null PointerExc eption("in valid null  input");
  294                }
  295                this.pas sword = (p assword ==  null) ? n ull : pass word.clone ();
  296                this.pro tectionAlg orithm = p rotectionA lgorithm;
  297                this.pro tectionPar ameters =  protection Parameters ;
  298           }
  299  
  300           /* *
  301            *  Gets the  name of th e protecti on algorit hm.
  302            *  If none w as set the n the keys tore provi der will u se its def ault
  303            *  protectio n algorith m. The nam e of the d efault pro tection al gorithm
  304            *  for a giv en keystor e type is  set using  the
  305            *  {@code 'k eystore.<t ype>.keyPr otectionAl gorithm'}  security p roperty.
  306            *  For examp le, the
  307            *  {@code ke ystore.PKC S12.keyPro tectionAlg orithm} pr operty sto res the
  308            *  name of t he default  key prote ction algo rithm used  for PKCS1 2
  309            *  keystores . If the s ecurity pr operty is  not set, a n
  310            *  implement ation-spec ific algor ithm will  be used.
  311            *
  312            *  @return t he algorit hm name, o r {@code n ull} if no ne was set
  313            *
  314            *  @since 1. 8
  315            * /
  316           pu blic Strin g getProte ctionAlgor ithm() {
  317                return p rotectionA lgorithm;
  318           }
  319  
  320           /* *
  321            *  Gets the  parameters  supplied  for the pr otection a lgorithm.
  322            *
  323            *  @return t he algorit hm paramet er specifi cation, or  {@code  n ull},
  324            *      if no ne was set
  325            *
  326            *  @since 1. 8
  327            * /
  328           pu blic Algor ithmParame terSpec ge tProtectio nParameter s() {
  329                return p rotectionP arameters;
  330           }
  331  
  332           /* *
  333            *  Gets the  password.
  334            *
  335            *  <p>Note t hat this m ethod retu rns a refe rence to t he passwor d.
  336            *  If a clon e of the a rray is cr eated it i s the call er's
  337            *  responsib ility to z ero out th e password  informati on
  338            *  after it  is no long er needed.
  339            *
  340            *  @see #des troy()
  341            *  @return t he passwor d, which m ay be {@co de null}
  342            *  @exceptio n IllegalS tateExcept ion if the  password  has
  343            *                been c leared (de stroyed)
  344            * /
  345           pu blic synch ronized ch ar[] getPa ssword() {
  346                if (dest royed) {
  347                    thro w new Ille galStateEx ception("p assword ha s been cle ared");
  348                }
  349                return p assword;
  350           }
  351  
  352           /* *
  353            *  Clears th e password .
  354            *
  355            *  @exceptio n DestroyF ailedExcep tion if th is method  was unable
  356            *       to c lear the p assword
  357            * /
  358           pu blic synch ronized vo id destroy () throws  DestroyFai ledExcepti on {
  359                destroye d = true;
  360                if (pass word != nu ll) {
  361                    Arra ys.fill(pa ssword, '  ');
  362                }
  363           }
  364  
  365           /* *
  366            *  Determine s if passw ord has be en cleared .
  367            *
  368            *  @return t rue if the  password  has been c leared, fa lse otherw ise
  369            * /
  370           pu blic synch ronized bo olean isDe stroyed()  {
  371                return d estroyed;
  372           }
  373       }
  374  
  375       /**
  376        * A P rotectionP arameter e ncapsulati ng a Callb ackHandler .
  377        *
  378        * @si nce 1.5
  379        */
  380       public  static cl ass Callba ckHandlerP rotection
  381                implemen ts Protect ionParamet er {
  382  
  383           pr ivate fina l Callback Handler ha ndler;
  384  
  385           /* *
  386            *  Construct s a new Ca llbackHand lerProtect ion from a
  387            *  CallbackH andler.
  388            *
  389            *  @param ha ndler the  CallbackHa ndler
  390            *  @exceptio n NullPoin terExcepti on if hand ler is nul l
  391            * /
  392           pu blic Callb ackHandler Protection (CallbackH andler han dler) {
  393                if (hand ler == nul l) {
  394                    thro w new Null PointerExc eption("ha ndler must  not be nu ll");
  395                }
  396                this.han dler = han dler;
  397           }
  398  
  399           /* *
  400            *  Returns t he Callbac kHandler.
  401            *
  402            *  @return t he Callbac kHandler.
  403            * /
  404           pu blic Callb ackHandler  getCallba ckHandler( ) {
  405                return h andler;
  406           }
  407  
  408       }
  409  
  410       /**
  411        * A m arker inte rface for  {@code Key Store} ent ry types.
  412        *
  413        * @si nce 1.5
  414        */
  415       public  static in terface En try {
  416  
  417           /* *
  418            *  Retrieves  the attri butes asso ciated wit h an entry .
  419            *  <p>
  420            *  The defau lt impleme ntation re turns an e mpty {@cod e Set}.
  421            *
  422            *  @return a n unmodifi able {@cod e Set} of  attributes , possibly  empty
  423            *
  424            *  @since 1. 8
  425            * /
  426           pu blic defau lt Set<Att ribute> ge tAttribute s() {
  427                return C ollections .<Attribut e>emptySet ();
  428           }
  429  
  430           /* *
  431            *  An attrib ute associ ated with  a keystore  entry.
  432            *  It compri ses a name  and one o r more val ues.
  433            *
  434            *  @since 1. 8
  435            * /
  436           pu blic inter face Attri bute {
  437                /**
  438                 * Retur ns the att ribute's n ame.
  439                 *
  440                 * @retu rn the att ribute nam e
  441                 */
  442                public S tring getN ame();
  443  
  444                /**
  445                 * Retur ns the att ribute's v alue.
  446                 * Multi -valued at tributes e ncode thei r values a s a single  string.
  447                 *
  448                 * @retu rn the att ribute val ue
  449                 */
  450                public S tring getV alue();
  451           }
  452       }
  453  
  454       /**
  455        * A { @code KeyS tore} entr y that hol ds a {@cod e PrivateK ey}
  456        * and  correspon ding certi ficate cha in.
  457        *
  458        * @si nce 1.5
  459        */
  460       public  static fi nal class  PrivateKey Entry impl ements Ent ry {
  461  
  462           pr ivate fina l PrivateK ey privKey ;
  463           pr ivate fina l Certific ate[] chai n;
  464           pr ivate fina l Set<Attr ibute> att ributes;
  465  
  466           /* *
  467            *  Construct s a {@code  PrivateKe yEntry} wi th a
  468            *  {@code Pr ivateKey}  and corres ponding ce rtificate  chain.
  469            *
  470            *  <p> The s pecified { @code chai n} is clon ed before  it is stor ed
  471            *  in the ne w {@code P rivateKeyE ntry} obje ct.
  472            *
  473            *  @param pr ivateKey t he {@code  PrivateKey }
  474            *  @param ch ain an arr ay of {@co de Certifi cate}s
  475            *       repr esenting t he certifi cate chain .
  476            *       The  chain must  be ordere d and cont ain a
  477            *       {@co de Certifi cate} at i ndex 0
  478            *       corr esponding  to the pri vate key.
  479            *
  480            *  @exceptio n NullPoin terExcepti on if
  481            *       {@co de private Key} or {@ code chain }
  482            *       is { @code null }
  483            *  @exceptio n IllegalA rgumentExc eption if  the specif ied chain  has a
  484            *       leng th of 0, i f the spec ified chai n does not  contain
  485            *       {@co de Certifi cate}s of  the same t ype,
  486            *       or i f the {@co de Private Key} algor ithm
  487            *       does  not match  the algor ithm of th e {@code P ublicKey}
  488            *       in t he end ent ity {@code  Certifica te} (at in dex 0)
  489            * /
  490           pu blic Priva teKeyEntry (PrivateKe y privateK ey, Certif icate[] ch ain) {
  491                this(pri vateKey, c hain, Coll ections.<A ttribute>e mptySet()) ;
  492           }
  493  
  494           /* *
  495            *  Construct s a {@code  PrivateKe yEntry} wi th a {@cod e PrivateK ey} and
  496            *  correspon ding certi ficate cha in and ass ociated en try attrib utes.
  497            *
  498            *  <p> The s pecified { @code chai n} and {@c ode attrib utes} are  cloned
  499            *  before th ey are sto red in the  new {@cod e PrivateK eyEntry} o bject.
  500            *
  501            *  @param pr ivateKey t he {@code  PrivateKey }
  502            *  @param ch ain an arr ay of {@co de Certifi cate}s
  503            *       repr esenting t he certifi cate chain .
  504            *       The  chain must  be ordere d and cont ain a
  505            *       {@co de Certifi cate} at i ndex 0
  506            *       corr esponding  to the pri vate key.
  507            *  @param at tributes t he attribu tes
  508            *
  509            *  @exceptio n NullPoin terExcepti on if {@co de private Key}, {@co de chain}
  510            *       or { @code attr ibutes} is  {@code nu ll}
  511            *  @exceptio n IllegalA rgumentExc eption if  the specif ied chain  has a
  512            *       leng th of 0, i f the spec ified chai n does not  contain
  513            *       {@co de Certifi cate}s of  the same t ype,
  514            *       or i f the {@co de Private Key} algor ithm
  515            *       does  not match  the algor ithm of th e {@code P ublicKey}
  516            *       in t he end ent ity {@code  Certifica te} (at in dex 0)
  517            *
  518            *  @since 1. 8
  519            * /
  520           pu blic Priva teKeyEntry (PrivateKe y privateK ey, Certif icate[] ch ain,
  521               Set<Attri bute> attr ibutes) {
  522  
  523                if (priv ateKey ==  null || ch ain == nul l || attri butes == n ull) {
  524                    thro w new Null PointerExc eption("in valid null  input");
  525                }
  526                if (chai n.length = = 0) {
  527                    thro w new Ille galArgumen tException
  528                                      ("invali d zero-len gth input  chain");
  529                }
  530  
  531                Certific ate[] clon edChain =  chain.clon e();
  532                String c ertType =  clonedChai n[0].getTy pe();
  533                for (int  i = 1; i  < clonedCh ain.length ; i++) {
  534                    if ( !certType. equals(clo nedChain[i ].getType( ))) {
  535                         throw new  IllegalArg umentExcep tion
  536                                      ("chain  does not c ontain cer tificates  " +
  537                                      "of the  same type" );
  538                    }
  539                }
  540                if (!pri vateKey.ge tAlgorithm ().equals
  541                             (clone dChain[0]. getPublicK ey().getAl gorithm()) ) {
  542                    thro w new Ille galArgumen tException
  543                                      ("privat e key algo rithm does  not match  " +
  544                                      "algorit hm of publ ic key in  end entity  " +
  545                                      "certifi cate (at i ndex 0)");
  546                }
  547                this.pri vKey = pri vateKey;
  548  
  549                if (clon edChain[0]  instanceo f X509Cert ificate &&
  550                    !(cl onedChain  instanceof  X509Certi ficate[]))  {
  551  
  552                    this .chain = n ew X509Cer tificate[c lonedChain .length];
  553                    Syst em.arrayco py(clonedC hain, 0,
  554                                      this.cha in, 0, clo nedChain.l ength);
  555                } else {
  556                    this .chain = c lonedChain ;
  557                }
  558  
  559                this.att ributes =
  560                    Coll ections.un modifiable Set(new Ha shSet<>(at tributes)) ;
  561           }
  562  
  563           /* *
  564            *  Gets the  {@code Pri vateKey} f rom this e ntry.
  565            *
  566            *  @return t he {@code  PrivateKey } from thi s entry
  567            * /
  568           pu blic Priva teKey getP rivateKey( ) {
  569                return p rivKey;
  570           }
  571  
  572           /* *
  573            *  Gets the  {@code Cer tificate}  chain from  this entr y.
  574            *
  575            *  <p> The s tored chai n is clone d before b eing retur ned.
  576            *
  577            *  @return a n array of  {@code Ce rtificate} s correspo nding
  578            *       to t he certifi cate chain  for the p ublic key.
  579            *       If t he certifi cates are  of type X. 509,
  580            *       the  runtime ty pe of the  returned a rray is
  581            *       {@co de X509Cer tificate[] }.
  582            * /
  583           pu blic Certi ficate[] g etCertific ateChain()  {
  584                return c hain.clone ();
  585           }
  586  
  587           /* *
  588            *  Gets the  end entity  {@code Ce rtificate}
  589            *  from the  certificat e chain in  this entr y.
  590            *
  591            *  @return t he end ent ity {@code  Certifica te} (at in dex 0)
  592            *       from  the certi ficate cha in in this  entry.
  593            *       If t he certifi cate is of  type X.50 9,
  594            *       the  runtime ty pe of the  returned c ertificate  is
  595            *       {@co de X509Cer tificate}.
  596            * /
  597           pu blic Certi ficate get Certificat e() {
  598                return c hain[0];
  599           }
  600  
  601           /* *
  602            *  Retrieves  the attri butes asso ciated wit h an entry .
  603            *  <p>
  604            *
  605            *  @return a n unmodifi able {@cod e Set} of  attributes , possibly  empty
  606            *
  607            *  @since 1. 8
  608            * /
  609           @O verride
  610           pu blic Set<A ttribute>  getAttribu tes() {
  611                return a ttributes;
  612           }
  613  
  614           /* *
  615            *  Returns a  string re presentati on of this  PrivateKe yEntry.
  616            *  @return a  string re presentati on of this  PrivateKe yEntry.
  617            * /
  618           pu blic Strin g toString () {
  619                StringBu ilder sb =  new Strin gBuilder() ;
  620                sb.appen d("Private  key entry  and certi ficate cha in with "
  621                    + ch ain.length  + " eleme nts:\r\n") ;
  622                for (Cer tificate c ert : chai n) {
  623                    sb.a ppend(cert );
  624                    sb.a ppend("\r\ n");
  625                }
  626                return s b.toString ();
  627           }
  628  
  629       }
  630  
  631       /**
  632        * A { @code KeyS tore} entr y that hol ds a {@cod e SecretKe y}.
  633        *
  634        * @si nce 1.5
  635        */
  636       public  static fi nal class  SecretKeyE ntry imple ments Entr y {
  637  
  638           pr ivate fina l SecretKe y sKey;
  639           pr ivate fina l Set<Attr ibute> att ributes;
  640  
  641           /* *
  642            *  Construct s a {@code  SecretKey Entry} wit h a
  643            *  {@code Se cretKey}.
  644            *
  645              * @param  PW      Key the {@ code Secre tKey}
  646            *
  647              * @excepti on NullPoi nterExcept ion if {@c ode  PW      Key}
  648            *       is { @code null }
  649            * /
  650             public Sec retKeyEntr y(SecretKe PW      Key) {
  651                  if ( PW      Key == nul l) {
  652                    thro w new Null PointerExc eption("in valid null  input");
  653                }
  654                  this.sKey  PW      Key;
  655                this.att ributes =  Collection s.<Attribu te>emptySe t();
  656           }
  657  
  658           /* *
  659            *  Construct s a {@code  SecretKey Entry} wit h a {@code  SecretKey } and
  660            *  associate d entry at tributes.
  661            *
  662            *  <p> The s pecified { @code attr ibutes} is  cloned be fore it is  stored
  663            *  in the ne w {@code S ecretKeyEn try} objec t.
  664            *
  665              * @param  PW      Key the {@ code Secre tKey}
  666            *  @param at tributes t he attribu tes
  667            *
  668              * @excepti on NullPoi nterExcept ion if {@c ode  PW      Key} or
  669            *      {@cod e attribut es} is {@c ode null}
  670            *
  671            *  @since 1. 8
  672            * /
  673             public Sec retKeyEntr y(SecretKe PW      Key, Set<A ttribute>  attributes ) {
  674  
  675                  if ( PW      Key == nul l || attri butes == n ull) {
  676                    thro w new Null PointerExc eption("in valid null  input");
  677                }
  678                  this.sKey  PW      Key;
  679                this.att ributes =
  680                    Coll ections.un modifiable Set(new Ha shSet<>(at tributes)) ;
  681           }
  682  
  683           /* *
  684            *  Gets the  {@code Sec retKey} fr om this en try.
  685            *
  686            *  @return t he {@code  SecretKey}  from this  entry
  687            * /
  688           pu blic Secre tKey getSe cretKey()  {
  689                return s Key;
  690           }
  691  
  692           /* *
  693            *  Retrieves  the attri butes asso ciated wit h an entry .
  694            *  <p>
  695            *
  696            *  @return a n unmodifi able {@cod e Set} of  attributes , possibly  empty
  697            *
  698            *  @since 1. 8
  699            * /
  700           @O verride
  701           pu blic Set<A ttribute>  getAttribu tes() {
  702                return a ttributes;
  703           }
  704  
  705           /* *
  706            *  Returns a  string re presentati on of this  SecretKey Entry.
  707            *  @return a  string re presentati on of this  SecretKey Entry.
  708            * /
  709           pu blic Strin g toString () {
  710                return " Secret key  entry wit h algorith m " + sKey .getAlgori thm();
  711           }
  712       }
  713  
  714       /**
  715        * A { @code KeyS tore} entr y that hol ds a trust ed
  716        * {@c ode Certif icate}.
  717        *
  718        * @si nce 1.5
  719        */
  720       public  static fi nal class  TrustedCer tificateEn try implem ents Entry  {
  721  
  722           pr ivate fina l Certific ate cert;
  723           pr ivate fina l Set<Attr ibute> att ributes;
  724  
  725           /* *
  726            *  Construct s a {@code  TrustedCe rtificateE ntry} with  a
  727            *  trusted { @code Cert ificate}.
  728            *
  729            *  @param tr ustedCert  the truste d {@code C ertificate }
  730            *
  731            *  @exceptio n NullPoin terExcepti on if
  732            *       {@co de trusted Cert} is { @code null }
  733            * /
  734           pu blic Trust edCertific ateEntry(C ertificate  trustedCe rt) {
  735                if (trus tedCert ==  null) {
  736                    thro w new Null PointerExc eption("in valid null  input");
  737                }
  738                this.cer t = truste dCert;
  739                this.att ributes =  Collection s.<Attribu te>emptySe t();
  740           }
  741  
  742           /* *
  743            *  Construct s a {@code  TrustedCe rtificateE ntry} with  a
  744            *  trusted { @code Cert ificate} a nd associa ted entry  attributes .
  745            *
  746            *  <p> The s pecified { @code attr ibutes} is  cloned be fore it is  stored
  747            *  in the ne w {@code T rustedCert ificateEnt ry} object .
  748            *
  749            *  @param tr ustedCert  the truste d {@code C ertificate }
  750            *  @param at tributes t he attribu tes
  751            *
  752            *  @exceptio n NullPoin terExcepti on if {@co de trusted Cert} or
  753            *      {@cod e attribut es} is {@c ode null}
  754            *
  755            *  @since 1. 8
  756            * /
  757           pu blic Trust edCertific ateEntry(C ertificate  trustedCe rt,
  758               Set<Attri bute> attr ibutes) {
  759                if (trus tedCert ==  null || a ttributes  == null) {
  760                    thro w new Null PointerExc eption("in valid null  input");
  761                }
  762                this.cer t = truste dCert;
  763                this.att ributes =
  764                    Coll ections.un modifiable Set(new Ha shSet<>(at tributes)) ;
  765           }
  766  
  767           /* *
  768            *  Gets the  trusted {@ code Certf icate} fro m this ent ry.
  769            *
  770            *  @return t he trusted  {@code Ce rtificate}  from this  entry
  771            * /
  772           pu blic Certi ficate get TrustedCer tificate()  {
  773                return c ert;
  774           }
  775  
  776           /* *
  777            *  Retrieves  the attri butes asso ciated wit h an entry .
  778            *  <p>
  779            *
  780            *  @return a n unmodifi able {@cod e Set} of  attributes , possibly  empty
  781            *
  782            *  @since 1. 8
  783            * /
  784           @O verride
  785           pu blic Set<A ttribute>  getAttribu tes() {
  786                return a ttributes;
  787           }
  788  
  789           /* *
  790            *  Returns a  string re presentati on of this  TrustedCe rtificateE ntry.
  791            *  @return a  string re presentati on of this  TrustedCe rtificateE ntry.
  792            * /
  793           pu blic Strin g toString () {
  794                return " Trusted ce rtificate  entry:\r\n " + cert.t oString();
  795           }
  796       }
  797  
  798       /**
  799        * Cre ates a Key Store obje ct of the  given type , and enca psulates t he given
  800        * pro vider impl ementation  (SPI obje ct) in it.
  801        *
  802        * @pa ram keySto reSpi the  provider i mplementat ion.
  803        * @pa ram provid er the pro vider.
  804        * @pa ram type t he keystor e type.
  805        */
  806       protec ted KeySto re(KeyStor eSpi keySt oreSpi, Pr ovider pro vider, Str ing type)
  807       {
  808           th is.keyStor eSpi = key StoreSpi;
  809           th is.provide r = provid er;
  810           th is.type =  type;
  811  
  812           if  (!skipDeb ug && pdeb ug != null ) {
  813                pdebug.p rintln("Ke yStore." +  type.toUp perCase()  + " type f rom: " +
  814                    this .provider. getName()) ;
  815           }
  816       }
  817  
  818       /**
  819        * Ret urns a key store obje ct of the  specified  type.
  820        *
  821        * <p>  This meth od travers es the lis t of regis tered secu rity Provi ders,
  822        * sta rting with  the most  preferred  Provider.
  823        * A n ew KeyStor e object e ncapsulati ng the
  824        * Key StoreSpi i mplementat ion from t he first
  825        * Pro vider that  supports  the specif ied type i s returned .
  826        *
  827        * <p>  Note that  the list  of registe red provid ers may be  retrieved  via
  828        * the  {@link Se curity#get Providers( ) Security .getProvid ers()} met hod.
  829        *
  830        * @pa ram type t he type of  keystore.
  831        * See  the KeySt ore sectio n in the < a href=
  832        * "{@ docRoot}/. ./technote s/guides/s ecurity/St andardName s.html#Key Store">
  833        * Jav a Cryptogr aphy Archi tecture St andard Alg orithm Nam e Document ation</a>
  834        * for  informati on about s tandard ke ystore typ es.
  835        *
  836        * @re turn a key store obje ct of the  specified  type.
  837        *
  838        * @ex ception Ke yStoreExce ption if n o Provider  supports  a
  839        *           KeyS toreSpi im plementati on for the
  840        *           spec ified type .
  841        *
  842        * @se e Provider
  843        */
  844       public  static Ke yStore get Instance(S tring type )
  845           th rows KeySt oreExcepti on
  846       {
  847           tr y {
  848                Object[]  objs = Se curity.get Impl(type,  "KeyStore ", (String )null);
  849                return n ew KeyStor e((KeyStor eSpi)objs[ 0], (Provi der)objs[1 ], type);
  850           }  catch (NoS uchAlgorit hmExceptio n nsae) {
  851                throw ne w KeyStore Exception( type + " n ot found",  nsae);
  852           }  catch (NoS uchProvide rException  nspe) {
  853                throw ne w KeyStore Exception( type + " n ot found",  nspe);
  854           }
  855       }
  856  
  857       /**
  858        * Ret urns a key store obje ct of the  specified  type.
  859        *
  860        * <p>  A new Key Store obje ct encapsu lating the
  861        * Key StoreSpi i mplementat ion from t he specifi ed provide r
  862        * is  returned.   The speci fied provi der must b e register ed
  863        * in  the securi ty provide r list.
  864        *
  865        * <p>  Note that  the list  of registe red provid ers may be  retrieved  via
  866        * the  {@link Se curity#get Providers( ) Security .getProvid ers()} met hod.
  867        *
  868        * @pa ram type t he type of  keystore.
  869        * See  the KeySt ore sectio n in the < a href=
  870        * "{@ docRoot}/. ./technote s/guides/s ecurity/St andardName s.html#Key Store">
  871        * Jav a Cryptogr aphy Archi tecture St andard Alg orithm Nam e Document ation</a>
  872        * for  informati on about s tandard ke ystore typ es.
  873        *
  874        * @pa ram provid er the nam e of the p rovider.
  875        *
  876        * @re turn a key store obje ct of the  specified  type.
  877        *
  878        * @ex ception Ke yStoreExce ption if a  KeyStoreS pi
  879        *           impl ementation  for the s pecified t ype is not
  880        *           avai lable from  the speci fied provi der.
  881        *
  882        * @ex ception No SuchProvid erExceptio n if the s pecified p rovider is  not
  883        *           regi stered in  the securi ty provide r list.
  884        *
  885        * @ex ception Il legalArgum entExcepti on if the  provider n ame is nul l
  886        *           or e mpty.
  887        *
  888        * @se e Provider
  889        */
  890       public  static Ke yStore get Instance(S tring type , String p rovider)
  891           th rows KeySt oreExcepti on, NoSuch ProviderEx ception
  892       {
  893           if  (provider  == null | | provider .length()  == 0)
  894                throw ne w IllegalA rgumentExc eption("mi ssing prov ider");
  895           tr y {
  896                Object[]  objs = Se curity.get Impl(type,  "KeyStore ", provide r);
  897                return n ew KeyStor e((KeyStor eSpi)objs[ 0], (Provi der)objs[1 ], type);
  898           }  catch (NoS uchAlgorit hmExceptio n nsae) {
  899                throw ne w KeyStore Exception( type + " n ot found",  nsae);
  900           }
  901       }
  902  
  903       /**
  904        * Ret urns a key store obje ct of the  specified  type.
  905        *
  906        * <p>  A new Key Store obje ct encapsu lating the
  907        * Key StoreSpi i mplementat ion from t he specifi ed Provide r
  908        * obj ect is ret urned.  No te that th e specifie d Provider  object
  909        * doe s not have  to be reg istered in  the provi der list.
  910        *
  911        * @pa ram type t he type of  keystore.
  912        * See  the KeySt ore sectio n in the < a href=
  913        * "{@ docRoot}/. ./technote s/guides/s ecurity/St andardName s.html#Key Store">
  914        * Jav a Cryptogr aphy Archi tecture St andard Alg orithm Nam e Document ation</a>
  915        * for  informati on about s tandard ke ystore typ es.
  916        *
  917        * @pa ram provid er the pro vider.
  918        *
  919        * @re turn a key store obje ct of the  specified  type.
  920        *
  921        * @ex ception Ke yStoreExce ption if K eyStoreSpi
  922        *           impl ementation  for the s pecified t ype is not  available
  923        *           from  the speci fied Provi der object .
  924        *
  925        * @ex ception Il legalArgum entExcepti on if the  specified  provider i s null.
  926        *
  927        * @se e Provider
  928        *
  929        * @si nce 1.4
  930        */
  931       public  static Ke yStore get Instance(S tring type , Provider  provider)
  932           th rows KeySt oreExcepti on
  933       {
  934           if  (provider  == null)
  935                throw ne w IllegalA rgumentExc eption("mi ssing prov ider");
  936           tr y {
  937                Object[]  objs = Se curity.get Impl(type,  "KeyStore ", provide r);
  938                return n ew KeyStor e((KeyStor eSpi)objs[ 0], (Provi der)objs[1 ], type);
  939           }  catch (NoS uchAlgorit hmExceptio n nsae) {
  940                throw ne w KeyStore Exception( type + " n ot found",  nsae);
  941           }
  942       }
  943  
  944       /**
  945        * Ret urns the d efault key store type  as specif ied by the
  946        * {@c ode keysto re.type} s ecurity pr operty, or  the strin g
  947        * {@l iteral "jk s"} (acron ym for {@l iteral "Ja va keystor e"})
  948        * if  no such pr operty exi sts.
  949        *
  950        * <p> The defaul t keystore  type can  be used by  applicati ons that d o not
  951        * wan t to use a  hard-code d keystore  type when  calling o ne of the
  952        * {@c ode getIns tance} met hods, and  want to pr ovide a de fault keys tore
  953        * typ e in case  a user doe s not spec ify its ow n.
  954        *
  955        * <p> The defaul t keystore  type can  be changed  by settin g the valu e of the
  956        * {@c ode keysto re.type} s ecurity pr operty to  the desire d keystore  type.
  957        *
  958        * @re turn the d efault key store type  as specif ied by the
  959        * {@c ode keysto re.type} s ecurity pr operty, or  the strin g {@litera l "jks"}
  960        * if  no such pr operty exi sts.
  961        * @se e java.sec urity.Secu rity secur ity proper ties
  962        */
  963       public  final sta tic String  getDefaul tType() {
  964           St ring kstyp e;
  965           ks type = Acc essControl ler.doPriv ileged(new  Privilege dAction<St ring>() {
  966                public S tring run( ) {
  967                    retu rn Securit y.getPrope rty(KEYSTO RE_TYPE);
  968                }
  969           }) ;
  970           if  (kstype = = null) {
  971                kstype =  "jks";
  972           }
  973           re turn kstyp e;
  974       }
  975  
  976       /**
  977        * Ret urns the p rovider of  this keys tore.
  978        *
  979        * @re turn the p rovider of  this keys tore.
  980        */
  981       public  final Pro vider getP rovider()
  982       {
  983           re turn this. provider;
  984       }
  985  
  986       /**
  987        * Ret urns the t ype of thi s keystore .
  988        *
  989        * @re turn the t ype of thi s keystore .
  990        */
  991       public  final Str ing getTyp e()
  992       {
  993           re turn this. type;
  994       }
  995  
  996       /**
  997        * Ret urns the k ey associa ted with t he given a lias, usin g the give n
  998        * pas sword to r ecover it.   The key  must have  been assoc iated with
  999        * the  alias by  a call to  {@code set KeyEntry},
  1000        * or  by a call  to {@code  setEntry}  with a
  1001        * {@c ode Privat eKeyEntry}  or {@code  SecretKey Entry}.
  1002        *
  1003        * @pa ram alias  the alias  name
  1004        * @pa ram passwo rd the pas sword for  recovering  the key
  1005        *
  1006        * @re turn the r equested k ey, or nul l if the g iven alias  does not  exist
  1007        * or  does not i dentify a  key-relate d entry.
  1008        *
  1009        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized
  1010        * (lo aded).
  1011        * @ex ception No SuchAlgori thmExcepti on if the  algorithm  for recove ring the
  1012        * key  cannot be  found
  1013        * @ex ception Un recoverabl eKeyExcept ion if the  key canno t be recov ered
  1014        * (e. g., the gi ven passwo rd is wron g).
  1015        */
  1016       public  final Key  getKey(St ring alias , char[] p assword)
  1017           th rows KeySt oreExcepti on, NoSuch AlgorithmE xception,
  1018                Unrecove rableKeyEx ception
  1019       {
  1020           if  (!initial ized) {
  1021                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1022           }
  1023           re turn keySt oreSpi.eng ineGetKey( alias, pas sword);
  1024       }
  1025  
  1026       /**
  1027        * Ret urns the c ertificate  chain ass ociated wi th the giv en alias.
  1028        * The  certifica te chain m ust have b een associ ated with  the alias
  1029        * by  a call to  {@code set KeyEntry},
  1030        * or  by a call  to {@code  setEntry}  with a
  1031        * {@c ode Privat eKeyEntry} .
  1032        *
  1033        * @pa ram alias  the alias  name
  1034        *
  1035        * @re turn the c ertificate  chain (or dered with  the user' s certific ate first
  1036        * fol lowed by z ero or mor e certific ate author ities), or  null if t he given a lias
  1037        * doe s not exis t or does  not contai n a certif icate chai n
  1038        *
  1039        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized
  1040        * (lo aded).
  1041        */
  1042       public  final Cer tificate[]  getCertif icateChain (String al ias)
  1043           th rows KeySt oreExcepti on
  1044       {
  1045           if  (!initial ized) {
  1046                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1047           }
  1048           re turn keySt oreSpi.eng ineGetCert ificateCha in(alias);
  1049       }
  1050  
  1051       /**
  1052        * Ret urns the c ertificate  associate d with the  given ali as.
  1053        *
  1054        * <p>  If the gi ven alias  name ident ifies an e ntry
  1055        * cre ated by a  call to {@ code setCe rtificateE ntry},
  1056        * or  created by  a call to  {@code se tEntry} wi th a
  1057        * {@c ode Truste dCertifica teEntry},
  1058        * the n the trus ted certif icate cont ained in t hat entry  is returne d.
  1059        *
  1060        * <p>  If the gi ven alias  name ident ifies an e ntry
  1061        * cre ated by a  call to {@ code setKe yEntry},
  1062        * or  created by  a call to  {@code se tEntry} wi th a
  1063        * {@c ode Privat eKeyEntry} ,
  1064        * the n the firs t element  of the cer tificate c hain in th at entry
  1065        * is  returned.
  1066        *
  1067        * @pa ram alias  the alias  name
  1068        *
  1069        * @re turn the c ertificate , or null  if the giv en alias d oes not ex ist or
  1070        * doe s not cont ain a cert ificate.
  1071        *
  1072        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized
  1073        * (lo aded).
  1074        */
  1075       public  final Cer tificate g etCertific ate(String  alias)
  1076           th rows KeySt oreExcepti on
  1077       {
  1078           if  (!initial ized) {
  1079                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1080           }
  1081           re turn keySt oreSpi.eng ineGetCert ificate(al ias);
  1082       }
  1083  
  1084       /**
  1085        * Ret urns the c reation da te of the  entry iden tified by  the given  alias.
  1086        *
  1087        * @pa ram alias  the alias  name
  1088        *
  1089        * @re turn the c reation da te of this  entry, or  null if t he given a lias does
  1090        * not  exist
  1091        *
  1092        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized
  1093        * (lo aded).
  1094        */
  1095       public  final Dat e getCreat ionDate(St ring alias )
  1096           th rows KeySt oreExcepti on
  1097       {
  1098           if  (!initial ized) {
  1099                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1100           }
  1101           re turn keySt oreSpi.eng ineGetCrea tionDate(a lias);
  1102       }
  1103  
  1104       /**
  1105        * Ass igns the g iven key t o the give n alias, p rotecting  it with th e given
  1106        * pas sword.
  1107        *
  1108        * <p> If the giv en key is  of type {@ code java. security.P rivateKey} ,
  1109        * it  must be ac companied  by a certi ficate cha in certify ing the
  1110        * cor responding  public ke y.
  1111        *
  1112        * <p> If the giv en alias a lready exi sts, the k eystore in formation
  1113        * ass ociated wi th it is o verridden  by the giv en key (an d possibly
  1114        * cer tificate c hain).
  1115        *
  1116        * @pa ram alias  the alias  name
  1117        * @pa ram key th e key to b e associat ed with th e alias
  1118        * @pa ram passwo rd the pas sword to p rotect the  key
  1119        * @pa ram chain  the certif icate chai n for the  correspond ing public
  1120        * key  (only req uired if t he given k ey is of t ype
  1121        * {@c ode java.s ecurity.Pr ivateKey}) .
  1122        *
  1123        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized
  1124        * (lo aded), the  given key  cannot be  protected , or this  operation  fails
  1125        * for  some othe r reason
  1126        */
  1127       public  final voi d setKeyEn try(String  alias, Ke y key, cha r[] passwo rd,
  1128                                        Certif icate[] ch ain)
  1129           th rows KeySt oreExcepti on
  1130       {
  1131           if  (!initial ized) {
  1132                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1133           }
  1134           if  ((key ins tanceof Pr ivateKey)  &&
  1135                (chain = = null ||  chain.leng th == 0))  {
  1136                throw ne w IllegalA rgumentExc eption("Pr ivate key  must be "
  1137                                                      + " accompanie d by certi ficate "
  1138                                                      + " chain");
  1139           }
  1140           ke yStoreSpi. engineSetK eyEntry(al ias, key,  password,  chain);
  1141       }
  1142  
  1143       /**
  1144        * Ass igns the g iven key ( that has a lready bee n protecte d) to the  given
  1145        * ali as.
  1146        *
  1147        * <p> If the pro tected key  is of typ e
  1148        * {@c ode java.s ecurity.Pr ivateKey},  it must b e accompan ied by a
  1149        * cer tificate c hain certi fying the  correspond ing public  key. If t he
  1150        * und erlying ke ystore imp lementatio n is of ty pe {@code  jks},
  1151        * {@c ode key} m ust be enc oded as an
  1152        * {@c ode Encryp tedPrivate KeyInfo} a s defined  in the PKC S #8 stand ard.
  1153        *
  1154        * <p> If the giv en alias a lready exi sts, the k eystore in formation
  1155        * ass ociated wi th it is o verridden  by the giv en key (an d possibly
  1156        * cer tificate c hain).
  1157        *
  1158        * @pa ram alias  the alias  name
  1159        * @pa ram key th e key (in  protected  format) to  be associ ated with  the alias
  1160        * @pa ram chain  the certif icate chai n for the  correspond ing public
  1161        *           key  (only usef ul if the  protected  key is of  type
  1162        *           {@co de java.se curity.Pri vateKey}).
  1163        *
  1164        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized
  1165        * (lo aded), or  if this op eration fa ils for so me other r eason.
  1166        */
  1167       public  final voi d setKeyEn try(String  alias, by te[] key,
  1168                                        Certif icate[] ch ain)
  1169           th rows KeySt oreExcepti on
  1170       {
  1171           if  (!initial ized) {
  1172                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1173           }
  1174           ke yStoreSpi. engineSetK eyEntry(al ias, key,  chain);
  1175       }
  1176  
  1177       /**
  1178        * Ass igns the g iven trust ed certifi cate to th e given al ias.
  1179        *
  1180        * <p>  If the gi ven alias  identifies  an existi ng entry
  1181        * cre ated by a  call to {@ code setCe rtificateE ntry},
  1182        * or  created by  a call to  {@code se tEntry} wi th a
  1183        * {@c ode Truste dCertifica teEntry},
  1184        * the  trusted c ertificate  in the ex isting ent ry
  1185        * is  overridden  by the gi ven certif icate.
  1186        *
  1187        * @pa ram alias  the alias  name
  1188        * @pa ram cert t he certifi cate
  1189        *
  1190        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized,
  1191        * or  the given  alias alre ady exists  and does  not identi fy an
  1192        * ent ry contain ing a trus ted certif icate,
  1193        * or  this opera tion fails  for some  other reas on.
  1194        */
  1195       public  final voi d setCerti ficateEntr y(String a lias, Cert ificate ce rt)
  1196           th rows KeySt oreExcepti on
  1197       {
  1198           if  (!initial ized) {
  1199                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1200           }
  1201           ke yStoreSpi. engineSetC ertificate Entry(alia s, cert);
  1202       }
  1203  
  1204       /**
  1205        * Del etes the e ntry ident ified by t he given a lias from  this keyst ore.
  1206        *
  1207        * @pa ram alias  the alias  name
  1208        *
  1209        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized,
  1210        * or  if the ent ry cannot  be removed .
  1211        */
  1212       public  final voi d deleteEn try(String  alias)
  1213           th rows KeySt oreExcepti on
  1214       {
  1215           if  (!initial ized) {
  1216                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1217           }
  1218           ke yStoreSpi. engineDele teEntry(al ias);
  1219       }
  1220  
  1221       /**
  1222        * Lis ts all the  alias nam es of this  keystore.
  1223        *
  1224        * @re turn enume ration of  the alias  names
  1225        *
  1226        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized
  1227        * (lo aded).
  1228        */
  1229       public  final Enu meration<S tring> ali ases()
  1230           th rows KeySt oreExcepti on
  1231       {
  1232           if  (!initial ized) {
  1233                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1234           }
  1235           re turn keySt oreSpi.eng ineAliases ();
  1236       }
  1237  
  1238       /**
  1239        * Che cks if the  given ali as exists  in this ke ystore.
  1240        *
  1241        * @pa ram alias  the alias  name
  1242        *
  1243        * @re turn true  if the ali as exists,  false oth erwise
  1244        *
  1245        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized
  1246        * (lo aded).
  1247        */
  1248       public  final boo lean conta insAlias(S tring alia s)
  1249           th rows KeySt oreExcepti on
  1250       {
  1251           if  (!initial ized) {
  1252                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1253           }
  1254           re turn keySt oreSpi.eng ineContain sAlias(ali as);
  1255       }
  1256  
  1257       /**
  1258        * Ret rieves the  number of  entries i n this key store.
  1259        *
  1260        * @re turn the n umber of e ntries in  this keyst ore
  1261        *
  1262        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized
  1263        * (lo aded).
  1264        */
  1265       public  final int  size()
  1266           th rows KeySt oreExcepti on
  1267       {
  1268           if  (!initial ized) {
  1269                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1270           }
  1271           re turn keySt oreSpi.eng ineSize();
  1272       }
  1273  
  1274       /**
  1275        * Ret urns true  if the ent ry identif ied by the  given ali as
  1276        * was  created b y a call t o {@code s etKeyEntry },
  1277        * or  created by  a call to  {@code se tEntry} wi th a
  1278        * {@c ode Privat eKeyEntry}  or a {@co de SecretK eyEntry}.
  1279        *
  1280        * @pa ram alias  the alias  for the ke ystore ent ry to be c hecked
  1281        *
  1282        * @re turn true  if the ent ry identif ied by the  given ali as is a
  1283        * key -related e ntry, fals e otherwis e.
  1284        *
  1285        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized
  1286        * (lo aded).
  1287        */
  1288       public  final boo lean isKey Entry(Stri ng alias)
  1289           th rows KeySt oreExcepti on
  1290       {
  1291           if  (!initial ized) {
  1292                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1293           }
  1294           re turn keySt oreSpi.eng ineIsKeyEn try(alias) ;
  1295       }
  1296  
  1297       /**
  1298        * Ret urns true  if the ent ry identif ied by the  given ali as
  1299        * was  created b y a call t o {@code s etCertific ateEntry},
  1300        * or  created by  a call to  {@code se tEntry} wi th a
  1301        * {@c ode Truste dCertifica teEntry}.
  1302        *
  1303        * @pa ram alias  the alias  for the ke ystore ent ry to be c hecked
  1304        *
  1305        * @re turn true  if the ent ry identif ied by the  given ali as contain s a
  1306        * tru sted certi ficate, fa lse otherw ise.
  1307        *
  1308        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized
  1309        * (lo aded).
  1310        */
  1311       public  final boo lean isCer tificateEn try(String  alias)
  1312           th rows KeySt oreExcepti on
  1313       {
  1314           if  (!initial ized) {
  1315                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1316           }
  1317           re turn keySt oreSpi.eng ineIsCerti ficateEntr y(alias);
  1318       }
  1319  
  1320       /**
  1321        * Ret urns the ( alias) nam e of the f irst keyst ore entry  whose cert ificate
  1322        * mat ches the g iven certi ficate.
  1323        *
  1324        * <p>  This meth od attempt s to match  the given  certifica te with ea ch
  1325        * key store entr y. If the  entry bein g consider ed was
  1326        * cre ated by a  call to {@ code setCe rtificateE ntry},
  1327        * or  created by  a call to  {@code se tEntry} wi th a
  1328        * {@c ode Truste dCertifica teEntry},
  1329        * the n the give n certific ate is com pared to t hat entry' s certific ate.
  1330        *
  1331        * <p>  If the en try being  considered  was
  1332        * cre ated by a  call to {@ code setKe yEntry},
  1333        * or  created by  a call to  {@code se tEntry} wi th a
  1334        * {@c ode Privat eKeyEntry} ,
  1335        * the n the give n certific ate is com pared to t he first
  1336        * ele ment of th at entry's  certifica te chain.
  1337        *
  1338        * @pa ram cert t he certifi cate to ma tch with.
  1339        *
  1340        * @re turn the a lias name  of the fir st entry w ith a matc hing certi ficate,
  1341        * or  null if no  such entr y exists i n this key store.
  1342        *
  1343        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized
  1344        * (lo aded).
  1345        */
  1346       public  final Str ing getCer tificateAl ias(Certif icate cert )
  1347           th rows KeySt oreExcepti on
  1348       {
  1349           if  (!initial ized) {
  1350                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1351           }
  1352           re turn keySt oreSpi.eng ineGetCert ificateAli as(cert);
  1353       }
  1354  
  1355       /**
  1356        * Sto res this k eystore to  the given  output st ream, and  protects i ts
  1357        * int egrity wit h the give n password .
  1358        *
  1359        * @pa ram stream  the outpu t stream t o which th is keystor e is writt en.
  1360        * @pa ram passwo rd the pas sword to g enerate th e keystore  integrity  check
  1361        *
  1362        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized
  1363        * (lo aded).
  1364        * @ex ception IO Exception  if there w as an I/O  problem wi th data
  1365        * @ex ception No SuchAlgori thmExcepti on if the  appropriat e data int egrity
  1366        * alg orithm cou ld not be  found
  1367        * @ex ception Ce rtificateE xception i f any of t he certifi cates incl uded in
  1368        * the  keystore  data could  not be st ored
  1369        */
  1370       public  final voi d store(Ou tputStream  stream, c har[] pass word)
  1371           th rows KeySt oreExcepti on, IOExce ption, NoS uchAlgorit hmExceptio n,
  1372                Certific ateExcepti on
  1373       {
  1374           if  (!initial ized) {
  1375                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1376           }
  1377           ke yStoreSpi. engineStor e(stream,  password);
  1378       }
  1379  
  1380       /**
  1381        * Sto res this k eystore us ing the gi ven {@code  LoadStore Parameter} .
  1382        *
  1383        * @pa ram param  the {@code  LoadStore Parameter}
  1384        *           that  specifies  how to st ore the ke ystore,
  1385        *           whic h may be { @code null }
  1386        *
  1387        * @ex ception Il legalArgum entExcepti on if the  given
  1388        *           {@co de LoadSto reParamete r}
  1389        *           inpu t is not r ecognized
  1390        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized
  1391        *           (loa ded)
  1392        * @ex ception IO Exception  if there w as an I/O  problem wi th data
  1393        * @ex ception No SuchAlgori thmExcepti on if the  appropriat e data int egrity
  1394        *           algo rithm coul d not be f ound
  1395        * @ex ception Ce rtificateE xception i f any of t he certifi cates incl uded in
  1396        *           the  keystore d ata could  not be sto red
  1397        *
  1398        * @si nce 1.5
  1399        */
  1400       public  final voi d store(Lo adStorePar ameter par am)
  1401                    thro ws KeyStor eException , IOExcept ion,
  1402                    NoSu chAlgorith mException , Certific ateExcepti on {
  1403           if  (!initial ized) {
  1404                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1405           }
  1406           ke yStoreSpi. engineStor e(param);
  1407       }
  1408  
  1409       /**
  1410        * Loa ds this Ke yStore fro m the give n input st ream.
  1411        *
  1412        * <p> A password  may be gi ven to unl ock the ke ystore
  1413        * (e. g. the key store resi des on a h ardware to ken device ),
  1414        * or  to check t he integri ty of the  keystore d ata.
  1415        * If  a password  is not gi ven for in tegrity ch ecking,
  1416        * the n integrit y checking  is not pe rformed.
  1417        *
  1418        * <p> In order t o create a n empty ke ystore, or  if the ke ystore can not
  1419        * be  initialize d from a s tream, pas s {@code n ull}
  1420        * as  the {@code  stream} a rgument.
  1421        *
  1422        * <p>  Note that  if this k eystore ha s already  been loade d, it is
  1423        * rei nitialized  and loade d again fr om the giv en input s tream.
  1424        *
  1425        * @pa ram stream  the input  stream fr om which t he keystor e is loade d,
  1426        * or  {@code nul l}
  1427        * @pa ram passwo rd the pas sword used  to check  the integr ity of
  1428        * the  keystore,  the passw ord used t o unlock t he keystor e,
  1429        * or  {@code nul l}
  1430        *
  1431        * @ex ception IO Exception  if there i s an I/O o r format p roblem wit h the
  1432        * key store data , if a pas sword is r equired bu t not give n,
  1433        * or  if the giv en passwor d was inco rrect. If  the error  is due to  a
  1434        * wro ng passwor d, the {@l ink Throwa ble#getCau se cause}  of the
  1435        * {@c ode IOExce ption} sho uld be an
  1436        * {@c ode Unreco verableKey Exception}
  1437        * @ex ception No SuchAlgori thmExcepti on if the  algorithm  used to ch eck
  1438        * the  integrity  of the ke ystore can not be fou nd
  1439        * @ex ception Ce rtificateE xception i f any of t he certifi cates in t he
  1440        * key store coul d not be l oaded
  1441        */
  1442       public  final voi d load(Inp utStream s tream, cha r[] passwo rd)
  1443           th rows IOExc eption, No SuchAlgori thmExcepti on, Certif icateExcep tion
  1444       {
  1445           ke yStoreSpi. engineLoad (stream, p assword);
  1446           in itialized  = true;
  1447       }
  1448  
  1449       /**
  1450        * Loa ds this ke ystore usi ng the giv en {@code  LoadStoreP arameter}.
  1451        *
  1452        * <p>  Note that  if this K eyStore ha s already  been loade d, it is
  1453        * rei nitialized  and loade d again fr om the giv en paramet er.
  1454        *
  1455        * @pa ram param  the {@code  LoadStore Parameter}
  1456        *           that  specifies  how to lo ad the key store,
  1457        *           whic h may be { @code null }
  1458        *
  1459        * @ex ception Il legalArgum entExcepti on if the  given
  1460        *           {@co de LoadSto reParamete r}
  1461        *           inpu t is not r ecognized
  1462        * @ex ception IO Exception  if there i s an I/O o r format p roblem wit h the
  1463        *           keys tore data.  If the er ror is due  to an inc orrect
  1464        *          {@cod e Protecti onParamete r} (e.g. w rong passw ord)
  1465        *          the { @link Thro wable#getC ause cause } of the
  1466        *          {@cod e IOExcept ion} shoul d be an
  1467        *          {@cod e Unrecove rableKeyEx ception}
  1468        * @ex ception No SuchAlgori thmExcepti on if the  algorithm  used to ch eck
  1469        *           the  integrity  of the key store cann ot be foun d
  1470        * @ex ception Ce rtificateE xception i f any of t he certifi cates in t he
  1471        *           keys tore could  not be lo aded
  1472        *
  1473        * @si nce 1.5
  1474        */
  1475       public  final voi d load(Loa dStorePara meter para m)
  1476                    thro ws IOExcep tion, NoSu chAlgorith mException ,
  1477                    Cert ificateExc eption {
  1478  
  1479           ke yStoreSpi. engineLoad (param);
  1480           in itialized  = true;
  1481       }
  1482  
  1483       /**
  1484        * Get s a keysto re {@code  Entry} for  the speci fied alias
  1485        * wit h the spec ified prot ection par ameter.
  1486        *
  1487        * @pa ram alias  get the ke ystore {@c ode Entry}  for this  alias
  1488        * @pa ram protPa ram the {@ code Prote ctionParam eter}
  1489        *           used  to protec t the {@co de Entry},
  1490        *           whic h may be { @code null }
  1491        *
  1492        * @re turn the k eystore {@ code Entry } for the  specified  alias,
  1493        *           or { @code null } if there  is no suc h entry
  1494        *
  1495        * @ex ception Nu llPointerE xception i f
  1496        *           {@co de alias}  is {@code  null}
  1497        * @ex ception No SuchAlgori thmExcepti on if the  algorithm  for recove ring the
  1498        *           entr y cannot b e found
  1499        * @ex ception Un recoverabl eEntryExce ption if t he specifi ed
  1500        *           {@co de protPar am} were i nsufficien t or inval id
  1501        * @ex ception Un recoverabl eKeyExcept ion if the  entry is  a
  1502        *           {@co de Private KeyEntry}  or {@code  SecretKeyE ntry}
  1503        *           and  the specif ied {@code  protParam } does not  contain
  1504        *           the  informatio n needed t o recover  the key (e .g. wrong  password)
  1505        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized
  1506        *           (loa ded).
  1507        * @se e #setEntr y(String,  KeyStore.E ntry, KeyS tore.Prote ctionParam eter)
  1508        *
  1509        * @si nce 1.5
  1510        */
  1511       public  final Ent ry getEntr y(String a lias, Prot ectionPara meter prot Param)
  1512                    thro ws NoSuchA lgorithmEx ception, U nrecoverab leEntryExc eption,
  1513                    KeyS toreExcept ion {
  1514  
  1515           if  (alias ==  null) {
  1516                throw ne w NullPoin terExcepti on("invali d null inp ut");
  1517           }
  1518           if  (!initial ized) {
  1519                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1520           }
  1521           re turn keySt oreSpi.eng ineGetEntr y(alias, p rotParam);
  1522       }
  1523  
  1524       /**
  1525        * Sav es a keyst ore {@code  Entry} un der the sp ecified al ias.
  1526        * The  protectio n paramete r is used  to protect  the
  1527        * {@c ode Entry} .
  1528        *
  1529        * <p>  If an ent ry already  exists fo r the spec ified alia s,
  1530        * it  is overrid den.
  1531        *
  1532        * @pa ram alias  save the k eystore {@ code Entry } under th is alias
  1533        * @pa ram entry  the {@code  Entry} to  save
  1534        * @pa ram protPa ram the {@ code Prote ctionParam eter}
  1535        *           used  to protec t the {@co de Entry},
  1536        *           whic h may be { @code null }
  1537        *
  1538        * @ex ception Nu llPointerE xception i f
  1539        *           {@co de alias}  or {@code  entry}
  1540        *           is { @code null }
  1541        * @ex ception Ke yStoreExce ption if t he keystor e has not  been initi alized
  1542        *           (loa ded), or i f this ope ration fai ls for som e other re ason
  1543        *
  1544        * @se e #getEntr y(String,  KeyStore.P rotectionP arameter)
  1545        *
  1546        * @si nce 1.5
  1547        */
  1548       public  final voi d setEntry (String al ias, Entry  entry,
  1549                             Protec tionParame ter protPa ram)
  1550                    thro ws KeyStor eException  {
  1551           if  (alias ==  null || e ntry == nu ll) {
  1552                throw ne w NullPoin terExcepti on("invali d null inp ut");
  1553           }
  1554           if  (!initial ized) {
  1555                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1556           }
  1557           ke yStoreSpi. engineSetE ntry(alias , entry, p rotParam);
  1558       }
  1559  
  1560       /**
  1561        * Det ermines if  the keyst ore {@code  Entry} fo r the spec ified
  1562        * {@c ode alias}  is an ins tance or s ubclass of  the speci fied
  1563        * {@c ode entryC lass}.
  1564        *
  1565        * @pa ram alias  the alias  name
  1566        * @pa ram entryC lass the e ntry class
  1567        *
  1568        * @re turn true  if the key store {@co de Entry}  for the sp ecified
  1569        *           {@co de alias}  is an inst ance or su bclass of  the
  1570        *           spec ified {@co de entryCl ass}, fals e otherwis e
  1571        *
  1572        * @ex ception Nu llPointerE xception i f
  1573        *           {@co de alias}  or {@code  entryClass }
  1574        *           is { @code null }
  1575        * @ex ception Ke yStoreExce ption if t he keystor e has not  been
  1576        *           init ialized (l oaded)
  1577        *
  1578        * @si nce 1.5
  1579        */
  1580       public  final boo lean
  1581           en tryInstanc eOf(String  alias,
  1582                             Class< ? extends  KeyStore.E ntry> entr yClass)
  1583           th rows KeySt oreExcepti on
  1584       {
  1585  
  1586           if  (alias ==  null || e ntryClass  == null) {
  1587                throw ne w NullPoin terExcepti on("invali d null inp ut");
  1588           }
  1589           if  (!initial ized) {
  1590                throw ne w KeyStore Exception( "Uninitial ized keyst ore");
  1591           }
  1592           re turn keySt oreSpi.eng ineEntryIn stanceOf(a lias, entr yClass);
  1593       }
  1594  
  1595       /**
  1596        * A d escription  of a to-b e-instanti ated KeySt ore object .
  1597        *
  1598        * <p> An instanc e of this  class enca psulates t he informa tion neede d to
  1599        * ins tantiate a nd initial ize a KeyS tore objec t. That pr ocess is
  1600        * tri ggered whe n the {@li nkplain #g etKeyStore } method i s called.
  1601        *
  1602        * <p> This makes  it possib le to deco uple confi guration f rom KeySto re
  1603        * obj ect creati on and e.g . delay a  password p rompt unti l it is
  1604        * nee ded.
  1605        *
  1606        * @se e KeyStore
  1607        * @se e javax.ne t.ssl.KeyS toreBuilde rParameter s
  1608        * @si nce 1.5
  1609        */
  1610       public  static ab stract cla ss Builder  {
  1611  
  1612           //  maximum t imes to tr y the call backhandle r if the p assword is  wrong
  1613           st atic final  int MAX_C ALLBACK_TR IES = 3;
  1614  
  1615           /* *
  1616            *  Construct  a new Bui lder.
  1617            * /
  1618           pr otected Bu ilder() {
  1619                // empty
  1620           }
  1621  
  1622           /* *
  1623            *  Returns t he KeyStor e describe d by this  object.
  1624            *
  1625            *  @return t he {@code  KeyStore}  described  by this ob ject
  1626            *  @exceptio n KeyStore Exception  if an erro r occurred  during th e
  1627            *    operati on, for ex ample if t he KeyStor e could no t be
  1628            *    instant iated or l oaded
  1629            * /
  1630           pu blic abstr act KeySto re getKeyS tore() thr ows KeySto reExceptio n;
  1631  
  1632           /* *
  1633            *  Returns t he Protect ionParamet ers that s hould be u sed to obt ain
  1634            *  the {@lin k KeyStore .Entry Ent ry} with t he given a lias.
  1635            *  The {@cod e getKeySt ore} metho d must be  invoked be fore this
  1636            *  method ma y be calle d.
  1637            *
  1638            *  @return t he Protect ionParamet ers that s hould be u sed to obt ain
  1639            *    the {@l ink KeySto re.Entry E ntry} with  the given  alias.
  1640            *  @param al ias the al ias of the  KeyStore  entry
  1641            *  @throws N ullPointer Exception  if alias i s null
  1642            *  @throws K eyStoreExc eption if  an error o ccurred du ring the
  1643            *    operati on
  1644            *  @throws I llegalStat eException  if the ge tKeyStore  method has
  1645            *    not bee n invoked  prior to c alling thi s method
  1646            * /
  1647           pu blic abstr act Protec tionParame ter getPro tectionPar ameter(Str ing alias)
  1648                throws K eyStoreExc eption;
  1649  
  1650           /* *
  1651            *  Returns a  new Build er that en capsulates  the given  KeyStore.
  1652            *  The {@lin kplain #ge tKeyStore}  method of  the retur ned object
  1653            *  will retu rn {@code  keyStore},  the {@lin kplain
  1654            *  #getProte ctionParam eter getPr otectionPa rameter()}  method wi ll
  1655            *  return {@ code prote ctionParam eters}.
  1656            *
  1657            *  <p> This  is useful  if an exis ting KeySt ore object  needs to  be
  1658            *  used with  Builder-b ased APIs.
  1659            *
  1660            *  @return a  new Build er object
  1661            *  @param ke yStore the  KeyStore  to be enca psulated
  1662            *  @param pr otectionPa rameter th e Protecti onParamete r used to
  1663            *    protect  the KeySt ore entrie s
  1664            *  @throws N ullPointer Exception  if keyStor e or
  1665            *    protect ionParamet ers is nul l
  1666            *  @throws I llegalArgu mentExcept ion if the  keyStore  has not be en
  1667            *    initial ized
  1668            * /
  1669           pu blic stati c Builder  newInstanc e(final Ke yStore key Store,
  1670                    fina l Protecti onParamete r protecti onParamete r) {
  1671                if ((key Store == n ull) || (p rotectionP arameter = = null)) {
  1672                    thro w new Null PointerExc eption();
  1673                }
  1674                if (keyS tore.initi alized ==  false) {
  1675                    thro w new Ille galArgumen tException ("KeyStore  not initi alized");
  1676                }
  1677                return n ew Builder () {
  1678                    priv ate volati le boolean  getCalled ;
  1679  
  1680                    publ ic KeyStor e getKeySt ore() {
  1681                         getCalled  = true;
  1682                         return key Store;
  1683                    }
  1684  
  1685                    publ ic Protect ionParamet er getProt ectionPara meter(Stri ng alias)
  1686                    {
  1687                         if (alias  == null) {
  1688                             throw  new NullPo interExcep tion();
  1689                         }
  1690                         if (getCal led == fal se) {
  1691                             throw  new Illega lStateExce ption
  1692                                 (" getKeyStor e() must b e called f irst");
  1693                         }
  1694                         return pro tectionPar ameter;
  1695                    }
  1696                };
  1697           }
  1698  
  1699           /* *
  1700            *  Returns a  new Build er object.
  1701            *
  1702            *  <p>The fi rst call t o the {@li nk #getKey Store} met hod on the  returned
  1703            *  builder w ill create  a KeyStor e of type  {@code typ e} and cal l
  1704            *  its {@lin k KeyStore #load load ()} method .
  1705            *  The {@cod e inputStr eam} argum ent is con structed f rom
  1706            *  {@code fi le}.
  1707            *  If {@code  protectio n} is a
  1708            *  {@code Pa sswordProt ection}, t he passwor d is obtai ned by
  1709            *  calling t he {@code  getPasswor d} method.
  1710            *  Otherwise , if {@cod e protecti on} is a
  1711            *  {@code Ca llbackHand lerProtect ion}, the  password i s obtained
  1712            *  by invoki ng the Cal lbackHandl er.
  1713            *
  1714            *  <p>Subseq uent calls  to {@link  #getKeySt ore} retur n the same  object
  1715            *  as the in itial call . If the i nitial cal l to faile d with a
  1716            *  KeyStoreE xception,  subsequent  calls als o throw a
  1717            *  KeyStoreE xception.
  1718            *
  1719            *  <p>The Ke yStore is  instantiat ed from {@ code provi der} if
  1720            *  non-null.  Otherwise , all inst alled prov iders are  searched.
  1721            *
  1722            *  <p>Calls  to {@link  #getProtec tionParame ter getPro tectionPar ameter()}
  1723            *  will retu rn a {@lin k KeyStore .PasswordP rotection  PasswordPr otection}
  1724            *  object en capsulatin g the pass word that  was used t o invoke t he
  1725            *  {@code lo ad} method .
  1726            *
  1727            *  <p><em>No te</em> th at the {@l ink #getKe yStore} me thod is ex ecuted
  1728            *  within th e {@link A ccessContr olContext}  of the co de invokin g this
  1729            *  method.
  1730            *
  1731            *  @return a  new Build er object
  1732            *  @param ty pe the typ e of KeySt ore to be  constructe d
  1733            *  @param pr ovider the  provider  from which  the KeySt ore is to
  1734            *    be inst antiated ( or null)
  1735            *  @param fi le the Fil e that con tains the  KeyStore d ata
  1736            *  @param pr otection t he Protect ionParamet er securin g the KeyS tore data
  1737            *  @throws N ullPointer Exception  if type, f ile or pro tection is  null
  1738            *  @throws I llegalArgu mentExcept ion if pro tection is  not an in stance
  1739            *    of eith er Passwor dProtectio n or Callb ackHandler Protection ; or
  1740            *    if file  does not  exist or d oes not re fer to a n ormal file
  1741            * /
  1742           pu blic stati c Builder  newInstanc e(String t ype, Provi der provid er,
  1743                    File  file, Pro tectionPar ameter pro tection) {
  1744                if ((typ e == null)  || (file  == null) | | (protect ion == nul l)) {
  1745                    thro w new Null PointerExc eption();
  1746                }
  1747                if ((pro tection in stanceof P asswordPro tection ==  false) &&
  1748                    (pro tection in stanceof C allbackHan dlerProtec tion == fa lse)) {
  1749                    thro w new Ille galArgumen tException
  1750                    ("Pr otection m ust be Pas swordProte ction or "  +
  1751                     "Ca llbackHand lerProtect ion");
  1752                }
  1753                if (file .isFile()  == false)  {
  1754                    thro w new Ille galArgumen tException
  1755                         ("File doe s not exis t or it do es not ref er " +
  1756                          "to a nor mal file:  " + file);
  1757                }
  1758                return n ew FileBui lder(type,  provider,  file, pro tection,
  1759                    Acce ssControll er.getCont ext());
  1760           }
  1761  
  1762           pr ivate stat ic final c lass FileB uilder ext ends Build er {
  1763  
  1764                private  final Stri ng type;
  1765                private  final Prov ider provi der;
  1766                private  final File  file;
  1767                private  Protection Parameter  protection ;
  1768                private  Protection Parameter  keyProtect ion;
  1769                private  final Acce ssControlC ontext con text;
  1770  
  1771                private  KeyStore k eyStore;
  1772  
  1773                private  Throwable  oldExcepti on;
  1774  
  1775                FileBuil der(String  type, Pro vider prov ider, File  file,
  1776                         Protection Parameter  protection ,
  1777                         AccessCont rolContext  context)  {
  1778                    this .type = ty pe;
  1779                    this .provider  = provider ;
  1780                    this .file = fi le;
  1781                    this .protectio n = protec tion;
  1782                    this .context =  context;
  1783                }
  1784  
  1785                public s ynchronize d KeyStore  getKeySto re() throw s KeyStore Exception
  1786                {
  1787                    if ( keyStore ! = null) {
  1788                         return key Store;
  1789                    }
  1790                    if ( oldExcepti on != null ) {
  1791                         throw new  KeyStoreEx ception
  1792                             ("Prev ious KeySt ore instan tiation fa iled",
  1793                              oldEx ception);
  1794                    }
  1795                    Priv ilegedExce ptionActio n<KeyStore > action =
  1796                             new Pr ivilegedEx ceptionAct ion<KeySto re>() {
  1797                         public Key Store run( ) throws E xception {
  1798                             if (pr otection i nstanceof  CallbackHa ndlerProte ction == f alse) {
  1799                                 re turn run0( );
  1800                             }
  1801                             // whe n using a  CallbackHa ndler,
  1802                             // rep rompt if t he passwor d is wrong
  1803                             int tr ies = 0;
  1804                             while  (true) {
  1805                                 tr ies++;
  1806                                 tr y {
  1807                                      return r un0();
  1808                                 }  catch (IOE xception e ) {
  1809                                      if ((tri es < MAX_C ALLBACK_TR IES)
  1810                                               && (e.getC ause() ins tanceof Un recoverabl eKeyExcept ion)) {
  1811                                          cont inue;
  1812                                      }
  1813                                      throw e;
  1814                                 }
  1815                             }
  1816                         }
  1817                         public Key Store run0 () throws  Exception  {
  1818                             KeySto re ks;
  1819                             if (pr ovider ==  null) {
  1820                                 ks  = KeyStor e.getInsta nce(type);
  1821                             } else  {
  1822                                 ks  = KeyStor e.getInsta nce(type,  provider);
  1823                             }
  1824                             InputS tream in =  null;
  1825                             char[]  password  = null;
  1826                             try {
  1827                                 in  = new Fil eInputStre am(file);
  1828                                 if  (protecti on instanc eof Passwo rdProtecti on) {
  1829                                      password  =
  1830                                      ((Passwo rdProtecti on)protect ion).getPa ssword();
  1831                                      keyProte ction = pr otection;
  1832                                 }  else {
  1833                                      Callback Handler ha ndler =
  1834                                          ((Ca llbackHand lerProtect ion)protec tion)
  1835                                          .get CallbackHa ndler();
  1836                                      Password Callback c allback =  new Passwo rdCallback
  1837                                          ("Pa ssword for  keystore  " + file.g etName(),
  1838                                          fals e);
  1839                                      handler. handle(new  Callback[ ] {callbac k});
  1840                                      password  = callbac k.getPassw ord();
  1841                                      if (pass word == nu ll) {
  1842                                          thro w new KeyS toreExcept ion("No pa ssword" +
  1843                                                                         " prov ided");
  1844                                      }
  1845                                      callback .clearPass word();
  1846                                      keyProte ction = ne w Password Protection (password) ;
  1847                                 }
  1848                                 ks .load(in,  password);
  1849                                 re turn ks;
  1850                             } fina lly {
  1851                                 if  (in != nu ll) {
  1852                                      in.close ();
  1853                                 }
  1854                             }
  1855                         }
  1856                    };
  1857                    try  {
  1858                         keyStore =  AccessCon troller.do Privileged (action, c ontext);
  1859                         return key Store;
  1860                    } ca tch (Privi legedActio nException  e) {
  1861                         oldExcepti on = e.get Cause();
  1862                         throw new  KeyStoreEx ception
  1863                             ("KeyS tore insta ntiation f ailed", ol dException );
  1864                    }
  1865                }
  1866  
  1867                public s ynchronize d Protecti onParamete r
  1868                             getPro tectionPar ameter(Str ing alias)  {
  1869                    if ( alias == n ull) {
  1870                         throw new  NullPointe rException ();
  1871                    }
  1872                    if ( keyStore = = null) {
  1873                         throw new  IllegalSta teExceptio n
  1874                             ("getK eyStore()  must be ca lled first ");
  1875                    }
  1876                    retu rn keyProt ection;
  1877                }
  1878           }
  1879  
  1880           /* *
  1881            *  Returns a  new Build er object.
  1882            *
  1883            *  <p>Each c all to the  {@link #g etKeyStore } method o n the retu rned
  1884            *  builder w ill return  a new Key Store obje ct of type  {@code ty pe}.
  1885            *  Its {@lin k KeyStore #load(KeyS tore.LoadS toreParame ter) load( )}
  1886            *  method is  invoked u sing a
  1887            *  {@code Lo adStorePar ameter} th at encapsu lates
  1888            *  {@code pr otection}.
  1889            *
  1890            *  <p>The Ke yStore is  instantiat ed from {@ code provi der} if
  1891            *  non-null.  Otherwise , all inst alled prov iders are  searched.
  1892            *
  1893            *  <p>Calls  to {@link  #getProtec tionParame ter getPro tectionPar ameter()}
  1894            *  will retu rn {@code  protection }.
  1895            *
  1896            *  <p><em>No te</em> th at the {@l ink #getKe yStore} me thod is ex ecuted
  1897            *  within th e {@link A ccessContr olContext}  of the co de invokin g this
  1898            *  method.
  1899            *
  1900            *  @return a  new Build er object
  1901            *  @param ty pe the typ e of KeySt ore to be  constructe d
  1902            *  @param pr ovider the  provider  from which  the KeySt ore is to
  1903            *    be inst antiated ( or null)
  1904            *  @param pr otection t he Protect ionParamet er securin g the Keys tore
  1905            *  @throws N ullPointer Exception  if type or  protectio n is null
  1906            * /
  1907           pu blic stati c Builder  newInstanc e(final St ring type,
  1908                    fina l Provider  provider,  final Pro tectionPar ameter pro tection) {
  1909                if ((typ e == null)  || (prote ction == n ull)) {
  1910                    thro w new Null PointerExc eption();
  1911                }
  1912                final Ac cessContro lContext c ontext = A ccessContr oller.getC ontext();
  1913                return n ew Builder () {
  1914                    priv ate volati le boolean  getCalled ;
  1915                    priv ate IOExce ption oldE xception;
  1916  
  1917                    priv ate final  Privileged ExceptionA ction<KeyS tore> acti on
  1918                             = new  Privileged ExceptionA ction<KeyS tore>() {
  1919  
  1920                         public Key Store run( ) throws E xception {
  1921                             KeySto re ks;
  1922                             if (pr ovider ==  null) {
  1923                                 ks  = KeyStor e.getInsta nce(type);
  1924                             } else  {
  1925                                 ks  = KeyStor e.getInsta nce(type,  provider);
  1926                             }
  1927                             LoadSt oreParamet er param =  new Simpl eLoadStore Parameter( protection );
  1928                             if (pr otection i nstanceof  CallbackHa ndlerProte ction == f alse) {
  1929                                 ks .load(para m);
  1930                             } else  {
  1931                                 //  when usin g a Callba ckHandler,
  1932                                 //  reprompt  if the pas sword is w rong
  1933                                 in t tries =  0;
  1934                                 wh ile (true)  {
  1935                                      tries++;
  1936                                      try {
  1937                                          ks.l oad(param) ;
  1938                                          brea k;
  1939                                      } catch  (IOExcepti on e) {
  1940                                          if ( e.getCause () instanc eof Unreco verableKey Exception)  {
  1941                                               if (tries  < MAX_CALL BACK_TRIES ) {
  1942                                                   contin ue;
  1943                                               } else {
  1944                                                   oldExc eption = e ;
  1945                                               }
  1946                                          }
  1947                                          thro w e;
  1948                                      }
  1949                                 }
  1950                             }
  1951                             getCal led = true ;
  1952                             return  ks;
  1953                         }
  1954                    };
  1955  
  1956                    publ ic synchro nized KeyS tore getKe yStore()
  1957                             throws  KeyStoreE xception {
  1958                         if (oldExc eption !=  null) {
  1959                             throw  new KeySto reExceptio n
  1960                                 (" Previous K eyStore in stantiatio n failed",
  1961                                  o ldExceptio n);
  1962                         }
  1963                         try {
  1964                             return  AccessCon troller.do Privileged (action, c ontext);
  1965                         } catch (P rivilegedA ctionExcep tion e) {
  1966                             Throwa ble cause  = e.getCau se();
  1967                             throw  new KeySto reExceptio n
  1968                                 (" KeyStore i nstantiati on failed" , cause);
  1969                         }
  1970                    }
  1971  
  1972                    publ ic Protect ionParamet er getProt ectionPara meter(Stri ng alias)
  1973                    {
  1974                         if (alias  == null) {
  1975                             throw  new NullPo interExcep tion();
  1976                         }
  1977                         if (getCal led == fal se) {
  1978                             throw  new Illega lStateExce ption
  1979                                 (" getKeyStor e() must b e called f irst");
  1980                         }
  1981                         return pro tection;
  1982                    }
  1983                };
  1984           }
  1985  
  1986       }
  1987  
  1988       static  class Sim pleLoadSto reParamete r implemen ts LoadSto reParamete r {
  1989  
  1990           pr ivate fina l Protecti onParamete r protecti on;
  1991  
  1992           Si mpleLoadSt oreParamet er(Protect ionParamet er protect ion) {
  1993                this.pro tection =  protection ;
  1994           }
  1995  
  1996           pu blic Prote ctionParam eter getPr otectionPa rameter()  {
  1997                return p rotection;
  1998           }
  1999       }
  2000  
  2001   }