Csr Lua Reference Documentation
chilkat.Csr
Current Version: 11.7.0
Markdown version of this page for AI tools (v 11.7.0) · all AI docs
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
Object Creation
local chilkat = require("chilkat")
local csr = chilkat.Csr.new()Creates the object (chilkat.Csr() does the same). Lua's garbage collector frees it when it is no longer referenced; csr:dispose() frees it at once, and in Lua 5.4 and later local csr <close> = chilkat.Csr.new() frees it when the block ends. Calling a method of a disposed object raises an error.
Errors
A method that fails returns nil followed by the error text, as io.open does: local body, err = csr:method(...), where err is the object's last_error_text. Wrap the call in assert() to raise an error with that text instead. Methods that answer a question return true or false, numbers are returned as they are (check last_method_success where the description says a value means failure), and property reads and writes never fail for Chilkat reasons.
Misuse raises a Lua error: a wrong argument type or a missing argument (bad argument #1 to ...), an unknown property name, a write to a read-only property, an out-of-range integer, or an object of the wrong class.
Names are Chilkat's in snake_case: QuickGetStr is quick_get_str, LastErrorText is last_error_text. Properties are fields (csr.verbose_logging = true) and methods use the colon (csr:method(...)). Strings are UTF-8; binary data is a Lua string of bytes. Indexes are 0-based, as in every Chilkat API. Unlocking: call chilkat.unlock_bundle("...") once at startup.
Properties
CommonName
local strVal = csr.common_name
csr.common_name = strVal
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
local strVal = csr.company
csr.company = strVal
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
local strVal = csr.company_division
csr.company_division = strVal
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
local strVal = csr.country
csr.country = strVal
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
local strVal = csr.debug_log_file_path
csr.debug_log_file_path = strVal
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
local strVal = csr.email_address
csr.email_address = strVal
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
local strVal = csr.hash_algorithm
csr.hash_algorithm = strVal
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
local strVal = csr.last_error_html
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
local strVal = csr.last_error_text
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
local strVal = csr.last_error_xml
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
local boolVal = csr.last_method_success
csr.last_method_success = boolVal
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
local strVal = csr.locality
csr.locality = strVal
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
local strVal = csr.mgf_hash_alg
csr.mgf_hash_alg = strVal
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
local boolVal = csr.pss_padding
csr.pss_padding = boolVal
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
local strVal = csr.state
csr.state = strVal
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
local boolVal = csr.verbose_logging
csr.verbose_logging = boolVal
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
local strVal = csr.version
Methods
AddSan
-- san_value is a string
-- ok is true, or nil and err on failure
local ok, err = csr:add_san(san_type, san_value)
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 on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
GenCsrBd
-- csr_data is a chilkat.BinData
-- ok is true, or nil and err on failure
local ok, err = csr:gen_csr_bd(priv_key, csr_data)
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 on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
GenCsrPem
-- str is a string, or nil and err on failure
local str, err = csr:gen_csr_pem(priv_key)
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 the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
GetExtensionRequest
-- ok is true, or nil and err on failure
local ok, err = csr:get_extension_request(extension_req_xml)
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 on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
GetPublicKey
-- ok is true, or nil and err on failure
local ok, err = csr:get_public_key(pubkey)
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 on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
GetSans
-- ok is true, or nil and err on failure
local ok, err = csr:get_sans(sans)
Retrieves the Subject Alternative Names requested by the currently loaded CSR and writes them to the supplied StringTable.
Returns true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
GetSubjectField
-- str is a string, or nil and err on failure
local str, err = csr:get_subject_field(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 the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
LoadCsrPem
-- ok is true, or nil and err on failure
local ok, err = csr:load_csr_pem(csr_pem_str)
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 on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
SetExtensionRequest
-- ok is true, or nil and err on failure
local ok, err = csr:set_extension_request(extension_req_xml)
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 on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
SetSubjectField
-- value is a string
-- asn_type is a string
-- ok is true, or nil and err on failure
local ok, err = csr:set_subject_field(oid, value, asn_type)
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 on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
VerifyCsr
local ok, err = csr:verify_csr()
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 on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.