1 Overview

The openHiTLS command source code is located in the apps directory, and the compiled result is hitls. Users can run the hitls command to perform various cryptographic operations. This tool provides a complete cryptographic function suite, including random number generation, symmetric/asymmetric encryption, digital signatures, PKI certificate management, and SSL/TLS connections.

1.1 Supported Command List

Command Category	Command Name	Description
Basic Commands
	help	Display help information and list of supported commands
	list	List supported algorithms and functions, including digest, symmetric, asymmetric, MAC, random number, KDF algorithms, etc.
Encryption and Digest
	enc	Symmetric encryption and decryption operations, supporting multiple symmetric algorithms
	mac	Message authentication code calculation and verification
	dgst	Message digest calculation and digital signature operations
	kdf	Key derivation function, derive keys from input materials
Key and Parameter Management
	rsa	RSA key processing, including format conversion and information display
	genrsa	Generate RSA private keys
	genpkey	Generate various types of public and private keys
	pkey	Public and private key processing tool
	pkeyutl	Use keys for encryption, decryption, signing, verification and other operations
	keymgmt	Key management functions, including key creation, deletion, querying, etc. (SM mode)
PKI Certificate Management
	pkcs12	Processing of PKCS#12 format certificates and key packages
	x509	Generation, parsing, conversion and verification of X.509 certificates
	crl	Generation and management of certificate revocation lists
	verify	Certificate chain verification and trust relationship checking
	req	Generation and processing of certificate signing requests
SSL/TLS Communication
	s_client	SSL/TLS client tool
	s_server	SSL/TLS server tool
Other Utility Tools
	rand	Generate random numbers of specified length, supporting hexadecimal and Base64 encoded output
	prime	Generate and test primes, support hexadecimal input/output

1.2 Command Usage

hitls <command> [options]

Where <command> is the specific functional command, and [options] are the parameter options for that command. Each command supports the -help option to view detailed usage instructions.

2 Options

2.1 Provider Options

• -provider <name>: Specify the Provider name, which can also be the Provider path. The command line loads and initializes the Provider identified by this name.
• -provider-path: Specify the Provider search path, used in conjunction with -provider <name>. This path is prepended to the name.
• -provider-attr: Specify the attribute query clause to be used when the Provider obtains algorithms. For more detailed description, please refer to Provider Development Guide.

3 Commands

3.1 Basic Commands

3.1.1 help

Function: Display help information for all supported commands or specific commands

Usage:

hitls help [command name]

Parameters:

• No parameters: Display list of all supported commands
• Command name: Display detailed help information for specific command

Examples:

hitls help                # Display all supported commands
hitls help rand           # Display help information for rand command

3.1.2 list

Function: List supported algorithms and functions, including digest, symmetric, asymmetric, MAC, random number, KDF algorithms, etc.

Usage:

hitls list [-help] [-all-algorithms] [-digest-algorithms] [-cipher-algorithms] [-asym-algorithms] [-mac-algorithms] [-rand-algorithms] [-kdf-algorithms] [-all-curves]

Supported Options:

• -help: Display help information
• -all-algorithms: List all supported algorithms
• -digest-algorithms: List all supported digest algorithms
• -cipher-algorithms: List all supported symmetric algorithms
• -asym-algorithms: List all supported asymmetric algorithms
• -mac-algorithms: List all supported MAC algorithms
• -rand-algorithms: List all supported random number algorithms
• -kdf-algorithms: List all supported KDF algorithms
• -all-curves: List all supported curves

Examples:

hitls list -all-algorithms
hitls list -cipher-algorithms
hitls list -all-curves

3.2 Encryption and Digest

3.2.1 enc

Symmetric encryption and decryption operations, supporting multiple symmetric algorithms

AES-WRAP algorithms are not supported by the enc command.

Function: Symmetric encryption/decryption

Usage:

hitls enc -cipher <alg> -enc|-dec -in <infile> -out <outfile> -pass <pass> [options]

Options:

• -help: Show help information
• -cipher <alg>: Specify the symmetric algorithm. Use hitls list -cipher-algorithms to view supported algorithms.
• -enc: Encryption
• -dec: Decryption
• -in <file>: Input file
• -out <file>: Output file
• -pass <pass:xxx|file:xxx>: Passphrase source
• -hex: Hex-encoded output/input
• -base64: Base64-encoded output/input
• -md <alg>: Digest algorithm used to derive the key (default: SHA256)
• -iter <count>: Number of PBKDF2 iterations used for key derivation. If not specified, the default value 10000 is used. The valid range for count is 1 to 4294967295.
• -provider, -provider-path, -provider-attr: See Provider options

Notes:

• If -hex/-base64 is not specified, the output is binary.
• The decryption format must match the encryption output format (for example, use -base64 for both).

Examples:

# Binary output by default
hitls enc -cipher aes128_ecb -enc -in in.txt -pass pass:12345678 -out out.bin

# Hex output
hitls enc -cipher aes128_ecb -enc -in in.txt -pass pass:12345678 -out out.txt -hex

# Base64 output
hitls enc -cipher aes128_ecb -enc -in in.txt -pass pass:12345678 -out out.txt -base64

3.2.2 mac

Message authentication code calculation and verification

GMAC algorithms are not supported by the mac command.

3.2.3 dgst

Message digest calculation and digital signature operations

3.2.4 kdf

Key derivation function, derive keys from input materials

3.3 Key and Parameter Management

3.3.1 rsa

RSA key processing, including format conversion and information display

3.3.2 genrsa

Generate RSA private keys

3.3.3 genpkey

Generate various types of public and private keys

3.3.4 pkey

Public and private key processing tool

3.3.5 pkeyutl

Use keys for encryption, decryption, signing, verification and other operations

3.3.6 keymgmt

Key management functions, including key creation, deletion, querying, etc. (SM mode)

3.4 PKI Certificate Management

3.4.1 pkcs12

Processing of PKCS#12 format certificates and key packages

3.4.2 x509

Generation, parsing, conversion and verification of X.509 certificates

3.4.3 crl

Generation and management of certificate revocation lists

Function: Parse, output, and verify CRLs, and print issuer/hash/text information
Usage:

hitls crl [-help] [-in file] [-inform PEM|DER] [-out file] [-outform PEM|DER] [-noout] [-nextupdate] [-CAfile file] [-issuer] [-hash] [-text]

Supported Options:

• -help: Display help information
• -in <file>: Input CRL file, default stdin
• -inform <PEM|DER>: Input format, PEM or DER
• -out <file>: Output file, default stdout
• -outform <PEM|DER>: Output format, PEM or DER
• -noout: Do not output CRL content (PEM/DER), but still print issuer/hash/text information
• -nextupdate: Print CRL next update time
• -CAfile <file>: Verify CRL using CA certificate
• -issuer: Print issuer DN
• -hash: Print issuer DN hash (prefix: "Issuer Hash=")
• -text: Print CRL in text

Examples:

# Print issuer/hash/text to a file
hitls crl -in crl.pem -noout -issuer -hash -text -out crl_info.txt

# Convert DER to PEM
hitls crl -in crl.der -inform DER -out crl.pem -outform PEM

# Verify CRL signature
hitls crl -in crl.pem -noout -CAfile ca.crt

3.4.4 verify

Certificate chain verification and trust relationship checking

3.4.5 req

Generation and processing of certificate signing requests

3.5 SSL/TLS Communication

3.5.1 s_client

SSL/TLS client tool

3.5.2 s_server

SSL/TLS server tool

3.6 Other Utility Tools

3.6.1 rand

Function: Generate random data Usage:

hitls rand [-help] [-out file] [-algorithm alg] [-hex] [-base64] [-provider name] [-provider-path path] [-provider-attr attr] numbytes

Supported Options:

• -help: Display help information
• -hex: Output in hexadecimal format, default format is binary
• -base64: Output in Base64 format, default format is binary
• -out <file>: Write output to specified file, if not specified, output to stdout
• -algorithm <algorithm>: Specify random number generation algorithm, supported random number algorithms can be viewed using list command
• -provider, -provider-path, -provider-attr: Please refer to Provider Options

Examples:

# Generate 16 bytes of random data, output in binary format
hitls rand 16

# Generate 32 bytes of random data, output in hexadecimal format
hitls rand -hex 32

# Generate 64 bytes of random data, save in Base64 format to rand.txt
hitls rand -base64 -out rand.txt 64

# Use hmac-sha256 random number algorithm to generate 10 bytes of random data, output in hexadecimal format
hitls rand -algorithm hmac-sha256 -hex 10

3.6.2 prime

Function: Generate and test primes

Usage:

hitls prime [-help] [-generate] [-bits num] [-hex] [-checks num] [number]

Supported Options:

• -help: Show help information
• -bits <n>: Specify the bit length of the prime to be generated
• -hex: Use hexadecimal format for input/output (decimal by default)
• -generate: Enable prime generation mode
• -check <n>: Number of iterations for primality testing (default: 64)

Examples:

# Check if a decimal number is prime
./hitls prime 17

# Check a hexadecimal number
./hitls prime -hex 1F

# Customize number of primality test rounds
./hitls prime -checks 128 97

# Generate a 256-bit prime
./hitls prime -generate -bits 256

# Output in hexadecimal format
./hitls prime -generate -bits 128 -hex

3.6.3 errdecode

Function: Convert error codes to human-readable strings

Usage:

hitls errdecode [-help] [-v | --verbose] [--stack] [-hex] [error_code ...]

Supported Options:

• -help: Display help information
• -v, --verbose: Show detailed error code field breakdown
• --stack: Display error stack (if supported)
• -hex: Force hexadecimal parsing

Arguments:

• error_code: Error code in decimal or hexadecimal format
  • Hexadecimal can be with (0x) or without prefix
  • Multiple error codes can be specified

Examples:

# Decode a decimal error code
hitls errdecode 101

# Decode a hexadecimal error code (with 0x prefix)
hitls errdecode 0x0E000065

# Decode a hexadecimal error code (without 0x prefix)
hitls errdecode 0E000065

# Show detailed error code field breakdown
hitls errdecode -v 0x1408F10B

# Batch process multiple error codes
hitls errdecode 101 0x0E000065 234567890

# Read error codes from pipeline
echo "0x1408F10B" | hitls errdecode

# Display error stack
hitls errdecode --stack