From 6614f7fda643ebb09a1c21979a067fab17c3ab6c Mon Sep 17 00:00:00 2001 From: Megan Woods Date: Tue, 15 Jan 2019 14:55:39 +1100 Subject: Updated C# doc. Removed EJBCA EnrollmentTest as it s not viable to produce an example on .Net Framework 2.0 --- crypto/src/crmf/AuthenticatorControl.cs | 20 ++++++-- crypto/src/crmf/CertificateRequestMessage.cs | 63 +++++++++++++++++++++--- crypto/src/crmf/EncryptedValueBuilder.cs | 71 ++++++++++++++-------------- crypto/src/crmf/IEncryptedValuePadder.cs | 33 ++++++------- crypto/src/crmf/PKMacBuilder.cs | 40 ++++++++++++++++ crypto/src/crmf/PkiArchiveControl.cs | 25 ++++++++++ crypto/src/crmf/RegTokenControl.cs | 18 ++++++- 7 files changed, 207 insertions(+), 63 deletions(-) (limited to 'crypto/src/crmf') 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 { + /// + /// Carrier for an authenticator control. + /// public class AuthenticatorControl:IControl { @@ -14,21 +14,35 @@ namespace Org.BouncyCastle.Crmf private readonly DerUtf8String token; + /// + /// Basic constructor - build from a UTF-8 string representing the token. + /// + /// UTF-8 string representing the token. public AuthenticatorControl(DerUtf8String token) { this.token = token; } + /// + /// Basic constructor - build from a string representing the token. + /// + /// string representing the token. public AuthenticatorControl(String token) { this.token = new DerUtf8String(token); } + /// + /// Return the type of this control. + /// public DerObjectIdentifier Type { get { return type; } } + /// + /// Return the token associated with this control (a UTF8String). + /// 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); } + /// + /// Create a CertificateRequestMessage from the passed in bytes. + /// + /// BER/DER encoding of the CertReqMsg structure. + public CertificateRequestMessage(byte[] encoded):this(CertReqMsg.GetInstance(encoded)) + { + + } + public CertificateRequestMessage(CertReqMsg certReqMsg) { this.certReqMsg = certReqMsg; this.controls = certReqMsg.CertReq.Controls; } + /// + /// Return the underlying ASN.1 object defining this CertificateRequestMessage object. + /// + /// A CertReqMsg public CertReqMsg ToAsn1Structure() { return certReqMsg; } + /// + /// Return the certificate template contained in this message. + /// + /// a CertTemplate structure. public CertTemplate GetCertTemplate() { return this.certReqMsg.CertReq.CertTemplate; } + /// + /// Return whether or not this request has control values associated with it. + /// + /// true if there are control values present, false otherwise. public bool HasControls { get { return controls != null; } } - + /// + /// Return whether or not this request has a specific type of control value. + /// + /// the type OID for the control value we are checking for. + /// true if a control value of type is present, false otherwise. public bool HasControl(DerObjectIdentifier objectIdentifier) { return findControl(objectIdentifier) != null; } + /// + /// Return a control value of the specified type. + /// + /// the type OID for the control value we are checking for. + /// the control value if present, null otherwise. public IControl GetControl(DerObjectIdentifier type) { AttributeTypeAndValue found = findControl(type); @@ -100,16 +126,29 @@ namespace Org.BouncyCastle.Crmf return found; } + /// + /// Return whether or not this request message has a proof-of-possession field in it. + /// + /// true if proof-of-possession is present, false otherwise. public bool HasProofOfPossession { get { return certReqMsg.Popo != null; } } + /// + /// Return the type of the proof-of-possession this request message provides. + /// + /// one of: popRaVerified, popSigningKey, popKeyEncipherment, popKeyAgreement public int ProofOfPossession { get { return certReqMsg.Popo.Type; } } + /// + /// Return whether or not the proof-of-possession (POP) is of the type popSigningKey and + /// it has a public key MAC associated with it. + /// + /// true if POP is popSigningKey and a PKMAC is present, false otherwise. public bool HasSigningKeyProofOfPossessionWithPkMac { get @@ -127,7 +166,13 @@ namespace Org.BouncyCastle.Crmf } } - + /// + /// Return whether or not a signing key proof-of-possession (POP) is valid. + /// + /// a provider that can produce content verifiers for the signature contained in this POP. + /// true if the POP is valid, false otherwise. + /// if there is a problem in verification or content verifier creation. + /// if POP not appropriate. public bool IsValidSigningKeyPop(IVerifierFactoryProvider verifierProvider) { ProofOfPossession pop = certReqMsg.Popo; @@ -176,6 +221,10 @@ namespace Org.BouncyCastle.Crmf return result.IsVerified(signKey.Signature.GetBytes()); } + /// + /// Return the ASN.1 encoding of the certReqMsg we wrap. + /// + /// a byte array containing the binary encoding of the certReqMsg. 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. + /// + /// wrapper a wrapper for key used to encrypt the actual data contained in the EncryptedValue. + /// encryptor an output encryptor to encrypt the actual data contained in the EncryptedValue. + /// 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. + /// + /// a wrapper for key used to encrypt the actual data contained in the EncryptedValue. + /// encryptor an output encryptor to encrypt the actual data contained in the EncryptedValue. + /// padder a padder to ensure that the EncryptedValue created will always be a constant length. + /// 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. + /// + /// a revocation pass phrase. + ///an EncryptedValue containing the encrypted pass phrase. + /// 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. - */ + /// + /// Build an EncryptedValue structure containing the certificate contained in + /// the passed in holder. + /// + /// a holder containing a certificate. + /// an EncryptedValue containing the encrypted certificate. + /// on a failure to encrypt the data, or wrap the symmetric key for this value. + /// 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. - */ + /// + /// Build an EncryptedValue structure containing the private key contained in + /// the passed info structure. + /// + /// a PKCS#8 private key info structure. + /// an EncryptedValue containing an EncryptedPrivateKeyInfo structure. + /// on a failure to encrypt the data, or wrap the symmetric key for this value. + /// 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. - */ + + /// + /// An encrypted value padder is used to make sure that prior to a value been + /// encrypted the data is padded to a standard length. + /// public interface EncryptedValuePadder { - /** - * Return a byte array of padded data. - * - * @param data the data to be padded. - * @return a padded byte array containing data. - */ + /// + /// Return a byte array of padded data. + /// + /// the data to be padded. + /// a padded byte array containing data. + /// 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. - */ + /// + /// Return a byte array of with padding removed. + /// + /// the data to be padded. + /// an array containing the original unpadded data. + /// 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; + /// + /// Default, IterationCount = 1000, OIW=IdSha1, Mac=HmacSHA1 + /// public PKMacBuilder() : this(new AlgorithmIdentifier(OiwObjectIdentifiers.IdSha1), 1000, new AlgorithmIdentifier(IanaObjectIdentifiers.HmacSha1, DerNull.Instance), new DefaultPKMacPrimitivesProvider()) { } + /// + /// Defaults with IPKMacPrimitivesProvider + /// + /// public PKMacBuilder(IPKMacPrimitivesProvider provider) : this(new AlgorithmIdentifier(OiwObjectIdentifiers.IdSha1), 1000, new AlgorithmIdentifier(IanaObjectIdentifiers.HmacSha1, DerNull.Instance), provider) { } + /// + /// Create. + /// + /// The Mac provider + /// Digest Algorithm Id + /// Mac Algorithm Id public PKMacBuilder(IPKMacPrimitivesProvider provider, AlgorithmIdentifier digestAlgorithmIdentifier, AlgorithmIdentifier macAlgorithmIdentifier) : this(digestAlgorithmIdentifier, 1000, macAlgorithmIdentifier, provider) { } + /// + /// Create a PKMAC builder enforcing a ceiling on the maximum iteration count. + /// + /// supporting calculator + /// max allowable value for iteration count. 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; } + /// + /// Set the iteration count. + /// + /// the iteration count. + /// this + /// if iteration count is less than 100 public PKMacBuilder SetIterationCount(int iterationCount) { if (iterationCount < 100) @@ -167,6 +192,11 @@ namespace Org.BouncyCastle.Crmf return this; } + /// + /// Set PbmParameters + /// + /// The parameters. + /// this public PKMacBuilder SetParameters(PbmParameter parameters) { checkIterationCountCeiling(parameters.IterationCount.Value.IntValue); @@ -176,6 +206,11 @@ namespace Org.BouncyCastle.Crmf return this; } + /// + /// The Secure random + /// + /// The random. + /// this public PKMacBuilder SetSecureRandom(SecureRandom random) { this.random = random; @@ -183,6 +218,11 @@ namespace Org.BouncyCastle.Crmf return this; } + /// + /// Build an IMacFactory. + /// + /// The password. + /// IMacFactory 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; + /// + /// Basic constructor - build from an PKIArchiveOptions structure. + /// + /// the ASN.1 structure that will underlie this control. public PkiArchiveControl(PkiArchiveOptions pkiArchiveOptions) { this.pkiArchiveOptions = pkiArchiveOptions; } + /// + /// Return the type of this control. + /// + /// CRMFObjectIdentifiers.id_regCtrl_pkiArchiveOptions public DerObjectIdentifier Type { + get { return type; } } + /// + /// Return the underlying ASN.1 object. + /// + /// a PKIArchiveOptions structure. public Asn1Encodable Value { get { return pkiArchiveOptions; } } + /// + /// Return the archive control type, one of: encryptedPrivKey,keyGenParameters,or archiveRemGenPrivKey. + /// + /// the archive control type. public int ArchiveType { get { return pkiArchiveOptions.Type; } } + /// + /// Return whether this control contains enveloped data. + /// + /// true if the control contains enveloped data, false otherwise. public bool EnvelopedData { get @@ -47,6 +68,10 @@ namespace Org.BouncyCastle.Crmf } } + /// + /// Return the enveloped data structure contained in this control. + /// + /// a CMSEnvelopedData object. 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; + /// + /// Basic constructor - build from a UTF-8 string representing the token. + /// + /// UTF-8 string representing the token. public RegTokenControl(DerUtf8String token) { this.token = token; } - + /// + /// Basic constructor - build from a string representing the token. + /// + /// string representing the token. public RegTokenControl(String token) { this.token = new DerUtf8String(token); } + /// + /// Return the type of this control. + /// + /// CRMFObjectIdentifiers.id_regCtrl_regToken public DerObjectIdentifier Type { get { return type; } } + + /// + /// Return the token associated with this control (a UTF8String). + /// + /// a UTF8String. public Asn1Encodable Value { get { return token; } -- cgit 1.5.1