Csr Unicode C Reference Documentation
Csr
Current Version: 11.5.0
Chilkat.Csr
Generate certificate signing requests using RSA or ECDSA private keys
and the subject fields required by the certificate authority.
Set common X.509 subject fields such as common name, organization,
organizational unit, locality, state, country, and email address.
Add custom subject attributes by object identifier when a certificate
authority or application profile requires nonstandard fields.
Include DNS names, IP addresses, email addresses, URIs, or other SAN
entries needed for modern TLS and identity certificates.
Request certificate extensions that the issuing CA may include in the
final certificate.
Load an existing CSR, extract its public key, inspect requested names and
fields, and verify that the CSR signature is valid.
For an extended overview, see
Csr Class Overview.
Create, load, inspect, and verify Certificate Signing Requests.
Chilkat.Csr is the Chilkat class for working with Certificate
Signing Requests. It can create CSRs from RSA or ECDSA private keys, set
common certificate subject fields, add custom subject fields by OID, include
Subject Alternative Names, request certificate extensions, export CSRs in
PEM or DER format, load existing CSRs, extract the public key, inspect SAN
values, and verify the CSR signature.
Create CSRs
Subject fields
Custom OID fields
Subject Alternative Names
Extension requests
Inspect and verify
Create/Dispose
HCkCsrW instance = CkCsrW_Create(); // ... CkCsrW_Dispose(instance);
Creates an instance of the HCkCsrW object and returns a handle ("void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.
Objects created by calling CkCsrW_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function. Also, any handle returned by a Chilkat "C" function must also be freed by the application by calling the appropriate Dispose method, such as CkCsrW_Dispose.
Properties
CommonName
void CkCsrW_putCommonName(HCkCsrW cHandle, const wchar_t *newVal);
const wchar_t *CkCsrW_commonName(HCkCsrW cHandle);
Gets or sets the subject common name (CN), OID 2.5.4.3, for the CSR. For a TLS server request this has traditionally been a DNS hostname; for other certificate profiles it may identify a person, device, service, or organization.
Chilkat requires this property when generating a CSR. The exact value and validation rules are determined by the certificate authority and certificate profile.
AddSan. Current TLS identity verification uses Subject Alternative Name entries, and the common name is retained primarily for compatibility and display.Company
void CkCsrW_putCompany(HCkCsrW cHandle, const wchar_t *newVal);
const wchar_t *CkCsrW_company(HCkCsrW cHandle);
Gets or sets the subject organization name (O), OID 2.5.4.10. For organization-validated certificate profiles, this is typically the legal or verified organization name.
This property is optional at the PKCS #10 level, but a certificate authority may require it or replace it with a value established during identity validation.
topCompanyDivision
void CkCsrW_putCompanyDivision(HCkCsrW cHandle, const wchar_t *newVal);
const wchar_t *CkCsrW_companyDivision(HCkCsrW cHandle);
Gets or sets the subject organizational unit name (OU), OID 2.5.4.11. It may identify a department, division, team, or other unit within the organization.
This property is optional. Some public certificate profiles restrict or omit organizational-unit values, so follow the requirements of the receiving CA.
topCountry
void CkCsrW_putCountry(HCkCsrW cHandle, const wchar_t *newVal);
const wchar_t *CkCsrW_country(HCkCsrW cHandle);
Gets or sets the subject country name (C), OID 2.5.4.6. The value is normally a two-letter uppercase ISO 3166-1 country code, such as US, CA, or DE.
This property is optional unless required by the certificate authority's enrollment profile.
PrintableString. Do not place a full country name such as United States in this field.DebugLogFilePath
void CkCsrW_putDebugLogFilePath(HCkCsrW cHandle, const wchar_t *newVal);
const wchar_t *CkCsrW_debugLogFilePath(HCkCsrW cHandle);
If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.
Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.
Possible causes of hangs include:
- A timeout property set to 0, indicating an infinite timeout.
- A hang occurring within an event callback in the application code.
- An internal bug in the Chilkat code causing the hang.
EmailAddress
void CkCsrW_putEmailAddress(HCkCsrW cHandle, const wchar_t *newVal);
const wchar_t *CkCsrW_emailAddress(HCkCsrW cHandle);
Gets or sets the legacy PKCS #9 emailAddress subject attribute, OID 1.2.840.113549.1.9.1. This property is optional.
emailAddress attribute is permitted for legacy compatibility but is deprecated in the Internet X.509 profile. When the certificate must identify an email address, also use AddSan with rfc822Name, as required by the target certificate profile.HashAlgorithm
void CkCsrW_putHashAlgorithm(HCkCsrW cHandle, const wchar_t *newVal);
const wchar_t *CkCsrW_hashAlgorithm(HCkCsrW cHandle);
Gets or sets the message-digest algorithm used when signing a generated CSR. Supported values are sha1, sha256, sha384, and sha512. The default is sha256.
This property selects the digest for the CSR's proof-of-possession signature. It does not select the signature algorithm that the certificate authority will use on the issued certificate.
sha256 or stronger unless a legacy enrollment system explicitly requires SHA-1. The digest must also be compatible with the supplied key type and the receiving CA.LastErrorHtml
const wchar_t *CkCsrW_lastErrorHtml(HCkCsrW cHandle);
Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastErrorText
const wchar_t *CkCsrW_lastErrorText(HCkCsrW cHandle);
Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
LastErrorXml
const wchar_t *CkCsrW_lastErrorXml(HCkCsrW cHandle);
Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastMethodSuccess
void CkCsrW_putLastMethodSuccess(HCkCsrW cHandle, BOOL newVal);
Indicates the success or failure of the most recent method call: TRUE means success, FALSE means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.
Locality
void CkCsrW_putLocality(HCkCsrW cHandle, const wchar_t *newVal);
const wchar_t *CkCsrW_locality(HCkCsrW cHandle);
Gets or sets the subject locality name (L), OID 2.5.4.7. This usually identifies a city, town, or other local jurisdiction.
This property is optional unless required by the certificate authority's enrollment profile.
topMgfHashAlg
void CkCsrW_putMgfHashAlg(HCkCsrW cHandle, const wchar_t *newVal);
const wchar_t *CkCsrW_mgfHashAlg(HCkCsrW cHandle);
Gets or sets the hash algorithm used by MGF1 in an RSASSA-PSS CSR signature. This property applies only when the private key is RSA and PssPadding is TRUE.
Supported values are sha256, sha384, and sha512. The default is sha256.
HashAlgorithm unless the receiving profile explicitly specifies different RSASSA-PSS parameters.PssPadding
void CkCsrW_putPssPadding(HCkCsrW cHandle, BOOL newVal);
Controls the RSA signature scheme used when generating a CSR with an RSA private key. When TRUE, Chilkat signs using RSASSA-PSS. When FALSE, the RSA signature uses the traditional RSASSA-PKCS1-v1_5 scheme. This property has no effect for elliptic-curve keys.
HashAlgorithm selects the digest of the certification-request information. When PSS is enabled, MgfHashAlg selects the digest used by MGF1.State
void CkCsrW_putState(HCkCsrW cHandle, const wchar_t *newVal);
const wchar_t *CkCsrW_state(HCkCsrW cHandle);
Gets or sets the subject state or province name (ST, sometimes displayed as S), OID 2.5.4.8.
This property is optional unless required by the certificate authority. Use the full jurisdiction name expected by the CA, such as Illinois, rather than assuming an abbreviation is accepted.
VerboseLogging
void CkCsrW_putVerboseLogging(HCkCsrW cHandle, BOOL newVal);
If set to TRUE, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is FALSE. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
Version
const wchar_t *CkCsrW_version(HCkCsrW cHandle);
Methods
AddSan
Adds one Subject Alternative Name to the CSR that will be generated. Call this method once for each name to request. The SAN values are carried as requested certificate extensions; the issuing certificate authority decides whether to validate and include them in the final certificate.
sanType | Meaning and example |
|---|---|
dnsName | A DNS hostname, such as www.example.com or an allowed wildcard such as *.example.com. |
IPAddress | An IPv4 or IPv6 address, such as 192.0.2.10 or 2001:db8::10. |
rfc822Name | An Internet email address, such as user@example.com. |
uniformResourceIndicator | A URI. This is Chilkat's accepted keyword; the X.509 GeneralName field is formally named uniformResourceIdentifier. |
directoryName | An X.500 distinguished name. |
registeredID | A registered object identifier. |
otherName, x400Address, ediPartyName | Less common X.509 GeneralName forms used by specialized profiles. |
dNSName and iPAddress SAN entries rather than relying on the subject common name.Returns TRUE for success, FALSE for failure.
topGenCsrBd
Generates a PKCS #10 Certificate Signing Request using the supplied RSA or elliptic-curve private key and writes the binary DER representation to csrData.
The generated request uses the subject fields, Subject Alternative Names, extension request, and signature settings currently configured on this object. The DER bytes are the same request data that would appear as the Base64 body returned by GenCsrPem.
Returns TRUE for success, FALSE for failure.
GenCsrPem
const wchar_t *CkCsrW_genCsrPem(HCkCsrW cHandle, HCkPrivateKeyW privKey);
Generates a PKCS #10 Certificate Signing Request using the supplied PrivateKey and the subject fields, Subject Alternative Names, extension request, and signature settings currently configured on this object. The private key may be RSA or elliptic-curve (ECDSA).
On success, returns the CSR in PEM form, normally enclosed by -----BEGIN CERTIFICATE REQUEST----- and -----END CERTIFICATE REQUEST----- lines. The Base64 body is the DER-encoded PKCS #10 request.
privKey, optional attributes such as requested extensions, and a signature made with the corresponding private key. The private key itself is never included.HashAlgorithm selects the digest. For RSA keys, PssPadding and MgfHashAlg control whether RSASSA-PSS is used and which MGF1 digest is encoded in its parameters.Returns TRUE for success, FALSE for failure.
GetExtensionRequest
Retrieves the PKCS #9 extensionRequest attribute, OID 1.2.840.113549.1.9.14, from the currently loaded CSR. When present, the requested extensions are loaded into extensionReqXml as Chilkat ASN.1 XML.
Returns TRUE for success, FALSE for failure.
GetPublicKey
Copies the public key contained in the currently loaded CSR into pubkey. The resulting PublicKey object is independent of the CSR and contains no private-key material.
VerifyCsr to check that relationship; merely extracting the public key does not verify the CSR signature.Returns TRUE for success, FALSE for failure.
topGetSans
Retrieves the Subject Alternative Names requested by the currently loaded CSR and writes them to the supplied StringTable.
Returns TRUE for success, FALSE for failure.
topGetSubjectField
const wchar_t *CkCsrW_getSubjectField(HCkCsrW cHandle, const wchar_t *oid);
Returns the value of a subject distinguished-name attribute from the currently loaded or configured CSR, identified by its object identifier. For example, OID 2.5.4.9 identifies streetAddress.
CN, O, OU, and C, are labels for specific OIDs. This method uses the numeric OID so uncommon or application-specific attributes can also be retrieved.Returns TRUE for success, FALSE for failure.
LoadCsrPem
Loads a PEM-encoded PKCS #10 Certificate Signing Request. On success, the subject properties and retrieval methods on this object reflect the values contained in the loaded request, including its public key, Subject Alternative Names, and extension-request attribute when present.
VerifyCsr to verify that the request was signed by the private key corresponding to the public key carried in the CSR.Returns TRUE for success, FALSE for failure.
SetExtensionRequest
Sets the PKCS #9 extensionRequest attribute, OID 1.2.840.113549.1.9.14, for the CSR to be generated. extensionReqXml supplies the requested X.509 extensions as ASN.1 represented in Chilkat XML form.
Returns TRUE for success, FALSE for failure.
SetSubjectField
Sets a subject distinguished-name attribute identified by oid. For example, OID 2.5.4.9 identifies streetAddress. Use the dedicated properties such as CommonName, Company, and Country for the commonly used subject attributes.
asnType specifies the ASN.1 string type used to encode the value and may be UTF8String, IA5String, or PrintableString. Use UTF8String unless the attribute definition or certificate-authority profile requires another type.
| ASN.1 type | Typical use |
|---|---|
UTF8String | General Unicode text and the preferred default for most modern directory attributes. |
IA5String | ASCII-based attributes whose schema specifically requires IA5String, such as the legacy PKCS #9 emailAddress attribute. |
PrintableString | Attributes constrained to the limited PrintableString character set, such as the X.520 country name. |
Returns TRUE for success, FALSE for failure.
topVerifyCsr
Verifies the digital signature on the currently loaded CSR using the public key embedded in that request. Returns TRUE when the signature is cryptographically valid; otherwise returns FALSE.
Returns TRUE for success, FALSE for failure.
top