NAME

Crypt::OpenSSL::CA::Resources - A bibliography of documentations and tools that I found helpful for implementing X509 PKIs in Perl over all these years.

TUTORIALS

For a tutorial introduction to the concepts of PKI and X509, please refer to the appropriate Wikipedia articles (in particular <http://en.wikipedia.org/wiki/Public_key_infrastructure> and <http://en.wikipedia.org/wiki/X.509>).

Have some giggles while uncovering the bleak truth about the state of affairs in PKI-world with Peter Gutmann's crypto tutorials at <http://www.cs.auckland.ac.nz/~pgut001/tutorial/index.html>, and especially the one that deals with X509 PKI at <http://www.cs.auckland.ac.nz/~pgut001/pubs/pkitutorial.pdf>.

ALPHABET SOUP

See Crypt::OpenSSL::CA::AlphabetSoup

IMPLEMENTATION GUIDELINES

X509 Style Guide

The X509 Style Guide, also by Peter Gutmann (http://www.cs.auckland.ac.nz/~pgut001/pubs/x509guide.txt), although partly outdated (e.g. as regards Unicode support) is the single most helpful resource one needs to develop and deploy a full-fledged X509 PKI.

SOFTWARE

IDX-PKI

A working, rugged implementation of "PKIX" in Crypt::OpenSSL::CA::AlphabetSoup that is GPL-licenced and covers all the bases, despite its being restricted from the "commercial" version. Definitely a reference implementation in the field (I know, since I helped write it!). <http://idx-pki.idealx.org/index.en.html>

OpenSSL

The venerable, feature-rich but quirky and poorly documented cryptographic library that Crypt::OpenSSL::CA is built upon. Available on <http://www.openssl.org/> (and also on <https://www.openssl.org/>, of course).

/usr/bin/openssl

Of special interest is the "/usr/bin/openssl" command-line tool, that serves as a Swiss army knife of crypto debugging from making and parsing certificates to debugging SSL. Actually "/usr/bin/openssl" is powerful enough to serve as the sole foundation for a full-fledged PKI; this is almost what "IDX-PKI" does, but it is quirky (and therefore Crypt::OpenSSL::CA departs from that idea).

Here are a few tricks that I know by heart from typing them so often:

Parsing a certificate and displaying the details

  openssl x509 -noout -text -in cert.pem

or at an even lower level, using "dumpasn1":

  openssl x509 -outform der -in cert.pem | dumpasn1 -

Getting the modulus (unique public key identifier) of a certificate or private key

If both match, then the private key and certificate correspond to each other.

  openssl x509 -noout -modulus -in cert.pem
  openssl rsa -noout -modulus -in key.pem

Generating a self-signed certificate and matching private key for tests

  openssl req -x509 -nodes -new -newkey 1024 -keyout key.pem -out cert.pem

The resulting "key.pem" and "cert.pem" files can be used directly for a network server, or to build a toy CA.

Building a toy CA

Under distros that sport a cooperative "openssl.cnf": this was tested on Ubuntu Edgy, your mileage may vary.

1.

create a test directory and chdir into it

2.

create subdirectories "demoCA/private" and "demoCA/newcerts"; put the string 01 into "demoCA/serial"; create an empty "demoCA/index.txt" file.

3.

create a key and a self-signed certificate for the CA as explained above, and save them respectively as "demoCA/private/cakey.pem" and "demoCA/cacert.pem".

4.

create a certificate request using "openssl req"

5.

run

 openssl ca -subj "/C=AU/ST=Some-State/O=Internet Widgits Pty Ltd/CN=test" \
    -in user.req

6.

Rinse and repeat, tweaking the command line and the contents of the "./demoCA" subdirectory until openssl is satisfied. Read the ca(3) man page to interpret and resolve the error messages.

7.

Your certificate should appear in "./demoCA/newcerts" after a finite time (and tearing out only a minority subset of your hair).

8.

For advanced usage, copy over the default "openssl.cnf" file (usually to be found in "/usr/lib/openssl", "/usr/share/openssl" or "/etc/openssl") into "demoCA" and tack a "-config ./openssl.cnf" onto the "openssl" command line. Then you can start mucking with X509 extensions and so on.

Source code

Any serious work towards contributing to Crypt::OpenSSL::CA requires promiscuity with OpenSSL's code base. I suggest reading and understanding "demos/mkcert.c" and "apps/ca.c" first, comparing and contrasting with the XS code in Crypt::OpenSSL::CA which does roughly the same thing in a simpler and more modular way. Seasoned programmers will find the OpenSSL man pages of some limited help, and the command "grep -r some_identifier /usr/include/openssl" to come in handy more often than not.

"openssl.txt"

There is a succint overview of OpenSSL's whole API in a file named "doc/openssl.txt", to be found either in OpenSSL's source or possibly in the documentation directory of your distribution's openssl package (YMMV).

dumpasn1

A tool to debug "ASN.1" in Crypt::OpenSSL::CA::AlphabetSoup data structures, more fault-tolerant than the "openssl asn1parse" command (see "OpenSSL"). Available on "Peter Gutmann's site" and as a Debian package.

INTERNET SITES

STANDARDS

The RFCs and other standards describing PKIX (the X509 PKI) are, in suggested reading order:

RFC4210: Basics, security model, definition of the entities (EE, RA, CA), format of messages between these entities (that nobody in his right mind would bother to implement in this contrived way).
RFC4514: Distinguished Names ("DN" in Crypt::OpenSSL::CA::AlphabetSoup)
RFC3280: Certificate and CRL formats, extensions in certificates, certificate validation algorithm.
RFC3279: How one should set the "keyUsage" bits in an X509 certificate.
PKCS10: Certificate request file format - One of the most popular ones (the great thing about standards, as the saying goes, is that there are so many to choose from...)
SPKAC: The other certificate request file format of importance to an Internet PKIX deployment (<http://wp.netscape.com/eng/security/ca-interface.html>). Used by all browsers of the Netscape family.
<http://wp.netscape.com/eng/security/comm4-cert-exts.html>: The specification of the Netscape certificate type X509v3 extension. Mostly obsolete, but it does make your certificates all that more christmas-treeish.
PKCS12: A transport and backup format for X509 key material. Allows for bundling a user's certificate, its matching private key (password-protected), and the chain of CA certificates and CRLs that certify the user's certificate, all into a single binary blob.
RFC2560: "OCSP" in Crypt::OpenSSL::CA::AlphabetSoup
RFC3739: Qualified certificates.