Chilkat.Csr Class Overview

Chilkat.Csr creates, loads, inspects, and verifies Certificate Signing Requests. It provides subject distinguished-name fields, Subject Alternative Name support, RSA/ECDSA private-key signing, PEM and DER output, extension-request support, public-key extraction, and CSR signature verification.

What the Class Is Used For

Use Chilkat.Csr when an application needs to generate a CSR to send to a certificate authority, or when it needs to load and inspect an existing CSR. A CSR contains the requested certificate subject information, the public key, optional extensions such as Subject Alternative Names, and a signature created with the matching private key.

Create CSRs Set subject fields, add SANs, choose the hash algorithm, and generate PEM or DER CSR output using an RSA or ECDSA private key.
Load and Inspect CSRs Load a CSR from PEM, read subject fields, extract SANs, retrieve extension requests, and get the CSR public key.
Customize Subject Fields Use standard properties for common DN fields or set additional fields directly by OID.
Verify CSR Integrity Verify that the CSR signature is valid and corresponds to the public key in the request.

Typical CSR Generation Workflow

  1. Create a Csr object.
  2. Set the required CommonName property.
  3. Set optional subject fields such as Company, CompanyDivision, Country, State, Locality, and EmailAddress.
  4. Add Subject Alternative Names with AddSan, if the certificate should contain SAN entries.
  5. Optionally set HashAlgorithm. The default is SHA256.
  6. For RSA-PSS signing, set PssPadding and optionally MgfHashAlg.
  7. Optionally add an extension request with SetExtensionRequest.
  8. Generate the CSR as PEM with GenCsrPem, or as DER bytes with GenCsrBd.
  9. Check LastErrorText after failures or unexpected behavior.

Typical CSR Inspection Workflow

  1. Load a CSR PEM string with LoadCsrPem.
  2. Read populated subject properties such as CommonName, Company, Country, and EmailAddress.
  3. Retrieve specific subject fields by OID with GetSubjectField.
  4. Retrieve Subject Alternative Names with GetSans.
  5. Retrieve the public key with GetPublicKey.
  6. Retrieve the extension request with GetExtensionRequest, if present.
  7. Verify the CSR signature with VerifyCsr.

Core Concepts

Concept Meaning Important Members
Certificate Signing Request A signed request containing the desired certificate subject information, public key, and optional requested extensions. GenCsrPem, GenCsrBd, LoadCsrPem
Subject Distinguished Name The identity fields requested for the certificate subject, such as CN, O, OU, C, ST, L, and email address. CommonName, Company, SetSubjectField
Subject Alternative Names Additional identities requested for the certificate, commonly DNS names, IP addresses, or email addresses. AddSan, GetSans
CSR Public Key The public key embedded in the CSR. The CA uses it when issuing the certificate. GetPublicKey
CSR Signature The request is signed by the matching private key to prove possession of the private key. GenCsrPem, GenCsrBd, VerifyCsr
Extension Request A PKCS#9 extensionRequest attribute, identified by OID 1.2.840.113549.1.9.14, used to request certificate extensions. SetExtensionRequest, GetExtensionRequest

Subject Properties

Property DN Field OID Required? Purpose
CommonName CN 2.5.4.3 Yes Common name for the certificate. For SSL/TLS certificates, this is typically a domain name. For email certificates, this is typically an email address.
Company O 2.5.4.10 No Organization or company name.
CompanyDivision OU 2.5.4.11 No Organizational unit or company division.
Country C 2.5.4.6 No Two-letter uppercase country abbreviation, such as US.
State S or ST 2.5.4.8 No State or province.
Locality L 2.5.4.7 No Locality, city, or town.
EmailAddress E 1.2.840.113549.1.9.1 No Email address for the requested certificate.
Required field: CommonName is required for CSR generation. Other subject fields are optional and may be left empty.

Signing and Hash Options

Property Purpose Values / Guidance
HashAlgorithm Hash algorithm used when creating the CSR signature. Default is SHA256. Can be set to SHA1, SHA256, SHA384, or SHA512.
PssPadding Uses RSASSA-PSS padding when the private key is RSA. Only applies to RSA private keys. ECDSA keys do not use RSA padding.
MgfHashAlg MGF hash algorithm used for RSASSA-PSS padding. Applies only when the private key is RSA and PssPadding is true. Default is sha256. Can be sha256, sha384, or sha512.
LastErrorText Diagnostic text for the last method or property access. Check after failures or unexpected results. Diagnostic information may be available regardless of success or failure.

Subject Alternative Names

AddSan adds Subject Alternative Name values to the CSR. It can be called multiple times, once for each SAN entry.

SAN Type Typical Value Common Use
dnsName example.com DNS hostnames for TLS certificates.
IPAddress 69.12.122.63 IP addresses that should appear in the certificate SAN list.
rfc822Name person@example.com Email-address SAN entries.
uniformResourceIndicator https://example.com/app URI SAN entries.
registeredID Object identifier value Registered ID SAN entries.
otherName, x400Address, directoryName, ediPartyName Depends on SAN type Specialized SAN forms for uncommon certificate requirements.
Modern TLS guidance: For SSL/TLS certificates, DNS identities are typically placed in SAN entries using dnsName. The CommonName is still required by this class for CSR generation.

Generating CSR Output

Output Format Method Behavior
PEM string GenCsrPem Generates a CSR and returns it as PEM text. The supplied private key can be RSA or ECDSA.
Binary DER GenCsrBd Generates a CSR and writes the binary DER bytes to a supplied BinData object. The supplied private key can be RSA or ECDSA.
Private-key rule: The CSR is signed with the supplied private key. The generated CSR contains the corresponding public key.

Loading and Inspecting Existing CSRs

Need Method Behavior
Load CSR PEM LoadCsrPem Loads a CSR from a PEM string and sets this object’s properties to the values found in the CSR.
Get public key GetPublicKey Returns the CSR’s public key into a supplied PublicKey object.
Get Subject Alternative Names GetSans Writes the CSR’s SAN values to a supplied StringTable.
Get subject field by OID GetSubjectField Returns a subject field value by OID, such as 2.5.4.9.
Get extension request GetExtensionRequest Retrieves the 1.2.840.113549.1.9.14 extensionRequest as ASN.1 XML if one exists.
Verify CSR signature VerifyCsr Returns true if the CSR signature is valid.

Custom Subject Fields and Extension Requests

Task Method Important Details
Set a subject field by OID SetSubjectField Sets a subject field using an OID, value, and ASN.1 string type. The asnType can be UTF8String, IA5String, or PrintableString.
Get a subject field by OID GetSubjectField Reads a subject field value by OID.
Add an extension request SetExtensionRequest Adds a PKCS#9 extensionRequest to the CSR. The supplied Xml contains the ASN.1 in XML format.
Read an extension request GetExtensionRequest Gets the extensionRequest from a previously loaded CSR, if one exists.
ASN.1 string type guidance: For SetSubjectField, choose UTF8String when there is no special requirement for another ASN.1 string type.

Method Summary by Category

Category Methods Purpose
Generate CSR GenCsrPem, GenCsrBd Create a CSR from configured subject fields, SANs, extension requests, and an RSA or ECDSA private key.
Load CSR LoadCsrPem Load an existing CSR from PEM text and populate the object’s properties.
Subject fields SetSubjectField, GetSubjectField Set or retrieve subject DN fields by OID.
Subject Alternative Names AddSan, GetSans Add SAN entries before generation or retrieve SAN entries from a loaded CSR.
Extension request SetExtensionRequest, GetExtensionRequest Add or read the PKCS#9 extensionRequest attribute in ASN.1 XML form.
Public key and validation GetPublicKey, VerifyCsr Extract the CSR public key and verify the CSR signature.

Diagnostics and Troubleshooting

Problem Area Member What to Check
CSR generation fails CommonName, GenCsrPem, GenCsrBd, LastErrorText Confirm CommonName is set, the private key is valid, and required subject or extension data is well formed.
SANs are missing from the generated CSR AddSan Call AddSan once for each SAN before generating the CSR.
RSA-PSS signature settings do not appear to apply PssPadding, MgfHashAlg These settings apply only when the private key is RSA. They do not apply to ECDSA private keys.
CSR signature verification fails VerifyCsr The CSR may be malformed, altered, or not signed correctly with the private key corresponding to the CSR public key.
Extension request is not found GetExtensionRequest The loaded CSR may not contain a 1.2.840.113549.1.9.14 extensionRequest attribute.
Custom subject field is encoded incorrectly SetSubjectField Choose the appropriate ASN.1 string type. Use UTF8String when no special type is required.

Common Pitfalls

Pitfall Better Approach
Leaving CommonName empty. Set CommonName before generating the CSR. It is required by this class.
Assuming optional subject fields are required. Company, CompanyDivision, Country, State, Locality, and EmailAddress may be left empty.
Adding only a CN for a TLS certificate and forgetting SANs. Add DNS names with AddSan("dnsName", "...") when the CSR should request Subject Alternative Names.
Using the wrong SAN type spelling. Use a supported SAN type string such as dnsName, IPAddress, or rfc822Name.
Expecting RSA-PSS padding for ECDSA CSRs. PssPadding and MgfHashAlg are RSA-specific.
Trusting a loaded CSR without checking its signature. Use VerifyCsr to verify that the CSR signature is valid.

Best Practices

Recommendation Reason
Set CommonName explicitly. It is required for CSR generation and represents the CN field in the subject distinguished name.
Add SANs for TLS identities. SAN entries are the normal place to request DNS names, IP addresses, and other alternate identities.
Use SHA256 or stronger unless compatibility requires otherwise. HashAlgorithm defaults to SHA256 and can be set to stronger SHA-2 variants when required.
Use UTF8String for custom subject fields unless another type is required. It is the safest default when there is no special ASN.1 string type requirement.
Verify loaded CSRs before relying on them. VerifyCsr confirms that the CSR signature is valid.
Use DER output when binary CSR data is needed. GenCsrBd writes binary DER to BinData; GenCsrPem returns PEM text.
Check LastErrorText after failures. It provides the most useful diagnostic detail for generation, loading, subject-field, SAN, extension-request, and verification problems.

Summary

Chilkat.Csr is the Chilkat class for creating and inspecting Certificate Signing Requests. It supports common certificate subject fields, custom subject fields by OID, Subject Alternative Names, extension requests, RSA and ECDSA private keys, PEM and DER CSR output, CSR loading, public key extraction, SAN extraction, and CSR signature verification.

The most important practical guidance is to set CommonName, add SANs before generation when needed, choose an appropriate hash algorithm, use RSA-PSS options only with RSA private keys, and verify loaded CSRs before trusting their contents.