DeforaNetworks/fwknop
3
0
Fork 0
Code Releases Activity

a few HMAC doc updates to the libfko.texi file

Browse Source
This commit is contained in:
Michael Rash
2013-06-03 21:45:29 -04:00
parent 69ba2d7a06
commit 7c4beabea0
1 changed files with 68 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/libfko.texi
+68 -19
View File
@@ -610,8 +610,8 @@ char *key;
int key_len;
char *hmac_key;
int hmac_key_len;
int hmac_type;
int enc_mode;
int hmac_type = FKO_HMAC_SHA256;
int enc_mode = FKO_ENC_MODE_CBC;
int rc;
/* Assume we called code that retrieves the data and key
@@ -630,9 +630,9 @@ if(rc != FKO_SUCCESS)
@noindent
Or, perhaps you need to defer decryption and parsing to a later point
in the program. We could use fko_new_with_data(), passing NULL for the
decryption key, or we could use fko_new() to create an empty context,
then use fko_set_spa_data() to add the encypted data (see comments in the code
samples).
decryption key and HMAC keys, or we could use fko_new() to create an empty
context, then use fko_set_spa_data() to add the encypted data (see comments
in the code samples).
@example
fko_ctx_t ctx;
@@ -643,7 +643,8 @@ int rc;
/* Assume we called code that retrieves the data and key
*/
rc = fko_new_with_data(&ctx, spa_data, NULL);
rc = fko_new_with_data(&ctx, spa_data, NULL, 0,
FKO_ENC_MODE_CBC, NULL, 0, FKO_HMAC_SHA256);
if(rc != FKO_SUCCESS)
@{
@@ -663,9 +664,19 @@ if(rc != FKO_SUCCESS)
/* Assume we called other code and functions... */
/* Verify HMAC
*/
rc = fko_verify_hmac(ctx, hmac_key, hmac_key_len);
if(rc != FKO_SUCCESS)
@{
fprintf(stderr, "Error from fko_verify_hmac: %s\n",
fko_errstr(rc));
exit(1);
@}
/* Decrypt and decode...
*/
rc = fko_decrypt_spa_data(ctx, key);
rc = fko_decrypt_spa_data(ctx, key, key_len);
if(rc != FKO_SUCCESS)
@{
@@ -752,13 +763,19 @@ a contrived bit of code demonstrating this:
int
main(int argc, char **argv)
@{
fko_ctx_t ctx; /* FKO Context */
char *password; /* Encryption password */
char *final_spa; /* Final encrypted SPA data */
int rc; /* Result code */
fko_ctx_t ctx; /* FKO Context */
char *key; /* Encryption passphrase */
char *hmac_key; /* HMAC key */
char *final_spa; /* Final encrypted SPA data */
int key_len; /* Length of encryption key */
int hmac_key_len; /* Length of HMAC key */
int rc; /* Result code */
int hmac_type = FKO_HMAC_SHA256; /* Default HMAC digest */
int enc_mode = FKO_ENC_MODE_ASYMMETRIC; /* Use GPG */
/* Assume we processed the command line
* and retrieved the password.
* and retrieved the password and the HMAC key and
* set their associated lengths.
*/
/* Create the context */
@@ -792,7 +809,8 @@ main(int argc, char **argv)
rc = fko_set_gpg_signer(ctx, "me@@right.here");
/* Finalize the SPA data */
rc = fko_spa_data_final(ctx);
rc = fko_spa_data_final(ctx, key, key_len, enc_mode,
hmac_key, hmac_key_len, hmac_type);
if(rc != FKO_SUCCESS)
@{
fprintf(stderr, "Error encoding SPA data: %s\n", fko_errstr(rc));
@@ -813,7 +831,7 @@ main(int argc, char **argv)
exit(0);
@}
@end example
@node Setting SPA Data
@section Setting SPA Data
@cindex spa data, setting values
@@ -834,6 +852,16 @@ For example:
@end example
@end deftypefun
@deftypefun int fko_set_spa_hmac_type (@w{fko_ctx_t @var{ctx}, short @var{hmac_type}});
Set the message hmac type. Valid values can be found in @ref{HMAC Digests}
of this manual. If a value other than the those that are supported is given,
the function will return @code{FKO_ERROR_INVALID_DATA}.
For example:
@example
rc = fko_set_hmac_type(ctx, FKO_HMAC_SHA256);
@end example
@end deftypefun
@deftypefun int fko_set_spa_encryption_type (@w{fko_ctx_t @var{ctx}, short @var{encrypt_type}});
Set the encrytion algorithm to use when ecrypting the final @acronym{SPA}
data. Valid values can be found in @ref{Encryption Algorithms} of this
@@ -902,7 +930,7 @@ the correct @code{message_type} ahead of time.
@end deftypefun
@deftypefun int fko_set_spa_digest (@w{fko_ctx_t @var{ctx}});
Initiates a calculation (or recalculation) if the message digest hash for the
Initiates a calculation (or recalculation) of the message digest hash for the
current @acronym{SPA} data. If the required data fields are not set this
function will return @code{FKO_ERROR_MISSING_ENCODED_DATA}.
@strong{Note}: It should not be necessary to call this function directly
@@ -910,6 +938,14 @@ as it will be called automatically by other functions during normal
processing (most notably @code{fko_spa_data_final}).
@end deftypefun
@deftypefun int fko_set_spa_hmac (@w{fko_ctx_t @var{ctx}, const char @var{*hmac_key}, const int @var{hmac_key_len}});
Initiates a calculation (or recalculation) of the message HMAC for the
current @acronym{SPA} data.
@strong{Note}: It should not be necessary to call this function directly
as it will be called automatically by other functions during normal
processing (most notably @code{fko_spa_data_final}).
@end deftypefun
@deftypefun int fko_set_spa_data (@w{fko_ctx_t @var{ctx}, char @var{*enc_data}});
This function is used to place encrypted @acronym{SPA} data into a newly
created empty context (i.e. with @code{fko_new}). In most cases, you would
@@ -1054,12 +1090,25 @@ list of valid digest_types listed in @ref{Digests} of this manual. The
return value is an FKO error status.
@end deftypefun
@deftypefun int fko_get_spa_hmac_type (@w{fko_ctx_t @var{ctx}, short @var{*hmac_type}});
Sets the value of the @var{hmac_type} variable to the HMAC type value
associated with the current context. This value can be checked against the
list of valid hmac_types listed in @ref{HMAC Digests} of this manual. The
return value is an FKO error status.
@end deftypefun
@deftypefun int fko_get_spa_digest (@w{fko_ctx_t @var{ctx}, char @var{**spa_digest}});
Assigns the pointer to the string holding the the fko @acronym{SPA} digest
value associated with the current context to the address @var{spa_digest}
is pointing to. The return value is an FKO error status.
@end deftypefun
@deftypefun int fko_get_spa_hmac (@w{fko_ctx_t @var{ctx}, char @var{**spa_hmac}});
Assigns the pointer to the string holding the the fko @acronym{SPA} HMAC
value associated with the current context to the address @var{spa_hmac}
is pointing to. The return value is an FKO error status.
@end deftypefun
@deftypefun int fko_get_spa_encryption_type (@w{fko_ctx_t @var{ctx}, short @var{*enc_type}});
Sets the value of the @var{enc_type} variable to the encryption type value
associated with the current context. This value can be checked against the
@@ -1167,14 +1216,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}, char @var{*enc_key}});
@deftypefun int fko_spa_data_final (@w{fko_ctx_t @var{ctx}, char @var{*enc_key}, int @var{ken_len}, char @var{*hmac_key}, int @var{hmac_key_len}});
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}, char @var{*dec_key}});
@deftypefun int fko_decrypt_spa_data (@w{fko_ctx_t @var{ctx}, char @var{*dec_key}, int @var{key_len}});
When given the correct @var{key} (password), 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
@@ -1183,10 +1232,10 @@ 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}, char @var{*enc_key}});
@deftypefun int fko_encrypt_spa_data (@w{fko_ctx_t @var{ctx}, char @var{*enc_key}, int @var{key_len}});
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}.
called directly as it is called from @code{fko_spa_data_final}.
@end deftypefun
@deftypefun int fko_decode_spa_data (@w{fko_ctx_t @var{ctx}});