From 4ef8a25596de387d0ad61a39221af5c15178c611 Mon Sep 17 00:00:00 2001 From: Damien Stuart Date: Wed, 11 Feb 2009 01:00:08 +0000 Subject: [PATCH] Update libfko docs for the gpgme-related error codes and function. git-svn-id: file:///home/mbr/svn/fwknop/trunk@60 510a4753-2344-4c79-9c09-4d669213fbeb --- doc/libfko.texi | 72 +++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 67 insertions(+), 5 deletions(-) diff --git a/doc/libfko.texi b/doc/libfko.texi index 1061521a..e0687df3 100644 --- a/doc/libfko.texi +++ b/doc/libfko.texi @@ -528,7 +528,7 @@ if(rc != FKO_SUCCESS) For a context that will be used for receiving and parsing an existing @acronym{SPA} message, you will use the @code{fko_new_with_data} function: -@deftypefun int fko_new_with_data (@w{fko_ctx_t @var{*ctx}, char @var{*data}, const char @var{*key}}) +@deftypefun int fko_new_with_data (@w{fko_ctx_t @var{*ctx}, char @var{*data}, char @var{*key}}) The function @code{fko_new_with_data} sets up and initializes a new @code{fko_ctx_t} context, but instead of initializing default values, it stores the encrypted message data and makes it ready for parsing. This @@ -676,7 +676,7 @@ int main(int argc, char **argv) @{ fko_ctx_t ctx; /* FKO Context */ - const char *password; /* Encryption password */ + char *password; /* Encryption password */ char *final_spa; /* Final encrypted SPA data */ int rc; /* Result code */ @@ -987,14 +987,14 @@ All of these functions return an integer representing the return status of the function. When succesfull, they will return @code{FKO_SUCCESS}. Otherwise, an error code value is returned. -@deftypefun int fko_spa_data_final (@w{fko_ctx_t @var{ctx}, const char @var{*enc_key}}); +@deftypefun int fko_spa_data_final (@w{fko_ctx_t @var{ctx}, char @var{*enc_key}}); This function is the final step in creating a complete encrypted @acronym{SPA} data string suitable for transmission to an fwknop server. It does require all of the requisite @acronym{SPA} data fields be set, otherwise it will fail with an appropriate error code. @end deftypefun -@deftypefun int fko_decrypt_spa_data (@w{fko_ctx_t @var{ctx}, const char @var{*dec_key}}); +@deftypefun int fko_decrypt_spa_data (@w{fko_ctx_t @var{ctx}, char @var{*dec_key}}); When given the correct @var{key} (passsword), this function decrypts, decodes, and parses the encrypted @acronym{SPA} data that was supplied to the context via the @code{fko_new_with_data} function that was also called without the @@ -1003,7 +1003,7 @@ via the @code{fko_new_with_data} function that was also called without the fields in the context for later retrieval. @end deftypefun -@deftypefun int fko_encrypt_spa_data (@w{fko_ctx_t @var{ctx}, const char @var{*enc_key}}); +@deftypefun int fko_encrypt_spa_data (@w{fko_ctx_t @var{ctx}, char @var{*enc_key}}); Encrypts the intermediate encoded @acronym{SPA} data stored in the context. This function will call @code{fko_encode} if necessary. It is normally not called directly as it is called from @code{fko_spa_data_final}. @@ -1090,6 +1090,68 @@ Unknown/Unclassified error @end table @end deftypevar +If GPG support is available, there are additional possible error conditions +and error codes. The @acronym{GPG} support is implemented via @acronym{GPGME}. +The libfko error handling code wraps many of the @acronym{GPGME} error codes +that may be encountered while using libfko's @acronym{GPG} related functions. +These are: + +@cindex error codes, gpgme related + +@deftypevar int error_code (gpgme support only) +@table @code +@item FKO_ERROR_GPGME_NO_OPENPGP +This GPGME implementation does not support OpenPGP +@item FKO_ERROR_GPGME_CONTEXT +Unable to create GPGME context +@item FKO_ERROR_GPGME_PLAINTEXT_DATA_OBJ +Error creating the plaintext data object +@item FKO_ERROR_GPGME_SET_PROTOCOL +Unable to set GPGME to use OpenPGP protocol +@item FKO_ERROR_GPGME_CIPHER_DATA_OBJ +Error creating the encrypted data data object +@item FKO_ERROR_GPGME_BAD_PASSPHRASE +The GPG passphrase was not valid +@item FKO_ERROR_GPGME_ENCRYPT_SIGN +Error during the encrypt and sign operation +@item FKO_ERROR_GPGME_CONTEXT_SIGNER_KEY +Unable to create GPGME context for the signer key +@item FKO_ERROR_GPGME_SIGNER_KEYLIST_START +Error from signer keylist start operation +@item FKO_ERROR_GPGME_SIGNER_KEY_NOT_FOUND +The key for the given signer was not found +@item FKO_ERROR_GPGME_SIGNER_KEY_AMBIGUOUS +Ambiguous name/id for the signer key (mulitple matches) +@item FKO_ERROR_GPGME_ADD_SIGNER +Error adding the signer key to the gpgme context +@item FKO_ERROR_GPGME_CONTEXT_RECIPIENT_KEY +Unable to create GPGME context for the recipient key +@item FKO_ERROR_GPGME_RECIPIENT_KEYLIST_START +Error from signer keylist start operation +@item FKO_ERROR_GPGME_RECIPIENT_KEY_NOT_FOUND +The key for the given recipient was not found +@item FKO_ERROR_GPGME_RECIPIENT_KEY_AMBIGUOUS +Ambiguous name/id for the recipient key (mulitple matches) +@item FKO_ERROR_GPGME_DECRYPT_FAILED +Decryption operation failed +@end table +@end deftypevar + +You can use the @code{IS_GPGME_ERROR(err_code)} macro to determine whether +or not an error id @acronym{GPGME} related. If the macro evaluates to a +true value, you may be able to get additioinal information about the error +using the following function: + +@cindex gpg-specific functions + +@deftypefun {const char *} fko_gpg_errstr (@w{int @var{err_code}}) +The function @code{fko_errstr} returns a pointer to a statically +allocated string containing the descripton of the @acronym{GPGME} error. +@end deftypefun + +@noindent +@strong{Note}: For some errors, this function may return an empty string. + @c --End of main chapters. @include gpl-2.0.texi