[20/50] qpid-proton git commit: PROTON-932: SSL platform notes

[ac...@apache.org]

PROTON-932: SSL platform notes


Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/e4c99b93
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/e4c99b93
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/e4c99b93

Branch: refs/heads/cjansen-cpp-client
Commit: e4c99b936d776b16b482aa5ef1c2e34f3177620d
Parents: dcc09f1
Author: Clifford Jansen <cl...@apache.org>
Authored: Fri Jul 3 12:29:13 2015 -0700
Committer: Clifford Jansen <cl...@apache.org>
Committed: Fri Jul 3 12:29:13 2015 -0700

----------------------------------------------------------------------
 proton-c/src/ssl/PLATFORM_NOTES.md | 82 +++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/e4c99b93/proton-c/src/ssl/PLATFORM_NOTES.md
----------------------------------------------------------------------
diff --git a/proton-c/src/ssl/PLATFORM_NOTES.md b/proton-c/src/ssl/PLATFORM_NOTES.md
new file mode 100644
index 0000000..1c4c517
--- /dev/null
+++ b/proton-c/src/ssl/PLATFORM_NOTES.md
@@ -0,0 +1,82 @@
+Proton SSL/TLS implementations have platform dependent formats for specifying
+private and public key information.
+
+OpenSSL
+=======
+
+On OpenSSL (POSIX) based systems, certificates and their private keys are
+specified separately in two files: the public X509 certificate in PEM format
+and the password protected PKCS#8 encoded private key.
+
+  `pn_ssl_domain_set_credentials(path_to_public_x509.pem,  
+                path_to_private_pkcs8.pem, password_for_pkcs8)`
+
+
+A database of trusted Certificate Authority certificates may be specified as a
+path to a file or a directory.  In the former case, the file consists of one
+or more X509 certificates in PEM format concatenated together.  In the latter
+case, the directory contains a file for each X509 certificate in PEM format
+and indexed by (i.e. the file name is derived from) the X509 `-subject_hash`
+of the certificate's name.  See
+[here](https://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.htm)
+for more details.
+
+
+SChannel
+========
+
+On SChannel (Windows) based systems, trust and identity certificates are
+stored in certificate stores, which may be file based or system/registry
+based.  The former are in PKCS#12 format and the latter are typically managed
+by the Microsoft graphical management console.  The public and private keys
+are stored together, except in the case of trusted authority certificates
+which only contain the public key information.
+
+To specify a certificate:
+
+  `pn_ssl_domain_set_credentials(store, certificate_friendly_name,  
+                 password_for_store)`
+
+File based stores are specified by their relative or absolute path names.
+Registry stores are specified by their names (which are case insensitive)
+preceded by "ss:" for "Current User" system stores or "lmss:" for "Local
+Machine" system stores.  Examples:
+
+  "ss:Personal" specifies the Personal store for the Current User.
+
+  "lmss:AMQP" specifies a registry store called "AMQP" for the Local Machine
+  context.
+
+  "ss:Root" specifies the Trusted Root Certificate Authorities store for the
+  Current User.
+
+If a store contains a single certificate, the friendly name is optional.  The
+password may be null in the case of a registry store that is not password
+protected.
+
+Trusted root certificates must be placed in a store that is not password
+protected.
+
+In the special case that the peer certificate chain being verified requires
+revocation checking, the trusted root certificate must be present in both the
+trust store specified to Proton and also in the Windows "Trusted Root
+Certificate Authorities" system store.  Such certificate chains are usually
+managed by a central corporate network administrator or by a recognized
+certificate authority in which case the trusted root is often already present
+in the system store.  This requirement can be worked around by creating a
+special purpose CA database for Proton that includes the target peer's
+certificate (making it trusted, with the caution that you must consider the
+security implications of bypassing the revocation check).
+
+Existing OpenSSL keys (say `xx_x509.pem` and `xx_private_key.pem`) can be
+converted to PKCS#12 by the command:
+
+  `openssl pkcs12 -export -out xx_windows.p12 -passin pass:password \  
+          -passout pass:password -inkey xx_private_key.pem -in xx_x509.pem \  
+          -name xx_friendlyname`
+
+To create a PKCS#12 trust store from a Certificate Authority's public X509
+certificate with an empty password:
+
+  `openssl pkcs12 -export -out trust_store.p12 -in ca-certificate.pem \  
+          -name ca-certificate -nokeys -passout pass:`


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org