From 1d238694e7b186d924e74f25d98068706095bc45 Mon Sep 17 00:00:00 2001 From: Jakub Jelen Date: Tue, 24 May 2022 09:41:31 +0200 Subject: [PATCH] Improve documentation by mentioning the free functions Related: https://gitlab.com/libssh/libssh-mirror/-/issues/3 Signed-off-by: Jakub Jelen Reviewed-by: Andreas Schneider --- src/channels.c | 3 +++ src/dh.c | 3 ++- src/misc.c | 27 +++++++++++++++++++------ src/options.c | 3 ++- src/pki.c | 39 ++++++++++++++++++++++--------------- src/pki_container_openssh.c | 2 +- src/session.c | 4 ++-- 7 files changed, 54 insertions(+), 27 deletions(-) diff --git a/src/channels.c b/src/channels.c index 5339adbc..f97e53ba 100644 --- a/src/channels.c +++ b/src/channels.c @@ -80,6 +80,9 @@ static ssh_channel channel_from_msg(ssh_session session, ssh_buffer packet); * @param[in] session The ssh session to use. * * @return A pointer to a newly allocated channel, NULL on error. + * The channel needs to be freed with ssh_channel_free(). + * + * @see ssh_channel_free() */ ssh_channel ssh_channel_new(ssh_session session) { diff --git a/src/dh.c b/src/dh.c index 2de85145..38a24b97 100644 --- a/src/dh.c +++ b/src/dh.c @@ -711,7 +711,8 @@ static char *ssh_get_b64_unpadded(const unsigned char *hash, size_t len) * * @param len Length of the buffer to convert. * - * @return Returns the allocated fingerprint hash or NULL on error. + * @return Returns the allocated fingerprint hash or NULL on error. The caller + * needs to free the memory using ssh_string_free_char(). * * @see ssh_string_free_char() */ diff --git a/src/misc.c b/src/misc.c index b945a279..0d455df2 100644 --- a/src/misc.c +++ b/src/misc.c @@ -834,7 +834,7 @@ const void *_ssh_list_pop_head(struct ssh_list *list){ * dirname breaks a null-terminated pathname string into a directory component. * In the usual case, ssh_dirname() returns the string up to, but not including, * the final '/'. Trailing '/' characters are not counted as part of the - * pathname. The caller must free the memory. + * pathname. The caller must free the memory using ssh_string_free_char(). * * @param[in] path The path to parse. * @@ -842,7 +842,10 @@ const void *_ssh_list_pop_head(struct ssh_list *list){ * If path does not contain a slash, c_dirname() returns * the string ".". If path is a string "/", it returns * the string "/". If path is NULL or an empty string, - * "." is returned. + * "." is returned. The memory needs to be freed using + * ssh_string_free_char(). + * + * @see ssh_string_free_char() */ char *ssh_dirname (const char *path) { char *new = NULL; @@ -897,7 +900,10 @@ char *ssh_dirname (const char *path) { * @return The filename of path or NULL if we can't allocate * memory. If path is the string "/", basename returns * the string "/". If path is NULL or an empty string, - * "." is returned. + * "." is returned. The caller needs to free this memory + * ssh_string_free_char(). + * + * @see ssh_string_free_char() */ char *ssh_basename (const char *path) { char *new = NULL; @@ -1032,7 +1038,10 @@ int ssh_mkdirs(const char *pathname, mode_t mode) * * @param[in] d The directory to expand. * - * @return The expanded directory, NULL on error. + * @return The expanded directory, NULL on error. The caller + * needs to free the memory using ssh_string_free_char(). + * + * @see ssh_string_free_char() */ char *ssh_path_expand_tilde(const char *d) { char *h = NULL, *r; @@ -1101,7 +1110,10 @@ char *ssh_path_expand_tilde(const char *d) { * %l local hostname * %r remote username * %p remote port - * @returns Expanded string. + * @returns Expanded string. The caller needs to free the memory using + * ssh_string_free_char(). + * + * @see ssh_string_free_char() */ char *ssh_path_expand_escape(ssh_session session, const char *s) { char host[NI_MAXHOST] = {0}; @@ -1844,7 +1856,10 @@ err: * @param[in] replace String to be replaced is stored in replace. * * @returns src_replaced a pointer that points to the replaced string. - * NULL if allocation fails or if src is NULL. + * NULL if allocation fails or if src is NULL. The returned memory needs to be + * freed using ssh_string_free_char(). + * + * @see ssh_string_free_char() */ char *ssh_strreplace(const char *src, const char *pattern, const char *replace) { diff --git a/src/options.c b/src/options.c index 9e09703c..e6bd920b 100644 --- a/src/options.c +++ b/src/options.c @@ -57,11 +57,12 @@ * @param src The session to use to copy the options. * * @param dest A pointer to store the allocated session with duplicated - * options. You have to free the memory. + * options. You have to free the memory using ssh_free() * * @returns 0 on success, -1 on error with errno set. * * @see ssh_session_connect() + * @see ssh_free() */ int ssh_options_copy(ssh_session src, ssh_session *dest) { diff --git a/src/pki.c b/src/pki.c index 3b58921e..9f1b392d 100644 --- a/src/pki.c +++ b/src/pki.c @@ -811,7 +811,7 @@ void ssh_signature_free(ssh_signature sig) * @param[in] auth_data Private data passed to the auth function. * * @param[out] pkey A pointer where the allocated key can be stored. You - * need to free the memory. + * need to free the memory using ssh_key_free() * * @return SSH_ERROR in case of error, SSH_OK otherwise. * @@ -874,9 +874,11 @@ int ssh_pki_import_privkey_base64(const char *b64_key, * @param[in] auth_data Private data passed to the auth function. * * @param[out] b64_key A pointer to store the allocated base64 encoded key. You - * need to free the buffer. + * need to free the buffer using ssh_string_from_char(). * * @return SSH_OK on success, SSH_ERROR on error. + * + * @see ssh_string_free_char() */ int ssh_pki_export_privkey_base64(const ssh_key privkey, const char *passphrase, @@ -931,7 +933,7 @@ int ssh_pki_export_privkey_base64(const ssh_key privkey, * @param[in] auth_data Private data passed to the auth function. * * @param[out] pkey A pointer to store the allocated ssh_key. You need to - * free the key. + * free the key using ssh_key_free(). * * @returns SSH_OK on success, SSH_EOF if the file doesn't exist or permission * denied, SSH_ERROR otherwise. @@ -1600,7 +1602,7 @@ fail: * @param[in] type The type of the key to format. * * @param[out] pkey A pointer where the allocated key can be stored. You - * need to free the memory. + * need to free the memory using ssh_key_free(). * * @return SSH_OK on success, SSH_ERROR on error. * @@ -1648,7 +1650,7 @@ int ssh_pki_import_pubkey_base64(const char *b64_key, * 6.6 "Public Key Algorithms". * * @param[out] pkey A pointer where the allocated key can be stored. You - * need to free the memory. + * need to free the memory using ssh_key_free(). * * @return SSH_OK on success, SSH_ERROR on error. * @@ -1735,7 +1737,10 @@ bool ssh_pki_is_uri(const char *cmp) * * @param[in] priv_uri Private PKCS #11 URI. * - * @returns pointer to the public PKCS #11 URI + * @returns pointer to the public PKCS #11 URI. You need to free + * the memory using ssh_string_free_char(). + * + * @see ssh_string_free_char(). */ char *ssh_pki_export_pub_uri_from_priv_uri(const char *priv_uri) { @@ -1755,7 +1760,7 @@ char *ssh_pki_export_pub_uri_from_priv_uri(const char *priv_uri) * PKCS #11 URI corresponding to the public key. * * @param[out] pkey A pointer to store the allocated public key. You need to - * free the memory. + * free the memory using ssh_key_free(). * * @returns SSH_OK on success, SSH_EOF if the file doesn't exist or permission * denied, SSH_ERROR otherwise. @@ -1878,7 +1883,7 @@ int ssh_pki_import_pubkey_file(const char *filename, ssh_key *pkey) * @param[in] type The type of the cert to format. * * @param[out] pkey A pointer where the allocated key can be stored. You - * need to free the memory. + * need to free the memory using ssh_key_free(). * * @return SSH_OK on success, SSH_ERROR on error. * @@ -1899,7 +1904,7 @@ int ssh_pki_import_cert_base64(const char *b64_cert, * 6.6 "Public Key Algorithms". * * @param[out] pkey A pointer where the allocated key can be stored. You - * need to free the memory. + * need to free the memory using ssh_key_free(). * * @return SSH_OK on success, SSH_ERROR on error. * @@ -1916,7 +1921,7 @@ int ssh_pki_import_cert_blob(const ssh_string cert_blob, * @param[in] filename The path to the certificate. * * @param[out] pkey A pointer to store the allocated certificate. You need to - * free the memory. + * free the memory using ssh_key_free(). * * @returns SSH_OK on success, SSH_EOF if the file doesn't exist or permission * denied, SSH_ERROR otherwise. @@ -1937,11 +1942,13 @@ int ssh_pki_import_cert_file(const char *filename, ssh_key *pkey) * rsa : length of the key in bits (e.g. 1024, 2048, 4096) * dsa : length of the key in bits (e.g. 1024, 2048, 3072) * @param[out] pkey A pointer to store the allocated private key. You need - * to free the memory. + * to free the memory using ssh_key_free(). * * @return SSH_OK on success, SSH_ERROR on error. * * @warning Generating a key pair may take some time. + * + * @see ssh_key_free() */ int ssh_pki_generate(enum ssh_keytypes_e type, int parameter, ssh_key *pkey){ @@ -2031,7 +2038,7 @@ error: * @param[in] privkey The private key to get the public key from. * * @param[out] pkey A pointer to store the newly allocated public key. You - * NEED to free the key. + * NEED to free the key using ssh_key_free(). * * @return SSH_OK on success, SSH_ERROR on error. * @@ -2069,11 +2076,11 @@ int ssh_pki_export_privkey_to_pubkey(const ssh_key privkey, * from. * * @param[out] pblob A pointer to store the newly allocated key blob. You - * NEED to free it. + * need to free it using ssh_string_free(). * * @return SSH_OK on success, SSH_ERROR otherwise. * - * @see SSH_STRING_FREE() + * @see ssh_string_free() */ int ssh_pki_export_pubkey_blob(const ssh_key key, ssh_string *pblob) @@ -2099,11 +2106,11 @@ int ssh_pki_export_pubkey_blob(const ssh_key key, * @param[in] key The key to hash * * @param[out] b64_key A pointer to store the allocated base64 encoded key. You - * need to free the buffer. + * need to free the buffer using ssh_string_free_char() * * @return SSH_OK on success, SSH_ERROR on error. * - * @see SSH_STRING_FREE_CHAR() + * @see ssh_string_free_char() */ int ssh_pki_export_pubkey_base64(const ssh_key key, char **b64_key) diff --git a/src/pki_container_openssh.c b/src/pki_container_openssh.c index ecde4cdd..cc97da7f 100644 --- a/src/pki_container_openssh.c +++ b/src/pki_container_openssh.c @@ -49,7 +49,7 @@ * code. * * @param[out] pkey A pointer where the allocated key can be stored. You - * need to free the memory. + * need to free the memory using ssh_key_free(). * * @return SSH_OK on success, SSH_ERROR on error. * diff --git a/src/session.c b/src/session.c index bb007e59..9b6248b7 100644 --- a/src/session.c +++ b/src/session.c @@ -1057,7 +1057,7 @@ void ssh_clean_pubkey_hash(unsigned char **hash) { * @param[in] session The session to get the key from. * * @param[out] key A pointer to store the allocated key. You need to free - * the key. + * the key using ssh_key_free(). * * @return SSH_OK on success, SSH_ERROR on errror. * @@ -1101,7 +1101,7 @@ int ssh_get_publickey(ssh_session session, ssh_key *key) * * @param[in] type The type of the hash you want. * - * @param[in] hash A pointer to store the allocated buffer. It can be + * @param[out] hash A pointer to store the allocated buffer. It can be * freed using ssh_clean_pubkey_hash(). * * @param[in] hlen The length of the hash.