[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[SCM] GNU shishi branch, master, updated. shishi-1-0-2-49-gfb1c9d5
|
From: |
Mats Erik Andersson |
|
Subject: |
[SCM] GNU shishi branch, master, updated. shishi-1-0-2-49-gfb1c9d5 |
|
Date: |
Fri, 25 Jul 2014 18:15:26 +0000 |
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU shishi".
http://git.savannah.gnu.org/cgit/shishi.git/commit/?id=fb1c9d5a3a33fb8c4ce26e4da29ff44d02e01636
The branch, master has been updated
via fb1c9d5a3a33fb8c4ce26e4da29ff44d02e01636 (commit)
via 4fe9efba0e4ac07b18f01e52f394321cc21ce6a1 (commit)
via 73cd5b2421c6a4328d745609bd2dfe5201d931e8 (commit)
from 9d2b6c8268bef8ad7d8c8c7a4ffa810ffc975b67 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit fb1c9d5a3a33fb8c4ce26e4da29ff44d02e01636
Author: Mats Erik Andersson <address@hidden>
Date: Fri Jul 25 18:17:55 2014 +0200
API documentation
commit 4fe9efba0e4ac07b18f01e52f394321cc21ce6a1
Author: Mats Erik Andersson <address@hidden>
Date: Thu Jul 24 22:53:28 2014 +0200
crypto: defaultcksumtype is signed integer type.
The Redmond fraction enforces upon us a negative value
for SHISHI_ARCFOUR_HMAC_MD5 in the Kerberos standard.
Adapt to this fact, thus silencing a compiler warning.
commit 73cd5b2421c6a4328d745609bd2dfe5201d931e8
Author: Mats Erik Andersson <address@hidden>
Date: Thu Jul 24 22:36:43 2014 +0200
gdoc: Let texinfo mode detect environment.
Let the dollar sign signify an environment variable
in TexInfo mode. This influences all documentation,
since our typeset formats are derived off TexInfo.
-----------------------------------------------------------------------
Summary of changes:
db/config.c | 6 +-
doc/gdoc | 3 +-
lib/cfg.c | 21 +++---
lib/crypto.h | 2 +-
lib/diskio.c | 28 ++++---
lib/kdc.c | 249 +++++++++++++++++++++++++++++++---------------------------
lib/realm.c | 120 +++++++++++++++++-----------
lib/resolv.c | 21 +++--
8 files changed, 250 insertions(+), 200 deletions(-)
diff --git a/db/config.c b/db/config.c
index 7de9f41..3961d6e 100644
--- a/db/config.c
+++ b/db/config.c
@@ -36,7 +36,7 @@
* Neither TYPE nor LOCATION may contain embedded spaces,
* but PARAMETER may do so.
*
- * Return Value: Returns %SHISA_OK if a database was parsed and opened
+ * Return value: Returns %SHISA_OK if a database was parsed and opened
* successfully.
**/
int
@@ -101,7 +101,7 @@ shisa_cfg_db (Shisa * dbh, const char *value)
* The prefix "db", mandatory in @option, makes shisa_cfg() suited
* to a syntax with key-value pairs also in PARAMETER.
*
- * Return Value: Returns %SHISA_OK if @option is valid.
+ * Return value: Returns %SHISA_OK if @option is valid.
**/
int
shisa_cfg (Shisa * dbh, const char *option)
@@ -132,7 +132,7 @@ shisa_cfg (Shisa * dbh, const char *option)
* Configures the Shisa library using a configuration file
* located at @cfg.
*
- * Return Value: Returns %SHISA_OK if successful. Typically
+ * Return value: Returns %SHISA_OK if successful. Typically
* returns %SHISA_CFG_NO_FILE in response to a misnamed file.
**/
int
diff --git a/doc/gdoc b/doc/gdoc
index 83f3312..f067117 100755
--- a/doc/gdoc
+++ b/doc/gdoc
@@ -183,9 +183,10 @@ my %highlights_html = (
my %highlights_texinfo = (
$type_addr => '@@',
$type_constant => '@code{$1}',
+ $type_env => '@env{$1}',
$type_func => '@code{$1}',
- $type_struct => '@code{$1}',
$type_param => '@var{$1}',
+ $type_struct => '@code{$1}',
);
my %highlights_tex = (
diff --git a/lib/cfg.c b/lib/cfg.c
index 025437f..402a911 100644
--- a/lib/cfg.c
+++ b/lib/cfg.c
@@ -110,7 +110,7 @@ _shishi_realminfo_new (Shishi * handle, char *realm)
* Configures the shishi library according to the options
* given in @option.
*
- * Return Value: Returns SHISHI_OK if @option is valid
+ * Return value: Returns %SHISHI_OK if @option is valid
* and configuration was successful.
**/
int
@@ -356,7 +356,7 @@ out:
* Configures the shishi library using a configuration file
* located at @cfg.
*
- * Return Value: Returns %SHISHI_OK if successful.
+ * Return value: Returns %SHISHI_OK if successful.
**/
int
shishi_cfg_from_file (Shishi * handle, const char *cfg)
@@ -431,7 +431,7 @@ _shishi_transport2string (int transport)
* Prints library configuration status to @fh. This function is
* mostly intended for debugging purposes.
*
- * Return Value: Always returns SHISHI_OK.
+ * Return value: Always returns %SHISHI_OK.
**/
int
shishi_cfg_print (Shishi * handle, FILE * fh)
@@ -500,13 +500,12 @@ shishi_cfg_default_systemfile (Shishi * handle)
* @handle: Shishi library handle created by shishi_init().
*
* The default user directory, referred to for Shishi ticket cache
- * and other purposes, is normally computed by appending the compile
- * time macro %BASE_DIR ("/.shishi" by default) to the content of
- * the environment variable $HOME.
+ * and other purposes, is normally computed by appending the fixed
+ * string "/.shishi" to the content of the environment variable $HOME.
*
- * The hard coded directory, generally "$HOME/.shishi/", will be
- * replaced by whatever complete path is stored in the environment
- * variable $SHISHI_HOME.
+ * This hard coded directory, i.e., "$HOME/.shishi/", can be replaced
+ * by whatever complete path is stored in the environment variable
+ * $SHISHI_HOME.
*
* Return value: Returns the user's directory name where the Shishi
* library will search for configuration files, ticket caches,
@@ -634,7 +633,7 @@ shishi_cfg_clientkdcetype_fast (Shishi * handle)
*
* aes256-cts-hmac-sha1-96 des3-cbc-sha1-kd des-cbc-md5
*
- * Return value: Returns SHISHI_OK if successful, and
+ * Return value: Returns %SHISHI_OK if successful, and
* %SHISHI_INVALID_ARGUMENT otherwise.
**/
int
@@ -689,7 +688,7 @@ shishi_cfg_clientkdcetype_set (Shishi * handle, char *value)
* authentication based on preset principals, and then fall back
* to the basic test of identical principal names.
*
- * Return value: Returns SHISHI_OK if successful, and
+ * Return value: Returns %SHISHI_OK if successful, and
* %SHISHI_INVALID_ARGUMENT otherwise.
**/
int
diff --git a/lib/crypto.h b/lib/crypto.h
index 872aacb..71bedb8 100644
--- a/lib/crypto.h
+++ b/lib/crypto.h
@@ -120,7 +120,7 @@ struct cipherinfo
size_t confoundersize;
size_t keylen;
size_t randomlen;
- uint32_t defaultcksumtype;
+ int32_t defaultcksumtype;
Shishi_random_to_key_function random2key;
Shishi_string_to_key_function string2key;
Shishi_encrypt_function encrypt;
diff --git a/lib/diskio.c b/lib/diskio.c
index 3818f77..6cde96d 100644
--- a/lib/diskio.c
+++ b/lib/diskio.c
@@ -981,12 +981,12 @@ shishi_key_parse (Shishi * handle, FILE * fh, Shishi_key
** key)
/**
* shishi_key_print:
- * @handle: shishi handle as allocated by shishi_init().
- * @fh: file handle opened for writing.
- * @key: key to print.
+ * @handle: Shishi handle as allocated by shishi_init().
+ * @fh: File handle open for writing.
+ * @key: Key to print.
*
- * Print an ASCII representation of a key structure to file
- * descriptor. Example output:
+ * Prints an ASCII representation of a key structure @key
+ * to the file descriptor @fh. Example output:
*
* -----BEGIN SHISHI KEY-----
* Keytype: 18 (aes256-cts-hmac-sha1-96)
@@ -998,7 +998,8 @@ shishi_key_parse (Shishi * handle, FILE * fh, Shishi_key **
key)
* P1QdeW/oSiag/bTyVEBAY2msiGSTmgLXlopuCKoppDs=
* -----END SHISHI KEY-----
*
- * Return value: Returns SHISHI_OK iff successful.
+ * Return value: Returns %SHISHI_OK if successful.
+ * The only failure is %SHISHI_MALLOC_ERROR.
**/
int
shishi_key_print (Shishi * handle, FILE * fh, const Shishi_key * key)
@@ -1054,15 +1055,16 @@ shishi_key_print (Shishi * handle, FILE * fh, const
Shishi_key * key)
/**
* shishi_key_to_file:
- * @handle: shishi handle as allocated by shishi_init().
- * @filename: filename to append key to.
- * @key: key to print.
+ * @handle: Shishi handle as allocated by shishi_init().
+ * @filename: Name of file, to which the key text is appended.
+ * @key: Key to print.
*
- * Print an ASCII representation of a key structure to a file. The
- * file is appended to if it exists. See shishi_key_print() for
- * format of output.
+ * Prints an ASCII representation of a key structure @key
+ * to the file @filename. The text is appended if the file
+ * exists. See shishi_key_print() for an example of output text.
*
- * Return value: Returns SHISHI_OK iff successful.
+ * Return value: Returns %SHISHI_OK if successful.
+ * Failures are due to I/O issues, or to allocation.
**/
int
shishi_key_to_file (Shishi * handle, const char *filename, Shishi_key * key)
diff --git a/lib/kdc.c b/lib/kdc.c
index 01332eb..b5d0ac7 100644
--- a/lib/kdc.c
+++ b/lib/kdc.c
@@ -24,19 +24,21 @@
/**
* shishi_as_derive_salt:
- * @handle: shishi handle as allocated by shishi_init().
- * @asreq: input AS-REQ variable.
- * @asrep: input AS-REP variable.
- * @salt: newly allocated output array with salt.
- * @saltlen: holds actual size of output array with salt.
+ * @handle: Shishi handle as allocated by shishi_init().
+ * @asreq: Input AS-REQ variable.
+ * @asrep: Input AS-REP variable.
+ * @salt: Returned pointer to newly allocated output array.
+ * @saltlen: Pointer to integer, returning size of output array.
*
- * Derive the salt that should be used when deriving a key via
- * shishi_string_to_key() for an AS exchange. Currently this searches
- * for PA-DATA of type SHISHI_PA_PW_SALT in the AS-REP and returns it
- * if found, otherwise the salt is derived from the client name and
- * realm in AS-REQ.
+ * Computes the salt that should be used when deriving a key via
+ * shishi_string_to_key() for an AS exchange. Currently this
+ * searches for PA-DATA of type %SHISHI_PA_PW_SALT in the AS-REP
+ * provided by @asrep, and if present returns it. Otherwise the
+ * salt is composed from the client name and the realm, both are
+ * extracted from the request @asreq.
*
- * Return value: Returns SHISHI_OK iff successful.
+ * Return value: Returns %SHISHI_OK if successful.
+ * Failure conditions include various ASN.1 issues.
**/
int
shishi_as_derive_salt (Shishi * handle,
@@ -109,17 +111,19 @@ shishi_as_derive_salt (Shishi * handle,
/**
* shishi_kdcreq_sendrecv_hint:
* @handle: Shishi library handle created by shishi_init().
- * @kdcreq: input variable with a prepared AS-REQ.
- * @kdcrep: output variable with decoded AS-REP.
- * @hint: input #Shishi_tkts_hint structure with flags.
+ * @kdcreq: Input variable with a prepared AS-REQ.
+ * @kdcrep: Output pointer variable for decoded AS-REP.
+ * @hint: Input #Shishi_tkts_hint structure with flags.
*
- * Send a request to KDC, and receive the response.
- * The provided AS-REQ and the hints structure determine
- * transmitted data. On reception the reply is decoded to AS-REP.
+ * Sends a request to KDC, and receives the response.
+ * The provided request @kdcreq and the hints structure @hint,
+ * together determine transmitted data. On reception the reply
+ * is decoded as AS-REP into @kdcrep.
*
- * Returns: %SHISHI_OK on success, %SHISHI_KDC_TIMEOUT on timeouts,
- * %SHISHI_ASN1_ERROR on translation errors,
- * or %SHISHI_GOT_KRBERROR for other corruptions.
+ * Return value: Return code is %SHISHI_OK on success,
+ * %SHISHI_KDC_TIMEOUT on timeouts, %SHISHI_ASN1_ERROR on
+ * translation errors, and %SHISHI_GOT_KRBERROR for other
+ * corruptions.
**/
int
shishi_kdcreq_sendrecv_hint (Shishi * handle,
@@ -203,16 +207,18 @@ shishi_kdcreq_sendrecv_hint (Shishi * handle,
/**
* shishi_kdcreq_sendrecv:
* @handle: Shishi library handle created by shishi_init().
- * @kdcreq: input variable with a prepared AS-REQ.
- * @kdcrep: output variable with received AS-REP.
+ * @kdcreq: Input variable with a prepared AS-REQ.
+ * @kdcrep: Output pointer variable returning received AS-REP.
*
- * Send a request to KDC, and receive the response.
- * The provided AS-REQ sets all data for the request.
- * On reception the reply is decoded to AS-REP.
+ * Sends a request to KDC, and receives the response.
+ * The provided AS-REQ, in @kdcreq, sets all data for the
+ * request. On reception the reply is decoded as AS-REP
+ * into @kdcrep.
*
- * Returns: %SHISHI_OK on success, %SHISHI_KDC_TIMEOUT on timeouts,
- * %SHISHI_ASN1_ERROR on translation errors,
- * or %SHISHI_GOT_KRBERROR for other corruptions.
+ * Return value: Return code is %SHISHI_OK on success,
+ * %SHISHI_KDC_TIMEOUT on timeouts, %SHISHI_ASN1_ERROR on
+ * translation errors, and %SHISHI_GOT_KRBERROR for other
+ * corruptions.
**/
int
shishi_kdcreq_sendrecv (Shishi * handle, Shishi_asn1 kdcreq,
@@ -223,13 +229,15 @@ shishi_kdcreq_sendrecv (Shishi * handle, Shishi_asn1
kdcreq,
/**
* shishi_kdc_copy_crealm:
- * @handle: shishi handle as allocated by shishi_init().
- * @kdcrep: KDC-REP to read crealm from.
- * @encticketpart: EncTicketPart to set crealm in.
+ * @handle: Shishi handle as allocated by shishi_init().
+ * @kdcrep: KDC-REP where the field "crealm" is updated.
+ * @encticketpart: EncTicketPart providing "crealm" field.
*
- * Set crealm in KDC-REP to value in EncTicketPart.
+ * Reads the field "crealm" from the ticket @encticketpart
+ * and copies the value into the reply @kdcrep.
*
- * Return value: Returns SHISHI_OK if successful.
+ * Return value: Returns %SHISHI_OK if successful, and ASN.1
+ * failures otherwise.
**/
int
shishi_kdc_copy_crealm (Shishi * handle,
@@ -253,16 +261,18 @@ shishi_kdc_copy_crealm (Shishi * handle,
/**
* shishi_as_check_crealm:
- * @handle: shishi handle as allocated by shishi_init().
- * @asreq: AS-REQ to compare realm field in.
- * @asrep: AS-REP to compare realm field in.
+ * @handle: Shishi handle as allocated by shishi_init().
+ * @asreq: Request of type AS-REQ.
+ * @asrep: Reply structure of type AS-REP.
*
- * Verify that AS-REQ.req-body.realm and AS-REP.crealm fields match.
- * This is one of the steps that has to be performed when processing a
- * AS-REQ and AS-REP exchange, see shishi_kdc_process().
+ * Verifies that the fields @asreq.req-body.realm and @asrep.crealm
+ * contain identical realm names. This is one of the steps that
+ * has to be performed when processing an exchange of AS-REQ and
+ * AS-REP; see shishi_kdc_process() for more details.
*
- * Return value: Returns SHISHI_OK if successful,
- * SHISHI_REALM_MISMATCH if the values differ, or an error code.
+ * Return value: Returns %SHISHI_OK if successful,
+ * %SHISHI_REALM_MISMATCH whenever the realm names differ,
+ * and an error code otherwise.
**/
int
shishi_as_check_crealm (Shishi * handle, Shishi_asn1 asreq, Shishi_asn1 asrep)
@@ -310,13 +320,15 @@ shishi_as_check_crealm (Shishi * handle, Shishi_asn1
asreq, Shishi_asn1 asrep)
/**
* shishi_kdc_copy_cname:
- * @handle: shishi handle as allocated by shishi_init().
- * @kdcrep: KDC-REP to read cname from.
- * @encticketpart: EncTicketPart to set cname in.
+ * @handle: Shishi handle as allocated by shishi_init().
+ * @kdcrep: KDC-REP where the field "cname" is updated.
+ * @encticketpart: EncTicketPart providing "cname" field.
*
- * Set cname in KDC-REP to value in EncTicketPart.
+ * Reads the field "cname" from the ticket @encticketpart
+ * and copies the value into the reply @kdcrep.
*
- * Return value: Returns SHISHI_OK if successful.
+ * Return value: Returns %SHISHI_OK if successful, and ASN.1
+ * failures otherwise.
**/
int
shishi_kdc_copy_cname (Shishi * handle,
@@ -371,16 +383,18 @@ shishi_kdc_copy_cname (Shishi * handle,
/**
* shishi_as_check_cname:
- * @handle: shishi handle as allocated by shishi_init().
- * @asreq: AS-REQ to compare client name field in.
- * @asrep: AS-REP to compare client name field in.
+ * @handle: Shishi handle as allocated by shishi_init().
+ * @asreq: Request of type AS-REQ.
+ * @asrep: Reply structure of type AS-REP.
*
- * Verify that AS-REQ.req-body.cname and AS-REP.cname fields match.
- * This is one of the steps that has to be performed when processing a
- * AS-REQ and AS-REP exchange, see shishi_kdc_process().
+ * Verifies that the fields @asreq.req-body.cname and @asrep.cname
+ * contain identical names. This is one of the steps that has to
+ * be performed when processing an exchange of AS-REQ and AS-REP;
+ * see shishi_kdc_process() for more details.
*
- * Return value: Returns SHISHI_OK if successful,
- * SHISHI_CNAME_MISMATCH if the values differ, or an error code.
+ * Return value: Returns %SHISHI_OK if successful,
+ * %SHISHI_CNAME_MISMATCH if the names differ,
+ * and an error code otherwise.
**/
int
shishi_as_check_cname (Shishi * handle, Shishi_asn1 asreq, Shishi_asn1 asrep)
@@ -442,13 +456,14 @@ shishi_as_check_cname (Shishi * handle, Shishi_asn1
asreq, Shishi_asn1 asrep)
/**
* shishi_kdc_copy_nonce:
- * @handle: shishi handle as allocated by shishi_init().
- * @kdcreq: KDC-REQ to read nonce from.
- * @enckdcreppart: EncKDCRepPart to set nonce in.
+ * @handle: Shishi handle as allocated by shishi_init().
+ * @kdcreq: KDC-REQ providing "nonce" field.
+ * @enckdcreppart: EncKDCRepPart where "nonce" field is updated.
*
- * Set nonce in EncKDCRepPart to value in KDC-REQ.
+ * Sets the field "nonce" in @enckdcreppart to a value retreived
+ * from the corresponding field in @kdcreq.
*
- * Return value: Returns SHISHI_OK if successful.
+ * Return value: Returns %SHISHI_OK if successful.
**/
int
shishi_kdc_copy_nonce (Shishi * handle,
@@ -493,12 +508,12 @@ shishi_kdc_check_nonce_1 (Shishi * handle,
*
* RFC 1510 didn't restrict nonce to 4 bytes, so the nonce field
* may be longer. There are KDCs that will accept longer nonces
- * but truncated them to 4 bytes in the response. If we happen
+ * but truncate them to 4 bytes in the response. If we happen
* to parse such a KDC request, we consider it OK even though it
* isn't. I doubt this is a security problem, because you need
- * to break the integrity protection of the encryption system
- * as well as guess the nonce correctly. The nonce doesn't seem
- * to serve any purpose at all, really.
+ * to break the integrity protection of the encryption system,
+ * as well as guessing the nonce correctly. The nonce doesn't
+ * seem to serve any purpose at all, really.
*
*/
@@ -519,18 +534,19 @@ shishi_kdc_check_nonce_1 (Shishi * handle,
/**
* shishi_kdc_check_nonce:
- * @handle: shishi handle as allocated by shishi_init().
- * @kdcreq: KDC-REQ to compare nonce field in.
- * @enckdcreppart: Encrypted KDC-REP part to compare nonce field in.
+ * @handle: Shishi handle as allocated by shishi_init().
+ * @kdcreq: Request of type KDC-REQ.
+ * @enckdcreppart: Encrypted KDC-REP part.
*
- * Verify that KDC-REQ.req-body.nonce and EncKDCRepPart.nonce fields
- * match. This is one of the steps that has to be performed when
- * processing a KDC-REQ and KDC-REP exchange.
+ * Verifies that @kdcreq.req-body.nonce and @enckdcreppart.nonce
+ * contain matching values. This is one of the steps that has to
+ * be performed when processing an exchange of KDC-REQ and KDC-REP.
*
- * Return value: Returns SHISHI_OK if successful,
- * SHISHI_NONCE_LENGTH_MISMATCH if the nonces have different lengths
- * (usually indicates that buggy server truncated nonce to 4 bytes),
- * SHISHI_NONCE_MISMATCH if the values differ, or an error code.
+ * Return value: Returns %SHISHI_OK if successful,
+ * %SHISHI_NONCE_MISMATCH whenever the nonces are of
+ * differing lengths (usually a sign that a buggy server
+ * truncates the nonce to 4 bytes) and the same code if the
+ * nonce values differ, or an error code otherwise.
**/
int
shishi_kdc_check_nonce (Shishi * handle,
@@ -571,20 +587,23 @@ shishi_kdc_check_nonce (Shishi * handle,
/**
* shishi_tgs_process:
- * @handle: shishi handle as allocated by shishi_init().
- * @tgsreq: input variable holding the transmitted KDC-REQ.
- * @tgsrep: input variable holding the received KDC-REP.
- * @authenticator: input variable with Authenticator from AP-REQ in KDC-REQ.
- * @oldenckdcreppart: input variable with EncKDCRepPart used in request.
- * @enckdcreppart: output variable holding the new EncKDCRepPart.
+ * @handle: Shishi handle as allocated by shishi_init().
+ * @tgsreq: Input variable holding the transmitted KDC-REQ.
+ * @tgsrep: Input variable holding the received KDC-REP.
+ * @authenticator: Input variable with an authenticator extracted
+ * from the AP-REQ part of @tgsreq.
+ * @oldenckdcreppart: Input variable with EncKDCRepPart used
+ * in the request.
+ * @enckdcreppart: Output variable holding the new EncKDCRepPart.
*
- * Process a TGS client exchange and output the decrypted EncKDCRepPart
- * which holds details for the received ticket. This function
- * simply derives the encryption key from the ticket used to construct
- * the TGS request, and then calls shishi_kdc_process().
+ * Processes a TGS client exchange and outputs the decrypted
+ * EncKDCRepPart, holding details about the received ticket.
+ * This function simply derives the encryption key from the
+ * ticket used to construct the original TGS request, and then
+ * calls shishi_kdc_process().
*
- * Return value: Returns SHISHI_OK iff the TGS client exchange was
- * successful.
+ * Return value: Returns %SHISHI_OK if the TGS client exchange
+ * was successful. Failures include ASN.1 and TGS conditions.
**/
int
shishi_tgs_process (Shishi * handle,
@@ -653,19 +672,19 @@ shishi_tgs_process (Shishi * handle,
/**
* shishi_as_process:
- * @handle: shishi handle as allocated by shishi_init().
- * @asreq: input variable holding the transmitted KDC-REQ.
- * @asrep: input variable holding the received KDC-REP.
- * @string: input variable with a null terminated password.
- * @enckdcreppart: output variable holding a new EncKDCRepPart.
+ * @handle: Shishi handle as allocated by shishi_init().
+ * @asreq: Input variable holding the transmitted KDC-REQ.
+ * @asrep: Input variable holding the received KDC-REP.
+ * @string: Input variable with a null terminated password.
+ * @enckdcreppart: Output variable returning a new EncKDCRepPart.
*
- * Process an AS client exchange and output the decrypted EncKDCRepPart
- * which holds details for the received ticket. This function
- * simply derives the encryption key from the password, and then calls
- * shishi_kdc_process().
+ * Processes an AS client exchange and returns the decrypted
+ * EncKDCRepPart, holding details about the received ticket.
+ * This function simply derives the encryption key from the
+ * password, and then calls shishi_kdc_process().
*
- * Return value: Returns SHISHI_OK iff the AS client exchange was
- * successful.
+ * Return value: Returns %SHISHI_OK if the AS client exchange was
+ * successful. Multiple failure conditions are possible.
**/
int
shishi_as_process (Shishi * handle,
@@ -704,28 +723,28 @@ shishi_as_process (Shishi * handle,
/**
* shishi_kdc_process:
- * @handle: shishi handle as allocated by shishi_init().
- * @kdcreq: input variable holding the transmitted KDC-REQ.
- * @kdcrep: input variable holding the received KDC-REP.
- * @key: input array with key for decrypting the encrypted part of KDC-REP.
- * @keyusage: kerberos key usage value.
- * @enckdcreppart: output variable holding the new EncKDCRepPart.
+ * @handle: Shishi handle as allocated by shishi_init().
+ * @kdcreq: Input variable holding the transmitted KDC-REQ.
+ * @kdcrep: Input variable holding the received KDC-REP.
+ * @key: Input pointet to key for decrypting parts of @kdcrep.
+ * @keyusage: Kerberos key usage code.
+ * @enckdcreppart: Output pointer for the extracted EncKDCRepPart.
*
- * Process a KDC client exchange and output the decrypted EncKDCRepPart,
- * which holds details for the received ticket. Use
- * shishi_kdcrep_get_ticket() to extract the ticket. This function
- * verifies the various conditions that must hold if the response is
- * to be considered valid. In particular it compares nonces
- * (shishi_kdc_check_nonce()), and if the exchange was an AS exchange,
- * it also checks cname and crealm (shishi_as_check_cname() and
- * shishi_as_check_crealm()).
+ * Processes a KDC client exchange and extracts a decrypted
+ * EncKDCRepPart, holding details about the received ticket.
+ * Use shishi_kdcrep_get_ticket() to extract the ticket itself.
+ * This function verifies the various conditions that must hold
+ * if the response is to be considered valid. In particular,
+ * it compares nonces (using shishi_kdc_check_nonce()), and if
+ * the exchange was an AS exchange, it also checks cname and
+ * crealm (using shishi_as_check_cname(), shishi_as_check_crealm()).
*
- * Usually the shishi_as_process() and shishi_tgs_process() functions
- * should be used instead, since they simplify the decryption key
- * computation.
+ * Usually shishi_as_process() and shishi_tgs_process() should be
+ * used instead of this call, since they simplify computation of
+ * the decryption key.
*
- * Return value: Returns SHISHI_OK iff the KDC client exchange was
- * successful.
+ * Return value: Returns %SHISHI_OK if the KDC client exchange was
+ * successful. Multiple failure conditions are possible.
**/
int
shishi_kdc_process (Shishi * handle,
diff --git a/lib/realm.c b/lib/realm.c
index 86f25c2..ee4775e 100644
--- a/lib/realm.c
+++ b/lib/realm.c
@@ -25,15 +25,24 @@
/**
* shishi_realm_default_guess:
*
- * Guesses a realm based on getdomainname() (which really is NIS/YP
- * domain, but if it is set it might be a good guess), or if it fails,
- * based on gethostname(), or if it fails, the string
- * "could-not-guess-default-realm". Note that the hostname is not
- * trimmed off of the data returned by gethostname() to get the domain
- * name and use that as the realm.
- *
- * Return value: Returns guessed realm for host as a string that has
- * to be deallocated with free() by the caller.
+ * Guesses a realm based on getdomainname(), which really responds
+ * with a NIS/YP domain, but if set properly, it might be a good
+ * first guess. If this NIS query fails, call gethostname(),
+ * and on its failure, fall back to returning the artificial
+ * string "could-not-guess-default-realm".
+ *
+ * Note that the hostname is not trimmed off of the string returned
+ * by gethostname(), thus pretending the local host name is a valid
+ * realm name. The resulting corner case could merit a check that
+ * the suggested realm is distinct from the fully qualifies host,
+ * and if not, simply strip the host name from the returned string
+ * before it is used in an application. One reason for sticking
+ * with the present behaviour, is that some systems respond with
+ * a non-qualified host name as reply from gethostname().
+ *
+ * Return value: Returns a guessed realm for the running host,
+ * containing a string that has to be deallocated with
+ * free() by the caller.
**/
char *
shishi_realm_default_guess (void)
@@ -59,12 +68,14 @@ shishi_realm_default_guess (void)
/**
* shishi_realm_default:
- * @handle: Shishi library handle create by shishi_init().
+ * @handle: Shishi library handle created by shishi_init().
*
- * Get name of default realm.
+ * Determines name of default realm, i.e., the name of whatever
+ * realm the library will use whenever an explicit realm is not
+ * stated during a library call.
*
- * Return value: Returns the default realm used in the library. (Not
- * a copy of it, so don't modify or deallocate it.)
+ * Return value: Returns the default realm in use by the library.
+ * Not a copy, so do not modify or deallocate the returned string.
**/
const char *
shishi_realm_default (Shishi * handle)
@@ -82,12 +93,15 @@ shishi_realm_default (Shishi * handle)
/**
* shishi_realm_default_set:
- * @handle: Shishi library handle create by shishi_init().
- * @realm: string with new default realm name, or NULL to reset to default.
+ * @handle: Shishi library handle created by shishi_init().
+ * @realm: String stating a new default realm name, or %NULL.
*
- * Set the default realm used in the library. The string is copied
- * into the library, so you can dispose of the variable immediately
- * after calling this function.
+ * Sets the default realm used by the library; or, with @realm
+ * set to %NULL, resets the library realm setting to that name
+ * selected by configuration for default value.
+ *
+ * The string is copied into the library, so you can dispose of
+ * the content in @realm immediately after calling this function.
**/
void
shishi_realm_default_set (Shishi * handle, const char *realm)
@@ -101,12 +115,13 @@ shishi_realm_default_set (Shishi * handle, const char
*realm)
/**
* shishi_realm_for_server_file:
- * @handle: Shishi library handle create by shishi_init().
- * @server: hostname to find realm for.
+ * @handle: Shishi library handle created by shishi_init().
+ * @server: Hostname to determine realm for.
*
- * Find realm for a host using configuration file.
+ * Finds the realm applicable to a host @server, using the
+ * standard configuration file.
*
- * Return value: Returns realm for host, or NULL if not found.
+ * Return value: Returns realm for host, or %NULL if not known.
**/
char *
shishi_realm_for_server_file (Shishi * handle, char *server)
@@ -145,35 +160,40 @@ shishi_realm_for_server_file (Shishi * handle, char
*server)
/**
* shishi_realm_for_server_dns:
- * @handle: Shishi library handle create by shishi_init().
- * @server: hostname to find realm for.
- *
- * Find realm for a host using DNS lookups, according to
- * draft-ietf-krb-wg-krb-dns-locate-03.txt. Since DNS lookups may be
- * spoofed, relying on the realm information may result in a
- * redirection attack. In a single-realm scenario, this only achieves
- * a denial of service, but with cross-realm trust it may redirect you
- * to a compromised realm. For this reason, Shishi prints a warning,
- * suggesting that the user should add the proper 'server-realm'
- * configuration tokens instead.
+ * @handle: Shishi library handle created by shishi_init().
+ * @server: Hostname to find realm for.
+ *
+ * Finds the realm for a host @server using DNS lookup, as is
+ * prescribed in "draft-ietf-krb-wg-krb-dns-locate-03.txt".
+ *
+ * Since DNS lookup can be spoofed, relying on the realm information
+ * may result in a redirection attack. In a single-realm scenario,
+ * this only achieves a denial of service, but with trust across
+ * multiple realms the attack may redirect you to a compromised realm.
+ * For this reason, Shishi prints a warning, suggesting that the user
+ * should instead add a proper 'server-realm' configuration token.
*
* To illustrate the DNS information used, here is an extract from a
* zone file for the domain ASDF.COM:
*
- * _kerberos.asdf.com. IN TXT "ASDF.COM"
- * _kerberos.mrkserver.asdf.com. IN TXT "MARKETING.ASDF.COM"
- * _kerberos.salesserver.asdf.com. IN TXT "SALES.ASDF.COM"
+ * _kerberos.asdf.com. IN TXT "ASDF.COM"
+ * _kerberos.mrkserver.asdf.com. IN TXT "MARKETING.ASDF.COM"
+ * _kerberos.salesserver.asdf.com. IN TXT "SALES.ASDF.COM"
*
* Let us suppose that in this case, a client wishes to use a service
- * on the host foo.asdf.com. It would first query:
+ * on the host "foo.asdf.com". It would first query for
+ *
+ * _kerberos.foo.asdf.com. IN TXT
*
- * _kerberos.foo.asdf.com. IN TXT
+ * Finding no match, it would then query for
*
- * Finding no match, it would then query:
+ * _kerberos.asdf.com. IN TXT
*
- * _kerberos.asdf.com. IN TXT
+ * With the resource records stated above, the latter query returns
+ * a positive answer.
*
- * Return value: Returns realm for host, or NULL if not found.
+ * Return value: Returns realm for the indicated host, or %NULL
+ * if no relevant TXT record could be found.
**/
char *
shishi_realm_for_server_dns (Shishi * handle, char *server)
@@ -211,15 +231,19 @@ shishi_realm_for_server_dns (Shishi * handle, char
*server)
/**
* shishi_realm_for_server:
- * @handle: Shishi library handle create by shishi_init().
- * @server: hostname to find realm for.
+ * @handle: Shishi library handle created by shishi_init().
+ * @server: Hostname to find realm for.
+ *
+ * Finds a realm for the host @server, using various methods.
*
- * Find realm for a host, using various methods. Currently this
- * includes static configuration files (see
- * shishi_realm_for_server_file()) and DNS (see
- * shishi_realm_for_server_dns()).
+ * Currently this includes static configuration files, using
+ * the library call shishi_realm_for_server_file(), and DNS
+ * lookup using shishi_realm_for_server_dns(). They are
+ * attempted in the stated order. See the documentation of
+ * either function for more information.
*
- * Return value: Returns realm for host, or NULL if not found.
+ * Return value: Returns realm for the indicated host, or %NULL
+ * if nothing is known about @server.
**/
char *
shishi_realm_for_server (Shishi * handle, char *server)
diff --git a/lib/resolv.c b/lib/resolv.c
index 615b2fc..88235b1 100644
--- a/lib/resolv.c
+++ b/lib/resolv.c
@@ -124,14 +124,18 @@ srv_compare (const void *a, const void *b)
/**
* shishi_resolv:
- * @zone: owner name of data, e.g. "EXAMPLE.ORG"
- * @querytype: type of data to query for, e.g., SHISHI_DNS_TXT.
+ * @zone: Domain name of authentication zone, e.g. "EXAMPLE.ORG"
+ * @querytype: Type of domain data to query for.
*
- * Query DNS resolver for data of type @querytype at owner name @zone.
- * Currently TXT and SRV types are supported.
+ * Queries the DNS resolver for data of type @querytype about
+ * the domain name @zone. Currently, the types %SHISHI_DNS_TXT
+ * and %SHISHI_DNS_SRV are the only supported kinds.
*
- * Return value: Returns linked list of DNS records, or NULL if query
- * failed.
+ * After its use, the returned list should be deallocated by
+ * a call to shishi_resolv_free().
+ *
+ * Return value: Returns a linked list of DNS resource records,
+ * or %NULL if the query failed.
**/
Shishi_dns
shishi_resolv (const char *zone, uint16_t querytype)
@@ -279,9 +283,10 @@ shishi_resolv (const char *zone, uint16_t querytype)
/**
* shishi_resolv_free:
- * @rrs: list of DNS RR as returned by shishi_resolv().
+ * @rrs: List of DNS RRs as returned by shishi_resolv().
*
- * Deallocate list of DNS RR as returned by shishi_resolv().
+ * Deallocates a list of DNS resource records returned by
+ * a call to shishi_resolv().
**/
void
shishi_resolv_free (Shishi_dns rrs)
hooks/post-receive
--
GNU shishi
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [SCM] GNU shishi branch, master, updated. shishi-1-0-2-49-gfb1c9d5,
Mats Erik Andersson <=