SmartFTP FTP Library
IKey Interface Reference

Encapsulates a cryptographic key pair, public key, or certificate. More...

import "sfFTPLib.idl";

Public Member Functions

HRESULT ImportBlob ([in] LPCWSTR pszBlobType, [in, size_is(cbInput)] byte *pbInput, [in] ULONG cbInput)
 Loads a key or certificate from a memory buffer.
HRESULT Verify ([in] HashAlgo hashAlgo, [in, size_is(cbSignature)] byte *pbSignature, [in] ULONG cbSignature, [in, size_is(cbInput)] byte *pbInput, [in] ULONG cbInput, [in] ULONG flags)
 Verifies a digital signature against a data blob.
HRESULT ExportKey ([in] LPCWSTR pszBlobType, [out, size_is(*pcbData)] byte *pbData, [in, out] ULONG *pcbData)
 Serializes the key to a memory buffer.
HRESULT Sign ([in] HashAlgo hashAlgo, [in, size_is(cbInput)] byte *pbInput, [in] ULONG cbInput, [out, size_is(*pcbSignature)] byte *pbSignature, [in, out] ULONG *pcbSignature, [in] ULONG flags)
 Generates a digital signature for a data blob.
HRESULT SetProperty ([in] LPCWSTR pszProperty, [in, size_is(cbInput)] byte *pbInput, [in] ULONG cbInput, [in] ULONG dwFlags)
 Sets advanced or algorithm-specific properties.

Properties

KeyType Type [get]
 Retrieves the classification of the key (e.g., Private, Public, or None).
long Bits [get]
 Retrieves the strength of the key in bits.
KeyAlgo Algo [get]
 Identifies the cryptographic algorithm used by this key.
VARIANT Certificate [get]
 Retrieves the raw certificate data associated with this key, if any.
CertificateType CertificateType [get]
 Indicates the format of the attached certificate.

Detailed Description

Encapsulates a cryptographic key pair, public key, or certificate.

This interface represents a cryptographic entity used for authentication and data integrity. It abstracts over various algorithms (RSA, DSA, ECDSA, Ed25519) and formats, providing a unified way to perform operations like Signing and Verification.

Usage Scenarios:

  • Authentication: Loading a private key to authenticate against an SSH server.
  • Verification: checking if a file signature is valid using a sender's public key.

Member Function Documentation

◆ ExportKey()

HRESULT IKey::ExportKey ( [in] LPCWSTR pszBlobType,
[out, size_is(*pcbData)] byte * pbData,
[in, out] ULONG * pcbData )

Serializes the key to a memory buffer.

Memory Handling: Standard COM buffer pattern:

  1. Call with pbData = NULL to retrieve the required size in pcbData.
  2. Allocate the buffer.
  3. Call again with the allocated buffer to retrieve the data.
Parameters
[in]pszBlobTypeTarget format
[out]pbDataBuffer to receive the key data.
[in,out]pcbDataInput: Size of buffer. Output: Actual bytes written.

◆ ImportBlob()

HRESULT IKey::ImportBlob ( [in] LPCWSTR pszBlobType,
[in, size_is(cbInput)] byte * pbInput,
[in] ULONG cbInput )

Loads a key or certificate from a memory buffer.

Parameters
[in]pszBlobTypeString constant identifying the input format.
[in]pbInputPointer to the byte array containing the key data.
[in]cbInputSize of the input buffer in bytes.

◆ SetProperty()

HRESULT IKey::SetProperty ( [in] LPCWSTR pszProperty,
[in, size_is(cbInput)] byte * pbInput,
[in] ULONG cbInput,
[in] ULONG dwFlags )

Sets advanced or algorithm-specific properties.

Purpose: Allows configuration of properties that do not fit into the standard getters.

Parameters
[in]pszPropertyName of the property to set.
[in]pbInputValue of the property (binary or string data).
[in]cbInputSize of the input data.
[in]dwFlagsFlags modifying the set operation.

◆ Sign()

HRESULT IKey::Sign ( [in] HashAlgo hashAlgo,
[in, size_is(cbInput)] byte * pbInput,
[in] ULONG cbInput,
[out, size_is(*pcbSignature)] byte * pbSignature,
[in, out] ULONG * pcbSignature,
[in] ULONG flags )

Generates a digital signature for a data blob.

Requirement: The IKey object must contain a Private Key. If it only contains a Public Key, this method will return an error.

Mechanism: Hashes the input data using hashAlgo and encrypts the hash with the private key components.

Parameters
[in]hashAlgoThe hashing algorithm to use (e.g., SHA-256, SHA-512).
[in]pbInputThe data to be signed.
[in]cbInputSize of the data to be signed.
[out]pbSignatureBuffer to receive the signature.
[in,out]pcbSignatureInput: Buffer size. Output: Bytes written.
[in]flagsOptions for signing (e.g., probabilistic signatures).

◆ Verify()

HRESULT IKey::Verify ( [in] HashAlgo hashAlgo,
[in, size_is(cbSignature)] byte * pbSignature,
[in] ULONG cbSignature,
[in, size_is(cbInput)] byte * pbInput,
[in] ULONG cbInput,
[in] ULONG flags )

Verifies a digital signature against a data blob.

Uses the Public Key component to ensure that pbSignature was generated by the holder of the corresponding Private Key and that pbInput has not been tampered with.

Parameters
[in]hashAlgoThe hashing algorithm used (e.g., SHA-256).
[in]pbSignatureThe signature bytes to verify.
[in]cbSignatureSize of the signature buffer.
[in]pbInputThe original data that was signed.
[in]cbInputSize of the original data.
[in]flagsBitmask for verification options (usually 0).

Property Documentation

◆ Algo

KeyAlgo IKey::Algo
getproperty

Identifies the cryptographic algorithm used by this key.

This property returns the precise algorithm identifier (e.g., ftpKeyAlgoEd25519, ftpKeyAlgoMlDsa65) rather than just a generic family.

Parameters
[out]retvalReceives the KeyAlgo enumeration value.

◆ Bits

long IKey::Bits
getproperty

Retrieves the strength of the key in bits.

Common Values:

  • RSA: 2048, 3072, 4096.
  • ECDSA: 256 (NIST P-256), 384, 521.
  • Ed25519: Fixed at 256.

◆ Certificate

VARIANT IKey::Certificate
getproperty

Retrieves the raw certificate data associated with this key, if any.

Content: If the key was loaded from a certificate (or has a certificate attached), this variant contains the raw binary blob (array of bytes). If no certificate is present, this is empty.

◆ CertificateType

CertificateType IKey::CertificateType
getproperty

Indicates the format of the attached certificate.

Helps determine how to parse the data returned by the Certificate property.

◆ Type

KeyType IKey::Type
getproperty

Retrieves the classification of the key (e.g., Private, Public, or None).

Significance: Determines which operations are valid.

  • Private Keys: Can generate (Sign) and verify signatures (Verify).
  • Public Keys: Can only verify signatures (Verify).
The documentation for this interface was generated from the following file: