certmanager Library API Documentation

Signature Actions
[Signing and Encrypting Actions]


Enumerations

enum  {
  SigStat_VALID = 0x0001, SigStat_GREEN = 0x0002, SigStat_RED = 0x0004, SigStat_KEY_REVOKED = 0x0010,
  SigStat_KEY_EXPIRED = 0x0020, SigStat_SIG_EXPIRED = 0x0040, SigStat_KEY_MISSING = 0x0080, SigStat_CRL_MISSING = 0x0100,
  SigStat_CRL_TOO_OLD = 0x0200, SigStat_BAD_POLICY = 0x0400, SigStat_SYS_ERROR = 0x0800, SigStat_NUMERICAL_CODE = 0x8000
}
enum  {
  SigStatus_UNKNOWN = 0x0000, SigStatus_VALID = SigStat_VALID, SigStatus_GREEN = SigStat_GREEN, SigStatus_RED = SigStat_RED,
  SigStatus_KEY_REVOKED = SigStat_KEY_REVOKED, SigStatus_KEY_EXPIRED = SigStat_KEY_EXPIRED, SigStatus_SIG_EXPIRED = SigStat_SIG_EXPIRED, SigStatus_KEY_MISSING = SigStat_KEY_MISSING,
  SigStatus_CRL_MISSING = SigStat_CRL_MISSING, SigStatus_CRL_TOO_OLD = SigStat_CRL_TOO_OLD, SigStatus_BAD_POLICY = SigStat_BAD_POLICY, SigStatus_SYS_ERROR = SigStat_SYS_ERROR,
  SigStatus_NUMERICAL_CODE = 0x8000
}

Functions

bool CryptPlug::signMessage (const char *cleartext, char **ciphertext, const size_t *cipherLen, const char *certificate, struct StructuringInfo *structuring, int *errId, char **errTxt, SendCertificates sendCertificates, SignatureCompoundMode signatureCompoundMode)
bool CryptPlug::checkMessageSignature (char **cleartext, const char *signaturetext, bool signatureIsBinary, int signatureLen, struct SignatureMetaData *sigmeta, char **attrOrder, const char *unknownAttrsHandling)
bool CryptPlug::storeCertificatesFromMessage (const char *ciphertext)
bool CryptPlugWrapper::signMessage (const char *cleartext, char **ciphertext, const size_t *cipherLen, const char *certificate, StructuringInfoWrapper &structuring, int *errId, char **errTxt)
bool CryptPlugWrapper::checkMessageSignature (char **cleartext, const char *signaturetext, bool signatureIsBinary, int signatureLen, CryptPlug::SignatureMetaData *sigmeta)
bool CryptPlugWrapper::storeCertificatesFromMessage (const char *ciphertext)

Detailed Description

This section describes methods that are used for working with signatures.

Enumeration Type Documentation

anonymous enum
 

Flags used to compose the SigStatusFlags value.

This status flags are used to compose the SigStatusFlags value returned in SignatureMetaDataExtendedInfo after trying to verify a signed message part's signature status.

The normal flags may not be used together with the special SigStat_NUMERICAL_CODE flag. When finding the special SigStat_NUMERICAL_CODE flag in a SigStatusFlags value you can obtain the respective error code number by substracting the SigStatusFlags value by SigStat_NUMERICAL_CODE: this is used to transport special status information NOT matching any of the normal predefined status codes.

Note:
to PlugIn developers: Implementations of the CryptPlug API should try to express their signature states by bit-wise OR'ing the normal SigStatusFlags values. Using the SigStat_NUMERICAL_CODE flag should only be used as for exceptional situations where no other flag(s) could be used. By using the normal status flags your PlugIn's users will be told an understandable description of the status - when using (SigStat_NUMERICAL_CODE + internalCode) they will only be shown the respective code number and have to look into your PlugIn's manual to learn about it's meaning...
Definition at line 279 of file cryptplug.h.

anonymous enum [inherited]
 

Flags used to compose the SigStatusFlags value.

This status flags are used to compose the SigStatusFlags value returned in SignatureMetaDataExtendedInfo after trying to verify a signed message part's signature status.

The normal flags may not be used together with the special SigStatus_NUMERICAL_CODE flag. When finding the special SigStatus_NUMERICAL_CODE flag in a SigStatusFlags value you can obtain the respective error code number by substracting the SigStatusFlags value by SigStatus_NUMERICAL_CODE: this is used to transport special status information NOT matching any of the normal predefined status codes.

Note:
to PlugIn developers: Implementations of the CryptPlug API should try to express their signature states by bit-wise OR'ing the normal SigStatusFlags values. Using the SigStatus_NUMERICAL_CODE flag should only be used as for exceptional situations where no other flag(s) could be used. By using the normal status flags your PlugIn's users will be told an understandable description of the status - when using (SigStatus_NUMERICAL_CODE + internalCode) they will only be shown the respective code number and have to look into your PlugIn's manual to learn about it's meaning...
Definition at line 501 of file cryptplugwrapper.h.


Function Documentation

bool CryptPlug::signMessage const char *  cleartext,
char **  ciphertext,
const size_t *  cipherLen,
const char *  certificate,
struct StructuringInfo structuring,
int *  errId,
char **  errTxt,
SendCertificates  sendCertificates,
SignatureCompoundMode  signatureCompoundMode
[inherited]
 

Signs a message cleartext and returns in *ciphertext the signature data bloc that is to be added to the message. The length returned in *cipherLen tells you the size (==amount of bytes) of the ciphertext, if the structuring information would return with contentTEncCode set to "base64" the ciphertext might contain a char 0x00 and has to be converted into base64 before sending.

The signature role is specified by certificate. If certificate is NULL, the default certificate is used.

If the message could be signed, the function returns true, otherwise false.

Use the StructuringInfo data returned in parameter structuring to find out how to build the respective MIME object (or the plain text message body, resp.).

Note:
The function allocates memory for the *ciphertext, so make sure you set free that memory when no longer needing it (as shown in example code provided with documentation of the struct StructuringInfo).

The function also allocates memory for some char* members of the StructuringInfo* parameter that you are providing, therefore you must call the free_StructuringInfo() function to make sure all memory is set free that was allocated. This must be done before calling the next cryptography function - even if you intend to call encryptMessage() immediately after signMessage().

See also:
StructuringInfo, free_StructuringInfo
Definition at line 357 of file cryptplug.cpp.

bool CryptPlug::checkMessageSignature char **  cleartext,
const char *  signaturetext,
bool  signatureIsBinary,
int  signatureLen,
struct SignatureMetaData *  sigmeta,
char **  attrOrder,
const char *  unknownAttrsHandling
[inherited]
 

Checks whether the signature of a message is valid.

cleartext must never be 0 but be a valid pointer.

If *cleartext > 0 then **cleartext specifies the message text that was signed and signaturetext is the signature itself.

If *cleartext == 0 is an empty string then signaturetext is supposed to contain an opaque signed message part. After checking the data and verifying the signature the cleartext of the message will be returned in cleartext. The user must free the respective memory ocupied by *cleartext.

Depending on the configuration, MUAs might not need to use this. If sigmeta is non-null, the SignatureMetaData object pointed to will contain meta information about the signature after the function call. Definition at line 1907 of file cryptplug.cpp.

bool CryptPlug::storeCertificatesFromMessage const char *  ciphertext  )  [inherited]
 

Stores the certificates that follow with the message ciphertext locally.

Definition at line 573 of file cryptplug.cpp.

bool CryptPlugWrapper::signMessage const char *  cleartext,
char **  ciphertext,
const size_t *  cipherLen,
const char *  certificate,
StructuringInfoWrapper structuring,
int *  errId,
char **  errTxt
[inherited]
 

Signs a message cleartext and returns in *ciphertext the signature data bloc that is to be added to the message. The length returned in *cipherLen tells you the size (==amount of bytes) of the ciphertext, if the structuring information would return with contentTEncCode set to "base64" the ciphertext might contain a char 0x00 and has to be converted into base64 before sending.

The signature role is specified by certificate. If certificate is NULL, the default certificate is used.

If the message could be signed, the function returns true, otherwise false.

Use the StructuringInfoWrapper data returned in parameter structuring to find out how to build the respective MIME object (or the plain text message body, resp.).

Note:
The function allocates memory for the *ciphertext, so make sure you set free that memory when no longer needing it (as shown in example code provided with documentation of the class StructuringInfoWrapper).

The function also does not use a pure StructuringInfo* struct parameter (as defined in cryptplug.h) but a convenient StructuringInfoWrapper& class parameter. Therefore you must not call the free_StructuringInfo() function: all memory that will be occupied for structuring info by the signing function will be freed automatically by the StructuringInfoWrapper's destructor.

See also:
StructuringInfoWrapper
Definition at line 939 of file cryptplugwrapper.cpp.

References StructuringInfoWrapper::data.

bool CryptPlugWrapper::checkMessageSignature char **  cleartext,
const char *  signaturetext,
bool  signatureIsBinary,
int  signatureLen,
CryptPlug::SignatureMetaData *  sigmeta
[inherited]
 

Checks whether the signature of a message is valid.

cleartext must never be 0 but be a valid pointer.

If *cleartext > 0 then **cleartext specifies the message text that was signed and signaturetext is the signature itself.

If *cleartext == 0 is an empty string then signaturetext is supposed to contain an opaque signed message part. After checking the data and verifying the signature the cleartext of the message will be returned in cleartext. The user must free the respective memory occupied by *cleartext.

Depending on the configuration, MUAs might not need to use this. If sigmeta is non-null, the SignatureMetaData object pointed to will contain meta information about the signature after the function call. Definition at line 953 of file cryptplugwrapper.cpp.

bool CryptPlugWrapper::storeCertificatesFromMessage const char *  ciphertext  )  [inherited]
 

Stores the certificates that follow with the message ciphertext locally.

Definition at line 973 of file cryptplugwrapper.cpp.

KDE Logo
This file is part of the documentation for certmanager Library Version 3.3.0.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Fri Aug 27 12:49:36 2004 by doxygen 1.3.8 written by Dimitri van Heesch, © 1997-2003