harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mloe...@apache.org
Subject svn commit: r410258 [2/2] - /incubator/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/org/apache/harmony/security/provider/cert/
Date Tue, 30 May 2006 12:26:43 GMT
Modified: incubator/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/org/apache/harmony/security/provider/cert/X509CertImpl.java
URL: http://svn.apache.org/viewvc/incubator/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/org/apache/harmony/security/provider/cert/X509CertImpl.java?rev=410258&r1=410257&r2=410258&view=diff
==============================================================================
--- incubator/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/org/apache/harmony/security/provider/cert/X509CertImpl.java
(original)
+++ incubator/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/org/apache/harmony/security/provider/cert/X509CertImpl.java
Tue May 30 05:26:43 2006
@@ -51,20 +51,28 @@
 import org.apache.harmony.security.x509.TBSCertificate;
 
 /**
- * X509CertImpl
+ * This class is an implementation of X509Certificate. It wraps
+ * the instance of org.apache.harmony.security.x509.Certificate
+ * built on the base of provided ASN.1 DER encoded form of
+ * Certificate structure (as specified in RFC 3280
+ * http://www.ietf.org/rfc/rfc3280.txt).
+ * @see org.apache.harmony.security.x509.Certificate
+ * @see java.security.cert.X509Certificate
  */
 public class X509CertImpl extends X509Certificate {
-    
+
     /**
      * @serial
      */
     private static final long serialVersionUID = 2972248729446736154L;
 
+    // the core object to be wrapped in X509Certificate
     private final Certificate certificate;
+
+    // to speed up access to the info, the following fields
+    // cache values retrieved from the certificate object
     private final TBSCertificate tbsCert;
     private final Extensions extensions;
-    
-    // cached values
     private long notBefore = -1;
     private long notAfter;
     private BigInteger serialNumber;
@@ -75,42 +83,68 @@
     private String sigAlgName;
     private String sigAlgOID;
     private byte[] sigAlgParams;
+    // indicates whether the signature algorithm parameters are null
     private boolean nullSigAlgParams;
-    //Values are taken directly from tbsCerttificate:
-    // private boolean[] issuerUniqueID;
-    // private boolean[] subjectUniqueID;
     private PublicKey publicKey;
-    
+
+    // encoding of the certificate
     private byte[] encoding;
-    
+
+    //
+    // ---------------------- Constructors -------------------------------
+    //
+
+    /**
+     * Constructs the instance on the base of ASN.1 encoded
+     * form of X.509 certificate provided via stream parameter.
+     * @param in input stream containing ASN.1 encoded form of certificate.
+     * @throws CertificateException if some decoding problems occur.
+     */
     public X509CertImpl(InputStream in) throws CertificateException {
         try {
+            // decode the Certificate object
             this.certificate = (Certificate) Certificate.ASN1.decode(in);
+            // cache the values of TBSCertificate and Extensions
             this.tbsCert = certificate.getTbsCertificate();
             this.extensions = tbsCert.getExtensions();
         } catch (IOException e) {
             throw new CertificateException(e);
         }
     }
-    
+
+    /**
+     * Constructs the instance on the base of existing Certificate object to
+     * be wrapped.
+     */
     public X509CertImpl(Certificate certificate) {
         this.certificate = certificate;
+        // cache the values of TBSCertificate and Extensions
         this.tbsCert = certificate.getTbsCertificate();
         this.extensions = tbsCert.getExtensions();
     }
 
+    /**
+     * Constructs the instance on the base of ASN.1 encoded
+     * form of X.509 certificate provided via array of bytes.
+     * @param encoding byte array containing ASN.1 encoded form of certificate.
+     * @throws IOException if some decoding problems occur.
+     */
     public X509CertImpl(byte[] encoding) throws IOException {
-        this((Certificate) Certificate.ASN1.decode(encoding)); 
+        this((Certificate) Certificate.ASN1.decode(encoding));
     }
 
-
-    // 
+    //
     // ----------------- Public methods implementations ------------------
     //
 
+    /**
+     * @see java.security.cert.X509Certificate#checkValidity()
+     * method documentation for more information.
+     */
     public void checkValidity() throws CertificateExpiredException,
                                        CertificateNotYetValidException {
         if (notBefore == -1) {
+            // retrieve and cache the value of validity period
             notBefore = tbsCert.getValidity().getNotBefore().getTime();
             notAfter = tbsCert.getValidity().getNotAfter().getTime();
         }
@@ -123,10 +157,15 @@
         }
     }
 
-    public void checkValidity(Date date) 
-                                throws CertificateExpiredException, 
+    /**
+     * @see java.security.cert.X509Certificate#checkValidity(Date)
+     * method documentation for more information.
+     */
+    public void checkValidity(Date date)
+                                throws CertificateExpiredException,
                                        CertificateNotYetValidException {
         if (notBefore == -1) {
+            // retrieve and cache the value of validity period
             notBefore = tbsCert.getValidity().getNotBefore().getTime();
             notAfter = tbsCert.getValidity().getNotAfter().getTime();
         }
@@ -138,11 +177,19 @@
             throw new CertificateExpiredException();
         }
     }
-    
+
+    /**
+     * @see java.security.cert.X509Certificate#getVersion()
+     * method documentation for more information.
+     */
     public int getVersion() {
         return tbsCert.getVersion() + 1;
     }
 
+    /**
+     * @see java.security.cert.X509Certificate#getSerialNumber()
+     * method documentation for more information.
+     */
     public BigInteger getSerialNumber() {
         if (serialNumber == null) {
             serialNumber = tbsCert.getSerialNumber();
@@ -150,54 +197,88 @@
         return serialNumber;
     }
 
+    /**
+     * @see java.security.cert.X509Certificate#getIssuerDN()
+     * method documentation for more information.
+     */
     public Principal getIssuerDN() {
         if (issuer == null) {
+            // retrieve the issuer's principal
             issuer = tbsCert.getIssuer().getX500Principal();
         }
         return issuer;
     }
 
+    /**
+     * @see java.security.cert.X509Certificate#getIssuerX500Principal()
+     * method documentation for more information.
+     */
     public X500Principal getIssuerX500Principal() {
         if (issuer == null) {
+            // retrieve the issuer's principal
             issuer = tbsCert.getIssuer().getX500Principal();
         }
         return issuer;
     }
-        
+
+    /**
+     * @see java.security.cert.X509Certificate#getSubjectDN()
+     * method documentation for more information.
+     */
     public Principal getSubjectDN() {
         if (subject == null) {
+            // retrieve the subject's principal
             subject = tbsCert.getSubject().getX500Principal();
         }
         return subject;
     }
 
+    /**
+     * @see java.security.cert.X509Certificate#getSubjectX500Principal()
+     * method documentation for more information.
+     */
     public X500Principal getSubjectX500Principal() {
         if (subject == null) {
+            // retrieve the subject's principal
             subject = tbsCert.getSubject().getX500Principal();
         }
         return subject;
     }
 
+    /**
+     * @see java.security.cert.X509Certificate#getNotBefore()
+     * method documentation for more information.
+     */
     public Date getNotBefore() {
         if (notBefore == -1) {
+            // the value was not retrieved from the certificate, do it:
             notBefore = tbsCert.getValidity().getNotBefore().getTime();
             notAfter = tbsCert.getValidity().getNotAfter().getTime();
         }
         return new Date(notBefore);
     }
 
+    /**
+     * @see java.security.cert.X509Certificate#getNotAfter()
+     * method documentation for more information.
+     */
     public Date getNotAfter() {
         if (notBefore == -1) {
+            // the value was not retrieved from the certificate, do it:
             notBefore = tbsCert.getValidity().getNotBefore().getTime();
             notAfter = tbsCert.getValidity().getNotAfter().getTime();
         }
         return new Date(notAfter);
     }
 
+    /**
+     * @see java.security.cert.X509Certificate#getTBSCertificate()
+     * method documentation for more information.
+     */
     public byte[] getTBSCertificate()
-                        throws CertificateEncodingException
-    {
+                        throws CertificateEncodingException {
         if (tbsCertificate == null) {
+            // retrieve the encoded form of the TBSCertificate structure
             tbsCertificate = tbsCert.getEncoded();
         }
         byte[] result = new byte[tbsCertificate.length];
@@ -205,8 +286,13 @@
         return result;
     }
 
+    /**
+     * @see java.security.cert.X509Certificate#getSignature()
+     * method documentation for more information.
+     */
     public byte[] getSignature() {
         if (signature == null) {
+            // retrieve the value of the signature
             signature = certificate.getSignatureValue();
         }
         byte[] result = new byte[signature.length];
@@ -214,28 +300,46 @@
         return result;
     }
 
+    /**
+     * @see java.security.cert.X509Certificate#getSigAlgName()
+     * method documentation for more information.
+     */
     public String getSigAlgName() {
         if (sigAlgOID == null) {
+            // if info was not retrieved (and cached), do it:
             sigAlgOID = tbsCert.getSignature().getAlgorithm();
+            // retrieve the name of the signing algorithm
             sigAlgName = AlgNameMapper.map2AlgName(sigAlgOID);
             if (sigAlgName == null) {
+                // if could not be found, use OID as a name
                 sigAlgName = sigAlgOID;
             }
         }
         return sigAlgName;
     }
 
+    /**
+     * @see java.security.cert.X509Certificate#getSigAlgOID()
+     * method documentation for more information.
+     */
     public String getSigAlgOID() {
         if (sigAlgOID == null) {
+            // if info was not retrieved (and cached), do it:
             sigAlgOID = tbsCert.getSignature().getAlgorithm();
+            // retrieve the name of the signing algorithm
             sigAlgName = AlgNameMapper.map2AlgName(sigAlgOID);
             if (sigAlgName == null) {
+                // if could not be found, use OID as a name
                 sigAlgName = sigAlgOID;
             }
         }
         return sigAlgOID;
     }
 
+    /**
+     * @see java.security.cert.X509Certificate#getSigAlgParams()
+     * method documentation for more information.
+     */
     public byte[] getSigAlgParams() {
         if (nullSigAlgParams) {
             return null;
@@ -251,21 +355,24 @@
     }
 
     /**
-     * @return
+     * @see java.security.cert.X509Certificate#getIssuerUniqueID()
+     * method documentation for more information.
      */
     public boolean[] getIssuerUniqueID() {
         return tbsCert.getIssuerUniqueID();
     }
 
     /**
-     * @return
+     * @see java.security.cert.X509Certificate#getSubjectUniqueID()
+     * method documentation for more information.
      */
     public boolean[] getSubjectUniqueID() {
         return tbsCert.getSubjectUniqueID();
     }
 
     /**
-     * @return
+     * @see java.security.cert.X509Certificate#getKeyUsage()
+     * method documentation for more information.
      */
     public boolean[] getKeyUsage() {
         if (extensions == null) {
@@ -274,6 +381,10 @@
         return extensions.valueOfKeyUsage();
     }
 
+    /**
+     * @see java.security.cert.X509Certificate#getExtendedKeyUsage()
+     * method documentation for more information.
+     */
     public List/*<String>*/ getExtendedKeyUsage()
                                 throws CertificateParsingException {
         if (extensions == null) {
@@ -286,6 +397,10 @@
         }
     }
 
+    /**
+     * @see java.security.cert.X509Certificate#getBasicConstraints()
+     * method documentation for more information.
+     */
     public int getBasicConstraints() {
         if (extensions == null) {
             return Integer.MAX_VALUE;
@@ -293,36 +408,53 @@
         return extensions.valueOfBasicConstrains();
     }
 
+    /**
+     * @see java.security.cert.X509Certificate#getSubjectAlternativeNames()
+     * method documentation for more information.
+     */
     public Collection/*<List<?>>*/ getSubjectAlternativeNames()
                                 throws CertificateParsingException {
         if (extensions == null) {
             return null;
         }
         try {
+            // Retrieve the extension value from the cached extensions object
+            // This extension is not checked for correctness during
+            // certificate generation, so now it can throw exception
             return extensions.valueOfSubjectAlternativeName();
         } catch (IOException e) {
             throw new CertificateParsingException(e);
         }
     }
 
+    /**
+     * @see java.security.cert.X509Certificate#getIssuerAlternativeNames()
+     * method documentation for more information.
+     */
     public Collection/*FIXME <List<?>>*/ getIssuerAlternativeNames()
                                 throws CertificateParsingException {
         if (extensions == null) {
             return null;
         }
         try {
+            // Retrieve the extension value from the cached extensions object
+            // This extension is not checked for correctness during
+            // certificate generation, so now it can throw exception
             return extensions.valueOfIssuerAlternativeName();
         } catch (IOException e) {
             throw new CertificateParsingException(e);
         }
     }
 
-    // 
+    //
     // ----- java.security.cert.Certificate methods implementations ------
     //
-    
-    public byte[] getEncoded() throws CertificateEncodingException
-    {
+
+    /**
+     * @see java.security.cert.Certificate#getEncoded()
+     * method documentation for more information.
+     */
+    public byte[] getEncoded() throws CertificateEncodingException {
         if (encoding == null) {
             encoding = certificate.getEncoded();
         }
@@ -331,102 +463,122 @@
         return result;
     }
 
+    /**
+     * @see java.security.cert.Certificate#getPublicKey()
+     * method documentation for more information.
+     */
     public PublicKey getPublicKey() {
         if (publicKey == null) {
+            // retrieve the public key from SubjectPublicKeyInfo
+            // substructure of X.509 certificate
             publicKey = tbsCert.getSubjectPublicKeyInfo().getPublicKey();
         }
         return publicKey;
     }
 
     /**
-     * TODO: should be fully implemented.
-     * @return
+     * @see java.security.cert.Certificate#toString()
+     * method documentation for more information.
      */
     public String toString() {
         return certificate.toString();
     }
-    
+
     /**
-     * TODO
-     * @param   key:    PublicKey
-     * @return
-     * @throwsCertificateException
-     * @throwsNoSuchAlgorithmException
-     * @throwsInvalidKeyException
-     * @throwsNoSuchProviderException
-     * @throwsSignatureException    
+     * Verifies the signature of the certificate.
+     * @see java.security.cert.Certificate#verify(PublicKey)
+     * method documentation for more information.
      */
     public void verify(PublicKey key)
                          throws CertificateException, NoSuchAlgorithmException,
                                 InvalidKeyException, NoSuchProviderException,
-                                SignatureException
-    {
-        Signature signature = Signature.getInstance(
-                                tbsCert.getSignature().getAlgorithm());
+                                SignatureException {
+        Signature signature = Signature.getInstance(getSigAlgName());
         signature.initVerify(key);
-        byte[] tbsCertEncoding = tbsCert.getEncoded();
-        signature.update(tbsCertEncoding, 0, tbsCertEncoding.length);
+        // retrieve the ecnoding of the TBSCertificate structure
+        if (tbsCertificate == null) {
+            tbsCertificate = tbsCert.getEncoded();
+        }
+        // compute and verify the signature
+        signature.update(tbsCertificate, 0, tbsCertificate.length);
         if (!signature.verify(certificate.getSignatureValue())) {
             throw new SignatureException("Signature was not verified.");
         }
     }
 
     /**
-     * TODO
-     * @param   key:    PublicKey
-     * @param   sigProvider:    String
-     * @return
-     * @throwsCertificateException
-     * @throwsNoSuchAlgorithmException
-     * @throwsInvalidKeyException
-     * @throwsNoSuchProviderException
-     * @throwsSignatureException    
+     * Verifies the signature of the certificate.
+     * @see java.security.cert.Certificate#verify(PublicKey,String)
+     * method documentation for more information.
      */
     public void verify(PublicKey key, String sigProvider)
                          throws CertificateException, NoSuchAlgorithmException,
                                 InvalidKeyException, NoSuchProviderException,
-                                SignatureException
-    {
-        Signature signature = Signature.getInstance(
-                    tbsCert.getSignature().getAlgorithm(), sigProvider);
+                                SignatureException {
+        Signature signature =
+            Signature.getInstance(getSigAlgName(), sigProvider);
         signature.initVerify(key);
-        byte[] tbsCertEncoding = tbsCert.getEncoded();
-        signature.update(tbsCertEncoding, 0, tbsCertEncoding.length);
+        // retrieve the ecnoding of the TBSCertificate structure
+        if (tbsCertificate == null) {
+            tbsCertificate = tbsCert.getEncoded();
+        }
+        // compute and verify the signature
+        signature.update(tbsCertificate, 0, tbsCertificate.length);
         if (!signature.verify(certificate.getSignatureValue())) {
             throw new SignatureException("Signature was not verified.");
         }
     }
 
-    // 
+    //
     // ----- java.security.cert.X509Extension methods implementations ----
     //
 
+    /**
+     * @see java.security.cert.X509Extension#getNonCriticalExtensionOIDs()
+     * method documentation for more information.
+     */
     public Set getNonCriticalExtensionOIDs() {
         if (extensions == null) {
             return null;
         }
+        // retrieve the info from the cached extensions object
         return extensions.getNonCriticalExtensions();
     }
 
+    /**
+     * @see java.security.cert.X509Extension#getCriticalExtensionOIDs()
+     * method documentation for more information.
+     */
     public Set getCriticalExtensionOIDs() {
         if (extensions == null) {
             return null;
         }
+        // retrieve the info from the cached extensions object
         return extensions.getCriticalExtensions();
     }
 
+    /**
+     * @see java.security.cert.X509Extension#getExtensionValue(String)
+     * method documentation for more information.
+     */
     public byte[] getExtensionValue(String oid) {
         if (extensions == null) {
             return null;
         }
+        // retrieve the info from the cached extensions object
         Extension ext = extensions.getExtensionByOID(oid);
         return (ext == null) ? null : ext.getRawExtnValue();
     }
 
+    /**
+     * @see java.security.cert.X509Extension#hasUnsupportedCriticalExtension()
+     * method documentation for more information.
+     */
     public boolean hasUnsupportedCriticalExtension() {
         if (extensions == null) {
             return false;
         }
+        // retrieve the info from the cached extensions object
         return extensions.hasUnsupportedCritical();
     }
 

Modified: incubator/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/org/apache/harmony/security/provider/cert/X509CertPathImpl.java
URL: http://svn.apache.org/viewvc/incubator/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/org/apache/harmony/security/provider/cert/X509CertPathImpl.java?rev=410258&r1=410257&r2=410258&view=diff
==============================================================================
--- incubator/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/org/apache/harmony/security/provider/cert/X509CertPathImpl.java
(original)
+++ incubator/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/org/apache/harmony/security/provider/cert/X509CertPathImpl.java
Tue May 30 05:26:43 2006
@@ -41,12 +41,33 @@
 import org.apache.harmony.security.pkcs7.SignedData;
 import org.apache.harmony.security.x509.Certificate;
 
-
 /**
- * X509CertPathImpl
+ * This class is an implementation of X.509 CertPath. This implementation
+ * provides ability to create the instance of X.509 Certification Path
+ * by several means:<br>
+ *
+ * &nbsp;  1. It can be created over the list of X.509 certificates
+ * (implementations of X509Certificate class) provided in constructor.<br>
+ *
+ * &nbsp;  2. It can be created by means of <code>getInstance</code> methods
+ * on the base of the following ASN.1 DER encoded forms:<br>
+ *
+ * &nbsp;&nbsp;  - PkiPath as defined in
+ * ITU-T Recommendation X.509(2000) Corrigendum 1(2001)
+ * (can be seen at
+ * ftp://ftp.bull.com/pub/OSIdirectory/DefectResolution/TechnicalCorrigenda/ApprovedTechnicalCorrigendaToX.509/8%7CX.509-TC1(4th).pdf)
+ * <br>
+ * &nbsp;&nbsp;  - PKCS #7 SignedData object provided in the form of
+ * ContentInfo structure. CertPath object is generated on the base of
+ * certificates presented in ?certificates? field of the SignedData
+ * object which in its turn is retrieved from ContentInfo structure.
+ * (see http://www.rsasecurity.com/rsalabs/node.asp?id=2129
+ * for more info on PKCS #7)
+ * <br>
+ * &nbsp;
  */
 public class X509CertPathImpl extends CertPath {
- 
+
     /**
      * @serial
      */
@@ -55,29 +76,32 @@
     // supported encoding types:
     public static final int PKI_PATH = 0;
     public static final int PKCS7 = 1;
-    
-    // supported encoding names:
-    private static final String[] encodingsArr = 
+
+    // supported encoding names
+    private static final String[] encodingsArr =
                                         new String[] {"PkiPath", "PKCS7"};
     static final List encodings = Collections.unmodifiableList(
                                             Arrays.asList(encodingsArr));
+    // the list of certificates representing this certification path
     private final List certificates;
+    // PkiPath encoding of the certification path
     private byte[] pkiPathEncoding;
+    // PKCS7 encoding of the certification path
     private byte[] pkcs7Encoding;
-    
+
+    /**
+     * Creates an instance of X.509 Certification Path over the specified
+     * list of certificates.
+     * @throws CertificateException if some of the object in the list
+     * is not an instance of subclass of X509Certificate.
+     */
     public X509CertPathImpl(List certs) throws CertificateException {
         super("X.509");
-        // if (certs == null) {
-        //     throw new CertificateException(
-        //             "Provided list of certificates provided is null.");
-        // }
-        // throw NullPointerException:
         int size = certs.size();
         certificates = new ArrayList(size);
         for (int i=0; i<size; i++) {
             Object cert = certs.get(i);
             if (!(cert instanceof X509Certificate) ) {
-                //    && ("X.509".equals(((X509Certificate) cert).getType()))) )
{
                 throw new CertificateException(
                         "One of provided certificates is not X509 certificate");
             }
@@ -85,6 +109,15 @@
         }
     }
 
+    /*
+     * Internally used constructor.
+     * Creates an X.509 Certification Path over the specified
+     * list of certificates and their encoded form of specified type.
+     * @param certs - the list of certificates
+     * @param type - the type of the encoded form on the base of which
+     * this list of certificates had been built.
+     * @param encoding - encoded form of certification path.
+     */
     private X509CertPathImpl(List certs, int type, byte[] encoding) {
         super("X.509");
         if (type == PKI_PATH) {
@@ -92,12 +125,18 @@
         } else { // PKCS7
             this.pkcs7Encoding = encoding;
         }
-        // We do not need the type check and list cloning here, 
+        // We do not need the type check and list cloning here,
         // because it has been done during decoding.
         certificates = certs;
     }
 
-    public static X509CertPathImpl getInstance(InputStream in) 
+    /**
+     * Generates certification path object on the base of PkiPath
+     * encoded form provided via input stream.
+     * @throws CertificateException if some problems occurred during
+     * the decoding.
+     */
+    public static X509CertPathImpl getInstance(InputStream in)
                                         throws CertificateException {
         try {
             return (X509CertPathImpl) ASN1.decode(in);
@@ -107,7 +146,14 @@
         }
     }
 
-    public static X509CertPathImpl getInstance(InputStream in, String encoding) 
+    /**
+     * Generates certification path object on the base of encoding provided via
+     * input stream. The format of provided encoded form is specified by
+     * parameter <code>encoding</code>.
+     * @throws CertificateException if specified encoding form is not supported,
+     * or some problems occurred during the decoding.
+     */
+    public static X509CertPathImpl getInstance(InputStream in, String encoding)
         throws CertificateException {
         if (!encodings.contains(encoding)) {
             throw new CertificateException(
@@ -115,16 +161,19 @@
         }
         try {
             if (encodingsArr[0].equals(encoding)) {
+                // generate the object from PkiPath encoded form
                 return (X509CertPathImpl) ASN1.decode(in);
             } else {
+                // generate the object from PKCS #7 encoded form
                 ContentInfo ci = (ContentInfo) ContentInfo.ASN1.decode(in);
                 SignedData sd = ci.getSignedData();
                 if (sd == null) {
                     throw new CertificateException(
-                            "Incorrect PKCS7 encoded form: missing signed data");
+                        "Incorrect PKCS7 encoded form: missing signed data");
                 }
                 List certs = sd.getCertificates();
                 if (certs == null) {
+                    // empty chain of certificates
                     certs = new ArrayList();
                 }
                 return new X509CertPathImpl(certs, PKCS7, ci.getEncoded());
@@ -135,7 +184,13 @@
         }
     }
 
-    public static X509CertPathImpl getInstance(byte[] in) 
+    /**
+     * Generates certification path object on the base of PkiPath
+     * encoded form provided via array of bytes.
+     * @throws CertificateException if some problems occurred during
+     * the decoding.
+     */
+    public static X509CertPathImpl getInstance(byte[] in)
                                         throws CertificateException {
         try {
             return (X509CertPathImpl) ASN1.decode(in);
@@ -145,7 +200,14 @@
         }
     }
 
-    public static X509CertPathImpl getInstance(byte[] in, String encoding) 
+    /**
+     * Generates certification path object on the base of encoding provided via
+     * array of bytes. The format of provided encoded form is specified by
+     * parameter <code>encoding</code>.
+     * @throws CertificateException if specified encoding form is not supported,
+     * or some problems occurred during the decoding.
+     */
+    public static X509CertPathImpl getInstance(byte[] in, String encoding)
         throws CertificateException {
         if (!encodings.contains(encoding)) {
             throw new CertificateException(
@@ -153,13 +215,15 @@
         }
         try {
             if (encodingsArr[0].equals(encoding)) {
+                // generate the object from PkiPath encoded form
                 return (X509CertPathImpl) ASN1.decode(in);
-            } else { // PKCS7
+            } else {
+                // generate the object from PKCS #7 encoded form
                 ContentInfo ci = (ContentInfo) ContentInfo.ASN1.decode(in);
                 SignedData sd = ci.getSignedData();
                 if (sd == null) {
                     throw new CertificateException(
-                            "Incorrect PKCS7 encoded form: missing signed data");
+                        "Incorrect PKCS7 encoded form: missing signed data");
                 }
                 List certs = sd.getCertificates();
                 if (certs == null) {
@@ -173,15 +237,21 @@
         }
     }
 
+    // ---------------------------------------------------------------------
+    // ---- java.security.cert.CertPath abstract method implementations ----
+    // ---------------------------------------------------------------------
+
     /**
-     * getCertificates
+     * @see java.security.cert.CertPath#getCertificates()
+     * method documentation for more info
      */
     public List getCertificates() {
         return Collections.unmodifiableList(certificates);
     }
 
     /**
-     * getEncoded
+     * @see java.security.cert.CertPath#getEncoded()
+     * method documentation for more info
      */
     public byte[] getEncoded() throws CertificateEncodingException {
         if (pkiPathEncoding == null) {
@@ -193,7 +263,8 @@
     }
 
     /**
-     * getEncoded
+     * @see java.security.cert.CertPath#getEncoded(String)
+     * method documentation for more info
      */
     public byte[] getEncoded(String encoding)
         throws CertificateEncodingException {
@@ -202,47 +273,70 @@
                     "Unsupported encoding: "+encoding);
         }
         if (encodingsArr[0].equals(encoding)) {
+            // PkiPath encoded form
             return getEncoded();
         } else {
-            // FIXME: PKCS7 encoding support
-            // PKCS7 encoded form:
+            // PKCS7 encoded form
             if (pkcs7Encoding == null) {
-                SignedData sd = new SignedData(1, new ArrayList(), 
+                SignedData sd = new SignedData(1, new ArrayList(),
                         new ContentInfo(ContentInfo.DATA, null), certificates,
                         null, new ArrayList());
                 ContentInfo ci = new ContentInfo(ContentInfo.SIGNED_DATA, sd);
                 pkcs7Encoding = ci.getEncoded();
             }
             byte[] result = new byte[pkiPathEncoding.length];
-            System.arraycopy(pkcs7Encoding, 0, result, 0, 
+            System.arraycopy(pkcs7Encoding, 0, result, 0,
                                         pkcs7Encoding.length);
             return result;
         }
     }
 
     /**
-     * getEncodings
+     * @see java.security.cert.CertPath#getEncodings()
+     * method documentation for more info
      */
     public Iterator getEncodings() {
         return encodings.iterator();
     }
 
-    public static ASN1SequenceOf ASN1 = new ASN1SequenceOf(ASN1Any.getInstance()) {
-   
+    /**
+     * ASN.1 DER Encoder/Decoder for PkiPath structure.
+     */
+    public static ASN1SequenceOf ASN1 =
+                                    new ASN1SequenceOf(ASN1Any.getInstance()) {
+
+        /**
+         * Builds the instance of X509CertPathImpl on the base of the list
+         * of ASN.1 encodings of X.509 certificates provided via
+         * PkiPath structure.
+         * This method participates in decoding process.
+         */
         public Object getDecodedObject(BerInputStream in) throws IOException {
+            // retrieve the decoded content
             List encodings = (List) in.content;
             int size = encodings.size();
             List certificates = new ArrayList(size);
             for (int i=0; i<size; i++) {
+                // create the X.509 certificate on the base of its encoded form
+                // and add it to the list.
                 certificates.add(
-                        new X509CertImpl((Certificate) 
-                            Certificate.ASN1.decode((byte[]) encodings.get(i))));
+                    new X509CertImpl((Certificate)
+                        Certificate.ASN1.decode((byte[]) encodings.get(i))));
             }
-            return new X509CertPathImpl(certificates, PKI_PATH, in.getEncoded());
+            // create and return the resulting object
+            return new X509CertPathImpl(
+                    certificates, PKI_PATH, in.getEncoded());
         }
 
+        /**
+         * Returns the Collection of the encoded form of certificates contained
+         * in the X509CertPathImpl object to be encoded.
+         * This method participates in encoding process.
+         */
         public Collection getValues(Object object) {
+            // object to be encoded
             X509CertPathImpl cp = (X509CertPathImpl) object;
+            // if it has no certificates in it - create the sequence of size 0
             if (cp.certificates == null) {
                 return new ArrayList();
             }
@@ -250,11 +344,13 @@
             List encodings = new ArrayList(size);
             try {
                 for (int i=0; i<size; i++) {
-                    encodings.add(((X509Certificate) 
+                    // get the encoded form of certificate and place it into the
+                    // list to be encoded in PkiPath format
+                    encodings.add(((X509Certificate)
                                 cp.certificates.get(i)).getEncoded());
                 }
             } catch (CertificateEncodingException e) {
-                throw new IllegalArgumentException("Encoding Error occured");
+                throw new IllegalArgumentException("Encoding Error occurred");
             }
             return encodings;
         }



Mime
View raw message