From: Nancy Gilman <nlgilman@mit.edu>
Date: Thu, 13 Jan 1994 01:53:28 +0000 (+0000)
Subject:  nlg- updated based on function prototypes
X-Git-Tag: krb5-1.0-beta3~57
X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=1b627b36caf3e1d5d7a7968c4008f56f2e82ae8e;p=krb5.git

 nlg- updated based on function prototypes
arguments should now be correct

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@3305 dc483132-0cff-0310-8789-dd5450dbe970
---

diff --git a/doc/api/ccache.tex b/doc/api/ccache.tex
index 83607af9b..983eb0d8b 100644
--- a/doc/api/ccache.tex
+++ b/doc/api/ccache.tex
@@ -20,7 +20,7 @@ Creates a credentials cache named by \funcparam{residual} (which may be
 interpreted differently by each type of ccache).  The cache is not
 opened, but the cache name is held in reserve.
 
-\begin{funcdecl}{krb5_cc_gennew_internal}{krb5_error_code}{\funcout}
+\begin{funcdecl}{krb5_cc_gen_new_internal}{krb5_error_code}{\funcout}
 \funcarg{krb5_ccache *}{id}
 \end{funcdecl}
 
@@ -59,16 +59,16 @@ Errors:  permission errors.
 \funcarg{krb5_ccache}{id}
 \end{funcdecl}
 
-Closes the credentials cache \funcparam{id}, invalidates \funcparam{id},
-and releases any other resources acquired during use of the credentials
-cache.  Requires that \funcparam{id} identifies a valid credentials
-cache.  After return, \funcparam{id} must not be used unless it is first
-reinitialized.
+Closes the credentials cache \funcparam{id}, invalidates
+\funcparam{id}, and releases \funcparam{id} and any other resources
+acquired during use of the credentials cache.  Requires that
+\funcparam{id} identifies a valid credentials cache.  After return,
+\funcparam{id} must not be used unless it is first reinitialized.
 
 
 \begin{funcdecl}{krb5_cc_store_cred}{krb5_error_code}{\funcin}
 \funcarg{krb5_ccache}{id}
-\funcarg{krb5_credentials *}{creds}
+\funcarg{krb5_creds *}{creds}
 \end{funcdecl}
 
 Stores \funcparam{creds} in the cache \funcparam{id}, tagged with
@@ -80,9 +80,9 @@ Errors: permission errors, storage failure errors.
 \begin{funcdecl}{krb5_cc_retrieve_cred}{krb5_error_code}{\funcin}
 \funcarg{krb5_ccache}{id}
 \funcarg{krb5_flags}{whichfields}
-\funcarg{krb5_credentials *}{mcreds}
+\funcarg{krb5_creds *}{mcreds}
 \funcout
-\funcarg{krb5_credentials *}{creds}
+\funcarg{krb5_creds *}{creds}
 \end{funcdecl}
 
 Searches the cache \funcparam{id} for credentials matching
@@ -92,7 +92,8 @@ name \funcparam{mcreds{\ptsto}server}.
 Requires that \funcparam{id} identifies a valid credentials cache.
 
 If at least one match is found, one of the matching credentials is
-returned in \funcparam{*creds}. XXX free the return creds?
+returned in \funcparam{*creds}. The credentials should be freed using
+\funcname{krb5_free_credentials}.
 
 Errors: error code if no matches found.
 
@@ -124,7 +125,7 @@ Requires that \funcparam{id} identifies a valid credentials cache opened by
 \begin{funcdecl}{krb5_cc_next_cred}{krb5_error_code}{\funcin}
 \funcarg{krb5_ccache}{id}
 \funcout
-\funcarg{krb5_credentials *}{creds}
+\funcarg{krb5_creds *}{creds}
 \funcinout
 \funcarg{krb5_cc_cursor *}{cursor}
 \end{funcdecl}
@@ -157,7 +158,7 @@ Errors: may return error code if \funcparam{*cursor} is invalid.
 \begin{funcdecl}{krb5_cc_remove_cred}{krb5_error_code}{\funcin}
 \funcarg{krb5_ccache}{id}
 \funcarg{krb5_flags}{which}
-\funcarg{krb5_credentials *}{cred}
+\funcarg{krb5_creds *}{cred}
 \end{funcdecl}
 
 Removes any credentials from \funcparam{id} which match the principal
diff --git a/doc/api/keytab.tex b/doc/api/keytab.tex
index 4a45295c5..a10e40fd4 100644
--- a/doc/api/keytab.tex
+++ b/doc/api/keytab.tex
@@ -120,7 +120,7 @@ Errors: error code if no more cache entries or if the keytab changes.
 
 \begin{funcdecl}{krb5_kt_end_seq_get}{krb5_error_code}{\funcin}
 \funcarg{krb5_keytab}{id}
-\funcarg{krb5_kt_cursor}{cursor}
+\funcarg{krb5_kt_cursor *}{cursor}
 \end{funcdecl}
 
 Finishes sequential processing mode and invalidates \funcparam{cursor},
@@ -179,7 +179,7 @@ yet known.
 An error is returned if \funcparam{ops{\ptsto}prefix} is already known.
 
 \begin{funcdecl}{krb5_kt_resolve}{krb5_error_code}{\funcin}
-\funcarg{char *}{string_name}
+\funcarg{const char *}{string_name}
 \funcout
 \funcarg{krb5_keytab *}{id}
 \end{funcdecl}
diff --git a/doc/implement/ccache-i.tex b/doc/implement/ccache-i.tex
index 83607af9b..983eb0d8b 100644
--- a/doc/implement/ccache-i.tex
+++ b/doc/implement/ccache-i.tex
@@ -20,7 +20,7 @@ Creates a credentials cache named by \funcparam{residual} (which may be
 interpreted differently by each type of ccache).  The cache is not
 opened, but the cache name is held in reserve.
 
-\begin{funcdecl}{krb5_cc_gennew_internal}{krb5_error_code}{\funcout}
+\begin{funcdecl}{krb5_cc_gen_new_internal}{krb5_error_code}{\funcout}
 \funcarg{krb5_ccache *}{id}
 \end{funcdecl}
 
@@ -59,16 +59,16 @@ Errors:  permission errors.
 \funcarg{krb5_ccache}{id}
 \end{funcdecl}
 
-Closes the credentials cache \funcparam{id}, invalidates \funcparam{id},
-and releases any other resources acquired during use of the credentials
-cache.  Requires that \funcparam{id} identifies a valid credentials
-cache.  After return, \funcparam{id} must not be used unless it is first
-reinitialized.
+Closes the credentials cache \funcparam{id}, invalidates
+\funcparam{id}, and releases \funcparam{id} and any other resources
+acquired during use of the credentials cache.  Requires that
+\funcparam{id} identifies a valid credentials cache.  After return,
+\funcparam{id} must not be used unless it is first reinitialized.
 
 
 \begin{funcdecl}{krb5_cc_store_cred}{krb5_error_code}{\funcin}
 \funcarg{krb5_ccache}{id}
-\funcarg{krb5_credentials *}{creds}
+\funcarg{krb5_creds *}{creds}
 \end{funcdecl}
 
 Stores \funcparam{creds} in the cache \funcparam{id}, tagged with
@@ -80,9 +80,9 @@ Errors: permission errors, storage failure errors.
 \begin{funcdecl}{krb5_cc_retrieve_cred}{krb5_error_code}{\funcin}
 \funcarg{krb5_ccache}{id}
 \funcarg{krb5_flags}{whichfields}
-\funcarg{krb5_credentials *}{mcreds}
+\funcarg{krb5_creds *}{mcreds}
 \funcout
-\funcarg{krb5_credentials *}{creds}
+\funcarg{krb5_creds *}{creds}
 \end{funcdecl}
 
 Searches the cache \funcparam{id} for credentials matching
@@ -92,7 +92,8 @@ name \funcparam{mcreds{\ptsto}server}.
 Requires that \funcparam{id} identifies a valid credentials cache.
 
 If at least one match is found, one of the matching credentials is
-returned in \funcparam{*creds}. XXX free the return creds?
+returned in \funcparam{*creds}. The credentials should be freed using
+\funcname{krb5_free_credentials}.
 
 Errors: error code if no matches found.
 
@@ -124,7 +125,7 @@ Requires that \funcparam{id} identifies a valid credentials cache opened by
 \begin{funcdecl}{krb5_cc_next_cred}{krb5_error_code}{\funcin}
 \funcarg{krb5_ccache}{id}
 \funcout
-\funcarg{krb5_credentials *}{creds}
+\funcarg{krb5_creds *}{creds}
 \funcinout
 \funcarg{krb5_cc_cursor *}{cursor}
 \end{funcdecl}
@@ -157,7 +158,7 @@ Errors: may return error code if \funcparam{*cursor} is invalid.
 \begin{funcdecl}{krb5_cc_remove_cred}{krb5_error_code}{\funcin}
 \funcarg{krb5_ccache}{id}
 \funcarg{krb5_flags}{which}
-\funcarg{krb5_credentials *}{cred}
+\funcarg{krb5_creds *}{cred}
 \end{funcdecl}
 
 Removes any credentials from \funcparam{id} which match the principal
diff --git a/doc/implement/encrypt-i.tex b/doc/implement/encrypt-i.tex
index 198c3224a..7a0e883e6 100644
--- a/doc/implement/encrypt-i.tex
+++ b/doc/implement/encrypt-i.tex
@@ -5,7 +5,7 @@ Kerberos v5 implementation must implement at least this interface:
 \subsection{Functional interface}
 
 \begin{funcdecl}{encrypt_func}{krb5_error_code}{\funcvoid}
-\funcarg{const krb5_pointer}{in}
+\funcarg{krb5_const_pointer}{in}
 \funcarg{krb5_pointer}{out}
 \funcarg{const size_t}{size}
 \funcarg{krb5_encrypt_block *}{eblock}
@@ -29,7 +29,7 @@ If null, the cryptosystem may choose an appropriate initialization vector.
 Returns errors.
 
 \begin{funcdecl}{decrypt_func}{krb5_error_code}{\funcvoid}
-\funcarg{const krb5_pointer}{in}
+\funcarg{krb5_const_pointer}{in}
 \funcarg{krb5_pointer}{out}
 \funcarg{const size_t}{size}
 \funcarg{krb5_encrypt_block *}{eblock}
@@ -53,7 +53,7 @@ Returns errors.
 
 \begin{funcdecl}{process_key}{krb5_error_code}{\funcvoid}
 \funcarg{krb5_encrypt_block *}{eblock}
-\funcarg{krb5_keyblock *}{keyblock}
+\funcarg{const krb5_keyblock *}{keyblock}
 \end{funcdecl}
 Does any necessary key preprocessing (such as computing key
 schedules for DES).
@@ -76,10 +76,10 @@ resources held by \funcparam{eblock{\ptsto}priv}.
 Returns errors.
 
 \begin{funcdecl}{string_to_key}{krb5_error_code}{\funcvoid}
-\funcarg{krb5_keytype}{keytype}
+\funcarg{const krb5_keytype}{keytype}
 \funcarg{krb5_keyblock *}{keyblock}
-\funcarg{krb5_data *}{data}
-\funcarg{krb5_principal}{princ}
+\funcarg{const krb5_data *}{data}
+\funcarg{const krb5_data}{salt}
 \end{funcdecl}
 Converts the string pointed to by \funcparam{data} into an encryption key
 of type \funcparam{keytype}.  \funcparam{*keyblock} is filled in with
@@ -87,7 +87,7 @@ the key info; in particular, \funcparam{keyblock{\ptsto}contents} is to
 be set to allocated storage. It is the responsibility of the caller to
 release this storage when the generated key no longer needed.
 
-The routine may use \funcparam{princ} to seed or alter the conversion
+The routine may use \funcparam{salt} to seed or alter the conversion
 algorithm.
 
 If the particular function called does not know how to make a
@@ -96,9 +96,10 @@ key of type \funcparam{keytype}, an error may be returned.
 Returns errors.
 
 \begin{funcdecl}{init_random_key}{krb5_error_code}{\funcvoid}
-\funcarg{krb5_keyblock *}{seedblock}
+\funcarg{const krb5_keyblock *}{seedblock}
 \funcarg{krb5_pointer *}{seed}
 \end{funcdecl}
+
 Initialize the random key generator using the encryption key
 \funcparam{seedblock} and allocating private sequence information, filling
 in \funcparam{*seed} with the address of such information.
@@ -106,15 +107,17 @@ in \funcparam{*seed} with the address of such information.
 sequence information.
 
 \begin{funcdecl}{finish_random_key}{krb5_error_code}{\funcvoid}
-\funcarg{krb5_pointer}{seed}
+\funcarg{krb5_pointer *}{seed}
 \end{funcdecl}
+
 Free any resources held by \funcparam{seed} and assigned by
 \funcname{init_random_key}. 
 
 \begin{funcdecl}{random_key}{krb5_error_code}{\funcvoid}
-\funcarg{krb5_pointer}{seed}
+\funcarg{krb5_pointer *}{seed}
 \funcarg{krb5_keyblock **}{keyblock}
 \end{funcdecl}
+
 Generate a random encryption key, allocating storage for it and
 filling in the keyblock address in \funcparam{*keyblock}.
 When the caller has finished using the keyblock, he should call
diff --git a/doc/implement/kdb-i.tex b/doc/implement/kdb-i.tex
index 443a7b744..fb9ac801e 100644
--- a/doc/implement/kdb-i.tex
+++ b/doc/implement/kdb-i.tex
@@ -147,7 +147,7 @@ Returns error code if not all entries were stored.
 
 Iterates over the database, fetching every entry in an unspecified order
 and calling \funcparam{(*func)}(\funcparam{iterate_arg},
-{\sl principal\/}) where {\sl principal\/} points to a record from the
+\funcparam{principal}) where \funcparam{principal} points to a record from the
 database.
 
 If \funcparam{(*func)}() ever returns an error code, the iteration is
@@ -168,6 +168,7 @@ principal name \funcparam{mname} is used.
 \funcarg{krb5_encrypt_block *}{eblock}
 \funcarg{krb5_boolean}{fromkeyboard}
 \funcarg{krb5_boolean}{twice}
+\funcarg{krb5_data }{salt}
 \funcinout
 \funcarg{krb5_keyblock *}{key}
 \end{funcdecl}
@@ -175,23 +176,30 @@ principal name \funcparam{mname} is used.
 Get the KDC database master key from somewhere, filling it into
 \funcparam{*key}. 
 \funcparam{key{\ptsto}keytype} should be set to the desired key type.
+
 If \funcparam{fromkeyboard} is TRUE, then the master key is read as a password
-from the user's terminal.  In this case,
+from the user's terminal.  In this case:
 \funcparam{eblock} should point to a block with an appropriate
-\funcname{string_to_key}  function.
-If \funcparam{twice} is TRUE, the password is read twice for verification.
+\funcname{string_to_key} function; if \funcparam{twice} is TRUE, the
+password is read twice for verification; and if \funcparam{salt} is
+non-NULL, it is used as the salt when converting the typed
+password to the master key.
+
 
 If \funcparam{fromkeyboard} is false, then the key is read from
 a file whose name is derived from the principal name \funcparam{mname}.
+Therefore, \funcparam{eblock}, \funcparam{twice} and \funcparam{salt}
+are ignored.
+
 
 \funcparam{mname} is the name of the key sought; this is often used by
 \funcname{string_to_key} to aid in conversion of the password to a key. 
 
 \begin{funcdecl}{krb5_kdb_encrypt_key}{krb5_error_code}{\funcin}
 \funcarg{krb5_encrypt_block *}{eblock}
-\funcarg{krb5_keyblock *}{in}
+\funcarg{const krb5_keyblock *}{in}
 \funcinout
-\funcarg{krb5_keyblock *}{out}
+\funcarg{krb5_encrypted_keyblock *}{out}
 \end{funcdecl}
 
 Encrypt a key for storage in the database.  \funcparam{eblock} is used
@@ -201,7 +209,7 @@ freed when the caller is finished with it.
 
 \begin{funcdecl}{krb5_kdb_decrypt_key}{krb5_error_code}{\funcin}
 \funcarg{krb5_encrypt_block *}{eblock}
-\funcarg{krb5_keyblock *}{in}
+\funcarg{const krb5_encrypted_keyblock *}{in}
 \funcinout
 \funcarg{krb5_keyblock *}{out}
 \end{funcdecl}
diff --git a/doc/implement/keytab-i.tex b/doc/implement/keytab-i.tex
index 4a45295c5..a10e40fd4 100644
--- a/doc/implement/keytab-i.tex
+++ b/doc/implement/keytab-i.tex
@@ -120,7 +120,7 @@ Errors: error code if no more cache entries or if the keytab changes.
 
 \begin{funcdecl}{krb5_kt_end_seq_get}{krb5_error_code}{\funcin}
 \funcarg{krb5_keytab}{id}
-\funcarg{krb5_kt_cursor}{cursor}
+\funcarg{krb5_kt_cursor *}{cursor}
 \end{funcdecl}
 
 Finishes sequential processing mode and invalidates \funcparam{cursor},
@@ -179,7 +179,7 @@ yet known.
 An error is returned if \funcparam{ops{\ptsto}prefix} is already known.
 
 \begin{funcdecl}{krb5_kt_resolve}{krb5_error_code}{\funcin}
-\funcarg{char *}{string_name}
+\funcarg{const char *}{string_name}
 \funcout
 \funcarg{krb5_keytab *}{id}
 \end{funcdecl}