Chilkat.Dsa Class Overview

Chilkat.Dsa provides DSA key generation, key import/export, hash signing, signature verification, explicit key parameter handling, and convenience methods for working with DSA keys in DER, PEM, encrypted PEM, XML, and OpenSSL parameter formats.

What the Class Is Used For

Use Chilkat.Dsa when an application needs to work with Digital Signature Algorithm keys or signatures. The class can generate DSA keys, load existing private or public keys, export keys in common formats, sign an already-computed hash, verify a signature over a hash, and expose the DSA key components P, Q, G, X, and Y.

Generate DSA Keys Create new DSA keys directly, from OpenSSL parameter files, or from explicit P, Q, and G values.
Load and Export Keys Import and export private or public DSA keys as DER, PEM, encrypted PEM, XML, byte arrays, files, or BinData.
Sign and Verify Hashes Set a hash, sign it with a private key, retrieve the signature, then verify with the corresponding public key.
Inspect Key Components Read DSA parameters and key values as hex-encoded SSH1-format bignums.

Typical Signing Workflow

  1. Create a Dsa object.
  2. Load or generate a DSA private key using FromPem, FromEncryptedPem, FromDer, FromXml, GenKey, or another key-generation method.
  3. Compute the hash of the data externally.
  4. Set the hash with Hash or SetEncodedHash.
  5. Call SignHash.
  6. Retrieve the signature using Signature, GetEncodedSignature, or R/S-specific handling.
  7. Check LastErrorText after failures or unexpected behavior.

Typical Verification Workflow

  1. Create a Dsa object.
  2. Load the DSA public key using FromPublicPem, FromPublicDer, FromPublicDerFile, FromPublicDerBd, or FromXml.
  3. Set the hash that was signed using Hash or SetEncodedHash.
  4. Set the signature to verify using Signature, SetEncodedSignature, or SetEncodedSignatureRS.
  5. Call Verify.
  6. Optionally call VerifyKey to verify the loaded key itself.

Core Concepts

Concept Meaning Important Members
DSA Parameters DSA key parameters consist of P, Q, and G. HexP, HexQ, HexG, GenKeyFromPQG
Private Key Value X is the private key value. It is available only when a private key is loaded. HexX, SetKeyExplicit
Public Key Value Y is the public key value. It is available for public keys and also when a private key is loaded. HexY, SetPubKeyExplicit
Hash to Sign DSA signs an already-computed hash. The hash must be set before signing or verifying. Hash, SetEncodedHash, SignHash, Verify
Signature The DSA signature generated by SignHash or supplied before Verify. Signature, GetEncodedSignature, SetEncodedSignature, SetEncodedSignatureRS
SSH1-Format Bignum The key components exposed by this class are represented as hex-encoded SSH1-format bignums. HexP, HexQ, HexG, HexX, HexY

Core Properties

Property Purpose Guidance
Hash The hash bytes to be signed or verified. Must be set before SignHash or Verify. It can also be set with SetEncodedHash.
Signature The DSA signature bytes. Set by SignHash. For verification, set it before calling Verify.
GroupSize Group size in bits used in DSA key generation. Default is 160. The documentation says this should not be changed; it exists for future expansion.
HexP DSA parameter P, the large prime. Returned as a hex-encoded SSH1-format bignum.
HexQ DSA parameter Q. Returned as a hex-encoded SSH1-format bignum.
HexG DSA parameter G, the generator. Returned as a hex-encoded SSH1-format bignum.
HexX DSA private key value X. Available only for private keys.
HexY DSA public key value Y. Available for public keys and private keys.
UncommonOptions Catch-all property for uncommon needs. Defaults to the empty string and should typically remain empty.
LastErrorText Diagnostic text for the last method or property access. Check after failures or unexpected results. Diagnostic information may be available regardless of success or failure.

Key Generation

Method Purpose Important Details
GenKey Generates a new DSA key of the requested bit length. numBits should be at least 1024 and a multiple of 64. Typical values are 1024 and 2048.
GenKey2 Generates a DSA key using a key length and modulus size. FIPS 186-4 combinations listed by the reference are (1024,160), (2048,224), (2048,256), and (3072,256).
GenKeyFromPQG Generates a new DSA key from pre-chosen P, Q, and G parameters. Use when parameters are supplied externally or must be reused.
GenKeyFromParamsPem, GenKeyFromParamsPemFile Generates a new DSA key from OpenSSL PEM-formatted DSA parameters. Useful with OpenSSL-generated DSA parameter PEM data.
GenKeyFromParamsDer, GenKeyFromParamsDerBd, GenKeyFromParamsDerFile Generates a new DSA key from OpenSSL DER-formatted DSA parameters. Use byte arrays, BinData, or DER parameter files.
OpenSSL parameter workflow: The reference shows OpenSSL parameter generation examples such as openssl dsaparam 1024 dsaparam.pem and openssl dsaparam -outform DER 1024 dsaparam.der.

Loading DSA Keys

Key Type Input Format Methods
Private key DER bytes, file, or BinData FromDer, FromDerFile, FromDerBd
Private key Unencrypted PEM string FromPem
Private key Encrypted PEM string FromEncryptedPem. If the PEM is unencrypted, the password is ignored.
Public key DER bytes, file, or BinData FromPublicDer, FromPublicDerFile, FromPublicDerBd
Public key PEM string FromPublicPem
Public or private key XML string FromXml
Private key from explicit values Hex-encoded SSH1-format bignums SetKeyExplicit
Public key from explicit values Hex-encoded SSH1-format bignums SetPubKeyExplicit

Exporting DSA Keys

Output Private Key Methods Public Key Methods
DER byte array ToDer ToPublicDer
DER BinData ToDerBd ToPublicDerBd
DER file ToDerFile ToPublicDerFile
PEM string ToPem ToPublicPem
Encrypted PEM string ToEncryptedPem Not applicable
XML string ToXml. The bPublicOnly argument determines whether public or private key XML is written.

Signing and Verification

Task Method / Property Behavior
Set hash bytes Hash or SetEncodedHash The hash must be set before calling SignHash or Verify.
Sign hash SignHash Signs the current Hash using the loaded private key. On success, Signature is set.
Get encoded hash GetEncodedHash Returns the current Hash bytes as hex or base64.
Get encoded signature GetEncodedSignature Returns the current Signature bytes as hex or base64.
Set encoded signature SetEncodedSignature Sets the signature from a hex or base64 encoded string before verification.
Set signature from R and S SetEncodedSignatureRS Sets the signature from separately encoded R and S values.
Verify signature Verify Verifies the current Signature over the current Hash.
Important: Chilkat.Dsa signs and verifies a hash, not the original message bytes. The application should compute the hash first, then provide it through Hash or SetEncodedHash.

Explicit Key Components

Component Property Meaning Available With
P HexP Large DSA prime. Public or private key.
Q HexQ DSA subgroup parameter. Public or private key.
G HexG DSA generator. Public or private key.
X HexX Private key value. Private key only.
Y HexY Public key value. Public key, and also available when a private key is loaded.
Encoding rule: Explicit DSA components are represented as hex-encoded SSH1-format bignums. This applies to the Hex* properties and the explicit key-setting methods.

Text File Convenience Methods

Method Purpose Encoding Note
LoadText Loads the entire contents of a text file into a string. Assumes the text contains ANSI encoded character data.
SaveText Saves a string to a text file. Saves using ANSI character encoding.

Method Summary by Category

Category Methods Purpose
Generate keys GenKey, GenKey2, GenKeyFromPQG, GenKeyFromParamsPem, GenKeyFromParamsPemFile, GenKeyFromParamsDer, GenKeyFromParamsDerBd, GenKeyFromParamsDerFile Generate new DSA keys directly, from explicit parameters, or from OpenSSL parameter data.
Load private keys FromDer, FromDerBd, FromDerFile, FromPem, FromEncryptedPem, FromXml, SetKeyExplicit Load private DSA keys from DER, PEM, encrypted PEM, XML, or explicit key components.
Load public keys FromPublicDer, FromPublicDerBd, FromPublicDerFile, FromPublicPem, FromXml, SetPubKeyExplicit Load public DSA keys from DER, PEM, XML, or explicit key components.
Export keys ToDer, ToDerBd, ToDerFile, ToPem, ToEncryptedPem, ToPublicDer, ToPublicDerBd, ToPublicDerFile, ToPublicPem, ToXml Export private or public DSA keys in DER, PEM, encrypted PEM, or XML format.
Sign and verify SetEncodedHash, GetEncodedHash, SignHash, SetEncodedSignature, SetEncodedSignatureRS, GetEncodedSignature, Verify Set hash and signature bytes, sign hashes, and verify signatures.
Validate and utilities VerifyKey, LoadText, SaveText Verify that a loaded key is valid and perform simple ANSI text file I/O.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Key generation fails GenKey, GenKey2, LastErrorText Confirm the key length is at least 1024 bits and follows the documented constraints. For GenKey2, use one of the listed key/modulus size combinations.
OpenSSL parameter import fails GenKeyFromParamsPem, GenKeyFromParamsDer Confirm the parameter data is DSA parameter data in the expected PEM or DER format.
Signing fails Hash, SetEncodedHash, SignHash Confirm a private key is loaded and the hash has been set before calling SignHash.
Verification fails Hash, Signature, Verify Confirm the public key is correct, the hash matches the original signed data, and the signature bytes are set in the expected format.
Signature is provided as separate R and S values SetEncodedSignatureRS Use this method when the signature is represented as separate encoded R and S values.
Explicit key setup fails SetKeyExplicit, SetPubKeyExplicit Confirm all key components are hex-encoded SSH1-format bignums and that the group size is supplied in bytes.
Need key-integrity confirmation VerifyKey Call VerifyKey to verify that the loaded public or private key is valid.

Common Pitfalls

Pitfall Better Approach
Calling SignHash without setting the hash. Set Hash directly or call SetEncodedHash before signing.
Calling Verify without setting both hash and signature. Set the hash and signature first, using the properties or encoded setter methods.
Trying to sign original message bytes directly. Hash the message first, then sign the hash with SignHash.
Changing GroupSize unnecessarily. Leave it at the default value unless a future Chilkat feature specifically requires otherwise.
Using public-key import methods when a private key is required for signing. Load a private key with FromPem, FromEncryptedPem, FromDer, or another private-key method before signing.
Expecting HexX from a public key. HexX is private-key material and is not available in a DSA public key.
Using non-DSA parameters with OpenSSL parameter import methods. Provide DSA parameters generated by OpenSSL’s dsaparam command.

Best Practices

Recommendation Reason
Use GenKey2 when explicit key and modulus sizes are required. It lets you choose documented FIPS 186-4 key/modulus combinations.
Use BinData methods for binary DER workflows. FromDerBd, FromPublicDerBd, ToDerBd, and ToPublicDerBd avoid unnecessary byte-array handling.
Use encoded setters/getters for easy interchange. SetEncodedHash, SetEncodedSignature, GetEncodedHash, and GetEncodedSignature simplify hex and Base64 workflows.
Use SetEncodedSignatureRS when signatures are split into R and S values. It avoids manual reconstruction of the signature byte format.
Call VerifyKey after loading unfamiliar keys. It confirms that the loaded public or private key is valid.
Protect private keys when exporting. Use ToEncryptedPem when a private key should be exported in encrypted PEM form.
Check LastErrorText after failures. It provides the most useful diagnostic detail for key loading, key generation, signing, verification, import/export, and explicit-parameter issues.

Summary

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 exposes DSA key components as hex-encoded SSH1-format bignums and provides helpers for encoded hashes and signatures.

The most important practical guidance is to remember that DSA signs hashes rather than raw message data, set both the hash and signature before verification, use the correct private/public key method for the operation, and keep GroupSize unchanged unless Chilkat specifically documents a future need to change it.