description
luaossl is a comprehensive binding to OpenSSL for Lua 5.1, 5.2, and later. I dare say it's the most comprehensive OpenSSL binding in the Lua universe, and one of the most comprehensive bindings of OpenSSL in any language, on par with the best bindings in Python and Ruby. If you think otherwise, let me know so I can fix it!
It includes support for certificate and key management, key generation, signature verification, and deep bindings to the distinguished name, alternative name, and X.509v3 extension interfaces.
It also binds OpenSSL's bignum, message digest, HMAC, cipher, and CSPRNG interfaces. The end goal is to bind almost everything that OpenSSL supports, but no more. It's intended as a low-level interface.
Basic bindings to OpenSSL's SSL* session and SSL_CTX* prototype objects are available, but they cannot yet be used standalone to do SSL I/O. My cqueues project supports SSL/TLS sockets internally, accepts an SSL_CTX* object from Lua code for session configuration, and exports an SSL* object to Lua for session introspection. But also checkout LuaSSL and LuaSec.
luaossl started as an extension module in the cqueues project before splitting off. For earlier history see the cqueues project page.
usage
Comprehensive usage is documented in the luaossl Userguide PDF. For easy browsing use a PDF viewer with a side tab for the table of contents, such as Preview.app on OS X.
See examples/ in the project tree for example scripts.
todo
Add support for OpenSSL session caching.
Cache the /dev/urandom descriptor, and add pthread_atfork handler to stir the pot after a fork.
Detect and throw an error in ssl:setPrivateKey when the private key is not present in the pkey object.
Update documentation.
See Github issue tracker for more items.
news
2016-11-01
Workaround for broken GCC on some newer Debian and Ubuntu installations with odd GCC default flags that fail compilation on C99-style for-loops without any language standard or warning flags explicitly specified.
Tag rel-20161101 (cb727f97f2e00512c70631210de2d8b951e81587).
2016-10-29
OpenSSL 1.1 API compatability.
Support Linux getrandom() for entropy, and switch to arc4random on BSDs. (@oerdnj)
Support for getting and setting SubjectAltNames on CSRs. (@ashb)
Install missing openssl.x509.csr module. (@Zash)
Improve BIGNUM bindings. (@daurnimator)
Expose EVP_PKEY parameters with pkey:getParameters and pkey:setParameters. (@daurnimator)
Tag rel-20161029 (f88b333f9eaa605a0f7a835874b5b562b294b1c3).
2015-12-21
Various portability improvements and bug fixes.
Add :getParameters() method to EVP_PKEY objects.
Various enhancements to X.509 extensions bindings.
Tag rel-20151221 (86a593a0548563d156d7adc55cff179340a811c8).
2015-05-04
Use lightuserdata as registry keys. C function hashes aren't stable in LuaJIT.
Add openssl.version as binding for SSLeay_version.
Fix build on OpenBSD 5.6 libressl.
Tag rel-20150504 (91eb47726cb3b8d487f21a17b3c2b8c5e9fb1024).
2015-04-22
Add support for ALPN server callback, SSL_CTX_set_alpn_select_cb.
Fix X509_STORE double-free bug on older OpenSSL releases (< 1.0.2) by implementing and using (from both external application data destructor hook on SSL_CTX, as well as Lua __gc metamethod) our own X509_STORE_free routine which properly checks reference counts. Workaround adapted from Ruby OpenSSL bindings.
Fix strerror_r usage on glibc.
Tag rel-20150422 (b6ce57a198ed27f314b7183a0876c30f719ef69b).
2015-03-04
Merge ALPN support from quae@daurnimator.com.
2015-02-25
Add DES module with bindings to DES_string_to_key and DNS_set_odd_parity. Useful for implementing Windows LAN Manager authentication.
2014-10-28
Fix "TLS" and "SSL" method names for context.new. OpenSSL TLSv1_method() literally only speaks 1.0, not 1.0 and above. "TLS" now uses SSLv23_method and disables SSLv2 and SSLv3. "SSL" uses SSLv23_method and disables SSLv2.
2014-10-15
Add ssl:getVersion and ssl:getClientVersion.
2014-09-23
Merged more CRL support from Kaarle Ritvanen.
Add Lua 5.3 support.
Bind SSL_CTX_set_options and SSL_set_options.
Add openssl.ssl.context:setEphemeralKey, so networking libraries can enable perfect forward secrecy.
Add Server Name Indication (SNI) support with openssl.ssl:setHostName and :getHostName.
Fixed issue which prevented loading public and private keys concurrently. If openssl.pkey.new was passed a PEM-encoded string with both public and private keys, and the key type was left unspecified, the instantiated pkey object would only contain the public key, which was supremely non-obvious. (Also, OpenSSL will crash when an SSL context uses a pkey object without the private key portion! TODO: Detect and throw an error in ssl:setPrivateKey when the private key is not present in the pkey object.) Now it will parse and set both the public and private keys.
Add bindings to the opensslv.h and opensslconf.h headers. The macros can be accessed as static fields of the new openssl module (just "openssl", no suffix). For example, if OPENSSL_NO_EC is defined then require"openssl".NO_EC evaluates to true.
2014-07-18
Various fixes.
Merged CRL support from Kaarle Ritvanen.
Merged PKCS12 support from Kaarle Ritvanen.
Merged custom extension support from Kaarle Ritvanen.
Add AIX as supported platform.
Tag rel-20140718 (9157308b90ea7df405ed9b22f1801f3f70f2e30b).
2014-04-19
Add rand.stir, which tries to be more robust than OpenSSL's default RAND_poll implementation, which isn't chroot- or RLIMIT_NOFILE-safe because it requires opening /dev/urandom. In particular, it will use sysctl-based randomness sources on Linux and the BSDs (excluding OS X).
Reseed when fork detected.
2014-04-02
Tag rel-20140328 (657892416234797396bc0f3a6cf03614083009fc).
2014-03-27
Change return value of digest:update and hmac:update to return the digest object, rather than boolean true.
Fix rand.uniform implementation to use lua_Unsigned when it's a 64-bit integer type, as on Lua 5.3.
Rename openssl.pubkey to openssl.pkey. On install a symlink is created at the old module name to point to the new. For some reason "pkey" originally just looked odd, but it's confusing to use "pubkey" when OpenSSL and every other binding uses "pkey".
2014-03-26
Add DER input/output formats. Now you can explicitly specify PEM or DER, or allow the library to deduce the format.
Add GEN_DIRNAME alternative names, which allows specifying a X509_NAME object as an alternative name.
Change the return value of several :add methods. They now return the self object, so you can chain calls—local dn = name.new():add("C", "US"):add("ST", "California"):add("L", "San Francisco").
2014-03-22
Add luaossl user guide, separate from the cqueues user guide.
Add Lua 5.3 support.
Tag rel-20140322 (9975e282f13d63378e54081056c6597508c2ddb4).
2014-01-31
Add multi-threaded re-entrancy protection.
I originally just added the OpenSSL mutex callbacks to the cqueues' thread module. But it turns out that OpenSSL doesn't bother using the locking callbacks within its own initialization paths, so I had no choice but to put a mutex around the initialization invocations in luaossl. Unfotunately that creates a dependency on libpthread.
I also went ahead and added locking callback logic to luaossl as well. Others might be using luaossl with another threading library. That required a dependency on libdl so that I could pin the module in memory if we installed a locking callback.
As far as I can tell everything should continue working the same, as libpthread, libdl, and the dladdr(3) extension are quite standard at this point. But it will complicate a Windows port.
2013-12-09
Split off from the cqueues project.
2013-12-06
Add openssl.rand.uniform() for generating cryptographically strong, uniform random integers in the interval [0, N-1]. The maximum interval is [0, 2^64-1], although for Lua 5.1 and 5.2 you're restricted to the integral range of your Lua VM number type, which is too narrow in most implementations. Lua 5.3 is expected to add a 64-bit integer type.
2013-12-05
Add openssl.rand module, with bindings to OpenSSL RAND_bytes and RAND_status.
2013-03-14
Fixed bug in digest and HMAC modules which left the last argument to :update unprocessed.
Added openssl.cipher module, which binds OpenSSL EVP_CIPHER_CTX objects.
2013-02-26
Added openssl.pubkey:sign and openssl.pubkey:verify, which bind OpenSSL EVP_SignFinal and EVP_VerifyFinal. This allows constructing ad hoc signature schemes in applications.
2013-01-31
Added openssl.digest and openssl.hmac modules.
2012-10-09
Added insanely comprehensive OpenSSL bindings in ext/, including Lua bindings for manipulating bignums, public keys, X.509 certificates (names, altnames, chains, stores, etc), and SSL_CTX objects.
These bindings are similar to a X.509 Perl XS module I wrote several years ago and used for a CA which dynamically issued certificates to clients on an encrypted multimedia streaming network. That Perl module was proprietary, unfortunately. But I like using Lua better, anyhow.
license
Copyright (c) 2012-2016 William Ahern
Copyright (c) 2015-2017 Daurnimator
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
source
git clone http://25thandClement.com/~william/projects/luaossl.git