Updated C# doc.

Removed EJBCA EnrollmentTest as it s not viable to produce an example on .Net Framework 2.0

7 files changed, 207 insertions, 63 deletions

diff --git a/crypto/src/crmf/AuthenticatorControl.cs b/crypto/src/crmf/AuthenticatorControl.cs
index 7803c4418..976135ed8 100644
--- a/crypto/src/crmf/AuthenticatorControl.cs
+++ b/crypto/src/crmf/AuthenticatorControl.cs
@@ -1,12 +1,12 @@
 using System;
-using System.Collections.Generic;
-using System.Text;
-
 using Org.BouncyCastle.Asn1;
 using Org.BouncyCastle.Asn1.Crmf;
 
 namespace Org.BouncyCastle.Crmf
 {
+    /// <summary>
+    /// Carrier for an authenticator control.
+    /// </summary>
     public class AuthenticatorControl:IControl
     {
 
@@ -14,21 +14,35 @@ namespace Org.BouncyCastle.Crmf
 
         private readonly DerUtf8String token;
 
+        /// <summary>
+        /// Basic constructor - build from a UTF-8 string representing the token.
+        /// </summary>
+        /// <param name="token">UTF-8 string representing the token.</param>
         public AuthenticatorControl(DerUtf8String token)
         {
             this.token = token;
         }
 
+        /// <summary>
+        /// Basic constructor - build from a string representing the token.
+        /// </summary>
+        /// <param name="token">string representing the token.</param>
         public AuthenticatorControl(String token)
         {
             this.token = new DerUtf8String(token);
         }
 
+        /// <summary>
+        /// Return the type of this control.
+        /// </summary>
         public DerObjectIdentifier Type
         {
             get { return type; }
         }
 
+        /// <summary>
+        /// Return the token associated with this control (a UTF8String).
+        /// </summary>
         public Asn1Encodable Value {
             get { return token; }
         }
diff --git a/crypto/src/crmf/CertificateRequestMessage.cs b/crypto/src/crmf/CertificateRequestMessage.cs
index 818facade..087e8a933 100644
--- a/crypto/src/crmf/CertificateRequestMessage.cs
+++ b/crypto/src/crmf/CertificateRequestMessage.cs
@@ -1,7 +1,4 @@
 using System;
-using System.Collections.Generic;
-using System.Runtime.InteropServices;
-using System.Text;
 using Org.BouncyCastle.Asn1;
 using Org.BouncyCastle.Asn1.Crmf;
 using Org.BouncyCastle.Crypto;
@@ -19,39 +16,68 @@ namespace Org.BouncyCastle.Crmf
         private readonly CertReqMsg certReqMsg;
         private readonly Controls controls;
 
-        private static CertReqMsg ParseBytes(byte[] encoding)
-       
+        private static CertReqMsg ParseBytes(byte[] encoding)       
         {        
                 return CertReqMsg.GetInstance(encoding);
         }
 
+        /// <summary>
+        /// Create a CertificateRequestMessage from the passed in bytes.
+        /// </summary>
+        /// <param name="encoded">BER/DER encoding of the CertReqMsg structure.</param>
+        public CertificateRequestMessage(byte[] encoded):this(CertReqMsg.GetInstance(encoded))
+        {
+
+        }
+
         public CertificateRequestMessage(CertReqMsg certReqMsg)
         {
             this.certReqMsg = certReqMsg;
             this.controls = certReqMsg.CertReq.Controls;
         }
 
+        /// <summary>
+        /// Return the underlying ASN.1 object defining this CertificateRequestMessage object.
+        /// </summary>
+        /// <returns>A CertReqMsg</returns>
         public CertReqMsg ToAsn1Structure()
         {
             return certReqMsg; 
         }
 
+        /// <summary>
+        /// Return the certificate template contained in this message.
+        /// </summary>
+        /// <returns>a CertTemplate structure.</returns>
         public CertTemplate GetCertTemplate()
         {
             return this.certReqMsg.CertReq.CertTemplate;
         }
 
+        /// <summary>
+        /// Return whether or not this request has control values associated with it.
+        /// </summary>
+        /// <returns>true if there are control values present, false otherwise.</returns>
         public bool HasControls
         {
             get { return controls != null; }
         }
 
-
+        /// <summary>
+        /// Return whether or not this request has a specific type of control value.
+        /// </summary>
+        /// <param name="objectIdentifier">the type OID for the control value we are checking for.</param>
+        /// <returns>true if a control value of type is present, false otherwise.</returns>
         public bool HasControl(DerObjectIdentifier objectIdentifier)
         {
             return findControl(objectIdentifier) != null;
         }
 
+        /// <summary>
+        /// Return a control value of the specified type.
+        /// </summary>
+        /// <param name="type">the type OID for the control value we are checking for.</param>
+        /// <returns>the control value if present, null otherwise.</returns>
         public IControl GetControl(DerObjectIdentifier type)
         {
             AttributeTypeAndValue found = findControl(type);
@@ -100,16 +126,29 @@ namespace Org.BouncyCastle.Crmf
             return found;
         }
 
+        /// <summary>
+        /// Return whether or not this request message has a proof-of-possession field in it.
+        /// </summary>
+        /// <returns>true if proof-of-possession is present, false otherwise.</returns>
         public bool HasProofOfPossession
         {
             get { return certReqMsg.Popo != null; }
         }
 
+        /// <summary>
+        /// Return the type of the proof-of-possession this request message provides.
+        /// </summary>
+        /// <returns>one of: popRaVerified, popSigningKey, popKeyEncipherment, popKeyAgreement</returns>
         public int ProofOfPossession
         {
             get { return certReqMsg.Popo.Type; }
         }
 
+        /// <summary>
+        /// Return whether or not the proof-of-possession (POP) is of the type popSigningKey and
+        /// it has a public key MAC associated with it.
+        /// </summary>
+        /// <returns>true if POP is popSigningKey and a PKMAC is present, false otherwise.</returns>
         public bool HasSigningKeyProofOfPossessionWithPkMac
         {
             get
@@ -127,7 +166,13 @@ namespace Org.BouncyCastle.Crmf
 
             }
         }
-   
+        /// <summary>
+        /// Return whether or not a signing key proof-of-possession (POP) is valid.
+        /// </summary>
+        /// <param name="verifierProvider">a provider that can produce content verifiers for the signature contained in this POP.</param>
+        /// <returns>true if the POP is valid, false otherwise.</returns>
+        /// <exception cref="InvalidOperationException">if there is a problem in verification or content verifier creation.</exception>
+        /// <exception cref="InvalidOperationException">if POP not appropriate.</exception>
         public bool IsValidSigningKeyPop(IVerifierFactoryProvider verifierProvider)
         {
             ProofOfPossession pop = certReqMsg.Popo;
@@ -176,6 +221,10 @@ namespace Org.BouncyCastle.Crmf
             return result.IsVerified(signKey.Signature.GetBytes());
         }
 
+        /// <summary>
+        /// Return the ASN.1 encoding of the certReqMsg we wrap.
+        /// </summary>
+        /// <returns>a byte array containing the binary encoding of the certReqMsg.</returns>
         public byte[] GetEncoded()
         {
             return certReqMsg.GetEncoded();
diff --git a/crypto/src/crmf/EncryptedValueBuilder.cs b/crypto/src/crmf/EncryptedValueBuilder.cs
index f9279bd53..28d5b52b4 100644
--- a/crypto/src/crmf/EncryptedValueBuilder.cs
+++ b/crypto/src/crmf/EncryptedValueBuilder.cs
@@ -24,23 +24,23 @@ namespace Org.BouncyCastle.Crmf
         private ICipherBuilderWithKey encryptor;
         private EncryptedValuePadder padder;
 
-        /**
-         * Create a builder that makes EncryptedValue structures.
-         *
-         * @param wrapper a wrapper for key used to encrypt the actual data contained in the EncryptedValue.
-         * @param encryptor  an output encryptor to encrypt the actual data contained in the EncryptedValue. 
-         */
+        ///
+        /// Create a builder that makes EncryptedValue structures.
+        ///
+        /// <param name="wrapper">wrapper a wrapper for key used to encrypt the actual data contained in the EncryptedValue.</param>
+        /// <param name="encryptor">encryptor  an output encryptor to encrypt the actual data contained in the EncryptedValue. </param>
+        ///
         public EncryptedValueBuilder(IKeyWrapper wrapper, ICipherBuilderWithKey encryptor) : this(wrapper, encryptor, null)
         {
         }
 
-        /**
-         * Create a builder that makes EncryptedValue structures with fixed length blocks padded using the passed in padder.
-         *
-         * @param wrapper a wrapper for key used to encrypt the actual data contained in the EncryptedValue.
-         * @param encryptor  an output encryptor to encrypt the actual data contained in the EncryptedValue.
-         * @param padder a padder to ensure that the EncryptedValue created will always be a constant length.
-         */
+        ///
+        /// Create a builder that makes EncryptedValue structures with fixed length blocks padded using the passed in padder.
+        ///
+        /// <param name="wrapper">a wrapper for key used to encrypt the actual data contained in the EncryptedValue.</param>
+        /// <param name="encryptor">encryptor  an output encryptor to encrypt the actual data contained in the EncryptedValue.</param>
+        /// <param name="padder">padder a padder to ensure that the EncryptedValue created will always be a constant length.</param>
+        ///
         public EncryptedValueBuilder(IKeyWrapper wrapper, ICipherBuilderWithKey encryptor, EncryptedValuePadder padder)
         {
             this.wrapper = wrapper;
@@ -48,26 +48,25 @@ namespace Org.BouncyCastle.Crmf
             this.padder = padder;
         }
 
-        /**
-         * Build an EncryptedValue structure containing the passed in pass phrase.
-         *
-         * @param revocationPassphrase  a revocation pass phrase.
-         * @return an EncryptedValue containing the encrypted pass phrase.
-         * @throws CrmfException on a failure to encrypt the data, or wrap the symmetric key for this value.
-         */
+        ///
+        /// Build an EncryptedValue structure containing the passed in pass phrase.
+        ///
+        /// <param name="revocationPassphrase">a revocation pass phrase.</param>
+        ///<returns>an EncryptedValue containing the encrypted pass phrase.</returns>       
+        ///
         public EncryptedValue Build(char[] revocationPassphrase)
         {
             return encryptData(padData(Strings.ToUtf8ByteArray(revocationPassphrase)));
         }
 
-        /**
-         * Build an EncryptedValue structure containing the certificate contained in
-         * the passed in holder.
-         *
-         * @param holder  a holder containing a certificate.
-         * @return an EncryptedValue containing the encrypted certificate.
-         * @throws CrmfException on a failure to encrypt the data, or wrap the symmetric key for this value.
-         */
+        ///<summary>
+        /// Build an EncryptedValue structure containing the certificate contained in
+        /// the passed in holder.
+        ///</summary>
+        /// <param name="holder">a holder containing a certificate.</param>
+        ///  <returns>an EncryptedValue containing the encrypted certificate.</returns>
+        /// <exception cref="CrmfException">on a failure to encrypt the data, or wrap the symmetric key for this value.</exception>
+        ///
         public EncryptedValue Build(X509Certificate holder)
         {
             try
@@ -80,14 +79,14 @@ namespace Org.BouncyCastle.Crmf
             }
         }
 
-        /**
-         * Build an EncryptedValue structure containing the private key contained in
-         * the passed info structure.
-         *
-         * @param privateKeyInfo  a PKCS#8 private key info structure.
-         * @return an EncryptedValue containing an EncryptedPrivateKeyInfo structure.
-         * @throws CrmfException on a failure to encrypt the data, or wrap the symmetric key for this value.
-         */
+        ///<summary>
+        /// Build an EncryptedValue structure containing the private key contained in
+        /// the passed info structure.
+        ///</summary>
+        /// <param name="privateKeyInfo">a PKCS#8 private key info structure.</param>
+        /// <returns>an EncryptedValue containing an EncryptedPrivateKeyInfo structure.</returns>
+        /// <exception cref="CrmfException">on a failure to encrypt the data, or wrap the symmetric key for this value.</exception>
+        ///
         public EncryptedValue Build(PrivateKeyInfo privateKeyInfo)
         {
             Pkcs8EncryptedPrivateKeyInfoBuilder encInfoBldr = new Pkcs8EncryptedPrivateKeyInfoBuilder(privateKeyInfo);
diff --git a/crypto/src/crmf/IEncryptedValuePadder.cs b/crypto/src/crmf/IEncryptedValuePadder.cs
index b620186dc..b12993e1f 100644
--- a/crypto/src/crmf/IEncryptedValuePadder.cs
+++ b/crypto/src/crmf/IEncryptedValuePadder.cs
@@ -4,26 +4,27 @@ using System.Text;
 
 namespace Org.BouncyCastle.Crmf
 {
-    /**
-     * An encrypted value padder is used to make sure that prior to a value been
-     * encrypted the data is padded to a standard length.
-     */
+
+     /// <summary>
+     /// An encrypted value padder is used to make sure that prior to a value been
+     /// encrypted the data is padded to a standard length.
+     /// </summary>
     public interface EncryptedValuePadder
     {
-        /**
-         * Return a byte array of padded data.
-         *
-         * @param data the data to be padded.
-         * @return a padded byte array containing data.
-         */
+        ///
+        /// <summary>Return a byte array of padded data.</summary>
+        ///
+        /// <param name="data">the data to be padded.</param>
+        /// <returns>a padded byte array containing data.</returns>
+        ///
         byte[] GetPaddedData(byte[] data);
 
-        /**
-         * Return a byte array of with padding removed.
-         *
-         * @param paddedData the data to be padded.
-         * @return an array containing the original unpadded data.
-         */
+        ///
+        /// <summary>Return a byte array of with padding removed.</summary>
+        ///
+        /// <param name="paddedData">the data to be padded.</param>
+        /// <returns>an array containing the original unpadded data.</returns>
+        ///
         byte[] GetUnpaddedData(byte[] paddedData);
     }
 }
diff --git a/crypto/src/crmf/PKMacBuilder.cs b/crypto/src/crmf/PKMacBuilder.cs
index 3dec4e86f..00bec9f8b 100644
--- a/crypto/src/crmf/PKMacBuilder.cs
+++ b/crypto/src/crmf/PKMacBuilder.cs
@@ -107,27 +107,46 @@ namespace Org.BouncyCastle.Crmf
         private byte[] salt;
         private int maxIterations;
 
+        /// <summary>
+        /// Default, IterationCount = 1000, OIW=IdSha1, Mac=HmacSHA1
+        /// </summary>
         public PKMacBuilder() :
             this(new AlgorithmIdentifier(OiwObjectIdentifiers.IdSha1), 1000, new AlgorithmIdentifier(IanaObjectIdentifiers.HmacSha1, DerNull.Instance), new DefaultPKMacPrimitivesProvider())
         {
         }
 
+        /// <summary>
+        /// Defaults with IPKMacPrimitivesProvider
+        /// </summary>
+        /// <param name="provider"></param>
         public PKMacBuilder(IPKMacPrimitivesProvider provider) :
             this(new AlgorithmIdentifier(OiwObjectIdentifiers.IdSha1), 1000, new AlgorithmIdentifier(IanaObjectIdentifiers.HmacSha1, DerNull.Instance), provider)
         {       
         }
 
+        /// <summary>
+        /// Create.
+        /// </summary>
+        /// <param name="provider">The Mac provider</param>
+        /// <param name="digestAlgorithmIdentifier">Digest Algorithm Id</param>
+        /// <param name="macAlgorithmIdentifier">Mac Algorithm Id</param>
         public PKMacBuilder(IPKMacPrimitivesProvider provider, AlgorithmIdentifier digestAlgorithmIdentifier, AlgorithmIdentifier macAlgorithmIdentifier) :
             this(digestAlgorithmIdentifier, 1000, macAlgorithmIdentifier, provider)
         {
         }
 
+        /// <summary>
+        /// Create a PKMAC builder enforcing a ceiling on the maximum iteration count.
+        /// </summary>
+        /// <param name="provider">supporting calculator</param>
+        /// <param name="maxIterations">max allowable value for iteration count.</param>
         public PKMacBuilder(IPKMacPrimitivesProvider provider, int maxIterations)
         {
             this.provider = provider;
             this.maxIterations = maxIterations;
         }
 
+
         private PKMacBuilder(AlgorithmIdentifier digestAlgorithmIdentifier, int iterationCount, AlgorithmIdentifier macAlgorithmIdentifier, IPKMacPrimitivesProvider provider)
         {
             this.iterationCount = iterationCount;
@@ -154,6 +173,12 @@ namespace Org.BouncyCastle.Crmf
             return this;
         }
 
+        /// <summary>
+        /// Set the iteration count.
+        /// </summary>
+        /// <param name="iterationCount">the iteration count.</param>
+        /// <returns>this</returns>
+        /// <exception cref="ArgumentException">if iteration count is less than 100</exception>
         public PKMacBuilder SetIterationCount(int iterationCount)
         {
             if (iterationCount < 100)
@@ -167,6 +192,11 @@ namespace Org.BouncyCastle.Crmf
             return this;
         }
 
+        /// <summary>
+        /// Set PbmParameters
+        /// </summary>
+        /// <param name="parameters">The parameters.</param>
+        /// <returns>this</returns>
         public PKMacBuilder SetParameters(PbmParameter parameters)
         {
             checkIterationCountCeiling(parameters.IterationCount.Value.IntValue);
@@ -176,6 +206,11 @@ namespace Org.BouncyCastle.Crmf
             return this;
         }
 
+        /// <summary>
+        /// The Secure random
+        /// </summary>
+        /// <param name="random">The random.</param>
+        /// <returns>this</returns>
         public PKMacBuilder SetSecureRandom(SecureRandom random)
         {
             this.random = random;
@@ -183,6 +218,11 @@ namespace Org.BouncyCastle.Crmf
             return this;          
         }
 
+        /// <summary>
+        /// Build an IMacFactory.
+        /// </summary>
+        /// <param name="password">The password.</param>
+        /// <returns>IMacFactory</returns>
         public IMacFactory Build(char[] password)
         {
             if (parameters != null)
diff --git a/crypto/src/crmf/PkiArchiveControl.cs b/crypto/src/crmf/PkiArchiveControl.cs
index ec8fb7671..d533e6c52 100644
--- a/crypto/src/crmf/PkiArchiveControl.cs
+++ b/crypto/src/crmf/PkiArchiveControl.cs
@@ -18,26 +18,47 @@ namespace Org.BouncyCastle.Crmf
 
         private readonly PkiArchiveOptions pkiArchiveOptions;
 
+        /// <summary>
+        /// Basic constructor - build from an PKIArchiveOptions structure.
+        /// </summary>
+        /// <param name="pkiArchiveOptions">the ASN.1 structure that will underlie this control.</param>
         public PkiArchiveControl(PkiArchiveOptions pkiArchiveOptions)
         {
             this.pkiArchiveOptions = pkiArchiveOptions;
         }
 
+        /// <summary>
+        /// Return the type of this control.
+        /// </summary>
+        /// <returns>CRMFObjectIdentifiers.id_regCtrl_pkiArchiveOptions</returns>
         public DerObjectIdentifier Type
         {
+            
             get { return type; }
         }
 
+        /// <summary>
+        /// Return the underlying ASN.1 object.
+        /// </summary>
+        /// <returns>a PKIArchiveOptions structure.</returns>    
         public Asn1Encodable Value
         {
             get { return pkiArchiveOptions; }
         }
 
+        /// <summary>
+        /// Return the archive control type, one of: encryptedPrivKey,keyGenParameters,or archiveRemGenPrivKey.
+        /// </summary>
+        /// <returns>the archive control type.</returns>
         public int ArchiveType
         {
             get { return pkiArchiveOptions.Type; }
         }
 
+        /// <summary>
+        /// Return whether this control contains enveloped data.
+        /// </summary>
+        /// <returns>true if the control contains enveloped data, false otherwise.</returns>
         public bool EnvelopedData
         {
             get
@@ -47,6 +68,10 @@ namespace Org.BouncyCastle.Crmf
             }
         }
 
+        /// <summary>
+        /// Return the enveloped data structure contained in this control.
+        /// </summary>
+        /// <returns>a CMSEnvelopedData object.</returns>
         public CmsEnvelopedData GetEnvelopedData()
         {
             try
diff --git a/crypto/src/crmf/RegTokenControl.cs b/crypto/src/crmf/RegTokenControl.cs
index b53ce1922..90e956f67 100644
--- a/crypto/src/crmf/RegTokenControl.cs
+++ b/crypto/src/crmf/RegTokenControl.cs
@@ -14,20 +14,36 @@ namespace Org.BouncyCastle.Crmf
     
         private readonly DerUtf8String token;
 
+        /// <summary>
+        /// Basic constructor - build from a UTF-8 string representing the token.
+        /// </summary>
+        /// <param name="token">UTF-8 string representing the token.</param>
         public RegTokenControl(DerUtf8String token)
         {
             this.token = token;
         }
-
+        /// <summary>
+        /// Basic constructor - build from a string representing the token.
+        /// </summary>
+        /// <param name="token">string representing the token.</param>
         public RegTokenControl(String token)
         {
             this.token = new DerUtf8String(token);
         }
 
+        /// <summary>
+        /// Return the type of this control.
+        /// </summary>
+        /// <returns>CRMFObjectIdentifiers.id_regCtrl_regToken</returns>
         public DerObjectIdentifier Type
         {
             get { return type; }
         }
+
+        /// <summary>
+        /// Return the token associated with this control (a UTF8String).
+        /// </summary>
+        /// <returns>a UTF8String.</returns>
         public Asn1Encodable Value
         {
             get { return token; }