Csr SQL Server Reference Documentation
Csr
Current Version: 11.6.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
Object Creation
DECLARE @hr int
DECLARE @csr int
EXEC @hr = sp_OACreate 'Chilkat.Csr', @csr OUT
IF @hr <> 0
BEGIN
PRINT 'Failed to create ActiveX component'
RETURN
END
-- ... use @csr ...
EXEC @hr = sp_OADestroy @csrT-SQL uses the Chilkat ActiveX through the OLE Automation stored procedures. They must be enabled once on the server (EXEC sp_configure 'Ole Automation Procedures', 1; RECONFIGURE;), and the Chilkat ActiveX registered must match the bitness of the SQL Server instance (64-bit for a 64-bit SQL Server). To bind to a specific major version of Chilkat, append the major version number to the ProgID, such as sp_OACreate 'Chilkat.Csr.11' for Chilkat v11.*.*.
sp_OACreate returns an object token (an int) that is passed as the first argument of every sp_OAMethod, sp_OAGetProperty and sp_OASetProperty call, and released with sp_OADestroy. Objects returned by methods (such as an HttpResponse or JsonObject) are also tokens received through an int OUT parameter; they must likewise be destroyed, and the OUT parameter is NULL when the method fails to return an object. Objects passed as arguments are passed by their token. When an OLE Automation procedure itself fails (non-zero @hr), sp_OAGetErrorInfo describes the error.
Data types: strings are nvarchar(4000); integers, booleans (1 or 0) and object tokens are int; dates are datetime. In the signatures on this page, @success, @iResult, @sResult and the like are the OUT variables receiving a method's return value, @iValue / @sValue receive or supply a property value, and the remaining @ variables are the method's arguments in order.
A string returned through an OUT parameter is limited to 4000 characters. For longer values, retrieve the result as a result set into a table variable instead of an OUT parameter, for example DECLARE @tmp TABLE (outputLine ntext) followed by INSERT INTO @tmp EXEC sp_OAGetProperty @csr, 'LastErrorText'. See string length limitations for strings returned by sp_OAMethod calls.
Methods that pass or return raw byte arrays are not shown on this page, because varbinary(max) values cannot be exchanged through sp_OAMethod (see varbinary(max) limitation). Use the BinData-based alternatives (methods ending in Bd) or the base64 / hex string-encoded variants instead. Binary properties (such as LastBinaryResult) can be retrieved as a result set into a table variable, as shown in their signatures. Asynchronous (*Async) methods and event callbacks are not available from SQL Server.
Properties
CommonName
EXEC sp_OASetProperty @csr, 'CommonName', @sValue
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
EXEC sp_OASetProperty @csr, 'Company', @sValue
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
EXEC sp_OASetProperty @csr, 'CompanyDivision', @sValue
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
EXEC sp_OASetProperty @csr, 'Country', @sValue
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
EXEC sp_OASetProperty @csr, 'DebugLogFilePath', @sValue
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
EXEC sp_OASetProperty @csr, 'EmailAddress', @sValue
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
EXEC sp_OASetProperty @csr, 'HashAlgorithm', @sValue
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.LastBinaryResult
This property is mainly used in SQL Server stored procedures to retrieve binary data from the last method call that returned binary data. It is only accessible if Chilkat.Global.KeepBinaryResult is set to 1. This feature allows for the retrieval of large varbinary results in an SQL Server environment, which has restrictions on returning large data via method calls, though temp tables can handle binary properties.
LastErrorHtml
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
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
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
EXEC sp_OASetProperty @csr, 'LastMethodSuccess', @iValue
Indicates the success or failure of the most recent method call: 1 means success, 0 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.
LastStringResult
In SQL Server stored procedures, this property holds the string return value of the most recent method call that returns a string. It is accessible only when Chilkat.Global.KeepStringResult is set to TRUE. SQL Server has limitations on string lengths returned from methods and properties, but temp tables can be used to access large strings.
LastStringResultLen
The length, in characters, of the string contained in the LastStringResult property.
topLocality
EXEC sp_OASetProperty @csr, 'Locality', @sValue
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
EXEC sp_OASetProperty @csr, 'MgfHashAlg', @sValue
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 1.
Supported values are sha256, sha384, and sha512. The default is sha256.
HashAlgorithm unless the receiving profile explicitly specifies different RSASSA-PSS parameters.PssPadding
EXEC sp_OASetProperty @csr, 'PssPadding', @iValue
Controls the RSA signature scheme used when generating a CSR with an RSA private key. When 1, Chilkat signs using RSASSA-PSS. When 0, 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
EXEC sp_OASetProperty @csr, 'State', @sValue
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
EXEC sp_OASetProperty @csr, 'VerboseLogging', @iValue
If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
Version
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 1 for success, 0 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 1 for success, 0 for failure.
GenCsrPem
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 NULL on 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 1 for success, 0 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 1 for success, 0 for failure.
topGetSans
Retrieves the Subject Alternative Names requested by the currently loaded CSR and writes them to the supplied StringTable.
Returns 1 for success, 0 for failure.
topGetSubjectField
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 NULL on 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 1 for success, 0 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 1 for success, 0 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 1 for success, 0 for failure.
topVerifyCsr
Verifies the digital signature on the currently loaded CSR using the public key embedded in that request. Returns 1 when the signature is cryptographically valid; otherwise returns 0.
Returns 1 for success, 0 for failure.
top