Improving Developer Documentation

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

Improving Developer Documentation

Casey Dunham
Greetings,

I have just subscribed and hopefully I am not breaking any list etiquette here, but I wanted to respond to the thread that was started back in April on Improving the Documentation for OpenSSL.


I am a developer (BS CS, Minor in Math) but not up to speed with the OpenSSL library and more to my immediate interests, the cryptographic library that is part of OpenSSL.

I am looking at using it in an upcoming project, but I definitely need to learn more about crypto. 

However, getting started with OpenSSL from reading the main project page at openssl.org and the wiki leaves a bit to be desired. The wiki was very useful however as it was the only place I could find usage examples ;)

It took me a while to get started with a simple example and just getting an overview of the API is not easy (yes the source code which I am using).

I also noticed that some of the code examples need to be updated.

So I think that there are really three different areas of documentation that would be useful:

- User documentation for the command line applications
- Developer documentation for the OpenSSL / Crypto APIs
- Up to date code examples for the usage of the APIs

Having a single online resource for this would be great (unless I am completely missing a resource here).

My main incentive is to provide a resource that developers could use to get started with the API quickly while also providing inline best practices and good coding examples. 

I have sent an email requesting access to the wiki and am interested in helping out where I can.

Sorry for the long message!

Regards,
Casey
Reply | Threaded
Open this post in threaded view
|

RE: Improving Developer Documentation

david.lloyd

There is a vast quantity of OpenSSL information on the Internet.  There's even an O'Reilly book:  http://www.amazon.co.uk/Network-Security-OpenSSL-Cryptography-Communications/dp/059600270X

This looks like a good one to start with:
http://www.rtfm.com/openssl-examples/part1.pdf

Whether they could all be better linked from the OpenSSL wiki is a different question of course :)

Good luck!


> Message Received: Nov 14 2014, 01:58 AM
> From: "Casey Dunham" <[hidden email]>
> To: [hidden email]
> Cc:
> Subject: Improving Developer Documentation
>
> Greetings,
>
> I have just subscribed and hopefully I am not breaking any list etiquette
> here, but I wanted to respond to the thread that was started back in April
> on Improving the Documentation for OpenSSL.
>
> http://marc.info/?l=openssl-dev&m=139832883828644
>
> I am a developer (BS CS, Minor in Math) but not up to speed with the
> OpenSSL library and more to my immediate interests, the cryptographic
> library that is part of OpenSSL.
>
> I am looking at using it in an upcoming project, but I definitely need to
> learn more about crypto.
>
> However, getting started with OpenSSL from reading the main project page at
> openssl.org and the wiki leaves a bit to be desired. The wiki was very
> useful however as it was the only place I could find usage examples ;)
>
> It took me a while to get started with a simple example and just getting an
> overview of the API is not easy (yes the source code which I am using).
>
> I also noticed that some of the code examples need to be updated.
>
> So I think that there are really three different areas of documentation
> that would be useful:
>
> - User documentation for the command line applications
> - Developer documentation for the OpenSSL / Crypto APIs
> - Up to date code examples for the usage of the APIs
>
> Having a single online resource for this would be great (unless I am
> completely missing a resource here).
>
> My main incentive is to provide a resource that developers could use to get
> started with the API quickly while also providing inline best practices and
> good coding examples.
>
> I have sent an email requesting access to the wiki and am interested in
> helping out where I can.
>
> Sorry for the long message!
>
> Regards,
> Casey
>
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

RE: Improving Developer Documentation

bushsf

I would applaud the effort to create better (and more tutorial-style) documentation.

 

It would also be great to bring the documentation and examples up to date.

 

Description: cid:image001.jpg@01CFFF4A.CA221DD0

 

 

-----Original Message-----
From: [hidden email] [mailto:[hidden email]] On Behalf Of [hidden email]
Sent: Friday, November 14, 2014 8:03 AM
To: [hidden email]; [hidden email]
Subject: RE: Improving Developer Documentation

 

 

There is a vast quantity of OpenSSL information on the Internet.  There's even an O'Reilly book:  http://www.amazon.co.uk/Network-Security-OpenSSL-Cryptography-Communications/dp/059600270X

 

This looks like a good one to start with:

http://www.rtfm.com/openssl-examples/part1.pdf

 

Whether they could all be better linked from the OpenSSL wiki is a different question of course :)

 

Good luck!

 

 

> Message Received: Nov 14 2014, 01:58 AM

> From: "Casey Dunham" <[hidden email]>

> To: [hidden email]

> Cc:

> Subject: Improving Developer Documentation

>

> Greetings,

>

> I have just subscribed and hopefully I am not breaking any list

> etiquette here, but I wanted to respond to the thread that was started

> back in April on Improving the Documentation for OpenSSL.

>

> http://marc.info/?l=openssl-dev&m=139832883828644

>

> I am a developer (BS CS, Minor in Math) but not up to speed with the

> OpenSSL library and more to my immediate interests, the cryptographic

> library that is part of OpenSSL.

>

> I am looking at using it in an upcoming project, but I definitely need

> to learn more about crypto.

>

> However, getting started with OpenSSL from reading the main project

> page at openssl.org and the wiki leaves a bit to be desired. The wiki

> was very useful however as it was the only place I could find usage

> examples ;)

>

> It took me a while to get started with a simple example and just

> getting an overview of the API is not easy (yes the source code which I am using).

>

> I also noticed that some of the code examples need to be updated.

>

> So I think that there are really three different areas of

> documentation that would be useful:

>

> - User documentation for the command line applications

> - Developer documentation for the OpenSSL / Crypto APIs

> - Up to date code examples for the usage of the APIs

>

> Having a single online resource for this would be great (unless I am

> completely missing a resource here).

>

> My main incentive is to provide a resource that developers could use

> to get started with the API quickly while also providing inline best

> practices and good coding examples.

>

> I have sent an email requesting access to the wiki and am interested

> in helping out where I can.

>

> Sorry for the long message!

>

> Regards,

> Casey

>

______________________________________________________________________

OpenSSL Project                                 http://www.openssl.org

Development Mailing List                       [hidden email]

Automated List Manager                           [hidden email]


Stephen F Bush.vcf (6K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

RE: Improving Developer Documentation

Krzysztof Kwiatkowski-2
In reply to this post by david.lloyd
> http://www.amazon.co.uk/Network-Security-OpenSSL-Cryptography-Communications/dp/059600270X

I've found basics and even more advanced topics in this book, but please
notice that it is more than 10 years old, so doesn't cover new stuff and
I've found some information outdated. Still - good book.
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Improving Developer Documentation

Casey Dunham
In looking for documentation regarding OpenSSL all I have found have been outdated examples. Even the rtfm link is unmaintained and has not been updated since 2002, according to this: http://www.rtfm.com/openssl-examples/

I think it would be great to link to these from a single source on the wiki. I am still going through the wiki and not sure if a page for this already exists. Perhaps I can make that a task to work on is getting all resources into a single place.

C


On Fri Nov 14 2014 at 9:05:46 AM Krzysztof Kwiatkowski <[hidden email]> wrote:
> http://www.amazon.co.uk/Network-Security-OpenSSL-Cryptography-Communications/dp/059600270X

I've found basics and even more advanced topics in this book, but please
notice that it is more than 10 years old, so doesn't cover new stuff and
I've found some information outdated. Still - good book.
Reply | Threaded
Open this post in threaded view
|

Re: Improving Developer Documentation

david.lloyd
In reply to this post by Casey Dunham


OpenSSL APIs haven't changed much in 10 years :)


> In looking for documentation regarding OpenSSL all I have found have been
> outdated examples. Even the rtfm link is unmaintained and has not been
> updated since 2002, according to this: http://www.rtfm.com/openssl-examples/

______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

RE: Improving Developer Documentation

bushsf
Pre-Shared Keys might be one example of something that is hard to find in any documented example.

Steve

-----Original Message-----
From: [hidden email] [mailto:[hidden email]] On Behalf Of [hidden email]
Sent: Friday, November 14, 2014 4:16 PM
To: [hidden email]; Krzysztof Kwiatkowski; [hidden email]
Cc: [hidden email]
Subject: Re: Improving Developer Documentation



OpenSSL APIs haven't changed much in 10 years :)


> In looking for documentation regarding OpenSSL all I have found have
> been outdated examples. Even the rtfm link is unmaintained and has not
> been updated since 2002, according to this:
> http://www.rtfm.com/openssl-examples/

______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
:��I"Ϯ��r�m���� (���Z+�7�zZ)���1���x ��h���W^��^��%����&jם.+-1�ځ��j:+v�������h�
Reply | Threaded
Open this post in threaded view
|

Re: Improving Developer Documentation

Krzysztof Kwiatkowski-2
SRP is another

On Fri, 2014-11-14 at 22:42 +0000, Bush, Stephen F (GE Global Research)
wrote:

> Pre-Shared Keys might be one example of something that is hard to find in any documented example.
>
> Steve
>
> -----Original Message-----
> From: [hidden email] [mailto:[hidden email]] On Behalf Of [hidden email]
> Sent: Friday, November 14, 2014 4:16 PM
> To: [hidden email]; Krzysztof Kwiatkowski; [hidden email]
> Cc: [hidden email]
> Subject: Re: Improving Developer Documentation
>
>
>
> OpenSSL APIs haven't changed much in 10 years :)
>
>
> > In looking for documentation regarding OpenSSL all I have found have
> > been outdated examples. Even the rtfm link is unmaintained and has not
> > been updated since 2002, according to this:
> > http://www.rtfm.com/openssl-examples/
>
> ______________________________________________________________________
> OpenSSL Project                                 http://www.openssl.org
> Development Mailing List                       [hidden email]
> Automated List Manager                           [hidden email]
> Ensڶj!(7yy' yǢ_yl܅-ze5]}yo'ǫ[zzvǮ+a<I"/Mxn7ӝ4A'hh'睲CzXzjׅ-x6^6ۍ4D^qyiV-Y^y'ze+aƧD)קhfj!('u^+M4$;1+'睲E-x6^6ۍ4Eҥ$z^Ȩ*Z,j"}Mt}zxh5睲wUҥz]*Z+Z
> (6ַ*tt-
> <+J0H<%ylP ޮ^%uZ+'z)z{,ׯhn7)
 <ޖ^:gbtNbp
> z{Kjx.jD1!ڰmiW1$Pj+Ɗ)ڶ)ݵ_w
> z{Sʗ{VZǭ_*'Nw(v)m0E^Ȩ]>(~"bz"{ޝ+rzx"6Mt}~MM4G^~)*'
 <׍uם5Mx]yMx]x]5('j۫z4\h{Rz֢')jjh'2ןjm+x
> ,rK.(4(4iۥ(4nd+x
> ,)jf-Jj'iqƧr
> ^x^4n4Myب&j)]uM{AɔMɕ-́ЁᅵͽѡѡЁ́ɐѼ䁑յѕᅵ4(4)Mѕٔ4(4(=ɥ5ͅ4)ɽ聽ݹȵͰͰɜmѼݹȵͰͰɝt= =٥͵4)Mɥ䰁9ٕȀаЀ؁A44)Q聽ͰͰɜ-ѽ-ݥѭͭ쁽ͰͰɜ4)
> 聽ݹȵͰͰɜ4)MՉI%ɽ٥ٕȁյхѥ4(4(4(4)=MM0A%ٕ́ЁՍ啅̀4(4(4(%ȁյхѥɕɑ=MM0$ٔչٔ4(ёѕᅵ̸ٕѡљ́չх́Ѐ4(ѕͥȰɑѼѡ4(輽ܹљͰᅵ̼4(4)}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}|4)=MM0AɽЀ輽ܹͰɜ4)ٕЁ51ЀͰͰɜ4)ѽѕ1Ё5ȀɑͰɜ4(

:��I"Ϯ��r�m���� (���Z+�7�zZ)���1���x ��h���W^��^��%����&jם.+-1�ځ��j:+v�������h�
Reply | Threaded
Open this post in threaded view
|

RE: Improving Developer Documentation

bushsf
Quantum key distribution systems are growing and it would be good to use PSK or other mechanisms to help accommodate QKD symmetric keys.

Steve

-----Original Message-----
From: Krzysztof Kwiatkowski [mailto:[hidden email]]
Sent: Friday, November 14, 2014 7:00 PM
To: Bush, Stephen F (GE Global Research)
Cc: [hidden email]; [hidden email]
Subject: Re: Improving Developer Documentation

SRP is another

On Fri, 2014-11-14 at 22:42 +0000, Bush, Stephen F (GE Global Research)
wrote:

> Pre-Shared Keys might be one example of something that is hard to find in any documented example.
>
> Steve
>
> -----Original Message-----
> From: [hidden email]
> [mailto:[hidden email]] On Behalf Of
> [hidden email]
> Sent: Friday, November 14, 2014 4:16 PM
> To: [hidden email]; Krzysztof Kwiatkowski;
> [hidden email]
> Cc: [hidden email]
> Subject: Re: Improving Developer Documentation
>
>
>
> OpenSSL APIs haven't changed much in 10 years :)
>
>
> > In looking for documentation regarding OpenSSL all I have found have
> > been outdated examples. Even the rtfm link is unmaintained and has
> > not been updated since 2002, according to this:
> > http://www.rtfm.com/openssl-examples/
>
> ______________________________________________________________________
> OpenSSL Project                                 http://www.openssl.org
> Development Mailing List                       [hidden email]
> Automated List Manager                           [hidden email]
> Ensڶj!(7yy' yǢ_yl܅-ze5]}yo'ǫ[zzvǮ+a<I"/Mxn7ӝ4A'hh'睲CzXzjׅ-x6^6ۍ4D^qyiV-Y^y'ze+aƧD)קhfj!('u^+M4$;1+'睲E-x6^6ۍ4Eҥ$z^Ȩ*Z,j"}Mt}zxh5睲wUҥz]*Z+Z
> (6ַ*tt-
> <+J0H<%ylP ޮ^%uZ+'z)z{,ׯhn7)
 <ޖ^:gbtNbp
> z{Kjx.jD1!ڰmiW1$Pj+Ɗ)ڶ)ݵ_w
> z{Sʗ{VZǭ_*'Nw(v)m0E^Ȩ]>(~"bz"{ޝ+rzx"6Mt}~MM4G^~)*'
 <׍uם5Mx]yMx]x]5('j۫z4\h{Rz֢')jjh'2ןjm+x
> ,rK.(4(4iۥ(4nd+x
> ,)jf-Jj'iqƧr
> ^x^4n4Myب&j)]uM{AɔMɕ-́ЁᅵͽѡѡЁ́ɐѼ䁑յѕᅵ4(4)Mѕٔ4(4(=ɥ5ͅ4)ɽ聽ݹȵͰͰɜmѼݹȵͰͰɝt= =٥͵4)Mɥ䰁9ٕȀаЀ؁A44)Q聽ͰͰɜ-ѽ-ݥѭͭ쁽ͰͰɜ4)
> 聽ݹȵͰͰɜ4)MՉI%ɽ٥ٕȁյхѥ4(4(4(4)=MM0A%ٕ́ЁՍ啅̀4(4(4(%ȁյхѥɕɑ=MM0$ٔչٔ4(ёѕᅵ̸ٕѡљ́
> չх́Ѐ4(ѕͥȰɑѼѡ4(輽ܹљͰᅵ̼4(4)}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}
> }}}}}}}}}}}}}}}}}}}}}}}|4)=MM0AɽЀ輽ܹͰɜ4)ٕЁ51ЀͰͰɜ4)ѽѕ1Ё5ȀɑͰɜ4(


Stephen F Bush.vcf (6K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Improving Developer Documentation

Casey Dunham
If anyone wants to post some code, I'll start working to get it on the wiki. Probably won't have time until Sunday, but those of you who are posting this definitely know more about it than I do, so I think its safe to assume we can start with your code and go from there!

C

On Fri Nov 14 2014 at 8:37:15 PM Bush, Stephen F (GE Global Research) <[hidden email]> wrote:
Quantum key distribution systems are growing and it would be good to use PSK or other mechanisms to help accommodate QKD symmetric keys.

Steve

-----Original Message-----
From: Krzysztof Kwiatkowski [mailto:[hidden email]]
Sent: Friday, November 14, 2014 7:00 PM
To: Bush, Stephen F (GE Global Research)
Cc: [hidden email]; [hidden email]
Subject: Re: Improving Developer Documentation

SRP is another

On Fri, 2014-11-14 at 22:42 +0000, Bush, Stephen F (GE Global Research)
wrote:
> Pre-Shared Keys might be one example of something that is hard to find in any documented example.
>
> Steve
>
> -----Original Message-----
> From: [hidden email]
> [mailto:[hidden email]] On Behalf Of
> [hidden email]
> Sent: Friday, November 14, 2014 4:16 PM
> To: [hidden email]; Krzysztof Kwiatkowski;
> [hidden email]
> Cc: [hidden email]
> Subject: Re: Improving Developer Documentation
>
>
>
> OpenSSL APIs haven't changed much in 10 years :)
>
>
> > In looking for documentation regarding OpenSSL all I have found have
> > been outdated examples. Even the rtfm link is unmaintained and has
> > not been updated since 2002, according to this:
> > http://www.rtfm.com/openssl-examples/
>
> ______________________________________________________________________
> OpenSSL Project                                 http://www.openssl.org
> Development Mailing List                       [hidden email]
> Automated List Manager                           [hidden email]
> Ensڶj!(7yy'   yǢ_yl܅-ze5]}yo'ǫ[zzvǮ+a<I"/Mxn7ӝ4A'hh'睲CzXzjׅ-x6^6ۍ4D^qyiV-Y^y'ze+aƧD)קhfj!('u^+M4$;1+'睲E-x6^6ۍ4Eҥ$z^Ȩ*Z,j"}Mt}zxh5睲wUҥz]*Z+Z
> (6ַ*tt-
> <+J0H<%ylP    ޮ^%uZ+'z)z{,ׯhn7)
 <ޖ^:gbtNbp
> z{Kjx.jD1!ڰmiW1$Pj+Ɗ)ڶ)ݵ_w
> z{Sʗ{ VZǭ_*'Nw(v)m0E^Ȩ]>(~"bz"{ޝ+rzx"6Mt}~MM4G^~)*'
 <׍uם5Mx]yMx]x]5('j۫z4\h{Rz֢')jjh'2ןjm+x
> ,rK.(4(4iۥ(4nd+x
> ,)jf-Jj'iqƧr
> ^x^4n4Myب&j)]uM{AɔMɕ-́ЁᅵͽѡѡЁ́ɐѼ䁑յѕᅵ4(4)Mѕٔ4(4(=ɥ5ͅ4)ɽ聽ݹȵͰͰɜmѼݹȵͰͰɝt=  =٥͵4)Mɥ䰁9ٕȀаЀ؁A44)Q聽ͰͰɜ-ѽ-ݥѭͭ쁽ͰͰɜ4)
> 聽ݹȵͰͰɜ4)MՉI%ɽ٥ٕȁյхѥ4(4(4(4)=MM0A%ٕ́ЁՍ啅̀4(4(4(%ȁյхѥɕɑ=MM0$ٔչٔ4(ёѕᅵ̸ٕѡљ́
> չх́Ѐ4(ѕͥȰɑѼѡ4(輽ܹљͰᅵ̼4(4)}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}
> }}}}}}}}}}}}}}}}}}}}}}}|4)=MM0AɽЀ輽ܹͰɜ4)ٕЁ51ЀͰͰɜ4)ѽѕ1Ё5ȀɑͰɜ4(

Reply | Threaded
Open this post in threaded view
|

Re: Improving Developer Documentation

Philip Prindeville
In reply to this post by Krzysztof Kwiatkowski-2
I asked O’Reilly if it was going to be updated, but here’s the response I got:

    Hello,

    Thanks for you for your interest in Network Security with OpenSSL. I wish I had better news for your, but unfortunately it appears as if there isn't a new edition being planned.

    Best regards,
    Paul Fichera
    O'Reilly Media


Hmmm… perhaps if enough people asked for an update…


On Nov 14, 2014, at 7:05 AM, Krzysztof Kwiatkowski <[hidden email]> wrote:

>> http://www.amazon.co.uk/Network-Security-OpenSSL-Cryptography-Communications/dp/059600270X
>
> I've found basics and even more advanced topics in this book, but please notice that it is more than 10 years old, so doesn't cover new stuff and I've found some information outdated. Still - good book.



______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Improving Developer Documentation

Philip Prindeville
In an interesting turn, I had emailed John Viega and asked him if there was a chance of an updated and expanded edition of his book, and his response was:

    Probably next year, yes.

so that’s something to look forward to.

-Philip


On Nov 15, 2014, at 2:04 PM, Philip Prindeville <[hidden email]> wrote:

> I asked O’Reilly if it was going to be updated, but here’s the response I got:
>
>    Hello,
>
>    Thanks for you for your interest in Network Security with OpenSSL. I wish I had better news for your, but unfortunately it appears as if there isn't a new edition being planned.
>
>    Best regards,
>    Paul Fichera
>    O'Reilly Media
>
>
> Hmmm… perhaps if enough people asked for an update…
>
>
> On Nov 14, 2014, at 7:05 AM, Krzysztof Kwiatkowski <[hidden email]> wrote:
>
>>> http://www.amazon.co.uk/Network-Security-OpenSSL-Cryptography-Communications/dp/059600270X
>>
>> I've found basics and even more advanced topics in this book, but please notice that it is more than 10 years old, so doesn't cover new stuff and I've found some information outdated. Still - good book.

______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]