PublicKey SQL Server Reference Documentation
PublicKey
Current Version: 11.6.0
PublicKey
Import public keys from PEM, DER, XML, JWK, Base64 DER, RFC 4716 SSH2 blocks, raw ECDSA coordinates, or Ed25519 hex.
Convert public keys to DER, PEM, encoded DER, JWK, XML, or file-based
output for use by other systems and APIs.
Represent public keys for RSA, DSA, ECDSA, Ed25519, and related
public-key cryptographic workflows.
Pass public keys to Chilkat classes that verify signatures, JWTs, JWS
objects, signed data, or protocol-specific authentication messages.
Use public-key material for operations where the public half of a key
pair is required, such as encryption or verification.
Use
For an extended overview, see
PublicKey Class Overview.
Load, inspect, convert, export, and use public-key material.
PublicKey represents one public key at a time and provides loading, inspection, and format-conversion operations. It can load keys from many common formats,
including DER, PEM, XML, JWK, Base64 DER, RFC 4716 SSH2 blocks, raw ECDSA coordinates, and Ed25519 hex, then export them as DER, PEM, encoded DER, JWK, XML, or files. Public
keys are commonly used for signature verification, encryption, JWT/JWS
validation, SSH-related workflows, and interoperability with certificates,
private keys, and external cryptographic systems.
Load public keys
Export and convert
Work with key types
Verify signatures
Encrypt or validate data
Interoperate with certs and keys
Cert to obtain a public key from an X.509 certificate, or
use PrivateKey to obtain the public portion of an encrypted private key.
Cert, and load encrypted private keys with PrivateKey, then obtain the public key from those objects.
Object Creation
DECLARE @hr int
DECLARE @publicKey int
EXEC @hr = sp_OACreate 'Chilkat.PublicKey', @publicKey OUT
IF @hr <> 0
BEGIN
PRINT 'Failed to create ActiveX component'
RETURN
END
-- ... use @publicKey ...
EXEC @hr = sp_OADestroy @publicKeyT-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.PublicKey.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 @publicKey, '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
DebugLogFilePath
EXEC sp_OASetProperty @publicKey, '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.
Empty
Returns 10PublicKey object is empty.
A PublicKey object holds at most one key. Every successful load replaces the current key. Every failed load clears the object; a previously loaded key is never preserved after a load failure.
KeySize
Returns the key size in bits. The meaning is algorithm-specific:
| Key type | Reported size |
|---|---|
| RSA | The bit length of the RSA modulus, such as 2048. |
| DSA | The bit length of the prime parameter p. |
| EC | The size of the curve field, such as 256 for P-256. |
| Ed25519 | 256. |
| Empty object | 0. |
KeyType
Returns the type of public key currently held by this object.
| Value | Meaning |
|---|---|
empty | No public key is loaded. |
rsa | An RSA public key. |
dsa | A DSA public key. |
ecc | An elliptic-curve public key, commonly used with ECDSA or ECDH. |
ed25519 | An Ed25519 public key. |
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 @publicKey, '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.
topVerboseLogging
EXEC sp_OASetProperty @publicKey, '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
GetDerBd
Writes the public key as binary DER to bd. preferPkcs1 selects the representation using the same RSA, EC, DSA, and Ed25519 rules described for GetDer.
bd is replaced; data already present in the BinData is not appended to. If the method fails, including when this object is empty, bd is cleared.
GetDer when working with binary data in newer code.Returns 1 for success, 0 for failure.
GetEncoded
Returns the DER representation selected by preferPkcs1, encoded as text using the binary encoding named by encoding. The DER-selection rules are the same as for GetDer.
Common encoding value | Output encoding |
|---|---|
base64 | Standard Base64 with no line breaks. This is the most common choice for textual DER. |
base64Url | URL-safe Base64, useful when key bytes must appear in URLs or JSON-oriented protocols. |
hex | Uppercase hexadecimal. |
hexLower | Lowercase hexadecimal. |
Encoding names are case-insensitive. See the Chilkat Binary Encoding List for the complete set of supported encoding names. An empty or unsupported encoding name causes the method to fail. The method also fails if this object is empty.
Returns NULL on failure
GetJwk
Returns the public key as a compact JWK (JSON Web Key). Binary values use Base64url encoding without padding. Repeated calls for the same key produce the same compact member order.
RSA:
{"kty":"RSA","n":"BASE64URL_MODULUS","e":"BASE64URL_EXPONENT"}
EC:
{"kty":"EC","crv":"P-256","x":"BASE64URL_X","y":"BASE64URL_Y"}
Ed25519:
{"kty":"OKP","crv":"Ed25519","x":"BASE64URL_PUBLIC_KEY"}
Only public key parameters are emitted. Private members and optional JWK metadata are not included. The method fails if this object is empty or if the loaded key type cannot be represented as a supported JWK.
AQAB commonly represents exponent 65537, but the actual exponent from the loaded RSA key is exported.Returns NULL on failure
GetJwkThumbprint
Returns the RFC 7638 JWK thumbprint for this public key. Chilkat constructs the required canonical JSON object from the public JWK members, hashes its UTF-8 representation using the algorithm named by hashAlg, and returns the digest using Base64url encoding without padding.
Accepted algorithm names are md5, sha1, sha256, sha384, and sha512. Names are case-insensitive. An empty or unsupported algorithm name causes the method to fail. sha256 is the conventional choice for RFC 7638 thumbprints.
The method fails if this object is empty or if the key cannot be represented as a supported JWK.
Returns NULL on failure
GetPem
Returns the public key in PEM format. preferPkcs1 selects the underlying DER representation as follows:
| Key type | | |
|---|---|---|
| RSA | RSA PUBLIC KEY, containing PKCS #1 RSAPublicKey. | PUBLIC KEY, containing X.509 SubjectPublicKeyInfo. |
| EC | PUBLIC KEY with named-curve parameters. | PUBLIC KEY with explicit EC domain parameters. |
| Ed25519 | PUBLIC KEY. | The same PUBLIC KEY representation. |
PEM output uses CRLF line endings, Base64 body lines of at most 64 characters, and a final CRLF after the closing boundary line. The method fails if this object is empty.
preferPkcs1. The boundary label identifies the enclosed structure.Returns NULL on failure
GetXml
Returns the public key in Chilkat XML format. The exact representation depends on the key type.
RSA:
<RSAPublicKey><Modulus>BASE64_MODULUS</Modulus><Exponent>BASE64_EXPONENT</Exponent></RSAPublicKey>
DSA:
<DSAPublicKey> <P>BASE64_P</P> <Q>BASE64_Q</Q> <G>BASE64_G</G> <Y>BASE64_Y</Y> </DSAPublicKey>
EC:
<ECCPublicKey curve="secp256r1" x="UPPERCASE_HEX_X" y="UPPERCASE_HEX_Y">BASE64_DER</ECCPublicKey>
For EC keys, the curve attribute contains the Chilkat curve name, the x and y attributes contain full-width uppercase hexadecimal coordinates, and the element text contains a Base64-encoded DER public-key structure with explicit curve parameters.
Ed25519:
<Ed25519PublicKey>BASE64_32_BYTE_PUBLIC_KEY</Ed25519PublicKey>
The returned XML can be loaded by LoadFromString, LoadFromFile, or LoadBd. The method fails if this object is empty.
Returns NULL on failure
LoadBase64
Loads a public key from standard Base64-encoded DER in keyStr. Whitespace within the Base64 text is permitted. The decoded DER is inspected to determine the key type and structure. For RSA, both PKCS #1 RSAPublicKey and X.509 SubjectPublicKeyInfo are recognized.
A complete PEM string is also accepted, including its BEGIN/END boundary lines. Base64url text, arbitrary non-PEM text surrounding the encoded data, X.509 certificates, and encrypted private keys are not accepted.
A successful load replaces the current key. A failed load clears this object.
Cert object and obtain its public key from the certificate. Encrypted private-key input is also not supported by this class; load and decrypt it with a PrivateKey object, then obtain the corresponding public key.SubjectPublicKeyInfo. It is sometimes informally called a “PKCS #8 public key,” although PKCS #8 formally defines private-key syntax.Returns 1 for success, 0 for failure.
LoadBd
Loads a public key from the data in bd. The BinData may contain binary DER or any textual representation recognized by LoadFromString, including PEM, Chilkat XML, JWK, standard Base64 DER, and supported RFC 4716 SSH2 public-key blocks.
Public keys and unencrypted private keys are accepted; when private-key material is supplied, only the public portion is retained. For binary DER, the first recognized DER object is loaded and trailing bytes are ignored. Hex-encoded DER, Base64url-encoded DER, one-line OpenSSH public keys, X.509 certificates, and encrypted private keys are not recognized.
JWK required-member and metadata behavior is the same as described for LoadFromString. A successful load replaces the current key. A failed load clears this object.
Cert object and obtain its public key from the certificate. Encrypted private-key input is also not supported by this class; load and decrypt it with a PrivateKey object, then obtain the corresponding public key.Returns 1 for success, 0 for failure.
LoadEcdsa
Loads an elliptic-curve public key directly from its affine point coordinates. curveName names the curve, Qx is the hexadecimal x-coordinate (Qx), and Qy is the hexadecimal y-coordinate (Qy).
The coordinate strings must contain exactly the full field width for the selected curve. Uppercase and lowercase hexadecimal are accepted. A 0x prefix, whitespace, separators, extra leading zero bytes, shortened coordinates, non-hexadecimal characters, empty values, and all-zero coordinates are rejected. Curve names are case-insensitive.
| Supported curve | Description and aliases |
|---|---|
secp256r1 | NIST P-256; also known as P-256 and prime256v1. |
secp384r1 | NIST P-384; also known as P-384. |
secp521r1 | NIST P-521; also known as P-521. |
secp256k1 | The 256-bit Koblitz curve used by Bitcoin. |
secp192r1 | 192-bit SEC/NIST curve. |
secp224r1 | 224-bit SEC/NIST curve. |
brainpoolP160r1 | 160-bit Brainpool curve. |
brainpoolP192r1 | 192-bit Brainpool curve. |
brainpoolP224r1 | 224-bit Brainpool curve. |
brainpoolP256r1 | 256-bit Brainpool curve. |
brainpoolP320r1 | 320-bit Brainpool curve. |
brainpoolP384r1 | 384-bit Brainpool curve. |
brainpoolP512r1 | 512-bit Brainpool curve. |
A successful load replaces the current key. A failed load clears this object. The method validates syntax, coordinate width, and obvious zero values, but it does not fully verify that the supplied coordinates form a point on the named curve.
LoadBd, LoadFromString, or LoadFromFile.Returns 1 for success, 0 for failure.
LoadEd25519
Loads a raw Ed25519 public key from the hexadecimal string in pubKey. pubKey must contain exactly 64 hexadecimal characters representing 32 bytes. Uppercase and lowercase hexadecimal are accepted.
A 0x prefix, whitespace, separators, non-hexadecimal characters, odd-length input, and values shorter or longer than 32 bytes are rejected. A successful load replaces the current key; a failed load clears this object.
This method validates the hexadecimal syntax and exact byte count. It does not determine whether every 32-byte value is a usable Ed25519 public point; for example, an all-zero 32-byte value is accepted.
Returns 1 for success, 0 for failure.
LoadFromFile
Loads a public key from the local filesystem path specified by path. Chilkat examines the file contents rather than the filename extension. Supported content includes binary DER, PEM, Chilkat XML, JWK, standard Base64 DER, and RFC 4716 SSH2 public-key blocks for supported RSA and Ed25519 keys.
Public keys and unencrypted private keys are accepted. When private-key material is supplied, only the public portion is retained. Hex-encoded DER, Base64url-encoded DER, one-line OpenSSH public keys, X.509 certificates, and encrypted private keys are not recognized.
For PEM files, UTF-8 BOMs, CRLF or LF line endings, surrounding text, and unrelated PEM blocks are tolerated. If multiple recognized key blocks are present, the first recognized key is loaded. For binary DER, the first recognized DER object is loaded and trailing bytes are ignored.
JWK required-member and metadata behavior is the same as described for LoadFromString. A successful load replaces the current key. A failed load clears this object.
Cert object and obtain its public key from the certificate. Encrypted private-key input is also not supported by this class; load and decrypt it with a PrivateKey object, then obtain the corresponding public key.Returns 1 for success, 0 for failure.
LoadFromString
Loads a public key from the string in keyString. Chilkat examines the content and recognizes these textual representations:
- PEM public keys.
- Unencrypted PEM private keys, from which only the public portion is retained.
- Chilkat XML public or private keys.
- Public or private JWK.
- Standard Base64-encoded DER.
- RFC 4716 SSH2 public-key blocks for supported RSA and Ed25519 keys.
Hex-encoded DER, Base64url-encoded DER, one-line OpenSSH forms such as ssh-rsa ... and ssh-ed25519 ..., X.509 certificates, and encrypted private keys are not recognized.
For PEM input, UTF-8 BOMs, CRLF or LF line endings, leading and trailing whitespace, unrelated surrounding text, and unrelated PEM blocks are tolerated. If multiple recognized key blocks are present, the first recognized key is loaded.
For JWK input, required public members must be present. Private members such as d may be present but are discarded. Optional metadata such as kid, use, alg, key_ops, and x5c is not retained.
| Key type | Required public members |
|---|---|
| RSA | kty, n, and a nonzero e. |
| EC | kty, crv, x, and y. |
| Ed25519 | kty, crv, and x. |
A successful load replaces the current key. A failed load clears this object.
Cert object and obtain its public key from the certificate. Encrypted private-key input is also not supported by this class; load and decrypt it with a PrivateKey object, then obtain the corresponding public key.Returns 1 for success, 0 for failure.
SaveDerFile
Saves the public key to path as binary DER. preferPkcs1 selects the representation using the same RSA, EC, and Ed25519 rules described for GetDer.
An existing destination file is overwritten. Parent directories are not created automatically. The method fails if path names a directory. If this object is empty, the method fails without creating the file.
Returns 1 for success, 0 for failure.
SavePemFile
Saves the public key to path in PEM format. preferPkcs1 selects the representation and PEM label using the same rules described for GetPem.
The generated file uses CRLF line endings, Base64 body lines of at most 64 characters, and a final CRLF. An existing destination file is overwritten. If this object is empty, the method fails without creating the file.
Returns 1 for success, 0 for failure.
SaveXmlFile
Saves the public key to the local filesystem path specified by path using exactly the same key-type-specific XML text returned by GetXml. No additional BOM or line ending is added.
An existing destination file is overwritten. If this object is empty, the method fails without creating the destination file.
Returns 1 for success, 0 for failure.