Dsa Chilkat2 Perl Reference Documentation
Chilkat2::Dsa
Current Version: 11.7.0
Markdown version of this page for AI tools (v 11.7.0) · all AI docs
Chilkat.Dsa
Create DSA key pairs and parameters for workflows that still require
DSA-based signing or verification.
Load and save private or public DSA keys in DER, PEM, encrypted PEM,
XML, component-based, and OpenSSL-compatible formats.
Create DSA signatures over message digests using a loaded private key
and the appropriate encoded hash input.
Verify DSA signatures using a public key, encoded hash, and signature
data.
Access DSA parameters and key components as hex-encoded SSH1-format
bignums for low-level interoperability scenarios.
Work with encoded hashes and signatures when applications need hex,
Base64, or other textual representations of binary values.
For an extended overview, see
Dsa Class Overview.
Generate, import, export, sign, and verify DSA keys and signatures.
Chilkat.Dsa is the Chilkat class for DSA key generation,
DSA key import/export, DSA hash signing, and DSA signature verification.
It supports private and public keys in DER, PEM, encrypted PEM, XML,
explicit component, and OpenSSL parameter workflows. It also exposes DSA key
components as hex-encoded SSH1-format bignums and provides helpers for
working with encoded hashes and signatures.
Generate DSA keys
Import and export keys
Sign hashes
Verify signatures
Key components
Encoded data helpers
Dsa to sign the hash with the private key or
verify the signature with the public key. For new protocol designs, consider
whether a more modern signature algorithm is preferred; use this class when
DSA is required for compatibility.
Object Creation
use Chilkat2;
my $dsa = Chilkat2::Dsa->new;
# or set properties (and RaiseError) at creation:
# my $dsa = Chilkat2::Dsa->new(VerboseLogging => 1, RaiseError => 1);Creates the object. The optional pairs set writable properties (and RaiseError) in order, as if set one by one; an unknown or read-only name croaks. use Chilkat2; loads every class; the Chilkat2/Dsa.pm file holds only this class's documentation (perldoc Chilkat2::Dsa).
Perl frees the object when its last reference goes (undef $dsa, or the variable going out of scope); there is nothing to close. Objects returned by methods are independent and freed the same way. The class may be subclassed (use parent -norequire, 'Chilkat2::Dsa';): an object is a blessed hash reference whose hash is free for the subclass's own fields.
When false (the default), a method that fails returns false (or undef), and the reason is in LastErrorText. When true, it dies with a Chilkat2::Error instead, as DBI does with its RaiseError. Objects returned by a method inherit the value of the object that returned them.
Errors
A Chilkat2::Error stringifies to the failed call's full LastErrorText, and has the methods text, class ('Chilkat2::Dsa'), method (the method name) and object. Methods that look something up and find nothing return undef without dying (each such method says so), methods that answer a question (HasMember, IsUnlocked, ...) return a plain boolean, and property reads and writes never fail for Chilkat reasons.
Misuse always croaks, with your file and line, whatever RaiseError is: a wrong number of arguments, a reference or undef where a string or number is expected, an object of the wrong class, an out-of-range integer, a string containing a NUL character, a wide character in a byte string, or a write to a read-only property.
Strings are Perl character strings in both directions (length, regexes and :encoding layers see characters); binary data (BinData) is a byte string. Unlocking: call Chilkat2::Global->new->UnlockBundle('...') once at startup.
Properties
DebugLogFilePath
my $strVal = $dsa->DebugLogFilePath;
$dsa->DebugLogFilePath($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.
GroupSize
my $intVal = $dsa->GroupSize;
$dsa->GroupSize($intVal);
Specifies the size, in bits, of the DSA subgroup parameter Q used by the legacy GenKey method. The default is 160. This also determines the natural size of the DSA signature components r and s.
Applications should normally leave this property at its default. When an explicit standards-era (L, N) parameter pair is required, use GenKey2, where L is the bit length of P and N is the bit length of Q.
HexG
my $strVal = $dsa->HexG;
Returns the DSA domain parameter G, the generator of the subgroup of order Q modulo P.
The returned text is a hexadecimal encoding of Chilkat's SSH1-format bignum representation, which includes a two-byte bit-length prefix followed by the unsigned integer bytes.
topHexP
my $strVal = $dsa->HexP;
Returns the DSA domain parameter P, the large prime modulus.
The returned text is a hexadecimal encoding of Chilkat's SSH1-format bignum representation, which includes a two-byte bit-length prefix followed by the unsigned integer bytes.
topHexQ
my $strVal = $dsa->HexQ;
Returns the DSA domain parameter Q, a prime divisor of P - 1. The bit length of Q is commonly written as N and determines the range of the private value X and signature components r and s.
The returned text is a hexadecimal encoding of Chilkat's SSH1-format bignum representation, which includes a two-byte bit-length prefix followed by the unsigned integer bytes.
topHexX
my $strVal = $dsa->HexX;
Returns the DSA private value X. It is present only when the object contains a private key and satisfies 0 < X < Q.
The returned text is a hexadecimal encoding of Chilkat's SSH1-format bignum representation, which includes a two-byte bit-length prefix followed by the unsigned integer bytes.
X can create signatures as the key owner. Do not log, transmit, or persist this value unless it is protected as private-key material.HexY
my $strVal = $dsa->HexY;
Returns the DSA public value Y, where Y = GX mod P. It is available when either a public or private DSA key is loaded.
The returned text is a hexadecimal encoding of Chilkat's SSH1-format bignum representation, which includes a two-byte bit-length prefix followed by the unsigned integer bytes.
topLastErrorHtml
my $strVal = $dsa->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
my $strVal = $dsa->LastErrorText;
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
my $strVal = $dsa->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
my $boolVal = $dsa->LastMethodSuccess;
$dsa->LastMethodSuccess($boolVal);
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.
UncommonOptions
my $strVal = $dsa->UncommonOptions;
$dsa->UncommonOptions($strVal);
Reserved for uncommon or compatibility-specific options. The default is the empty string, and applications should normally leave this property unchanged unless Chilkat documentation or support identifies a specific keyword required for the target system.
topVerboseLogging
my $boolVal = $dsa->VerboseLogging;
$dsa->VerboseLogging($boolVal);
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
my $strVal = $dsa->Version;
Methods
FromDerBd
Loads a DSA private key from the DER bytes contained in the BinData object passed in $bd1 on successful decoding.
BinData content contains secret key material and should be cleared or released when no longer needed.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FromDerFile
# $success is true or false
my $success = $dsa->FromDerFile($path);
Loads a DSA private key from the DER-encoded file specified by $path1 when the file is read and decoded successfully; otherwise returns 0.
LastErrorText when loading fails.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FromEncryptedPem
# $pemData is a string
# $success is true or false
my $success = $dsa->FromEncryptedPem($password, $pemData);
Loads a DSA private key from the PEM text in $pemData$password
Returns 1 on success and 0 if the PEM cannot be decoded, the password is incorrect, or the contained key is not a supported DSA private key.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FromPem
# $success is true or false
my $success = $dsa->FromPem($pemData);
Loads an unencrypted DSA private key from the PEM text in $pemData
FromEncryptedPem when password-protected PEM is available.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FromPublicDerBd
Loads a DSA public key from the DER bytes contained in the BinData object passed in $bd
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FromPublicDerFile
# $success is true or false
my $success = $dsa->FromPublicDerFile($path);
Loads a DSA public key from the DER-encoded file specified by $path1 when the file is read and decoded successfully; otherwise returns 0.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FromPublicPem
# $success is true or false
my $success = $dsa->FromPublicPem($pemData);
Loads a DSA public key from the PEM text in $pemData1 when the PEM contains a supported DSA public key and is decoded successfully.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FromXml
# $success is true or false
my $success = $dsa->FromXml($xmlKey);
Loads a DSA public or private key from the XML text in $xmlKeyX.
X, it contains the complete private key and must be protected accordingly.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GenKey
# $success is true or false
my $success = $dsa->GenKey($numBits);
Generates a new DSA key pair with a P size of $numBits$numBitsGroupSize, whose default is 160 bits.
For explicit standard parameter pairs such as (2048, 224) or (3072, 256), use GenKey2.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GenKey2
# $modLenBits is an integer
# $success is true or false
my $success = $dsa->GenKey2($keyLenBits, $modLenBits);
Generates a new DSA key pair using an explicit (L, N) parameter-size combination. $keyLenBitsL, the bit length of the prime modulus P. $modLenBitsN, the bit length of the subgroup prime Q.
| L | N | Historical FIPS 186-4 combination |
|---|---|---|
1024 | 160 | Legacy |
2048 | 224 or 256 | Supported parameter pairs |
3072 | 256 | Largest listed pair |
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GenKeyFromParamsDerBd
# $success is true or false
my $success = $dsa->GenKeyFromParamsDerBd($bd);
Generates a new DSA key pair from OpenSSL-style DSA parameters stored as DER bytes in the BinData object passed in $bd
The supplied data contains DSA domain parameters P, Q, and G, not an existing private key. Chilkat validates or imports those parameters and generates a fresh private value X and corresponding public value Y.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GenKeyFromParamsDerFile
# $success is true or false
my $success = $dsa->GenKeyFromParamsDerFile($path);
Generates a new DSA key pair from the OpenSSL-style DER DSA-parameters file specified by $path
The supplied data contains DSA domain parameters P, Q, and G, not an existing private key. Chilkat validates or imports those parameters and generates a fresh private value X and corresponding public value Y.
Returns 1 when the parameters are loaded and a key pair is generated successfully.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GenKeyFromParamsPem
# $success is true or false
my $success = $dsa->GenKeyFromParamsPem($pem);
Generates a new DSA key pair from OpenSSL-style DSA parameters supplied as PEM text in $pem
The supplied data contains DSA domain parameters P, Q, and G, not an existing private key. Chilkat validates or imports those parameters and generates a fresh private value X and corresponding public value Y.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GenKeyFromParamsPemFile
# $success is true or false
my $success = $dsa->GenKeyFromParamsPemFile($path);
Generates a new DSA key pair from the OpenSSL-style PEM DSA-parameters file specified by $path
The supplied data contains DSA domain parameters P, Q, and G, not an existing private key. Chilkat validates or imports those parameters and generates a fresh private value X and corresponding public value Y.
A typical parameter file is PEM-armored with a BEGIN DSA PARAMETERS header. The newly generated private key can be exported with the applicable To* methods.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GenKeyFromPQG
# $qHex is a string
# $gHex is a string
# $success is true or false
my $success = $dsa->GenKeyFromPQG($pHex, $qHex, $gHex);
Generates a new DSA private/public key pair using the preselected domain parameters P, Q, and G supplied in $pHex$qHex$gHex
Each argument is hexadecimal text in Chilkat's SSH1-format bignum representation. Chilkat generates a fresh private value X and derives Y; the supplied values are domain parameters, not an existing key pair.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetEncodedHash
# $str is a string or undef
my $str = $dsa->GetEncodedHash($encoding);
Returns the current Hash bytes encoded according to $encodinghex or base64.
This method does not compute a hash; it only converts the bytes already stored in the Hash property to text.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetEncodedSignature
# $str is a string or undef
my $str = $dsa->GetEncodedSignature($encoding);
Returns the current Signature bytes encoded according to $encodinghex or base64.
After a successful SignHash call, the returned bytes are the ASN.1 DER-encoded DSA signature containing the integers r and s.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
LoadText
# $str is a string or undef
my $str = $dsa->LoadText($path);
Loads the entire file specified by $path
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SaveText
# $path is a string
# $success is true or false
my $success = $dsa->SaveText($strToSave, $path);
Writes $strToSave$path1 on success.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SetEncodedHash
# $encodedHash is a string
# $success is true or false
my $success = $dsa->SetEncodedHash($encoding, $encodedHash);
Decodes $encodedHash$encodingHash property. Use hex or base64.
The decoded value must be the already-computed message digest that will be signed by SignHash or checked by Verify.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SetEncodedSignature
# $encodedSig is a string
# $success is true or false
my $success = $dsa->SetEncodedSignature($encoding, $encodedSig);
Decodes the signature text in $encodedSig$encodingSignature property. Use hex or base64.
The decoded bytes are expected to contain the ASN.1 DER-encoded DSA signature. Set the corresponding Hash and public key before calling Verify.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SetEncodedSignatureRS
# $encodedR is a string
# $encodedS is a string
# $success is true or false
my $success = $dsa->SetEncodedSignatureRS($encoding, $encodedR, $encodedS);
Builds the DSA signature from separately encoded r and s integer values. $encoding$encodedR$encodedShex or base64.
On success, Signature contains the ASN.1 DER SEQUENCE of the two integers and is ready for use with Verify.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SetKeyExplicit
# $pHex is a string
# $qHex is a string
# $gHex is a string
# $xHex is a string
# $success is true or false
my $success = $dsa->SetKeyExplicit($groupSizeInBytes, $pHex, $qHex, $gHex, $xHex);
Loads a DSA private key from explicitly supplied components. $groupSizeInBytesQ in bytes. $pHex$qHex$gHex$xHexP, Q, G, and the private value X, respectively.
The corresponding public value Y = GX mod P is derived from the private key.
xHex contains the private key. Do not expose it in logs or transmit it over an unprotected channel.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SetPubKeyExplicit
# $pHex is a string
# $qHex is a string
# $gHex is a string
# $yHex is a string
# $success is true or false
my $success = $dsa->SetPubKeyExplicit($groupSizeInBytes, $pHex, $qHex, $gHex, $yHex);
Loads a DSA public key from explicitly supplied components. $groupSizeInBytesQ in bytes. $pHex$qHex$gHex$yHexP, Q, G, and the public value Y, respectively.
The resulting object can verify DSA signatures but cannot create them.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SignHash
my $success = $dsa->SignHash();
Creates a DSA signature over the digest currently stored in Hash. A DSA private key must be loaded, and the digest must be set directly or with SetEncodedHash before this method is called.
On success, Signature contains an ASN.1 DER-encoded sequence of the DSA values r and s. Retrieve it with GetEncodedSignature or read the Signature property.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToDerBd
Writes the DER-encoded DSA private key to the BinData object passed in $bd1 on success.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToDerFile
# $success is true or false
my $success = $dsa->ToDerFile($path);
Writes the loaded DSA private key to the DER file specified by $path1 on success.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToEncryptedPem
# $str is a string or undef
my $str = $dsa->ToEncryptedPem($password);
Returns the loaded DSA private key as password-encrypted PEM text using $password
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToPem
my $str = $dsa->ToPem();
Returns the loaded DSA private key as unencrypted PEM text.
ToEncryptedPem when password protection is required.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToPublicDerFile
# $success is true or false
my $success = $dsa->ToPublicDerFile($path);
Writes the public portion of the loaded DSA key to the DER file specified by $path1 on success.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToPublicPem
my $str = $dsa->ToPublicPem();
Returns the public portion of the loaded DSA key as PEM text. Public-key PEM may be distributed to parties that need to verify signatures; it does not contain the private value X.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ToXml
# $str is a string or undef
my $str = $dsa->ToXml($bPublicOnly);
Returns the loaded DSA key as XML. Set $bPublicOnly1 to export public components only. Set it to 0 to include the private component when a private key is loaded.
$bPublicOnly0, the XML can contain the private value X. Protect it as private-key material.Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
Verify
my $success = $dsa->Verify();
Verifies the DSA signature currently stored in Signature against the digest stored in Hash, using the loaded public key. Both values must be set before calling this method.
Returns 1 only when the signature is valid. A 0 result can indicate an invalid signature, malformed input, an incompatible key, or another operational error; inspect LastErrorText when the reason matters.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
VerifyKey
my $flag = $dsa->VerifyKey();
Checks the mathematical validity and internal consistency of the DSA public or private key currently loaded in the object. Returns 1 when the key parameters and available key components pass validation.
This does not establish who owns the key, whether the key came from a trusted source, or whether it is suitable for a particular protocol.
Never dies: false is an answer, not a failure.