From 88fa9b8bc2d4459bacdea263ac113907f9d66c69 Mon Sep 17 00:00:00 2001 From: Bart van Strien Date: Fri, 5 Jun 2015 15:03:06 +0200 Subject: [PATCH] Document the context module --- doc/context.md | 198 +++++++++++++++++++++++++++++++++++++++++++++---- doc/luasec.md | 77 +------------------ 2 files changed, 187 insertions(+), 88 deletions(-) diff --git a/doc/context.md b/doc/context.md index 7aa9563..83baef4 100644 --- a/doc/context.md +++ b/doc/context.md @@ -1,20 +1,192 @@ Functions --------- -`context.create` -`context.locations` -`context.loadcert` -`context.loadkey` -`context.checkkey` -`context.setcipher` -`context.setdepth` -`context.setdhparam` -`context.setcurve` -`context.setverify` -`context.setoptions` -`context.setmode` +### context.create ### + + ctxt = context.create(method) + +Creates a new context. Can fail, in which case it returns nil, followed by an +error. + +### context.locations ### + + success, error = context.locations(ctxt, [cafile], [capath]) + +Set the location of either the CA certificate file, or the directory which +contains said file(s). + +### context.loadcert ### + + success, error = context.loadcert(ctxt, filename) + +Load a certificate from a file into this context. + +### context.loadkey ### + + success, error = context.loadkey(ctxt, filename) + success, error = context.loadkey(ctxt, filename, string) + success, error = context.loadkey(ctxt, filename, function() -> string) + +Loads a private key from a PEM-format file. The third argument can be either a +string, or a function returning a string producing the password for the key. + +### context.checkkey ### + + success = context.checkkey(ctxt) + +Returns true if the certificate loaded matches the key loaded. + +### context.setcipher ### + + success, error = context.setcipher(ctxt, cipherlist) + +Sets the ciphers used when negotiation. For the format of the string +`cipherlist`, see the openssl documentation, and in particular the `openssl +ciphers` command line tool. + +### context.setdepth ### + + success = context.setdepth(ctxt) + +Set the maximum verification depth for checking certificate chains. + +### context.setdhparam ### + + context.setdhparam(ctxt, function(isExport, keyLength) -> params) + +Sets a callback to obtain Diffie-Hellman parameters on this context. Once these +parameters are required, the callback gets called with a flag (`isExport`) +indicating whether export-level security is used, and a key length +(`keyLength`). It is then expected to produce a string containg parameters. + +For the format of the parameters string, see the openssl documentation. + +### context.setcurve ### + + success, error = context.setcurve(ctxt, curve) + +Set the curve to use for Elliptic Curve cryptography. + +The curve can be one of: + + - `secp112r1` + - `secp112r2` + - `secp128r1` + - `secp128r2` + - `secp160k1` + - `secp160r1` + - `secp160r2` + - `secp192k1` + - `secp224k1` + - `secp224r1` + - `secp256k1` + - `secp384r1` + - `secp521r1` + - `sect113r1` + - `sect113r2` + - `sect131r1` + - `sect131r2` + - `sect163k1` + - `sect163r1` + - `sect163r2` + - `sect193r1` + - `sect193r2` + - `sect233k1` + - `sect233r1` + - `sect239k1` + - `sect283k1` + - `sect283r1` + - `sect409k1` + - `sect409r1` + - `sect571k1` + - `sect571r1` + - `prime192v1` + - `prime192v2` + - `prime192v3` + - `prime239v1` + - `prime239v2` + - `prime239v3` + - `prime256v1` + +### context.setverify ### + + success, error = context.setverify(ctxt, options...) + +Sets verification options for this context. + +The following options are valid: + + - `none` + - `peer` + - `client_once` + - `fail_if_no_peer_cert` + +### context.setoptions ### + + success, error = context.setoptions(ctxt, options...) + +Set generic context options for this context. + +The following options are valid: + + - `all` + - `allow_unsafe_legacy_renegotiation` + - `cipher_server_preference` + - `cisco_anyconnect` + - `cookie_exchange` + - `cryptopro_tlsext_bug` + - `dont_insert_empty_fragments` + - `ephemeral_rsa` + - `legacy_server_connect` + - `microsoft_big_sslv3_buffer` + - `microsoft_sess_id_bug` + - `msie_sslv2_rsa_padding` + - `netscape_ca_dn_bug` + - `netscape_challenge_bug` + - `netscape_demo_cipher_change_bug` + - `netscape_reuse_cipher_change_bug` + - `no_compression` + - `no_query_mtu` + - `no_session_resumption_on_renegotiation` + - `no_sslv2` + - `no_sslv3` + - `no_ticket` + - `no_tlsv1` + - `no_tlsv1_1` + - `no_tlsv1_2` + - `pkcs1_check_1` + - `pkcs1_check_2` + - `single_dh_use` + - `single_ecdh_use` + - `ssleay_080_client_dh_bug` + - `sslref2_reuse_cert_type_bug` + - `tls_block_padding_bug` + - `tls_d5_bug` + - `tls_rollback_bug` + +### context.setmode ### + + success = context.setmode(ctxt, mode) + +Set the mode for this context. + +Mode can be one of: + + - `client` + - `server` Methods ------- -`context:setverifyext` +### ctxt:setverifyext ### + + success, error = ctxt:setverifyext(flags...) + +Set which extra verification steps to use. + +The following flags are valid: + + - `lsec_continue`: Continue with verification errors + - `lsec_ignore_purpose`: Ignore this certificate's purpose (like server/client) + - `crl_check`: Check Certification Revocation Lists + - `crl_check_chain`: Check CRLs for the entire chain diff --git a/doc/luasec.md b/doc/luasec.md index 5164f34..c57083e 100644 --- a/doc/luasec.md +++ b/doc/luasec.md @@ -34,82 +34,9 @@ Creates a new context based on the settings in the `cfg` table. See OpenSSL documentation on specifics on these settings, and see the `openssl ciphers` command for the list of supported ciphers and its format specifically. -#### options #### - "all" - "allow_unsafe_legacy_renegotiation" - "cipher_server_preference" - "cisco_anyconnect" - "cookie_exchange" - "cryptopro_tlsext_bug" - "dont_insert_empty_fragments" - "ephemeral_rsa" - "legacy_server_connect" - "microsoft_big_sslv3_buffer" - "microsoft_sess_id_bug" - "msie_sslv2_rsa_padding" - "netscape_ca_dn_bug" - "netscape_challenge_bug" - "netscape_demo_cipher_change_bug" - "netscape_reuse_cipher_change_bug" - "no_compression" - "no_query_mtu" - "no_session_resumption_on_renegotiation" - "no_sslv2" - "no_sslv3" - "no_ticket" - "no_tlsv1" - "no_tlsv1_1" - "no_tlsv1_2" - "pkcs1_check_1" - "pkcs1_check_2" - "single_dh_use" - "single_ecdh_use" - "ssleay_080_client_dh_bug" - "sslref2_reuse_cert_type_bug" - "tls_block_padding_bug" - "tls_d5_bug" - "tls_rollback_bug" +For a list of options, see `context.setoptions`. -#### curves #### - - "secp112r1" - "secp112r2" - "secp128r1" - "secp128r2" - "secp160k1" - "secp160r1" - "secp160r2" - "secp192k1" - "secp224k1" - "secp224r1" - "secp256k1" - "secp384r1" - "secp521r1" - "sect113r1" - "sect113r2" - "sect131r1" - "sect131r2" - "sect163k1" - "sect163r1" - "sect163r2" - "sect193r1" - "sect193r2" - "sect233k1" - "sect233r1" - "sect239k1" - "sect283k1" - "sect283r1" - "sect409k1" - "sect409r1" - "sect571k1" - "sect571r1" - "prime192v1" - "prime192v2" - "prime192v3" - "prime239v1" - "prime239v2" - "prime239v3" - "prime256v1" +For a list of curves, see `context.setcurve`. ### ssl.loadcertificate ### Alias for `cert.load`.