lua-openssl

• Index

Contents

• Functions
• Class bio

Modules

• asn1
• bio
• bn
• callback
• cipher
• cms
• compat
• dh
• digest
• dsa
• ec
• engine
• hmac
• kdf
• lhash
• mac
• misc
• ocsp
• openssl
• param
• pkcs12
• pkcs7
• pkey
• rsa
• srp
• ssl
• th-lock
• ts
• util
• x509
• x509.algor
• x509.attribute
• x509.crl
• x509.extension
• x509.name
• x509.req
• x509.store

Topics

• README

Module bio

bio module to mapping a BIO in openssl to a lua object.

Usage:

bio = require'openssl'.bio

Functions

mem ([data=nil])	make string as bio object
pair ([buffer1=0[, buffer2=buffer1]])	create a pair of connected BIOs
destroy_pair (bio)	destroy a BIO pair connection
null ()	create a null BIO that discards all data written to it
socket (fd[, support='noclose'])	make tcp bio from socket fd
dgram (fd[, support='noclose'])	make dgram bio from socket fd
fd (fd[, support='noclose'])	make socket or file bio with fd
file (file[, mode='r'])	make file object with file name or path
accept (host_port)	make tcp listen socket
connect (host_addr[, connect=true])	make tcp client socket
connect (address[, connect=true])	make tcp client socket with address table
filter (mode)	make base64 or buffer bio, which can append to an io BIO object
filter (mode, md_alg)	make digest bio, which can append to an io BIO object
filter (mode, s[, flag='noclose'])	make ssl bio
filter (mode, alg, key, iv[, encrypt=true])	make cipher filter bio object

Class bio

bio:read (len)	read data from bio object
bio:gets ([max=256])	get line from bio object
bio:write (data)	write data to bio object
bio:puts (data)	put line to bio object
bio:flush ()	flush buffer of bio object
bio:free ([free_all=false])	free BIO object and associated resources
bio:type ()	get type of bio
bio:nbio (nonblock)	set nonblock for bio object
bio:retry ()	check if BIO operation should be retried
bio:reset ()	reset bio to initial state
bio:push (append)	push bio append to chain of bio, if want to free a chain use free_all()
bio:pop (toremove)	remove bio from chain
bio:get_mem ()	get mem data, only support mem bio object
bio:get_md ()	get message digest from BIO filter chain
bio:next ()	get next BIO in the filter chain
bio:cipher_status ()	get cipher status for BIO
bio:accept ([setup=false])	setup ready and accept client connect
bio:shutdown ()	shutdown SSL or TCP connection
bio:get_ssl ()	get ssl object assosited with bio object
bio:connect ()	do TCP or SSL connect
bio:handshake ()	do handshake of TCP or SSL connection
bio:fd ()	get fd of bio object
bio:fd (fd)	set fd of bio object
bio:seek (offset)	seek to position in BIO
bio:tell ()	get current position in BIO
bio:set_callback (callback)	set callback function of bio information
bio:pending ()	return pending length of bytes to read and write
bio:close ()	close bio

Functions

mem ([data=nil])

make string as bio object

Parameters:

• data string , it will be memory buffer data (default nil)

Returns:

bio it can be input or output object

pair ([buffer1=0[, buffer2=buffer1]])

create a pair of connected BIOs

Parameters:

• buffer1 number buffer size for first BIO (default 0)
• buffer2 number buffer size for second BIO (default buffer1)

Returns:

1. bio first BIO of the pair
2. bio second BIO of the pair

destroy_pair (bio)

destroy a BIO pair connection

Parameters:

• bio bio BIO object that is part of a pair

Returns:

boolean true on success, false on failure

null ()

create a null BIO that discards all data written to it

Returns:

bio null BIO object

socket (fd[, support='noclose'])

make tcp bio from socket fd

Parameters:

• fd number
• support flag ‘close’ or ‘noclose’ when close or gc (default 'noclose')

Returns:

bio

dgram (fd[, support='noclose'])

make dgram bio from socket fd

Parameters:

• fd number
• support flag ‘close’ or ‘noclose’ when close or gc (default 'noclose')

Returns:

bio

fd (fd[, support='noclose'])

make socket or file bio with fd

Parameters:

• fd number
• support flag ‘close’ or ‘noclose’ when close or gc (default 'noclose')

Returns:

bio

file (file[, mode='r'])

make file object with file name or path

Parameters:

• file string
• mode string (default 'r')

Returns:

bio

accept (host_port)

make tcp listen socket

Parameters:

• host_port string address like ‘host:port’

Returns:

bio

connect (host_addr[, connect=true])

make tcp client socket

Parameters:

• host_addr string address like ‘host:port’ (e.g., ‘kkhub.com:443’)
• connect boolean default connect immediately, false to defer connection (default true)

Returns:

bio TCP client BIO object

connect (address[, connect=true])

make tcp client socket with address table

Parameters:

• address table table with hostname, ip, port fields
• connect boolean default connect immediately, false to defer connection (default true)

Returns:

bio TCP client BIO object

Usage:

-- String format
local cli = bio.connect("kkhub.com:443")

-- Table format
local cli = bio.connect({
  hostname = "kkhub.com",
  port = "12345"
})

-- Deferred connection
local cli = bio.connect("host:port", false)

filter (mode)

make base64 or buffer bio, which can append to an io BIO object

Parameters:

• mode string support ‘base64’ or ‘buffer’

Returns:

bio filter BIO object

filter (mode, md_alg)

make digest bio, which can append to an io BIO object

Parameters:

• mode string must be ‘md’ for message digest
• md_alg evp_md or string message digest algorithm name (e.g., ‘sha1’, ‘sha256’)

Returns:

bio filter BIO object for message digest operations

filter (mode, s[, flag='noclose'])

make ssl bio

Parameters:

• mode string must be ‘ssl’
• s ssl SSL object to attach
• flag string support ‘close’ or ‘noclose’ when close or gc (default 'noclose')

Returns:

bio SSL filter BIO object

filter (mode, alg, key, iv[, encrypt=true])

make cipher filter bio object

Parameters:

• mode string must be ‘cipher’
• alg string or evp_cipher cipher algorithm name (e.g., ‘aes-128-ecb’)
• key string encryption/decryption key
• iv string initialization vector
• encrypt boolean true for encryption, false for decryption (default true)

Returns:

bio cipher filter BIO object

Class bio

bio:read (len)

read data from bio object

Parameters:

• len number

Returns:

string string length may be less than param len

bio:gets ([max=256])

get line from bio object

Parameters:

• max number line len (default 256)

Returns:

string string length may be less than param len

bio:write (data)

write data to bio object

Parameters:

• data string

Returns:

number length success write

bio:puts (data)

put line to bio object

Parameters:

• data string

Returns:

number length success write

bio:flush ()

flush buffer of bio object

Returns:

boolean true for success, others for fail

bio:free ([free_all=false])

free BIO object and associated resources

Parameters:

• free_all boolean if true, free entire BIO chain; if false, free only this BIO (default false)

Returns:

number always returns 0

bio:type ()

get type of bio

Returns:

string

bio:nbio (nonblock)

set nonblock for bio object

Parameters:

• nonblock boolean

Returns:

boolean result, true for success, others for fail

bio:retry ()

check if BIO operation should be retried

Returns:

1. boolean true if operation should be retried
2. boolean true if should retry read operation
3. boolean true if should retry write operation
4. boolean true if should retry special I/O operation

bio:reset ()

reset bio to initial state

Returns:

boolean true on success, false on failure

bio:push (append)

push bio append to chain of bio, if want to free a chain use free_all()

Parameters:

• append bio

Returns:

bio

bio:pop (toremove)

remove bio from chain

Parameters:

• toremove bio

bio:get_mem ()

get mem data, only support mem bio object

Returns:

string

bio:get_md ()

get message digest from BIO filter chain

Returns:

1. evp_md or nil message digest object or nil if not found
2. evp_md_ctx or nil message digest context or nil if not found

bio:next ()

get next BIO in the filter chain

Returns:

bio or nil next BIO object in chain or nil if none

bio:cipher_status ()

get cipher status for BIO

Returns:

boolean cipher status

bio:accept ([setup=false])

setup ready and accept client connect

Parameters:

• setup boolean true for setup accept bio, false or none will accept client connect (default false)

Returns:

boolean result only when setup is true

Or

bio accpeted bio object

bio:shutdown ()

shutdown SSL or TCP connection

bio:get_ssl ()

get ssl object assosited with bio object

Returns:

ssl

bio:connect ()

do TCP or SSL connect

Returns:

booolean result true for success and others for fail

bio:handshake ()

do handshake of TCP or SSL connection

Returns:

boolean result true for success, and others for fail

bio:fd ()

get fd of bio object

Returns:

number

bio:fd (fd)

set fd of bio object

Parameters:

• fd number

Returns:

number fd

bio:seek (offset)

seek to position in BIO

Parameters:

• offset number position offset to seek to

Returns:

number new position after seek

bio:tell ()

get current position in BIO

Returns:

number current position in the BIO

bio:set_callback (callback)

set callback function of bio information

Parameters:

• callback function

Returns:

boolean result true for success, and others for fail

bio:pending ()

return pending length of bytes to read and write

Returns:

number pending of read, followed by pending of write

bio:close ()

close bio