Re: OpenSSL wikibook
On 02/02/2013 03:46 AM, Bry8 Star wrote: It would be great to see a wiki site of OpenSSL, like: https://wiki.openssl.org/ Then helpful, experienced and knowledgeable users can contribute and help each-others. This is a good idea that has been proposed a number of times. It hasn't been acted on before due to limited spare cycles and competition for other needs like the server move and upgrade. Personally I also have some reservations, 1) I've never set up or managed a wiki before and 2) the presence of content officially hosted at wiki.openssl.org would imply endorsement by the OpenSSL team. Frankly there is some very misleading OpenSSL related documentation and commentary floating around the Internet, and the only thing worse than no documentation is bad documentation. I know my colleagues and I may not be able to give the wiki the attention it needs to always be completely current and accurate. But, that shouldn't be an excuse for doing nothing. So I propose to set up a wiki at the OSF web site, http://wiki.opensslfoundation.com/ as an initial attempt and experiment. If that turns out well we'll move it to wiki.openssl.org later. Based on some preliminary research and input we're looking at MediaWiki. Give us a few days to get that stood up and I'll make an announcement when we think it's more or less ready. -Steve M. -- Steve Marquess OpenSSL Software Foundation, Inc. 1829 Mount Ephraim Road Adamstown, MD 21710 USA +1 877 673 6775 s/b +1 301 874 2571 direct marqu...@opensslfoundation.com marqu...@openssl.com __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: OpenSSL wikibook
Hello Steve, Nice to hear about your proposal. Just a few comments about docs : As I said I think that the command line doc is not so bad, for example. I think that some docs will benefit from a wiki, other docs...not. For API docs I really think that it must come from the code, as in java API. What is missing presently in openssl API doc is function available since :, this page has been updated on date. And maybe, as in linux man pages, maintained by ... with a valid mail contact if some errors has to be reported in the doc. Many people are lacking HOW TO docs, which are more suitable for a wiki. For myself I was looking for command line use cases such as how to create a CSR, how to self sign a cert?, I want a cert for specific purposes signing mail/ signing java applets... how to do that., how to revoke a cert, how to check the validity of a cert or a collection of certs in a ca (to know what to renew), how to renew a cert... How to set up a quick ca (I checked the code of some apps and scripts and was not satisfied with the options offered). And for such an infinite set of question and answers, a wiki can be a good tool. But with a minimum of structuration in big chapters. For a programmer, the mailing list can help to find some returning topics that could be put in a wiki.: with some programming examples. What I mean is that I think the API and APPS can only be documented by the dev team, for their man pages. But the wiki could deal with specific use cases, HOWTO...and programming examples. Best regards, Pierre Le 04/02/2013 12:16, Steve Marquess a écrit : On 02/02/2013 03:46 AM, Bry8 Star wrote: It would be great to see a wiki site of OpenSSL, like: https://wiki.openssl.org/ Then helpful, experienced and knowledgeable users can contribute and help each-others. This is a good idea that has been proposed a number of times. It hasn't been acted on before due to limited spare cycles and competition for other needs like the server move and upgrade. Personally I also have some reservations, 1) I've never set up or managed a wiki before and 2) the presence of content officially hosted at wiki.openssl.org would imply endorsement by the OpenSSL team. Frankly there is some very misleading OpenSSL related documentation and commentary floating around the Internet, and the only thing worse than no documentation is bad documentation. I know my colleagues and I may not be able to give the wiki the attention it needs to always be completely current and accurate. But, that shouldn't be an excuse for doing nothing. So I propose to set up a wiki at the OSF web site, http://wiki.opensslfoundation.com/ as an initial attempt and experiment. If that turns out well we'll move it to wiki.openssl.org later. Based on some preliminary research and input we're looking at MediaWiki. Give us a few days to get that stood up and I'll make an announcement when we think it's more or less ready. -Steve M. __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: OpenSSL wikibook
It would be great to see a wiki site of OpenSSL, like: https://wiki.openssl.org/ Then helpful, experienced and knowledgeable users can contribute and help each-others. -- Bry8Star. Received from Patrick Pelletier, on 2013-02-02 5:29 AM: Since the quality of OpenSSL documentation, and the ease of contributing to it, has been a subject of discussion on both the openssl-users list and the cryptography list in the past few months, and since the only commercial book on OpenSSL is over a decade old now, I thought it would be worthwhile to start an OpenSSL wikibook: https://en.wikibooks.org/wiki/OpenSSL All I have in place right now is a skeleton of a table of contents, but I'm hoping that OpenSSL users will contribute to the book in their areas of expertise, or as they learn new things that they wish had been documented. --Patrick signature.asc Description: OpenPGP digital signature
Re: OpenSSL wikibook
Great idea! I hope many people will contribute! Cheers, Since the quality of OpenSSL documentation, and the ease of contributing to it, has been a subject of discussion on both the openssl-users list and the cryptography list in the past few months, and since the only commercial book on OpenSSL is over a decade old now, I thought it would be worthwhile to start an OpenSSL wikibook: https://en.wikibooks.org/wiki/OpenSSL All I have in place right now is a skeleton of a table of contents, but I'm hoping that OpenSSL users will contribute to the book in their areas of expertise, or as they learn new things that they wish had been documented. --Patrick __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: OpenSSL wikibook
When I suggested wiki myself, I received this answer... http://www.mail-archive.com/openssl-users@openssl.org/msg69232.html Anyway, the doc is not so bad : I use only openssl command line for some ca scripts of my own, and they are working...I learnt from the doc, and some doc in apache docs. But to improve it, at least we should know ...who is in charge of it,..and what is the present process of writing it. Could the doc be managed as the code, by a kind of cvs system ? Or synchronized with it by extracting comments ? something I dislike because documenting the code of something is not the same thing as documenting what this code is useful for (specs), nor how to use it (user's manual)..and the code is not at all the right place to put doc that overcome its purpose, and that should exist before the code is written... I guess that people have more problems with the lib doc: I do not use the lib, but I can suggest, for the online man pages, to add, to each command page, the last date of update, and the VERSIONS of openssl that are compatible with the doc. The java doc is a good example of what I have in mind. Pierre Le 02/02/2013 09:46, Bry8 Star a écrit : It would be great to see a wiki site of OpenSSL, like: https://wiki.openssl.org/ Then helpful, experienced and knowledgeable users can contribute and help each-others. -- Bry8Star. Received from Patrick Pelletier, on 2013-02-02 5:29 AM: Since the quality of OpenSSL documentation, and the ease of contributing to it, has been a subject of discussion on both the openssl-users list and the cryptography list in the past few months, and since the only commercial book on OpenSSL is over a decade old now, I thought it would be worthwhile to start an OpenSSL wikibook: https://en.wikibooks.org/wiki/OpenSSL All I have in place right now is a skeleton of a table of contents, but I'm hoping that OpenSSL users will contribute to the book in their areas of expertise, or as they learn new things that they wish had been documented. --Patrick __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: OpenSSL wikibook
I have previously submitted a largish patch for documentation around the OpenSSL EC library. Unfortunately there seems little interest in it, and it has been hanging around in RT for some while: https://rt.openssl.org/Ticket/Display.html?id=2799 (username guest, password guest) This documentation is in the POD format used by OpenSSL so isn't ideal for a direct conversion onto the wiki. However it seems a shame for it to be inaccessible so I've published it onto your wikibooks site anyway. See the following pages (and a number of pages linked from it): https://en.wikibooks.org/wiki/OpenSSL/EC I hope its useful to some people. Since this has not been accepted by the OpenSSL devs into the official distribution - use it at your own risk!! Matt On 2 February 2013 05:29, Patrick Pelletier c...@funwithsoftware.orgwrote: Since the quality of OpenSSL documentation, and the ease of contributing to it, has been a subject of discussion on both the openssl-users list and the cryptography list in the past few months, and since the only commercial book on OpenSSL is over a decade old now, I thought it would be worthwhile to start an OpenSSL wikibook: https://en.wikibooks.org/wiki/OpenSSL All I have in place right now is a skeleton of a table of contents, but I'm hoping that OpenSSL users will contribute to the book in their areas of expertise, or as they learn new things that they wish had been documented. --Patrick
Re: OpenSSL wikibook
I think a good wiki for OpenSSL would be great! I had some trouble getting non-blocking IO to work-- the details were all there, but spread across many pages. So I put together this, which lists how to handle various return codes for various non-blocking calls: http://jmarshall.com/wiki/bin/view/Main/HandlingNonBlockingIOErrorsInOpenSSL It could be simpler (e.g. you could handle most of it with on SSL_ERROR_WANT_READ/WRITE select on R/W and do same operation again) but I wanted a general structure to accommodate any outlying cases, plus something tabular that could be echoed in switch blocks. All comments welcome. I'd feel more comfortable if someone who knows better could verify it. Anything missing? If it's accurate, I'm happy to transfer it to Patrick's wiki. Cheers, James On Fri, Feb 1, 2013 at 9:29 PM, Patrick Pelletier c...@funwithsoftware.org wrote: Since the quality of OpenSSL documentation, and the ease of contributing to it, has been a subject of discussion on both the openssl-users list and the cryptography list in the past few months, and since the only commercial book on OpenSSL is over a decade old now, I thought it would be worthwhile to start an OpenSSL wikibook: https://en.wikibooks.org/wiki/OpenSSL All I have in place right now is a skeleton of a table of contents, but I'm hoping that OpenSSL users will contribute to the book in their areas of expertise, or as they learn new things that they wish had been documented. --Patrick __ OpenSSL Project http://www.openssl.org User Support Mailing Listopenssl-users@openssl.org Automated List Manager majord...@openssl.org
Re: OpenSSL wikibook
On Feb 2, 2013, at 2:46 AM, Matt Caswell wrote: I have previously submitted a largish patch for documentation around the OpenSSL EC library. Unfortunately there seems little interest in it, and it has been hanging around in RT for some while: https://rt.openssl.org/Ticket/Display.html?id=2799 (username guest, password guest) This documentation is in the POD format used by OpenSSL so isn't ideal for a direct conversion onto the wiki. However it seems a shame for it to be inaccessible so I've published it onto your wikibooks site anyway. I agree on both counts. Ideally, the actual API documentation should be maintained by the OpenSSL project, so it can be version-controlled along with the source, and the documentation can be installed as man pages. Ultimately, my vision for the OpenSSL wikibook is that it focus more on what would you use these functions for, and how would you use them together rather than these are the arguments and return values. Something that explains a bit more of the big picture and real-world usage. I see it more as a replacement for the out-of-date O'Reilly book, rather than a replacement for the OpenSSL manpages. However, at this point, I am very happy to have content of any sort in the wikibook, and I thank you for your contribution! I've reorganized the table of contents a bit, so that all of your pages are directly accessible from the table of contents. (Again, this man-page style format isn't quite what I'm looking for in the long term, but I'm quite happy to have it for now!) Thanks so much for contributing, --Patrick
OpenSSL wikibook
Since the quality of OpenSSL documentation, and the ease of contributing to it, has been a subject of discussion on both the openssl-users list and the cryptography list in the past few months, and since the only commercial book on OpenSSL is over a decade old now, I thought it would be worthwhile to start an OpenSSL wikibook: https://en.wikibooks.org/wiki/OpenSSL All I have in place right now is a skeleton of a table of contents, but I'm hoping that OpenSSL users will contribute to the book in their areas of expertise, or as they learn new things that they wish had been documented. --Patrick
