Skip to content

docs: add XML documentation for X.509 certificate and CRL generators (Batch 12a-1) #684

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
KonradSop wants to merge 1 commit into from
+151 −49
Closed

docs: add XML documentation for X.509 certificate and CRL generators (Batch 12a-1) #684

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 18 additions & 4 deletions crypto/src/x509/X509V1CertificateGenerator.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,9 @@
namespace Org.BouncyCastle.X509
{
/// <summary>
/// Class to Generate X509V1 Certificates.
/// Generator for X.509 version 1 certificates as defined in RFC 5280.
/// Builds the TBSCertificate structure and signs the result via
/// <see cref="Generate(ISignatureFactory)"/>.
/// </summary>
public class X509V1CertificateGenerator
{
Expand All @@ -36,9 +38,14 @@ public void Reset()
/// <summary>
/// Set the certificate's serial number.
/// </summary>
/// <remarks>Make serial numbers long, if you have no serial number policy make sure the number is at least 16 bytes of secure random data.
/// You will be surprised how ugly a serial number collision can get.</remarks>
/// <remarks>
/// Make serial numbers long; if you have no serial number policy make sure the number is at least
/// 16 bytes of secure random data. You will be surprised how ugly a serial number collision can get.
/// </remarks>
/// <param name="serialNumber">The serial number.</param>
/// <exception cref="ArgumentException">
/// <paramref name="serialNumber"/> is not a positive integer.
/// </exception>
public void SetSerialNumber(
BigInteger serialNumber)
{
Expand All @@ -59,8 +66,12 @@ public void SetIssuerDN(
X509Name issuer)
{
tbsGen.SetIssuer(issuer);
}
}

/// <summary>
/// Sets the certificate validity period from a pre-built <see cref="Validity"/> structure.
/// </summary>
/// <param name="validity">The not-before and not-after times.</param>
public void SetValidity(Validity validity)
{
tbsGen.SetValidity(validity);
Expand Down Expand Up @@ -101,6 +112,9 @@ public void SetSubjectDN(
/// Set the public key that this certificate identifies.
/// </summary>
/// <param name="publicKey"/>
/// <exception cref="ArgumentException">
/// The public key could not be encoded as <see cref="SubjectPublicKeyInfo"/>.
/// </exception>
public void SetPublicKey(
AsymmetricKeyParameter publicKey)
{
Expand Down
127 changes: 86 additions & 41 deletions crypto/src/x509/X509V2CRLGenerator.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,27 +8,39 @@

namespace Org.BouncyCastle.X509
{
/**
* class to produce an X.509 Version 2 CRL.
*/
/// <summary>
/// Generator for X.509 version 2 certificate revocation lists (CRLs) as defined in RFC 5280.
/// Builds the TBSCertList structure, optional CRL extensions, and signs the result via
/// <see cref="Generate(ISignatureFactory)"/>.
/// </summary>
public class X509V2CrlGenerator
{
private readonly X509ExtensionsGenerator extGenerator = new X509ExtensionsGenerator();

private V2TbsCertListGenerator tbsGen;

/// <summary>
/// Creates an empty version 2 CRL generator.
/// </summary>
public X509V2CrlGenerator()
{
tbsGen = new V2TbsCertListGenerator();
}

/// <summary>Create a builder for a version 2 CRL, initialised with another CRL.</summary>
/// <summary>
/// Creates a generator for a version 2 CRL, initialised from another CRL.
/// </summary>
/// <param name="template">Template CRL to base the new one on.</param>
public X509V2CrlGenerator(X509Crl template)
: this(template.CertificateList)
{
}

/// <summary>
/// Creates a generator for a version 2 CRL, initialised from a parsed
/// <see cref="CertificateList"/> structure.
/// </summary>
/// <param name="template">Template certificate list to copy issuer, dates, entries and extensions from.</param>
public X509V2CrlGenerator(CertificateList template)
{
tbsGen = new V2TbsCertListGenerator();
Expand All @@ -55,41 +67,55 @@ public X509V2CrlGenerator(CertificateList template)
}
}

/**
* reset the generator
*/
/// <summary>
/// Resets the generator to an empty CRL state, discarding issuer, dates, entries and extensions.
/// </summary>
public void Reset()
{
tbsGen = new V2TbsCertListGenerator();
extGenerator.Reset();
}

/**
* Set the issuer distinguished name - the issuer is the entity whose private key is used to sign the
* certificate.
*/
/// <summary>
/// Sets the issuer distinguished name — the entity whose private key signs the CRL.
/// </summary>
/// <param name="issuer">The issuer's distinguished name.</param>
public void SetIssuerDN(
X509Name issuer)
{
tbsGen.SetIssuer(issuer);
}

/// <summary>
/// Sets the time at which this CRL was issued (<c>thisUpdate</c> in the TBSCertList).
/// </summary>
/// <param name="date">The issue time.</param>
public void SetThisUpdate(
DateTime date)
{
tbsGen.SetThisUpdate(new Time(date));
}

/// <summary>
/// Sets the time by which the next CRL in the sequence is expected to be issued
/// (<c>nextUpdate</c> in the TBSCertList).
/// </summary>
/// <param name="date">The next update time.</param>
public void SetNextUpdate(
DateTime date)
{
tbsGen.SetNextUpdate(new Time(date));
}

/**
* Reason being as indicated by CrlReason, i.e. CrlReason.KeyCompromise
* or 0 if CrlReason is not to be used
**/
/// <summary>
/// Adds a revoked-certificate entry with an optional <see cref="CrlReason"/> code.
/// </summary>
/// <param name="userCertificate">Serial number of the revoked certificate.</param>
/// <param name="revocationDate">The revocation date.</param>
/// <param name="reason">
/// Reason code as defined by <see cref="CrlReason"/> (for example
/// <see cref="CrlReason.KeyCompromise"/>), or <c>0</c> to omit a reason extension.
/// </param>
public void AddCrlEntry(
BigInteger userCertificate,
DateTime revocationDate,
Expand All @@ -98,11 +124,15 @@ public void AddCrlEntry(
tbsGen.AddCrlEntry(new DerInteger(userCertificate), new Time(revocationDate), reason);
}

/**
* Add a CRL entry with an Invalidity Date extension as well as a CrlReason extension.
* Reason being as indicated by CrlReason, i.e. CrlReason.KeyCompromise
* or 0 if CrlReason is not to be used
**/
/// <summary>
/// Adds a revoked-certificate entry with <see cref="CrlReason"/> and an Invalidity Date extension.
/// </summary>
/// <param name="userCertificate">Serial number of the revoked certificate.</param>
/// <param name="revocationDate">The revocation date.</param>
/// <param name="reason">
/// Reason code as defined by <see cref="CrlReason"/>, or <c>0</c> to omit a reason extension.
/// </param>
/// <param name="invalidityDate">The invalidity date carried in the Invalidity Date extension.</param>
public void AddCrlEntry(
BigInteger userCertificate,
DateTime revocationDate,
Expand All @@ -113,9 +143,12 @@ public void AddCrlEntry(
Rfc5280Asn1Utilities.CreateGeneralizedTime(invalidityDate));
}

/**
* Add a CRL entry with extensions.
**/
/// <summary>
/// Adds a revoked-certificate entry with caller-supplied CRL entry extensions.
/// </summary>
/// <param name="userCertificate">Serial number of the revoked certificate.</param>
/// <param name="revocationDate">The revocation date.</param>
/// <param name="extensions">Extensions to attach to this CRL entry.</param>
public void AddCrlEntry(
BigInteger userCertificate,
DateTime revocationDate,
Expand All @@ -124,11 +157,11 @@ public void AddCrlEntry(
tbsGen.AddCrlEntry(new DerInteger(userCertificate), new Time(revocationDate), extensions);
}

/**
* Add the CRLEntry objects contained in a previous CRL.
*
* @param other the X509Crl to source the other entries from.
*/
/// <summary>
/// Copies all revoked-certificate entries from another CRL into this generator.
/// </summary>
/// <param name="other">The CRL whose entries are to be added.</param>
/// <exception cref="ArgumentNullException"><paramref name="other"/> is <c>null</c>.</exception>
public void AddCrl(X509Crl other)
{
if (other == null)
Expand All @@ -145,9 +178,12 @@ public void AddCrl(X509Crl other)
}
}

/**
* add a given extension field for the standard extensions tag (tag 0)
*/
/// <summary>
/// Adds a CRL extension identified by a dotted-decimal OID string.
/// </summary>
/// <param name="oid">Dotted-decimal object identifier.</param>
/// <param name="critical"><c>true</c> if the extension is marked critical.</param>
/// <param name="extensionValue">The DER-encoded extension value.</param>
public void AddExtension(
string oid,
bool critical,
Expand All @@ -156,9 +192,12 @@ public void AddExtension(
extGenerator.AddExtension(new DerObjectIdentifier(oid), critical, extensionValue);
}

/**
* add a given extension field for the standard extensions tag (tag 0)
*/
/// <summary>
/// Adds a CRL extension.
/// </summary>
/// <param name="oid">The extension object identifier.</param>
/// <param name="critical"><c>true</c> if the extension is marked critical.</param>
/// <param name="extensionValue">The DER-encoded extension value.</param>
public void AddExtension(
DerObjectIdentifier oid,
bool critical,
Expand All @@ -167,9 +206,12 @@ public void AddExtension(
extGenerator.AddExtension(oid, critical, extensionValue);
}

/**
* add a given extension field for the standard extensions tag (tag 0)
*/
/// <summary>
/// Adds a CRL extension identified by a dotted-decimal OID string.
/// </summary>
/// <param name="oid">Dotted-decimal object identifier.</param>
/// <param name="critical"><c>true</c> if the extension is marked critical.</param>
/// <param name="extensionValue">Raw octets of the extension value.</param>
public void AddExtension(
string oid,
bool critical,
Expand All @@ -178,9 +220,12 @@ public void AddExtension(
extGenerator.AddExtension(new DerObjectIdentifier(oid), critical, DerOctetString.FromContents(extensionValue));
}

/**
* add a given extension field for the standard extensions tag (tag 0)
*/
/// <summary>
/// Adds a CRL extension.
/// </summary>
/// <param name="oid">The extension object identifier.</param>
/// <param name="critical"><c>true</c> if the extension is marked critical.</param>
/// <param name="extensionValue">Raw octets of the extension value.</param>
public void AddExtension(
DerObjectIdentifier oid,
bool critical,
Expand Down Expand Up @@ -223,7 +268,7 @@ public X509Crl Generate(ISignatureFactory signatureFactory)
/// <param name="isCritical">Whether the 'alt' extensions should be marked critical.</param>
/// <param name="altSignatureFactory">A <see cref="ISignatureFactory">signature factory</see> used to create the
/// altSignatureAlgorithm and altSignatureValue extensions.</param>
/// <returns>An <see cref="X509Certificate"/>.</returns>
/// <returns>An <see cref="X509Crl"/>.</returns>
public X509Crl Generate(ISignatureFactory signatureFactory, bool isCritical,
ISignatureFactory altSignatureFactory)
{
Expand Down
51 changes: 47 additions & 4 deletions crypto/src/x509/X509V3CertificateGenerator.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,26 +10,41 @@
namespace Org.BouncyCastle.X509
{
/// <summary>
/// A class to Generate Version 3 X509Certificates.
/// Generator for X.509 version 3 certificates as defined in RFC 5280.
/// Builds the TBSCertificate structure, optional v3 extensions, and signs the result via
/// <see cref="Generate(ISignatureFactory)"/>.
/// </summary>
public class X509V3CertificateGenerator
{
private readonly X509ExtensionsGenerator extGenerator = new X509ExtensionsGenerator();

private V3TbsCertificateGenerator tbsGen;

/// <summary>
/// Creates an empty version 3 certificate generator.
/// </summary>
public X509V3CertificateGenerator()
{
tbsGen = new V3TbsCertificateGenerator();
}

/// <summary>Create a generator for a version 3 certificate, initialised with another certificate.</summary>
/// <summary>
/// Creates a generator for a version 3 certificate, initialised from another certificate.
/// </summary>
/// <param name="template">Template certificate to base the new one on.</param>
public X509V3CertificateGenerator(X509Certificate template)
: this(template.CertificateStructure)
{
}

/// <summary>
/// Creates a generator for a version 3 certificate, initialised from a parsed
/// <see cref="X509CertificateStructure"/>.
/// </summary>
/// <param name="template">
/// Template certificate structure to copy serial number, issuer, validity, subject, public key and
/// extensions from (excluding alternate public key and alternate signature extensions).
/// </param>
public X509V3CertificateGenerator(X509CertificateStructure template)
{
tbsGen = new V3TbsCertificateGenerator();
Expand Down Expand Up @@ -67,9 +82,14 @@ public void Reset()
/// <summary>
/// Set the certificate's serial number.
/// </summary>
/// <remarks>Make serial numbers long, if you have no serial number policy make sure the number is at least 16 bytes of secure random data.
/// You will be surprised how ugly a serial number collision can Get.</remarks>
/// <remarks>
/// Make serial numbers long; if you have no serial number policy make sure the number is at least
/// 16 bytes of secure random data. You will be surprised how ugly a serial number collision can get.
/// </remarks>
/// <param name="serialNumber">The serial number.</param>
/// <exception cref="ArgumentException">
/// <paramref name="serialNumber"/> is not a positive integer.
/// </exception>
public void SetSerialNumber(
BigInteger serialNumber)
{
Expand All @@ -92,6 +112,10 @@ public void SetIssuerDN(
tbsGen.SetIssuer(issuer);
}

/// <summary>
/// Sets the certificate validity period from a pre-built <see cref="Validity"/> structure.
/// </summary>
/// <param name="validity">The not-before and not-after times.</param>
public void SetValidity(Validity validity)
{
tbsGen.SetValidity(validity);
Expand Down Expand Up @@ -220,11 +244,24 @@ public void AddExtension(string oid, bool critical, byte[] extensionValue) =>
public void AddExtension(DerObjectIdentifier oid, bool critical, byte[] extensionValue) =>
extGenerator.AddExtension(oid, critical, DerOctetString.FromContents(extensionValue));

/// <summary>
/// Adds a pre-built extension value to this certificate.
/// </summary>
/// <param name="oid">The extension object identifier.</param>
/// <param name="x509Extension">The extension, including criticality flag and value.</param>
public void AddExtension(DerObjectIdentifier oid, X509Extension x509Extension) =>
extGenerator.AddExtension(oid, x509Extension);

/// <summary>
/// Adds a parsed ASN.1 extension to this certificate.
/// </summary>
/// <param name="extension">The extension to add.</param>
public void AddExtension(Asn1.X509.Extension extension) => extGenerator.AddExtension(extension);

/// <summary>
/// Adds all extensions from an <see cref="X509Extensions"/> collection.
/// </summary>
/// <param name="extensions">The extensions to copy into this certificate.</param>
public void AddExtensions(X509Extensions extensions) => extGenerator.AddExtensions(extensions);

/// <summary>
Expand All @@ -239,6 +276,12 @@ public void CopyAndAddExtension(string oid, bool critical, X509Certificate cert)
/// Add a given extension field for the standard extensions tag (tag 3),
/// copying the extension value from another certificate.
/// </summary>
/// <param name="oid">The extension object identifier.</param>
/// <param name="critical"><c>true</c> if the copied extension should be marked critical.</param>
/// <param name="cert">The certificate to copy the extension value from.</param>
/// <exception cref="CertificateParsingException">
/// <paramref name="cert"/> does not contain an extension with the given OID.
/// </exception>
public void CopyAndAddExtension(DerObjectIdentifier oid, bool critical, X509Certificate cert)
{
X509Extension ext = cert.GetExtension(oid) ??
Expand Down