Module: kamailio
Branch: master
Commit: 0befd685ffda86a97ee639264b9e7fba7f8ab6c5
URL: https://github.com/kamailio/kamailio/commit/0befd685ffda86a97ee639264b9e7fb…
Author: Daniel-Constantin Mierla <miconda(a)gmail.com>
Committer: Daniel-Constantin Mierla <miconda(a)gmail.com>
Date: 2016-05-12T15:02:58+02:00
core: contribuitions guidelines updated with reporting issues section
---
Modified: .github/CONTRIBUTING.md
---
Diff: https://github.com/kamailio/kamailio/commit/0befd685ffda86a97ee639264b9e7fb…
Patch: https://github.com/kamailio/kamailio/commit/0befd685ffda86a97ee639264b9e7fb…
---
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index fd4d022..1b23d8c 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -12,10 +12,12 @@ changes to this document in a pull request.
### Table Of Contents ###
* [Overview](#overview)
- * [Basic Rules](#basic-rules)
- * [Commit Message Format](#commit-message-format)
- * [Examples Of Commit Messages](#examples-of-commit-messages)
- * [See Also](#see-also)
+ * [Contributing Code Or Content](#contributing-code-or-content)
+ * [Basic Rules](#basic-rules)
+ * [Commit Message Format](#commit-message-format)
+ * [Examples Of Commit Messages](#examples-of-commit-messages)
+ * [See Also](#see-also)
+ * [Reporting Issues](#reporting-issues)
* [License](#license)
* [License Of New Code Contributions](#license-of-new-code-contributions)
* [Further Assistance](#further-assistance)
@@ -28,7 +30,8 @@ contribution to code or documentation is very welcome and appreciated.
In order to be easily able to track the changes and have a coherent ChangLog
and commit history, there are several *rules* required for each contribution.
-## Basic Rules ##
+## Contributing Code Or Content ##
+### Basic Rules ###
* github pull requests are the favourited mechanism to submit contributions
(patches)
@@ -72,7 +75,7 @@ and commit history, there are several *rules* required for each contribution.
regenerated in the corresponding branch.
-## Commit Message Format ##
+### Commit Message Format ###
Please create the commit messages following the GIT convention:
@@ -93,7 +96,7 @@ Please start always with the prefix of the component (subsystem) that is modifie
* lib_name: critical bug fix for abc case
* kamctl: added support for management of module xyz
-### Examples Of Commit Messages ###
+#### Examples Of Commit Messages ####
* change to usrloc module from modules
@@ -116,7 +119,7 @@ core: loadpath can now use a list of directories
be loaded and the search will stop).
```
-### See Also ###
+#### See Also ####
* [Creating Good Commit Messages](http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#…
* http://www.tpope.net/node/106
@@ -125,6 +128,28 @@ The above content about commit message format is taken from Kamailio wiki page:
* https://www.kamailio.org/wiki/devel/git-commit-guidelines
* it is recommended you read that one as well.
+## Reporting Issues ##
+
+Whenever reporting an issue, along with the description of the problems, try to
+include following details:
+
+ * kamailio version you are using
+ * the output of: **kamailio -v**
+ * the operating system being used
+ * the CPU architecture
+
+Always useful to have:
+
+ * whenever there is a crash with a corefile, send the backtrace
+ * the output of **bt full** in **gbd**
+ * log messages printed by kamailio in syslog file
+ * *pcap* or *ngrep* capture of SIP packets causing the issue
+ * config file snippets which expose the issues
+
+Note: replace any sensitive information in the content you add to the issue
+(e.g., passwords in modparams can be replaced with xyz, each IP address can be
+replaced with tokens like a.b.c.d, f.g.h.j).
+
## License ##
Kamailio Main License: *GPLv2*.
Hello,
We would like to adapt the "auth" module to allow digest authentication that uses a different hashing algorithm (SHA-256 instead of MD5). We use the auth module together with the "auth_db" module.
I identified the following changes that would be required for this feature:
1. The field algorithm=SHA-256 must be present in the "WWW-Authenticate" and "Proxy-Authenticate" headers to indicate the custom algorithm
e.g. WWW-Authenticate: Digest realm="realm.test", nonce="VzMh7lczIMKzhKh2gFjSnAnufvKupxx0B3JSSoA=", qop="auth", algorithm=SHA-256
2. The rfc2617.h/c files must be duplicated and adapted to use SHA-256
3. A SHA-256 hash value is twice as long as a MD5 hash value. So we must make sure that large enough char arrays are allocated to hold hash values.
It looks like this is no problem for the auth_* modules because they use char[256] for the ha1 hash values. The HASHHEX which is char[33] seems only to be used inside the auth module itself.
I thought of some possible solutions and we would like to get a feedback if any of these could make it into the official kamailio version and which one you would prefer:
Solution A: Add SHA-256 capabilities to module "auth" :
Add a module parameter "algorithm" that allows configuring "SHA-256" instead of "MD5" (which would be the default value).
Add SHA-256 versions for the functions calc_HA1 and calc_response (similar to rfc2617.c/h) and add two function pointers that can either point to the MD5 or SHA256 implementations, depending on the config.
Use the function pointers in the functions auth_s, auth_check_response and pv_authenticate where calc_HA1 or calc_response are used.
In the function auth_check_response replace HASHHEX allocated on the stack by char[65] or char[256] and compare the length of the credentials provided by the client dynamically depending on the config (32 for MD5, 64 for SHA-256).
Provide the configured algorithm to the two calls to get_challenge_hf to build the challenge header field with the desired algorithm.
Solution B: Add a new module "auth_sha256" that 'extends' the module "auth"
The idea of this solution is to put any sha256 specific code in a separate module while reusing most of the other code from the auth module.
As in solution A, the auth module would use some function pointers for the calc_HA1 and calc_response functions.
But instead of a configuration value, these function pointers could be initialized in mod_init depending whether the auth_sha256 module is available or not. (e.g. the module auth could call a function in the module auth_sha256 similar to bind_auth_s to replace parts of its own api by SHA-256 specific functions.)
Solution C: Add a new module "auth_sha256" that is a duplicate of the module "auth", adapted for SHA-256
With this solution, no existing modules have to be modified, but more code has to be duplicated and maintained separately.
Kind regards,
Andreas Huber
Friends,
I have developed an allergy. It causes all kinds of weird behaviour.
We have a lot of functions that are documented in README’s that have no documentation of the return codes,
even though they do exist in the source code. Sometimes you can see that the developer added an example
of an if() statement - proving that there is a return code, but the text doesn’t mention it.
If you write new functions in *any* module please document error codes in the README.
If you have written or understand from the source code that there are return codes around, please add them to
the README.
If you find functions that have no documentation on return codes and you can’t figure it out, file a bug report.
Documentation fixes can go both in master and in 4.4.
If you clean up return codes and modify the source - this needs to go only in master. I just did for the “unregister” function in
REGISTRAR - there was a mixup of return codes where the same value actually had different meanings,
which was hard to document.
Thank you!
/O