Module pkey

pkey module to create and process public or private key, do asymmetric key operations.

Usage:

    pkey = require'openssl'.pkey

Functions

read (input[, priv=false[, format='auto'[, passhprase]]]) read public/private key from data
new (alg, curvename[, flags]) generate a new ec keypair
new ([alg='rsa'[, bits=2048|512[, e[, eng]]]]) generate a new keypair
new (factors) create a new keypair by factors of keypair or get public key only

Class evp_pkey

evp_pkey:export ([support='pem'[, raw=false[, passphrase]]]) export evp_pkey as pem/der string
evp_pkey:parse () get key details as table
evp_pkey:encrypt (data, string) encrypt message with public key encrypt length of message must not longer than key size, if shorter will do padding,currently supports 6 padding modes.
evp_pkey:decrypt (data, string) decrypt message with private key pair with encrypt
evp_pkey:is_private () return key is private or not
evp_pkey:get_public () return public key
evp_pkey:ctx ([engine]) create EVP_PKEY_CTX context for public key operations
evp_pkey:ctx_new (algorithm[, engine]) create new EVP_PKEY_CTX by algorithm identifier
evp_pkey:keygen ([bits]) generate a key pair using the context
evp_pkey:ctrl (name, value) control EVP_PKEY_CTX with string parameters
evp_pkey:decrypt_init () initialize EVP_PKEY_CTX for decryption operations
evp_pkey:encrypt_init () initialize EVP_PKEY_CTX for encryption operations
evp_pkey:verify_init () initialize EVP_PKEY_CTX for verification operations
evp_pkey:sign_init () initialize EVP_PKEY_CTX for signing operations
evp_pkey:decrypt (data) decrypt data using private key context
evp_pkey:encrypt (data) encrypt data using public key context
evp_pkey:verify (data, signature) verify signature using EVP_PKEY_CTX
evp_pkey:sign (digest) create digital signature using EVP_PKEY_CTX
evp_pkey:derive (pkey, peer[, eng]) Derive public key algorithm shared secret
evp_pkey:sign (data[, md_alg[, userId='1234567812345678']]) sign message with private key
evp_pkey:verify (data, signature[, md_alg[, userId='1234567812345678']]) verify signed message with public key
evp_pkey:seal (data[, alg='RC4']) seal and encrypt message with one public key data be encrypt with secret key, secret key be encrypt with public key
evp_pkey:open (ekey, string[, md_alg='RC4']) open and ecrypted seal data with private key
evp_pkey:seal_init (cipher, public_keys) initialize envelope encryption (sealing) context
evp_pkey:seal_update (context, data) update envelope encryption with data
evp_pkey:seal_final (context) finalize envelope encryption
evp_pkey:open_init (private_key, encrypted_key, iv[, cipher]) initialize envelope decryption (opening) context
evp_pkey:open_update (context, data) update envelope decryption with encrypted data
evp_pkey:open_final (context) finalize envelope decryption
evp_pkey:bits () get the number of bits in the key
evp_pkey:set_engine (eng) set engine for the key
evp_pkey:as_sm2 () convert EC key to SM2 key type
evp_pkey:missing_paramaters () check if key parameters are missing


Functions

read (input[, priv=false[, format='auto'[, passhprase]]])
read public/private key from data

Parameters:

  • input string or openssl.bio string data or bio object
  • priv boolean prikey set true when input is private key (default false)
  • format string or encoding of input, support ‘auto’,‘pem’,‘der’ (default 'auto')
  • passhprase string when input is private key, or key types ‘ec’,‘rsa’,‘dsa’,‘dh’ (optional)

Returns:

    evp_pkey public key

See also:

new (alg, curvename[, flags])
generate a new ec keypair

Parameters:

  • alg string , alg must be ‘ec’
  • curvename string or number this can be integer as curvename NID
  • flags integer when alg is ec need this. (optional)

Returns:

    evp_pkey object with mapping to EVP_PKEY in openssl
new ([alg='rsa'[, bits=2048|512[, e[, eng]]]])
generate a new keypair

Parameters:

  • alg string , accept rsa,dsa,dh (default 'rsa')
  • bits integer , rsa with 2048, dh or dsa with 1024 (default 2048|512)
  • e integer , when alg is rsa give e value default is 0x10001, when alg is dh give generator value default is 2, when alg is dsa give string type seed value default is none. (optional)
  • eng engine (optional)

Returns:

    evp_pkey object with mapping to EVP_PKEY in openssl
new (factors)
create a new keypair by factors of keypair or get public key only

Parameters:

  • factors table to create private/public key, key alg only accept accept ‘rsa’,‘dsa’,‘dh’,‘ec’ and must exist
    when arg is rsa, table may with key n,e,d,p,q,dmp1,dmq1,iqmp, both are binary string or openssl.bn
    when arg is dsa, table may with key p,q,g,priv_key,pub_key, both are binary string or openssl.bn
    when arg is dh, table may with key p,g,priv_key,pub_key, both are binary string or openssl.bn
    when arg is ec, table may with d,x,y,z,both are binary string or openssl.bn, and with curve_name, enc_flag, conv_form

Returns:

    evp_pkey object with mapping to EVP_PKEY in openssl

Usage:

    --create rsa public key
  pubkey = new({alg='rsa',n=...,e=...}
--create new rsa
  rsa = new({alg='rsa',n=...,q=...,e=...,...}

Class evp_pkey

openssl.evp_pkey object
evp_pkey:export ([support='pem'[, raw=false[, passphrase]]])
export evp_pkey as pem/der string

Parameters:

  • support string export as ‘pem’ or ‘der’ format, default is ‘pem’ (default 'pem')
  • raw boolean true for export low layer key just rsa,dsa,ec (default false)
  • passphrase string if given, export key will encrypt with aes-128-cbc, only need when export private key (optional)

Returns:

    string
evp_pkey:parse ()
get key details as table

Returns:

    table infos with key bits,pkey,type, pkey may be rsa,dh,dsa, show as table with factor hex encoded bignum
evp_pkey:encrypt (data, string)
encrypt message with public key encrypt length of message must not longer than key size, if shorter will do padding,currently supports 6 padding modes. They are: pkcs1, sslv23, no, oaep, x931, pss.

Parameters:

Returns:

    string encrypted message
evp_pkey:decrypt (data, string)
decrypt message with private key pair with encrypt

Parameters:

Returns:

    string result

Or

    nil
evp_pkey:is_private ()
return key is private or not

Returns:

    boolean ture is private or public key
evp_pkey:get_public ()
return public key

Returns:

    evp_pkey pub
evp_pkey:ctx ([engine])
create EVP_PKEY_CTX context for public key operations

Parameters:

  • engine engine optional engine for hardware acceleration (optional)

Returns:

    evp_pkey_ctx public key context object for RSA operations
evp_pkey:ctx_new (algorithm[, engine])
create new EVP_PKEY_CTX by algorithm identifier

Parameters:

  • algorithm string or number algorithm name or NID
  • engine engine optional engine for hardware acceleration (optional)

Returns:

    evp_pkey_ctx or nil new context object or nil on error
evp_pkey:keygen ([bits])
generate a key pair using the context

Parameters:

  • bits number key size in bits (depends on key type) (optional)

Returns:

    evp_pkey generated key pair on success
evp_pkey:ctrl (name, value)
control EVP_PKEY_CTX with string parameters

Parameters:

  • name string control parameter name
  • value string control parameter value

Returns:

    boolean true on success, false on failure
evp_pkey:decrypt_init ()
initialize EVP_PKEY_CTX for decryption operations

Returns:

    evp_pkey_ctx context object ready for decryption
evp_pkey:encrypt_init ()
initialize EVP_PKEY_CTX for encryption operations

Returns:

    evp_pkey_ctx context object ready for encryption
evp_pkey:verify_init ()
initialize EVP_PKEY_CTX for verification operations

Returns:

    evp_pkey_ctx context object ready for verification
evp_pkey:sign_init ()
initialize EVP_PKEY_CTX for signing operations

Returns:

    evp_pkey_ctx context object ready for signing
evp_pkey:decrypt (data)
decrypt data using private key context

Parameters:

  • data string encrypted data to decrypt

Returns:

    string or nil decrypted data or nil on error
evp_pkey:encrypt (data)
encrypt data using public key context

Parameters:

Returns:

    string or nil encrypted data or nil on error
evp_pkey:verify (data, signature)
verify signature using EVP_PKEY_CTX

Parameters:

  • data string original data that was signed
  • signature string signature to verify

Returns:

    boolean true if signature is valid, false otherwise
evp_pkey:sign (digest)
create digital signature using EVP_PKEY_CTX

Parameters:

  • digest string message digest to sign

Returns:

    string or nil digital signature or nil on error
evp_pkey:derive (pkey, peer[, eng])
Derive public key algorithm shared secret

Parameters:

  • pkey evp_pkey private key
  • peer evp_pkey public key
  • eng engine (optional)

Returns:

    string
evp_pkey:sign (data[, md_alg[, userId='1234567812345678']])
sign message with private key

Parameters:

  • data string data be signed
  • md_alg string or env_digest default use sha256 or sm3 when pkey is SM2 type (optional)
  • userId string used when pkey is SM2 type (default '1234567812345678')

Returns:

    string signed message
evp_pkey:verify (data, signature[, md_alg[, userId='1234567812345678']])
verify signed message with public key

Parameters:

  • data string data be signed
  • signature string signed result
  • md_alg string or env_digest default use sha256 or sm3 when pkey is SM2 type (optional)
  • userId string used when pkey is SM2 type (default '1234567812345678')

Returns:

    boolean true for pass verify
evp_pkey:seal (data[, alg='RC4'])
seal and encrypt message with one public key data be encrypt with secret key, secret key be encrypt with public key

Parameters:

  • data string data to be encrypted
  • alg cipher or string (default 'RC4')

Returns:

  1. string data encrypted
  2. string skey secret key encrypted by public key
  3. string iv
evp_pkey:open (ekey, string[, md_alg='RC4'])
open and ecrypted seal data with private key

Parameters:

  • ekey string encrypted secret key
  • string string iv
  • md_alg evp_cipher or string (default 'RC4')

Returns:

    string data decrypted message or nil on failure
evp_pkey:seal_init (cipher, public_keys)
initialize envelope encryption (sealing) context

Parameters:

  • cipher string or evp_cipher encryption cipher to use
  • public_keys table array of public keys for recipients

Returns:

  1. evp_cipher_ctx or nil encryption context or nil on error
  2. table or nil encrypted keys for each recipient
  3. string or nil initialization vector
evp_pkey:seal_update (context, data)
update envelope encryption with data

Parameters:

  • context evp_cipher_ctx encryption context from seal_init
  • data string data to encrypt

Returns:

    string or nil encrypted data or nil on error
evp_pkey:seal_final (context)
finalize envelope encryption

Parameters:

  • context evp_cipher_ctx encryption context from seal_init

Returns:

    string or nil final encrypted data or nil on error
evp_pkey:open_init (private_key, encrypted_key, iv[, cipher])
initialize envelope decryption (opening) context

Parameters:

  • private_key evp_pkey private key for decryption
  • encrypted_key string encrypted symmetric key
  • iv string initialization vector
  • cipher string or evp_cipher decryption cipher to use (optional)

Returns:

    evp_cipher_ctx or nil decryption context or nil on error
evp_pkey:open_update (context, data)
update envelope decryption with encrypted data

Parameters:

  • context evp_cipher_ctx decryption context from open_init
  • data string encrypted data to decrypt

Returns:

    string or nil decrypted data or nil on error
evp_pkey:open_final (context)
finalize envelope decryption

Parameters:

  • context evp_cipher_ctx decryption context from open_init

Returns:

    string or nil final decrypted data or nil on error
evp_pkey:bits ()
get the number of bits in the key

Returns:

    number number of bits in the key
evp_pkey:set_engine (eng)
set engine for the key

Parameters:

  • eng engine engine object to use for this key

Returns:

    boolean result true for success
evp_pkey:as_sm2 ()
convert EC key to SM2 key type

Returns:

    boolean result true if successfully converted to SM2
evp_pkey:missing_paramaters ()
check if key parameters are missing

Returns:

    boolean true if key is missing parameters
generated by LDoc 1.5.0 Last updated 2025-09-22 19:55:54