Submitted by: "Victor B. Wagner" <vitus@cryptocom.ru>
Approved by: steve@openssl.org

Document/clarify use of some options and include details of GOST algorihthm
usage.
This commit is contained in:
Dr. Stephen Henson 2009-04-10 16:42:28 +00:00
parent 36a252ea46
commit 6fda4d7e5d
11 changed files with 384 additions and 59 deletions

View File

@ -251,6 +251,33 @@ cipher suites using MD5.
cipher suites using SHA1.
=item B<aGOST>
cipher suites using GOST R 34.10 (either 2001 or 94) for authenticaction
(needs an engine supporting GOST algorithms).
=item B<aGOST01>
cipher suites using GOST R 34.10-2001 authentication.
=item B<aGOST94>
cipher suites using GOST R 34.10-94 authentication (note that R 34.10-94
standard has been expired so use GOST R 34.10-2001)
=item B<kGOST>
cipher suites, using VKO 34.10 key exchange, specified in the RFC 4357.
=item B<GOST94>
cipher suites, using HMAC based on GOST R 34.11-94.
=item B<GOST89MAC>
cipher suites using GOST 28147-89 MAC B<instead of> HMAC.
=back
=head1 CIPHER SUITE NAMES
@ -376,6 +403,16 @@ e.g. DES-CBC3-SHA. In these cases, RSA authentication is used.
TLS_DH_anon_WITH_SEED_CBC_SHA ADH-SEED-SHA
=head2 GOST ciphersuites from draft-chudov-cryptopro-cptls, extending TLS v1.0
Note: these ciphers require an engine which including GOST cryptographic
algorithms, such as the B<ccgost> engine, included in the OpenSSL distribution.
TLS_GOSTR341094_WITH_28147_CNT_IMIT GOST94-GOST89-GOST89
TLS_GOSTR341001_WITH_28147_CNT_IMIT GOST2001-GOST89-GOST89
TLS_GOSTR341094_WITH_NULL_GOSTR3411 GOST94-NULL-GOST94
TLS_GOSTR341001_WITH_NULL_GOSTR3411 GOST2001-NULL-GOST94
=head2 Additional Export 1024 and other cipher suites
Note: these ciphers can also be used in SSL v3.

View File

@ -36,17 +36,7 @@ B<openssl> B<cms>
[B<-CAfile file>]
[B<-CApath dir>]
[B<-md digest>]
[B<-des>]
[B<-des3>]
[B<-rc2-40>]
[B<-rc2-64>]
[B<-rc2-128>]
[B<-aes128>]
[B<-aes192>]
[B<-aes256>]
[B<-camellia128>]
[B<-camellia192>]
[B<-camellia256>]
[B<-[cipher]>]
[B<-nointern>]
[B<-no_signer_cert_verify>]
[B<-nocerts>]
@ -253,13 +243,13 @@ to each certificate.
digest algorithm to use when signing or resigning. If not present then the
default digest algorithm for the signing key will be used (usually SHA1).
=item B<-des -des3 -rc2-40 -rc2-64 -rc2-128 -aes128 -aes192 -aes256 -camellia128 -camellia192 -camellia256>
=item B<-[cipher]>
the encryption algorithm to use. DES (56 bits), triple DES (168 bits), 40, 64
or 128 bit RC2, 128, 192 or 256 bit AES, or 128, 192 or 256 bit Camellia
respectively. Any other cipher name (as recognized by the
the encryption algorithm to use. For example triple DES (168 bits) - B<-des3>
or 256 bit AES - B<-aes256>. Any standard algorithm name (as used by the
EVP_get_cipherbyname() function) can also be used preceded by a dash, for
example B<-aes_128_cbc>.
example B<-aes_128_cbc>. See L<B<enc>|enc(1)> for a list of ciphers
supported by your version of OpenSSL.
If not specified triple DES is used. Only used with B<-encrypt> and
B<-EncryptedData_create> commands.
@ -411,6 +401,11 @@ portion of a message so they may be included manually. If signing
then many S/MIME mail clients check the signers certificate's email
address matches that specified in the From: address.
=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy>
Set various certificate chain valiadition option. See the
L<B<verify>|verify(1)> manual page for details.
=back
=head1 NOTES

View File

@ -14,6 +14,7 @@ B<openssl> B<dgst>
[B<-binary>]
[B<-out filename>]
[B<-sign filename>]
[B<-keyform arg>]
[B<-passin arg>]
[B<-verify filename>]
[B<-prverify filename>]
@ -61,6 +62,23 @@ filename to output to, or standard output by default.
digitally sign the digest using the private key in "filename".
=item B<-keyform arg>
Specifies the key format to sign digest with. Only PEM and ENGINE
formats are supported by the B<dgst> command.
=item B<-engine id>
Use engine B<id> for operations (including private key storage).
This engine is not used as source for digest algorithms, unless it is
also specified in the configuration file.
=item B<-sigopt nm:v>
Pass options to the signature algorithm during sign or verify operations.
Names and values of these options are algorithm-specific.
=item B<-passin arg>
the private key password source. For more information about the format of B<arg>
@ -83,6 +101,35 @@ the actual signature to verify.
create a hashed MAC using "key".
=item B<-mac alg>
create MAC (keyed Message Authentication Code). The most popular MAC
algorithm is HMAC (hash-based MAC), but there are other MAC algorithms
which are not based on hash, for instance B<gost-mac> algorithm,
supported by B<ccgost> engine. MAC keys and other options should be set
via B<-macopt> parameter.
=item B<-macopt nm:v>
Passes options to MAC algorithm, specified by B<-mac> key.
Following options are supported by both by B<HMAC> and B<gost-mac>:
=over 8
=item B<key:string>
Specifies MAC key as alphnumeric string (use if key contain printable
characters only). String length must conform to any restrictions of
the MAC algorithm for example exactly 32 chars for gost-mac.
=item B<hexkey:string>
Specifies MAC key in hexadecimal form (two hex digits per byte).
Key length must conform to any restrictions of the MAC algorithm
for example exactly 32 chars for gost-mac.
=back
=item B<-rand file(s)>
a file or files containing random data used to seed the random number

View File

@ -12,17 +12,24 @@ B<openssl enc -ciphername>
[B<-pass arg>]
[B<-e>]
[B<-d>]
[B<-a>]
[B<-a/-base64>]
[B<-A>]
[B<-k password>]
[B<-kfile filename>]
[B<-K key>]
[B<-iv IV>]
[B<-S salt>]
[B<-salt>]
[B<-nosalt>]
[B<-z>]
[B<-md>]
[B<-p>]
[B<-P>]
[B<-bufsize number>]
[B<-nopad>]
[B<-debug>]
[B<-none>]
[B<-engine id>]
=head1 DESCRIPTION
@ -74,6 +81,10 @@ base64 process the data. This means that if encryption is taking place
the data is base64 encoded after encryption. If decryption is set then
the input data is base64 decoded before being decrypted.
=item B<-base64>
same as B<-a>
=item B<-A>
if the B<-a> option is set then base64 process the data on one line.
@ -89,10 +100,18 @@ read the password to derive the key from the first line of B<filename>.
This is for compatibility with previous versions of OpenSSL. Superseded by
the B<-pass> argument.
=item B<-nosalt>
do not use a salt
=item B<-salt>
use salt (randomly generated or provide with B<-S> option) when
encrypting (this is the default).
=item B<-S salt>
the actual salt to use: this must be represented as a string comprised only
of hex digits.
the actual salt to use: this must be represented as a string of hex digits.
=item B<-K key>
@ -131,12 +150,34 @@ disable standard block padding
debug the BIOs used for I/O.
=item B<-z>
Compress or decompress clear text using zlib before encryption or after
decryption. This option exists only if OpenSSL with compiled with zlib
or zlib-dynamic option.
=item B<-none>
Use NULL cipher (no encryption or decryption of input).
=back
=head1 NOTES
The program can be called either as B<openssl ciphername> or
B<openssl enc -ciphername>.
B<openssl enc -ciphername>. But the first form doesn't work with
engine-provided ciphers, because this form is processed before the
configuration file is read and any ENGINEs loaded.
Engines which provide entirely new encryption algorithms (such as ccgost
engine which provides gost89 algorithm) should be configured in the
configuration file. Engines, specified in the command line using -engine
options can only be used for hadrware-assisted implementations of
ciphers, which are supported by OpenSSL core or other engine, specified
in the configuration file.
When enc command lists supported ciphers, ciphers provided by engines,
specified in the configuration files are listed too.
A password will be prompted for to derive the key and IV if necessary.
@ -169,6 +210,14 @@ Blowfish and RC5 algorithms use a 128 bit key.
=head1 SUPPORTED CIPHERS
Note that some of these ciphers can be disabled at compile time
and some are available only if an appropriate engine is configured
in the configuration file. The output of the B<enc> command run with
unsupported options (for example B<openssl enc -help>) includes a
list of ciphers, supported by your versesion of OpenSSL, including
ones provided by configured engines.
base64 Base 64
bf-cbc Blowfish in CBC mode
@ -203,6 +252,9 @@ Blowfish and RC5 algorithms use a 128 bit key.
desx DESX algorithm.
gost89 GOST 28147-89 in CFB mode (provided by ccgost engine)
gost89-cnt `GOST 28147-89 in CNT mode (provided by ccgost engine)
idea-cbc IDEA algorithm in CBC mode
idea same as idea-cbc
idea-cfb IDEA in CFB mode

View File

@ -138,6 +138,37 @@ the EC curve to use.
=back
=head1 GOST2001 KEY GENERATION AND PARAMETER OPTIONS
Gost 2001 support is not enabled by default. To enable this algorithm,
one should load the ccgost engine in the OpenSSL configuration file.
See README.gost file in the engines/ccgost directiry of the source
distribution for more details.
Use of a parameter file for the GOST R 34.10 algorithm is optional.
Parameters can be specified during key generation directly as well as
during generation of parameter file.
=over 4
=item B<paramset:name>
Specifies GOST R 34.10-2001 parameter set according to RFC 4357.
Parameter set can be specified using abbreviated name, object short name or
numeric OID. Following parameter sets are supported:
paramset OID Usage
A 1.2.643.2.2.35.1 Signature
B 1.2.643.2.2.35.2 Signature
C 1.2.643.2.2.35.3 Signature
XA 1.2.643.2.2.36.0 Key exchange
XB 1.2.643.2.2.36.1 Key exchange
test 1.2.643.2.2.35.0 Test purposes
=back
=head1 NOTES
The use of the genpkey program is encouraged over the algorithm specific

View File

@ -81,6 +81,10 @@ Certificate Authority (CA) Management.
Cipher Suite Description Determination.
=item L<B<cms>|cms(1)>
CMS (Cryptographic Message Syntax) utility
=item L<B<crl>|crl(1)>
Certificate Revocation List (CRL) Management.
@ -98,6 +102,12 @@ Message Digest Calculation.
Diffie-Hellman Parameter Management.
Obsoleted by L<B<dhparam>|dhparam(1)>.
=item L<B<dhparam>|dhparam(1)>
Generation and Management of Diffie-Hellman Parameters. Superseded by
L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>
=item L<B<dsa>|dsa(1)>
DSA Data Management.
@ -107,19 +117,26 @@ DSA Data Management.
DSA Parameter Generation and Management. Superseded by
L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>
=item L<B<ec>|ec(1)>
EC (Elliptic curve) key processing
=item L<B<ecparam>|ecparam(1)>
EC parameter manipulation and generation
=item L<B<enc>|enc(1)>
Encoding with Ciphers.
=item L<B<engine>|engine(1)>
Engine (loadble module) information and manipulation.
=item L<B<errstr>|errstr(1)>
Error Number to Error String Conversion.
=item L<B<dhparam>|dhparam(1)>
Generation and Management of Diffie-Hellman Parameters. Superseded by
L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>
=item B<gendh>
Generation of Diffie-Hellman Parameters.
@ -138,6 +155,10 @@ Generation of Private Key or Parameters.
Generation of RSA Private Key. Superceded by L<B<genpkey>|genpkey(1)>.
=item L<B<nseq>|nseq(1)
Create or examine a netscape certificate sequence
=item L<B<ocsp>|ocsp(1)>
Online Certificate Status Protocol utility.
@ -158,14 +179,14 @@ PKCS#7 Data Management.
Public and private key management.
=item L<B<pkeyutl>|pkeyutl(1)>
Public key algorithm cryptographic operation utility.
=item L<B<pkeyparam>|pkeyparam(1)>
Public key algorithm parameter management.
=item L<B<pkeyutl>|pkeyutl(1)>
Public key algorithm cryptographic operation utility.
=item L<B<rand>|rand(1)>
Generate pseudo-random bytes.
@ -178,6 +199,7 @@ PKCS#10 X.509 Certificate Signing Request (CSR) Management.
RSA key management.
=item L<B<rsautl>|rsautl(1)>
RSA utility for signing, verification, encryption, and decryption. Superseded
@ -215,6 +237,10 @@ S/MIME mail processing.
Algorithm Speed Measurement.
=item L<B<spkac>|spkac(1)>
SPKAC printing and generating utility
=item L<B<ts>|ts(1)>
Time Stamping Authority tool (client/server)

View File

@ -12,6 +12,7 @@ B<openssl> B<pkeyutl>
[B<-sigfile file>]
[B<-inkey file>]
[B<-keyform PEM|DER>]
[B<-passin arg>]
[B<-peerkey file>]
[B<-peerform PEM|DER>]
[B<-pubin>]
@ -26,6 +27,7 @@ B<openssl> B<pkeyutl>
[B<-pkeyopt opt:value>]
[B<-hexdump>]
[B<-asn1parse>]
[B<-engine id>]
=head1 DESCRIPTION
@ -52,7 +54,13 @@ the input key file, by default it should be a private key.
=item B<-keyform PEM|DER>
the key format PEM or DER.
the key format PEM, DER or ENGINE.
=item B<-passin arg>
the input key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-peerkey file>
@ -60,7 +68,15 @@ the peer key file, used by key derivation (agreement) operations.
=item B<-peerform PEM|DER>
the peer key format PEM or DER.
the peer key format PEM, DER or ENGINE.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<pkeyutl>
to attempt to obtain a functional reference to the specified engine,
thus initialising it if needed. The engine will then be set as the default
for all available algorithms.
=item B<-pubin>

View File

@ -22,13 +22,13 @@ B<openssl> B<req>
[B<-new>]
[B<-rand file(s)>]
[B<-newkey rsa:bits>]
[B<-newkey dsa:file>]
[B<-newkey alg:file>]
[B<-nodes>]
[B<-key filename>]
[B<-keyform PEM|DER>]
[B<-keyout filename>]
[B<-[md5|sha1|md2|mdc2]>]
[B<-keygen_engine id>]
[B<-[digest]>]
[B<-config filename>]
[B<-subj arg>]
[B<-multivalue-rdn>]
@ -36,11 +36,15 @@ B<openssl> B<req>
[B<-days n>]
[B<-set_serial n>]
[B<-asn1-kludge>]
[B<-no-asn1-kludge>]
[B<-newhdr>]
[B<-extensions section>]
[B<-reqexts section>]
[B<-utf8>]
[B<-nameopt>]
[B<-reqopt>]
[B<-subject>]
[B<-subj arg>]
[B<-batch>]
[B<-verbose>]
[B<-engine id>]
@ -92,6 +96,11 @@ see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
prints out the certificate request in text form.
=item B<-subject>
prints out the request subject (or certificate subject if B<-x509> is
specified)
=item B<-pubkey>
outputs the public key.
@ -119,6 +128,13 @@ in the configuration file and any requested extensions.
If the B<-key> option is not used it will generate a new RSA private
key using information specified in the configuration file.
=item B<-subj arg>
Replaces subject field of input request with specified data and outputs
modified request. The arg must be formatted as
I</type0=value0/type1=value1/type2=...>,
characters may be escaped by \ (backslash), no spaces are skipped.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
@ -132,12 +148,26 @@ all others.
this option creates a new certificate request and a new private
key. The argument takes one of several forms. B<rsa:nbits>, where
B<nbits> is the number of bits, generates an RSA key B<nbits>
in size. B<dsa:filename> generates a DSA key using the parameters
in the file B<filename>. B<param:file> generates a key using the
parameter file B<file>, the algorithm is determined by the
parameters. B<algname:file> use algorithm B<algname> and parameter file
B<file> the two algorithms must match or an error occurs. B<algname> just
uses algorithm B<algname>.
in size. If B<nbits> is omitted, i.e. B<-newkey rsa> specified,
the default key size, specified in the configuration file is used.
All other algorithms support the B<-newkey alg:file> form, where file may be
an algorithm parameter file, created by the B<genpkey -genparam> command
or and X.509 certificate for a key with approriate algorithm.
B<param:file> generates a key using the parameter file or certificate B<file>,
the algorithm is determined by the parameters. B<algname:file> use algorithm
B<algname> and parameter file B<file>: the two algorithms must match or an
error occurs. B<algname> just uses algorithm B<algname>, and parameters,
if neccessary should be specified via B<-pkeyopt> parameter.
B<dsa:filename> generates a DSA key using the parameters
in the file B<filename>. B<ec:filename> generates EC key (usable both with
ECDSA or ECDH algorithms), B<gost2001:filename> generates GOST R
34.10-2001 key (requires B<ccgost> engine configured in the configuration
file). If just B<gost2001> is specified a parameter set should be
specified by B<-pkeyopt paramset:X>
=item B<-pkeyopt opt:value>
@ -167,11 +197,15 @@ configuration file is used.
if this option is specified then if a private key is created it
will not be encrypted.
=item B<-[md5|sha1|md2|mdc2]>
=item B<-[digest]>
this specifies the message digest to sign the request with. This
overrides the digest algorithm specified in the configuration file.
This option is ignored for DSA requests: they always use SHA1.
this specifies the message digest to sign the request with (such as
B<-md5>, B<-sha1>). This overrides the digest algorithm specified in
the configuration file.
Some public key algorithms may override this choice. For instance, DSA
signatures always use SHA1, GOST R 34.10 signatures always use
GOST R 34.11-94 (B<-md_gost94>).
=item B<-config filename>
@ -239,6 +273,15 @@ B<option> argument can be a single option or multiple options separated by
commas. Alternatively the B<-nameopt> switch may be used more than once to
set multiple options. See the L<x509(1)|x509(1)> manual page for details.
=item B<-reqopt>
customise the output format used with B<-text>. The B<option> argument can be
a single option or multiple options separated by commas.
See discission of the B<-certopt> parameter in the L<B<x509>|x509(1)>
command.
=item B<-asn1-kludge>
by default the B<req> command outputs certificate requests containing
@ -254,6 +297,10 @@ B<SET OF> whereas the correct form does.
It should be noted that very few CAs still require the use of this option.
=item B<-no-asn1-kludge>
Reverses effect of B<-asn1-kludge>
=item B<-newhdr>
Adds the word B<NEW> to the PEM file header and footer lines on the outputed
@ -274,6 +321,11 @@ to attempt to obtain a functional reference to the specified engine,
thus initialising it if needed. The engine will then be set as the default
for all available algorithms.
=item B<-keygen_engine id>
specifies an engine (by its unique B<id> string) which would be used
for key generation operations.
=back
=head1 CONFIGURATION FILE FORMAT

View File

@ -101,6 +101,11 @@ also used when building the client certificate chain.
A file containing trusted certificates to use during server authentication
and to use when attempting to build the client certificate chain.
=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy>
Set various certificate chain valiadition option. See the
L<B<verify>|verify(1)> manual page for details.
=item B<-reconnect>
reconnects to the same server 5 times using the same session ID, this can

View File

@ -13,17 +13,7 @@ B<openssl> B<smime>
[B<-resign>]
[B<-verify>]
[B<-pk7out>]
[B<-des>]
[B<-des3>]
[B<-rc2-40>]
[B<-rc2-64>]
[B<-rc2-128>]
[B<-aes128>]
[B<-aes192>]
[B<-aes256>]
[B<-camellia128>]
[B<-camellia192>]
[B<-camellia256>]
[B<-[cipher]>]
[B<-in file>]
[B<-certfile file>]
[B<-signer file>]
@ -161,13 +151,13 @@ to each certificate.
digest algorithm to use when signing or resigning. If not present then the
default digest algorithm for the signing key will be used (usually SHA1).
=item B<-des -des3 -rc2-40 -rc2-64 -rc2-128 -aes128 -aes192 -aes256 -camellia128 -camellia192 -camellia256>
=item B<-[cipher]>
the encryption algorithm to use. DES (56 bits), triple DES (168 bits), 40, 64
or 128 bit RC2, 128, 192 or 256 bit AES, or 128, 192 or 256 bit Camellia
respectively. Any other cipher name (as recognized by the
the encryption algorithm to use. For example DES (56 bits) - B<-des>,
triple DES (168 bits) - B<-des3>,
EVP_get_cipherbyname() function) can also be used preceded by a dash, for
example B<-aes_128_cbc>.
example B<-aes_128_cbc>. See L<B<enc>|enc(1)> for list of ciphers
supported by your version of OpenSSL.
If not specified 40 bit RC2 is used. Only used with B<-encrypt>.
@ -269,6 +259,11 @@ portion of a message so they may be included manually. If signing
then many S/MIME mail clients check the signers certificate's email
address matches that specified in the From: address.
=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy>
Set various options of certificate chain verification. See
L<B<verify>|verify(1)> manual page for details.
=back
=head1 NOTES

View File

@ -10,6 +10,18 @@ B<openssl> B<verify>
[B<-CApath directory>]
[B<-CAfile file>]
[B<-purpose purpose>]
[B<-policy arg>]
[B<-ignore_critical>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-policy_check>]
[B<-explicit_policy>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-x509_strict>]
[B<-extended_crl>]
[B<-use_deltas>]
[B<-policy_print>]
[B<-untrusted file>]
[B<-help>]
[B<-issuer_checks>]
@ -66,6 +78,63 @@ certificate was rejected. However the presence of rejection messages
does not itself imply that anything is wrong: during the normal
verify process several rejections may take place.
=item B<-policy arg>
Enable policy processing and add B<arg> to the user-initial-policy-set
(see RFC3280 et al). The policy B<arg> can be an object name an OID in numeric
form. This argument can appear more than once.
=item B<-policy_check>
Enables certificate policy processing.
=item B<-explicit_policy>
Set policy variable require-explicit-policy (see RFC3280 et al).
=item B<-inhibit_any>
Set policy variable inhibit-any-policy (see RFC3280 et al).
=item B<-inhibit_map>
Set policy variable inhibit-policy-mapping (see RFC3280 et al).
=item B<-policy_print>
Print out diagnostics, related to policy checking
=item B<-crl_check>
Checks end entity certificate validity by attempting to lookup a valid CRL.
If a valid CRL cannot be found an error occurs.
=item B<-crl_check_all>
Checks the validity of B<all> certificates in the chain by attempting
to lookup valid CRLs.
=item B<-ignore_critical>
Normally if an unhandled critical extension is present which is not
supported by OpenSSL the certificate is rejected (as required by
RFC3280 et al). If this option is set critical extensions are
ignored.
=item B<-x509_strict>
Disable workarounds for broken certificates which have to be disabled
for strict X.509 compliance.
=item B<-extended_crl>
Enable extended CRL features such as indirect CRLs and alternate CRL
signing keys.
=item B<-use_deltas>
Enable support for delta CRLs.
=item B<->
marks the last option. All arguments following this are assumed to be